个人 AI 聚合服务 v1：架构、选型与实施交付契约

更新入口（2026-10-01）：AI Aggregator Gateway：APISIX Standalone 与 Home-Lab 架构。本文保留历史交付基线，其中 Kong、双域名和“尚未部署”的描述不代表当前 Home-Lab 状态；当前选型与已验证范围请见新文档。

状态：v1 实施基线；默认 disabled，尚未完成真实节点部署、OAuth 登录或请求验收。 v1 公共入口只有 Caddy；Cloudflare Worker/Pages、Cloud Run、Bedrock、Vertex AI、Azure Foundry 均不在 v1 运行链路。

架构图单独维护于：AI Gateway v1 架构图。

零、先看架构图：CPA 节点 = AI Desktop Role + CodeAgent + 单账号 CPA

flowchart LR
    U[Claude Code / Codex CLI / Android Studio / SDK / Web SaaS]
    C[Caddy :443\nTLS + IP 白名单]
    K[Kong :8000\nJWT/Key Auth + Tenant ACL\nRate Limit + Host Route + Audit]
    N[New API :3000\nCPA Channel / Model Alias / Health]
    L[LiteLLM :4000\n官方 OpenAI / Anthropic / xAI]
    D1[AI Desktop Role\nCodex CPA + CodeAgent]
    D2[AI Desktop Role\nClaude CPA + CodeAgent]
    D3[AI Desktop Role\nGrok CPA + CodeAgent]
    V[(Vault\n仅 DB/Gateway/Provider Key)]
    P[(PostgreSQL\nKong/New API/LiteLLM 独立 DB)]
    U --> C --> K
    K -->|ai.*| N
    K -->|direct.ai.*| L
    N --> D1
    N --> D2
    N --> D3
    L --> O[官方 API]
    V -.运行时注入.-> K
    V -.运行时注入.-> N
    V -.运行时注入.-> L
    K --- P
    N --- P
    L --- P

这张图的关键约束是：AI Desktop Role 只落在 CPA 执行节点；它提供桌面、浏览器、CodeAgent Runtime 和基础监控，随后由 ai_aggregator_v1 role 安装一个实例一个账号的 CPA。Gateway 节点不安装 CPA/CodeAgent，CPA 节点不承担 Caddy、Kong、New API 或 LiteLLM。

零点一、项目任务拆解与实施计划

运行阶段定义

1. plan：只解析 GitOps、检查资源契约、Ansible 语法和安全约束，不连接真实节点。
2. provision：仅 UAT 可选，按 GitOps 资源契约创建 AWS ARM64 Spot 节点；每个 CPA 节点 2C2G 起步，建议 2C4G。
3. stage：先执行 deploy_ai_desktop.yml -e ai_desktop_cpa_codeagent=true -e ai_desktop_remote_enabled=false -e ai_desktop_manage_user=false，再执行 deploy-ai-aggregator-v1.yml；只准备基线、目录、systemd、路由和临时凭据，不启用公网流量。
4. OAuth：操作者分别进入四个 CPA 的 AI Desktop 会话，完成对应账号登录；OAuth bundle 只写入该实例本地加密 auth/ 目录，绝不复制到 Vault 或 Git。
5. validate：检查本地 auth、CPA 健康、New API channel、Kong 租户 Token、三类协议和故障隔离。
6. activate：仅在人工确认四个 OAuth 与 smoke test 后启动生产链路；Prod 需要 environment approval，UAT 资源仍受 60 分钟自动销毁约束。

CPA 节点基线的实际执行关系

deploy_ai_desktop.yml -e ai_desktop_cpa_codeagent=true -e ai_desktop_remote_enabled=false
  └─ roles/vhosts/ai_desktop
       ├─ XFCE/XRDP
       ├─ roles/ai_agent_runtime   → Codex / Claude Code Runtime
       └─ roles/vhosts/node_exporter
  └─ deploy-ai-aggregator-v1.yml
       └─ roles/vhosts/ai_aggregator_v1 → 单账号 CPA / 本地 auth / CodeAgent workspace

Grok 在 v1 中作为 CPA provider/channel 纳入矩阵；仓库现有 Agent Runtime 没有预设一个未经审核的 Grok CLI npm 包，因此不会伪造或自动安装该包。Grok CPA 的账号登录和适配由 CPA 节点承载，待确定受信任 CLI 制品后再追加到该节点的 CodeAgent 包清单。

为避免新增桌面密码类凭据，流水线在云节点上默认关闭 XRDP 的密码登录，保留 XFCE、浏览器和 Agent Runtime 基线；OAuth 人工操作通过受控 SSH 会话完成。若后续确需图形化 XRDP，只能从现有加密 inventory/Vault contract 注入密码，并且只允许私网或 SSH 隧道访问，禁止开放公网 3389。

一、目标、调用链路与部署模式

1. 核心调用链路

 [ 客户端 (IDE / SDK / 终端工具) ]
           │
           │ HTTPS (:443) / IP 白名单 / 设备级 Key (sk-device-xxx)
           ▼
   [ Caddy 网关 (:443) ]
           │
           │ 127.0.0.1 内部转发（仅 TLS 终止与 IP 白名单）
           ▼
  [ Kong (:8000) ] ── (JWT/Key Auth / Tenant ACL / Rate Limit / Audit Metadata)
           ├── [ New API (:3000) ] ── (模型别名 / CPA Channel / PostgreSQL 状态)
           │
           │ 私网 / WireGuard / 宿主 loopback (禁止公网直接暴露)
           ├── CPA Codex 逻辑 Channels (:8317/:8320) ── 节点加密 auth ──► OpenAI / Codex 账号实例
           ├── CPA Claude Code 逻辑 Channel (:8318)   ── 节点加密 auth ──► Anthropic / Claude 账号实例
           └── CPA Grok 逻辑 Channel (:8319)          ── 节点加密 auth ──► xAI / Grok 账号实例

 [ Caddy direct.ai.* ] ──► [ Kong (:8000) ] ──► LiteLLM (:4000) ──► 官方 OpenAI / Anthropic / xAI API

这里是两条并列的聚合承载链路：New API → CPA 面向订阅账号和 CLI/IDE 应用适配，LiteLLM 面向官方 API 的统一协议、模型路由和直连调用；Kong 只负责多租户入口访问控制，不承担 Provider 聚合。LiteLLM 不作为 CPA 的前置代理， 二者也不互相串联。客户端根据需要选择 ai.* 或 direct.ai.*，但两者都必须经过 Caddy 的 HTTPS、IP 白名单和 Kong 的统一 Token 校验。

外部客户端只看到两个受控聚合入口之一（https://ai.svc.plus 或 https://direct.ai.svc.plus）和分发的业务 Key（sk-client-xxxxxxxx），完全不知道底层的 CPA 地址、CPA 内部通信 Key 以及具体的 OAuth Token。

3. 第三方客户端接入目标

v1 的完成定义包含“第三方客户端可配置接入”，而不仅是服务端进程启动：

Claude Code 的 gateway 配置使用 ANTHROPIC_BASE_URL 和 ANTHROPIC_AUTH_TOKEN，其中 token 由本机密钥链或 Vault helper 提供；不写入项目文件。Android Studio 的远程模型配置需要 HTTPS API endpoint、API key，并通过 /v1/models 刷新模型；因此 Caddy、模型列表和 Bearer token 校验都是 v1 验收项。详见 Anthropic LLM gateway configuration 和 Android Studio remote model。

GitOps 中的 client_profiles 是非敏感接入契约；实际租户/应用 Token 由 Kong Consumer 管理并保存到 Kong PostgreSQL，Vault 不保存客户端 token。客户端接入前必须通过固定 IP 白名单，客户端配置不得包含 CPA 地址、OAuth token、Kong Admin 凭据或数据库凭据。

推荐接入方式：

# Claude Code：走 New API -> CPA Claude；值由本机密钥链 / Vault helper 注入
export ANTHROPIC_BASE_URL="https://ai.svc.plus"
export ANTHROPIC_AUTH_TOKEN="<从本机安全存储读取的 client token>"
claude

# OpenAI-compatible SDK / IDE：走 New API -> CPA Codex
export OPENAI_BASE_URL="https://ai.svc.plus/v1"
export OPENAI_API_KEY="<从本机安全存储读取的 client token>"

Android Studio 配置为 Tools → AI → Model Providers → Third-Party Remote Provider，URL 填 https://direct.ai.svc.plus/v1，API key 填 Android Studio 专用 client token，点击 Refresh 确认能看到 anthropic-api、openai-api 或 xai-api 等模型。Android Studio 的 Chat 与 AI Agent 是 v1 目标能力；依赖 Google/Gemini 特有协议的功能不作为 v1 兼容承诺。

2. 两种部署模式

• 模式一：独立部署 (Standalone)
  • 适用场景：全新独立节点或后续物理迁移。
  • 架构特征：本项目直接管理 Caddy；绑定独立公网域名；管理 New API、LiteLLM、CPA 等全套 systemd 单元及 PostgreSQL 连接。
• 模式二：嵌入 AI Workspace (Embedded - v1 首选)
  • 适用场景：复用现有运行节点（如 jp-xhttp-contabo.svc.plus）。
  • 架构特征：复用宿主机已有的 Caddy 网关，通过 conf.d 引入两个域名路由；New API 与 LiteLLM 在不同端口并行运行。New API→CPA 面向 AI App，LiteLLM 面向直接 AI API，互不串联。

两种模式统一由同一套 GitOps 拓扑模型与 Ansible Role 交付：

spec:
  deployment_mode: embedded # 或 standalone
  entrypoint:
    domain: ai.svc.plus
    direct_api_domain: direct.ai.svc.plus
    reuse_existing_caddy: true
  upstream:
    app_gateway: new-api
    direct_api: litellm

二、纯技术选型对比：Sub2API vs CPA + New API

选型裁决依据

1. 个人 / 小团队自用订阅资源整合: Sub2API > CPA + New API。Domain Model 高度契合，链路更短，部署运维开销极小。
2. 长期演化 / 多来源统一 AI 基础设施: CPA + New API > Sub2API。Adapter（CPA）与 Gateway（New API）清晰解耦，后续可无缝接入自建模型、外部正规商用 API 或更换适配器。
3. 纯商用 API Key 汇聚与转售: New API 单独使用，无需引入 CPA 或 Sub2API。

三、资源预算与测试环境硬约束 (Spot t4g 1h)

1. 测试与验证阶段硬约束 (AWS Spot t4g 1h)

[!IMPORTANT] 测试阶段统一计算规格：AWS Spot t4g.medium (ARM64) 1小时生命周期实例！

• 实例类型：t4g.small (2 vCPU / 2 GiB) 或 t4g.medium (2 vCPU / 4 GiB ARM64)。
• 竞价模式：spot_instance: true（one-time 临时竞价实例）。
• 硬性生命周期限制：max_runtime_minutes: 60。实例启动时通过 user_data 注入到期自动关机脚本（sleep 3600 && /sbin/shutdown -h now），结合 AWS instance_initiated_shutdown_behavior: terminate 实现物理自动销毁，坚决杜绝因人工遗忘产生的闲置计费。
• 架构构建要求：所有构建物料（New API 二进制、CPA 二进制）必须提供 Linux arm64 原生二进制及对应 SHA-256 校验和。

2. 生产与长效运行容量规划

• 最低可运行配置 (2 vCPU / 4 GB RAM / 40 GB SSD): 承载 Caddy + New API + 1 个 CPA 实例。
• 推荐 Gateway 配置 (4 vCPU / 8 GB RAM / 80 GB SSD): 承载 Caddy + Kong + New API + LiteLLM。
• 每个 CPA 节点建议 (2 vCPU / 2–4 GB RAM / 40 GB SSD): 承载一个 CPA + 一个 CodeAgent CLI 账号实例。
• 多实例横向扩展规则: 每增加 1 个 CPA + CLI 实例，追加预留 +1 vCPU、+512 MB 至 1 GB RAM、+5 GB SSD。

四、网络收敛与边界加固规范

1. 宿主机网络边界收敛

宿主机执行 ss -lntp，理想状态仅允许：

• 0.0.0.0:22 (SSH 受控运维端口)
• 0.0.0.0:443 (Caddy HTTPS 唯一对外入口)
• 严禁外部监听：0.0.0.0:3000 (New API) ❌, 0.0.0.0:8317-8319 (CPA) ❌。必须严格绑定 127.0.0.1 或加密私网。

2. Caddy 与 Kong 的单一职责

• Caddy：只做 HTTPS、证书、物理源 IP 白名单和安全 Header；两个域名统一反代至 Kong 127.0.0.1:8000，不再维护 New API/LiteLLM 的路径分流，也不校验业务 Token。
• Kong：只做 JWT/Key Auth、Tenant ACL、请求/并发限流、Host Route 和审计元数据；Admin API 127.0.0.1:8001，不对公网开放。
• AI 路由：ai.* → Kong → New API → CPA；direct.ai.* → Kong → LiteLLM → 官方 API。
• 管理面：Caddy 不发布 Kong Admin、New API Admin 或 LiteLLM Admin；运维通过 SSH port-forward 或节点本地访问。Kong 的租户 Consumer/ACL 配置进入 Kong PostgreSQL，由受控同步任务维护。
• Caddy 使用物理连接源 IP 判定白名单；客户端自报 X-Forwarded-For 无效。空白名单部署直接阻断。

3. CPA Management API 彻底关闭

• CPA 默认暴露的 /v0/management 必须在配置文件中彻底禁用公网访问：

  remote-management:
    allow-remote: false
    secret-key: "" # 为空且不设密码，关闭公开管理接口
  

• 账号维护与 OAuth 登录必须通过 SSH 登录节点或临时端口映射执行。

五、Kong 最小多租户实施设计

1. 部署模式

Kong 使用 Traditional DB-backed 模式，PostgreSQL 只保存 Kong 的 Routes、Services、Consumers、ACL 和 Plugin 配置；不部署 etcd、Kong hybrid control plane、Kong Manager 或 Redis。Kong Proxy 监听 127.0.0.1:8000，Admin API 监听 127.0.0.1:8001，两个端口均不进入公网防火墙。

Gateway PostgreSQL 集群内使用独立数据库和用户：

kong       → Kong 路由、Consumer、ACL、插件配置
new_api    → New API 业务状态和 CPA channel
litellm    → LiteLLM 用量、成本和 Provider 状态

2. 单一职责

3. 多租户配置边界

GitOps 只声明租户的 tenant_id、应用、允许入口、模型别名、限流策略和启停状态；受控同步任务负责将 Kong Consumer、ACL membership、JWT 公钥凭据、JWT jti 和吊销状态写入 Kong/PostgreSQL。JWT bearer token 本身不存储；原始 OAuth Token、Provider API Key 不进入 Git、Terraform state、systemd unit 或 CI artifact。

Kong v1 同时保留 jwt 和 key-auth 的契约，但每个环境只启用一种入口认证模式；默认使用 JWT。未完成租户凭据同步时，认证 Route 保持拒绝请求，不允许匿名回退。Kong AI Proxy v1 关闭，LiteLLM 是唯一官方 Provider 聚合器。

4. 运行路由

ai.<env-domain>          → Kong Host Route → New API → CPA
direct.ai.<env-domain>   → Kong Host Route → LiteLLM → 官方 API

Kong Route 只按 Host 和 /v1 路径匹配；Caddy 不再重复维护 New API/LiteLLM 上游地址。Kong Admin API 只在本机可访问，基础 Route/Plugin 由 Ansible 通过 loopback Admin API 幂等对账，租户 Consumer/ACL/JWT credential 由独立受控同步任务管理。

六、多账号池与路由治理最佳实践

1. 单层调度原则（收敛于 CPA）

• 每个 CPA 实例严格绑定一个账号；多个 CPA 实例通过 New API 的多个同类 channel 实现横向扩展。
• New API 不把 LiteLLM 放在 CPA 前面；直接 API 请求走独立 LiteLLM 域名。
• Codex 使用 8317/8320，Claude 使用 8318，Grok 使用 8319；远端地址由 CMDB 私网事实注入。

2. 模型稳定别名抽象 (Model Mapping)

• 客户端绝不直连具体服务商底层模型名，而是在 New API 建立稳定别名映射：
  • codex-main ──► 映射为底层最新的 GPT/Codex 模型
  • claude-main ──► 映射为底层最新的 Claude 3.7 Sonnet
  • grok-main ──► 映射为底层最新的 Grok 模型
• 上游模型升级迭代时，仅需在 New API / CPA 修改映射表，所有客户端与 IDE 零改造。

3. 原生协议全量保留

• 拒绝强行将所有请求压缩为 /v1/chat/completions:
  • 保留 /v1/responses：满足 OpenAI/Codex 原生推理、thinking 过程与高级工具调用。
  • 保留 /v1/messages：满足 Claude 原生上下文协议与客户端最佳体验。
  • 保留 /v1/models：供客户端自动发现能力。

4. 设备级 API Key 隔离

• 严禁全局共用单一 Master Key。按租户、客户端与设备在 Kong Consumer 中独立派发 Token（tenant/application/device），单设备凭据泄露时只吊销对应 Consumer；New API/LiteLLM Master Key 仅用于内部服务通信。

七、账号矩阵与 Vault 凭据平面

1. 账号矩阵（非敏感声明）

• 严格遵循 1:1:1:1 隔离模型：1 个 CPA 实例绑定 1 个 Provider 账号，对应 1 个独立 Unix 用户和 1 个独立本地加密 auth 目录。

2. Vault KV v2 路径与内容规范

Vault API: https://vault.svc.plus (KV v2 API 路径为 kv/data/...，逻辑引用不含 data/)

v1 只允许以下路径：

• kv/<env>/ai-aggregator/database/new-api: dsn。
• kv/<env>/ai-aggregator/database/litellm: dsn。
• kv/<env>/ai-aggregator/database/kong: dsn。
• kv/<env>/ai-aggregator/gateway/new-api: session_secret, crypto_secret, jwt_private_key, jwt_issuer, jwt_audience。
• kv/<env>/ai-aggregator/gateway/litellm: master_key, proxy_secret。
• kv/<env>/ai-aggregator/litellm/providers/<provider>: endpoint, api_key（仅 openai、anthropic、xai）。

accounts/<id>、instances/<id>、clients/<id> 是 PostgreSQL 中的动态逻辑记录，不是 Vault KV 路径。数据库保存账号邮箱、Provider、CLI、节点、端口、状态、模型映射、Kong Consumer/token hash、JWT jti 与吊销状态；不得保存 OAuth token 明文。

CPA OAuth 不集中写入 Vault 或数据库。每个 CPA 节点由操作者完成 Provider 登录，OAuth bundle 只保存在 /var/lib/ai-aggregator/cpa/<id>/auth/ 的节点加密目录中。New API 用 Vault 中的 JWT 私钥动态签发短期、实例级 channel JWT；CPA 仅用节点上的非敏感公钥验证。不得将任何 secret 写入 Git、文档、Terraform state、CI artifact、Ansible facts 或 systemd unit。

建议最小数据库记录：

• ai_aggregator_accounts(id, provider, cli, account_email, status)。
• ai_aggregator_instances(id, account_id, node_ref, bind_address, port, jwt_audience, status)。
• ai_aggregator_instances 与 ai_aggregator_accounts 为一对一绑定；一个账号不得同时绑定多个活动 CPA 实例。

3. 凭据隔离与动态 JWT 约束

1. 最小权限: Kong 只读取本环境的 database/kong；New API 只读取 database/new-api 与 gateway/new-api；LiteLLM 只读取 database/litellm、gateway/litellm 与 litellm/providers/*；CPA 不需要 Vault 读取权限。
2. 运行时存储: Gateway 临时凭据只允许落在 /run/ai-aggregator/ tmpfs；CPA OAuth 保存在节点级加密的 /var/lib/ai-aggregator/cpa/<id>/auth/，文件属主为对应 CPA 用户、权限 0700。
3. 动态 JWT: New API 使用 Vault 私钥签发短期 JWT，CPA 使用非敏感公钥校验 issuer、实例级 audience、exp 和 jti；过期、错实例和重放必须拒绝。
4. OAuth 生命周期: UAT Spot 销毁后 OAuth 随节点销毁；Prod 持久节点重启后从本地加密目录恢复。节点丢失或 Provider refresh 失效时必须人工重新登录。
5. New API 数据库审计: 审计锁定 fork 是否明文保存 key，不盲目宣称零明文持久化。

实现闸门：当前采用的 CLIProxyAPI 配置示例只明确提供 auth-dir、api-keys 和远程管理开关，尚未提供可验证的原生入站 JWT 校验配置。因此 Ansible 的 activate 在 CPA 节点缺少经审核的 cpa-jwt-auth-gate 可执行文件或启动命令时会硬失败；未提供启动命令时，已渲染的 CPA systemd unit 使用失败占位命令，不会启动未鉴权 CPA。待兼容 CPA 构建或 auth-gate 完成后，必须补做错误 aud、过期 JWT、错误实例 ID 和 jti 重放测试。

八、四仓库协作与流水线闭环 (Delivery Pipeline)

1. 仓库职责与事实源

2. 交付生命周期阶段

[ 1. PR 静态校验 ] ──► [ 2. Plan ] ──► [ 3. Preflight 资源探针 ] ──► [ 4. Build 制品校验 ]
        │
        ▼
[ 5. Stage 无密钥渲染 ] ──► [ 6. Bootstrap 临时认证注入 ] ──► [ 7. Activate 服务启动 ]
        │
        ▼
[ 8. Verify 端到端验收 ] ──► [ 9. Cutover 流量切换 ] ──► [ 10. Rollback 回滚预案 ]

• Stage 阶段防呆: GitOps 未启用 (enabled: false)、IP 白名单为空、制品缺少 SHA-256 校验和、或 New API 启动命令未固定 loopback 时，Stage 必须直接阻断。
• Activate 顺序: Gateway Vault 凭据注入 tmpfs 就绪 ──► Kong PostgreSQL migration 与启动 ──► Kong 两个 Host Route/认证/限流插件对账 ──► CPA 本地 auth 就绪并启动 ──► LiteLLM 启动 ──► New API 启动并绑定 127.0.0.1 ──► Caddy validate 检查通过并 reload。

3. GitOps 如何声明和使用资源

spec.infrastructure 是环境资源使用契约，服务声明与资源声明分离：

UAT 每个 nodes[].resource_ref 对应资源 contract 中的一个显式 host；流水线读取 resource_contract.path，渲染 Terraform，再把私网地址等非敏感输出写入临时 CMDB/inventory。 Prod 的 resource_ref 指向现有 CMDB 节点，GitOps 只声明角色、绑定和服务配置，不接管节点生命周期。 Vultr/GCP contract 只作为后续 provider adapter 的声明入口，v1 不自动应用。

九、验收矩阵与排障清单 (Acceptance Checklist)

十、备份与待实施状态

1. 数据库备份: New API 与 LiteLLM 使用独立 PostgreSQL 数据库和用户；升级前分别执行一致性备份，备份流直接加密并通过 Vault 中的备份凭据写入受控存储，严禁生成明文 SQL dump。
2. OAuth 凭据备份: 不进入 Vault。Prod 节点依赖加密磁盘；禁止把 auth 目录打包到 CI artifact 或普通备份。节点丢失时通过人工 OAuth 恢复。
3. 当前落地状态:
   • 已落地：四仓库的 v1 文档、GitOps UAT/Prod 声明、Ansible systemd/Caddy/Vault 注入角色、AWS Spot 渲染 contract、AWS/Vultr/GCP provider contract、manifest 校验器与 UAT 流水线骨架。
   • 待实施：提交并合并各仓库变更、配置 GitHub OIDC/Vault role 与 AWS role、填入固定 SSH/API 白名单、锁定并发布 New API/CPA/LiteLLM 制品、安装并审核 CPA JWT auth-gate、真实节点部署、OAuth 人工登录、New API channel 建立和完整 smoke test。

十一、后续云原生与 Serverless 演进（非 v1 运行链路）

本节只记录后续演进选项。Cloudflare Worker/Pages、GCP Cloud Run、Supabase 不属于 v1 部署路径，不能替换 v1 的 Caddy、宿主持久进程或 PostgreSQL 运行约束。

当聚合服务从单节点 VPS 进一步演进时，核心原则为：非 CPA 节点全量上 Serverless 云原生，CPA 节点保持独立 VPS 账号执行层。

1. 现代化分工拓扑

                                     [ 用户终端 (IDE / Web / 开发者) ]
                                                    │
                                                    │ HTTPS
                                                    ▼
                     ┌─────────────────────────────────────────────────────────────┐
                     │                 Cloudflare 边缘托管层                       │
                     │  - Cloudflare Pages: 托管 "Token 配额分析" 前端 Web 控制台     │
                     │  - Cloudflare Workers: 边缘 API 网关、Key 预检、缓存、速率限制  │
                     └──────────────────────────────┬──────────────────────────────┘
                                                    │ mTLS / 内部签名
                                                    ▼
                     ┌─────────────────────────────────────────────────────────────┐
                     │              GCP Cloud Run (Serverless Gateway)             │
                     │  - 运行 New API (容器化)，支持自动缩容至 0 (Scale to zero)   │
                     │  - 模型稳定别名映射 (codex-main, claude-main, grok-main)    │
                     │  - 协议原生转发 (/v1/responses, /v1/messages, /v1/chat)     │
                     │  - 凭据集成：GCP Secret Manager / Vault                    │
                     └───────────────┬─────────────────────────────┬───────────────┘
                                     │                             │
                                     │ PostgreSQL 连接池            │ WireGuard / 加密私网隧道
                                     ▼                             ▼
   ┌───────────────────────────────────────────────┐     ┌─────────────────────────────────────┐
   │         Supabase Cloud (Free Tier)            │     │          VPS 专属执行节点 (CPA)      │
   │  - 托管 PostgreSQL 数据库 (替代本地 SQLite)      │     │  - 必须常驻 VPS (账号执行层)         │
   │  - Token 配额、7 天滚动用量、缓存命中时序分析     │     │  - 1:1:1:1 账号隔离 (单实例单账号)   │
   │  - Row Level Security (RLS) & REST API        │     │  - 节点加密 auth + 动态 JWT         │
   │  - 为 Cloudflare Pages 前端直接提供用量查询   │     │  - CPA 仅内网绑定，对外零暴露        │
   └───────────────────────────────────────────────┘     └─────────────────────────────────────┘

2. 核心组件定位与优势

1. 前端展示：Cloudflare Pages
   • 托管类似截图风格的“Token 配额分析”交互式控制台（单页静态应用 SPA）。
   • 全球边缘 CDN 分发，秒级加载，完全免疫网络攻击，零服务器运维。
2. 边缘调度与防护：Cloudflare Workers
   • 负责统一入口鉴权与请求转发。
   • 客户端 API Key 格式预校验、防刷限流（Rate Limiting）及 CORS 自动化处理。
3. 核心网关层：GCP Cloud Run
   • 容器化运行 New API，取代在 VPS 手工常驻进程。
   • 自动弹性扩缩容（具备 Scale-to-Zero 能力），夜间无请求时零计费。
   • 原生集成 Google Secret Manager，开箱即用高可用 HTTPS 终端。
4. 统一状态与数据库：Supabase Cloud (Free Tier)
   • 免费提供 500MB 托管 PostgreSQL 与连接池（PgBouncer），解决本地 SQLite 无法多实例共享与容易写锁的问题。
   • 提供内置 RLS（行级安全）与自动生成的 REST API，前端控制台可直连 Supabase 安全拉取 Token 用量报表与图表数据。
5. 账号执行层：保留独立 VPS / Spot 实例上的 CPA
   • 上游 Provider（OpenAI/Claude/Grok）的 OAuth 登录、刷新握手和 CLI 进程必须维持原生网络和持久化进程。
   • 专心充当纯粹的私网上游 Adapter，对公网完全不可见。

十二、v1 事实模型与后续演进边界

以下云原生拓扑仅作为未来拆分参考；v1 的事实拓扑仍是“Caddy → New API → CPA”与“Caddy → LiteLLM”，且 Caddy 是唯一公网 HTTPS 入口。

AI 聚合服务体系确立了“凭据平面（Vault）”与“声明平面（GitOps）”严格解耦的两平面原则，同时在运行时建立“边缘调度路由引擎”与“账号执行引擎”的双引擎映射。

1. 总体架构拓扑图

                                     [ 用户终端 (IDE / Web / 开发者) ]
                                                    │
                                                    │ HTTPS: https://ai.svc.plus
                                                    ▼
                     ┌─────────────────────────────────────────────────────────────┐
                     │                 Cloudflare 边缘分流引擎                     │
                     │  - Cloudflare Pages: 托管 "Token 配额分析" 前端 Web 控制台     │
                     │  - Cloudflare Workers: 边缘 API 网关、Key 预检、缓存、速率限制  │
                     └──────────────────────────────┬──────────────────────────────┘
                                                    │ mTLS / 内部签名
                                                    ▼
                     ┌─────────────────────────────────────────────────────────────┐
                     │              GCP Cloud Run (Serverless Gateway)             │
                     │  - 运行 New API (容器化)，支持自动缩容至 0 (Scale to zero)   │
                     │  - 模型稳定别名映射 (codex-main, claude-main, grok-main)    │
                     │  - 协议原生转发 (/v1/responses, /v1/messages, /v1/chat)     │
                     │  - 凭据集成：GCP Secret Manager / Vault                    │
                     └───────────────┬─────────────────────────────┬───────────────┘
                                     │                             │
                                     │ PostgreSQL 连接池            │ WireGuard / 加密私网隧道
                                     ▼                             ▼
   ┌───────────────────────────────────────────────┐     ┌─────────────────────────────────────┐
   │         Supabase Cloud (Free Tier)            │     │       VPS 账号执行引擎 (CPA)         │
   │  - 托管 PostgreSQL 数据库 (替代本地 SQLite)      │     │  - 必须常驻 VPS (账号执行层)         │
   │  - Token 配额、7 天滚动用量、缓存命中时序分析     │     │  - 1:1:1:1 账号隔离 (单实例单账号)   │
   │  - Row Level Security (RLS) & REST API        │     │  - 节点加密 auth + 动态 JWT         │
   │  - 为 Cloudflare Pages 前端直接提供用量查询   │     │  - CPA 仅内网绑定，对外零暴露        │
   └───────────────────────────────────────────────┘     └─────────────────────────────────────┘

2. 两平面职责矩阵

3. 双引擎映射与数据流

• 引擎一：边缘调度路由引擎 (Edge Routing Engine)
  • 由 Cloudflare Pages + Cloudflare Workers + GCP Cloud Run / VPS Caddy 构成。
  • 职责：处理域名绑定（ai.svc.plus）、静态前端资产分发、客户端 API Key 格式校验、速率限制、防刷防御与模型别名路由。
  • 数据流向：客户端请求到达边缘后，Worker 将 API 流量无损送达 New API，同时前台静态看板通过只读匿名 Key 直连 Supabase 获取可视化时序图表。
• 引擎二：账号适配执行引擎 (Account Execution Engine)
  • 由 VPS 上的 CLIProxyAPI (CPA) 实例群 + CodeAgent CLI 构成。
  • 职责：作为 OpenAI/Codex、Anthropic/Claude、xAI/Grok 的底层协议适配器与账号池管理器。
  • 数据流向：CPA 从本节点加密 auth 目录读取账号凭据，与上游模型供应商握手；New API 使用 Vault 私钥动态签发实例级短期 JWT，CPA 仅用公钥校验，完全隐藏在私网中，不对公网开放任何管理入口。

十三、实施闭环与当前状态

交付顺序固定为：

1. 先提交 knowledge、GitOps、playbooks、Terraform contract 和 toolkit 的文档/配置变更。
2. PR 阶段执行 YAML、Vault 引用、CPA 矩阵、Terraform、Ansible、Caddy 模板和 secret scan。
3. 合并后仅在显式开启 AI_AGGREGATOR_UAT_ENABLED=true 且已配置 AWS/Vault/OIDC 变量时自动创建 AWS ARM64 Spot UAT。
4. UAT 使用本地 Terraform state，流水线结束或失败时执行 destroy；实例自身在 60 分钟内自动关机并终止。
5. CPA OAuth 必须人工登录；完成后人工确认本地加密 auth、New API channel、协议 smoke test，再启用 provider；不执行 Vault 写回。
6. Prod 只允许受保护环境手动触发 Ansible，复用既有持久节点，不执行 Terraform 创建、替换或销毁。

当前本地实现状态：

• 已完成：四仓库的非敏感契约、systemd/Caddy/Vault 注入模板、CPA 一实例一账号矩阵、AWS Spot UAT contract、Vultr/GCP adapter contract、manifest validator 和流水线骨架。
• 尚未声称完成：远端 PR/CI 全绿、真实 UAT 创建、Vault role 配置、制品 SHA-256 锁定、私网连通、OAuth 登录、New API channel 初始化、协议和备份恢复验收。
• 发生失败时，先保留旧 Caddy 配置；回滚步骤为恢复上一版本模板与 channel 声明、执行 caddy validate、reload，必要时将入口切回原 LiteLLM upstream。