安装

Codex Quota Monitor 连接已有的 CLIProxyAPI。它不会替你安装或管理 CPA。

0.2.0 的 PyPI 和 GHCR 命令需要等 v0.2.0 release tag 发布后才可用。如果你在 tag 存在前预览仓库，用下面的源码安装或本地 Docker build 路径。

挂载生产 management key 或 auth 文件前，先看安全自审计。首次评估保持 loopback-only，并使用只读 secret mount。

选择路径

NixOS：需要声明式服务时用 flake module。
Debian/Ubuntu：先用 uv 做前台 smoke test，再按需接 systemd service。
Docker：需要隔离运行时或 Docker Desktop 支持时用 GHCR image。
Windows：优先用 Docker Desktop；原生 Python 前台运行可用于 smoke test 和个人使用，但不提供 Windows Service 安装。

用 PyPI / uv 安装

如果本机还没有 uv，先安装它：

curl -LsSf https://astral.sh/uv/install.sh | sh

uv tool install codex-quota-monitor==0.2.0

如果你在 tag 发布前预览源码，可以从仓库源码安装：

uv tool install 'git+https://github.com/xsyxnx/codex-quota-monitor.git'

如果你更习惯传统 Python 工具安装器，也可以用 pipx install codex-quota-monitor==0.2.0，源码安装时使用同一个 git+https://... URL。 uv 和 pipx 安装都会暴露 cqm，它是 codex-quota-monitor 的等价短别名。

连接已有 CPA：

codex-quota-monitor \
  --management-base-url http://127.0.0.1:8317 \
  --management-key-file /path/to/management-key \
  --gateway-health-url http://127.0.0.1:8317/healthz \
  --auth-dir /path/to/auth-files \
  --state-db ~/.local/state/codex-quota-monitor/history.sqlite3

启用 --state-db 后，Stats 标签页可以展示已存历史，也可以用原生 JSON 在机器之间迁移：

codex-quota-monitor export-history --state-db ~/.local/state/codex-quota-monitor/history.sqlite3 --output backup.json
codex-quota-monitor import-history --state-db ~/.local/state/codex-quota-monitor/history.sqlite3 backup.json

原生 history backup 带 schema version。当前导入要求 backup schema version 2；更老的 backup 先用匹配的旧版 monitor 导入，再就地升级 SQLite DB。

然后打开 http://127.0.0.1:4515/。

运行日志写到 stderr。前台本地运行保留默认 text 日志即可；如果 service manager 或采集器需要每行一个 JSON object，加 --log-format json。--access-log off 只关闭 HTTP 请求 access 行，不会关闭运行告警。

改成 service 前先跑：

cqm print-config
cqm doctor

配置文件

CLI 参数覆盖环境变量，环境变量覆盖 TOML 配置文件。默认会在存在时读取 /etc/codex-quota-monitor/config.toml 和 ~/.config/codex-quota-monitor/config.toml；传 --config /path/to/config.toml 可指定单个文件，传 --config off 可关闭配置文件读取。

生成 starter 文件时默认只打印，不写系统路径：

cqm init --mode user
cqm init --mode system
cqm init --mode docker

需要落盘到临时目录时用 --output-dir ./codex-quota-monitor-starter。init 不会生成 inline management key；secret 应继续放在权限收紧的 key file 里。裸 CPA endpoint 的 key file 内容必须和 CPA remote-management.secret-key 明文值一致；较新的 CPA 在 secret 为空时会让 /v0/management/* 返回 404。

Rootless User Service

这是单用户 Linux 机器上认知成本最低的 service 路径：

uv tool install codex-quota-monitor==0.2.0
mkdir -p ~/.config/codex-quota-monitor ~/.local/state/codex-quota-monitor ~/.config/systemd/user
codex-quota-monitor init --mode user --output-dir /tmp/cqm-user
install -m 0600 /tmp/cqm-user/config.toml ~/.config/codex-quota-monitor/config.toml
install -m 0644 /tmp/cqm-user/codex-quota-monitor.user.service ~/.config/systemd/user/codex-quota-monitor.service
codex-quota-monitor --config ~/.config/codex-quota-monitor/config.toml doctor
systemctl --user daemon-reload
systemctl --user enable --now codex-quota-monitor

查看、重启或停止：

systemctl --user status codex-quota-monitor --no-pager
journalctl --user -u codex-quota-monitor -n 100 --no-pager
systemctl --user restart codex-quota-monitor
systemctl --user disable --now codex-quota-monitor

如果这台机器需要没有交互登录时也启动 user service，并且符合你的主机策略，可以执行 loginctl enable-linger "$USER"。

发行版差异

用你的发行版推荐方式或 uv 上游 installer 安装 uv，然后执行 uv tool install codex-quota-monitor==0.2.0。
Debian/Ubuntu、Fedora、Arch Linux 和 openSUSE 用户如果更习惯 pipx，仍可安装发行版的 pipx 包。

生成的 systemd unit 是普通 Linux unit；主要发行版差异只在 Python、uv 或 pipx 的安装方式。

System Service

创建独立用户和状态目录：

sudo useradd --system --home /var/lib/codex-quota-monitor --create-home --shell /usr/sbin/nologin codex-quota-monitor
sudo install -d -o codex-quota-monitor -g codex-quota-monitor /var/lib/codex-quota-monitor

在该用户的 venv 里安装：

sudo -u codex-quota-monitor python3 -m venv /var/lib/codex-quota-monitor/venv
sudo -u codex-quota-monitor /var/lib/codex-quota-monitor/venv/bin/python -m pip install --upgrade pip
sudo -u codex-quota-monitor /var/lib/codex-quota-monitor/venv/bin/python -m pip install codex-quota-monitor

仓库提供了可复制模板：examples/codex-quota-monitor.config.toml 和 examples/codex-quota-monitor.service。最小 unit 类似：

[Unit]
Description=Codex Quota Monitor
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=codex-quota-monitor
Group=codex-quota-monitor
ExecStart=/var/lib/codex-quota-monitor/venv/bin/codex-quota-monitor --config /etc/codex-quota-monitor/config.toml
Restart=on-failure
RestartSec=5s
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=strict
ProtectHome=read-only
ReadWritePaths=/var/lib/codex-quota-monitor

[Install]
WantedBy=multi-user.target

默认保持 loopback-only，除非你明确要通过 tunnel、reverse proxy 或 firewall rule 暴露。

如果 service 报 auth 文件 Permission denied，把 auth 文件目录以只读方式挂载/复制到 codex-quota-monitor 用户可遍历的位置，或给该用户加窄范围只读 ACL。不要通过放宽整个 home、.config 或 secret 目录权限来解决。Monitor 只需要读取 auth 文件，并写入自己的 SQLite 状态目录。

Docker

容器内部监听 0.0.0.0。宿主端口默认只绑定 loopback：

docker run --rm \
  --add-host=host.docker.internal:host-gateway \
  --read-only \
  --cap-drop=ALL \
  --security-opt=no-new-privileges \
  --tmpfs /tmp \
  -p 127.0.0.1:4515:4515 \
  -e CODEX_QUOTA_MONITOR_MANAGEMENT_BASE_URL=http://host.docker.internal:8317 \
  -e CODEX_QUOTA_MONITOR_MANAGEMENT_KEY_FILE=/management-key \
  -e CODEX_QUOTA_MONITOR_GATEWAY_HEALTH_URL=http://host.docker.internal:8317/healthz \
  -v codex-quota-monitor-data:/data \
  -v /path/to/management-key:/management-key:ro \
  -v /path/to/auth-files:/auth-files:ro \
  -e CODEX_QUOTA_MONITOR_AUTH_DIR=/auth-files \
  -e CODEX_QUOTA_MONITOR_LOG_FORMAT=text \
  -e CODEX_QUOTA_MONITOR_ACCESS_LOG=on \
  ghcr.io/xsyxnx/codex-quota-monitor:0.2.0

只挂载 monitor 需要的具体 management key 文件和 auth-files 目录，并保持只读；裸 CPA endpoint 挂载的 key file 必须和 CPA remote-management.secret-key 一致。 /data 应是唯一持久可写路径。不要把整个 home、.config 或其它无关 secret 目录挂进容器。

Docker Desktop for Windows 或 macOS 通常内置 host.docker.internal，一般不需要 --add-host=host.docker.internal:host-gateway。

如果你在 GHCR release image 发布前预览源码，可以先本地构建并把镜像名替换成 codex-quota-monitor:local：

docker build -t codex-quota-monitor:local .

Compose 部署可以从 examples/docker-compose.yml 开始；除非前面有带鉴权的 reverse proxy，否则宿主端口继续绑定 127.0.0.1。

通过 Reverse Proxy 做局域网访问

不要把 monitor API 当成鉴权边界。应用继续监听 127.0.0.1:4515，只把 proxy 暴露到专用 hostname 的根路径，例如 https://quota.example/：

codex-quota-monitor doctor --host 127.0.0.1 --allowed-host quota.example

starter proxy 示例在 examples/reverse-proxy/Caddyfile 和 examples/reverse-proxy/nginx.conf。允许手机、局域网客户端或公网 tunnel 访问 dashboard 前，先加 basic auth 或你常用的 access layer。https://example/tools/quota/ 这类 path-prefix 部署不是 v1 支持拓扑；需要时请使用专用 hostname。

Windows 前台 Python

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
uv tool install codex-quota-monitor==0.2.0
codex-quota-monitor --management-base-url http://127.0.0.1:8317 --management-key-file C:\path\to\management-key --gateway-health-url http://127.0.0.1:8317/healthz

这条路径只承诺前台运行。需要更可复现的 Windows 运行方式时，用 Docker Desktop。

Smoke Test

codex-quota-monitor --version
codex-quota-monitor print-config
codex-quota-monitor doctor
curl -fsS http://127.0.0.1:4515/healthz
curl -fsS http://127.0.0.1:4515/api/v1/status | jq '.summary'
curl -fsS http://127.0.0.1:4515/api/v1/stats | jq '.sources'
curl -fsS http://127.0.0.1:4515/api/v1/diagnostics | jq '.summary'
curl -fsS http://127.0.0.1:4515/api/v1/alerts | jq '.'
curl -fsS http://127.0.0.1:4515/metrics | sed -n '1,20p'