WeKnora deployment source with the reviewed wiki identity, summary and recovery fixes

2026-09-22 16:19:06 +08:00
commit f7fc992f57
3929 changed files with 1006607 additions and 0 deletions
@@ -0,0 +1,221 @@
+# 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`