Files
Enterprise-Knowledge-Base/DEVELOPMENT.md
T
wizardchen d387fd672f chore: Update .gitignore and Makefile for development enhancements
- 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.
2025-11-07 15:52:52 +08:00

268 lines
5.5 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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 秒
祝你开发愉快!🚀