new-api/temp/UPDATE_MANUAL.md

New-API 官方更新适配手册

概述

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

准备工作

远程仓库配置

确保已正确配置远程仓库：

# 检查远程仓库
git remote -v

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

如果没有 upstream，添加官方仓库：

git remote add upstream https://github.com/QuantumNous/new-api.git

更新流程

1. 获取官方最新更新

# 获取官方最新代码
git fetch upstream

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

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

2. 备份当前分支

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

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

# 切换回主分支
git checkout main

3. 更新到官方最新版本

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

4. 应用自定义功能

4.1 恢复 Footer 自定义

# 方法1：使用补丁（如果存在）
git apply -R patches/footer-custom.patch

# 方法2：手动编辑
# 编辑 web/src/components/layout/Footer.js
# 将第85-88行的官方链接替换为：

<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 函数替换为：

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. 验证和提交

# 检查修改状态
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. 推送到远程仓库

# 推送到自己的仓库
git push origin main

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

自动化脚本

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

#!/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+