收敛后端依赖装配并完善异步追踪与鉴权

集中装配后台、External API 与编辑器受保护路由并保持既有方法和请求大小限制将项目元数据及 External/MCP 鉴权迁移为组合根装配的窄依赖并补齐替代依赖测试使用 RAII 修复请求取消和 panic 的在途计数并统一 HTTP 路由模板追踪补齐 LLM 普通与流式调用的安全异步追踪和本地 Provider 回归同步两处依赖锁文件、后端规范、运维指标合同及团队协作约定
2026-09-18 20:58:46 +08:00
parent ee33af7b75
commit 896fcecbc1
19 changed files with 3059 additions and 816 deletions
@@ -26,6 +26,8 @@
 - 修改 `/api/external/v1` 时，同批更新 `docs/openapi/genarrative-external-v1.openapi.json` 与契约测试。
 - 修改 SpacetimeDB schema 时遵守字段追加/default 约束，同步 migration、表目录、生成绑定，并运行 schema 检查；删除、改名、重排或改类型前先确认迁移计划。
 - 日志不递归输出完整配置、应用状态或 provider client；新增字段默认不进入安全摘要。
+- HTTP 横切能力集中在 Axum/Tower 中间件：正常与降级路由复用追踪层；指标与 trace 使用 `MatchedPath` 模板及固定兜底，不把请求 ID、实际资源 ID 或 query 放入指标标签。在途请求通过 RAII guard 覆盖 Future 取消与 panic unwind；请求执行和响应体存活分别计量，不能把 handler 耗时当作 SSE 全生命周期。
+- 业务依赖在组合根显式装配，Axum `FromRef` 只抽取可浅拷贝的窄能力。项目元数据与 External API 鉴权不持有完整 `AppState`，测试经相同接口注入替代依赖。集中鉴权仍保留方法级 fallback、公开入口、MCP 和 body limit 顺序；Provider span 跳过完整参数，不隐藏计费、重试、幂等或事务规则。
 - 中文文案、注释和文档保持 UTF-8，优先局部补丁，不擅自翻译成英文。

 ## 文档生命周期
@@ -47,6 +47,15 @@ SpacetimeDB 版本口径：当前 Rust crate `spacetimedb`、`spacetimedb-sdk`
 npm run check:server-rs-ddd
 ```

+## 依赖装配与横切能力
+
+- 启动入口负责构造共享依赖，业务入口通过 Axum `State` / `FromRef` 获取所需能力。项目元数据链路与 External API 鉴权使用窄状态；窄状态不得持有完整 `AppState`、通过 `Deref` 暴露完整配置，或提供 `root_state()` 逃逸。仅在需要替换或隔离测试的外部能力处抽取接口，生产实现仍复用现有 `spacetime-client` facade，不新建数据库访问通道。
+- 后台、External API 和编辑器路由按同一种身份策略聚合鉴权，公开登录、公开文档、公开精选读取及 MCP 保持独立边界。路由、HTTP 方法、404/405、请求大小限制、授权和错误响应合同保持不变；后台 member 的实时权限校验和资源 owner 校验继续由现有权威逻辑执行。
+- HTTP 观测使用统一 Tower 追踪层与 `MatchedPath` 模板；请求计数通过 RAII 覆盖取消与 unwind，响应体存活单独统计。具体指标合同见开发运维文档。
+- Provider 函数级追踪采用现有 tracing 能力，显式列出 provider、operation、model 等非秘密字段，跳过完整参数、配置、凭据和消息正文；异步 span 覆盖实际执行与等待，不能只记录 Future 创建。装饰与追踪保持原始成功值、错误、重试次数、流式回调和取消语义。
+- 扣费、退款、幂等、资源登记、重试判定与事务边界保持显式业务流程；不引入自动扫描 IOC 容器、通用 AOP 框架或跨外部副作用的隐式事务。
+- 验收覆盖：所有受保护路由的匿名拒绝及公开入口可访问；原有 404/405 和 body limit；窄依赖可独立构造和替换；Provider 成功/失败、异步追踪归属与脱敏；已有 API、计费和幂等回归。真实本地服务 smoke 必须记录所用数据库及依赖可用性，不能用单元测试代替运行时证据。
+
 ## `spacetime-client` mapper 组织

 `spacetime-client` 的 Cargo `lib.path` 指向 `src/active.rs`，现役 mapper 聚合入口是 `src/active/mapper.rs`；原旧 facade 和 mapper 已删除。
@@ -808,13 +808,15 @@ OpenTelemetry 现阶段默认开启 OTLP traces / metrics / logs，但本地日
 - 应用日志按进程查看：父 API 使用 `journalctl -u genarrative-api.service`，独立 BgFilter worker 使用 `journalctl -u genarrative-bgfilter-worker.service`；Nginx 日志仍写文件。日志等级继续用 `GENARRATIVE_API_LOG` / `RUST_LOG` 控制，例如 `info,tower_http=info,spacetime_client=info`。
 - debug exporter / Rider 转发都会同时接收 traces、metrics 和 logs。
 - api-server 会随 metrics 发送进程级指标：`process.memory.usage`、`process.memory.virtual`、`process.cpu.time`、`genarrative.process.cpu.usage_percent`、`process.thread.count`、`genarrative.process.memory.private`；Windows 额外发送 `process.windows.handle.count`，Linux 额外发送 `process.unix.file_descriptor.count`。这些指标只描述当前进程，不携带请求、用户或作品 label。
- HTTP 运行态补充发送 `genarrative.http.server.response_bodies.in_flight` 与 `genarrative.http.server.request_permits.available`，后者带低基数 `pool=default|gallery|detail|admin` label，用于区分业务 handler / 背压 permit 是否仍被占用；拼图广场热点缓存补充发送 `genarrative.puzzle_gallery.cache.*` 指标，记录 fresh hit、stale hit、未命中、后台刷新开始 / 失败、重建耗时和预序列化 data JSON 字节数。
+- HTTP 请求在途指标 `http.server.active_requests` 从进入观测中间件计数，到生成 `Response` 时结束；使用 RAII guard 保证正常返回、Future 被取消释放和 panic unwind 时都按原始 method / route 标签且仅递减一次。`http.server.request.duration` 采用同一执行区间，仅记录已生成响应的请求，不表示响应已发送到客户端，也不表示 SSE 已结束。响应体存活另由 `genarrative.http.server.response_bodies.in_flight` 统计；背压 permit 由 `genarrative.http.server.request_permits.available{pool=default|admin}` 统计。
+- 正常服务与 SpacetimeDB 不可用时的降级路由复用同一 HTTP `TraceLayer` 构造函数。请求上下文在追踪层外侧，错误归一化和响应头回写在追踪层内侧，保证提前拒绝和降级响应仍记录同一 request ID 与最终状态。
+- `platform-llm` 的普通与流式调用统一生成 `llm.request` 子 span，字段白名单为 `provider`、`operation`、`api_kind`、`model`，继承调用方当前 span；范围覆盖响应读取、流式回调和异步等待，取消释放 Future 时结束。完整 client/config、API Key、请求/响应正文不进入该 span；既有 Provider 错误和重试策略保持原样，不能用遥测包装吞掉失败或自动重放。
 - 外部 API 失败统一发送 OTLP 并落库。当前 VectorEngine 图片生成 / 编辑失败由 `platform-image` provider 输出结构化日志字段，字段包括 provider、endpoint、failure_stage、status、source、source_chain、source_chain_depth、timeout、retryable、latency_ms、prompt_chars、reference_image_count、实际 provider `image_model`、request_params 和 raw_excerpt；发生模型回退时另带 `fallback_from_model` / `fallback_to_model`。图片编辑请求参数日志还会带 reference_image_bytes_total，并在 request_params.referenceImages 中记录每个 multipart `image` part 的 fileName、mimeType 和 bytes，不记录 API key 或原始图片 bytes；`api-server` 再记录指标 `genarrative.external_api.failures{provider,failure_stage,status_class,retryable}`，并写入 `tracking_event`，`event_key = external_api_call_failure`、`module_key = external-api`、`scope_kind = module`、`scope_id = provider`。调用方能拿到身份上下文时，失败事件还会在行级 `user_id` / `owner_user_id` / `profile_id` 和 `metadata_json.userId` / `metadata_json.profileId` / `metadata_json.requestId` / `metadata_json.errorSource` 中记录触发者、草稿 / 作品作用域、请求标识和传输错误链。排障时先按 provider / failureStage / imageModel 聚合，再下钻 userId / profileId，最后结合 request 日志、errorSource 和上游响应 excerpt 判断是模型不可用、限流、超时、解析失败还是未返回图片。
 - OSS 平台适配器也输出结构化日志，覆盖 `sign_post_object`、`sign_get_object_url`、`head_object` 和 `put_object`。排查资产签名、上传或确认失败时，先按 `provider=aliyun-oss` 与 `operation` 过滤，再看 `object_key` / `key_prefix`、`status`、`status_class`、`error_kind`、`content_length`、`content_type` 和 `elapsed_ms`；角色动画逐帧额外按 `frame_index`、`operation=source_put|final_put|final_head`、`attempt/max_attempts`、`will_retry`、`oss_code` 和 `oss_request_id` 对齐同一对象的请求尝试。`请求 OSS 失败` 时，`timeout/connect/transport=true` 表示传输类失败，OSS PutObject 的 `status=400, oss_code=RequestTimeout, timeout=true`、`status=429` 或 `500–599` 表示暂时性失败，PUT 的 `status=400`、`oss_code` 为空且 `timeout=true` 或 `transport=true`（message 含「错误响应体读取失败」，即 400 错误体读取超时/断流）也会重试；除这两类例外外，其他 400、401/403/404、配置、URL 和签名错误是确定性失败，不会重试。最终帧 HEAD 失败只会重试 HEAD，不会重复 PUT。日志不得包含 AccessKey、policy、signature、Authorization header、完整 signed URL 或 OSS 错误响应体；`oss_request_id` 只用于关联 OSS 服务端排障。排查 generated 图片重复下载时，先确认前端输入是否为 `/generated-*` legacy path 或可归一化的 `https://*.oss-*.aliyuncs.com/generated-*`；正确链路应先调 `/api/assets/read-url`，再由浏览器请求 signed URL，且同一路径、同一 `refreshKey` 版本和未临近过期的 signed URL 应复用。新上传 generated 私有对象应带 `Cache-Control: public, max-age=31536000, immutable`；旧对象若只有 `ETag` / `Last-Modified`，浏览器会走 304 协商缓存而不是长期强缓存，可通过刷新 OSS 元数据或 CDN 配置补齐。
 - SpacetimeDB 观测分为两类：procedure / reducer 调用继续用 `genarrative.spacetime.procedure.*`，订阅本地 cache 读使用 `genarrative.spacetime.read.*`。`read=list_puzzle_gallery` 表示拼图广场当前从 `puzzle_gallery_card_view` 本地 cache 读取，不再每个 HTTP 请求调用 `list_puzzle_gallery` procedure。
 - 本地 Windows 直连压测的内存高水位要结合 K6 VU / 连接数解释。250 RPS 下过高 `PREALLOCATED_VUS` 可能让 300 个本地 Established 连接把 `api-server` private memory 瞬时推到 GB 级，且 `/healthz` 小响应也能复现；若压测结束后回落、`response_bodies.in_flight` 和背压 permit 未显示业务积压，应优先按连接 / 发送链路高水位处理，而不是判断为 SpacetimeDB 或 JSON 缓存泄漏。
 - Rider 的 Logs 面板只展示 log event 自身字段，不会自动展开父 span 的全部 attributes；请求完成日志会直接带 `request_id`、`http.request.method`、`http.route`、`url.scheme`、`url.path`、`http.response.status_code`、`status_class`、`latency_ms` 和 `slow_request`，完整链路继续到 Traces 面板按 trace/span 查看。
- 指标 label 只允许低基数字段：HTTP 使用 `method`、`route`、`status_class`，SpacetimeDB 调用使用 `procedure`、`status_class`；`request_id` 只进入 trace/log attribute，不进入 metric label。
+- 指标 label 只允许低基数字段：HTTP 使用 `http.request.method`、`http.route`、`status_class`，SpacetimeDB 调用使用 `procedure`、`status_class`；`request_id` 只进入 trace/log attribute，不进入 metric label。HTTP trace、完成日志与指标共用 Axum `MatchedPath` 路由模板，例如 `/api/editor/projects/{project_id}`；未匹配路由或无路由模板的降级请求只使用 `/api/*`、`/admin/api/*`、`other` 三种固定兜底，不把实际 ID 或 query 写入 route 标签。原来按 `/api/*` 聚合的监控查询应改为按路由模板汇总。

 常见外部服务变量：