适用范围

本文面向 Linux 桌面/服务器的用户态部署（systemd --user），不依赖 root 级 system service。
基于当前机器实际运行方式整理：systemctl --user cli-proxy-api。

1. 下载与准备

  1. CLI Proxy API 二进制发布页：
    https://github.com/router-for-me/CLIProxyAPI/releases
  2. 管理界面 management.html 发布页：
    https://github.com/router-for-me/Cli-Proxy-API-Management-Center/releases

2. 当前部署结构（参考）

  • systemd 用户服务文件：~/.config/systemd/user/cli-proxy-api.service
  • 可执行文件：~/.local/bin/cli-proxy-api
  • 配置目录：~/.cli-proxy-api
  • 配置文件：~/.cli-proxy-api/config.yaml
  • 管理页面文件：~/.cli-proxy-api/static/management.html

3. 安装步骤（可复现流程）

3.1 创建目录

mkdir -p ~/.local/bin
mkdir -p ~/.cli-proxy-api/static
mkdir -p ~/.config/systemd/user

3.2 安装二进制

  1. 从发布页下载与你系统匹配的 Linux 二进制（例如 x86_64）。
  2. 将文件放置为 ~/.local/bin/cli-proxy-api。
  3. 授予执行权限：
chmod +x ~/.local/bin/cli-proxy-api

3.3 安装管理页面

  1. 从管理中心发布页下载 management.html
  2. 放置到：~/.cli-proxy-api/static/management.html

3.4 创建配置文件 ~/.cli-proxy-api/config.yaml

密钥安全

先用模板落地，再按实际模型供应商补齐。不要把明文密钥提交到 Git。

port: 8317

tls:
  enable: false

remote-management:
  allow-remote: true
  secret-key: "<bcrypt-hash>"
  disable-control-panel: false
  panel-github-repository: https://github.com/router-for-me/Cli-Proxy-API-Management-Center

auth-dir: /home/dev/.cli-proxy-api

api-keys:
  - "<client-api-key>"

debug: false
pprof:
  enable: false
  addr: 127.0.0.1:8316

commercial-mode: false
logging-to-file: false
logs-max-total-size-mb: 0
error-logs-max-files: 10
usage-statistics-enabled: true
force-model-prefix: false
request-retry: 3
max-retry-interval: 30

quota-exceeded:
  switch-project: true
  switch-preview-model: true

routing:
  strategy: round-robin

ws-auth: false
nonstream-keepalive-interval: 0

claude-api-key: []
codex-api-key: []
gemini-api-key: []

3.5 创建 systemd 用户服务 ~/.config/systemd/user/cli-proxy-api.service

[Unit]
Description=CLI Proxy API - OpenAI/Gemini/Claude Compatible Proxy Server
After=network-online.target
Wants=network-online.target

[Service]
# 如需代理再保留以下三行；不需要可删除
Environment="ALL_PROXY=http://127.0.0.1:7890"
Environment="HTTP_PROXY=http://127.0.0.1:7890"
Environment="HTTPS_PROXY=http://127.0.0.1:7890"

Type=simple
ExecStart=%h/.local/bin/cli-proxy-api -config %h/.cli-proxy-api/config.yaml
Restart=on-failure
RestartSec=5s

# 安全加固
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=strict
ReadWritePaths=%h/.cli-proxy-api

# 资源限制
LimitNOFILE=65536

[Install]
WantedBy=default.target

3.6 启动并设置用户级自启

systemctl --user daemon-reload
systemctl --user enable --now cli-proxy-api

如果你希望在登出后服务仍可继续运行，可额外启用 linger：

loginctl enable-linger "$USER"

4. 验证

4.1 查看服务状态

systemctl --user status cli-proxy-api --no-pager

4.2 检查管理页

curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:8317/management.html

返回 200 说明管理页面可访问。

4.3 检查 API 端点

curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:8317/v1/models

未携带鉴权时返回 401 属于正常现象。

5. 常用运维命令

systemctl --user restart cli-proxy-api
systemctl --user stop cli-proxy-api
journalctl --user -u cli-proxy-api -n 100 --no-pager
journalctl --user -u cli-proxy-api -f

6. 常见问题排查

  1. 服务起不来
  • 先看状态：systemctl --user status cli-proxy-api --no-pager
  • 再看日志：journalctl --user -u cli-proxy-api -n 100 --no-pager
  • 常见原因：二进制无执行权限、config.yaml 缩进错误、代理环境变量不可达。
  1. 管理页返回非 200
  • 确认 ~/.cli-proxy-api/static/management.html 是否存在。
  • 确认监听端口与 config.yaml 的 port 一致。
  1. API 返回 401
  • 对 /v1/models 未携带 key 时返回 401 是预期行为，不代表服务异常。

7. 安全建议

  • 将 remote-management.allow-remote 仅在必要时开启。
  • secret-key 使用强口令生成并妥善保管。
  • config.yaml 中的 API Key 建议使用最小权限、定期轮换。
  • 将 ~/.cli-proxy-api 加入备份策略，但避免把敏感字段明文同步到公开仓库。