Skip to content

Reverse Proxy CPA and CPA Manager Plus with the Same Domain Chinese

Jump to bottom
seakee edited this page Jun 5, 2026 · 2 revisions

本文介绍如何使用同一个域名同时访问：

  • CPA Manager Plus 面板：https://your-domain.com/management.html
  • CPA / CLI Proxy API：https://your-domain.com/v1/...
  • CPA OAuth 回调、Codex API、Amp 路由等 CPA 侧接口

适用于 CPA Manager Plus 的 Full Docker mode / Manager Server mode。

如果你使用的是 CPA panel mode，也就是直接由 CPA 托管 /management.html，则不需要本文的混合反代配置。本文主要面向 CPAMP 独立运行在 18317，CPA 独立运行在 8317 的部署方式。

一、基本架构

推荐架构如下：

Browser
  └── https://your-domain.com
        ├── /management.html       -> CPA Manager Plus :18317
        ├── /usage-service/*       -> CPA Manager Plus :18317
        ├── /v0/management/*       -> CPA Manager Plus :18317
        │                              ├── CPAMP 自己处理 usage / model-prices / aliases /
        │                              │   dashboard / monitoring / codex-inspection 等接口
        │                              └── 其他管理接口由 CPAMP 继续代理到 CPA
        └── /v1/*、/backend-api/*   -> CPA :8317

也就是说：

  • 管理面板、使用统计、请求监控、模型价格、API Key 别名、服务端巡检等 CPAMP 能力走 CPA Manager Plus
  • 普通 API 请求、Codex API、OAuth callback、CPA 新增接口兜底走 CPA
  • 用户访问同一个域名，但 Nginx 根据路径分流到不同后端

二、前置要求

1. CPA 与 CPAMP 是两个服务

CPA Manager Plus 不包含 CPA 本体。你需要单独运行 CPA / CLI Proxy API。

常见端口：

CPA / CLI Proxy API:     8317
CPA Manager Plus:        18317

2. CPA 需要开启 Management API

CPA 配置中至少需要开启：

remote-management:
  secret-key: "你的 CPA Management Key"
  allow-remote: true

两个容器即使在同一个 Docker network 内，CPA 看到的访问来源也通常不是 localhost，所以 allow-remote: true 是必要的。

3. 推荐 CPA 版本

建议使用较新的 CPA 版本。请求监控依赖 CPA usage queue：

  • 推荐 CPA：v7.1.39+
  • HTTP usage queue 最低要求：v6.10.8+

旧版本可能仍能使用基础管理功能，但请求监控、用量采集、部分请求元数据可能不完整。

三、Docker Compose 示例

下面示例假设：

  • CPA 服务名为 cli-proxy-api
  • CPAMP 服务名为 cpa-manager-plus
  • Nginx 与两个服务在同一个 Docker network 中
  • 对外只暴露 Nginx 的 80 / 443 
services:
  cli-proxy-api:
    image: your-cpa-image:latest
    container_name: cli-proxy-api
    restart: unless-stopped
    volumes:
      - ./cliproxyapi/config.yaml:/app/config.yaml
      - ./cliproxyapi/auths:/app/auths
      - ./cliproxyapi/logs:/app/logs
    expose:
      - "8317"

  cpa-manager-plus:
    image: seakee/cpa-manager-plus:latest
    container_name: cpa-manager-plus
    restart: unless-stopped
    volumes:
      - ./cpa-manager-plus-data:/data
    expose:
      - "18317"
    depends_on:
      - cli-proxy-api

  nginx:
    image: nginx:alpine
    container_name: cpa-nginx
    restart: unless-stopped
    ports:
      - "80:80"
      # 如果使用 HTTPS，可以再暴露 443
      # - "443:443"
    volumes:
      - ./nginx/conf.d:/etc/nginx/conf.d:ro
      # 如果使用 HTTPS，挂载证书目录
      # - ./nginx/ssl:/etc/nginx/ssl:ro
    depends_on:
      - cli-proxy-api
      - cpa-manager-plus

如果 CPA 已经在宿主机运行，也可以不把 CPA 写入 compose，只需要把 Nginx upstream 改成宿主机可访问的地址。

四、Nginx 配置

1. HTTP 示例

在 nginx.conf 的 http {} 块中加入：

map $http_upgrade $connection_upgrade {
    default upgrade;
    ''      close;
}

然后在站点配置中加入：

upstream cpa_api {
    server cli-proxy-api:8317;
}

upstream cpamp {
    server cpa-manager-plus:18317;
}

server {
    listen 80;
    server_name your-domain.com;

    client_max_body_size 64m;

    proxy_http_version 1.1;
    proxy_read_timeout 3600s;
    proxy_send_timeout 3600s;
    proxy_buffering off;

    proxy_set_header Host              $host;
    proxy_set_header X-Real-IP         $remote_addr;
    proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header Upgrade           $http_upgrade;
    proxy_set_header Connection        $connection_upgrade;

    # 默认进入 CPAMP 面板
    location = / {
        return 302 /management.html;
    }

    # ===== CPA Manager Plus =====

    location = /management.html { proxy_pass http://cpamp; }
    location = /health          { proxy_pass http://cpamp; }
    location = /status          { proxy_pass http://cpamp; }
    location = /setup           { proxy_pass http://cpamp; }

    # CPAMP 兼容接口与运行时接口
    location ^~ /usage-service/ { proxy_pass http://cpamp; }

    # /v0/management/* 先进入 CPAMP：
    # - usage / model-prices / api-key-aliases / dashboard / monitoring /
    #   codex-inspection / import-export 等由 CPAMP 自己处理
    # - 其他 CPA 管理接口由 CPAMP 使用服务端保存的 CPA Management Key 继续代理到 CPA
    #
    # 注意：不要只配置 location = /v0/management
    # 应使用带尾斜杠的前缀匹配 /v0/management/
    location ^~ /v0/management/ { proxy_pass http://cpamp; }

    # /models 由 CPAMP 提供兼容代理
    # 如果 CPAMP 尚未完成 setup，访问此路径可能返回 412
    location = /models          { proxy_pass http://cpamp; }

    # ===== CPA / CLI Proxy API =====

    # OpenAI / Claude Code / Codex 等实际 API 请求应直接走 CPA
    location ^~ /v1/                 { proxy_pass http://cpa_api; }
    location ^~ /v1beta/             { proxy_pass http://cpa_api; }
    location ^~ /backend-api/codex/  { proxy_pass http://cpa_api; }
    location ^~ /api/                { proxy_pass http://cpa_api; }

    # CPA 特殊路由与 OAuth callback
    location = /v1internal:method    { proxy_pass http://cpa_api; }
    location = /healthz              { proxy_pass http://cpa_api; }
    location = /anthropic/callback   { proxy_pass http://cpa_api; }
    location = /codex/callback       { proxy_pass http://cpa_api; }
    location = /google/callback      { proxy_pass http://cpa_api; }
    location = /antigravity/callback { proxy_pass http://cpa_api; }

    # 兜底给 CPA
    # 用于 CPA 根路径、Amp 路由以及未来新增接口
    location / {
        proxy_pass http://cpa_api;
    }
}

2. HTTPS 示例

HTTPS 只需要调整监听和证书，location 分流规则保持不变：

server {
    listen 443 ssl http2;
    server_name your-domain.com;

    ssl_certificate     /etc/nginx/ssl/your-domain.com/fullchain.pem;
    ssl_certificate_key /etc/nginx/ssl/your-domain.com/privkey.pem;

    # 其余 proxy_set_header、location 配置同上
}

server {
    listen 80;
    server_name your-domain.com;
    return 301 https://$host$request_uri;
}

3. 如果 Nginx 跑在宿主机

如果 Nginx 不在 Docker network 里，而是直接运行在宿主机上，可以把 upstream 改成宿主机端口：

upstream cpa_api {
    server 127.0.0.1:8317;
}

upstream cpamp {
    server 127.0.0.1:18317;
}

前提是 CPA 与 CPAMP 都已经把端口映射到宿主机：

ports:
  - "8317:8317"
ports:
  - "18317:18317"

五、CPAMP 首次 setup 应该怎么填

访问：

https://your-domain.com/management.html

首次 setup 需要填写：

Admin Key:             CPAMP 启动日志中的 cmp_admin_...
CPA URL:               http://cli-proxy-api:8317
CPA Management Key:    CPA remote-management.secret-key

注意：

  • 登录 CPAMP 面板用的是 CPAMP Admin Key
  • CPA Management Key 是 CPAMP 服务端访问 CPA 时使用的，不再需要浏览器直接保存
  • CPA URL 推荐填写 Docker 内网地址：http://cli-proxy-api:8317
  • 不推荐在 CPA URL 里填写当前公网域名，否则会形成“CPAMP -> Nginx -> CPAMP/CPA”的回环代理链路，排障更复杂

如果 CPAMP 是直接跑在宿主机上，CPA URL 可以填写：

http://127.0.0.1:8317

如果 CPAMP 在 Docker 内、CPA 在宿主机上，Docker Desktop 可以尝试：

http://host.docker.internal:8317

Linux Docker 环境则建议把 CPA 和 CPAMP 放到同一个 Docker network，使用服务名访问。

六、验证配置

配置完成后可以按顺序验证：

# 1. CPAMP 面板能打开
curl -I https://your-domain.com/management.html

# 2. CPAMP 健康检查
curl -i https://your-domain.com/health

# 3. CPA 健康检查
curl -i https://your-domain.com/healthz

# 4. CPAMP 运行时信息
curl -i https://your-domain.com/usage-service/info

# 5. CPA API 请求，应该命中 CPA
curl -i https://your-domain.com/v1/models \
  -H "Authorization: Bearer 你的 API Key"

# 6. CPAMP 代理的管理接口，应该先命中 CPAMP，再由 CPAMP 访问 CPA
curl -i https://your-domain.com/v0/management/config \
  -H "Authorization: Bearer 你的 CPAMP Admin Key"

七、常见问题

1. /management.html 能打开，但 setup 保存 CPA 地址失败

优先检查 CPAMP 容器是否能访问 CPA：

docker exec -it cpa-manager-plus sh
wget -O- http://cli-proxy-api:8317/healthz

如果不通，检查：

  • CPA 和 CPAMP 是否在同一个 Docker network
  • CPA 是否监听 0.0.0.0:8317
  • 服务名是否真的是 cli-proxy-api
  • CPA 容器是否正常启动
  • CPA 的 remote-management.allow-remote 是否为 true

2. 登录时应该填哪个 key？

CPAMP Full Docker mode 下：

登录面板：填 CPAMP Admin Key
连接 CPA：填 CPA Management Key
普通 API 请求：填 CPA API Key

不要混用这三个 key。

3. /models 返回 412

通常说明 CPAMP 尚未完成首次 setup。

先访问：

https://your-domain.com/management.html

完成 setup 后再重试。

4. 请求监控没有数据

按顺序检查：

  1. CPA Management API 是否启用
  2. CPA Management Key 是否正确
  3. CPAMP 中是否开启请求监控
  4. CPA 是否启用了 usage publishing
  5. CPA 版本是否支持 HTTP usage queue
  6. 是否有多个 CPAMP / Usage Service 同时消费同一个 CPA usage queue
  7. CPAMP 是否持续运行，避免队列数据过期

5. /v1/models 返回 401

/v1/models 是 CPA API 路由，不是 CPAMP 管理接口。

这里应该使用普通 API Key：

curl -i https://your-domain.com/v1/models \
  -H "Authorization: Bearer 你的 API Key"

不要使用 CPAMP Admin Key 或 CPA Management Key。

6. /v0/management/config 返回 401

这个路径在本文方案中会先进入 CPAMP。

Full Docker mode 下，浏览器侧登录使用的是 CPAMP Admin Key。 如果手动 curl 管理接口，也应优先使用 CPAMP Admin Key：

curl -i https://your-domain.com/v0/management/config \
  -H "Authorization: Bearer 你的 CPAMP Admin Key"

7. Nginx 配好后部分 CPA 新接口不可用

确认最后有兜底规则：

location / {
    proxy_pass http://cpa_api;
}

这样 CPA 新增的普通接口不会因为 Nginx 未显式配置 location 而被拦截。

八、是否需要把 /config、/logs、/auth-files 也转给 CPAMP？

一般不需要先手动加。

推荐先只配置：

location ^~ /v0/management/ { proxy_pass http://cpamp; }
location ^~ /usage-service/ { proxy_pass http://cpamp; }

如果实际使用中发现 CPAMP 面板中的配置、日志、认证文件等页面出现 401 / 404，再根据具体路径补充精确规则。

不建议一开始就把所有不确定路径都转给 CPAMP，否则可能影响 CPA 原生接口或未来新增路由。

九、推荐结论

同域名反代 CPAMP 的核心原则是：

CPAMP 明确接管的面板与管理路径 -> CPAMP :18317
CPA API、OAuth callback、Codex API、新增未知路径 -> CPA :8317

最重要的路径分流是：

/management.html        -> CPAMP
/usage-service/*        -> CPAMP
/v0/management/*        -> CPAMP
/v1/*                   -> CPA
/backend-api/codex/*    -> CPA
OAuth callback          -> CPA
其他兜底路径             -> CPA

这样既可以使用同一个域名访问 CPAMP 面板，也可以继续把同一个域名作为 CPA API Base URL 使用。

CPA Manager Plus Wiki

English

Start

Operations

中文

开始

运维

Links

Clone this wiki locally