tokens-reef/docs/MERGE_GUIDE.md

# 官方版本合并指南

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

---

## 一、合并前准备

### 1.1 环境检查

```bash
# 确认当前分支状态
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 添加官方仓库（首次）

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

### 1.3 备份当前工作

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

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

---

## 二、合并流程

### 2.1 标准合并步骤

```bash
# 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保持线性历史（可选）

```bash
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白名单域名

```go
// 国内模型 - 月之暗面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 编译验证

```bash
cd backend

# Go编译
go build ./cmd/server

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

### 4.2 测试验证

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

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

### 4.3 JSON格式验证

```bash
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 检查官方定价更新

```bash
# 查看定价文件变化
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文件

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

**解决**:
```bash
# 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

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

**解决**:
```bash
# 1. 查看差异
git diff HEAD upstream/main -- backend/internal/service/billing_service.go

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

### 6.3 合并冲突：config.go

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

**解决**:
```bash
# 保留本地URL白名单配置
# 合并官方新增配置项
```

### 6.4 测试失败：Windows超时

**问题**: logger测试在Windows上超时

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

---

## 七、自动化脚本

### 7.1 合并脚本

```bash
#!/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 定价更新检查脚本

```bash
#!/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 提交变更

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

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

### 8.2 推送到远程

```bash
git push origin main
```

### 8.3 创建标签

```bash
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 合并前回滚

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

### 9.2 合并后回滚

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

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

# 或使用revert
git revert -m 1 HEAD
```

### 9.3 使用备份恢复

```bash
# 从备份分支恢复
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