跳到主要内容
基于 CLIProxyAPI 与 New API 构建统一 AI 中转站实战指南 | 极客日志
Shell / Bash SaaS AI
基于 CLIProxyAPI 与 New API 构建统一 AI 中转站实战指南 通过 CLIProxyAPI 实现多模型统一代理，结合 New API 进行配额管理与标准接口转换。从服务器环境初始化、Systemd 服务配置到 Docker 容器化部署的全流程，涵盖 OAuth 认证、渠道映射及 Cherry Studio 客户端调试，解决网络限制与账户管理难题，构建高可用 AI 分发系统。
JavaCoder 发布于 2026/4/5 更新于 2026/4/25 前言
在大模型应用开发与个人使用场景中，直接调用官方 API 往往面临网络环境受限、账户管理复杂以及非标准接口兼容性差等挑战。CLIProxyAPI 通过模拟命令行交互方式，将 OpenAI、Gemini、Claude 等服务的后端逻辑封装为标准的 API 接口，实现了对异构模型服务的统一代理。本文将结合实际部署案例，详细阐述如何在海外服务器环境构建这一系统，并通过 Docker 容器化技术部署 New API 进行二次分发与配额管理，最终在客户端（如 Cherry Studio）实现全模型的高效调用。
第一部分：基础设施准备与 CLIProxyAPI 的核心部署
构建逆向代理系统的首要前提是拥有一个网络环境纯净且能够稳定访问上游模型服务提供商的基础设施。
1.1 服务器选型与环境初始化
本次部署选用的是腾讯云提供的美国区域云服务器，配置为 2 核 CPU 与 2GB 内存。选择美国节点的核心原因在于大多数主流 LLM 服务商对 IP 地理位置有严格限制，美国原生 IP 或数据中心 IP 通常能获得最佳的连通性与响应速度。
在通过 SSH 协议连接至服务器终端后，我们首先面对的是纯净的 Linux 操作系统环境。为了确保后续软件的顺利安装，建议先执行系统包管理器的更新操作，并安装必要的网络工具（如 curl、wget）和文本编辑器（如 nano 或 vim）。
上图展示了成功登录服务器后的终端界面，系统显示了基本的登录信息与资源使用情况。此时，服务器已准备好接收指令。
1.2 CLIProxyAPI 的自动化安装
CLIProxyAPI 项目提供了一键安装脚本，极大简化了二进制文件的下载与权限配置过程。该脚本通常托管在 GitHub 上，通过 curl 命令可以直接拉取并传输给 bash 解释器执行。
在终端输入以下安装命令：
curl -fsSL https://raw.githubusercontent.com/brokechubb/cliproxyapi-installer/refs/heads/master/cliproxyapi-installer | bash
该命令中的 -fsSL 参数确保了下载过程的静默模式、自动处理重定向以及强制使用 SSL 加密连接，保证了脚本获取的安全性与完整性。
脚本执行完毕后，控制台会输出安装成功的提示信息，并给出了后续的快速开始指引。如上图所示，安装程序自动创建了 /root/cliproxyapi 目录，并提示用户可以通过参数（如 --login、--claude-login）来初始化不同服务商的认证流程。这表明二进制文件已正确放置，且具备了执行权限。
1.3 核心配置文件 config.yaml 的深度定制
安装完成后，必须对默认配置文件进行调整以适应远程访问需求。进入程序目录：
cd /root/cliproxyapi
在该目录下，config.yaml 承载了服务监听、安全认证以及代理行为的关键参数。使用文本编辑器打开该文件。
首要修改的参数是 allow-remote。默认情况下，为了安全起见，该服务可能仅监听本地回环地址（127.0.0.1）。为了让外部客户端或同一内网下的其他服务（如后续的 New API）能够访问此代理，必须将此项设置为 true。
上图清晰地展示了将 allow-remote 字段的值从默认状态修改为 true 的操作细节。
其次，安全认证机制至关重要。secret-key 字段定义了访问管理面板和 API 接口时的全局密钥。这是一个对称加密或简单的访问令牌机制，任何持有此 Key 的客户端都拥有对服务的控制权。因此，必须将其修改为一个高强度的自定义密码。
修改完成后，如上图所示，保存并退出编辑器。至此，基础配置工作已完成。
第二部分：系统服务化管理与故障排查 为了保证 CLIProxyAPI 能够在后台稳定运行，并在服务器重启后自动拉起，将其注册为 systemd 服务是标准且规范的操作流程。
2.1 初始启动尝试与 Systemd 服务注册 systemctl --user enable cliproxyapi.service
如上图所示，如果系统提示无法找到服务单元文件或出现载入错误，这通常意味着安装脚本未自动创建系统级的 service 文件，或者文件路径不符合 systemd 的扫描规则。为了获得更高级别的权限管理与稳定性，推荐手动创建一个系统级的服务文件。
使用编辑器创建 /etc/systemd/system/cliproxyapi.service 文件，并填入以下内容：
[Unit]
Description =CLIPROXYAPI Service
After =network.target
[Service]
Type =simple
User =root
ExecStart =/root/cliproxyapi/cli-proxy-api
Restart =on -failure
RestartSec =5 s
[Install]
WantedBy =multi-user.target
该配置文件定义了服务的启动顺序（网络就绪后）、运行用户（root）、执行路径以及失败重启策略。
2.2 服务启动失败的深度分析与路径修正 在创建完服务文件后，执行以下命令重载配置并启动服务：
systemctl daemon-reload
systemctl enable cliproxyapi.service
systemctl start cliproxyapi.service
虽然控制台显示启动命令执行成功（如上图），但这并不代表进程正在正常运行。通过 systemctl status cliproxyapi.service 查看状态时，可能会发现服务处于'Active: activating (auto-restart)'或迅速退出的状态。
上图揭示了服务启动后迅速退出的异常状态。这类问题的根源通常在于**工作目录（Working Directory）或 配置文件路径（Configuration Path）**的缺失。当程序通过 systemd 启动时，其默认工作目录通常是根目录 /，而不是程序所在的 /root/cliproxyapi。程序试图读取 config.yaml，但在根目录下无法找到该文件，导致初始化失败并退出。
cd /root/cliproxyapi
ls -la
上图确认了 config.yaml 确实位于 /root/cliproxyapi 目录下。
2.3 修正 Systemd 配置与服务恢复 解决此问题的最佳实践是在 ExecStart 启动命令中显式指定配置文件的绝对路径，而非依赖程序的默认相对路径寻找机制。
再次编辑 /etc/systemd/system/cliproxyapi.service 文件，修改 ExecStart 行：
ExecStart =/root/cliproxyapi/cli-proxy-api --config /root/cliproxyapi/config.yaml
上图展示了修改后的服务文件内容。显式指定 --config 参数消除了路径歧义。随后重启服务：
systemctl daemon-reload
systemctl restart cliproxyapi.service
systemctl status cliproxyapi.service
此时，如上图所示，服务状态显示为绿色的 active (running)，且持续时间正常，表明守护进程已稳定运行。
第三部分：Web 管理界面的访问与 OAuth 认证集成 服务启动后，CLIProxyAPI 会在指定端口（默认为 8317）提供 Web 管理界面，用于后续的账号绑定与配额查看。
3.1 网络防火墙配置 在尝试从浏览器访问之前，必须确保服务器的防火墙（Security Group）已放行 TCP 协议的 8317 端口。
上图展示了在云服务商控制台添加防火墙规则的操作，源地址设为 0.0.0.0/0 意味着允许来自任何 IP 的访问，端口指向 8317。
3.2 仪表盘登录与功能概览 在浏览器地址栏输入 http://服务器 IP:8317/management.html。系统会弹出一个简单的登录框，此时输入在 config.yaml 中设置的 secret-key。
验证通过后，将进入系统仪表盘。该界面提供了直观的账号管理、配额监控和系统设置功能。
3.3 Google OAuth 认证流程 为了能够代理 Gemini 等 Google 系模型，必须完成 OAuth 2.0 认证流程。在左侧菜单找到 OAuth 登录选项。
点击后，系统会生成一个认证链接。复制该链接并在浏览器中打开，此时会跳转至 Google 的官方登录页面。
在 Google 账号登录并授权应用权限后，浏览器最终会跳转到一个包含回调参数（code=…）的 URL。如果是在无头服务器或非本地环境操作，浏览器可能会显示无法连接，但这不影响，我们需要的是地址栏中的完整 URL。
复制该回调 URL，返回 CLIProxyAPI 的管理界面，将其粘贴到指定的输入框中并提交。
系统解析回调参数后，完成 Token 的交换与存储。
认证成功后，在配额中心（Quota Center）可以看到当前账号的可用余额或请求限制情况，这标志着与上游服务的链路已经打通。
3.4 Gemini CLI Project ID 的关联 对于 Gemini 模型，还需要关联 Google Cloud Platform (GCP) 的 Project ID。访问 Google Cloud Console 创建一个新项目或选择现有项目。
复制项目 ID，回到 CLIProxyAPI 界面，找到 Gemini CLI OAuth 登录入口。
再次执行类似的 OAuth 流程，将回调 URL 填入后，Gemini 服务的特定鉴权即告完成。
第四部分：基于 Docker 的数据持久化与 New API 部署 CLIProxyAPI 仅提供了底层的代理通道，为了实现多渠道聚合、令牌分发、计费管理以及标准 OpenAI 格式的完美兼容，引入 New API 是架构升级的关键一步。考虑到部署的便捷性与环境隔离，我们采用 Docker 容器化方案。
4.1 MySQL 数据库容器化部署 New API 需要关系型数据库来存储用户、令牌和日志数据。MySQL 8.0 是一个稳定且兼容性良好的选择。
执行以下 Docker 命令启动 MySQL 容器：
docker run --name new-api-mysql -d --restart always \
-p 3306:3306 \
-e MYSQL_ROOT_PASSWORD=你的数据库密码 \
-e MYSQL_DATABASE=你的数据库名 \
-e TZ=Asia/Shanghai \
-v /your/mysql/data/path:/var/lib/mysql \
mysql:8.0
该命令通过 -v 参数实现了数据的宿主机持久化，防止容器删除后数据丢失；-e 参数配置了时区和数据库初始凭证。
上图显示 MySQL 容器 ID 已生成，表明启动成功。同时，务必在云服务器防火墙中放行 3306 端口，以便 New API 容器（如果不在同一 Docker 网络）或外部工具连接。
4.2 New API 中台系统部署 接下来部署 New API 容器，并通过环境变量配置数据库连接字符串（DSN）。
docker run --name new-api -d --restart always \
-p 3000:3000 \
-e SQL_DSN="root:你的密码@tcp(服务器内网 IP:3306)/数据库名" \
-e TZ=Asia/Shanghai \
-v /new-api/data:/data \
calciumion/new-api:latest
注意 SQL_DSN 中的 IP 地址。由于 MySQL 和 New API 是两个独立的容器，若未配置 Docker Compose 网络，建议使用宿主机的内网 IP（如 172.17.0.1 通常是 Docker 桥接网关地址）或公网 IP 来确保连接可达。
启动成功后，同样需要在防火墙放行 3000 端口，这是 New API 的默认服务端口。
第五部分：New API 的初始化配置与渠道映射 通过浏览器访问 http://IP:3000 进入 New API 的前端界面。
5.1 系统初始化 在此步骤中，设置系统管理员（root）的账号与密码。
选择运营模式。如果是个人自用或小范围分享，选择'对外运营模式'可以开启更多配额管理功能。
5.2 添加 CLIProxyAPI 渠道 New API 的核心功能是将上游的 API 转化为标准的 OpenAI 接口。我们需要将之前搭建的 CLIProxyAPI 作为'渠道'添加进来。
首先，回到 CLIProxyAPI 的管理界面，复制 API Key。
在 New API 面板左侧选择'渠道管理'，点击'添加渠道'。
类型 ：通常选择 OpenAI（因为 CLIProxyAPI 输出的是兼容接口）。代理地址 ：填写 http://你的 IP:8317。密钥 ：填入刚才复制的 CLIProxyAPI Key。 点击'获取模型列表'，系统会自动探测上游支持的模型。
勾选需要暴露给客户端的模型，并进行模型分组（例如归类为 "gemini" 或 "claude"）。
5.3 创建访问令牌 (Token) 为了让客户端软件连接 New API，需要创建一个令牌。在'令牌管理'页面添加新令牌，设置额度和过期时间。
第六部分：客户端集成与全链路调试 (Cherry Studio) 最后一步是使用现代化的 LLM 客户端 Cherry Studio 进行连接测试，验证整条链路的连通性与兼容性。
6.1 客户端基础配置 打开 Cherry Studio，进入设置页面。添加一个新的服务商，类型选择'OpenAI'（因为 New API 均已转为 OpenAI 标准）。
API 域名 ：填写 New API 的地址 http://你的 IP:3000。API 密钥 ：填写 New API 生成的令牌。
6.2 模型列表同步与倍率修正 点击模型管理旁边的刷新按钮。此时可能会遇到只识别到极少数模型的情况。
这是因为 New API 默认仅向客户端透出已配置了价格倍率的模型。回到 New API 系统设置，进入'分组与模型定价设置'，找到'未设置倍率模型'区域。将新模型添加进去，或者为特定模型设置倍率。
应用更改后，再次在 Cherry Studio 中刷新模型列表，此时所有已配置的模型均应出现。
6.3 协议兼容性与参数调试 进行对话测试。如果使用 GPT 系列模型，通常能直接回复。
但当切换至 Claude 等非原生 OpenAI 模型时，可能会遇到报错。
这是因为客户端可能默认尝试使用 Anthropic 的原生协议。在 Cherry Studio 的模型设置中，必须强制将该模型的调用协议指定为'OpenAI'，因为 New API 已经完成了格式转换。
6.4 特殊模型的参数映射处理 对于某些带有特殊功能（如 Thinking 思考模式）的模型，如 gemini-claude-opus-4-5-thinking，可能会出现参数错误。
这通常是因为 New API 未能识别该特殊模型名称，导致转发参数时字段缺失。解决方法是在 New API 的'系统设置' -> '模型相关设置'中，手动将该模型名称添加到白名单或映射列表中。
保存设置后，再次发起请求，所有参数即被正确透传，问题解决。
结语 通过上述六大步骤，我们成功构建了一套高可用的企业级大模型逆向代理与分发系统。该架构不仅解决了单一模型服务的访问限制问题，还通过 New API 实现了多源模型的统一标准化输出、计费与权限控制。从底层的 Linux 服务配置到上层的应用调试，每一个环节的精细调整都确保了系统的稳定性与扩展性，为后续接入更多 AI 能力奠定了坚实基础。
相关免费在线工具 RSA密钥对生成器 生成新的随机RSA私钥和公钥pem证书。 在线工具，RSA密钥对生成器在线工具，online
Mermaid 预览与可视化编辑 基于 Mermaid.js 实时预览流程图、时序图等图表，支持源码编辑与即时渲染。 在线工具，Mermaid 预览与可视化编辑在线工具，online
随机西班牙地址生成器 随机生成西班牙地址（支持马德里、加泰罗尼亚、安达卢西亚、瓦伦西亚筛选），支持数量快捷选择、显示全部与下载。 在线工具，随机西班牙地址生成器在线工具，online
Base64 字符串编码/解码 将字符串编码和解码为其 Base64 格式表示形式即可。 在线工具，Base64 字符串编码/解码在线工具，online
Base64 文件转换器 将字符串、文件或图像转换为其 Base64 表示形式。 在线工具，Base64 文件转换器在线工具，online
Markdown转HTML 将 Markdown（GFM）转为 HTML 片段，浏览器内 marked 解析；与 HTML转Markdown 互为补充。 在线工具，Markdown转HTML在线工具，online
