docs: 添加项目工作流程文档和 Claude Code 配置

- 创建详细的 Git 工作流程指南 (temp/git-workflow.md) - 添加 Claude Code 项目配置文件 (.claude) - 包含分支管理、开发指南、部署方案等完整文档
2025-08-26 16:45:38 +08:00
parent 878918ba58
commit ab48c8532c
2 changed files with 350 additions and 0 deletions
--- a/.claude
+++ 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 版本设置)*
--- a/temp/git-workflow.md
+++ 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 <commit-hash>  # 只合并需要的提交
+
+# 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 <stable-commit-hash>
+git push --force-with-lease origin main
+```
+
+### 冲突解决
+```bash
+# 1. 查看冲突文件
+git status
+
+# 2. 手动解决冲突
+# 编辑冲突文件，删除 <<<<<<< ======= >>>>>>> 标记
+
+# 3. 标记冲突已解决
+git add <resolved-file>
+git commit
+```
+
+---
+*本文档由 Claude Code 生成，请根据实际情况调整*