diff --git a/README.md b/README.md index 77d5057..3777e2c 100644 --- a/README.md +++ b/README.md @@ -360,6 +360,13 @@ make vet - [Agent 对话链路追踪设计](docs/学习/我的其他文档/Agent对话链路追踪设计文档.md) - [模型供应商测试说明](testdata/README.md) +### 开发流程 + +- [开发指南](docs/DEVELOPMENT.md) +- [PR流程规范](docs/PR流程规范.md) +- [Git提交规范](docs/Git提交规范.md) +- [部署流程](docs/部署流程.md) + README 只维护项目入口、依赖边界和本地启动流程；完整接口字段和专项模块设计以对应文档及当前代码为准。 ## 开发注意事项 diff --git "a/docs/Git\346\217\220\344\272\244\350\247\204\350\214\203.md" "b/docs/Git\346\217\220\344\272\244\350\247\204\350\214\203.md" new file mode 100644 index 0000000..8f6c5c3 --- /dev/null +++ "b/docs/Git\346\217\220\344\272\244\350\247\204\350\214\203.md" @@ -0,0 +1,258 @@ +# Git 提交规范 + +> 本文档定义了 Qavor 项目的 Git 提交信息规范。 +> 最后更新：2026-08-25 + +--- + +## 1. 提交信息格式 + +采用 [Conventional Commits](https://www.conventionalcommits.org/zh-hans/) 规范： + +``` +(): + +[optional body] + + +[optional footer(s)] +``` + +### 示例 + +```bash +# 简单提交 +git commit -m "feat(rag): 增加混合检索 RRF 融合" + +# 带范围的提交 +git commit -m "fix(auth): 修复登录 token 过期未刷新问题" + +# 带描述的提交 +git commit -m "feat(agent): 增加 Agent 执行取消功能 + +- 支持用户取消正在执行的 Agent 任务 +- 增加任务状态枚举 CANCELLED +- 修改前端按钮交互逻辑 + +Closes #123" +``` + +--- + +## 2. 类型说明 + +| 类型 | 说明 | 示例 | +|------|------|------| +| `feat` | 新功能 | `feat(rag): 增加混合检索` | +| `fix` | Bug 修复 | `fix(auth): 修复登录失败` | +| `docs` | 文档更新 | `docs: 更新部署流程文档` | +| `style` | 代码格式（不影响功能） | `style: 格式化 Go 代码` | +| `refactor` | 重构（非新功能、非修复） | `refactor(agent): 重构工具调用逻辑` | +| `perf` | 性能优化 | `perf(rag): 优化向量检索性能` | +| `test` | 测试相关 | `test: 增加 auth 模块单元测试` | +| `build` | 构建系统或外部依赖 | `build: 升级 Go 版本到 1.25` | +| `ci` | CI 配置 | `ci: 添加前端测试流水线` | +| `chore` | 其他杂项 | `chore: 清理无用代码` | +| `revert` | 回滚 | `revert: 回滚 feat(rag)` | + +--- + +## 3. 范围（Scope） + +范围是可选的，用于说明提交影响的模块： + +| 范围 | 说明 | +|------|------| +| `auth` | 用户认证模块 | +| `agent` | Agent 执行模块 | +| `rag` | RAG 知识库模块 | +| `chat` | 对话模块 | +| `tool` | 工具/MCP 模块 | +| `trace` | 链路追踪模块 | +| `skill` | Skill 系统 | +| `memory` | 记忆系统 | +| `frontend` | 前端通用 | +| `docker` | 容器化相关 | + +--- + +## 4. 主题（Subject） + +主题是提交的简短描述： + +- 使用中文 +- 不超过 50 个字符 +- 不加句号 +- 使用祈使句（"增加" 而非 "增加了"） + +**好的示例：** +```bash +feat(rag): 增加混合检索 RRF 融合 +fix(auth): 修复登录 token 过期问题 +docs: 更新部署流程文档 +``` + +**不好的示例：** +```bash +feat(rag): 增加了混合检索 RRF 融合功能。 # 太长，有句号 +fix bug # 太模糊 +update code # 太模糊 +``` + +--- + +## 5. 提交范围约定 + +### 5.1 代码文件 + +**只提交代码文件：** +- ✅ `.go` 文件 +- ✅ `.vue`、`.js`、`.ts` 文件 +- ✅ `.yaml`、`.yml` 配置文件 +- ✅ `go.mod`、`go.sum` +- ✅ `package.json`、`pnpm-lock.yaml` + +**不提交的文件：** +- ❌ `docs/` 文件夹 +- ❌ `frontend/test/` 测试文件 +- ❌ `*_test.go` 测试文件 +- ❌ 测试数据文件 +- ❌ `.env`、`configs/config.yaml`（本地配置） +- ❌ `logs/` 日志文件 +- ❌ `node_modules/` + +### 5.2 分次提交 + +一个功能应该分多次提交，每次提交只做一件事： + +```bash +# 1. 先提交实体定义 +git add internal/model/entity/knowledge_base.go +git commit -m "feat(knowledge): 定义知识库实体结构" + +# 2. 再提交 Repository +git add internal/repository/knowledge_base_repository.go +git commit -m "feat(knowledge): 实现知识库数据访问层" + +# 3. 再提交 Service +git add internal/service/knowledge_base_service.go +git commit -m "feat(knowledge): 实现知识库业务逻辑" + +# 4. 最后提交 Controller 和路由 +git add internal/api/v1/knowledge_base/ +git commit -m "feat(knowledge): 增加知识库 API 接口" +``` + +--- + +## 6. 特殊提交 + +### 6.1 合并冲突解决 + +```bash +git commit -m "merge: 解决与 develop 的合并冲突" +``` + +### 6.2 版本发布 + +```bash +git commit -m "chore(release): v1.0.0" +``` + +### 6.3 紧急修复 + +```bash +git commit -m "hotfix(auth): 紧急修复登录验证漏洞" +``` + +--- + +## 7. 检查工具 + +### 7.1 本地检查 + +```bash +# 检查最近一次提交 +git log -1 --pretty=%B + +# 检查最近 5 次提交 +git log -5 --pretty="%h %s" +``` + +### 7.2 自动格式化 + +项目可以配置 `commitlint` 来自动检查提交信息： + +```bash +# 安装（如果项目配置了） +npm install -D @commitlint/cli @commitlint/config-conventional + +# 检查提交信息 +npx commitlint --from HEAD~1 --to HEAD +``` + +--- + +## 8. 常见问题 + +### Q: 什么时候用 `feat`，什么时候用 `fix`？ + +- **feat**：新增功能（之前不存在的） +- **fix**：修复问题（之前存在但不正确的） + +### Q: scope 必须写吗？ + +不是必须的，但建议写。scope 能让提交信息更清晰。 + +### Q: 提交信息写英文还是中文？ + +建议使用**中文**，与项目保持一致。 + +### Q: 一个功能太大，怎么拆分提交？ + +按模块拆分： +```bash +# 实体层 +feat(xxx): 定义 xxx 实体结构 + +# 数据层 +feat(xxx): 实现 xxx 数据访问层 + +# 业务层 +feat(xxx): 实现 xxx 业务逻辑 + +# 接口层 +feat(xxx): 增加 xxx API 接口 +``` + +--- + +## 9. 示例提交历史 + +```bash +$ git log --oneline -15 + +a1b2c3d feat(knowledge): 增加知识库文档管理接口 +b2c3d4e feat(knowledge): 实现知识库业务逻辑 +c3d4e5f feat(knowledge): 实现知识库数据访问层 +d4e5f6g feat(knowledge): 定义知识库实体结构 +e5f6g7h fix(rag): 修复向量检索结果排序问题 +f6g7h8i feat(rag): 增加混合检索 RRF 融合 +g7h8i9j refactor(agent): 重构工具调用逻辑 +h8i9j0k fix(auth): 修复登录 token 过期未刷新 +i9j0k1l feat(auth): 增加用户登出功能 +j0k1l2m docs: 更新 API 文档 +k1l2m3n test: 增加 auth 模块单元测试 +l2m3n4o build: 升级 Go 版本到 1.25 +m3n4o5p ci: 添加前端测试流水线 +n4o5p6q chore: 清理无用代码 +o5p6q7r feat(agent): 增加 Agent 执行取消功能 +``` + +--- + +## 相关文档 + +- [PR流程规范](PR流程规范.md) +- [部署流程](部署流程.md) +- [开发指南](DEVELOPMENT.md) \ No newline at end of file diff --git "a/docs/PR\346\265\201\347\250\213\350\247\204\350\214\203.md" "b/docs/PR\346\265\201\347\250\213\350\247\204\350\214\203.md" new file mode 100644 index 0000000..dc2790f --- /dev/null +++ "b/docs/PR\346\265\201\347\250\213\350\247\204\350\214\203.md" @@ -0,0 +1,224 @@ +# Pull Request 流程规范 + +> 本文档定义了 Qavor 项目的 PR（Pull Request）提交、审查和合并流程。 +> 最后更新：2026-08-25 + +--- + +## 1. 分支策略 + +``` +main ← 生产分支，只接受 develop 的合并或紧急修复 + ↑ +develop ← 开发主分支，功能集成在此 + ↑ +feature/* ← 功能分支，从 develop 创建 +fix/* ← 修复分支，从 develop 或 main 创建 +``` + +| 分支类型 | 命名规范 | 说明 | +|---------|---------|------| +| `feature/*` | `feature/模块名-功能描述` | 新功能开发 | +| `fix/*` | `fix/模块名-问题描述` | Bug 修复 | +| `hotfix/*` | `hotfix/紧急问题描述` | 生产环境紧急修复 | +| `refactor/*` | `refactor/模块名-重构描述` | 代码重构 | + +--- + +## 2. PR 提交流程 + +### 2.1 创建功能分支 + +```bash +# 从 develop 拉取最新代码 +git checkout develop +git pull origin develop + +# 创建功能分支 +git checkout -b feature/模块名-功能描述 + +# 开发完成后推送 +git push origin feature/模块名-功能描述 +``` + +### 2.2 提交前检查清单 + +- [ ] 代码遵循项目代码规范（见 `docs/DEVELOPMENT.md`） +- [ ] 后端测试全部通过：`go test ./...` +- [ ] 前端测试全部通过：`cd frontend && pnpm test:unit` +- [ ] 代码已格式化：`go fmt ./...` +- [ ] 静态检查通过：`go vet ./...` +- [ ] 只提交代码文件，不提交 `docs/`、测试文件 +- [ ] 提交信息符合规范（见 [Git提交规范](Git提交规范.md)） + +### 2.3 创建 PR + +1. 登录 GitHub，进入仓库页面 +2. 点击 "Compare & pull request" 按钮 +3. 填写 PR 信息： + +**标题格式：** +``` +feat(模块): 功能描述 +``` + +**描述模板：** +```markdown +## 变更说明 + + +## 关联 Issue + +Closes # + +## 测试情况 +- [ ] 后端测试通过 +- [ ] 前端测试通过 +- [ ] 本地功能验证 + +## 截图/录屏 + +``` + +### 2.4 PR 目标分支 + +| PR 类型 | 目标分支 | +|---------|---------| +| 新功能 | `develop` | +| Bug 修复 | `develop` | +| 紧急修复 | `main` | + +--- + +## 3. PR 审查流程 + +### 3.1 审查要求 + +- **至少 1 人审查通过** 才能合并 +- 审查重点： + - 代码逻辑是否正确 + - 是否遵循项目规范 + - 是否有潜在的 Bug 或安全问题 + - 测试是否充分 + +### 3.2 审查操作 + +```bash +# 本地审查 PR 代码 +git fetch origin +git checkout origin/feature/模块名-功能描述 +``` + +### 3.3 审查反馈 + +- **通过**：在 PR 页面点击 "Approve" +- **需要修改**：在 PR 页面点击 "Request changes" 并说明原因 +- **评论**：在 PR 页面添加评论讨论 + +### 3.4 常见审查问题 + +| 问题类型 | 说明 | +|---------|------| +| 代码规范 | 命名、注释、格式不符合规范 | +| 逻辑错误 | 代码逻辑有问题 | +| 测试不足 | 缺少必要的单元测试 | +| 文档缺失 | 新功能未更新相关文档 | +| 提交信息 | 不符合 Conventional Commits 规范 | + +--- + +## 4. 合并策略 + +### 4.1 合并方式 + +项目使用 **Squash and merge** 策略，保持主分支历史清晰。 + +### 4.2 合并操作 + +1. PR 审查通过后，点击 "Squash and merge" +2. 确认提交信息（会自动合并为一条） +3. 删除功能分支（勾选 "Delete branch"） + +### 4.3 合并后清理 + +```bash +# 本地删除已合并的分支 +git checkout develop +git pull origin develop +git branch -d feature/模块名-功能描述 +``` + +--- + +## 5. 解决冲突 + +### 5.1 检测冲突 + +```bash +# 更新 develop 分支 +git fetch origin develop + +# 在功能分支上合并 develop +git checkout feature/模块名-功能描述 +git merge origin/develop +``` + +### 5.2 解决冲突 + +```bash +# 查看冲突文件 +git status + +# 手动解决冲突后 +git add <冲突文件> +git commit -m "merge: 解决与 develop 的合并冲突" +git push origin feature/模块名-功能描述 +``` + +--- + +## 6. 特殊情况处理 + +### 6.1 WIP（Work in Progress）PR + +- 创建 PR 时在标题前加 `[WIP]`：`[WIP] feat(模块): 功能描述` +- 表示 PR 尚未完成，不需要审查 + +### 6.2 紧急修复（Hotfix） + +```bash +# 从 main 创建 hotfix 分支 +git checkout main +git pull origin main +git checkout -b hotfix/紧急问题描述 + +# 修复后推送 +git push origin hotfix/紧急问题描述 +``` + +- PR 目标分支选择 `main` +- 合并后需要同步到 `develop`： + +```bash +git checkout develop +git merge main +git push origin develop +``` + +--- + +## 7. 最佳实践 + +1. **小批量提交**：PR 变更尽量控制在 200 行以内，便于审查 +2. **单一职责**：一个 PR 只做一件事 +3. **及时响应**：收到审查反馈后尽快修改 +4. **保持更新**：定期 rebase develop 分支，避免冲突积累 +5. **写好描述**：让审查者快速理解变更内容 + +--- + +## 相关文档 + +- [Git提交规范](Git提交规范.md) +- [部署流程](部署流程.md) +- [开发指南](DEVELOPMENT.md) \ No newline at end of file diff --git "a/docs/\351\203\250\347\275\262\346\265\201\347\250\213.md" "b/docs/\351\203\250\347\275\262\346\265\201\347\250\213.md" new file mode 100644 index 0000000..8201e15 --- /dev/null +++ "b/docs/\351\203\250\347\275\262\346\265\201\347\250\213.md" @@ -0,0 +1,380 @@ +# 部署流程 + +> 本文档描述了 Qavor 项目的 CI/CD 流水线和部署方式。 +> 最后更新：2026-08-25 + +--- + +## 1. 概述 + +项目采用 GitHub Actions 实现 CI/CD 自动化： + +| 流程 | 触发条件 | 说明 | +|------|---------|------| +| **CI（持续集成）** | push 到 `main`/`develop` 或 PR | 运行测试、构建验证 | +| **CD（持续部署）** | push 到 `main` 或版本 tag | 构建 Docker 镜像并推送到 GHCR | + +--- + +## 2. CI 流程（持续集成） + +### 2.1 触发条件 + +- push 到 `main` 或 `develop` 分支 +- Pull Request + +### 2.2 流程步骤 + +**后端（Backend）：** +```yaml +checkout → Go setup → go mod download → go mod verify → go test → go vet → go build +``` + +**前端（Frontend）：** +```yaml +checkout → pnpm setup → Node.js 22 → pnpm install → pnpm test:unit → eslint → pnpm build +``` + +### 2.3 本地验证 + +```bash +# 后端测试 +go test ./... +go vet ./... +go build -o bin/qavor-api ./cmd/server + +# 前端测试 +cd frontend +pnpm test:unit +pnpm lint +pnpm build +``` + +--- + +## 3. CD 流程（持续部署） + +### 3.1 触发条件 + +| 事件 | 镜像标签 | 说明 | +|------|---------|------| +| push 到 `main` | `:main` + `:latest` | 开发版本 | +| push 版本 tag | `:1.0.0` + `:1.0` + `:latest` | 正式版本 | +| 手动触发 | 自定义 | workflow_dispatch | + +### 3.2 镜像地址 + +| 组件 | 镜像地址 | +|------|---------| +| 后端 | `ghcr.io/6moran/qavor-api` | +| 前端 | `ghcr.io/6moran/qavor-web` | + +### 3.3 镜像标签说明 + +| 标签格式 | 示例 | 说明 | +|---------|------|------| +| `latest` | `:latest` | 最新稳定版（指向 main 分支最新） | +| 分支名 | `:main` | main 分支最新构建 | +| 完整版本 | `:1.0.0` | 语义化版本号 | +| 主次版本 | `:1.0` | 主版本.次版本 | +| 主版本 | `:1` | 主版本 | + +--- + +## 4. 发布新版本 + +### 4.1 正式发布流程 + +```bash +# 1. 确保 develop 分支已合并到 main +git checkout main +git pull origin main + +# 2. 创建版本 tag +git tag -a v1.0.0 -m "Release v1.0.0" + +# 3. 推送 tag（触发 CD 流水线） +git push origin v1.0.0 +``` + +### 4.2 版本号规范 + +采用 [语义化版本](https://semver.org/lang/zh-CN/)： + +``` +MAJOR.MINOR.PATCH +``` + +| 类型 | 说明 | 示例 | +|------|------|------| +| MAJOR | 不兼容的 API 修改 | v2.0.0 | +| MINOR | 向下兼容的功能新增 | v1.1.0 | +| PATCH | 向下兼容的问题修正 | v1.0.1 | + +--- + +## 5. 生产环境部署 + +### 5.1 拉取镜像 + +```bash +# 登录 GHCR +docker login ghcr.io -u <你的GitHub用户名> + +# 拉取镜像 +docker pull ghcr.io/6moran/qavor-api:latest +docker pull ghcr.io/6moran/qavor-web:latest +``` + +### 5.2 环境准备 + +1. **PostgreSQL** + - 安装并启用 `pgvector` 和 `pg_trgm` 扩展 + - 创建数据库：`CREATE DATABASE qavor;` + +2. **Redis** + - 安装 Redis 并确保可连接 + +3. **MinIO** + - 安装 MinIO 并创建 Bucket + +### 5.3 配置文件 + +创建生产环境配置： + +```bash +# 复制配置模板 +cp configs/config.yaml.example configs/config.yaml +cp .env.example .env + +# 编辑配置 +vim configs/config.yaml +vim .env +``` + +**重要配置项：** + +```yaml +# config.yaml +app: + mode: release # 生产模式 + +database: + auto_migrate: false # 生产环境关闭自动迁移 +``` + +```env +# .env +POSTGRES_HOST=your-db-host +POSTGRES_PASSWORD=your-strong-password +JWT_SECRET=your-random-secret +# ... 其他配置 +``` + +### 5.4 启动服务 + +**方式一：Docker Compose（推荐）** + +```yaml +# docker-compose.yml +version: '3.8' + +services: + api: + image: ghcr.io/6moran/qavor-api:latest + ports: + - "8080:8080" + env_file: + - .env + volumes: + - ./configs:/app/configs + depends_on: + - postgres + - redis + + web: + image: ghcr.io/6moran/qavor-web:latest + ports: + - "80:80" + depends_on: + - api + + postgres: + image: pgvector/pgvector:pg16 + environment: + POSTGRES_DB: qavor + POSTGRES_PASSWORD: ${POSTGRES_PASSWORD} + volumes: + - pgdata:/var/lib/postgresql/data + ports: + - "5432:5432" + + redis: + image: redis:7-alpine + ports: + - "6379:6379" + +volumes: + pgdata: +``` + +```bash +# 启动所有服务 +docker-compose up -d + +# 查看日志 +docker-compose logs -f + +# 停止服务 +docker-compose down +``` + +**方式二：手动部署** + +```bash +# 1. 启动 PostgreSQL +docker run -d --name qavor-pg \ + -e POSTGRES_DB=qavor \ + -e POSTGRES_PASSWORD=xxx \ + -p 5432:5432 \ + pgvector/pgvector:pg16 + +# 2. 启动 Redis +docker run -d --name qavor-redis \ + -p 6379:6379 \ + redis:7-alpine + +# 3. 初始化数据库 +psql -h localhost -U postgres -d qavor -c "CREATE EXTENSION IF NOT EXISTS vector;" +psql -h localhost -U postgres -d qavor -c "CREATE EXTENSION IF NOT EXISTS pg_trgm;" +psql -h localhost -U postgres -d qavor -f scripts/migrate.sql + +# 4. 启动后端 +docker run -d --name qavor-api \ + -p 8080:8080 \ + --env-file .env \ + -v $(pwd)/configs:/app/configs \ + ghcr.io/6moran/qavor-api:latest + +# 5. 启动前端（使用 Nginx） +docker run -d --name qavor-web \ + -p 80:80 \ + --link qavor-api:api \ + ghcr.io/6moran/qavor-web:latest +``` + +### 5.5 验证部署 + +```bash +# 检查健康状态 +curl http://localhost:8080/api/v1/health + +# 访问前端 +# 浏览器打开 http://localhost +``` + +--- + +## 6. 回滚流程 + +### 6.1 回滚到指定版本 + +```bash +# 停止当前服务 +docker-compose down + +# 修改镜像标签为指定版本 +# 编辑 docker-compose.yml，将 image 改为具体版本号 +# 例如：ghcr.io/6moran/qavor-api:v1.0.0 + +# 重新启动 +docker-compose up -d +``` + +### 6.2 回滚到上一版本 + +```bash +# 使用上一个版本的标签 +docker pull ghcr.io/6moran/qavor-api:v1.0.0 +docker-compose up -d +``` + +--- + +## 7. 环境变量说明 + +### 7.1 必需配置 + +| 变量 | 说明 | 示例 | +|------|------|------| +| `POSTGRES_HOST` | PostgreSQL 地址 | `localhost` | +| `POSTGRES_PORT` | PostgreSQL 端口 | `5432` | +| `POSTGRES_USERNAME` | PostgreSQL 用户名 | `postgres` | +| `POSTGRES_PASSWORD` | PostgreSQL 密码 | `xxx` | +| `POSTGRES_DATABASE` | 数据库名 | `qavor` | +| `REDIS_HOST` | Redis 地址 | `localhost` | +| `REDIS_PORT` | Redis 端口 | `6379` | +| `MINIO_ENDPOINT` | MinIO 地址 | `localhost:9000` | +| `MINIO_ACCESS_KEY` | MinIO Access Key | `xxx` | +| `MINIO_SECRET_KEY` | MinIO Secret Key | `xxx` | +| `MINIO_BUCKET` | MinIO Bucket 名称 | `qavor` | +| `JWT_SECRET` | JWT 签名密钥 | `随机强密码` | +| `QAVOR_AUTH_ADMIN_USERNAME` | 管理员用户名 | `admin` | +| `QAVOR_AUTH_ADMIN_PASSWORD` | 管理员密码 | `xxx` | + +### 7.2 可选配置 + +| 变量 | 说明 | 默认值 | +|------|------|--------| +| `APP_PORT` | 服务端口 | `8080` | +| `REDIS_DB` | Redis 数据库编号 | `0` | +| `RAG_CHUNK_TOKENS` | RAG 分块大小 | `512` | +| `trace.enabled` | 启用链路追踪 | `true` | + +--- + +## 8. 监控与日志 + +### 8.1 查看日志 + +```bash +# Docker 日志 +docker logs -f qavor-api + +# 或查看日志文件（如果挂载了日志目录） +tail -f logs/app.log +``` + +### 8.2 健康检查 + +```bash +# API 健康检查 +curl http://localhost:8080/api/v1/health + +# 返回示例 +{ + "status": "ok", + "timestamp": "2026-08-25T10:00:00Z" +} +``` + +--- + +## 9. 常见问题 + +| 问题 | 解决方案 | +|------|---------| +| 镜像拉取失败 | 检查 GHCR 登录状态：`docker login ghcr.io` | +| 数据库连接失败 | 检查 PostgreSQL 是否启动，配置是否正确 | +| Redis 连接失败 | 检查 Redis 是否启动，密码是否正确 | +| 文件上传失败 | 检查 MinIO 是否启动，Bucket 是否创建 | +| 服务启动慢 | 首次启动需要初始化数据库，等待 30-60 秒 | + +--- + +## 相关文档 + +- [PR流程规范](PR流程规范.md) +- [Git提交规范](Git提交规范.md) +- [开发指南](DEVELOPMENT.md) +- [架构设计](ARCHITECTURE.md) \ No newline at end of file