CLIProxyAPI（七）：自动化运维——配额监控与告警

本文是 CLIProxyAPI 系列教程第七篇，聚焦于使用脚本和定时任务对 CLIProxyAPI 进行自动化运维监控。

系列目录

1. （一）入门——把 CLI 订阅变成标准 API
2. （二）多账号轮询与配额策略
3. （三）接入主流 AI 编程工具
4. （四）生产部署——Nginx、TLS 与安全加固
5. （五）Antigravity——用 Google 订阅解锁 Claude Opus 4.8
6. （六）结合 new-api 打造多用户 API 网关
7. （七）自动化运维——配额监控与告警（本文）
8. （八）cpa_keeper 与 cpa_cost——用量追踪与成本分析工具

前言

CLIProxyAPI 跑起来之后，很多用户就不再管它了——直到某天发现请求突然失败，才意识到某个账号已经悄悄失效了好几个小时。配额耗尽、Token 刷新失败、账号被封禁，这些情况都不会主动通知你。

本篇讲的就是如何在这些问题出现之前发现它们：用脚本轮询管理 API、把状态写入日志或 CSV、出了问题第一时间推送告警，必要时还能自动触发重新登录流程。

1. 为什么需要运维监控

CLIProxyAPI 默认每 5 分钟刷新一次 OAuth Token。刷新失败时，对应账号会被标记为 unavailable，但服务本身不会发出任何通知。常见的静默失效场景：

• 账号密码被修改或会话被踢出，Token 失效
• 账号触发风控，被临时或永久禁用
• 网络波动导致连续多次刷新失败
• 配额用尽，后续请求被拒绝但代理层无感知

如果你只部署了一两个账号，某个账号失效就意味着整体可用性下降 50% 甚至更多。多账号轮询时，负载会集中到剩余健康账号上，进一步加速配额消耗，形成恶性循环。

定时监控的目标是：在这条链断掉之前，先收到告警。

2. 管理 API：查看账号状态

CLIProxyAPI v7.1.45 提供了管理 API，健康监控使用的端点是 GET /v0/management/auth-files，需要在请求头带上 secret-key 认证。

curl -s http://localhost:8317/v0/management/auth-files \
  -H "Authorization: Bearer YOUR_SECRET_KEY" | jq .

典型响应结构如下：

{
  "files": [
    {
      "email": "user1@gmail.com",
      "provider": "antigravity",
      "status": "active",
      "unavailable": false,
      "disabled": false,
      "success": 142,
      "failed": 0,
      "recent_requests": [
        {"time": "11:10-11:20", "success": 12, "failed": 0},
        {"time": "11:20-11:30", "success": 8,  "failed": 0}
      ]
    },
    {
      "email": "user2@gmail.com",
      "provider": "claude",
      "status": "unavailable",
      "unavailable": true,
      "disabled": false,
      "success": 0,
      "failed": 5,
      "recent_requests": []
    }
  ]
}

各字段含义：

unavailable: true 是需要重点关注的状态，表示账号已无法正常使用。

3. 账号健康检测脚本

下面的脚本每次运行时查询管理 API，找出所有非 active 的账号，并触发告警。将它配合 crontab 使用，可以实现定时巡检。

#!/usr/bin/env bash
# check_accounts.sh — CLIProxyAPI 账号健康检测

CPA_HOST="http://localhost:8317"
SECRET_KEY="YOUR_SECRET_KEY"
LOG_FILE="$HOME/cpa/logs/health_check.log"
ALERT_SCRIPT="$HOME/cpa/alert.sh"   # 告警脚本路径，见第5节

mkdir -p "$(dirname "$LOG_FILE")"

timestamp() { date '+%Y-%m-%dT%H:%M:%S%z'; }

log() { echo "[$(timestamp)] $*" | tee -a "$LOG_FILE"; }

# 查询管理 API
response=$(curl -sf \
  -H "Authorization: Bearer $SECRET_KEY" \
  "$CPA_HOST/v0/management/api-key-usage")

if [[ $? -ne 0 || -z "$response" ]]; then
  log "ERROR: Failed to reach management API"
  "$ALERT_SCRIPT" "CLIProxyAPI 管理 API 无响应，请检查服务是否运行"
  exit 1
fi

total_active=$(echo "$response" | jq -r '.total_active')
total_accounts=$(echo "$response" | jq -r '.total_accounts')

log "账号状态巡检：$total_active/$total_accounts 个账号正常"

# 找出所有非 active 的账号
problem_accounts=$(echo "$response" | jq -r \
  '.accounts[] | select(.status != "active") | "\(.email) [\(.status)]"')

if [[ -n "$problem_accounts" ]]; then
  while IFS= read -r account; do
    log "WARN: 账号异常 — $account"
    "$ALERT_SCRIPT" "CLIProxyAPI 账号异常：$account"
  done <<< "$problem_accounts"
fi

# 如果全部账号都失效，发升级告警
if [[ "$total_active" -eq 0 ]]; then
  log "CRITICAL: 所有账号均不可用！"
  "$ALERT_SCRIPT" "CRITICAL: CLIProxyAPI 全部账号失效，服务已中断！" critical
fi

将脚本保存为 ~/cpa/check_accounts.sh 后，赋予执行权限：

chmod +x ~/cpa/check_accounts.sh

4. 用量统计脚本

定期把各账号的请求量写入 CSV，方便后续绘图或成本分析。

#!/usr/bin/env bash
# usage_logger.sh — CLIProxyAPI 用量统计记录

CPA_HOST="http://localhost:8317"
SECRET_KEY="YOUR_SECRET_KEY"
CSV_FILE="$HOME/cpa/logs/usage_$(date '+%Y%m').csv"

# 写入 CSV 表头（仅首次）
if [[ ! -f "$CSV_FILE" ]]; then
  echo "timestamp,auth_index,email,status,recent_requests,total_requests" \
    > "$CSV_FILE"
fi

response=$(curl -sf \
  -H "Authorization: Bearer $SECRET_KEY" \
  "$CPA_HOST/v0/management/api-key-usage")

[[ $? -ne 0 ]] && { echo "API 请求失败" >&2; exit 1; }

ts=$(date '+%Y-%m-%dT%H:%M:%S')

echo "$response" | jq -r --arg ts "$ts" \
  '.accounts[] | [$ts, (.auth_index|tostring), .email, .status,
     (.recent_requests|tostring), (.total_requests|tostring)] | join(",")' \
  >> "$CSV_FILE"

echo "用量数据已追加到 $CSV_FILE"

CSV 文件按月分割，每次运行追加一行。月末可以用以下命令快速汇总：

# 统计本月各账号累计请求量最高值
awk -F',' 'NR>1 {
  if ($6 > max[$3]) max[$3] = $6
} END {
  for (email in max) print email, max[email]
}' /var/log/cpa/usage_$(date '+%Y%m').csv | sort -k2 -rn

5. 告警方案

将告警逻辑封装成统一的 alert.sh，健康检测脚本调用它即可。根据你的实际环境选择一种或多种渠道。

5.1 Telegram Bot 告警

先创建 Bot（通过 @BotFather），获取 BOT_TOKEN 和 CHAT_ID，然后：

#!/usr/bin/env bash
# alert.sh — 多渠道告警（Telegram 版）

MESSAGE="$1"
LEVEL="${2:-warning}"   # warning 或 critical

BOT_TOKEN="YOUR_TELEGRAM_BOT_TOKEN"
CHAT_ID="YOUR_CHAT_ID"

# Telegram 用 emoji 区分级别
if [[ "$LEVEL" == "critical" ]]; then
  text="🔴 [CLIProxyAPI] ${MESSAGE}"
else
  text="⚠️ [CLIProxyAPI] ${MESSAGE}"
fi

curl -sf -X POST \
  "https://api.telegram.org/bot${BOT_TOKEN}/sendMessage" \
  -d "chat_id=${CHAT_ID}" \
  --data-urlencode "text=${text}" \
  > /dev/null

5.2 企业微信 Webhook 告警

在企业微信群里添加机器人，复制 Webhook 地址：

#!/usr/bin/env bash
# alert.sh — 企业微信 Webhook 版

MESSAGE="$1"
LEVEL="${2:-warning}"
WEBHOOK_URL="https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=YOUR_KEY"

color="warning"
[[ "$LEVEL" == "critical" ]] && color="red"

payload=$(cat <<EOF
{
  "msgtype": "markdown",
  "markdown": {
    "content": "**CLIProxyAPI 告警**\n> 级别：<font color=\"${color}\">${LEVEL}</font>\n> 内容：${MESSAGE}"
  }
}
EOF
)

curl -sf -X POST "$WEBHOOK_URL" \
  -H "Content-Type: application/json" \
  -d "$payload" \
  > /dev/null

5.3 钉钉 Webhook 告警

#!/usr/bin/env bash
# alert.sh — 钉钉 Webhook 版
# 注意：钉钉安全设置需配置关键词，建议关键词设为 "CLIProxyAPI"

MESSAGE="$1"
LEVEL="${2:-warning}"
WEBHOOK_URL="https://oapi.dingtalk.com/robot/send?access_token=YOUR_TOKEN"

payload=$(cat <<EOF
{
  "msgtype": "markdown",
  "markdown": {
    "title": "CLIProxyAPI 告警",
    "text": "## CLIProxyAPI 告警\n\n**级别**：${LEVEL}\n\n**内容**：${MESSAGE}"
  },
  "at": { "isAtAll": false }
}
EOF
)

curl -sf -X POST "$WEBHOOK_URL" \
  -H "Content-Type: application/json" \
  -d "$payload" \
  > /dev/null

5.4 邮件告警（sendmail / SMTP）

如果服务器上已配置 sendmail 或 msmtp：

#!/usr/bin/env bash
# alert.sh — 邮件版

MESSAGE="$1"
LEVEL="${2:-warning}"
TO="ops@example.com"
FROM="cpa-monitor@yourdomain.com"
SUBJECT="[${LEVEL^^}] CLIProxyAPI 告警"

{
  echo "To: $TO"
  echo "From: $FROM"
  echo "Subject: $SUBJECT"
  echo "Content-Type: text/plain; charset=UTF-8"
  echo ""
  echo "告警时间：$(date '+%Y-%m-%d %H:%M:%S')"
  echo "级别：$LEVEL"
  echo "内容：$MESSAGE"
} | sendmail -t

如果没有本地 MTA，可以改用 curl 通过 SMTP 发送：

curl -sf \
  --url "smtps://smtp.example.com:465" \
  --ssl-reqd \
  --user "user@example.com:PASSWORD" \
  --mail-from "cpa-monitor@example.com" \
  --mail-rcpt "ops@example.com" \
  --upload-file <(printf "Subject: [CLIProxyAPI] %s\n\n%s" "$LEVEL" "$MESSAGE")

6. 自动重新登录策略

当检测到账号 unavailable 时，可以尝试触发重新登录流程让账号恢复正常。CLIProxyAPI 支持通过 --login 参数重新走 OAuth 授权。

注意：OAuth 授权需要在浏览器中完成操作，因此完全自动化登录在无头服务器上不直接可行。实际策略是：先告警，等人工完成授权后，脚本检测到账号恢复即停止告警。

但你可以脚本化整个发现和准备流程：

#!/usr/bin/env bash
# auto_relogin.sh — 检测失效账号并准备重新登录

CPA_HOST="http://localhost:8317"
SECRET_KEY="YOUR_SECRET_KEY"
CPA_BIN="$HOME/cliproxyapi/cli-proxy-api"   # 实际路径

response=$(curl -sf \
  -H "Authorization: Bearer $SECRET_KEY" \
  "$CPA_HOST/v0/management/api-key-usage")

unavailable_indices=$(echo "$response" | jq -r \
  '.accounts[] | select(.status == "unavailable") | .auth_index')

if [[ -z "$unavailable_indices" ]]; then
  echo "所有账号正常，无需重新登录"
  exit 0
fi

while IFS= read -r idx; do
  email=$(echo "$response" | jq -r \
    --argjson i "$idx" '.accounts[] | select(.auth_index == $i) | .email')
  echo "账号 $email (index=$idx) 需要重新登录"

  # 如果部署在有显示器的环境，可以直接启动登录流程：
  # "$CPA_BIN" --login --account-index "$idx"

  # 无头环境：记录到待处理文件，等待人工介入
  echo "$idx $email $(date '+%Y-%m-%dT%H:%M:%S')" \
    >> "$HOME/cpa/logs/pending_relogin.txt"
done <<< "$unavailable_indices"

echo "待处理的账号已记录到 ~/cpa/logs/pending_relogin.txt"

对于有条件做无头浏览器自动化的环境（如 Playwright + Chrome），可以把 OAuth 登录流程封装进去，实现真正的自动重新授权。这属于较高级的用法，可以结合 CLIProxyAPI 的 --headless-login（如果版本支持）一并考虑。

7. 日志分析

开启日志写文件后（配置文件中设置 logging-to-file: true），日志写到 logs-dir 指定的目录。

实时跟踪日志：

tail -f ~/cliproxyapi/logs/cpa.log

常用的日志分析命令：

LOG=~/cliproxyapi/logs/cpa.log

# 统计今天的请求总量
grep "$(date '+%Y-%m-%d')" "$LOG" | grep -c "request"

# 找出所有 Token 刷新失败的记录
grep -E "token.refresh.fail|refresh_error|unavailable" "$LOG"

# 统计各账号的请求分布（假设日志含邮箱）
grep "$(date '+%Y-%m-%d')" "$LOG" \
  | grep -oP '[\w.+-]+@[\w.-]+' \
  | sort | uniq -c | sort -rn

# 按小时统计请求量（用于分析流量峰值）
grep "$(date '+%Y-%m-%d')" "$LOG" \
  | grep -oP '\d{2}(?=:\d{2}:\d{2})' \
  | sort | uniq -c

8. 定时任务配置

方式一：crontab

crontab -e

添加以下内容：

# CLIProxyAPI 运维定时任务

# 每 5 分钟：账号健康检测
*/5 * * * * /home/sdmike/cpa/check_accounts.sh >> /home/sdmike/cpa/logs/cron.log 2>&1

# 每 5 分钟：cpa_keeper.py 采集快照到 SQLite
*/5 * * * * /usr/bin/python3 /home/sdmike/cpa/cpa_keeper.py collect >> /home/sdmike/cpa/logs/cron.log 2>&1

# 每小时：用量统计写入月度 CSV
0 * * * * /home/sdmike/cpa/usage_logger.sh >> /home/sdmike/cpa/logs/cron.log 2>&1

# 每周日凌晨 3 点：压缩归档旧日志
0 3 * * 0 find /home/sdmike/cpa/logs -name "*.log" -mtime +7 -exec gzip {} \;

方式二：systemd timer

更适合需要精确控制、自动重启和日志集成的场景。

创建 service 文件 /etc/systemd/system/cpa-health-check.service：

[Unit]
Description=CLIProxyAPI 账号健康检测
After=network.target

[Service]
Type=oneshot
ExecStart=/opt/cpa/check_accounts.sh
StandardOutput=journal
StandardError=journal

创建 timer 文件 /etc/systemd/system/cpa-health-check.timer：

[Unit]
Description=每 5 分钟运行一次 CLIProxyAPI 健康检测

[Timer]
OnBootSec=60
OnUnitActiveSec=5min
AccuracySec=30s

[Install]
WantedBy=timers.target

启用并启动：

systemctl daemon-reload
systemctl enable --now cpa-health-check.timer

# 查看 timer 状态
systemctl list-timers cpa-health-check.timer

# 查看最近执行日志
journalctl -u cpa-health-check.service -n 50

同理，为用量统计创建 cpa-usage-logger.service 和 cpa-usage-logger.timer，OnUnitActiveSec 改为 1h。

9. 进阶工具

除了上述 Shell 脚本外，本系列还提供了两个 Python 脚本，放在 ~/cpa/ 目录下，提供更强大的分析能力。详细使用说明见第八篇教程。

cpa_keeper.py — 持久化用量追踪

将管理 API 数据存入本地 SQLite，支持跨时间段的历史查询，是对月度 CSV 方案的补充。

# 查看当前账号状态（需先配置 ~/.cpa/config.env）
python3 ~/cpa/cpa_keeper.py status

# 手动采集一次快照
python3 ~/cpa/cpa_keeper.py collect

# 查询最近72小时历史
python3 ~/cpa/cpa_keeper.py query --hours 72

cpa_keeper.py 已通过 crontab 每 5 分钟自动采集，无需手动触发。

cpa_cost.py — 等效成本分析

基于 new-api 的请求日志，按官方定价计算等效 API 费用，量化订阅方案的节省价值。

# 生成本月成本报告
python3 ~/cpa/cpa_cost.py report --month 2026-06

# 按 new-api 令牌名筛选（查看某成员的消耗）
python3 ~/cpa/cpa_cost.py report --token alice-dev

示例输出（节选）：

📊 CLIProxyAPI 等效成本报告 — 2026-06
模型                                   请求  输入Token  输出Token  等效费用
──────────────────────────────────────────────────────────────────────
claude-opus-4-8                         12    48,200      3,100   $0.3183
claude-sonnet-4-6                       45    98,500      8,200   $0.4185
合计                                    57   146,700     11,300   $0.7368

💡 若直接调用 API，同等用量约需 $0.74 USD

小结

以上方案形成了一套完整的运维闭环：

1. 管理 API 提供账号状态和用量的实时数据源
2. 健康检测脚本 定时轮询，识别失效账号
3. 用量统计脚本 持续记录数据，支持后续分析
4. 告警脚本 对接 Telegram / 企微 / 钉钉 / 邮件，确保问题第一时间触达
5. 自动重新登录 降低人工介入成本
6. 日志分析 帮助定位历史问题和流量规律
7. crontab 或 systemd timer 把上述脚本串联成自动化流水线
8. 社区工具 提供更丰富的可视化和成本分析能力

把这套体系建好之后，CLIProxyAPI 就从"跑起来就不管了"变成了可观测、可告警、可自愈的生产级服务。

系列导航

• （一）入门——把 CLI 订阅变成标准 API
• （二）多账号轮询与配额策略
• （三）接入主流 AI 编程工具
• （四）生产部署——Nginx、TLS 与安全加固
• （五）Antigravity——用 Google 订阅解锁 Claude Opus 4.8
• （六）结合 new-api 打造多用户 API 网关
• （七）自动化运维——配额监控与告警（本文）
• （八）cpa_keeper 与 cpa_cost——用量追踪与成本分析工具

实操清单

• 管理 API 已开启（allow-remote: true，secret-key 已配置）
• 可通过 curl /v0/management/auth-files 查询账号状态（3 个账号全部 active）
• config.yaml 已开启文件日志（logging-to-file: true，logs-dir: ~/cliproxyapi/logs）
• 创建 ~/cpa/ 目录，编写 check_accounts.sh 健康检测脚本
• 编写 usage_logger.sh 用量统计脚本（月度 CSV 到 ~/cpa/logs/）
• 编写 alert.sh（默认写日志，注释块可快速启用 Telegram / 企微 / 钉钉）
• 配置 crontab：每 5 分钟跑健康检测 + cpa_keeper.py 采集，每小时记录 CSV
• 安装 cpa_keeper.py：持久化 SQLite 追踪，已接入 crontab，采集验证通过
• 安装 cpa_cost.py：基于 new-api 日志的等效成本分析，已验证本月报告
• 在 ~/.cpa/config.env 填入 CPA_SECRET，健康检测与追踪已激活
• 测试告警：~/cpa/alert.sh "测试告警" 写入 ~/cpa/logs/alerts.log 正常
• （可选）改用 systemd timer 替代 crontab，统一日志到 journald