From 954c0baeab5738f5bcaf54ebcf87ce626b2add52 Mon Sep 17 00:00:00 2001 From: chuan Date: Tue, 18 Aug 2026 16:21:05 +0800 Subject: [PATCH] chore: upgrade CPA baseline and automate core deployment --- .externals/CLIProxyAPI | 2 +- AGENTS.md | 4 +- README.md | 4 +- docs/dev.md | 2 + docs/operations.md | 227 +++++++++++++++++++ patch/README.md | 12 +- scripts/package.sh | 2 +- scripts/push.ps1 | 478 +++++++++++++++++++++++++++++++++++++++++ 8 files changed, 719 insertions(+), 12 deletions(-) create mode 100644 docs/operations.md create mode 100644 scripts/push.ps1 diff --git a/.externals/CLIProxyAPI b/.externals/CLIProxyAPI index 7efe0a7..ee2c494 160000 --- a/.externals/CLIProxyAPI +++ b/.externals/CLIProxyAPI @@ -1 +1 @@ -Subproject commit 7efe0a7c11adfecb7fe82f2d1128f873a9f4cbf3 +Subproject commit ee2c494788f8a089c58f7ae9aa6ebd1b422211cb diff --git a/AGENTS.md b/AGENTS.md index 92c4835..3dd9d6c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -34,8 +34,8 @@ - 本地 CPA 在 WSL 中运行，项目运行目录统一使用 `cpa-plugin/.runtime`；Windows 客户端经 `127.0.0.1` 访问 WSL 时，localhost 转发层可能不会立即向 CPA 传递客户端断开，取消链路测试优先在 WSL 内直连执行。 - 从 PowerShell 跨 WSL 或 SSH 执行包含 Bash 变量、命令替换或多层引号的逻辑时，优先在 `.runtime/tmp/` 创建临时脚本后传入目标环境执行，不拼接复杂的单行 shell；临时脚本不提交。 -- CLIProxyAPI `v7.2.133` 的宿主补丁保存在 `patch/`，必须按 `usage-context`、`usage-identity`、`request-lifecycle-cancel` 的顺序应用；升级 CPA 后先复测补丁是否仍有必要。 -- 构建本项目 patched CPA 时必须按上游 release workflow 使用 `-ldflags` 注入 `main.Version`、`main.Commit` 和 `main.BuildDate`。`Version` 固定使用“当前上游最新 tag + `-dev`”格式（例如 `v7.2.133-dev`），用于明确区分官方 Release 与本项目补丁构建；不得发布只显示 `dev`、`none` 或 `unknown` 的产物。上传前先在本地执行二进制并核对完整版本输出。 +- CLIProxyAPI 宿主补丁保存在 `patch/`，当前已验证基线为 `v7.2.135` / `ee2c4947`，必须按 `usage-context`、`usage-identity`、`request-lifecycle-cancel` 的顺序应用；升级 CPA 后按 `docs/operations.md` 核对补丁和已知上游测试例外。 +- 构建本项目 patched CPA 时必须按上游 release workflow 使用 `-ldflags` 注入 `main.Version`、`main.Commit` 和 `main.BuildDate`。`Version` 固定使用“当前上游最新 tag + `-dev`”格式（例如 `v7.2.135-dev`），用于明确区分官方 Release 与本项目补丁构建；不得发布只显示 `dev`、`none` 或 `unknown` 的产物。上传前先在本地执行二进制并核对完整版本输出。 - CPA Linux 可执行文件解压后约 60 MiB，`gzip -9` 后约 20 MiB。上传远端时使用 gzip/tar.gz 或 `scp -C`，不要直接传输未压缩二进制；部署后的运行文件仍需解压为原始可执行文件。 - 实际服务器为 `root@akko.pchuan.top`，CPA 根目录为 `/root/cpa`。只维护本项目的 `billing` 和已要求启用的 `keeper`，不启用或部署其他参考插件。 - 远端替换 CPA 或 billing 前，先停止 `/root/cpa/cpa.sh` 管理的进程，并把旧二进制、插件和 `data/cpa-ext.db*` 备份到 `/root/cpa/backups//`；新版本启动失败时恢复旧二进制和插件。 diff --git a/README.md b/README.md index a2f0099..aeaa27a 100644 --- a/README.md +++ b/README.md @@ -66,7 +66,7 @@ CLIProxyAPI 负责 HTTP 接入、协议转换、上游凭证和实际请求执 ## 当前兼容目标 -- CLIProxyAPI 基线：`v7.2.132` / `78f0c4079e3e6273d65d03b5549cffc898703264`，由 `.externals/CLIProxyAPI` submodule 锁定，需依次应用 `patch/` 中三项宿主补丁 +- CLIProxyAPI 基线：`v7.2.135` / `ee2c494788f8a089c58f7ae9aa6ebd1b422211cb`，由 `.externals/CLIProxyAPI` submodule 锁定，需依次应用 `patch/` 中三项宿主补丁 - 插件版本：`0.1.0` - Native ABI：`1` - RPC schema：最高 `4`，注册时按宿主版本向下协商；schema v4 提供 Usage 请求身份 @@ -141,7 +141,7 @@ CGO_ENABLED=1 go test ./... 请求明细由服务端分页，每页 100 条，默认按请求时间和稳定 ID 倒序展示。管理接口支持时间范围、用户 Key、模型、结果、上游 Auth ID、端点和完整 Request ID 筛选；连续翻页使用与筛选条件绑定的游标，数字页码跳转使用 SQLite 索引定位。用户页的今日汇总、各用户用量和近 7 日 Token 由数据库独立聚合，不受当前明细页影响。 -升级已有数据库时，插件会从原始 Usage 和请求终态事实自动建立轻量查询投影。事实表、计费账目和历史统计保持不变；没有 Usage 的取消或失败请求仍然可见。当前 CPA Usage 契约不提供 Request ID 或 Execution ID，因此只在模型和时间足够接近且匹配关系唯一时关联请求终态；存在并发歧义时保留为独立记录，不强行合并。 +升级已有数据库时，插件会从原始 Usage 和请求终态事实自动建立轻量查询投影。事实表、计费账目和历史统计保持不变；没有 Usage 的取消或失败请求仍然可见。patched CPA 使用 RPC schema v4 向 billing 传递 Usage Request ID 和 Trace ID，可以按 Request ID 精确关联请求终态。旧宿主或旧 schema 没有请求身份时，只有模型和时间足够接近且匹配关系唯一才关联；存在并发歧义时保留为独立记录。 ## 工程布局 diff --git a/docs/dev.md b/docs/dev.md index deaa86c..db01c9a 100644 --- a/docs/dev.md +++ b/docs/dev.md @@ -8,6 +8,8 @@ git submodule update --init --recursive 需要构建本项目使用的 CPA 时，再按 [`../patch/README.md`](../patch/README.md) 的顺序应用三个宿主补丁。submodule 本身始终锁定官方基线，补丁来源以根仓库 `patch/` 为准。 +升级 submodule、构建宿主、本地替换、验收和远端发布使用 [`operations.md`](operations.md)。该文档同时记录已确认的上游测试失败及免复测条件。 + 开发按依赖从少到多推进：先确定数据和规则，再实现存储与服务，最后接入外部协议和界面。核心逻辑不依赖框架类型，协议转换集中在边界层。涉及持久化时，先定义迁移和历史数据语义 开发的核心在于每一步的可预见性与可测试性 diff --git a/docs/operations.md b/docs/operations.md new file mode 100644 index 0000000..49074fb --- /dev/null +++ b/docs/operations.md @@ -0,0 +1,227 @@ +# 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 `；跳过补丁相关 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//`； +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/`。 diff --git a/patch/README.md b/patch/README.md index 846abe7..c645143 100644 --- a/patch/README.md +++ b/patch/README.md @@ -1,6 +1,6 @@ # CLIProxyAPI 宿主补丁 -这里保存 billing 在 CLIProxyAPI `v7.2.133` 上需要的三项宿主修复。三项补丁都不改变计费规则或数据库结构，必须按下列顺序应用： +这里保存 billing 最初为 CLIProxyAPI `v7.2.133` 制作、已在 `v7.2.135` 重新验证的三项宿主修复。三项补丁都不改变计费规则或数据库结构，必须按下列顺序应用： 1. [`cli-proxy-api-usage-context.patch`](cli-proxy-api-usage-context.patch) 2. [`cli-proxy-api-usage-identity.patch`](cli-proxy-api-usage-identity.patch) @@ -8,8 +8,8 @@ 适用基线： -- CLIProxyAPI：`v7.2.133` -- 提交：`7efe0a7c11adfecb7fe82f2d1128f873a9f4cbf3` +- CLIProxyAPI：`v7.2.135` +- 提交：`ee2c494788f8a089c58f7ae9aa6ebd1b422211cb` - Native ABI：`1` - 第二项补丁把 RPC schema 从 `3` 提升到 `4` @@ -84,8 +84,8 @@ git -C .externals/CLIProxyAPI apply ../../patch/cli-proxy-api-request-lifecycle- cd .externals/CLIProxyAPI gofmt -w internal/pluginhost sdk/api/handlers sdk/cliproxy/usage sdk/pluginabi sdk/pluginapi go test -race ./internal/pluginhost ./sdk/api/handlers ./sdk/cliproxy/usage -count=1 -version=v7.2.133-dev -commit=7efe0a7c +version=v7.2.135-dev +commit=ee2c4947 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" \ @@ -129,7 +129,7 @@ billing 必须使用 RPC schema v4 重新构建；旧 billing 动态库会向下 - billing 全部测试、billing race 测试及 CLIProxyAPI 相关包 race 测试通过； - schema v3 对照插件仍能正常注册，新增字段不会发送给旧 schema。 -升级到 CLIProxyAPI `v7.2.133` 后，三项补丁可从干净基线按顺序重放，补丁涉及的三个包及其 race 测试、billing 全仓 race 测试和两个 Linux amd64 产物构建均通过。宿主全仓 `go test ./...` 只剩 2 个与补丁无关的 `reviewedInPlaceByteWrites` 陈旧清单失败：`internal/home/client.go` 和 `internal/pluginstore/auth.go` 已不再包含清单记录的原地 byte 写入。 +升级到 CLIProxyAPI `v7.2.135` / `ee2c4947` 后，三项补丁可从干净基线按顺序重放，补丁涉及的三个包及其 race 测试、billing 全仓 race 测试和两个 Linux amd64 产物构建均通过。宿主全仓 `go test ./...` 有 3 个与补丁无关的 Claude 指纹测试失败；相同失败已在未应用补丁的纯上游 `ee2c4947` 上复现，详见 [`../docs/operations.md`](../docs/operations.md)。 ## 性能影响 diff --git a/scripts/package.sh b/scripts/package.sh index 58d1a08..63fed79 100755 --- a/scripts/package.sh +++ b/scripts/package.sh @@ -30,7 +30,7 @@ printf '%s\n' \ "target=linux/amd64" \ "native_abi=1" \ "rpc_schema=4" \ - "cliproxyapi_revision=78f0c4079e3e6273d65d03b5549cffc898703264+usage-context+usage-identity+request-lifecycle-cancel" \ + "cliproxyapi_revision=ee2c494788f8a089c58f7ae9aa6ebd1b422211cb+usage-context+usage-identity+request-lifecycle-cancel" \ >"$package_dir/VERSION.txt" archive="$root/dist/$name.tar.gz" diff --git a/scripts/push.ps1 b/scripts/push.ps1 new file mode 100644 index 0000000..8a2811d --- /dev/null +++ b/scripts/push.ps1 @@ -0,0 +1,478 @@ +[CmdletBinding(SupportsShouldProcess)] +param( + [string]$SshTarget = 'root@akko.pchuan.top', + [string]$RemoteRoot = '/root/cpa', + [string]$WslDistribution = 'Debian', + [int]$DrainTimeoutSeconds = 120, + [int]$DrainPollSeconds = 5, + [string]$BinaryPath = '', + [switch]$SkipBuild, + [switch]$SkipTests, + [switch]$SkipUpstreamCheck +) + +$ErrorActionPreference = 'Stop' +Set-StrictMode -Version Latest + +function Resolve-RequiredTool { + param([Parameter(Mandatory)][string]$Name) + + $command = Get-Command $Name -ErrorAction SilentlyContinue + if ($null -eq $command) { + throw "Required tool is missing from PATH: $Name" + } + return $command.Source +} + +function Invoke-NativeCommand { + param( + [Parameter(Mandatory)][string]$FilePath, + [Parameter(Mandatory)][string[]]$ArgumentList + ) + + & $FilePath @ArgumentList + if ($LASTEXITCODE -ne 0) { + throw "Command failed with exit code $LASTEXITCODE`: $FilePath $($ArgumentList -join ' ')" + } +} + +function Get-NativeOutput { + param( + [Parameter(Mandatory)][string]$FilePath, + [Parameter(Mandatory)][string[]]$ArgumentList + ) + + $output = & $FilePath @ArgumentList 2>&1 + if ($LASTEXITCODE -ne 0) { + throw "Command failed with exit code $LASTEXITCODE`: $FilePath $($ArgumentList -join ' ')`n$($output -join "`n")" + } + return (($output -join "`n").Trim()) +} + +function Write-Utf8NoBom { + param( + [Parameter(Mandatory)][string]$Path, + [Parameter(Mandatory)][string]$Content + ) + + $encoding = [System.Text.UTF8Encoding]::new($false) + [System.IO.File]::WriteAllText($Path, ($Content -replace "`r`n", "`n"), $encoding) +} + +if ($DrainTimeoutSeconds -lt 0) { + throw 'DrainTimeoutSeconds must be zero or greater.' +} +if ($DrainPollSeconds -lt 1) { + throw 'DrainPollSeconds must be at least one second.' +} +if ($SshTarget -notmatch '^[A-Za-z0-9_.@-]+$') { + throw "Unsupported SSH target format: $SshTarget" +} +if ($RemoteRoot -notmatch '^/[A-Za-z0-9._/-]+$') { + throw "Unsupported remote root format: $RemoteRoot" +} +if ($WslDistribution -notmatch '^[A-Za-z0-9._-]+$') { + throw "Unsupported WSL distribution name: $WslDistribution" +} + +$git = Resolve-RequiredTool 'git' +$ssh = Resolve-RequiredTool 'ssh' +$scp = Resolve-RequiredTool 'scp' +$wsl = Resolve-RequiredTool 'wsl.exe' + +$repoRoot = (Resolve-Path -LiteralPath (Join-Path $PSScriptRoot '..')).Path +$hostRoot = Join-Path $repoRoot '.externals\CLIProxyAPI' +$runtimeRoot = Join-Path $repoRoot '.runtime' +$tmpRoot = Join-Path $runtimeRoot 'tmp' +$deployRoot = Join-Path $runtimeRoot 'deploy' + +if (-not (Test-Path -LiteralPath $hostRoot -PathType Container)) { + throw "CLIProxyAPI submodule is missing: $hostRoot" +} + +[System.IO.Directory]::CreateDirectory($tmpRoot) | Out-Null +[System.IO.Directory]::CreateDirectory($deployRoot) | Out-Null + +Push-Location $repoRoot +try { + if (-not $SkipUpstreamCheck) { + Invoke-NativeCommand $git @('-C', $hostRoot, 'fetch', '--tags', '--prune', 'origin') + } + + $head = Get-NativeOutput $git @('-C', $hostRoot, 'rev-parse', 'HEAD') + if (-not $SkipUpstreamCheck) { + $originMain = Get-NativeOutput $git @('-C', $hostRoot, 'rev-parse', 'origin/main') + if ($head -ne $originMain) { + throw "Submodule HEAD is not origin/main. HEAD=$head origin/main=$originMain" + } + } + + $tag = Get-NativeOutput $git @('-C', $hostRoot, 'describe', '--tags', '--abbrev=0', $head) + $commit = Get-NativeOutput $git @('-C', $hostRoot, 'rev-parse', '--short=8', $head) + $version = "$tag-dev" + $buildDate = [DateTime]::UtcNow.ToString('yyyy-MM-ddTHH:mm:ssZ') + + foreach ($value in @($tag, $version, $commit)) { + if ($value -notmatch '^[A-Za-z0-9._+-]+$') { + throw "Unsupported version value: $value" + } + } + + Invoke-NativeCommand $git @('-C', $hostRoot, 'diff', '--check') + + $expectedModifiedFiles = Get-ChildItem -LiteralPath (Join-Path $repoRoot 'patch') -Filter '*.patch' | + Select-String -Pattern '^diff --git a/([^ ]+) b/' | + ForEach-Object { $_.Matches[0].Groups[1].Value } | + Sort-Object -Unique + $actualModifiedFiles = Get-NativeOutput $git @('-C', $hostRoot, 'diff', '--name-only') | + ForEach-Object { $_ -split "`n" } | + Where-Object { -not [string]::IsNullOrWhiteSpace($_) } | + ForEach-Object { $_.Trim() } | + Sort-Object -Unique + $untrackedHostFiles = Get-NativeOutput $git @('-C', $hostRoot, 'ls-files', '--others', '--exclude-standard') + if (-not [string]::IsNullOrWhiteSpace($untrackedHostFiles)) { + throw "CLIProxyAPI worktree contains untracked files:`n$untrackedHostFiles" + } + $unexpectedChanges = Compare-Object -ReferenceObject $expectedModifiedFiles -DifferenceObject $actualModifiedFiles + if ($unexpectedChanges) { + $details = $unexpectedChanges | ForEach-Object { "$($_.SideIndicator) $($_.InputObject)" } + throw "CLIProxyAPI worktree does not match the files declared by patch/*.patch:`n$($details -join "`n")" + } + + $wslRepoRoot = Get-NativeOutput $wsl @('-d', $WslDistribution, '--', 'wslpath', '-a', ($repoRoot -replace '\\', '/')) + $archiveName = "cli-proxy-api-$version-$commit-linux-amd64.tar.gz" + $archivePath = Join-Path $deployRoot $archiveName + $checksumPath = "$archivePath.sha256" + $wslArchivePath = "$wslRepoRoot/.runtime/deploy/$archiveName" + + if ($SkipBuild) { + if ([string]::IsNullOrWhiteSpace($BinaryPath)) { + $BinaryPath = Join-Path $runtimeRoot 'bin\cli-proxy-api' + } + $resolvedBinary = (Resolve-Path -LiteralPath $BinaryPath).Path + $wslBinaryPath = Get-NativeOutput $wsl @('-d', $WslDistribution, '--', 'wslpath', '-a', ($resolvedBinary -replace '\\', '/')) + $buildMode = '0' + } else { + $resolvedBinary = Join-Path $deployRoot "cli-proxy-api-$version-$commit" + $wslBinaryPath = "$wslRepoRoot/.runtime/deploy/cli-proxy-api-$version-$commit" + $buildMode = '1' + } + + $runTests = if ($SkipTests) { '0' } else { '1' } + $localScriptPath = Join-Path $tmpRoot 'push-build-core.sh' + $localScript = @" +#!/usr/bin/env bash +set -euo pipefail + +root='$wslRepoRoot' +host="`$root/.externals/CLIProxyAPI" +binary='$wslBinaryPath' +archive='$wslArchivePath' +version='$version' +commit='$commit' +build_date='$buildDate' +build_mode='$buildMode' +run_tests='$runTests' + +export GOPROXY=https://goproxy.cn,direct +export PATH="`$(go env GOROOT)/bin:`$PATH" + +if [[ "`$build_mode" == 1 ]]; then + cd "`$host" + git diff --check + if [[ "`$run_tests" == 1 ]]; then + go test -race ./internal/pluginhost ./sdk/api/handlers ./sdk/cliproxy/usage -count=1 + fi + CGO_ENABLED=1 go build -buildvcs=false \ + -ldflags="-s -w -X main.Version=`$version -X main.Commit=`$commit -X main.BuildDate=`$build_date" \ + -o "`$binary" ./cmd/server/ +fi + +test -f "`$binary" +chmod 0755 "`$binary" +help_output="`$("`$binary" -h 2>&1)" +first_line="`${help_output%%`$'\n'*}" +expected_prefix="CLIProxyAPI Version: `$version, Commit: `$commit, BuiltAt: " +[[ "`$first_line" == "`$expected_prefix"* ]] + +stage="`$(mktemp -d)" +trap 'rm -rf "`$stage"' EXIT +install -m 0755 "`$binary" "`$stage/cli-proxy-api" +tar -C "`$stage" -cf - cli-proxy-api | gzip -9 >"`$archive" +( + cd "`$(dirname "`$archive")" + sha256sum "`$(basename "`$archive")" >"`$(basename "`$archive").sha256" +) + +printf 'version_line=%s\n' "`$first_line" +sha256sum "`$binary" "`$archive" +stat -c 'archive_size=%s' "`$archive" +"@ + Write-Utf8NoBom -Path $localScriptPath -Content $localScript + + Write-Host "Preparing $version / $commit" + $wslLocalScriptPath = Get-NativeOutput $wsl @('-d', $WslDistribution, '--', 'wslpath', '-a', ($localScriptPath -replace '\\', '/')) + Invoke-NativeCommand $wsl @('-d', $WslDistribution, '--', 'bash', $wslLocalScriptPath) + + if (-not (Test-Path -LiteralPath $archivePath -PathType Leaf)) { + throw "Archive was not created: $archivePath" + } + if (-not (Test-Path -LiteralPath $checksumPath -PathType Leaf)) { + throw "Checksum file was not created: $checksumPath" + } + + $binaryHash = (Get-FileHash -Algorithm SHA256 -LiteralPath $resolvedBinary).Hash.ToLowerInvariant() + $archiveHash = (Get-FileHash -Algorithm SHA256 -LiteralPath $archivePath).Hash.ToLowerInvariant() + + $remoteScriptPath = Join-Path $tmpRoot 'push-remote-core.sh' + $remoteScript = @' +#!/usr/bin/env bash +set -euo pipefail + +archive_name="$1" +expected_archive_hash="$2" +expected_binary_hash="$3" +expected_version="$4" +expected_commit="$5" +drain_timeout="$6" +drain_poll="$7" +root="$8" + +archive="$root/upload/$archive_name" +checksum="$archive.sha256" +cpa_script="$root/cpa.sh" +tmp='' +backup='' +rollback_needed=0 +manager_was_running=0 +keeper_pid='' + +start_services() { + if [[ "$manager_was_running" -eq 1 ]]; then + "$cpa_script" start --plus + else + "$cpa_script" start + fi +} + +finish() { + rc=$? + trap - EXIT + if [[ "$rc" -ne 0 && "$rollback_needed" -eq 1 ]]; then + printf 'DEPLOYMENT_FAILED_ROLLING_BACK\n' + "$cpa_script" stop || true + if [[ -n "$backup" && -f "$backup/bin/cli-proxy-api" ]]; then + install -o root -g root -m 0755 "$backup/bin/cli-proxy-api" "$root/bin/cli-proxy-api" + fi + start_services || true + fi + if [[ -n "$tmp" && -d "$tmp" ]]; then + rm -rf "$tmp" + fi + exit "$rc" +} +trap finish EXIT + +printf 'VERIFY_UPLOAD\n' +test -f "$archive" +test -f "$checksum" +actual_archive_hash="$(sha256sum "$archive" | awk '{print $1}')" +test "$actual_archive_hash" = "$expected_archive_hash" +( + cd "$root/upload" + sha256sum -c "$(basename "$checksum")" +) +test "$(tar -tzf "$archive")" = 'cli-proxy-api' + +available_kb="$(df -Pk "$root" | awk 'NR==2 {print $4}')" +test "$available_kb" -ge 262144 + +tmp="$(mktemp -d "$root/.deploy-core.XXXXXX")" +tar -xzf "$archive" -C "$tmp" +test -f "$tmp/cli-proxy-api" +test ! -L "$tmp/cli-proxy-api" +chmod 0755 "$tmp/cli-proxy-api" +test "$(sha256sum "$tmp/cli-proxy-api" | awk '{print $1}')" = "$expected_binary_hash" +help_output="$("$tmp/cli-proxy-api" -h 2>&1)" +first_line="${help_output%%$'\n'*}" +expected_prefix="CLIProxyAPI Version: $expected_version, Commit: $expected_commit, BuiltAt: " +[[ "$first_line" == "$expected_prefix"* ]] +printf '%s\n' "$first_line" + +printf 'PREFLIGHT\n' +curl -fsS http://127.0.0.1:8317/healthz >/dev/null +admin="$(cat "$root/secrets/cpa-management-key")" +curl -fsS -H "Authorization: Bearer $admin" \ + http://127.0.0.1:8317/v0/management/plugins >"$tmp/plugins-before.json" + +python3 - "$tmp/plugins-before.json" "$tmp/plugins-before.normalized.json" <<'PY' +import json +import sys + +source, target = sys.argv[1:] +payload = json.load(open(source, encoding="utf-8")) +items = [] +for plugin in payload.get("plugins", []): + item = { + "id": plugin.get("id"), + "path": plugin.get("path"), + "version": (plugin.get("metadata") or {}).get("version"), + "registered": plugin.get("registered"), + "enabled": plugin.get("enabled"), + "effective_enabled": plugin.get("effective_enabled"), + } + if not all((item["registered"], item["enabled"], item["effective_enabled"])): + raise SystemExit(f"plugin preflight failed: {item}") + items.append(item) +items.sort(key=lambda value: value["id"] or "") +with open(target, "w", encoding="utf-8") as handle: + json.dump(items, handle, sort_keys=True, separators=(",", ":")) +print(f"plugins={len(items)}") +PY + +if [[ -s "$root/run/manager.pid" ]] && kill -0 "$(cat "$root/run/manager.pid")" 2>/dev/null; then + manager_was_running=1 +fi +if [[ -s "$root/keeper/run/keeper.pid" ]] && kill -0 "$(cat "$root/keeper/run/keeper.pid")" 2>/dev/null; then + keeper_pid="$(cat "$root/keeper/run/keeper.pid")" +fi + +attempts=$((drain_timeout / drain_poll + 1)) +active=-1 +for attempt in $(seq 1 "$attempts"); do + curl -fsS -H "Authorization: Bearer $admin" \ + http://127.0.0.1:8317/v0/management/plugins/billing/keys >"$tmp/keys-before.json" + active="$(python3 - "$tmp/keys-before.json" <<'PY' +import json +import sys + +keys = json.load(open(sys.argv[1], encoding="utf-8")).get("keys", []) +print(sum(int((item.get("billing") or {}).get("active_requests") or 0) for item in keys)) +PY +)" + printf 'drain_attempt=%s active_requests=%s\n' "$attempt" "$active" + if [[ "$active" -eq 0 ]]; then + break + fi + if [[ "$attempt" -lt "$attempts" ]]; then + sleep "$drain_poll" + fi +done +test "$active" -eq 0 + +backup="$root/backups/$(date -u +%Y%m%dT%H%M%SZ)-core-$expected_version" +mkdir "$backup" +mkdir -p "$backup/bin" "$backup/data" + +printf 'STOP_AND_BACKUP\n' +rollback_needed=1 +"$cpa_script" stop + +cp -a "$root/bin/cli-proxy-api" "$backup/bin/cli-proxy-api" +cp -a "$root/plugins" "$backup/plugins" +cp -a "$root/config.yaml" "$backup/config.yaml" +find "$root/data" -maxdepth 1 -type f \ + \( -name 'billing.db*' -o -name 'cpa-ext.db*' \) \ + -exec cp -a -t "$backup/data" {} + + +( + cd "$root" + find plugins -type f -name '*.so' -print0 | sort -z | xargs -0 sha256sum +) >"$backup/plugins.sha256" +sed -E 's/^([[:space:]]+secret-key:).*/\1 /' \ + "$root/config.yaml" >"$backup/config.normalized.yaml" +cp "$tmp/plugins-before.normalized.json" "$backup/plugins.normalized.json" +sha256sum "$backup/bin/cli-proxy-api" >"$backup/old-core.sha256" +sha256sum "$archive" >"$backup/new-archive.sha256" + +printf 'INSTALL_CORE\n' +install -o root -g root -m 0755 "$tmp/cli-proxy-api" "$root/bin/cli-proxy-api.new" +test "$(sha256sum "$root/bin/cli-proxy-api.new" | awk '{print $1}')" = "$expected_binary_hash" +mv -f "$root/bin/cli-proxy-api.new" "$root/bin/cli-proxy-api" + +printf 'START_AND_VERIFY\n' +start_services +curl -fsS http://127.0.0.1:8317/healthz >/dev/null + +help_output="$("$root/bin/cli-proxy-api" -h 2>&1)" +first_line="${help_output%%$'\n'*}" +[[ "$first_line" == "$expected_prefix"* ]] +test "$(sha256sum "$root/bin/cli-proxy-api" | awk '{print $1}')" = "$expected_binary_hash" +(cd "$root" && sha256sum -c "$backup/plugins.sha256") + +sed -E 's/^([[:space:]]+secret-key:).*/\1 /' \ + "$root/config.yaml" >"$tmp/config-after.normalized.yaml" +cmp "$backup/config.normalized.yaml" "$tmp/config-after.normalized.yaml" + +if [[ -n "$keeper_pid" ]]; then + test "$(cat "$root/keeper/run/keeper.pid")" = "$keeper_pid" + kill -0 "$keeper_pid" +fi +if [[ "$manager_was_running" -eq 1 ]]; then + test -s "$root/run/manager.pid" + kill -0 "$(cat "$root/run/manager.pid")" +fi + +admin="$(cat "$root/secrets/cpa-management-key")" +curl -fsS -H "Authorization: Bearer $admin" \ + http://127.0.0.1:8317/v0/management/plugins >"$tmp/plugins-after.json" +python3 - "$tmp/plugins-after.json" "$tmp/plugins-after.normalized.json" <<'PY' +import json +import sys + +source, target = sys.argv[1:] +payload = json.load(open(source, encoding="utf-8")) +items = [] +for plugin in payload.get("plugins", []): + item = { + "id": plugin.get("id"), + "path": plugin.get("path"), + "version": (plugin.get("metadata") or {}).get("version"), + "registered": plugin.get("registered"), + "enabled": plugin.get("enabled"), + "effective_enabled": plugin.get("effective_enabled"), + } + items.append(item) +items.sort(key=lambda value: value["id"] or "") +with open(target, "w", encoding="utf-8") as handle: + json.dump(items, handle, sort_keys=True, separators=(",", ":")) +PY +cmp "$backup/plugins.normalized.json" "$tmp/plugins-after.normalized.json" + +grep -q "CLIProxyAPI Version: $expected_version, Commit: $expected_commit" "$root/logs/cpa-console.log" +if grep -Eqi 'panic|pluginhost:.*(error|failed)' "$root/logs/cpa-console.log"; then + tail -n 100 "$root/logs/cpa-console.log" + exit 1 +fi + +rollback_needed=0 +printf 'DEPLOYMENT_OK\n' +printf 'version=%s\n' "$first_line" +printf 'backup=%s\n' "$backup" +printf 'core_sha256=%s\n' "$expected_binary_hash" +printf 'cpa_pid=%s\n' "$(cat "$root/run/cpa.pid")" +if [[ -n "$keeper_pid" ]]; then + printf 'keeper_pid=%s\n' "$keeper_pid" +fi +'@ + Write-Utf8NoBom -Path $remoteScriptPath -Content $remoteScript + + Write-Host "Archive: $archivePath" + Write-Host "Archive SHA-256: $archiveHash" + Write-Host "Binary SHA-256: $binaryHash" + + if (-not $PSCmdlet.ShouldProcess("$SshTarget`:$RemoteRoot", "Deploy CPA core $version / $commit")) { + return + } + + Invoke-NativeCommand $ssh @('-o', 'BatchMode=yes', $SshTarget, "test -d '$RemoteRoot/upload' -a -x '$RemoteRoot/cpa.sh'") + Invoke-NativeCommand $scp @('-C', $archivePath, $checksumPath, "$SshTarget`:$RemoteRoot/upload/") + + $remoteCommand = "tr -d '\r' | bash -s -- '$archiveName' '$archiveHash' '$binaryHash' '$version' '$commit' '$DrainTimeoutSeconds' '$DrainPollSeconds' '$RemoteRoot'" + Get-Content -Raw -LiteralPath $remoteScriptPath | & $ssh '-o' 'BatchMode=yes' $SshTarget $remoteCommand + if ($LASTEXITCODE -ne 0) { + throw "Remote deployment failed with exit code $LASTEXITCODE." + } +} finally { + Pop-Location +}