v2.0.0 — Pricing System Overhaul

What's Changed:

v2.0.0 introduces persisted request costs, more flexible pricing, and model speed comparisons, together with a database migration for existing v1 installations.

• Recorded request costs: Estimated costs are now calculated and saved when requests are processed. Dashboards, exports, and quota history use these stored values. Changing or deleting pricing settings no longer automatically changes historical costs. (#595)
• Flexible model pricing: A unified editor brings together default prices, model and conditional multipliers, and price branches based on input context length, daily time periods, and weekdays/weekends. Base-price synchronization preserves existing branches and multipliers. Time-based rules follow the configured timezone. (#595)
• Explicit historical recalculation: Choose a starting hour within the last 30 days to recalculate stored costs across all models using the current pricing configuration, with related summaries refreshed afterward. (#595)
• Model speed comparisons: Analysis and Realtime now compare output Token/s across models, with model selection, historical trends, and comparisons between the earlier and recent halves of a realtime window. (#635)
• Clearer quota history: Cycle summaries remain visible while details collapse by default. Selecting a historical cycle updates the chart, with a return-to-chart action that keeps the chart clear of sticky navigation. (#627)
• Smoother chart interactions: Refreshes retain existing charts and valid data, with consistent animations and tooltips across Overview, Analysis, Realtime, and quota history. (#638)
• Background execution usage: Usage containing an execution ID but no request ID can now be ingested. Retained messages previously rejected for a missing request ID are recovered during migration; request logs still require a real request ID. (#644)

Compatibility and important changes

• Keeper v2 supports CPA v8.0.12+, including grouped provider configuration. Please check your CPA version before upgrading. Local history remains accessible when CPA is unavailable. (#620)
• Local and Community Ranking have been removed. Their pages and ranking-specific stored data are removed during the upgrade. (#608)
• v2 becomes the default stable channel for Docker latest and Homebrew cpa-usage-keeper. Deployments staying on v1 should use an explicit v1 version or the cpa-usage-keeper@1 formula. (#647)

Upgrade and data migration

Please upgrade while CPA and Keeper are not in use. Pause new requests and stop the old Keeper instance before upgrading. Keep a verified pre-upgrade database backup, and resume use only after migration completes and Keeper is ready.

On the first v2 startup, Keeper automatically backs up the v1 database, captures the existing pricing configuration, backfills costs for retained recent and archived requests, and rebuilds the relevant summaries. The startup page displays migration status, and migration checkpoints support resuming after interruption. Duration depends on database size and disk performance; allow sufficient time and disk space. (#595, #642)

Historical totals may change: Overview statistics are rebuilt from retained request details. If older details were previously deleted, their contributions cannot be reconstructed, so historical request and Token totals may decrease. (#621)

If upgrading fails

You can roll back to v1.15.11 using a verified pre-upgrade database backup. When the automatic backup is verified after a migration failure, the logs include rollback guidance and its backup_path. (#649)

1. Stop Keeper v2. Preserve the failed database and any accompanying -wal and -shm files.
2. Copy the pre-upgrade backup into a separate data directory and name the copy app.db. Keep the original backup intact, and do not mix in files from the failed database.
3. Install v1.15.11 and set WORK_DIR to that directory. With the default Docker setup, mount the directory at /data, so the restored database is /data/app.db.

Do not open a migrated or partially migrated v2 database directly with v1.15.11. Restore from the pre-upgrade backup. Recovery returns data to the backup point; usage received afterward will not be included.

Full Changelog: v1.15.11...v2.0.0

---

更新内容：

v2.0.0 带来请求费用持久化、更灵活的计价配置与模型速度对比，并对现有 v1 数据库执行升级迁移。

• 请求费用持久化： 请求处理时计算并保存估算费用，仪表盘、导出与配额历史统一读取已保存的费用。修改或删除价格配置，不再自动改变历史费用。(#595)
• 更灵活的模型计价： 统一编辑默认价格、模型倍率、条件倍率，以及按输入上下文长度、每日时段、工作日／周末匹配的价格分支。同步基础价格时保留已有分支与倍率，时间规则按配置时区执行。(#595)
• 主动重算历史费用： 可选择最近 30 天内的起始小时，按当前价格配置统一重算所有模型的历史费用，并更新相关汇总。(#595)
• 模型速度对比： Analysis 与 Realtime 新增按模型对比输出 Token/s，支持模型选择、历史趋势，以及实时窗口前后两段的速度比较。(#635)
• 更清晰的配额历史： 周期摘要保持可见，明细默认折叠；选择历史周期即可更新图表，并可返回图表位置，避免被吸顶导航遮挡。(#627)
• 更连贯的图表交互： 刷新时保留已有图表与有效数据，统一 Overview、Analysis、Realtime 和配额历史的动画及悬浮提示行为。(#638)
• 后台执行用量接收： 支持只有执行 ID、没有请求 ID 的用量事件；迁移时会恢复仍保留、此前因缺少请求 ID 而被拒绝的消息。查看请求日志仍需真实的请求 ID。(#644)

兼容性与重要变化

• Keeper v2 支持 CPA v8.0.12+，适配分组提供商配置，请在升级前确认 CPA 版本。CPA 不可用时仍可查看本地历史。(#620)
• 移除本地排行与社区排行。 相关页面和排行专属存储数据会随升级移除。(#608)
• v2 成为 Docker latest 和 Homebrew cpa-usage-keeper 的默认稳定版本。需要继续使用 v1 的部署，请固定 v1 版本，或使用 cpa-usage-keeper@1 formula。(#647)

升级与数据迁移

请在不使用 CPA 和 Keeper 的时段升级，暂停新请求，并先停止旧版 Keeper。升级前请保留一份已确认可用的数据库备份，等待迁移完成、服务就绪后再恢复使用。

首次启动 v2 时，Keeper 会自动备份 v1 数据库，固定现有价格配置，为保留的近期与归档请求回填费用，并重建相关汇总。启动页面会显示迁移状态，迁移支持通过检查点在中断后继续。耗时取决于数据库大小和磁盘性能，请预留足够时间与磁盘空间。(#595, #642)

历史统计可能变化： Overview 会根据仍保留的请求明细重建统计。如果过去清理过历史明细，对应的统计贡献无法重建，因此部分历史请求数与 Token 总量可能减少。(#621)

升级失败时如何回退

如果升级失败，可以回退到 v1.15.11，并使用已验证的升级前数据库备份恢复。迁移失败后，若自动备份验证通过，日志会提供回退说明与备份路径 backup_path。(#649)

1. 停止 Keeper v2，保留故障数据库及其可能存在的 -wal、-shm 文件。
2. 将升级前备份复制到独立数据目录，并将副本命名为 app.db。保留原备份，不要混入故障数据库的文件。
3. 安装 v1.15.11，将 WORK_DIR 指向该目录。Docker 默认配置下，将该目录挂载到 /data，使恢复后的数据库位于 /data/app.db。

不要让 v1.15.11 直接打开已迁移或迁移到一半的 v2 数据库，必须使用升级前备份恢复。恢复后的数据回到备份时点，不包含此后收到的新用量。