xinmi/docs/开发指南.md

# WeKnora 开发指南

## 快速开发模式（推荐）

如果你需要频繁修改 `app` 或 `frontend` 代码，**不需要每次都重新构建 Docker 镜像**，可以使用本地开发模式。

### 方式一：使用 Make 命令（推荐）

#### 1. 启动基础设施服务

```bash
make dev-start
```

这将启动以下服务的 Docker 容器：
- PostgreSQL（数据库）
- Redis（缓存）
- MinIO（对象存储）
- Neo4j（图数据库）
- DocReader（文档读取服务）

#### 2. 启动后端应用（新终端）

```bash
make dev-app
```

这将在本地直接运行 Go 应用，修改代码后 Ctrl+C 停止，重新运行即可。

#### 3. 启动前端（新终端）

```bash
make dev-frontend
```

这将启动 Vite 开发服务器，支持热重载，修改代码后自动刷新。

#### 4. 查看服务状态

```bash
make dev-status
```

#### 5. 停止所有服务

```bash
make dev-stop
```

### 方式二：使用脚本命令

如果你更喜欢直接使用脚本：

```bash
# 启动基础设施
./scripts/dev.sh start

# 启动后端（新终端）
./scripts/dev.sh app

# 启动前端（新终端）
./scripts/dev.sh frontend

# 查看日志
./scripts/dev.sh logs

# 停止所有服务
./scripts/dev.sh stop
```

## 访问地址

### 开发环境

- **前端开发服务器**: http://localhost:5173
- **后端 API**: http://localhost:8080
- **PostgreSQL**: localhost:5432
- **Redis**: localhost:6379
- **MinIO Console**: http://localhost:9001
- **Neo4j Browser**: http://localhost:7474

## 开发工作流对比

### ❌ 旧方式（慢）

```bash
# 每次修改代码后都需要：
sh scripts/build_images.sh -p      # 重新构建镜像（很慢）
sh scripts/start_all.sh --no-pull  # 重启容器
```

**耗时**：每次修改需要 2-5 分钟

### ✅ 新方式（快）

```bash
# 首次启动（只需要一次）：
make dev-start

# 在另外两个终端分别运行：
make dev-app       # 修改 Go 代码后 Ctrl+C 重启即可（秒级）
make dev-frontend  # 修改前端代码自动热重载（无需重启）
```

**耗时**：
- 首次启动：1-2 分钟
- 后续修改后端：5-10 秒（重启 Go 应用）
- 后续修改前端：实时热重载

## 使用 Air 实现后端热重载（可选）

如果你希望后端代码修改后也能自动重启，可以安装 `air`：

```bash
go install github.com/air-verse/air@latest
```

项目根目录已内置 `.air.toml`，不需要手动创建配置文件。`make dev-app` 会检测本机是否安装了 Air：检测到 Air 时使用热重载模式，未检测到时使用普通 `go run` 模式。

## 其他开发技巧

### 只修改前端

如果只修改前端，只需要：

```bash
cd frontend
npm run dev
```

前端会连接到 http://localhost:8080 的后端 API。

### 只修改后端

如果只修改后端，只需要：

```bash
# 启动基础设施
make dev-start

# 运行后端
make dev-app
```

### 调试模式

#### 后端调试

使用 VS Code 或 GoLand 的调试功能，配置连接到本地运行的 Go 应用。

VS Code 配置示例（`.vscode/launch.json`）：

```json
{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Launch Server",
            "type": "go",
            "request": "launch",
            "mode": "auto",
            "program": "${workspaceFolder}/cmd/server",
            "env": {
                "DB_HOST": "localhost",
                "DOCREADER_ADDR": "localhost:50051",
                "MINIO_ENDPOINT": "localhost:9000",
                "REDIS_ADDR": "localhost:6379",
                "NEO4J_URI": "bolt://localhost:7687"
            },
            "args": []
        }
    ]
}
```

#### 前端调试

使用浏览器开发者工具即可，Vite 提供了 source map。

## 生产环境部署

当你完成开发需要部署时，才需要构建镜像：

```bash
# 构建所有镜像
sh scripts/build_images.sh

# 或只构建特定镜像
sh scripts/build_images.sh -p  # 只构建后端
sh scripts/build_images.sh -f  # 只构建前端
sh scripts/build_images.sh -d  # 只构建文档读取器
sh scripts/build_images.sh -s  # 只构建沙箱镜像（Agent Skills 执行环境）

# 启动生产环境
sh scripts/start_all.sh
```

## 常见问题

### Q: 启动 dev-app 时报错连接不到数据库

A: 确保先运行了 `make dev-start`，并等待所有服务启动完成（大约 30 秒）。

### Q: 前端访问 API 时报 CORS 错误

A: 检查前端的代理配置，确保 `vite.config.ts` 中配置了正确的代理。

### Q: DocReader 服务需要重新构建怎么办？

A: DocReader 仍然使用 Docker 镜像，如果需要修改，需要重新构建：

```bash
sh scripts/build_images.sh -d
make dev-restart
```

## 总结

- **日常开发**：使用 `make dev-*` 命令，快速迭代
- **测试集成**：使用 `sh scripts/start_all.sh --no-pull` 测试完整环境
- **生产部署**：使用 `sh scripts/build_images.sh` + `sh scripts/start_all.sh`