tokens-reef/docs/MERGE_GUIDE.md

官方版本合并指南

创建日期: 2026-04-15 项目路径: D:\project\sub2api-merge 适用场景: 每周定期合并官方仓库更新

---

一、合并前准备

1.1 环境检查

# 确认当前分支状态
git status
git branch -a

# 确认远程仓库配置
git remote -v
# 应该看到:
# origin    https://github.com/Wei-Shaw/sub2api.git (fetch)
# upstream  https://github.com/sub2api/sub2api.git (fetch)  # 官方仓库

1.2 添加官方仓库（首次）

# 如果没有upstream，添加官方仓库
git remote add upstream https://github.com/sub2api/sub2api.git
git fetch upstream

1.3 备份当前工作

# 创建备份分支
git checkout -b backup/$(date +%Y%m%d)

# 或使用worktree隔离
git worktree add ../sub2api-backup main

---

二、合并流程

2.1 标准合并步骤

# 1. 切换到主分支
git checkout main

# 2. 拉取官方最新代码
git fetch upstream

# 3. 查看差异
git log HEAD..upstream/main --oneline
git diff HEAD upstream/main --stat

# 4. 执行合并
git merge upstream/main

# 5. 如果有冲突，解决后继续
git mergetool  # 或手动编辑
git add .
git commit -m "Merge upstream/main $(date +%Y-%m-%d)"

2.2 使用Rebase保持线性历史（可选）

git rebase upstream/main

2.3 冲突解决策略

冲突类型	解决策略
代码逻辑冲突	优先保留官方版本，再手动添加本地修改
配置文件冲突	合并双方配置，保留本地特殊配置
定价数据冲突	保留官方定价，补充国内模型定价
URL白名单冲突	合并双方域名列表

---

三、本地独有功能清单

合并时需确保以下本地功能不被覆盖：

3.1 后端功能

文件	功能	说明
billing_service.go	国内模型定价	fallback定价和匹配逻辑
config.go	URL白名单	国内模型API域名
model_prices_and_context_window.json	定价数据	国内模型价格配置

3.2 国内模型支持

智谱GLM系列:

• glm-5, glm-5-turbo, glm-5.1, glm-4.7, glm-4.5-air
• glm-4-plus, glm-4-flash, glm-4-flashx
• glm-z1-air, glm-z1-airx

通义千问系列:

• qwen-turbo, qwen-plus, qwen-max, qwen-long
• qwen2.5-72b-instruct, qwen2.5-32b-instruct
• qwen-coder-plus, qwen3-8b

月之暗面Kimi系列:

• moonshot-v1-8k, moonshot-v1-32k, moonshot-v1-128k
• kimi-k2

MiniMax系列:

• abab6.5s-chat, abab6.5t-chat
• minimax-m2.7

豆包系列:

• doubao-lite-4k/32k/128k
• doubao-pro-4k/32k/128k
• doubao-seed-1.6, doubao-1.5-thinking-pro

百川智能系列:

• baichuan4, baichuan4-turbo, baichuan4-air
• baichuan-m3-plus

DeepSeek系列:

• deepseek-v3, deepseek-v3.2, deepseek-r1

3.3 URL白名单域名

// 国内模型 - 月之暗面Kimi
"api.kimi.com", "api.moonshot.cn",

// 国内模型 - 智谱GLM
"open.bigmodel.cn", "bigmodel.cn", "api.z.ai",

// 国内模型 - MiniMax
"api.minimaxi.com", "minimaxi.com",

// 国内模型 - 阿里云通义千问
"dashscope.aliyuncs.com", "dashscope.aliyun.com",

// 国内模型 - 豆包/火山引擎
"ark.cn-beijing.volces.com", "ark-api.volces.com", "api.volcengine.com",

// 国内模型 - DeepSeek
"api.deepseek.com",

// 国内模型 - 百度文心
"aip.baidubce.com",

// 国内模型 - 讯飞星火
"spark-api-open.xf-yun.com",

// 国内模型 - 腾讯混元
"hunyuan.tencentcloudapi.com",

// 国内模型 - 零一万物
"api.lingyiwanwu.com",

// 国内模型 - 百川智能
"api.baichuan-ai.com",

// 国内模型 - 硅基流动SiliconFlow
"api.siliconflow.cn",

// 国内模型 - Groq (加速推理)
"api.groq.com",

---

四、合并后验证

4.1 编译验证

cd backend

# Go编译
go build ./cmd/server

# 前端构建
cd ../frontend
npm run build

4.2 测试验证

# 后端测试
cd backend
go test ./... -v -count=1

# 注意: Windows上logger测试可能超时，可忽略

4.3 JSON格式验证

python -c "import json; json.load(open('backend/resources/model-pricing/model_prices_and_context_window.json', encoding='utf-8')); print('OK')"

4.4 功能验证清单

• 后端编译通过
• 前端构建通过
• 国内模型定价正确加载
• URL白名单配置正确
• 数据库迁移正常
• API接口响应正常

---

五、定价数据更新流程

5.1 检查官方定价更新

# 查看定价文件变化
git diff HEAD upstream/main -- backend/resources/model-pricing/

5.2 更新国内模型定价

1. 访问各厂商官方定价页面获取最新价格
2. 更新 model_prices_and_context_window.json
3. 更新 billing_service.go 中的 fallback 定价
4. 更新匹配逻辑

5.3 定价数据来源

厂商	定价页面
智谱GLM	https://open.bigmodel.cn/pricing
通义千问	https://help.aliyun.com/zh/dashscope/developer-reference/tongyi-qianwen
Moonshot	https://platform.moonshot.cn/docs/pricing/chat
MiniMax	https://platform.minimaxi.com/pricing
豆包	https://www.volcengine.com/docs/82379/1290310
DeepSeek	https://api-docs.deepseek.com/quick_start/pricing
百川智能	https://platform.baichuan-ai.com/prices
硅基流动	https://siliconflow.cn/pricing

---

六、常见问题处理

6.1 合并冲突：pricing文件

问题: 官方更新了定价文件，覆盖了国内模型定价

解决:

# 1. 备份本地定价
cp backend/resources/model-pricing/model_prices_and_context_window.json /tmp/local_pricing.json

# 2. 接受官方版本
git checkout --theirs backend/resources/model-pricing/model_prices_and_context_window.json

# 3. 手动合并国内模型定价
# 使用编辑器将 /tmp/local_pricing.json 中的国内模型部分追加回去

6.2 合并冲突：billing_service.go

问题: 官方更新了计费逻辑

解决:

# 1. 查看差异
git diff HEAD upstream/main -- backend/internal/service/billing_service.go

# 2. 手动合并，保留:
#    - initFallbackPricing() 中的国内模型定价
#    - getFallbackPricing() 中的国内模型匹配逻辑

6.3 合并冲突：config.go

问题: 官方更新了配置结构

解决:

# 保留本地URL白名单配置
# 合并官方新增配置项

6.4 测试失败：Windows超时

问题: logger测试在Windows上超时

解决: 这是已知问题，不影响功能。可忽略或标记为skip。

---

七、自动化脚本

7.1 合并脚本

#!/bin/bash
# merge-upstream.sh

set -e

echo "=== 开始合并官方仓库 ==="
date

# 1. 检查工作区状态
if [ -n "$(git status --porcelain)" ]; then
    echo "错误: 工作区有未提交的更改"
    exit 1
fi

# 2. 拉取官方更新
echo "拉取官方更新..."
git fetch upstream

# 3. 显示更新内容
echo "官方更新内容:"
git log HEAD..upstream/main --oneline

# 4. 执行合并
echo "执行合并..."
git merge upstream/main -m "Merge upstream/main $(date +%Y-%m-%d)"

# 5. 验证编译
echo "验证后端编译..."
cd backend && go build ./cmd/server

# 6. 验证JSON
echo "验证JSON格式..."
python -c "import json; json.load(open('resources/model-pricing/model_prices_and_context_window.json', encoding='utf-8'))"

echo "=== 合并完成 ==="

7.2 定价更新检查脚本

#!/bin/bash
# check-pricing.sh

echo "检查国内模型定价更新..."

# 定义厂商和URL
declare -A PRICING_URLS=(
    ["智谱GLM"]="https://open.bigmodel.cn/pricing"
    ["通义千问"]="https://help.aliyun.com/zh/dashscope/developer-reference/tongyi-qianwen"
    ["Moonshot"]="https://platform.moonshot.cn/docs/pricing/chat"
    ["MiniMax"]="https://platform.minimaxi.com/pricing"
    ["豆包"]="https://www.volcengine.com/docs/82379/1290310"
    ["DeepSeek"]="https://api-docs.deepseek.com/quick_start/pricing"
    ["百川"]="https://platform.baichuan-ai.com/prices"
    ["硅基流动"]="https://siliconflow.cn/pricing"
)

for name url in "${!PRICING_URLS[@]}"; do
    echo "- [$name] $url"
done

echo "请手动检查以上页面获取最新定价"

---

八、合并后发布

8.1 提交变更

git add .
git commit -m "Merge upstream/main $(date +%Y-%m-%d)

- 合并官方最新更新
- 保留国内模型定价配置
- 更新URL白名单
"

8.2 推送到远程

git push origin main

8.3 创建标签

git tag -a v$(date +%Y.%m.%d) -m "Weekly merge $(date +%Y-%m-%d)"
git push origin v$(date +%Y.%m.%d)

---

九、回滚方案

9.1 合并前回滚

# 如果合并还没完成
git merge --abort

9.2 合并后回滚

# 找到合并前的commit
git log --oneline -5

# 回滚到合并前
git reset --hard <commit-hash>

# 或使用revert
git revert -m 1 HEAD

9.3 使用备份恢复

# 从备份分支恢复
git checkout backup/20260415
git checkout -b main-restore
git branch -D main
git branch -m main-restore main

---

十、检查清单

合并完成后，使用此清单确认所有步骤：

• 官方代码已合并
• 国内模型定价数据完整
• URL白名单配置完整
• 后端编译通过
• 前端构建通过
• 测试运行通过（忽略已知问题）
• 变更已提交
• 已推送到远程仓库
• 已创建版本标签
• 更新文档记录

---

十一、联系与支持

如有问题，请检查：

1. 官方仓库: https://github.com/sub2api/sub2api
2. 本地仓库: https://github.com/Wei-Shaw/sub2api
3. 审查报告目录: docs/reviews/

---

文档版本: 1.0 最后更新: 2026-04-15 维护者: Claude Code AI