d387fd672f
- Added 'logs/' and '*.pid' to .gitignore to exclude log files and process ID files from version control. - Expanded Makefile with new development commands for easier local environment management, including 'dev-start', 'dev-stop', 'dev-restart', 'dev-logs', 'dev-status', 'dev-app', and 'dev-frontend'. - Updated README_CN.md to include instructions for the new development mode and commands for improved developer experience.
268 lines
5.5 KiB
Markdown
268 lines
5.5 KiB
Markdown
# 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 秒
|
||
|
||
祝你开发愉快!🚀
|
||
|