Enterprise-Knowledge-Base/DEVELOPMENT.md

WeKnora 开发环境快速入门

无需重新构建 Docker 镜像，实现秒级代码热更新！

🚀 快速开始（3 种方式）

方式 1：推荐 - 使用 Make 命令

终端 1 - 启动基础设施：

make dev-start

终端 2 - 启动后端：

make dev-app

终端 3 - 启动前端：

make dev-frontend

访问 http://localhost:5173 开始开发！

方式 2：使用脚本命令

# 终端 1
./scripts/dev.sh start

# 终端 2
./scripts/dev.sh app

# 终端 3
./scripts/dev.sh frontend

方式 3：一键启动（交互式）

./scripts/quick-dev.sh

按照提示选择是否启动后端和前端。

📋 常用命令

命令	说明
make dev-start	启动基础设施（postgres, redis, minio 等）
make dev-stop	停止所有服务
make dev-restart	重启所有服务
make dev-status	查看服务状态
make dev-logs	查看服务日志
make dev-app	启动后端（需先启动基础设施）
make dev-frontend	启动前端（需先启动基础设施）

🎯 访问地址

服务	地址
前端开发服务器	http://localhost:5173
后端 API	http://localhost:8080
PostgreSQL	localhost:5432
Redis	localhost:6379
MinIO Console	http://localhost:9001
Neo4j Browser	http://localhost:7474
Jaeger UI	http://localhost:16686

💡 开发工作流对比

❌ 旧方式（慢）

# 每次修改代码后
sh scripts/build_images.sh -p      # 重新构建镜像（2-5分钟）
sh scripts/start_all.sh --no-pull  # 重启容器

✅ 新方式（快）

# 首次启动（只需一次）
make dev-start

# 修改后端代码
# → Ctrl+C 停止 → make dev-app 重启（5-10秒）

# 修改前端代码
# → 自动热重载（无需任何操作）

时间对比：

• 旧方式：每次修改 2-5 分钟
• 新方式首次：1-2 分钟
• 新方式后续：
  • 后端修改：5-10 秒
  • 前端修改：实时热重载

🔥 进阶：后端热重载

安装 Air 实现后端代码修改后自动重启：

# 安装 Air
go install github.com/cosmtrek/air@latest

# 确保 $GOPATH/bin 在 PATH 中
export PATH=$PATH:$(go env GOPATH)/bin

# 使用 Air 启动（自动检测）
make dev-app
# 或直接运行
air

修改 Go 代码后，Air 会自动重新编译和重启，无需手动操作！

📝 开发场景示例

场景 1：只修改前端

# 一次性启动基础设施
make dev-start

# 启动前端，修改代码自动热重载
make dev-frontend

场景 2：只修改后端

# 启动基础设施
make dev-start

# 启动后端（如果安装了 Air，支持热重载）
make dev-app

场景 3：同时开发前后端

# 终端 1：启动基础设施
make dev-start

# 终端 2：启动后端
make dev-app

# 终端 3：启动前端
make dev-frontend

🛠 VS Code 调试配置

创建 .vscode/launch.json：

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

然后按 F5 开始调试！

🐛 故障排除

问题：启动后端时报错连接不到数据库

解决：确保先运行了 make dev-start 并等待 30 秒让服务完全启动。

查看服务状态：

make dev-status

问题：前端访问 API 时报 CORS 错误

解决：前端已配置代理，确保：

1. 后端运行在 localhost:8080
2. 前端运行在 localhost:5173
3. 查看 frontend/vite.config.ts 的代理配置

问题：端口被占用

解决：修改 .env 文件中的端口配置：

# .env
DB_PORT=5433        # 默认 5432
REDIS_PORT=6380     # 默认 6379
MINIO_PORT=9001     # 默认 9000

然后重启服务：

make dev-restart

问题：DocReader 需要重新构建

解决：DocReader 仍使用 Docker 镜像，需要重新构建：

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

🎯 生产环境部署

开发完成后需要部署时：

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

# 或只构建特定镜像
sh scripts/build_images.sh -p  # 后端
sh scripts/build_images.sh -f  # 前端
sh scripts/build_images.sh -d  # DocReader

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

📚 更多文档

• 完整开发指南
• API 文档
• Agent 开发

💪 最佳实践

1. 日常开发：使用 make dev-* 命令，享受快速迭代
2. 提交前测试：使用完整 Docker 环境测试集成功能
3. 生产部署：使用构建镜像的方式部署

🎉 总结

使用开发模式，你可以：

✅ 不重新构建镜像 - 直接在本地运行代码
✅ 秒级热更新 - 前端自动热重载，后端快速重启
✅ 完整调试支持 - IDE 断点调试，实时查看变量
✅ 节省时间 - 每次修改从 2-5 分钟降至 5-10 秒

祝你开发愉快！🚀