# New-API 官方更新适配手册

## 概述
本手册用于指导如何安全地将官方 GitHub 更新同步到我们的自定义版本，同时保留关键的自定义功能。

## 准备工作

### 远程仓库配置
确保已正确配置远程仓库：
```bash
# 检查远程仓库
git remote -v

# 应该看到：
# origin    https://git.586vip.cn/oadmin/new-api.git (自己的仓库)
# upstream  https://github.com/QuantumNous/new-api.git (官方仓库)
```

如果没有 upstream，添加官方仓库：
```bash
git remote add upstream https://github.com/QuantumNous/new-api.git
```

## 更新流程

### 1. 获取官方最新更新
```bash
# 获取官方最新代码
git fetch upstream

# 查看最新版本标签
git tag -l | grep "^v" | sort -V | tail -10

# 查看官方最新提交
git log upstream/main --oneline -10
```

### 2. 备份当前分支
```bash
# 创建备份分支（包含时间戳）
git checkout -b backup/before-sync-$(powershell -Command "Get-Date -Format 'yyyyMMdd-HHmm'")

# 提交当前所有修改
git add -A
git commit -m "备份：同步官方更新前的完整状态"

# 切换回主分支
git checkout main
```

### 3. 更新到官方最新版本
```bash
# 硬重置到官方最新版本（⚠️ 会覆盖所有本地修改）
git reset --hard upstream/main
```

### 4. 应用自定义功能
#### 4.1 恢复 Footer 自定义
```bash
# 方法1：使用补丁（如果存在）
git apply -R patches/footer-custom.patch

# 方法2：手动编辑
# 编辑 web/src/components/layout/Footer.js
# 将第85-88行的官方链接替换为：
```
```javascript
<span className="!text-semi-color-text-1">全栈服务提供商 </span>
<a href="https://hk.claude.cursorpro.com.cn" title="代理开设分销站" target="_blank" rel="noopener noreferrer" className="!text-semi-color-primary font-medium">听泉claude提供</a>
```

#### 4.2 恢复 Claude 穿透功能
编辑 `relay/channel/claude/adaptor.go`，将 `SetupRequestHeader` 函数替换为：

```go
func (a *Adaptor) SetupRequestHeader(c *gin.Context, req *http.Header, info *relaycommon.RelayInfo) error {
	if model_setting.GetGlobalSettings().PassThroughRequestEnabled {
		// 穿透模式：直接复制原始请求头，但跳过系统级头信息
		for key, values := range c.Request.Header {
			keyLower := strings.ToLower(key)
			if keyLower == "host" || keyLower == "content-length" || keyLower == "connection" {
				continue
			}
			for _, value := range values {
				req.Add(key, value)
			}
		}
	} else {
		// 非穿透模式：使用通用设置
		channel.SetupApiRequestHeader(info, c, req)
	}
	
	// 无论哪种模式都需要设置正确的API密钥
	req.Set("x-api-key", info.ApiKey)
	
	if !model_setting.GetGlobalSettings().PassThroughRequestEnabled {
		// 非穿透模式才强制设置这些头
		anthropicVersion := c.Request.Header.Get("anthropic-version")
		if anthropicVersion == "" {
			anthropicVersion = "2023-06-01"
		}
		req.Set("anthropic-version", anthropicVersion)
		model_setting.GetClaudeSettings().WriteHeaders(info.OriginModelName, req)
	}
	return nil
}
```

### 5. 检查其他可能的自定义修改
检查以下文件是否需要保留自定义修改：
- `controller/channel-billing.go` - 计费逻辑
- `docker-compose-custom.yml` - 自定义Docker配置
- `service/channel_state_reporter.go` - 渠道状态报告
- 其他业务相关文件

### 6. 验证和提交
```bash
# 检查修改状态
git status
git diff --name-only

# 添加修改的文件
git add relay/channel/claude/adaptor.go web/src/components/layout/Footer.js
git add 其他需要的文件...

# 提交修改
git commit -m "同步官方vX.X.X，保留自定义Footer和Claude穿透功能

- 更新到官方最新版本 (commit-hash)
- 保留自定义页脚品牌信息 (听泉claude提供)
- 保留Claude渠道请求穿透功能
- [其他自定义功能说明]

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>"
```

### 7. 推送到远程仓库
```bash
# 推送到自己的仓库
git push origin main

# 如果有冲突，可能需要强制推送（谨慎使用）
# git push origin main --force-with-lease
```

## 自动化脚本

创建 `scripts/sync-upstream.sh` 自动化脚本：

```bash
#!/bin/bash
set -e

echo "🔄 开始同步官方更新..."

# 获取最新版本
git fetch upstream
LATEST_COMMIT=$(git rev-parse upstream/main)
LATEST_TAG=$(git describe --tags --abbrev=0 upstream/main 2>/dev/null || echo "No tags")

echo "📋 准备更新到: $LATEST_TAG ($LATEST_COMMIT)"

# 备份当前分支
BACKUP_BRANCH="backup/before-sync-$(date +%Y%m%d-%H%M)"
git checkout -b $BACKUP_BRANCH
git add -A && git commit -m "备份：同步官方更新前的完整状态" || true
git checkout main

echo "💾 已创建备份分支: $BACKUP_BRANCH"

# 更新到官方最新
git reset --hard upstream/main

echo "✅ 已更新到官方最新版本"
echo "⚠️  请手动应用自定义修改："
echo "   1. Footer.js 自定义页脚"
echo "   2. Claude adaptor.go 穿透功能"
echo "   3. 其他业务相关修改"
echo ""
echo "🔍 检查修改: git status"
echo "💾 提交修改: git add . && git commit -m '更新说明'"
echo "🚀 推送远程: git push origin main"
```

## 重要提醒

### ⚠️ 风险提示
- `git reset --hard` 会**完全覆盖**本地修改
- 务必在操作前创建备份分支
- 推荐在测试环境先验证功能正常

### 🔍 验证检查清单
- [ ] Footer显示"听泉claude提供"
- [ ] Claude穿透功能正常工作
- [ ] 计费功能未受影响
- [ ] Docker配置正确
- [ ] 编译无错误
- [ ] 基础功能测试通过

### 📝 维护记录
每次更新后记录：
- 更新日期：
- 官方版本：
- 保留的自定义功能：
- 遇到的问题和解决方案：

## 联系信息
如有问题，联系技术团队或查看备份分支恢复。

---
*最后更新：2025-08-25*
*适用版本：v0.9.0-alpha.8+*