From ab48c8532c8d1804aa048ca181200e4d6416c4a3 Mon Sep 17 00:00:00 2001 From: huangzhenpc Date: Tue, 26 Aug 2025 16:45:38 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=B7=BB=E5=8A=A0=E9=A1=B9=E7=9B=AE?= =?UTF-8?q?=E5=B7=A5=E4=BD=9C=E6=B5=81=E7=A8=8B=E6=96=87=E6=A1=A3=E5=92=8C?= =?UTF-8?q?=20Claude=20Code=20=E9=85=8D=E7=BD=AE?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 创建详细的 Git 工作流程指南 (temp/git-workflow.md) - 添加 Claude Code 项目配置文件 (.claude) - 包含分支管理、开发指南、部署方案等完整文档 --- .claude | 133 ++++++++++++++++++++++++++ temp/git-workflow.md | 217 +++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 350 insertions(+) create mode 100644 .claude create mode 100644 temp/git-workflow.md diff --git a/.claude b/.claude new file mode 100644 index 00000000..8da5e3a0 --- /dev/null +++ b/.claude @@ -0,0 +1,133 @@ +# New-API 项目配置 - Claude Code + +## 🏗️ 项目架构 + +这是一个基于 Go + React 的 AI API 网关项目，用于代理和管理多种 AI 模型服务。 + +### 核心组件 +- **后端**: Go (Gin框架) - API网关和转发逻辑 +- **前端**: React (Vite) - 管理界面 +- **数据库**: SQLite/MySQL - 配置和日志存储 +- **部署**: Docker + Docker Compose + +## 📂 重要目录结构 + +``` +new-api/ +├── relay/ # 核心转发逻辑 +│ ├── channel/ # 各厂商适配器 +│ │ ├── claude/ # Claude 适配器 (重点关注) +│ │ ├── openai/ # OpenAI 适配器 +│ │ └── ... # 其他厂商 +│ ├── common/ # 通用转发组件 +│ └── helper/ # 辅助工具 +├── middleware/ # 中间件 (认证、限流、分发) +├── model/ # 数据模型 +├── controller/ # API控制器 +├── service/ # 业务服务 +├── web/ # React前端 +└── temp/ # 工作文档和脚本 + └── git-workflow.md # Git工作流程指南 +``` + +## 🎯 当前定制功能 + +### 1. Claude 智能请求头管理系统 (已实现) +**位置**: `relay/channel/claude/adaptor.go` +**功能**: +- 支持渠道级透传设置 +- 智能检测客户端类型 (Claude Code、killcode、其他) +- 动态请求头策略 (透传 vs 伪装) +- 防止显示 Go-http-client User-Agent + +### 2. 渠道透传增强 (已修复) +**问题**: Claude 适配器不支持渠道级透传设置 +**解决**: 添加 `info.ChannelSetting.PassThroughBodyEnabled` 检查 + +## 🔧 开发指南 + +### 添加新的 AI 厂商适配器 +1. 在 `relay/channel/` 创建新目录 +2. 实现 `Adaptor` 接口的所有方法 +3. 在 `relay/relay_adaptor.go` 注册适配器 +4. 添加常量定义到 `constant/` 目录 + +### 修改请求头处理逻辑 +**关键文件**: `relay/channel/claude/adaptor.go:SetupRequestHeader()` +**注意事项**: +- 保持与其他适配器的一致性 +- 考虑全局透传和渠道透传两种模式 +- 确保 User-Agent 不被 Go HTTP 客户端覆盖 + +### 前端界面修改 +**位置**: `web/src/components/table/channels/modals/EditChannelModal.jsx` +**渠道设置**: `ChannelSettings` 结构体对应前端表单 + +## 🚀 Git 工作流程 + +详细流程请查看: `temp/git-workflow.md` + +### 分支策略 +- `main`: 生产稳定版本 +- `develop`: 日常开发分支 +- `upstream-sync`: 上游官方同步 +- `hotfix/*`: 紧急修复分支 + +### 远程仓库 +- `origin`: https://git.586vip.cn/oadmin/new-api.git (私有仓库) +- `upstream`: https://github.com/QuantumNous/new-api.git (上游仓库) + +## 🐳 部署方案 + +### Docker Compose 部署 +```bash +# 构建并启动服务 +docker-compose -f docker-compose-custom.yml up --build -d + +# 查看日志 +docker-compose -f docker-compose-custom.yml logs -f new-api-custom +``` + +### 环境配置 +- **端口**: 3099 (外部访问) +- **数据目录**: `./data` +- **日志目录**: `./logs-custom` +- **网络**: `new-api_default` + +## ⚠️ 重要注意事项 + +### 代码修改原则 +1. **不要随意修改 go.mod 版本**: 本地和服务器环境可能不同 +2. **保持向后兼容**: 修改时考虑现有配置的兼容性 +3. **完整测试**: 每次修改都要测试多种客户端兼容性 +4. **文档同步**: 重要修改及时更新此配置文件 + +### 常见问题排查 +1. **透传不生效**: 检查全局设置和渠道设置 +2. **User-Agent 显示为 Go-http-client**: 检查请求头设置逻辑 +3. **Docker 构建失败**: 检查 Dockerfile 和依赖版本 + +## 📚 参考资料 + +- 官方文档: https://github.com/songquanpeng/one-api +- API 规范: `docs/api/` 目录 +- 部署指南: `docs/installation/` 目录 + +## 🔍 开发技巧 + +### 调试 HTTP 请求 +```go +if common.DebugEnabled { + println("Request Headers:", req.Header) + println("Request URL:", fullRequestURL) +} +``` + +### 测试客户端兼容性 +- Claude Code: User-Agent 包含 "claude-cli" +- killcode: User-Agent 包含 "B2/JS" 或存在 "X-Stainless" 头部 +- 其他客户端: 自动伪装成 killcode 格式 + +--- +*配置文件最后更新: 2025-01-26* +*对应代码版本: commit 878918ba (恢复原始 Go 版本设置)* \ No newline at end of file diff --git a/temp/git-workflow.md b/temp/git-workflow.md new file mode 100644 index 00000000..fcca19da --- /dev/null +++ b/temp/git-workflow.md @@ -0,0 +1,217 @@ +# New-API Git 工作流程指南 + +## 🎯 分支架构 + +``` +main (生产稳定) +├── develop (日常开发) +├── upstream-sync (上游同步) +└── hotfix/* (紧急修复) +``` + +## 📋 分支职责 + +### 🔒 main (生产分支) +- **用途**: 生产环境部署 +- **特点**: 只接受经过完整测试的代码 +- **保护**: 禁止直接推送，只能通过 PR/MR 合并 + +### 🚧 develop (开发分支) +- **用途**: 日常自定义功能开发 +- **特点**: 基于 main 分支，包含所有自定义修改 +- **流程**: 功能完成后合并回 main + +### 🔄 upstream-sync (同步分支) +- **用途**: 跟踪官方 new-api 更新 +- **特点**: 保持与上游仓库同步，不包含自定义修改 +- **流程**: 定期同步，选择性合并到 develop + +### 🚨 hotfix/* (修复分支) +- **用途**: 生产环境紧急问题修复 +- **特点**: 基于 main 分支，修复后直接合并回 main 和 develop + +## 🔄 标准工作流程 + +### 1. 日常功能开发 + +```bash +# 1. 确保在最新的 develop 分支 +git checkout develop +git pull origin develop + +# 2. 创建功能分支 (可选，小改动可直接在 develop) +git checkout -b feature/智能请求头优化 + +# 3. 开发和测试 +# ... 编码 ... +git add . +git commit -m "feat: 实现新功能" + +# 4. 推送到远程 +git push origin feature/智能请求头优化 + +# 5. 测试通过后合并到 develop +git checkout develop +git merge feature/智能请求头优化 +git push origin develop + +# 6. 部署测试无问题后合并到 main +git checkout main +git merge develop +git push origin main + +# 7. 清理功能分支 +git branch -d feature/智能请求头优化 +git push origin --delete feature/智能请求头优化 +``` + +### 2. 上游同步更新 + +```bash +# 1. 切换到同步分支 +git checkout upstream-sync + +# 2. 拉取上游最新更新 +git fetch upstream +git merge upstream/main + +# 3. 推送同步结果 +git push origin upstream-sync + +# 4. 检查更新内容，选择性合并到 develop +git checkout develop +git log upstream-sync --oneline -10 # 查看新提交 + +# 5. 选择需要的提交合并 (谨慎操作) +git cherry-pick # 只合并需要的提交 + +# 6. 或者创建合并请求进行 code review +``` + +### 3. 生产环境紧急修复 + +```bash +# 1. 基于 main 创建修复分支 +git checkout main +git checkout -b hotfix/修复Claude透传问题 + +# 2. 修复问题 +# ... 编码修复 ... +git add . +git commit -m "hotfix: 修复 Claude 透传问题" + +# 3. 测试修复效果 +# ... 测试 ... + +# 4. 合并到 main (生产部署) +git checkout main +git merge hotfix/修复Claude透传问题 +git push origin main + +# 5. 同步修复到 develop +git checkout develop +git merge hotfix/修复Claude透传问题 +git push origin develop + +# 6. 清理修复分支 +git branch -d hotfix/修复Claude透传问题 +``` + +## 🛡️ 安全检查清单 + +### 合并前检查 +- [ ] 代码编译通过 +- [ ] Docker 构建成功 +- [ ] 功能测试完成 +- [ ] 没有遗留 TODO 或 debug 代码 +- [ ] 提交信息清晰明确 + +### 部署前检查 +- [ ] 备份当前生产版本 +- [ ] 数据库迁移脚本准备就绪 +- [ ] 回滚方案确定 +- [ ] 监控告警已配置 + +## 📁 目录结构说明 + +``` +new-api/ +├── temp/ +│ ├── git-workflow.md # 本文档 +│ ├── deployment-checklist.md # 部署检查清单 +│ └── troubleshooting.md # 问题排查指南 +├── .claude # Claude Code 项目配置 +└── ... +``` + +## 🚀 自动化建议 + +### Git Hooks +```bash +# pre-commit: 提交前检查 +#!/bin/sh +echo "运行代码格式化..." +go fmt ./... + +echo "运行静态检查..." +go vet ./... +``` + +### CI/CD 流程 +```yaml +# GitHub Actions 示例 +name: CI/CD Pipeline +on: + push: + branches: [ main, develop ] + pull_request: + branches: [ main ] + +jobs: + test: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + - name: Build and Test + run: | + go build ./... + docker build -t new-api-test . +``` + +## 💡 最佳实践 + +1. **小步快跑**: 频繁小提交，避免大批量修改 +2. **描述清晰**: 提交信息使用约定式提交格式 +3. **测试先行**: 每个功能都要有对应测试 +4. **文档同步**: 重要修改及时更新文档 +5. **备份习惯**: 重要操作前先创建备份分支 + +## 📞 故障处理 + +### 紧急回滚 +```bash +# 1. 快速回滚到上一个稳定版本 +git checkout main +git reset --hard HEAD~1 +git push --force-with-lease origin main + +# 2. 或回滚到指定版本 +git reset --hard +git push --force-with-lease origin main +``` + +### 冲突解决 +```bash +# 1. 查看冲突文件 +git status + +# 2. 手动解决冲突 +# 编辑冲突文件，删除 <<<<<<< ======= >>>>>>> 标记 + +# 3. 标记冲突已解决 +git add +git commit +``` + +--- +*本文档由 Claude Code 生成，请根据实际情况调整* \ No newline at end of file