# 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 版本设置)*