feat: add image route usage telemetry

docs/deployment.md

@@ -23,7 +23,7 @@
 当前约束：
 
 - 使用系统 Python 3.12，不使用虚拟环境。
-- 图片生成仍是同步接口；真实图片生成耗时尚未在生产链路验证，**上线前必须跑一次真实图片 smoke 并记录耗时**。
+- 图片生成已提供旧同步接口和新异步提交 / 轮询接口；真实图片生成耗时仍需在生产链路记录，并用于校准旧同步超时和异步 worker 容量。
 - 真实支付需微信 / 支付宝商户密钥、证书、生产 SDK 与公网回调地址；未配置前只能用 `PAYMENT_CALLBACK_MODE=mock`。
 
 ## 二、系统准备
@@ -307,6 +307,49 @@ WantedBy=multi-user.target
 - `cmhub-generate.service`：旧同步生成接口，保留给老客户端。
 - `cmhub-image-worker.service`：新异步任务真正调上游生成图片。
 
+### 生图接口用量遥测与旧同步弃用
+
+T-615 起，旧同步 `POST /api/v1/generate/image` 和新异步提交 `POST /api/v1/generate/image/tasks` 会向 `cmhub.api.generation_usage` 写结构化日志，日志消息以 `generation_route_usage` 开头，JSON 字段包含：
+
+```json
+{
+  "event": "generation_route_usage",
+  "route_type": "sync",
+  "api_key_id": 12,
+  "api_key_prefix": "sk_cmhub_xxxxxx",
+  "user_id": 34,
+  "client_version": "0.1.1",
+  "alias": "image-hd",
+  "status": "success",
+  "latency_ms": 123456,
+  "error_code": "",
+  "http_status": 200
+}
+```
+
+安全边界：日志不得包含 API Key 明文、prompt 全文、`image_base64`、provider raw、上游密钥或图片内容。调用方建议在两个生图提交接口都带 `X-Client-Version`，便于按客户端版本观察迁移进度。
+
+systemd 日志查询示例：
+
+```bash
+journalctl -u cmhub-generate.service --since "24 hours ago" | grep generation_route_usage
+journalctl -u cmhub-web.service --since "24 hours ago" | grep generation_route_usage
+```
+
+常用观察维度：
+
+- 按 `route_type` 看旧同步 `sync` 与新异步 `async` 的调用占比。
+- 按 `client_version` 找仍在调用旧同步接口的客户端版本。
+- 按 `api_key_id` / `api_key_prefix` 找未迁移的接入账号。
+- 按 `status` / `error_code` / `latency_ms` 比较旧路和新路错误率、超时率和耗时。
+
+旧同步接口退出条件：
+
+1. 新版桌面端默认走异步提交 / 轮询接口。
+2. 连续观察一段生产窗口后，旧同步 `route_type=sync` 调用归零，或低于运营确认的阈值，且没有关键客户仍依赖旧路。
+3. 先在发布说明和接口文档中标记旧同步接口 deprecated。
+4. 单独立任务下线旧同步接口；下线前必须继续保持旧同步成功响应字段兼容。
+
 ## 八、宝塔 / Nginx 配置
 
 宝塔中新建站点并绑定域名和 SSL 后，在站点 Nginx 配置中加入或调整：