455 lines
17 KiB
Markdown
455 lines
17 KiB
Markdown
# 部署与运维模块
|
||
|
||
## 1. 定位
|
||
|
||
本模块规定 cpa-ext 如何构建、安装、启动、观察、备份、升级和恢复。它把 [dev.md](dev.md) 的 native runtime 约束、[security.md](security.md) 的 fail-closed 前提和 [persistence.md](persistence.md) 的数据库规则转成可执行运维流程。
|
||
|
||
当前仓库仍是只声明 `usage_plugin` 的基础骨架，不具备本文所述完整生产能力。只有 [test-plan.md](test-plan.md) 的相应发布门禁通过后，才能把某个版本标记为 production-ready。
|
||
|
||
## 2. 支持基线
|
||
|
||
设计验证基线：
|
||
|
||
| 项目 | 目标 |
|
||
| --- | --- |
|
||
| CLIProxyAPI | `v7.2.130` / `f43aad7637ad813745bf7d341acb5663617570c5` |
|
||
| Native ABI | `1` |
|
||
| RPC schema | `3` |
|
||
| cpa-ext plugin ID | `cpa-ext` |
|
||
| 当前 module Go | `1.24` |
|
||
| CPA module Go | `1.26.0` |
|
||
| Home mode | 不支持，必须关闭 |
|
||
| CPA build | 必须是 CGO/plugin-capable，不能使用 `no-plugin` 产物 |
|
||
|
||
生产兼容性按“精确 CPA tag + OS + arch + cpa-ext artifact”发布，不只写“ABI 1”。每次升级 CPA 都要重新跑 ABI、E2E、安全、性能和 soak 门禁。
|
||
|
||
目标发布矩阵：
|
||
|
||
- Linux amd64/arm64 `.so`；
|
||
- Windows amd64 `.dll`；
|
||
- macOS amd64/arm64 `.dylib`（若实际维护）；
|
||
- WSL 构建的 `.so` 只供运行在 WSL/Linux 的 CPA，不能装入 Windows CPA。
|
||
|
||
Go c-shared 需要目标平台 C toolchain，不能只设置 `GOOS/GOARCH` 假装完成 CGO 交叉编译。
|
||
|
||
## 3. 运行拓扑
|
||
|
||
### 3.1 默认 MVP
|
||
|
||
```text
|
||
reverse proxy / readiness gate
|
||
│
|
||
▼
|
||
CLIProxyAPI + cpa-ext.so
|
||
│
|
||
├─ synchronous short SQLite transactions
|
||
├─ callback-driven bounded maintenance
|
||
└─ no long-lived plugin worker
|
||
```
|
||
|
||
第一版默认 callback-driven：认证、准入、事实和账本在回调内完成必要短事务；聚合追赶、清理和 checkpoint 只在安全宿主调用中按时间/页数预算推进。
|
||
|
||
### 3.2 Sidecar 拓扑
|
||
|
||
P0 runtime/24h soak 失败，或需要长期 quota refresh、备份、归档、大导出时：
|
||
|
||
```text
|
||
CLIProxyAPI + thin cpa-ext plugin ── SQLite/IPC ── cpa-ext sidecar
|
||
```
|
||
|
||
sidecar 只承担长期任务/公共 API，不得形成第二套余额或价格权威。SQLite 单 writer、IPC 认证、文件锁和 crash ownership 必须另行验证。
|
||
|
||
### 3.3 Worker 拓扑
|
||
|
||
只有目标 CPA/Go/toolchain/SQLite driver 的双 runtime 24h soak 通过，才允许动态库启用有界 worker。发布元数据必须标出 topology；不能在补丁版本中静默从 callback-driven 改为 worker。
|
||
|
||
## 4. 文件与权限布局
|
||
|
||
建议 Linux 布局：
|
||
|
||
```text
|
||
<cpa-root>/
|
||
├─ cliproxy
|
||
├─ config.yaml
|
||
├─ plugins/
|
||
│ └─ linux/amd64/cpa-ext-v0.1.0.so
|
||
└─ data/cpa-ext/
|
||
├─ cpa-ext.db
|
||
├─ cpa-ext.db-wal
|
||
├─ cpa-ext.db-shm
|
||
├─ backups/
|
||
└─ diagnostics/
|
||
|
||
/etc/cpa-ext/
|
||
└─ hmac-keyring.json # 或 OS secret store，绝不放进 data/backups
|
||
```
|
||
|
||
要求：
|
||
|
||
- CPA 运行用户拥有 plugin/data，其他用户默认不可读；
|
||
- keyring `0600`、目录 `0700`；
|
||
- DB/backup `0600`、目录 `0700`；
|
||
- plugin binary 只由发布/运维用户写，运行用户只读；
|
||
- 数据目录不能位于临时目录、网络共享或会被自动清理的位置；
|
||
- 不把 SQLite、WAL、keyring、Auth、日志放进发布归档；
|
||
- Windows 使用等价 ACL，不能只依赖扩展名。
|
||
|
||
## 5. 目标配置
|
||
|
||
```yaml
|
||
remote-management:
|
||
allow-remote: false
|
||
secret-key: "<strong-random-management-key>"
|
||
|
||
# 仅保留一个运维离线 sentinel；绝不分发给用户。
|
||
api-keys:
|
||
- "<strong-random-sentinel-key>"
|
||
|
||
plugins:
|
||
enabled: true
|
||
dir: plugins
|
||
configs:
|
||
cpa-ext:
|
||
enabled: true
|
||
priority: 100
|
||
store:
|
||
version: "0.1.0"
|
||
codex_only: true
|
||
data_dir: data/cpa-ext
|
||
database_file: cpa-ext.db
|
||
settlement_currency: USD
|
||
frontend_auth_exclusive: true
|
||
unbound_key_policy: deny
|
||
unpriced_usage_policy: deny_new_requests
|
||
maintenance_mode: callback
|
||
```
|
||
|
||
说明：
|
||
|
||
- 上述是完整目标配置，当前基础插件只解析 `codex_only`；
|
||
- CPA `Home` 是由 `-home-jwt` 注入的 runtime-only 状态，YAML 中的 `home:` 会被当前 parser 忽略；生产启动命令不得使用 `-home-jwt`，并由 readiness 检查实际 runtime 状态；
|
||
- `enabled`、`priority` 是 CPA host-owned 字段，也会出现在 `config_yaml`；
|
||
- `store.version` 用于选择版本化动态库；
|
||
- `database_file` 相对 `data_dir` 解析，不能允许 `..` 逃逸；
|
||
- `settlement_currency` 第一版只能是 USD；
|
||
- HMAC keyring 通过受限 secret-file/OS store locator 注入，不把 key 值放进 YAML；
|
||
- 生产不允许 observe-only、unbound allow 或 unknown price=0；
|
||
- 所有可互相绑定的 Codex Auth 应使用相同 CPA priority。
|
||
|
||
热配置：UI 展示、查询限制、非安全统计刷新参数、明确允许的业务阈值。冷配置：data/database path、keyring source、currency、plugin identity、runtime topology。冷配置变化由 LKG reconfigure 拒绝并提示排空重启。
|
||
|
||
## 6. 本地开发构建
|
||
|
||
### 6.1 WSL/Linux
|
||
|
||
```bash
|
||
cd /mnt/d/agent/cpa-plugin
|
||
./scripts/check-env.sh
|
||
go test ./...
|
||
go test -race ./...
|
||
./scripts/build.sh
|
||
file bin/cpa-ext.so
|
||
nm -D bin/cpa-ext.so | grep cliproxy_plugin_init
|
||
```
|
||
|
||
`build.sh` 会执行 gofmt、`go mod tidy`、单元测试和 c-shared 构建。正式 CI 应把“依赖文件是否被意外修改”作为检查，不能让 tidy 的变化无人审阅。
|
||
|
||
### 6.2 PowerShell 调用 WSL
|
||
|
||
```powershell
|
||
./scripts/build.ps1
|
||
wsl file /mnt/d/agent/cpa-plugin/bin/cpa-ext.so
|
||
wsl nm -D /mnt/d/agent/cpa-plugin/bin/cpa-ext.so
|
||
```
|
||
|
||
当前产物是 Linux `.so`。Windows `.dll` 必须在 Windows CGO toolchain 下单独构建和验证 export。
|
||
|
||
### 6.3 当前测试宿主
|
||
|
||
仓库已有：
|
||
|
||
```bash
|
||
./scripts/run-test-host.sh
|
||
tail -f .runtime/cliproxy.log
|
||
./scripts/stop-test-host.sh
|
||
```
|
||
|
||
`.runtime/` 只用于本地测试，不是生产目录。`/healthz` 只证明 CPA 进程存活，不证明 cpa-ext active、价格可用或不存在认证旁路。
|
||
|
||
## 7. 发布物
|
||
|
||
每个 artifact 必须包含/伴随：
|
||
|
||
- `cpa-ext` 动态库；
|
||
- version、git commit、build timestamp；
|
||
- target OS/arch、Go version、C toolchain；
|
||
- minimum/exact tested CPA version；
|
||
- ABI=1、max RPC schema=3、capability 清单；
|
||
- runtime topology；
|
||
- LICENSE、NOTICE/THIRD_PARTY；
|
||
- SHA-256 checksum，推荐额外签名/provenance/SBOM。
|
||
|
||
CPA plugin store zip 根目录中的动态库文件名使用：
|
||
|
||
```text
|
||
cpa-ext.so
|
||
# 或
|
||
cpa-ext-v0.1.0.so
|
||
```
|
||
|
||
安装目标可位于 `plugins/<goos>/<goarch>/`。发布包不能包含生成 `.h`，除非消费者明确需要。
|
||
|
||
## 8. 安装前检查
|
||
|
||
1. 确认 CPA exact version、plugin-capable build 和平台架构；
|
||
2. 确认 CPA 未使用 `-home-jwt` 启动，实际 runtime `Home.Enabled=false`；
|
||
3. 备份 CPA config、SQLite 和匹配 keyring；
|
||
4. 校验 artifact checksum/signature；
|
||
5. 校验动态库 export `cliproxy_plugin_init`；
|
||
6. 检查 data/keyring 目录权限和磁盘余量；
|
||
7. 检查只有 sentinel 留在 CPA native `api-keys`，没有用户 Key；
|
||
8. 检查 management 仅 loopback/受信网关可达；
|
||
9. 检查所有可绑定 Codex Auth priority；
|
||
10. 准备 gateway drain 和 rollback artifact；
|
||
11. 首次生产部署必须先有已审阅 published price version；
|
||
12. 确认 P0 runtime/performance/soak gate 结论与所选 topology 一致。
|
||
|
||
## 9. 首次安装
|
||
|
||
1. 在排空环境停止 CPA；
|
||
2. 原子复制版本化 dynamic library 到目标目录；
|
||
3. 创建 data/keyring 目录和权限；
|
||
4. 写入/审阅配置，先不开放用户入口；
|
||
5. 启动 CPA，观察 plugin load/register/schema/capabilities；
|
||
6. 等待 migration、integrity 基础检查、keyring、price 和 recovery 完成；
|
||
7. 用 Management `/plugins` 确认 `cpa-ext` active 和版本；
|
||
8. 调用 cpa-ext `/readiness` 与最小 `/ready`；
|
||
9. 执行无效用户 Key 负向探针，确认不能访问上游；
|
||
10. 在隔离测试账户完成“签发 → 准入 → strict route → Usage → 金额账本”；
|
||
11. 对比无插件 OAuth 基线的 TTFT/吞吐；
|
||
12. gateway 才开始逐步放量。
|
||
|
||
任何一步失败都保持用户入口关闭。不能因为 CPA `/healthz` 为 200 就继续。
|
||
|
||
## 10. 启动顺序与 readiness
|
||
|
||
插件内部：
|
||
|
||
1. 解析 lifecycle config/schema；
|
||
2. 验证冷配置和路径；
|
||
3. 打开 SQLite、migration、quick integrity；
|
||
4. 加载 HMAC keyring；
|
||
5. 加载 active PriceVersion；
|
||
6. 恢复 pending/Usage/settlement/outbox；
|
||
7. 加载账户、Credential、route 和统计 Snapshot；
|
||
8. 装配 callback runner/sidecar；
|
||
9. 原子发布 Runtime；
|
||
10. 返回 registration。
|
||
|
||
Readiness component：
|
||
|
||
| Component | 失败影响 |
|
||
| --- | --- |
|
||
| runtime/schema/capabilities | 不注册/不开放流量 |
|
||
| SQLite/migration/ledger | fail closed |
|
||
| HMAC keyring | fail closed |
|
||
| active pricing | fail closed |
|
||
| Credential/account directory | fail closed |
|
||
| statistics projection | 可降级，显示 lag |
|
||
| quota refresh | 可降级，显示 stale |
|
||
| UI resources | 不影响计费，但管理页不可用 |
|
||
| backup/archive runner | 告警，不允许掩盖核心 readiness |
|
||
|
||
外部 gate 组合：
|
||
|
||
- CPA process health；
|
||
- Management plugin active/version/capabilities；
|
||
- cpa-ext self readiness；
|
||
- resource `/ready` 存在；
|
||
- Home 关闭；
|
||
- 负向认证探针；
|
||
- gateway 自己确认 sentinel 未被分发。
|
||
|
||
## 11. 监控与告警
|
||
|
||
最低指标：
|
||
|
||
| 类别 | 指标 |
|
||
| --- | --- |
|
||
| Runtime | active/fused/reconfigure rejected/schema/topology |
|
||
| RPC | 每 method 调用数、错误、panic、耗时、payload bytes |
|
||
| Auth | success/reject/unknown/dependency failure、rate limit |
|
||
| Access | terminate code、strict mismatch、scheduler fallback |
|
||
| Billing | settlement、amount、late revision、unpriced、unmeasured、negative balance |
|
||
| Persistence | transaction latency/error/busy、WAL/DB size、integrity、backup age |
|
||
| Projection | event_seq、checkpoint、lag、rebuild status |
|
||
| Upstream | account active/missing/priority shadow、quota age/error |
|
||
| Performance | TTFT、total latency、chunk gap、alloc/GC、stream RPC bytes |
|
||
| Gateway | open/drained、last readiness/negative probe |
|
||
|
||
必须告警：
|
||
|
||
- plugin route/active 状态消失或 fuse；
|
||
- readiness 核心 component 失败；
|
||
- persistence gap、账本不一致；
|
||
- active price 缺失/未知 GPT-5.6；
|
||
- unpriced/unmeasured 超阈值；
|
||
- keyring mismatch；
|
||
- DB/WAL/磁盘逼近上限；
|
||
- backup 超过目标 RPO；
|
||
- projection lag；
|
||
- priority 变化导致 binding 不可用；
|
||
- stream 性能相对基线退化。
|
||
|
||
指标端点默认只在 Management/受信 sidecar 暴露，不把账户数、金额或错误详情放进公开 `/ready`。
|
||
|
||
## 12. 日常维护
|
||
|
||
### 12.1 每日
|
||
|
||
- 检查 readiness、gateway 和关键告警；
|
||
- 检查 unpriced/unmeasured/persistence gap；
|
||
- 检查 backup 成功和磁盘；
|
||
- 检查 quota stale、missing Auth 和 strict mismatch；
|
||
- 检查异常 Credential 消费和负余额。
|
||
|
||
### 12.2 每周
|
||
|
||
- 运行账本余额 reconciliation；
|
||
- 检查 projection checkpoint 与 archive eligibility；
|
||
- 审阅价格候选，但不自动发布；
|
||
- 审阅 audit、Key rotation/expiry 和管理员操作；
|
||
- 抽样恢复 backup 到隔离目录。
|
||
|
||
### 12.3 每月/发布前
|
||
|
||
- 完整离线 restore drill；
|
||
- 容量/查询计划检查；
|
||
- 依赖、CPA 和价格来源复审；
|
||
- sentinel/Management/HMAC/key rotation 演练；
|
||
- 安全故障注入和 24h soak（涉及 runtime/toolchain/SQLite 变化时）。
|
||
|
||
## 13. 备份与恢复
|
||
|
||
### 13.1 备份
|
||
|
||
- 使用 SQLite online backup API，不直接复制 WAL 模式 `.db`；
|
||
- 备份包含 schema/version/content hash/created_at；
|
||
- keyring 单独加密备份，记录非秘密 fingerprint/key IDs；
|
||
- 保留 7～30 天并至少一份异地副本；
|
||
- 备份目录不由 public API 任意下载；
|
||
- 每次破坏性 migration 和版本升级前强制备份；
|
||
- backup 成功必须通过打开、integrity 和基本账本检查。
|
||
|
||
### 13.2 离线恢复
|
||
|
||
1. gateway 排空并停止 CPA/sidecar；
|
||
2. 保存损坏现场副本；
|
||
3. 选择匹配时间点的 SQLite + keyring；
|
||
4. 在隔离目录验证 checksum、schema、integrity、key fingerprint；
|
||
5. 替换明确目标文件，不操作宽泛目录；
|
||
6. 启动时运行 migration/recovery；
|
||
7. 从权威事实重建 projection；
|
||
8. 运行账本、Credential 和 PriceVersion reconciliation；
|
||
9. 完成全套 readiness/负向/计费探针；
|
||
10. 逐步恢复流量并记录事件审计。
|
||
|
||
缺失/不匹配 keyring 时不得自动生成新 key 后继续；保持 fail closed。
|
||
|
||
## 14. 升级与回滚
|
||
|
||
### 14.1 禁止热替换生产动态库
|
||
|
||
当前 CPA binary hot reload 会把旧 native 实例放入 retired 集合，直到宿主整体 shutdown 才真正 shutdown。旧 runtime/worker/SQLite handle 可能继续存在，因此生产升级固定为：排空 → 停 CPA → 替换/切换 version pin → 启动。
|
||
|
||
### 14.2 升级流程
|
||
|
||
1. 阅读 release notes、CPA compatibility、migration 和 topology 变化；
|
||
2. staging 完成 test-plan 全门禁；
|
||
3. 备份 SQLite + keyring + config；
|
||
4. gateway drain；
|
||
5. 停止 CPA 并确认进程退出；
|
||
6. 安装新版本化 artifact、更新 version pin；
|
||
7. 启动、migration/recovery/readiness；
|
||
8. 执行负向认证、金额 golden、route、cancel/stream 和性能 smoke；
|
||
9. 小流量观察；
|
||
10. 标记升级完成并保留旧 artifact/backup。
|
||
|
||
### 14.3 回滚
|
||
|
||
如果 migration 保持旧版兼容，可以停机切回旧 artifact。若 schema 已不兼容：
|
||
|
||
- 停机；
|
||
- 恢复升级前 SQLite + 对应 keyring；
|
||
- 恢复旧 config/artifact；
|
||
- 重新完成 readiness/探针；
|
||
- 对升级窗口产生的真实上游消费人工 reconciliation，不能静默丢账。
|
||
|
||
价格回滚不需要二进制回滚，走 [pricing.md](pricing.md) 的“创建新发布版本”。
|
||
|
||
## 15. 配置变更
|
||
|
||
- 使用 CPA Management API/YAML 变更前保存当前 revision；
|
||
- 安全敏感变更必须双人复核和 reason；
|
||
- 写入后检查 LKG/`reconfigure_rejected`；
|
||
- capability shape 不因热配置错误消失；
|
||
- 冷配置只在排空重启中修改；
|
||
- 不用手改 SQLite 代替管理 API；
|
||
- 不在 config 中放 Management/downstream/HMAC/OAuth secret 的副本；
|
||
- 变更 Codex Auth priority 前预览受影响 binding。
|
||
|
||
## 16. 常见故障 Runbook
|
||
|
||
### 16.1 CPA 正常但 `/ready` 404
|
||
|
||
立即撤流量 → 检查 Home、plugin global/instance enabled、文件名/版本 pin、架构、export、load/register 日志 → 不要临时删除 sentinel 或放开 native Key。
|
||
|
||
### 16.2 Readiness 显示 DB/keyring/price unhealthy
|
||
|
||
撤流量 → 保留现场 → 检查权限、磁盘、key ID、migration、active price → 修复后运行 integrity/reconciliation → 不切 observe-only。
|
||
|
||
### 16.3 用户请求突然变慢
|
||
|
||
先 A/B 比较同 CPA/OAuth/model/tier/transport：无插件、空 hook、collection-only、完整插件 → 检查 schema=3、每 chunk RPC 字节、HistoryChunks、response-before 重复 body、DB/锁和 GC → 超过 [dev.md](dev.md) 阈值即回滚/撤下相关 hook。
|
||
|
||
### 16.4 strict binding 不可用
|
||
|
||
检查 CPA Auth active/disabled/unavailable、模型和 priority → 查看 scheduler candidates/bindable reason → `priority_shadowed` 时统一 priority 或调整产品绑定，不强行返回隐藏 Auth ID。
|
||
|
||
### 16.5 quota stale
|
||
|
||
不影响已由 CPA candidate 证明可用的基础 strict 请求，但 UI 标 stale → 手动小批 refresh → 检查 provider allowlist、Auth ref、限流和 sidecar → 不把 stale 写成 0/无限。
|
||
|
||
### 16.6 persistence gap/unmeasured 激增
|
||
|
||
撤流量或收紧并发 → 检查 callback、DB、response correlation 和 CPA 版本 → 保存上游证据 → 修复后追加 settlement/adjustment；禁止猜 Token 或覆盖旧账本。
|
||
|
||
## 17. 容量与保留
|
||
|
||
发布前用真实形状数据验证：
|
||
|
||
- 50/500/更多 Credential 与上游账户；
|
||
- 百万级 Request/Execution/Usage/Ledger；
|
||
- 30/90 天查询；
|
||
- streaming 长 Prompt/多 chunk；
|
||
- 并发 1/8/32 及计划上限；
|
||
- WAL、backup、rebuild 和 archive；
|
||
- 磁盘增长、峰值内存、CPU、p95/p99。
|
||
|
||
容量结论记录最后成功点和最小失败点，生产持续负载取安全折扣。可参考 usage-keeper `internal/benchmark/capacity-v1` 的 canonical dataset、clone、cgroup memory peak 和 p99 方法，但需要增加 native plugin/CPA/stream 维度。
|
||
|
||
## 18. 验收标准
|
||
|
||
- 文档明确当前骨架与 production-ready 版本的差别；
|
||
- artifact、CPA、ABI/schema、OS/arch/toolchain 可追溯；
|
||
- 安装前 checksum/export/权限/version pin 均验证；
|
||
- 生产 gateway、sentinel、exclusive 和负向探针缺一不可；
|
||
- `/healthz` 不被误用为插件 readiness；
|
||
- SQLite/keyring 成对备份和隔离恢复演练通过；
|
||
- 升级一定排空并重启 CPA，不热替换；
|
||
- migration 失败、keyring mismatch、price 缺失时保持 fail closed；
|
||
- 关键指标/告警/日常检查和故障 runbook 可执行；
|
||
- WSL/Linux 与 Windows artifact 不混用；
|
||
- 生产配置不使用 `000`、observe-only、用户 native CPA Key 或未确认价格；
|
||
- 发布流程引用并满足 [test-plan.md](test-plan.md) 全部门禁。
|