228 lines
10 KiB
Markdown
228 lines
10 KiB
Markdown
# CLIProxyAPI 升级、构建与部署记录
|
||
|
||
## 当前基线
|
||
|
||
| 项目 | 当前值 |
|
||
|---|---|
|
||
| CLIProxyAPI Tag | `v7.2.135` |
|
||
| submodule 提交 | `ee2c494788f8a089c58f7ae9aa6ebd1b422211cb` |
|
||
| patched 构建版本 | `v7.2.135-dev` |
|
||
| Native ABI | `1` |
|
||
| RPC schema | `4` |
|
||
| Go | `1.26.6` |
|
||
| 本地运行目录 | `.runtime` |
|
||
| 本地管理页面 | `http://127.0.0.1:8317/management.html` |
|
||
| 远端目录 | `root@akko.pchuan.top:/root/cpa` |
|
||
|
||
DeepSeek 必须配置在 CPA 的 `codex-api-key` 通道，`base-url` 使用 `https://api.deepseek.com`。不要把该凭证配置为 `openai-compatibility`。Windows Codex CLI 连接本地 CPA 时，provider 的 `base_url` 使用 `http://127.0.0.1:8317/v1`，`wire_api` 使用 `responses`。
|
||
|
||
当前本地测试状态保存在被 Git 忽略的 `.runtime`：
|
||
|
||
- CPA 配置：`.runtime/config.yaml`；
|
||
- billing 数据库：`.runtime/data/billing.db`；
|
||
- 管理 Key 和默认下游 Key：`000000`；
|
||
- 测试模型：`deepseek-v4-flash`；
|
||
- 默认额度：`$10`，最大并发数：`4`；
|
||
- 当前价格是本地验收价格，不作为生产价格依据。
|
||
|
||
升级宿主或插件时保留配置和数据库，不重复初始化 Key、价格和额度。
|
||
|
||
## 已知上游测试失败
|
||
|
||
CLIProxyAPI `ee2c4947` 在 Debian WSL 中运行 `go test ./... -count=1` 时有以下失败：
|
||
|
||
| 测试 | 实际值 | 期望值 |
|
||
|---|---|---|
|
||
| `TestApplyClaudeHeaders_DisableDeviceProfileStabilization` | `X-Stainless-Os=MacOS` | `Linux` |
|
||
| `TestApplyClaudeHeaders_LegacyModePreservesConfiguredUserAgentOverrideForClaudeClients` | `X-Stainless-Os=MacOS` | `Linux` |
|
||
| `TestClaudeExecutor_NonClaudeRequestUsesClaudeCode220CLIFingerprint` | `X-Stainless-Os=MacOS` | `Linux` |
|
||
|
||
2026-08-18 已在未应用任何 billing 补丁的纯上游 `ee2c4947` 临时 worktree 中复现相同结果。三项补丁没有修改 `internal/runtime/executor`，因此同一提交、同一 WSL 环境、同一失败内容再次出现时，直接记为已知上游失败，不再创建干净 worktree复测。
|
||
|
||
出现以下任一情况时重新验证：
|
||
|
||
- submodule 提交不再是 `ee2c4947`；
|
||
- 上游修改了 `internal/runtime/executor/claude_executor_test.go`、`claude_executor_request.go` 或 `helps/claude_device_profile.go`；
|
||
- 失败测试、行号、实际值或期望值发生变化；
|
||
- 三项补丁开始修改 `internal/runtime/executor`。
|
||
|
||
## submodule 升级
|
||
|
||
当前 submodule 工作区包含三项已应用补丁。升级前必须按反方向撤销，再切换上游提交：
|
||
|
||
```bash
|
||
git -C .externals/CLIProxyAPI apply --reverse ../../patch/cli-proxy-api-request-lifecycle-cancel.patch
|
||
git -C .externals/CLIProxyAPI apply --reverse ../../patch/cli-proxy-api-usage-identity.patch
|
||
git -C .externals/CLIProxyAPI apply --reverse ../../patch/cli-proxy-api-usage-context.patch
|
||
git -C .externals/CLIProxyAPI fetch --tags --prune origin
|
||
git -C .externals/CLIProxyAPI switch --detach origin/main
|
||
```
|
||
|
||
重新应用补丁：
|
||
|
||
```bash
|
||
git -C .externals/CLIProxyAPI apply ../../patch/cli-proxy-api-usage-context.patch
|
||
git -C .externals/CLIProxyAPI apply ../../patch/cli-proxy-api-usage-identity.patch
|
||
git -C .externals/CLIProxyAPI apply ../../patch/cli-proxy-api-request-lifecycle-cancel.patch
|
||
git -C .externals/CLIProxyAPI diff --check
|
||
```
|
||
|
||
应用后 submodule 显示 `dirty` 是预期结果。根仓库提交新的 gitlink 指针和必要的 `patch/` 更新，不在 submodule 中创建派生提交。
|
||
|
||
## 测试顺序
|
||
|
||
WSL 使用以下环境。Go bootstrap 可能低于 `1.26.6`，有效 toolchain 由 Go 自动下载；`gofmt` 位于有效 `GOROOT/bin`，因此需要补充 `PATH`：
|
||
|
||
```bash
|
||
export GOPROXY=https://goproxy.cn,direct
|
||
export PATH="$(go env GOROOT)/bin:$PATH"
|
||
go version
|
||
gofmt -h >/dev/null
|
||
```
|
||
|
||
从 PowerShell 调用包含 Bash 变量、命令替换或多层引号的命令时，把内容写入 `.runtime/tmp/*.sh` 后交给 WSL 执行。`.runtime/tmp` 不提交。
|
||
|
||
每次升级执行以下检查：
|
||
|
||
```bash
|
||
cd .externals/CLIProxyAPI
|
||
go test -race ./internal/pluginhost ./sdk/api/handlers ./sdk/cliproxy/usage -count=1
|
||
go test ./... -count=1
|
||
|
||
cd ../..
|
||
go test ./... -count=1
|
||
go test -race ./... -count=1
|
||
```
|
||
|
||
补丁正确性的最低标准如下：
|
||
|
||
- 三项补丁按顺序应用成功，`git diff --check` 通过；
|
||
- `internal/pluginhost`、`sdk/api/handlers`、`sdk/cliproxy/usage` race 测试通过；
|
||
- billing 全量测试和全量 race 测试通过；
|
||
- CPA 全量测试除已记录的纯上游失败外通过；
|
||
- CPA 和 billing 均可编译。
|
||
|
||
## 构建
|
||
|
||
CPA 版本必须使用当前最新 Tag 加 `-dev`，提交取 submodule HEAD：
|
||
|
||
```bash
|
||
cd .externals/CLIProxyAPI
|
||
version=v7.2.135-dev
|
||
commit="$(git rev-parse --short=8 HEAD)"
|
||
build_date="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
|
||
CGO_ENABLED=1 go build -buildvcs=false \
|
||
-ldflags="-s -w -X main.Version=$version -X main.Commit=$commit -X main.BuildDate=$build_date" \
|
||
-o ../../.runtime/bin/cli-proxy-api.new ./cmd/server/
|
||
../../.runtime/bin/cli-proxy-api.new -h >/dev/null
|
||
```
|
||
|
||
`-h` 会在第一行输出完整版本。上游没有 `--version` 参数，不要使用该参数核对版本。
|
||
|
||
构建插件：
|
||
|
||
```bash
|
||
cd ../..
|
||
bash scripts/build.sh
|
||
cp bin/billing.so .runtime/plugins/billing.so.new
|
||
sha256sum bin/billing.so .runtime/plugins/billing.so.new
|
||
```
|
||
|
||
两个插件哈希必须一致。
|
||
|
||
## 本地替换与验收
|
||
|
||
本地 CPA 只使用 `.runtime`。替换前停止进程并保存旧产物：
|
||
|
||
```bash
|
||
bash scripts/stop-test-host.sh
|
||
backup=".runtime/backups/$(date +%Y%m%d-%H%M%S)"
|
||
mkdir -p "$backup"
|
||
cp .runtime/bin/cli-proxy-api "$backup/"
|
||
cp .runtime/plugins/billing.so "$backup/"
|
||
mv .runtime/bin/cli-proxy-api.new .runtime/bin/cli-proxy-api
|
||
mv .runtime/plugins/billing.so.new .runtime/plugins/billing.so
|
||
bash scripts/run-test-host.sh
|
||
```
|
||
|
||
启动后检查：
|
||
|
||
1. `/healthz` 返回 `status=ok`；
|
||
2. `/v0/management/plugins` 中 billing 的 `registered`、`enabled`、`effective_enabled` 都为 `true`；
|
||
3. 日志版本与构建参数一致，且没有插件错误或 panic；
|
||
4. 无下游 Key 的请求返回 401；
|
||
5. 有效 billing Key 的 `/v1/responses` 请求返回 200；
|
||
6. 请求只新增一条明细，包含唯一 Request ID 和 Token；
|
||
7. 额度只扣减一次，`active_requests` 回到 0。
|
||
|
||
本地 CPA 通过 WSL localhost 转发供 Windows 使用。取消链路测试需要在 WSL 内直连 `127.0.0.1:8317`，避免 Windows localhost 转发延迟传递断开。
|
||
|
||
## 远端发布
|
||
|
||
核心升级使用 PowerShell 脚本：
|
||
|
||
```powershell
|
||
./scripts/push.ps1
|
||
```
|
||
|
||
脚本默认执行以下操作：
|
||
|
||
- fetch `origin/main` 并要求 submodule HEAD 与其一致；
|
||
- 要求 submodule 修改文件集合与 `patch/*.patch` 声明一致；
|
||
- 运行三个补丁相关包的 race 测试；
|
||
- 使用最新 Tag 加 `-dev` 和当前提交、构建时间编译核心；
|
||
- 生成 gzip 最高压缩级别的核心包和 SHA-256；
|
||
- 上传后在远端重新校验压缩包、版本和核心哈希；
|
||
- 等待 billing `active_requests=0`，备份后只替换 CPA 核心；
|
||
- 核对配置、所有插件动态库、插件注册状态和独立 keeper；
|
||
- 失败时恢复旧核心并按部署前状态启动 CPA Manager Plus。
|
||
|
||
只执行本地构建、测试和打包，不上传或部署：
|
||
|
||
```powershell
|
||
./scripts/push.ps1 -WhatIf
|
||
```
|
||
|
||
复用已有核心时使用 `-SkipBuild -BinaryPath <path>`；跳过补丁相关 race 测试使用 `-SkipTests`；部署锁定但不是当前 `origin/main` 的提交时显式使用 `-SkipUpstreamCheck`。请求排空默认等待 120 秒，可通过 `-DrainTimeoutSeconds` 和 `-DrainPollSeconds` 调整。
|
||
|
||
远端只部署本项目的 billing 和已要求启用的 keeper。发布步骤如下：
|
||
|
||
1. 本地完成真实模型请求、协议、计费和取消链路验收；
|
||
2. 对 CPA 二进制和插件计算 SHA-256；
|
||
3. 使用 gzip、tar.gz 或 `scp -C` 上传；
|
||
4. 停止 `/root/cpa/cpa.sh` 管理的进程；
|
||
5. 把旧 CPA、billing、keeper 和 `data/cpa-ext.db*` 保存到 `/root/cpa/backups/<timestamp>/`；
|
||
6. 替换二进制和插件，保留配置及 secret 文件；
|
||
7. 启动进程并检查健康状态、版本、插件注册状态和日志；
|
||
8. 启动失败时恢复同一备份目录中的文件并重启。
|
||
|
||
远端不发送 `/v1/responses`、`/v1/chat/completions` 或 compact 请求。管理密钥和下游 Key 在远端脚本内部从 secret 文件或管理 API 读取，不输出到终端和普通日志。
|
||
|
||
`cpa.sh start` 会先把管理 Key 同步到 `config.yaml`，CPA 启动后会重新保存该字段的哈希，因此每次启动后 `config.yaml` 的原始 SHA-256 可能变化。部署校验应把 `remote-management.secret-key` 的值归一化后比较其余配置内容，不得因为原始配置哈希变化回滚核心。
|
||
|
||
远端存在持续请求时，在远端部署脚本内部先完成压缩包和插件检查，再每 5 秒读取 billing `active_requests`。检测到 0 后立即停止 CPA，避免在本地轮询与远端执行之间出现新请求。
|
||
|
||
## 2026-08-18 验证记录
|
||
|
||
`v7.2.135` / `ee2c4947` 已完成以下验证：
|
||
|
||
- 三项补丁重新应用成功，共修改 11 个文件，增加 289 行，删除 10 行；
|
||
- 补丁相关三个包的 race 测试通过；
|
||
- billing 全量测试和全量 race 测试通过；
|
||
- CPA 和 billing Linux amd64 产物编译成功；
|
||
- CPA 运行版本为 `v7.2.135-dev / ee2c4947`；
|
||
- billing `0.1.0` 加载并注册；
|
||
- DeepSeek Codex `/v1/responses` 返回 200 和 `CODEX_READY`；
|
||
- 该请求记录 129 Token，只产生一条计费记录，`active_requests=0`；
|
||
- 本地替换前产物保存在 `.runtime/backups/20260818-154252-v7.2.135/`。
|
||
|
||
同日已完成远端核心升级：
|
||
|
||
- 只替换 `/root/cpa/bin/cli-proxy-api`，插件、配置、数据库和独立 keeper 未替换；
|
||
- 远端运行版本为 `v7.2.135-dev / ee2c4947`，核心 SHA-256 为 `d702d8d65a06911b5bec78476d84e228bcfb57e03c511b4c1d89df8f460c41fd`；
|
||
- CPA PID 为 `278177`，独立 keeper PID 保持为 `230299`；
|
||
- billing 和 keeper `0.1.0` 均已加载、注册和启用；
|
||
- `/healthz` 正常，启动日志没有 panic 或插件错误；
|
||
- 未向远端模型端点发送验收请求；
|
||
- 升级前文件保存在 `/root/cpa/backups/20260818T081102Z-core-v7.2.135/`。
|