From d5656b4f565528b98eb736e55fdd794445cb4829 Mon Sep 17 00:00:00 2001 From: QiuSW <105186638@qq.com> Date: Wed, 8 Jul 2026 22:44:17 +0800 Subject: [PATCH] feat: add image route usage telemetry --- README.md | 2 +- apps/api/telemetry.py | 90 ++++++++++++++++++++++++++++ apps/api/tests.py | 123 +++++++++++++++++++++++++++++++++++++++ apps/api/views.py | 64 ++++++++++++++++++++ docs/00-ai-start-here.md | 4 +- docs/04-architecture.md | 4 +- docs/06-tasks.md | 2 +- docs/api.md | 11 ++++ docs/current-state.md | 20 ++++--- docs/deployment.md | 45 +++++++++++++- docs/project-brief.md | 4 +- docs/project-onepager.md | 2 +- progress.md | 26 +++++++++ 13 files changed, 379 insertions(+), 18 deletions(-) create mode 100644 apps/api/telemetry.py diff --git a/README.md b/README.md index a5953f1..f3fdfdf 100644 --- a/README.md +++ b/README.md @@ -25,7 +25,7 @@ Python 3.12 / Django 5.2 LTS + DRF / django-admin / 用户端 Django 模板 SSR ## 当前状态 -Phase 2 计费核心已完成，Phase 3 对外 API 与充值已完成到 T-306，Phase 4 用户端已完成 T-501~T-505，Phase 5 已完成 T-401 运营后台完善、T-402 MVP 完整验收与 T-403 部署 / 运行文档，Phase 6 已完成 T-601 可用别名发现、T-602/T-603 django-admin 中文化、T-604 中文敏感词本地过滤、T-605 免邮箱验证策略落地、T-606 公开首页 + 客户端下载入口、T-607 桌面端最新版本检查接口、T-608 新用户注册赠送 100 点试用点数、T-609 桌面端版本强制更新标记、T-610 首页导入模板下载入口、T-611 用户端品牌名统一为“虾皮圈”、T-612 生图同步接口止血、T-613 抽生成核心 service 与 T-614 生图异步任务化接口。用户可通过公开首页进入注册、登录、下载客户端和下载导入模板；新用户注册后经计费层自动获得 100 点并写注册赠点流水；登录后可扫码充值并轮询到账，生成 / 删除（吊销）API Key，查看余额、充值总额、分页充值记录、分页点数记录与可用模型；桌面端可匿名请求最新客户端版本 JSON，并读取 `release.force_update` 判断是否必须升级；新版桌面端可用异步生图提交 / 轮询接口，旧同步生图接口继续兼容；运营可在 django-admin 检索用户、钱包、API Key、计费规则、汇率、充值订单、点数流水、注册赠点记录、调用记录、图片生成任务、客户端发布版本和导入模板，并通过计费层带原因手工调点。下一步为 T-615 旧同步生图接口遥测；生产侧仍需补真实支付回调到账闭环。详见 [`docs/current-state.md`](docs/current-state.md)。 +Phase 2 计费核心已完成，Phase 3 对外 API 与充值已完成到 T-306，Phase 4 用户端已完成 T-501~T-505，Phase 5 已完成 T-401 运营后台完善、T-402 MVP 完整验收与 T-403 部署 / 运行文档，Phase 6 已完成 T-601 可用别名发现、T-602/T-603 django-admin 中文化、T-604 中文敏感词本地过滤、T-605 免邮箱验证策略落地、T-606 公开首页 + 客户端下载入口、T-607 桌面端最新版本检查接口、T-608 新用户注册赠送 100 点试用点数、T-609 桌面端版本强制更新标记、T-610 首页导入模板下载入口、T-611 用户端品牌名统一为“虾皮圈”、T-612 生图同步接口止血、T-613 抽生成核心 service、T-614 生图异步任务化接口与 T-615 旧同步生图接口遥测 / 弃用口径。用户可通过公开首页进入注册、登录、下载客户端和下载导入模板；新用户注册后经计费层自动获得 100 点并写注册赠点流水；登录后可扫码充值并轮询到账，生成 / 删除（吊销）API Key，查看余额、充值总额、分页充值记录、分页点数记录与可用模型；桌面端可匿名请求最新客户端版本 JSON，并读取 `release.force_update` 判断是否必须升级；新版桌面端可用异步生图提交 / 轮询接口，旧同步生图接口继续兼容并写结构化用量日志；运营可在 django-admin 检索用户、钱包、API Key、计费规则、汇率、充值订单、点数流水、注册赠点记录、调用记录、图片生成任务、客户端发布版本和导入模板，并通过计费层带原因手工调点。生产侧仍需补真实支付回调到账闭环，并按日志观察旧同步生图接口迁移进度。详见 [`docs/current-state.md`](docs/current-state.md)。 > ⚠️ 涉及资金/点数。改动充值、扣费、退款、对账相关代码前，先读 [`docs/05-coding-rules.md`](docs/05-coding-rules.md) 第 8 节与 [`docs/04-architecture.md`](docs/04-architecture.md) 第四节计费时序。 diff --git a/apps/api/telemetry.py b/apps/api/telemetry.py new file mode 100644 index 0000000..51278d5 --- /dev/null +++ b/apps/api/telemetry.py @@ -0,0 +1,90 @@ +from __future__ import annotations + +import json +import logging +from time import perf_counter +from typing import Any, Mapping + + +logger = logging.getLogger("cmhub.api.generation_usage") + +EVENT_NAME = "generation_route_usage" +MAX_CLIENT_VERSION_LENGTH = 64 +MAX_ALIAS_LENGTH = 64 + + +def telemetry_start_time() -> float: + return perf_counter() + + +def telemetry_elapsed_ms(started: float) -> int: + return max(0, int((perf_counter() - started) * 1000)) + + +def request_alias(data: Mapping[str, Any]) -> str: + try: + return normalize_text(data.get("model", ""), MAX_ALIAS_LENGTH) + except AttributeError: + return "" + + +def log_generation_route_usage( + *, + route_type: str, + request, + alias: str, + status: str, + latency_ms: int, + error_code: str = "", + http_status: int | None = None, +) -> dict[str, Any]: + event = build_generation_route_usage_event( + route_type=route_type, + request=request, + alias=alias, + status=status, + latency_ms=latency_ms, + error_code=error_code, + http_status=http_status, + ) + logger.info( + "%s %s", + EVENT_NAME, + json.dumps(event, ensure_ascii=False, sort_keys=True), + extra={"generation_route_usage": event}, + ) + return event + + +def build_generation_route_usage_event( + *, + route_type: str, + request, + alias: str, + status: str, + latency_ms: int, + error_code: str = "", + http_status: int | None = None, +) -> dict[str, Any]: + api_key = getattr(request, "auth", None) + user = getattr(request, "user", None) + return { + "event": EVENT_NAME, + "route_type": normalize_text(route_type, 16), + "api_key_id": getattr(api_key, "id", None), + "api_key_prefix": normalize_text(getattr(api_key, "key_prefix", ""), 32), + "user_id": getattr(user, "id", None), + "client_version": normalize_text( + request.headers.get("X-Client-Version", ""), + MAX_CLIENT_VERSION_LENGTH, + ), + "alias": normalize_text(alias, MAX_ALIAS_LENGTH), + "status": normalize_text(status, 32), + "latency_ms": max(0, int(latency_ms)), + "error_code": normalize_text(error_code, 64), + "http_status": http_status, + } + + +def normalize_text(value: Any, max_length: int) -> str: + return str(value or "").strip()[:max_length] diff --git a/apps/api/tests.py b/apps/api/tests.py index 4bd3f4a..f627d33 100644 --- a/apps/api/tests.py +++ b/apps/api/tests.py @@ -1168,6 +1168,43 @@ class GenerateApiTests(TestCase): with patch("apps.api.generation.get_provider", return_value=provider or self.provider): return self.client.post(path, payload, format="json", **self.auth_header(), **extra) + def telemetry_event_from_logs(self, captured): + events = [ + getattr(record, "generation_route_usage", None) + for record in captured.records + if getattr(record, "generation_route_usage", None) + ] + self.assertEqual(len(events), 1) + return events[0] + + def assert_generation_telemetry_is_safe(self, event, *, payload=None): + self.assertEqual( + set(event), + { + "event", + "route_type", + "api_key_id", + "api_key_prefix", + "user_id", + "client_version", + "alias", + "status", + "latency_ms", + "error_code", + "http_status", + }, + ) + serialized = json.dumps(event, ensure_ascii=False) + self.assertNotIn(self.raw_key, serialized) + self.assertNotIn("SECRET_RAW", serialized) + self.assertNotIn("prompt", serialized) + self.assertNotIn("image_base64", serialized) + if payload: + self.assertNotIn(str(payload.get("prompt") or ""), serialized) + encoded_image = str(payload.get("image_base64") or "") + if encoded_image: + self.assertNotIn(encoded_image, serialized) + def assert_generation_not_charged(self): self.wallet.refresh_from_db() self.assertEqual(self.wallet.points_balance, 100) @@ -1288,6 +1325,92 @@ class GenerateApiTests(TestCase): self.assertEqual(call.result_summary, "image_bytes=21") self.assertNotIn("SECRET_RAW", call.result_ref + call.result_summary) + def test_sync_image_usage_telemetry_logs_safe_client_version_and_key_identity(self): + encoded = base64.b64encode(b"input-image").decode("ascii") + payload = { + "prompt": "生成图片遥测测试", + "model": self.image_alias, + "image_base64": f"data:image/png;base64,{encoded}", + "resolution": "1K", + "aspect_ratio": "1:1", + } + + with self.assertLogs("cmhub.api.generation_usage", level="INFO") as captured: + response = self.post_with_provider( + "/api/v1/generate/image", + payload, + HTTP_X_CLIENT_VERSION="0.1.1", + ) + + self.assertEqual(response.status_code, 200) + event = self.telemetry_event_from_logs(captured) + self.assertEqual(event["event"], "generation_route_usage") + self.assertEqual(event["route_type"], "sync") + self.assertEqual(event["api_key_id"], self.api_key.id) + self.assertEqual(event["api_key_prefix"], self.api_key.key_prefix) + self.assertEqual(event["user_id"], self.user.id) + self.assertEqual(event["client_version"], "0.1.1") + self.assertEqual(event["alias"], self.image_alias) + self.assertEqual(event["status"], "success") + self.assertEqual(event["error_code"], "") + self.assertEqual(event["http_status"], 200) + self.assertIsInstance(event["latency_ms"], int) + self.assertGreaterEqual(event["latency_ms"], 0) + self.assert_generation_telemetry_is_safe(event, payload=payload) + + def test_async_image_submit_usage_telemetry_logs_safe_success_event(self): + payload = { + "prompt": "生成异步图片遥测测试", + "model": self.image_alias, + "resolution": "1K", + } + + with self.assertLogs("cmhub.api.generation_usage", level="INFO") as captured: + response = self.post_with_provider( + "/api/v1/generate/image/tasks", + payload, + HTTP_X_CLIENT_VERSION="0.1.2", + ) + + self.assertEqual(response.status_code, 202) + event = self.telemetry_event_from_logs(captured) + self.assertEqual(event["route_type"], "async") + self.assertEqual(event["api_key_id"], self.api_key.id) + self.assertEqual(event["api_key_prefix"], self.api_key.key_prefix) + self.assertEqual(event["user_id"], self.user.id) + self.assertEqual(event["client_version"], "0.1.2") + self.assertEqual(event["alias"], self.image_alias) + self.assertEqual(event["status"], "success") + self.assertEqual(event["error_code"], "") + self.assertEqual(event["http_status"], 202) + self.assert_generation_telemetry_is_safe(event, payload=payload) + + def test_async_image_submit_usage_telemetry_logs_error_code_without_sensitive_data(self): + self.wallet.points_balance = 1 + self.wallet.save(update_fields=("points_balance", "updated_at")) + payload = { + "prompt": "余额不足遥测测试", + "model": self.image_alias, + "resolution": "1K", + } + + with self.assertLogs("cmhub.api.generation_usage", level="INFO") as captured: + response = self.post_with_provider( + "/api/v1/generate/image/tasks", + payload, + HTTP_X_CLIENT_VERSION="0.1.3", + ) + + self.assertEqual(response.status_code, 402) + event = self.telemetry_event_from_logs(captured) + self.assertEqual(event["route_type"], "async") + self.assertEqual(event["status"], "error") + self.assertEqual(event["error_code"], "insufficient_points") + self.assertEqual(event["http_status"], 402) + self.assertEqual(event["client_version"], "0.1.3") + self.assertEqual(event["alias"], self.image_alias) + self.assert_generation_telemetry_is_safe(event, payload=payload) + @override_settings( MODERATION_ENABLED=True, MODERATION_PROVIDER="keyword", diff --git a/apps/api/views.py b/apps/api/views.py index b840ae4..91669ae 100644 --- a/apps/api/views.py +++ b/apps/api/views.py @@ -30,6 +30,12 @@ from apps.api.serializers import ( RechargeCreateRequestSerializer, RechargeStatusRequestSerializer, ) +from apps.api.telemetry import ( + log_generation_route_usage, + request_alias, + telemetry_elapsed_ms, + telemetry_start_time, +) from apps.api.throttles import GenerateRateThrottle, throttle_api_auth_failure from apps.ai.catalog import get_public_model_catalog from apps.billing.models import RechargeOrder @@ -95,12 +101,24 @@ class GenerateImageView(ExternalApiView): throttle_classes = (GenerateRateThrottle,) def post(self, request): + started = telemetry_start_time() + alias = request_alias(request.data) serializer = GenerateImageRequestSerializer(data=request.data) if not serializer.is_valid(): + log_generation_route_usage( + route_type="sync", + request=request, + alias=alias, + status="error", + latency_ms=telemetry_elapsed_ms(started), + error_code="bad_request", + http_status=status.HTTP_400_BAD_REQUEST, + ) return Response( api_error("bad_request", "参数错误"), status=status.HTTP_400_BAD_REQUEST, ) + alias = serializer.validated_data.get("model") or alias try: data = generate_image_response( user=request.user, @@ -109,7 +127,24 @@ class GenerateImageView(ExternalApiView): image_url_builder=request.build_absolute_uri, ) except ApiRequestError as exc: + log_generation_route_usage( + route_type="sync", + request=request, + alias=alias, + status="error", + latency_ms=telemetry_elapsed_ms(started), + error_code=exc.code, + http_status=exc.http_status, + ) return Response(exc.as_response_data(), status=exc.http_status) + log_generation_route_usage( + route_type="sync", + request=request, + alias=data.get("alias") or alias, + status="success", + latency_ms=telemetry_elapsed_ms(started), + http_status=status.HTTP_200_OK, + ) return Response(data, status=status.HTTP_200_OK) @@ -117,12 +152,24 @@ class GenerateImageTaskSubmitView(ExternalApiView): throttle_classes = (GenerateRateThrottle,) def post(self, request): + started = telemetry_start_time() + alias = request_alias(request.data) serializer = GenerateImageRequestSerializer(data=request.data) if not serializer.is_valid(): + log_generation_route_usage( + route_type="async", + request=request, + alias=alias, + status="error", + latency_ms=telemetry_elapsed_ms(started), + error_code="bad_request", + http_status=status.HTTP_400_BAD_REQUEST, + ) return Response( api_error("bad_request", "参数错误"), status=status.HTTP_400_BAD_REQUEST, ) + alias = serializer.validated_data.get("model") or alias try: task, _created = create_image_generation_task( user=request.user, @@ -131,7 +178,24 @@ class GenerateImageTaskSubmitView(ExternalApiView): idempotency_key=request.headers.get("Idempotency-Key", ""), ) except ApiRequestError as exc: + log_generation_route_usage( + route_type="async", + request=request, + alias=alias, + status="error", + latency_ms=telemetry_elapsed_ms(started), + error_code=exc.code, + http_status=exc.http_status, + ) return Response(exc.as_response_data(), status=exc.http_status) + log_generation_route_usage( + route_type="async", + request=request, + alias=task.call_record.alias, + status="success", + latency_ms=telemetry_elapsed_ms(started), + http_status=status.HTTP_202_ACCEPTED, + ) return Response(task_submit_response(task), status=status.HTTP_202_ACCEPTED) diff --git a/docs/00-ai-start-here.md b/docs/00-ai-start-here.md index 0f892e2..ccd69ab 100644 --- a/docs/00-ai-start-here.md +++ b/docs/00-ai-start-here.md @@ -38,7 +38,7 @@ ## 当前阶段 -当前项目处于：**Phase 6 增强任务推进期**。Phase 2 计费核心已完成到 T-204；Phase 3 已完成 T-301 API Key 鉴权、T-302 生成标题 / 图片接口、T-303 余额查询接口、T-304 充值回调、T-305 扫码充值下单 + 轮询与 T-306 对外 API 安全加固；Phase 4 已完成 T-501 注册 / 登录（allauth）、T-502 API Key 自助管理页、T-503 个人中心 / 记录页、T-504 充值页与 T-505 用户端审核优化；Phase 5 已完成 T-401 运营后台完善、T-402 MVP 完整验收与 T-403 部署 / 运行文档；Phase 6 已完成 T-601「可用别名发现」、T-602「django-admin 中文化第 1-3 层」、T-603「django-admin 字段级中文化」、T-604「中文敏感词本地过滤」、T-605「免邮箱验证策略落地」、T-606「公开首页 + 客户端下载入口」、T-607「桌面端最新版本检查接口」、T-608「新用户注册赠送 100 点试用点数」、T-609「桌面端版本检查接口增加强制更新标记」、T-610「首页导入模板下载入口」、T-611「用户端品牌名统一为虾皮圈」、T-612「生图同步接口止血」、T-613「抽生成核心 service」与 T-614「生图异步任务化接口」。生图慢 / 504 / 客户端超时已拆为 T-612~T-615：T-612 已先做同步接口上游硬截止止血，T-613 已抽共享生成 core，T-614 已新增异步提交 / 轮询接口与 DB worker；下一步 T-615 观察旧同步接口用量并形成弃用口径。生产侧仍需补真实支付回调到账闭环；邮件服务仅用于后续密码找回/通知等邮件能力，不阻塞注册登录。 +当前项目处于：**Phase 6 增强任务推进期**。Phase 2 计费核心已完成到 T-204；Phase 3 已完成 T-301 API Key 鉴权、T-302 生成标题 / 图片接口、T-303 余额查询接口、T-304 充值回调、T-305 扫码充值下单 + 轮询与 T-306 对外 API 安全加固；Phase 4 已完成 T-501 注册 / 登录（allauth）、T-502 API Key 自助管理页、T-503 个人中心 / 记录页、T-504 充值页与 T-505 用户端审核优化；Phase 5 已完成 T-401 运营后台完善、T-402 MVP 完整验收与 T-403 部署 / 运行文档；Phase 6 已完成 T-601「可用别名发现」、T-602「django-admin 中文化第 1-3 层」、T-603「django-admin 字段级中文化」、T-604「中文敏感词本地过滤」、T-605「免邮箱验证策略落地」、T-606「公开首页 + 客户端下载入口」、T-607「桌面端最新版本检查接口」、T-608「新用户注册赠送 100 点试用点数」、T-609「桌面端版本检查接口增加强制更新标记」、T-610「首页导入模板下载入口」、T-611「用户端品牌名统一为虾皮圈」、T-612「生图同步接口止血」、T-613「抽生成核心 service」、T-614「生图异步任务化接口」与 T-615「旧同步生图接口遥测 / 弃用口径」。生图慢 / 504 / 客户端超时已拆为 T-612~T-615 并完成：T-612 已做同步接口上游硬截止止血，T-613 已抽共享生成 core，T-614 已新增异步提交 / 轮询接口与 DB worker，T-615 已给旧同步 / 新异步提交路径接入结构化日志并形成旧同步接口退出条件。生产侧仍需补真实支付回调到账闭环；邮件服务仅用于后续密码找回/通知等邮件能力，不阻塞注册登录。 优先路径： @@ -48,7 +48,7 @@ 4. Phase 3：对外 API 与充值 —— T-301 Key 鉴权、T-302 生成接口、T-303 余额查询、T-304 充值回调、T-305 扫码下单与轮询、T-306 安全加固已完成。 5. Phase 4：用户端（Django 模板 SSR）—— T-501 注册登录、T-502 API Key 管理、T-503 个人中心 / 记录页、T-504 充值页与 T-505 用户端审核优化已完成。 6. Phase 5：后台与发布 —— T-401 运营后台完善、T-402 完整验收 MVP、T-403 部署 / 运行文档已完成；计划内 MVP 任务已收尾。 -7. Phase 6：增强（MVP 后）—— T-601 可用别名发现已完成，实现 `/api/v1/models` 与 portal 只读「可用模型」页；T-602 已完成 django-admin 分组/表名中文化；T-603 已完成字段级中文标签代码与 no-op 迁移并人工确认 admin 字段中文化；T-604 已完成中文敏感词本地过滤；T-605 已完成免邮箱验证策略落地；T-606 已完成公开首页 + 客户端下载入口；T-607 已完成桌面端最新版本检查接口；T-608 已完成新用户注册赠送 100 点试用点数；T-609 已完成桌面端版本检查接口增加强制更新标记；T-610 已完成首页导入模板下载入口；T-611 已完成用户端品牌名统一为虾皮圈；T-612 已完成生图同步接口止血；T-613 已完成抽生成核心 service；T-614 已完成生图异步任务化接口；当前下一个可领取任务为 T-615。 +7. Phase 6：增强（MVP 后）—— T-601 可用别名发现已完成，实现 `/api/v1/models` 与 portal 只读「可用模型」页；T-602 已完成 django-admin 分组/表名中文化；T-603 已完成字段级中文标签代码与 no-op 迁移并人工确认 admin 字段中文化；T-604 已完成中文敏感词本地过滤；T-605 已完成免邮箱验证策略落地；T-606 已完成公开首页 + 客户端下载入口；T-607 已完成桌面端最新版本检查接口；T-608 已完成新用户注册赠送 100 点试用点数；T-609 已完成桌面端版本检查接口增加强制更新标记；T-610 已完成首页导入模板下载入口；T-611 已完成用户端品牌名统一为虾皮圈；T-612 已完成生图同步接口止血；T-613 已完成抽生成核心 service；T-614 已完成生图异步任务化接口；T-615 已完成旧同步生图接口遥测与弃用口径；当前没有未领取的编号任务。 ## 领取任务规则 diff --git a/docs/04-architecture.md b/docs/04-architecture.md index e03fe7a..0484721 100644 --- a/docs/04-architecture.md +++ b/docs/04-architecture.md @@ -43,6 +43,8 @@ T-302 已实现 `/api/v1/generate/title` 与 `/api/v1/generate/image`：API 层 T-614 已实现 `/api/v1/generate/image/tasks` 与 `/api/v1/generate/image/tasks/{task_id}`：提交接口同步审核 prompt、解析图片输入和预扣点，创建 `ImageGenerationTask(status=queued)` 后立即返回公开 UUID `task_id`；后台 worker 通过 `select_for_update(skip_locked)` 抢任务，复用 T-613 `execute_precharged_generation()` 对已预扣 `CallRecord` 调上游、保存结果、成功确认或失败退点。任务表记录 worker 租约、心跳和尝试次数；reaper 识别僵尸 `running` 任务后默认判失败并幂等退点，不默认重排队。异步 worker 没有 DRF request，结果 URL 由 `MEDIA_PUBLIC_BASE_URL` / `PUBLIC_BASE_URL` 生成。 +T-615 已给旧同步生图接口和新异步提交接口接入 `cmhub.api.generation_usage` 结构化日志，事件名为 `generation_route_usage`。日志字段只包含 `route_type(sync/async)`、`api_key_id`、`api_key_prefix`、`user_id`、`client_version`、`alias`、`status`、`latency_ms`、`error_code`、`http_status` 等白名单信息；不得记录 API Key 明文、prompt 全文、`image_base64`、provider raw 或上游密钥。第一版用日志查询完成用量观察，不新增报表表结构；如后续要在 admin 做统计报表，需单独评估数据量、索引和保留周期。 + T-303 已实现 `/api/v1/balance`：外部 API 继续只认 API Key，API 层调用 `apps.billing.services.get_balance_snapshot()` 读取当前钱包余额；测试覆盖余额响应与流水累加一致的场景。 T-304 已实现 `/api/v1/recharge/callback/wechat` 与 `/api/v1/recharge/callback/alipay`：两个回调端点均 `@csrf_exempt` 且不挂登录态；回调验签后调用 `apps.billing.services.apply_recharge_payment()`，按 `order_no` 锁定 `RechargeOrder` 幂等入账，金额或通道不一致不加点。缺真实商户配置时仅允许使用明确的 HMAC mock 模式联调，生产应切换 `PAYMENT_CALLBACK_MODE=sdk`。 @@ -488,7 +490,7 @@ CREATE TABLE image_generation_task ( 1. **超时链路层层放大且对齐**（外层 ≥ 内层）：桌面端读超时 ≥ Nginx `proxy_read_timeout` ≥ Gunicorn `--timeout` ≥ cmhub→中转站实际读取超时。T-612 后生图读取超时为 `min(AiModel.timeout_seconds 或分辨率默认值, AI_IMAGE_UPSTREAM_DEADLINE_SECONDS)`；默认硬截止约 180s，生产按真实图片 smoke 校准。三个默认值仍是雷：`AiModel.timeout_seconds`（`0` 表示按 Provider 分辨率默认值，而不是无限等待）、Gunicorn 默认 `30s`（会直接杀掉跑图片的 worker）、Nginx 默认 `60s`。 2. **worker/线程数按峰值总并发预留**：同步下每个在飞请求占住一个 worker 整个生成周期（几十秒~分钟）。用 Gunicorn `gthread`（`--threads`）或多 sync worker，数量 ≥ 预期峰值总并发 + 余量，避免慢图片把快的生文接口和后台挤死。 -适用边界：**旧客户端 / 小并发批量**（桌面端 `concurrency` 1~4）仍可继续同步使用，点数一致性简单。T-614 起新版客户端优先走异步任务接口：提交后拿 `task_id`，后台 worker 慢慢生成，客户端轮询状态和结果，适合图片耗时长、窗口重启后继续查询、以及避免 HTTP 长连接占满生成池的场景。旧同步接口的用量观察和弃用条件放到 T-615。 +适用边界：**旧客户端 / 小并发批量**（桌面端 `concurrency` 1~4）仍可继续同步使用，点数一致性简单。T-614 起新版客户端优先走异步任务接口：提交后拿 `task_id`，后台 worker 慢慢生成，客户端轮询状态和结果，适合图片耗时长、窗口重启后继续查询、以及避免 HTTP 长连接占满生成池的场景。T-615 起通过 `generation_route_usage` 日志观察旧同步路与新异步路的调用量、客户端版本、错误率和耗时；旧同步接口下线前必须先保持成功响应兼容，待新版客户端默认异步、旧路调用归零或连续一段时间低于阈值后，再宣布 deprecate 并单独立任务下线。 ## 六、推荐开发顺序 diff --git a/docs/06-tasks.md b/docs/06-tasks.md index 89c4e07..9b0d1d2 100644 --- a/docs/06-tasks.md +++ b/docs/06-tasks.md @@ -93,7 +93,7 @@ | T-612 | 生图同步接口止血（上游硬截止 + 长请求池校准） | T-403 | **先行止血，不改成功响应契约**，保护存量老客户端的旧同步路。**真实现状**：线上已按路径分流到独立 Gunicorn 长请求池，当前是 `gthread` 而非 sync worker；P0 风险是同步生图长请求仍会占用生成池线程，上游慢 / 卡死时导致生成池排队、客户端写入或读取超时，并可能拖慢同池生文接口。**硬截止优先**：新增可配置上游生图硬截止（建议 `AI_IMAGE_UPSTREAM_DEADLINE_SECONDS`，默认 180s 左右，生产按真实 smoke 校准），Provider 实际读取超时取 `min(AiModel.timeout_seconds 或分辨率默认值, AI_IMAGE_UPSTREAM_DEADLINE_SECONDS)`；撞截止必须走现有失败退点路径，保证不超扣、不扣成负数。**Worker 策略**：默认继续使用已验证的 `gthread` 长请求池并校准 `workers/threads/timeout`；只有在本地和生产预演证明 `requests`、PyMySQL、Django cache、支付 SDK 在 monkey-patch 下无问题时，才允许把 `gevent` 作为替代方案写入部署文档，不能把 gevent 当成默认第一步。**接口兼容**：`POST /api/v1/generate/image` 的成功响应字段保持不变；失败响应外层结构保持 `{error:{code,message}}`，如新增 `upstream_timeout` 错误码必须同步 `api.md` 并保持旧客户端可按失败处理。**文档**：同步 `deployment.md`（硬截止、`AiModel.timeout_seconds`、Gunicorn `--timeout`、Nginx `proxy_read_timeout`、客户端 read timeout 的外层 >= 内层关系）、`04-architecture.md` 和 `env.md`。**验收**：模拟上游超时能退点并返回结构化错误；压测下卡死上游不会拖垮 `/balance`、`/models`，生文排队受控；线上配置仍保留 web 池和 generate 池分离；`check`/目标测试/`init` 通过并在 `../progress.md` 留证据 | DONE | | T-613 | 抽生成核心 service（计费+审核+上游共享 core） | T-612, T-302, T-604 | 为异步化铺路，**重构现有 `apps/api/generation.py`，不是另写第二套生成逻辑**。把「别名解析+能力校验 → 审核(T-604) → 图片输入处理 → 计费计算 → 预扣(precharge) → 调上游 → 保存结果 → 成功确认/失败退点」整理为不依赖 DRF `Request` / `Response` 的核心 service，并为 T-614 拆出可复用的阶段：同步旧接口可一口气执行完整 pipeline，异步 worker 可复用“已预扣 call_record 的执行与确认 / 退点”阶段，**严禁复制第二套扣点/退点逻辑**。**HTTP 解耦**：核心 service 不直接构造 DRF `Response`，错误用领域异常表达；图片保存不能强依赖 `request.build_absolute_uri()`，需通过 URL 构建器或公开基础 URL 生成结果 URL。**兼容约束**：旧 `POST /api/v1/generate/title|image` 的字段、HTTP 状态码和错误语义保持不变；不要求 JSON 字段顺序逐字节一致。**验收**：T-302/T-604 既有断言不降低标准即通过；覆盖旧同步接口成功、上游失败退点、敏感词拦截不扣点、图片 URL 保存；`check`/目标测试/`init` 通过并在 `../progress.md` 留证据 | DONE | | T-614 | 生图异步任务化接口（提交+轮询，新增不动旧接口） | T-613, T-203, T-301 | 新增任务化接口与旧同步接口**共存**（expand-contract 并行变更），新版桌面端走新路、老版本零感知。跨仓契约参考 cmshopee 侧设计（Obsidian「生图接口异步任务化-提交轮询方案」评审修订 v2），**落地口径以本任务 + `api.md` 为准**。**新增路由**：`POST /api/v1/generate/image/tasks`（提交后返回 `202` + `task_id`）、`GET /api/v1/generate/image/tasks/{task_id}`（轮询取状态和结果）；本期不暴露 cancel 路由，若后续要做取消单独拆任务且只允许取消 `queued`。**任务模型**：新增 `ImageGenerationTask`，公开 `task_id` 用 UUID，不暴露自增 ID；字段至少包含 `user`、`api_key`、`call_record`、`status(queued/running/succeeded/failed/expired)`、`idempotency_key`、`request_hash`、必要的请求快照 / 输入引用、`result_url`、`error_code`、`error_message`、`started_at`、`finished_at`、`expires_at`、`locked_at`、`lease_expires_at`、`heartbeat_at`、`worker_id`、`attempt_count`。不得把 provider raw、密钥或超大 base64 原文长期存 DB；`image_base64` 应先解码后落临时文件 / 存储引用，`image_url` submit 阶段至少做协议与公网地址校验，实际下载可在 worker 内执行，失败走退点。**提交段**：审核(T-604)同步执行，命中 BLOCK 直接 `400 content_blocked`，不建 task、不扣点、不调上游；submit 时预扣（沿用现有 `precharge`），余额不足 `402`，堵住「余额只够 1 张却提交 100 个 task」；建任务后立即返回 `202`。**幂等**：支持 `Idempotency-Key`，按 `api_key + operation + key` 去重；同 key 同 payload 返回同一 `task_id` 且不重复预扣，同 key 不同 payload 返回 `409 idempotency_conflict`。**后台 worker**：优先用 DB 任务表 + management command worker + systemd 托管，MySQL 8.4 可用 `select_for_update(skip_locked)` 抢任务；暂不引入 Celery/Redis，`django-q`/`huey` 只有在 DB worker 不够时再单独评估。worker 必须复用 T-613 共享 core 和已预扣的 `CallRecord`，成功保留扣点并返回 cmhub 托管 URL，失败/撞硬截止必须退点。**结果 URL**：异步 worker 没有 request，必须新增 `PUBLIC_BASE_URL` 或 `MEDIA_PUBLIC_BASE_URL` 等配置来生成绝对 URL；不得透传上游临时链接。**查询段**：只读、短超时，必须校验 `task.user == api_key.user`（防 IDOR，跨用户返回 404 或 403）；`succeeded` 幂等重取返回同一 URL；过期任务 / 图片 GC 口径写入文档。**保留窗口**：task_id 持久化的目的是扛客户端重启，窗口须覆盖桌面端现实停机（如关一晚），**任务元数据保留 ≥24h、结果图保留更久（如 24–72h，可配，别硬编码 6h）**，避免「点已扣、图被 GC」。**租约与僵任务回收（reaper，必做）**：worker 抢任务时写 `worker_id`、`locked_at`、`lease_expires_at`，运行中周期性更新 `heartbeat_at`；如果 worker 用 `select_for_update(skip_locked)` 抢任务后崩溃，行锁随连接释放但 `status` 会永远停在 `running`——**点数已预扣却永不退、客户端轮询到自己超时**。reaper 按 `lease_expires_at` / `heartbeat_at`（兜底 `started_at`）识别僵任务，默认把超时 `running` 判 `failed` + **退点（幂等）**，不默认重排队；只有能证明任务尚未调上游（如明确 `stage=not_started`）时才允许后续任务设计重排队。**worker 至少一次执行，账务和结果 exactly-once**：worker 可能重复执行同一任务，但「上游调用确认 / 退点 / 写结果」这些终态动作必须幂等；重复执行不得重复扣/退，不得覆盖已 `succeeded` 结果，也不得把 reaper 已判 `failed` 且已退点的任务改回 `succeeded`。**配置**：新增或同步 `IMAGE_TASK_RETENTION_HOURS`、`GENERATED_IMAGE_RETENTION_HOURS`、`IMAGE_TASK_REAPER_INTERVAL_SECONDS`、`IMAGE_TASK_LEASE_SECONDS` 等环境变量口径。**文档**：同步 `api.md`（新契约、状态机、错误码、幂等）、`routes.md`、`04-architecture.md`（异步计费时序）、`deployment.md`（worker 进程托管）、`env.md`。**验收**：审核命中不建 task/不扣点/不调上游；预扣余额不足 402；同 Idempotency-Key 去重且 payload 冲突 409；worker 成功后重复 GET 同一 URL；跨用户 GET 被拒；失败/超时退点不超扣；**模拟 worker 崩溃留下 `running` 僵任务 → reaper 判失败并退点、不超扣、客户端下次 GET 得到 `failed`**；**worker 重复执行同一任务幂等（不重复扣/退、不覆盖已 `succeeded` 结果）**；**reaper 已把任务判 `failed` 并退点后，迟到 worker 返回成功也不能改回 `succeeded`、不能覆盖结果、不能再次改账**；旧生文与旧同步生图不回归；`check`/目标测试/`init` 通过并在 `../progress.md` 留证据 | DONE | -| T-615 | 旧同步生图接口用量遥测 + 弃用口径 | T-614 | 给旧同步接口装可观测、定弃用退出条件，避免永久双维护。**最小遥测**：旧 `POST /api/v1/generate/image` 和新 `/tasks` 路径都写结构化日志 / 计数，至少含 route_type(sync/async)、api_key 前缀或 ID、user_id、client version（若请求头提供，如 `X-Client-Version`）、alias、status、latency_ms、error_code；日志不得包含 API Key 明文、prompt 全文、图片 base64 或 provider raw。**查看方式**：先用日志查询即可；若要 admin 报表需单独评估数据量和索引。**弃用口径**：在 `deployment.md`/`04-architecture.md` 记录迁移计划：新版桌面端默认走异步接口 → 观察旧路调用量和错误率 → 旧路调用归零或低于阈值一段时间 → 宣布 deprecate → 另立任务下线；旧同步接口下线前必须保留成功响应兼容。**验收**：能按 client version / api_key 看到旧路与新路用量；弃用条件成文；不泄露敏感数据；`check`/目标测试/`init` 通过并在 `../progress.md` 留证据 | TODO | +| T-615 | 旧同步生图接口用量遥测 + 弃用口径 | T-614 | 给旧同步接口装可观测、定弃用退出条件，避免永久双维护。**最小遥测**：旧 `POST /api/v1/generate/image` 和新 `/tasks` 路径都写结构化日志 / 计数，至少含 route_type(sync/async)、api_key 前缀或 ID、user_id、client version（若请求头提供，如 `X-Client-Version`）、alias、status、latency_ms、error_code；日志不得包含 API Key 明文、prompt 全文、图片 base64 或 provider raw。**查看方式**：先用日志查询即可；若要 admin 报表需单独评估数据量和索引。**弃用口径**：在 `deployment.md`/`04-architecture.md` 记录迁移计划：新版桌面端默认走异步接口 → 观察旧路调用量和错误率 → 旧路调用归零或低于阈值一段时间 → 宣布 deprecate → 另立任务下线；旧同步接口下线前必须保留成功响应兼容。**验收**：能按 client version / api_key 看到旧路与新路用量；弃用条件成文；不泄露敏感数据；`check`/目标测试/`init` 通过并在 `../progress.md` 留证据 | DONE | ## 里程碑 diff --git a/docs/api.md b/docs/api.md index 96a9a7a..be3ebf6 100644 --- a/docs/api.md +++ b/docs/api.md @@ -25,6 +25,8 @@ T-302 已实现生成接口基线：`POST /api/v1/generate/title` 与 `POST /api T-614 已实现生图异步任务化：`POST /api/v1/generate/image/tasks` 返回 `202` 与公开 UUID `task_id`，`GET /api/v1/generate/image/tasks/{task_id}` 轮询任务状态和结果。任务表 `ImageGenerationTask` 关联 `user`、`api_key` 与已预扣 `CallRecord`，支持 `Idempotency-Key` 去重、payload 冲突 `409 idempotency_conflict`、租约 / 心跳 / reaper 处理僵尸 running 任务并幂等退点。异步结果 URL 由 `MEDIA_PUBLIC_BASE_URL` 或 `PUBLIC_BASE_URL` 生成，不透传上游临时链接。 +T-615 已实现生图接口用量遥测：旧同步 `POST /api/v1/generate/image` 与新异步提交 `POST /api/v1/generate/image/tasks` 都会写 `cmhub.api.generation_usage` 结构化日志，事件名 `generation_route_usage`。调用方可选带 `X-Client-Version` 请求头，便于按客户端版本观察旧同步路迁移进度；该请求头不参与鉴权、计费或幂等判断。日志只记录 route/user/key 前缀/客户端版本/别名/状态/耗时/错误码等白名单字段，不记录 API Key 明文、prompt、图片 base64 或 provider raw。 + T-303 已实现余额查询基线：`GET /api/v1/balance` 已接入 API Key 鉴权，返回当前 `UserWallet.points_balance`，并保留旧字段同时新增不含邮箱的 `account` 账号展示对象；测试覆盖响应余额与 `PointsLedger.points_delta` 累加值一致的账务场景，并确认 Web session 不能调用该外部接口。 T-601 已实现可用别名发现：`GET /api/v1/models` 已接入 API Key 鉴权，只返回当前 active 且具备对应能力的公开别名、能力、是否需要原图和点数单价；接口不调用 `AiModel.to_resolved_model()`，不解密 provider key，不返回底层 SKU、模型 URL、`api_key_encrypted`、`extra_body` 等内部配置，且成功请求不占用生成接口限流额度。 @@ -172,6 +174,14 @@ GET /api/v1/client/releases/latest?platform=windows 生成图片（同步等待）。请求： +可选请求头： + +```http +X-Client-Version: 0.1.1 +``` + +该字段仅用于 T-615 的用量遥测，帮助服务端区分旧同步接口由哪些客户端版本调用；不影响响应结构。 + ```json { "prompt": "把这件衣服换成模特上身的穿搭图", @@ -208,6 +218,7 @@ GET /api/v1/client/releases/latest?platform=windows POST /api/v1/generate/image/tasks Authorization: Bearer sk_cmhub_xxx Idempotency-Key: desktop-job-20260708-0001 +X-Client-Version: 0.1.1 Content-Type: application/json ``` diff --git a/docs/current-state.md b/docs/current-state.md index c61d3eb..c3e2986 100644 --- a/docs/current-state.md +++ b/docs/current-state.md @@ -12,10 +12,12 @@ ## 当前快照 - 日期：2026-07-08 -- 阶段：Phase 6 增强（MVP 后）；Phase 3 对外 API 与充值已完成到 T-306，Phase 4 用户端 T-501 注册 / 登录（allauth）、T-502 API Key 自助管理页、T-503 个人中心 / 记录页、T-504 充值页与 T-505 用户端审核优化已完成，Phase 5 T-401 运营后台完善、T-402 MVP 完整验收与 T-403 部署 / 运行文档已完成，Phase 6 T-601 可用别名发现、T-602 django-admin 中文化第 1-3 层、T-603 django-admin 字段级中文化、T-604 中文敏感词本地过滤、T-605 免邮箱验证策略落地、T-606 公开首页 + 客户端下载入口、T-607 桌面端最新版本检查接口、T-608 新用户注册赠送 100 点试用点数、T-609 桌面端版本检查接口增加强制更新标记、T-610 首页导入模板下载入口、T-611 用户端品牌名统一为虾皮圈、T-612 生图同步接口止血、T-613 抽生成核心 service 与 T-614 生图异步任务化接口已完成；后续仍需处理真实支付回调到账闭环、客户端下载包发布和 T-615 旧同步生图接口遥测 +- 阶段：Phase 6 增强（MVP 后）；Phase 3 对外 API 与充值已完成到 T-306，Phase 4 用户端 T-501 注册 / 登录（allauth）、T-502 API Key 自助管理页、T-503 个人中心 / 记录页、T-504 充值页与 T-505 用户端审核优化已完成，Phase 5 T-401 运营后台完善、T-402 MVP 完整验收与 T-403 部署 / 运行文档已完成，Phase 6 T-601 可用别名发现、T-602 django-admin 中文化第 1-3 层、T-603 django-admin 字段级中文化、T-604 中文敏感词本地过滤、T-605 免邮箱验证策略落地、T-606 公开首页 + 客户端下载入口、T-607 桌面端最新版本检查接口、T-608 新用户注册赠送 100 点试用点数、T-609 桌面端版本检查接口增加强制更新标记、T-610 首页导入模板下载入口、T-611 用户端品牌名统一为虾皮圈、T-612 生图同步接口止血、T-613 抽生成核心 service、T-614 生图异步任务化接口与 T-615 旧同步生图接口遥测 / 弃用口径已完成；后续仍需处理真实支付回调到账闭环、客户端下载包发布和生产侧旧同步接口用量观察 - 技术栈：系统 Python 3.12.3 + Django 5.2.15 + DRF 3.16.1 + django-allauth 65.18.0 + PyMySQL 1.1.3 + cryptography 49.0.0 + requests 2.34.2 + ahocorapy 1.6.2 + wechatpayv3 2.0.2 + python-alipay-sdk 3.4.0 + django-admin；MySQL 8.4 已接入 settings，并支持 `MYSQL_CONNECT_TIMEOUT` / `MYSQL_READ_TIMEOUT` / `MYSQL_WRITE_TIMEOUT`；用户端已用 Django 模板 SSR + Bootstrap + allauth 落地注册登录；生产部署口径为 VPS / 宝塔 + Nginx + Gunicorn(gthread) + systemd；详见 `03-tech-stack.md` 与 `deployment.md` - 生产代码：已有最小 Django 工程骨架：`manage.py`、`config/`；T-002 已创建 `apps/users|portal|billing|ai|api`；T-003 已把自定义 `User` 注册进 django-admin；T-004 已完成 email 唯一性、init 版本断言、app 顺序、`.env.example` 与 `pyproject.toml`；T-101 已新增 `apps/ai/providers/`（Provider 接口、注册表、chat/gemini/images/images_edits 适配器）；T-102 已新增 `AiModel` / `ModelAlias`、Fernet 加密密钥存储、别名解析、admin 配置页、`import_ai_models` 导入命令；T-103 已新增 `AiConfigAuditLog` 审计表、admin 只读页面和后台保存/删除审计 hook；T-104/T-105 已完成录制 title/image smoke 与审核修补；T-201 已新增 `UserWallet` / `ApiKey`、`PointsLedger` / `CallRecord`、对应 admin 与迁移；T-202 已新增 `PricingRule` / `ExchangeRate`、`apps.billing.pricing` 计费计算函数、admin 配置页与迁移；T-203 已新增 `apps.billing.services`，实现并发安全预扣、成功确认与幂等失败退点；T-204 已新增 `billing.0003_pointsledger_unique_ledger_change_type_per_call`，用 MySQL 可落地的 `ref_call + change_type` 复合唯一约束兜底防重复 refund；T-301 已新增 `apps.api.authentication.ApiKeyAuthentication` 与 `ExternalApiView`；T-302 已新增生成接口编排、序列化器、图片本地存储和 `/api/v1/generate/title|image` 路由；T-303 已新增 `apps.billing.services.get_balance_snapshot()` 与 `/api/v1/balance` 余额查询接口；T-304 已新增 `RechargeOrder`、充值回调验签适配器、幂等入账服务、微信/支付宝回调路由与迁移 `billing.0004_rechargeorder_and_more`；T-305 已新增 `create_recharge_order()`、微信/支付宝扫码下单 mock/SDK 入口、`/api/v1/recharge/create` 与 `/api/v1/recharge/status`；T-306 已新增 `apps.api.throttles`、`apps.api.exceptions`、`REST_FRAMEWORK` 安全默认认证、生成/认证失败限流、`image_url` SSRF 防护与响应大小上限、充值单笔金额上限；T-501/T-608 已接入 allauth 注册登录路径，注册成功后 adapter 调用 `grant_signup_bonus()` 经 billing 一次性发放 100 点并写 `signup_bonus` 流水，新增 `SignupBonusGrant(user UNIQUE)` 幂等标记、admin 只读检索和 `billing.0007` 迁移；T-502 已新增 `/apikeys`、API Key 创建表单、列表页和删除（吊销）动作，生成后明文只显示一次，列表只显示 prefix；T-503/T-608 已扩展 `/dashboard` 为个人中心汇总，并新增 `/records/recharge` 充值记录与 `/records/usage` 点数记录，只读展示当前用户数据和注册赠点 / 消费 / 退款流水；T-504 已新增 `/recharge` 页面、`RechargeCreateForm`、充值导航入口和轮询脚本，页面创建 pending 订单、展示二维码票据、轮询 `/api/v1/recharge/status`，订单 paid 后刷新余额；T-505 已把 Bootstrap 5 CSS 与 qrcode.js vendoring 到 `apps/portal/static/portal/vendor/`，页面不再依赖 jsdelivr，并把充值记录 / 点数记录改为 Django `Paginator` 分页；T-401 已新增 `adjust_wallet_points()` 手工调点服务、钱包 admin 专用调点表单与模板，后台可管理/检索用户、钱包、API Key（脱敏）、计费规则、汇率、充值订单、点数流水、注册赠点记录和调用记录，流水/订单/调用记录保持只读；T-402 已新增 `docs/mvp-acceptance.md`，按 P0 验收矩阵记录 MVP 完整验收结论、测试证据和已知限制；T-403 已新增 `docs/deployment.md` 与 `requirements-production.txt`，并在 settings 中补齐 `STATIC_ROOT`、`CSRF_TRUSTED_ORIGINS`、共享 `CACHES`、HTTPS cookie、proxy SSL、HSTS 环境变量与 `ACCOUNT_SIGNUP_RATE_LIMIT` 注册限流配置；T-601 已新增 `apps.ai.catalog.get_public_model_catalog()`、`GET /api/v1/models` 与 portal `/models` 只读页面，只展示 active 可调用别名、能力、是否需要原图和点数单价，不解密 provider key，不暴露底层 SKU / URL / key / `extra_body`；T-604 已新增 `apps.moderation`、`SensitiveWord` 模型/admin/迁移、keyword provider、归一化管线和共享 cache 版本失效，生成接口已改为 prompt 先审再读取图片/计费/扣点/调上游；T-606 已新增公开首页 `/`、`DownloadRelease` 模型/admin/迁移、首页 SSR 模板、共享 `portal/brand.css`，并把现有 portal 页面套入同一套品牌 token；T-607/T-609 已新增 `ClientLatestReleaseView` 与 `/api/v1/client/releases/latest`，公开匿名返回当前客户端版本 JSON，`release.force_update` 表示该版本是否强制升级；`portal.0002_downloadrelease_force_update` 已给 `DownloadRelease` 增加 `force_update` 字段，admin 可编辑和筛选；T-610 已新增 `ImportTemplate` 模型/admin/迁移 `portal.0003_importtemplate`，首页读取当前模板并在“下载客户端”旁展示“下载导入模板”，本地文件 URL 转为当前站点绝对 URL，`external_url` 优先；T-611 已把用户端 portal 可见品牌名统一为“虾皮圈”，包括页面标题、顶部导航、首页 H1、用户端“虾皮圈 API Key”文案和 allauth 邮件模板；T-612 已新增 `AI_IMAGE_UPSTREAM_DEADLINE_SECONDS`，生图 Provider 上游请求和上游返回图片 URL 下载会按 `min(AiModel.timeout_seconds 或分辨率默认值, 硬截止)` 控制读取超时，超时返回 `upstream_timeout` 并走既有失败退点路径；T-613 已把旧同步生成链路抽成 `GenerationInput`、`prepare_generation()`、`precharge_generation()`、`execute_precharged_generation()` 与 `GenerationResult`，旧 view 只负责 serializer 和异常转 HTTP，后续异步 worker 可复用已预扣执行 / 确认 / 退点阶段。 - T-614 生产代码补充：已新增 `ImageGenerationTask` 与 `api.0001_initial`，新增 `POST /api/v1/generate/image/tasks`、`GET /api/v1/generate/image/tasks/{task_id}`、`apps.api.image_tasks` 任务服务、`run_image_tasks` management command 和只读 admin；异步提交支持 `Idempotency-Key` 去重 / 冲突检测，worker 使用 DB 任务表、租约、心跳与 reaper，成功返回 cmhub 托管 URL，失败 / 超时 / 僵任务走计费层幂等退款。 +- T-615 生产代码补充：已新增 `apps.api.telemetry`，旧同步 `POST /api/v1/generate/image` 与新异步提交 `POST /api/v1/generate/image/tasks` 都写 `cmhub.api.generation_usage` 结构化日志事件 `generation_route_usage`；字段白名单为 `route_type`、API Key ID/前缀、`user_id`、`X-Client-Version`、别名、状态、耗时、错误码和 HTTP 状态，不记录 API Key 明文、prompt、图片 base64 或 provider raw。 +- 最新验证：T-615 旧同步生图接口遥测已验证 `py -3.12 -m py_compile apps\api\telemetry.py apps\api\views.py apps\api\tests.py` 通过；新增 3 条目标测试通过，覆盖旧同步成功日志、新异步提交成功日志、异步余额不足错误日志，确认可按 client version / api_key / route_type 查询且不泄露 prompt、base64、完整 API Key 或 provider raw；`py -3.12 manage.py check` 通过，0 issues；`py -3.12 manage.py makemigrations --check --dry-run` 通过，No changes detected；`py -3.12 manage.py test apps.api.tests.GenerateApiTests --keepdb --noinput --verbosity 2` 通过，31 tests OK；`.\init.ps1` 通过；`git diff --check` 通过，仅 Windows CRLF 提示。测试期仍保留 allauth 在 MySQL 条件唯一约束上的既有 `models.W036` 警告。 - 用户端导航：顶部导航 active 状态已修复，`portal/base.html` 基于 `request.resolver_match.url_name` 高亮当前页面入口，并用 `aria-current="page"` 标记；「充值」不再在非充值页固定深色高亮。 - 最新验证：T-614 生图异步任务化接口已验证 `py -3.12 manage.py makemigrations api` 生成 `api.0001_initial`；`py -3.12 manage.py test apps.api.tests.GenerateApiTests -v 2 --keepdb` 通过，28 tests OK，覆盖敏感词拦截不建任务/不扣点、余额不足 402、Idempotency-Key 去重和冲突、worker 成功轮询同一 URL、跨用户拒绝、失败/超时退款、reaper 僵任务退款、重复 worker 幂等和 reaper 退款后的迟到 worker 不可改回成功。首次不带 `--keepdb` 运行时因已有 `test_cmhub` 触发交互式删除确认导致 EOF 中断；重跑 `--keepdb` 通过。测试期仍保留 allauth 在 MySQL 条件唯一约束上的既有 `models.W036` 警告。 - 最新验证：T-613 抽生成核心 service 已验证 `.\init.ps1` 开工前通过；`py -3.12 -m py_compile apps\api\generation.py apps\api\storage.py apps\api\views.py apps\api\tests.py` 通过；`py -3.12 manage.py check` 通过，0 issues；`py -3.12 manage.py makemigrations --check --dry-run` 通过，No changes detected；T-613 新增核心 service 目标测试 2 tests OK；`py -3.12 manage.py test apps.api.tests.GenerateApiTests --keepdb --noinput --verbosity 1` 通过，19 tests OK；`.\init.ps1` 收尾通过；`git diff --check` 通过，仅 Windows CRLF 提示。曾尝试 `py -3.12 manage.py test apps.api --keepdb --noinput --verbosity 1`，命令 484 秒超时无断言结果；拆跑非生成 API 测试类时在测试库 setup 阶段出现远程 MySQL `43.128.3.240` 连接超时 `OperationalError(2003)`，期间 `Test-NetConnection 43.128.3.240 -Port 3306` 显示端口可达。测试期仍保留 allauth 在 MySQL 条件唯一约束上的既有 `models.W036` 警告。 @@ -38,7 +40,7 @@ - 标准验证路径：Windows 用 `py -3.12 manage.py check` / `py -3.12 manage.py test` - 设计基线：**自助用户端 + 对外 API + 运营后台**三合一单体；用户模型 `User`(auth)/`UserWallet`(点数，锁 wallet 扣点)/`ApiKey`(1:N，哈希存储)；对外两接口 + **能力别名 + Provider 适配器**（可插拔供应商）；自助扫码充值；新用户注册成功一次性赠送 100 点试用点数，必须经 billing 写 `signup_bonus` 流水，且通过 `SignupBonusGrant(user UNIQUE)` 防重复发放。详见 `04-architecture.md` 与 2026-07-08 的 `progress.md` 决策 - 配置基线：运行环境变量集中见 `docs/env.md`；真实密钥/支付凭证不得写入代码或文档样例。用户端注册策略固定为 `ACCOUNT_EMAIL_VERIFICATION="none"`：免邮箱验证、注册即可用、邮箱仍必填且唯一；`DJANGO_EMAIL_BACKEND` / `DJANGO_DEFAULT_FROM_EMAIL` 仅用于后续密码找回、通知或恢复邮箱验证等邮件能力，不作为当前注册登录前置条件。充值订单在创建时锁定汇率与预计点数，回调入账使用订单值，不按新汇率重算。支付回调与下单由 `PAYMENT_CALLBACK_MODE` 控制：本地/测试可用 HMAC `mock`，生产应为 `sdk`；二维码本地有效期提示由 `PAYMENT_QR_EXPIRES_MINUTES` 控制。T-306 起对外 API 安全配置包含 `API_GENERATE_THROTTLE_RATE`、`API_AUTH_FAILURE_THROTTLE_RATE`、`IMAGE_URL_MAX_BYTES`、`IMAGE_URL_MAX_REDIRECTS`、`IMAGE_URL_CONNECT_TIMEOUT_SECONDS`、`IMAGE_URL_READ_TIMEOUT_SECONDS`、`RECHARGE_MAX_AMOUNT_CNY`。T-403 起生产静态、共享 cache 与 HTTPS 安全配置包含 `STATIC_URL`、`STATIC_ROOT`、`DJANGO_CACHE_BACKEND`、`DJANGO_CACHE_LOCATION`、`DJANGO_CSRF_TRUSTED_ORIGINS`、`DJANGO_SESSION_COOKIE_SECURE`、`DJANGO_CSRF_COOKIE_SECURE`、`DJANGO_SECURE_SSL_REDIRECT`、`DJANGO_SECURE_PROXY_SSL_HEADER`、`DJANGO_SECURE_HSTS_SECONDS`。T-604 起内容安全配置包含 `MODERATION_ENABLED`、`MODERATION_PROVIDER=keyword`、`MODERATION_FAIL_CLOSED`、`MODERATION_BLOCK_ON_REVIEW`、`MODERATION_CACHE_VERSION_KEY`；生产多 worker 下必须使用共享 cache 承载敏感词版本号。T-612 起生图同步接口止血配置包含 `AI_IMAGE_UPSTREAM_DEADLINE_SECONDS`，只作用于 `generate_image` 上游读取硬截止。T-614 起异步生图配置包含 `PUBLIC_BASE_URL`、`MEDIA_PUBLIC_BASE_URL`、`IMAGE_TASK_RETENTION_HOURS`、`GENERATED_IMAGE_RETENTION_HOURS`、`IMAGE_TASK_REAPER_INTERVAL_SECONDS`、`IMAGE_TASK_LEASE_SECONDS`；生产必须运行 `run_image_tasks` worker。 -- 当前 blocker：微信正式下单已能返回二维码，但线上微信回调曾出现 `PaymentVerificationError`，仍需单独修复并完成“付款后自动入账”闭环验收；支付宝恢复依赖开放平台把 `43.128.3.240` 加入可信 IP。线上真实标题生成已跑通并验证扣点；图片同步旧接口已由 T-612 加上游硬截止止血，T-614 已提供异步任务化路径，下一步按 T-615 补旧同步接口遥测与弃用口径。 +- 当前 blocker：微信正式下单已能返回二维码，但线上微信回调曾出现 `PaymentVerificationError`，仍需单独修复并完成“付款后自动入账”闭环验收；支付宝恢复依赖开放平台把 `43.128.3.240` 加入可信 IP。线上真实标题生成已跑通并验证扣点；图片同步旧接口已由 T-612 加上游硬截止止血，T-614 已提供异步任务化路径，T-615 已补旧同步 / 新异步提交遥测和旧路弃用口径。 ## 当前目录要点 @@ -59,11 +61,11 @@ 任务状态以 [`06-tasks.md`](06-tasks.md) 为准，历史执行记录见 [`../progress.md`](../progress.md)。 -- 已完成：T-001 初始化 Django + DRF 项目骨架；T-002 建立 apps 目录、自定义 User 与配置；T-003 接通 django-admin 与最小测试；T-004 Phase 0 骨架审核修补；T-101 Provider 适配器层 + 移植 cmbot 调用；T-102 AiModel + ModelAlias 模型 + 别名解析；T-103 配置变更审计；T-104 跑通一次录制标题生成；T-105 Phase 1 AI 层审核修补；T-201 User / UserWallet / ApiKey / PointsLedger / CallRecord 模型；T-202 PricingRule / ExchangeRate 模型 + 计费计算；T-203 并发安全扣点 / 退点；T-204 Phase 2 计费核心审核加固；T-301 API Key 鉴权；T-302 生成标题 / 图片接口；T-303 余额查询接口；T-304 充值回调；T-305 扫码充值下单 + 轮询；T-306 Phase 3 对外 API 安全加固；T-501 注册 / 登录（allauth）；T-502 API Key 自助管理页；T-503 个人中心 / 记录页；T-504 充值页（扫码 + 轮询到账）；T-505 Phase 4 用户端审核优化；T-401 运营后台完善；T-402 完整验收 MVP；T-403 部署 / 运行文档；T-601 可用别名发现；T-602 django-admin 中文化（第 1-3 层）；T-603 django-admin 中文化（第 4 层·字段级）；T-604 中文敏感词本地过滤；T-605 免邮箱验证策略落地；T-606 公开首页 + 客户端下载入口；T-607 桌面端最新版本检查接口；T-608 新用户注册赠送 100 点试用点数；T-609 桌面端版本检查接口增加强制更新标记；T-610 首页导入模板下载入口；T-611 用户端品牌名统一为虾皮圈；T-612 生图同步接口止血（上游硬截止 + 长请求池校准）；T-613 抽生成核心 service（计费+审核+上游共享 core）；T-614 生图异步任务化接口（提交+轮询，新增不动旧接口）。 +- 已完成：T-001 初始化 Django + DRF 项目骨架；T-002 建立 apps 目录、自定义 User 与配置；T-003 接通 django-admin 与最小测试；T-004 Phase 0 骨架审核修补；T-101 Provider 适配器层 + 移植 cmbot 调用；T-102 AiModel + ModelAlias 模型 + 别名解析；T-103 配置变更审计；T-104 跑通一次录制标题生成；T-105 Phase 1 AI 层审核修补；T-201 User / UserWallet / ApiKey / PointsLedger / CallRecord 模型；T-202 PricingRule / ExchangeRate 模型 + 计费计算；T-203 并发安全扣点 / 退点；T-204 Phase 2 计费核心审核加固；T-301 API Key 鉴权；T-302 生成标题 / 图片接口；T-303 余额查询接口；T-304 充值回调；T-305 扫码充值下单 + 轮询；T-306 Phase 3 对外 API 安全加固；T-501 注册 / 登录（allauth）；T-502 API Key 自助管理页；T-503 个人中心 / 记录页；T-504 充值页（扫码 + 轮询到账）；T-505 Phase 4 用户端审核优化；T-401 运营后台完善；T-402 完整验收 MVP；T-403 部署 / 运行文档；T-601 可用别名发现；T-602 django-admin 中文化（第 1-3 层）；T-603 django-admin 中文化（第 4 层·字段级）；T-604 中文敏感词本地过滤；T-605 免邮箱验证策略落地；T-606 公开首页 + 客户端下载入口；T-607 桌面端最新版本检查接口；T-608 新用户注册赠送 100 点试用点数；T-609 桌面端版本检查接口增加强制更新标记；T-610 首页导入模板下载入口；T-611 用户端品牌名统一为虾皮圈；T-612 生图同步接口止血（上游硬截止 + 长请求池校准）；T-613 抽生成核心 service（计费+审核+上游共享 core）；T-614 生图异步任务化接口（提交+轮询，新增不动旧接口）；T-615 旧同步生图接口用量遥测 + 弃用口径。 - 正在进行：无。 -- 待开始：T-615 旧同步生图接口用量遥测 + 弃用口径。 -- 当前 blocker：支付商户真实密钥/证书与生产 SDK 依赖仍待提供；微信回调到账闭环仍需真实支付验收；真实 AI 标题生成已在线上跑通，图片生成慢 / 504 / 客户端超时风险已拆为 T-612~T-615 分阶段处理，T-614 已提供异步任务路径。 -- 下一个可领取任务：T-615 旧同步生图接口用量遥测 + 弃用口径。 +- 待开始：无明确编号任务。 +- 当前 blocker：支付商户真实密钥/证书与生产 SDK 依赖仍待提供；微信回调到账闭环仍需真实支付验收；真实 AI 标题生成已在线上跑通，图片生成慢 / 504 / 客户端超时风险已拆为 T-612~T-615 并完成工程侧处理。 +- 下一个可领取任务：无明确编号任务；后续应在生产部署后观察 `generation_route_usage` 日志，并继续补真实支付回调到账闭环、客户端下载包发布等业务事项。 ## 当前可运行内容 @@ -125,15 +127,15 @@ python3.12 manage.py run_image_tasks --worker-id cmhub-image-worker-1 --sleep-se - `GET /records/usage` 当前骨架可运行。T-002 已在首次迁移前创建自定义 User，并按 `env.md` 接入 MySQL 8.4 / utf8mb4；远程 MySQL 已完成 Django 初始迁移。T-003 已接通 django-admin，测试可创建/销毁 `test_cmhub` 测试库；当前远程 MySQL 对频繁建库/销库仍可能间歇超时，必要时用 `--keepdb` 且串行跑测试。T-004 已应用 `users.0002_alter_user_email`，`user.email` 已有唯一索引。T-101 的 AI provider 层只做 HTTP 调用与响应解析；T-102 已把 provider 运行配置接到数据库 `AiModel` / `ModelAlias`，`resolve_alias()` 每次查当前 active 配置并按 `text` / `image` 能力校验。T-103 已补 `AiConfigAuditLog`，admin 保存/删除 `AiModel` / `ModelAlias` 时记录 actor、action、target、changed_fields、changes、created_at，密钥只记录 empty/set 状态。T-104/T-105 已用临时回滚配置跑通录制标题和录制图片生成。T-201 已落地钱包、API Key、点数流水和调用记录：API Key 明文只在创建 helper 返回，库内只存 hash/prefix；CallRecord 只存 `result_ref`/`result_summary`，没有 provider raw 字段。T-202 已落地 `PricingRule` / `ExchangeRate`：计费按 `operation_type + alias + resolution` 查 active 规则，优先精确分辨率，再回退默认价；缺规则抛 `NoPricingRuleError(code="no_pricing_rule")`；金额换点数按当前 active 汇率向下取整。T-203 已落地 `precharge_call()` / `mark_call_success()` / `refund_call_points()`：预扣锁钱包行，余额不足不写调用/流水；失败退点锁调用记录并幂等写 refund 流水。T-204 已完成复合唯一约束加固，并取得一次完整 `manage.py test` 单次全绿。T-301 已落地 `Authorization: Bearer ` 鉴权：成功后 `request.user` 为所属用户、`request.auth` 为 `ApiKey`，缺失/无效 Key 返回 401，用户或 Key 禁用返回 403，外部 API 不接受 Web session。T-302/T-613 已落地生成接口与共享核心：旧同步接口仍保持原响应契约；`prepare_generation()` 执行 prompt 审核、图片输入处理、别名解析、Provider 选择和计费计算；`precharge_generation()` 调 billing 预扣；`execute_precharged_generation()` 复用已预扣 `CallRecord` 调上游并成功确认或失败退点；图片结果保存到本地 media 并通过 URL 构建器返回外部 URL。T-303 已落地余额查询接口：`GET /api/v1/balance` 继承外部 API Key 鉴权，读取 billing 余额快照并返回兼容字段 `user` / `points_balance`，以及不含邮箱的 `account.username` / `account.display_name`，测试覆盖余额与流水累加一致。T-304 已落地充值回调：`RechargeOrder` 保存下单锁定的金额/汇率/点数，微信/支付宝回调先验签再按订单幂等入账，重复回调不重复加点，金额不一致不入账；主动查单兜底可调用 `query_and_apply_recharge_payment(order_no, query_func)` 复用同一入账路径。T-305 已落地扫码下单与轮询：用户端 session 登录后可 `POST /api/v1/recharge/create` 创建 pending 订单并拿到 mock/SDK 二维码票据，`GET /api/v1/recharge/status` 只返回本人订单并在 pending 时尝试主动查单补入账；API Key 不能调用这两个用户端接口。T-306 已落地对外 API 安全加固：`image_url` 下载在扣点前做协议白名单、公网地址校验、重定向逐跳校验和响应大小上限；DRF 全局默认不再隐式启用 Session/Basic；生成接口按 Key 限流，认证失败按 IP 限流；充值下单有单笔金额上限。T-501/T-605/T-608 已落地 allauth 注册 / 登录：`ACCOUNT_EMAIL_VERIFICATION="none"`，免邮箱验证、注册即可用，邮箱仍必填且唯一；注册成功经 billing 发放 100 点并写 `signup_bonus` 流水，重复调用或并发触发由 `SignupBonusGrant` 幂等标记兜底，注册限流由 allauth signup rate limit 执行。T-502 已落地 API Key 自助管理：`/apikeys` 登录访问，生成后完整明文只显示一次，列表只显示 prefix，不显示 hash 或历史明文；删除为吊销 `revoked`，吊销后外部 API 返回 403。T-503/T-608 已落地个人中心与记录页：`/dashboard` 展示剩余点数、充值总额、获得点数、净消耗点数和最近记录；`/records/recharge` 展示当前用户充值订单；`/records/usage` 展示当前用户 signup_bonus/consume/refund 点数流水并关联调用信息；所有页面均只读且只查本人。T-504 已落地充值页：`/recharge` GET 展示余额、充值表单、当前订单和最近充值，POST 创建 pending 订单并展示二维码票据，浏览器轮询 `/api/v1/recharge/status`，paid 后刷新页面重新读取余额；页面不直接写钱包或流水。T-401 已落地运营后台完善：用户列表显示钱包余额，钱包余额只读且通过专用表单手工调点，调点必须填原因、非 0、不得扣成负数，并经 `adjust_wallet_points()` 锁钱包写 `PointsLedger(adjust)`；API Key admin 只展示 prefix 和 hash 摘要，不回显明文或完整 hash；订单、流水、注册赠点记录、调用记录继续只读并增强检索。T-402 已完成 MVP P0 验收并新增 `docs/mvp-acceptance.md`。T-403 已完成部署 / 运行文档，生产按 `deployment.md` 执行，并已补 settings 对生产静态目录、共享 cache、CSRF trusted origins、HTTPS cookie/proxy/HSTS 与注册限流的环境变量支持。T-601 已落地可用别名发现：`GET /api/v1/models` 用 API Key 鉴权返回公开别名目录，`/models` 用 session 展示只读「可用模型」页；两者均不解密 provider key，不输出底层 SKU、URL、key 或 `extra_body`。T-603 已完成 django-admin 字段级中文化并人工确认字段标签中文。T-604 已落地本地 prompt 敏感词过滤：`MODERATION_ENABLED=false` 默认 no-op，启用 `keyword` 后命中返回 `content_blocked`，并在下载 `image_url`、解析别名、计费、预扣点和上游调用前拦截。T-606 已落地公开首页：`GET /` 匿名 200、不跳登录；下载区读取 Windows 当前 `DownloadRelease`，优先 `external_url`，无当前版本显示「暂未发布」；现有 portal 页面已共用 `brand.css` 品牌 token。T-607/T-609 已落地公开版本检查接口：`GET /api/v1/client/releases/latest` 匿名 200，无需 API Key；支持 `windows`/`macos`/`linux`，返回当前版本 JSON 或 `release:null`，当前版本响应包含 `release.force_update`。真实标题上游生成已在线上跑通并验证扣点；图片生成真实耗时仍需补测。 -T-614 已落地异步生图任务化：提交接口预扣后返回 `task_id`，轮询接口返回 queued/running/succeeded/failed，worker 和 reaper 复用同一套成功确认 / 失败退点路径，旧同步接口继续兼容。 +T-614 已落地异步生图任务化：提交接口预扣后返回 `task_id`，轮询接口返回 queued/running/succeeded/failed，worker 和 reaper 复用同一套成功确认 / 失败退点路径，旧同步接口继续兼容。T-615 已落地旧同步 / 新异步提交遥测：两个入口都会写 `generation_route_usage` 结构化日志，便于按客户端版本、API Key 和 route_type 观察迁移进度；旧同步接口下线前必须继续保持响应兼容，并单独立下线任务。 ## 开始编码前检查 1. 读仓库级 `AGENTS.md` / `CLAUDE.md`。 2. 读 `docs/00-ai-start-here.md`。 3. 读 `docs/05-coding-rules.md`（尤其第 8 节资金安全）。 -4. 在 `docs/06-tasks.md` 领取第一个 `TODO` 且依赖均 `DONE` 的任务；当前为 T-615。 -5. 下一步优先处理 T-615，给旧同步生图接口补结构化遥测和弃用口径；真实支付回调到账闭环和客户端下载包发布继续作为后续业务事项排期。 +4. 在 `docs/06-tasks.md` 领取第一个 `TODO` 且依赖均 `DONE` 的任务；当前无明确编号任务。 +5. 下一步优先按生产需要处理真实支付回调到账闭环、客户端下载包发布，或基于 `generation_route_usage` 日志观察旧同步生图接口迁移情况后再立下线任务。 ## 维护规则 diff --git a/docs/deployment.md b/docs/deployment.md index 5f3b339..bcc96fe 100644 --- a/docs/deployment.md +++ b/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 配置中加入或调整： diff --git a/docs/project-brief.md b/docs/project-brief.md index 140f68e..d7d11ce 100644 --- a/docs/project-brief.md +++ b/docs/project-brief.md @@ -108,8 +108,8 @@ - Phase 5 已完成 T-401：运营后台可管理/检索用户、钱包、API Key（脱敏）、计费规则、汇率、充值订单、点数流水和调用记录；手工调点必须填写原因，并经计费层锁钱包、写 `adjust` 流水。 - Phase 5 已完成 T-402：MVP P0 验收通过，注册/充值/API Key/调用/余额/记录/后台/别名映射均有测试证据，详见 `mvp-acceptance.md`。 - Phase 5 已完成 T-403：已补部署 / 运行文档，明确宝塔/Nginx/Gunicorn、生产静态与媒体文件、共享缓存限流、图片同步超时、真实商户配置和上线检查；当前免邮箱验证，邮件服务仅作为后续密码找回/通知等邮件能力配置项，详见 `deployment.md`。 -- Phase 6 已完成 T-601 可用别名发现、T-602 后台表名/分组中文化、T-603 字段级中文化、T-604 中文敏感词本地过滤、T-605 免邮箱验证策略落地、T-606 公开首页 + 客户端下载入口、T-607 桌面端最新版本检查接口、T-608 新用户注册赠送 100 点试用点数与 T-609 桌面端版本强制更新标记；线上真实标题生成已恢复并验证扣点。 -- 下一步可继续补跑真实支付回调到账闭环、配置并发布客户端下载包，并按 T-615 观察旧同步生图接口用量与弃用条件。 +- Phase 6 已完成 T-601 可用别名发现、T-602 后台表名/分组中文化、T-603 字段级中文化、T-604 中文敏感词本地过滤、T-605 免邮箱验证策略落地、T-606 公开首页 + 客户端下载入口、T-607 桌面端最新版本检查接口、T-608 新用户注册赠送 100 点试用点数、T-609 桌面端版本强制更新标记、T-610 首页导入模板下载入口、T-611 用户端品牌名统一、T-612~T-615 生图异步化与旧同步接口遥测；线上真实标题生成已恢复并验证扣点。 +- 下一步可继续补跑真实支付回调到账闭环、配置并发布客户端下载包，并在生产日志中观察旧同步生图接口用量与弃用条件。 --- *更多细节：愿景 `01-vision.md` ｜ 需求与验收 `02-requirements.md` ｜ 架构 `04-architecture.md` ｜ 任务计划 `06-tasks.md`。* diff --git a/docs/project-onepager.md b/docs/project-onepager.md index 63b647b..3ee9249 100644 --- a/docs/project-onepager.md +++ b/docs/project-onepager.md @@ -40,7 +40,7 @@ ## 进度 -M1 骨架已完成；M2 已通过录制生成 smoke 验证 AI 调用链路；M3 计费、对外 API、充值闭环与上线前安全加固已完成到 T-306；M4 用户端已完成注册 / 登录、API Key 管理、个人中心 / 记录页、充值页和审核优化；M5 已完成 T-401 运营后台完善、T-402 MVP 完整验收与 T-403 部署 / 运行文档；M7 注册试用额度已完成，注册后经账本发放 100 点并留流水；M11 生图异步任务化已完成到 T-614，旧同步接口继续兼容。下一步是在 VPS 上按部署文档接真实支付回调闭环，并按 T-615 观察旧同步生图用量。里程碑：M1 骨架可跑 · M2 跑通生成 · M3 计费充值闭环 · M4 用户端可用 · M5 验收上线 · M7 试用额度安全落地 · M11 生图异步任务化。 +M1 骨架已完成；M2 已通过录制生成 smoke 验证 AI 调用链路；M3 计费、对外 API、充值闭环与上线前安全加固已完成到 T-306；M4 用户端已完成注册 / 登录、API Key 管理、个人中心 / 记录页、充值页和审核优化；M5 已完成 T-401 运营后台完善、T-402 MVP 完整验收与 T-403 部署 / 运行文档；M7 注册试用额度已完成，注册后经账本发放 100 点并留流水；M11 生图异步任务化已完成到 T-615，旧同步接口继续兼容并写结构化用量日志。下一步是在 VPS 上按部署文档接真实支付回调闭环、发布客户端，并观察旧同步生图用量。里程碑：M1 骨架可跑 · M2 跑通生成 · M3 计费充值闭环 · M4 用户端可用 · M5 验收上线 · M7 试用额度安全落地 · M11 生图异步任务化。 --- *详见 `project-brief.md`（完整介绍）。* diff --git a/progress.md b/progress.md index d8cdada..8dae9a9 100644 --- a/progress.md +++ b/progress.md @@ -1734,3 +1734,29 @@ - 本期不暴露 cancel 路由；后续如需取消，仅允许取消 queued 并单独拆任务。 - `image_base64` 不进 DB 原文，提交阶段解码为输入文件引用；异步结果不透传上游临时链接，只返回 cmhub 托管 URL。 - 下一步：领取 T-615，给旧同步生图接口和新异步路径补结构化遥测，并形成旧同步接口弃用条件。 + +## 2026-07-08 实施：T-615 旧同步生图接口用量遥测 + 弃用口径 + +- 状态：DONE。 +- 代码变更： + - 新增 `apps/api/telemetry.py`，集中构造并写入 `cmhub.api.generation_usage` 结构化日志事件 `generation_route_usage`。 + - `apps/api/views.py`：旧同步 `POST /api/v1/generate/image` 与新异步提交 `POST /api/v1/generate/image/tasks` 在参数错误、业务错误和成功返回前写遥测日志；旧同步成功响应和异步提交响应契约不变。 + - `apps/api/tests.py`：新增 3 条目标测试，覆盖旧同步成功日志、异步提交成功日志、异步余额不足错误日志，并断言日志只含白名单字段，不包含完整 API Key、prompt、`image_base64` 或 provider raw。 +- 文档变更： + - `docs/04-architecture.md`、`docs/api.md`、`docs/deployment.md`：同步遥测字段、`X-Client-Version` 请求头建议、日志查看方式和旧同步接口弃用条件。 + - `README.md`、`docs/00-ai-start-here.md`、`docs/current-state.md`、`docs/project-brief.md`、`docs/project-onepager.md`：同步 T-615 已完成和后续生产观察口径。 + - `docs/06-tasks.md`：T-615 标记为 DONE。 +- 验证： + - `py -3.12 -m py_compile apps\api\telemetry.py apps\api\views.py apps\api\tests.py`：通过。 + - `py -3.12 manage.py test apps.api.tests.GenerateApiTests.test_sync_image_usage_telemetry_logs_safe_client_version_and_key_identity apps.api.tests.GenerateApiTests.test_async_image_submit_usage_telemetry_logs_safe_success_event apps.api.tests.GenerateApiTests.test_async_image_submit_usage_telemetry_logs_error_code_without_sensitive_data --keepdb --noinput --verbosity 2`：通过，3 tests OK。 + - `py -3.12 manage.py check`：通过，0 issues。 + - `py -3.12 manage.py makemigrations --check --dry-run`：通过，No changes detected。 + - `py -3.12 manage.py test apps.api.tests.GenerateApiTests --keepdb --noinput --verbosity 2`：通过，31 tests OK。 + - `.\init.ps1`：通过（Python 3.12.3，依赖已满足，`manage.py check` 0 issues，打印启动命令）。 + - `git diff --check`：通过，仅 Windows CRLF 提示。 +- 测试环境现象： + - 测试期仍保留 allauth `account.EmailAddress` 条件唯一约束在 MySQL 上不可创建的既有 `models.W036` 警告。 +- 决策： + - T-615 第一版只做日志遥测，不新增 admin 报表或统计表；如后续需要报表，单独评估数据量、索引和保留周期。 + - 旧同步接口下线前必须继续保持成功响应兼容；待新版客户端默认异步、旧路调用归零或低于运营阈值一段时间后，再宣布 deprecated 并单独立下线任务。 +- 下一步：部署后观察 `generation_route_usage` 日志；继续处理真实支付回调到账闭环、客户端下载包发布等业务事项。