升级

启用 history 时，Codex Quota Monitor 的运行状态保存在一个 SQLite 文件里。大版本升级前先备份它。

兼容策略

0.x release 可能调整 UI 文案，并在 API 声明 1.0 稳定前改变 JSON endpoint。
已文档化的命令行参数和 NixOS module options 在同一 minor line 内应保持兼容。
/api/v1/status、/api/v1/recommendations、/api/v1/diagnostics、/api/v1/alerts 和 /metrics 是 0.2.x 的文档化集成面。
未版本化的 /api/* JSON 路径、summary.subline、summary.fastPill、顶层 fastMode 和 tabs.pool.stats 已在 0.x 清理中删除。请使用 /api/v1/* 路径以及已文档化的 quota / recommendation 字段。
SQLite history schema version 2 删除 Fast/Routing snapshot 列和旧 Fast policy audit event。升级前先备份 DB；monitor 启动时会迁移表结构。
客户端应忽略未知 JSON 字段。

升级前

记录：

codex-quota-monitor --help
codex-quota-monitor --version
codex-quota-monitor print-config
codex-quota-monitor doctor
codex-quota-monitor init --mode user >/tmp/codex-quota-monitor-init.txt
curl -fsS http://127.0.0.1:4515/healthz
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 '.'

Python 安装后，这些交互检查里的 codex-quota-monitor 可以替换成 cqm。

如果使用 SQLite history，备份 state DB：

cp /var/lib/codex-quota-monitor/history.sqlite3 /var/lib/codex-quota-monitor/history.sqlite3.bak

Docker、uv、pipx 或自定义路径按实际 state 位置调整。

如果使用配置文件，保留一份 print-config 或 doctor 显示的当前配置文件。

uv

uv tool upgrade codex-quota-monitor
systemctl restart codex-quota-monitor

rootless user service 用 systemctl --user restart codex-quota-monitor。

回滚：

uv tool install --force 'codex-quota-monitor==<previous-version>'
systemctl restart codex-quota-monitor

如果你原来用 pipx 安装，则继续用 pipx upgrade codex-quota-monitor 和 pipx install --force 'codex-quota-monitor==<previous-version>'。

Docker

拉取目标镜像并重建容器：

docker pull ghcr.io/xsyxnx/codex-quota-monitor:0.2.0

保留同一个 /data volume 即可保留 history。回滚时用旧 tag 加同一个 volume 重新启动。

NixOS

更新 flake input 并在 switch 前求值/构建：

nix flake update codexQuotaMonitor
nix build .#nixosConfigurations.<host>.config.system.build.toplevel --no-link

然后使用你自己的 operator-controlled deployment path。

升级后

运行：

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/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'

打开 dashboard，确认 Pool、Diagnostics、Alerts，以及启用 history 时的 Trends。