kefu/deploy/token-usage-20260917/RELEASE.md

管理端模型 Token 统计

已于 2026-09-17 经用户明确授权上传并更新 192.168.110.111:/opt/im-admin。API、模型网关和知识加工进程均运行正常，服务器端与实际内网入口验证通过。

线上入口：模型调用统计。完整上线记录见 ../token-usage-deployed.md。

入口：管理端「AI 模型 → 调用统计」，路径 /#/model/stats。

使用

• 页面上方选择指定账号或全部授权账号，以及今天、近 7 天、近 30 天。
• 新增「模型 Token 用量」区域，默认包含客服回答与裁判、界面检测、知识整理。
• 展示实际上游请求数、输入/输出/总 Token、用量覆盖率、模型与用途汇总、UTC 每日趋势和分页明细。
• 「未返回」表示模型没有提供对应用量；历史调用未计量单独提示，不估算为真实零值。
• 缓存输入和推理 Token 是细分项，不再次叠加到总量。这里统计 Token，不根据未知价格估算费用。

数据范围

统计经过统一模型网关的回答候选、裁判、视觉判断、工具问答轮次，以及服务端知识整理的实际接口尝试。失败与重试保留记录，有返回 usage 就保留用量；客户端幂等缓存直接返回时不增加用量。

本次不采集绕过网关的桌面直连、管理端连通性测试，或可选向量 embedding 服务的独立请求。不能把页面合计作为供应商整账号的完整账单。

历史聊天字符数不能还原实际 Token；升级前的记录不做推算回填。UTC 自然日为统一时间口径，单账号和全部授权账号沿用既有权限隔离。

实现与兼容

• 新增 model_usage_events 账本，每个实际请求尝试有独立唯一事件编号，重复补写幂等。
• 保留现有按 task_id 合并的客服调用/审核日志，避免双候选、裁判、多轮工具请求在日志合并时丢失用量。
• 写锁等待每次最多 250ms；两次写入仍失败时，仅暂存用量元数据到数据库目录下 model_usage_pending，后续请求和网关后台每 30 秒恢复补写。
• 不保存新一份提示词、回答正文、接口密钥或原始供应商响应。请求元数据只含账号、模型、用途、标识符与计数。
• 非法 tool_calls 等单路异常不会中断其他候选；等待所有候选结束再汇总写入。
• 数据库迁移只增加账本与统计索引，不修改模型配置、角色、聊天归档或知识审核状态。
• 发布包包含此前已完成测试的网关视觉角色路由、Dify 上下文与附件兼容修复；发布前与服务器哈希匹配的本地旧发布包做差异核对。

协议口径参考

OpenAI Chat Completions usage、Claude 输入与缓存用量、Dify 官方兼容适配器。只解析上游提供的计数，不用字符长度模拟 Token。

验证与发布

• 前端：15 项 Vitest、严格类型检查和生产构建已通过。
• 后端：Token 采集/恢复专项 19 项、账本/API 专项 23 项已通过；完整后端回归 260 项通过；最后损坏暂存隔离修改的 4 项恢复回归另行通过。记录见 local-backend-regression.log / .json。
• 测试使用临时 SQLite 和模拟 HTTP 响应，不向客户发消息，不发起付费模型调用。
• 发布包：payload.tar.gz；完整 SHA-256 清单：manifest.json。
• 服务器候选镜像断网完整测试最终为 261 项全部通过，85.905 秒。首次测试发现旧有配置用例依赖开发机的机构名称；已用既有 _poison() 测试夹具补齐有效名称，未修改生产校验规则。首次失败日志保留为 candidate-tests-revision-1.log。
• 服务器保存源码备份 /home/ps/token-usage-20260917/source-before.tar.gz 和旧镜像 zyt/wecom-admin:before-token-usage-20260917。
• 数据库备份 /data/backups/token-usage-20260917/backend.db（容器内），4,765,184,000 字节，PRAGMA quick_check=ok。
• 03-deploy.sh 已成功执行：先等待加工进程和网关退出，再切换镜像并运行 04-verify.sh。261 个部署文件及 253 个运行镜像文件的 SHA-256 全部一致。
• 内网 :8369 首页、新统计资源、API/网关健康接口均返回 200；统计及明细未登录访问返回 401，旧 /api/ 代理路径也正确拦截。
• 全部账号和 18 个单账号的实际数据库统计/分页查询通过。浏览器工具初始化失败，未完成已有登录态的实际页面点击和认证 HTTP 200 验证；API 认证、账号隔离与返回结构已由候选镜像测试覆盖。
• 上线后归档消息由备份时 580451 条增加至核验时 580463 条；知识 864、客户端账号 18、模型供应商 5、管理用户 1，计数未减少。客户端发布策略保持原值。
• 若需回滚，执行 bash /home/ps/token-usage-20260917/rollback.sh，恢复旧源码和旧镜像，保留实时数据库。

首次上传被自动审批拒绝，随后用户明确授权上述目标目录、八个发布文件及 /opt/im-admin 服务更新；授权后的上传、部署和验证已成功完成。