大模型代理网关搭建指南：基于 CLIProxyAPI 的企业级反代实践本文详细记录了如何在 Linux 服务器上基于 C

背景说明

1. 为什么需要大模型代理网关 (CLIProxyAPI)？

在日常开发与业务场景中，我们经常需要在不同的终端和应用里调用大模型能力。与其在每个客户端单独配置和维护 API Key、处理网络请求，不如将模型能力统一反向代理并代理分发出去。 通过代理网关，我们能够将大模型能力打造成一个集中的基础设施模块，随时随地接入到“需要用的地方”，实现统一路由、管理和负载均衡。

[!info]- 主要优势通过反代，可以组建账号池，通过每个账号token额度的叠加，实现大模型自由

2. 解决网络问题？

在服务器上部署时，由于 Linux 服务器通常处于纯 CLI（命令行）环境，没有图形化界面，这就导致主流的桌面端代理软件（如 Clash Verge 等）根本无法部署和运行。而 虚空终端 完美解决了这个痛点：

纯粹的无头模式 (Headless)：它天生为服务器而生，作为后台常驻服务极度稳定。
友好的 Web 控制台：配合 metacubexd 等 Web UI 前端，可以直接脱离客户端，在浏览器里获得一致且强大的可视化运维体验，解决 Linux 命令行测速和切节点的痛苦。

CLIProxyAPI 搭建

[!info] 服务定位:高性能大模型路由与代理网关，提供 OpenAI 格式的统一 API 抽象、多提供商负载均衡、认证控制以及后台管理能力。

1. 基础环境架构表

组件名称	路径/参数	备注
服务器IP	`10.162.30.141`	内网地址
工作目录	`/home/induschain/cliproxyapi/`	包含主程序及配置文件
核心配置文件	`/home/induschain/cliproxyapi/config.yaml`	修改后必须重启服务生效
Token 存储目录	`~/.cli-proxy-api/` (`/home/induschain/.cli-proxy-api/`)	CPA Auth Tool 生成的认证文件存放处
服务启动项	`/home/induschain/.config/systemd/user/cliproxyapi.service`	`systemd` User 级别进程守护
服务端口	`TCP 8317`	API 暴露及管理后台端口
管理后台入口	`http://10.162.30.141:8317/management.html`	图形化控制面板 (含 OAuth 模型映射等)
管理密钥	`chanlian888!`	配置参数 `secret-key`所配置的值的不等同`api-key`

2. 服务生命周期管理 (Systemd)

该服务以 当前用户 (induschain) 级别注册进 systemd。进行启停操作时不需要 sudo，但必须携带 --user 参数。

重启服务 (最常用：修改 config.yaml 后执行)

systemctl --user restart cliproxyapi.service

查看服务运行状态 (关注有无 active (running) 以及红色 Error)

systemctl --user status cliproxyapi.service

停止服务

systemctl --user stop cliproxyapi.service

启动服务

systemctl --user start cliproxyapi.service

[!IMPORTANT] 进程常驻机制排雷 (Linger) 因为是 User 级别服务，当 induschain 用户注销/断开 SSH 时，服务可能会被 Linux 系统强制杀死。 强制保障措施：使用管理员权限执行一次 sudo loginctl enable-linger induschain，确保即使用户未登录，服务也在后台常驻。

3. 核心配置释义 (`config.yaml`)

运维日常最常修改的是 /home/induschain/cliproxyapi/config.yaml。

网络相关

host: "0.0.0.0"          # 必须为 "" 或 "0.0.0.0" 才能在内网 10.162.30.141 访问

port: 8317               # 服务监听端口

remote-management:

  allow-remote: true     # 🚨 允许非本地 IP(比如你的 Mac) 访问 management.html 后台

  secret-key: "你的密码"   # 🚨 极其重要！必须设置复杂密码，否则管理后台将沦为肉鸡

底层代理配置

[!info] 关联组件此处的底层代理链路，由下文的 [[#代理软件 Mihomo（clash内核）]] 提供网络支持，点击链接可跳转至具体配置说明。

# 如果网关所在服务器无法直连墙外 (如 api.openai.com)，必须配置全局走代理
proxy-url: "http://127.0.0.1:7890"  # 填入本机或旁路路由的科学代理地址

认证鉴权

auth-dir: "~/.cli-proxy-api" # 第三方工具获取的 token 文件存放处

api-keys:
  - "sk-xxxxx"           # 内部业务系统调用当前网关时，需校验的 API Key (可设置多个)

4. 日志观测与排错 (Observability)

方式一：终端实时追踪

可以直接通过 systemd 抓取服务生成的标准输出（追踪并发请求状态，支持 Ctrl+C 退出）：

journalctl --user -u cliproxyapi.service -n 100 -f

方式二：文件落盘分析

如果想将日志持久化方便排查追溯历史记录，修改 config.yaml 开启文件日志：

logging-to-file: true
logs-max-total-size-mb: 1000  # 日志轮转：最多占用 1GB 磁盘，防爆盘
error-logs-max-files: 30

开启后，日志将会落在 /home/induschain/cliproxyapi/logs/ 目录下。

5. 常规运维场景 (Playbook)

场景一：升级 CPA 版本

当官方发布新版本，需执行此标准流程实现丝滑升级：

下载新版本二进制放入 /home/induschain/cliproxyapi/
备份老版本，赋予新版本执行权限：chmod +x cli-proxy-api
无缝平滑重启：systemctl --user restart cliproxyapi.service
查日志验证：journalctl --user -u cliproxyapi.service -n 20

场景二：后台管理密码丢弃/重置

如果忘记了管理后台的密码：

打开 config.yaml。
找到 remote-management -> secret-key。
填入新的明文密码，CPA 读取后会自动哈希加密并在下一次启动时覆盖写入。
重启服务。

场景三：客户端路由不到模型 (`404 Model Not Found`)

当你们的客户端无法找到特定模型，访问 http://10.162.30.141:8317/management.html#/oauth 进入你的管理面板：

检查 Models 面板，看看上游供应池中是否含有该模型。
如果上游只有 claude-3-5-sonnet-20241022，但你的客户端硬编码了 claude-sonnet-latest，你需要在 config.yaml 中利用 alias 将其隐式映射。

[!tip] 最佳实践建议建议将该服务器 IP 固定为内部 DNS 域名（例如 api.gateway.internal），让所有业务方调用 http://api.gateway.internal:8317/v1，避免未来若服务器 IP 变动导致大面积修改配置。

代理软件虚空终端

[!tldr] 核心架构与环境速览 组件栈: mihomo + metacubexd Web UI 网络环境: 代理端口 7890 (mixed) | 管理 API 9090 关键路径:

核心配置: config.yaml

订阅缓存: /etc/mihomo/providers/

WebUI面板: /etc/mihomo/ui/ 后台进程: mihomo.service

1. 核心基线配置 (`config.yaml`)

mixed-port: 7890                 # 核心代理端口
allow-lan: true                  # 允许局域网连接
bind-address: "*"
mode: rule
log-level: info
external-controller: 127.0.0.1:9090 # 管理 API 端口
secret: "改成长随机字符串"            # 🚨 Web UI 登录密钥
external-ui: /etc/mihomo/ui      # UI 静态服务路径

# 自动订阅 provider
proxy-providers:
  mysub:
    type: http
    url: "你的订阅URL"
    path: ./providers/mysub.yaml
    interval: 3600

2. 服务启停标准 SOP

配置变更后的发布流：编辑完文件 -> 检查 -> 制式重启 -> 看日志。

# 日常启停与状态检查
sudo systemctl restart mihomo
sudo systemctl status mihomo --no-pager
sudo journalctl -u mihomo -f -o cat

3. Web UI 安全访问指南

[!warning] 安全准则绝不将 9090 端口直接向公网暴露。

内网环境直连访问: 如果是办公内网环境，浏览器可直接访问 http://10.162.30.141:9090/ui

注: 面板的登录密码对应 config.yaml 内的 secret 字段。

5. 日常运维 SOP

查看运行状态
systemctl status + journalctl -u mihomo -n 100
更新订阅
- WebUI 点 provider Update
- 若异常，命令行强制刷新：

sudo rm -f /etc/mihomo/providers/*.yaml
sudo systemctl restart mihomo

切换策略/节点
在 WebUI 的 Proxy 页面操作，不改主配置结构。

6. 常见故障处理

UI 可开但节点不更新
- 先看 config.yaml 中 url 是否新订阅
- 清 provider 缓存后重启
订阅报 EOF / context deadline exceeded
- 服务器到订阅站网络不通或被限流
- 用 curl -vL --max-time 20 <订阅URL> 验证
- 必要时用 proxy-providers.mysub.proxy 指定经可用节点拉取
重载按钮无效感
- WebUI“重载配置”只重读当前文件，不会替你换订阅来源
- 以 systemctl restart mihomo 为准

大模型代理网关搭建指南：基于 CLIProxyAPI 的企业级反代实践