CPA Manager Plus v1.14.0

92 commits · 165 files changed · +16,577 / -272

English ->

Overview

v1.14.0 是一次围绕历史用量生命周期管理的功能版本。新增的 Usage Maintenance（用量维护） 工作区把历史数据归档、完整性校验、在线明细清理、导入导出、任务恢复和存储诊断集中到一套明确的流程中，并为长期运行、SQLite 持续增长和历史数据迁移提供正式的维护边界。

本版本同时补齐离线空间回收能力：新增 compact-usage 命令，在 Manager Server 停止后通过独占锁与完整性检查安全执行 SQLite 压缩。对于已经归档并清理在线 raw usage 的实例，查询、rollup、pricing coverage 和恢复路径也增加了对应保护，避免把“逻辑删除”“物理空间回收”和“完整历史恢复”混为同一件事。

此外，修复模型发现中的一个配置正确性问题：上游仅用于展示的 display_name / displayName 不再自动写入 CPA 路由别名，避免保存后意外改变对外模型 ID。

Highlights

Usage Maintenance

新增独立的 用量维护 工作区，以“归档管理”和“导入/导出”为主要入口，并提供任务状态、筛选、详情抽屉和浏览器历史恢复。（Web / Manager Server）
支持按固定时间边界预览历史数据规模，然后依次执行 归档 → 校验 → 单独确认在线明细清理；归档和删除保持两个独立授权阶段。（Web / Manager Server）
归档任务状态、阶段与进度持久化，长时间任务可以在页面刷新、请求中断或服务重启后继续恢复，而不会因为前端连接中断丢失后台工作。（Web / Manager Server）
新增维护锁、coverage/readiness 检查和阶段状态机，阻止并发归档、校验、删除、压缩或未满足前置条件的破坏性操作。（Manager Server）
支持可选的历史数据自动 retention；默认关闭，只有显式启用后才会按配置的保留天数执行归档、校验和受保护的删除流程。（Manager Server）

Archive / Import / Export

历史归档按 run 保存到 usage-archives/，使用顺序化 gzip JSONL segment，并在数据库中保留 run、segment、identity ledger 和验证状态。（Manager Server）
完整 Usage JSONL 导出使用稳定快照边界读取当前仍在线的 usage_events，不受 USAGE_QUERY_LIMIT 限制；导出开始后新写入的事件不进入该快照。（Web / Manager Server）
导入改为可恢复 session：支持分块上传、服务端返回的动态 chunk size、临时文件磁盘配额、session 数量限制和 TTL 清理。（Web / Manager Server）
恢复已有上传 session 时会校验已上传前缀的 SHA-256；文件内容不一致时拒绝继续，避免仅凭文件名、大小或修改时间误恢复。（Web / Manager Server）
identity ledger 保证已归档并删除 raw row 的事件不会因为重新导入而被“复活”；将 archive 恢复到空白隔离实例时仍可按 segment 顺序重建 raw history。（Manager Server）

Historical Query And Data Safety

Request Monitoring、Usage Analytics、Dashboard 与 pricing coverage 增加历史清理后的读取边界，派生数据继续承担长窗口查询职责，而已经删除的 raw event 不会被静默假装仍然存在。（Web / Manager Server）
raw deletion 只有在归档已验证并满足 aggregate / coverage readiness 后才允许执行；统计刷新失败不会回滚已经完成且持久化成功的归档阶段。（Manager Server）
第一次删除历史 raw event 后，历史 pricing model 集合和 context-tier 阈值结构进入 fail-closed 保护，避免后续结构变化让已删除历史无法一致重建；费率更新仍然允许。（Manager Server）
完整历史恢复需要保留删除前的一致备份。普通 JSONL export 不会自动把已经删除到 archive segment 的历史记录重新拼回当前在线数据。（Manager Server / Docs）

Offline Compaction

新增原生命令：
cpa-manager-plus compact-usage --db-path <usage.sqlite>。（Manager Server / Native）
压缩必须在所有连接该数据库的 Manager Server 停止后执行；进程锁、SQLite 独占访问、维护锁和活动归档阶段都会阻止不安全的压缩。（Manager Server）
compact-usage 在长阶段输出状态/heartbeat，并将最终机器可读的 CompactResult JSON 独立写到 stdout。（Manager Server）
压缩不会自动执行，也不会修改 data.key 或推进 usage data migration checkpoint；建议预留最多约数据库文件两倍的临时可用空间。（Docs）

Model Discovery Alias Fix

normalizeModelList 不再把上游 display_name / displayName 当作配置用 alias。（Web）
新增独立的 display metadata，模型发现列表仍能显示友好名称并参与搜索/分类，但新导入的模型不会因此改变 CPA 对外注册的模型 ID。（Web）
显式上游 alias 和用户手工设置的 alias 行为保持不变。（Web）
已经由旧版本保存到配置中的错误 alias 不会自动重写。 如之前导入时已经把友好名称写入 alias，需要用户手工清空。（Web）

Upgrade Notes

无需手动数据库迁移。 Manager Server 启动时会自动创建和升级 Usage Maintenance 所需的 additive schema；升级本身不会自动删除历史 usage_events。
自动 retention 默认关闭。 只有显式设置 USAGE_ARCHIVE_RETENTION_ENABLED=true 后，Manager Server 才会按配置执行历史保留流程。
执行任何 raw cleanup 前，请先保留一致备份： usage.sqlite、usage.sqlite-wal、usage.sqlite-shm、data.key 和 usage-archives/ 必须来自同一个一致时间点。
compact-usage 只能离线执行。 停止所有使用该 SQLite 的 Manager Server 后再运行；逻辑删除不会自动缩小 SQLite 文件。
Usage Maintenance 的完整 JSONL 导出只覆盖导出开始时仍存在于 raw usage_events 中的记录，不会把已经删除的 archive segment 自动合并回来，也不等价于完整 CPAMP 备份。
一旦已经执行历史 raw cleanup，降级到旧版本时不能再简单假设“只换回旧二进制”即可恢复完整语义。需要恢复完整历史时，应使用删除前的一致备份或该版本提供的专用恢复路径。
完整 Muse / Meta 功能的 CPA 基线继续为 v7.3.4+；本版本没有提高 CPA 最低兼容基线。

Acknowledgements

@YogaSakti - 报告并贡献模型发现中 display name 与 routing alias 分离修复，避免友好名称被保存为路由别名并改变对外模型 ID。

Full Changelog: v1.13.2...v1.14.0

seakee/CPA-Manager-Plus v1.14.0 on GitHub