# WeKnora 开发环境快速入门 > 无需重新构建 Docker 镜像,实现秒级代码热更新! ## 🚀 快速开始(3 种方式) ### 方式 1:推荐 - 使用 Make 命令 **终端 1** - 启动基础设施: ```bash make dev-start ``` **终端 2** - 启动后端: ```bash make dev-app ``` **终端 3** - 启动前端: ```bash make dev-frontend ``` 访问 http://localhost:5173 开始开发! ### 方式 2:使用脚本命令 ```bash # 终端 1 ./scripts/dev.sh start # 终端 2 ./scripts/dev.sh app # 终端 3 ./scripts/dev.sh frontend ``` ### 方式 3:一键启动(交互式) ```bash ./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 | ## 💡 开发工作流对比 ### ❌ 旧方式(慢) ```bash # 每次修改代码后 sh scripts/build_images.sh -p # 重新构建镜像(2-5分钟) sh scripts/start_all.sh --no-pull # 重启容器 ``` ### ✅ 新方式(快) ```bash # 首次启动(只需一次) make dev-start # 修改后端代码 # → Ctrl+C 停止 → make dev-app 重启(5-10秒) # 修改前端代码 # → 自动热重载(无需任何操作) ``` **时间对比**: - 旧方式:每次修改 2-5 分钟 - 新方式首次:1-2 分钟 - 新方式后续: - 后端修改:5-10 秒 - 前端修改:实时热重载 ## 🔥 进阶:后端热重载 安装 Air 实现后端代码修改后自动重启: ```bash # 安装 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:只修改前端 ```bash # 一次性启动基础设施 make dev-start # 启动前端,修改代码自动热重载 make dev-frontend ``` ### 场景 2:只修改后端 ```bash # 启动基础设施 make dev-start # 启动后端(如果安装了 Air,支持热重载) make dev-app ``` ### 场景 3:同时开发前后端 ```bash # 终端 1:启动基础设施 make dev-start # 终端 2:启动后端 make dev-app # 终端 3:启动前端 make dev-frontend ``` ## 🛠 VS Code 调试配置 创建 `.vscode/launch.json`: ```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 秒让服务完全启动。 查看服务状态: ```bash make dev-status ``` ### 问题:前端访问 API 时报 CORS 错误 **解决**:前端已配置代理,确保: 1. 后端运行在 `localhost:8080` 2. 前端运行在 `localhost:5173` 3. 查看 `frontend/vite.config.ts` 的代理配置 ### 问题:端口被占用 **解决**:修改 `.env` 文件中的端口配置: ```bash # .env DB_PORT=5433 # 默认 5432 REDIS_PORT=6380 # 默认 6379 MINIO_PORT=9001 # 默认 9000 ``` 然后重启服务: ```bash make dev-restart ``` ### 问题:DocReader 需要重新构建 **解决**:DocReader 仍使用 Docker 镜像,需要重新构建: ```bash sh scripts/build_images.sh -d make dev-restart ``` ## 🎯 生产环境部署 开发完成后需要部署时: ```bash # 构建所有镜像 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 ``` ## 📚 更多文档 - [完整开发指南](docs/开发指南.md) - [API 文档](docs/API.md) - [Agent 开发](docs/AGENT.md) ## 💪 最佳实践 1. **日常开发**:使用 `make dev-*` 命令,享受快速迭代 2. **提交前测试**:使用完整 Docker 环境测试集成功能 3. **生产部署**:使用构建镜像的方式部署 ## 🎉 总结 使用开发模式,你可以: ✅ **不重新构建镜像** - 直接在本地运行代码 ✅ **秒级热更新** - 前端自动热重载,后端快速重启 ✅ **完整调试支持** - IDE 断点调试,实时查看变量 ✅ **节省时间** - 每次修改从 2-5 分钟降至 5-10 秒 祝你开发愉快!🚀