feat: add privacy-safe server diagnostics

control-plane/README.md

@@ -97,7 +97,7 @@ Auto 一旦发生 AI fallback，任务会永久绑定原 AI 会话。每次解
 
 对微信来源，listener 在调用 `TaskService.ingestMessage()` 前执行上述严格信封解包，因此手工正文与 AgentBus 正文进入同一个业务 route resolver、任务级 mode snapshot 和 parser orchestrator；`Conversation` 只属于传输路由，不会再污染业务字段签名。
 
-AgentBus 全链路日志使用现有控制平面 stdout/Pino 输出，并统一带 `agentbus_event` 字段，可用 `rg 'agentbus_event'` 过滤。日志覆盖连接尝试、socket 生命周期、session.ready、每个收发帧、帧忽略原因、任务入队、解析队列、持久化回执出队、最终回复和发送错误。默认只记录消息正文的长度与摘要；本地排障可在受保护的环境文件中设置 `AGENTBUS_LOG_PAYLOADS=true`，记录最多 2,000 个字符的正文预览。渠道 key、WebSocket Token、Invoke Token 和 Authorization header 永不写入日志。
+AgentBus 全链路日志使用控制平面 stdout/Pino 输出，同时带 `diagnostic_event=agentbus.<agentbus_event>` 与原有 `agentbus_event`。日志覆盖连接尝试、socket 生命周期、session.ready、每个收发帧、帧忽略原因、任务入队、解析队列、持久化回执出队、最终回复和发送错误。名单附件另外记录元数据存在性、DNS 开始/通过、公网地址数量与 IP family、HTTPS 状态、重定向次数、接收字节数、大小/摘要校验和各阶段耗时；不记录 URL、hostname、IP、文件名、附件字节或名单值。开发/测试环境可临时设置 `AGENTBUS_LOG_PAYLOADS=true` 记录最多 2,000 个字符的正文预览，生产环境会拒绝以该值启动。渠道 key、WebSocket Token、Invoke Token 和 Authorization header 永不写入日志。
 
 监听器只使用每个渠道的 WebSocket key；文档中的 Invoke Token 仅用于另一服务通过 Function Call API 主动向 Bot 投递任务，本服务的监听链路不会使用它。
 
@@ -105,6 +105,24 @@ AgentBus 全链路日志使用现有控制平面 stdout/Pino 输出，并统一
 
 任务响应统一提供 `important_message`，作为“需返回/交互用户的重要消息”出口：`awaiting_user_input` 返回 Superagent 的 `reply`，错误优先返回 ERP 业务反馈、否则返回简短错误摘要，成功且有可验证 ERP 证据时按 [AgentBus 用户回复契约](../agent设计规范/agentbus-reply-contract.md) 生成业务回执。操作台保留完整结构供内部展示，AgentBus `task.result` 发往渠道时携带 `kind`、用户可读 `text` 和符合微信渠道适配器契约的 HTTPS URL-only 附件元数据；不发送 `content_base64` 或后台鉴权下载地址。外部文件投递要求生产附件使用 OSS 存储，且 URL 域名已加入适配器白名单。错误码、执行阶段、回执校验状态、隐藏 ID 和哈希不外发。`awaiting_confirmation` 不进入该栏。没有 `reply` 的 awaiting 结果会在解析阶段转为错误；没有可验证回执的 `completed` 执行会被归类为 `reconciliation_pending`，不会返回成功回执。
 
+## 服务端诊断日志
+
+控制面、迁移、数据保留、数据库异常和管理员命令都输出一行一个 JSON 的结构化日志。公共字段包括 `time`、`level`、`service`、`environment`、`deployment_revision`、`pid`、`hostname`、`diagnostic_event` 和 `diagnostic_stage`；链路字段按事件提供 `request_id`、`task_id`、`inbound_frame_id`、`conversation_id`、`channel_id`、状态、结果与 `duration_ms`。覆盖范围包括服务启动/关闭、HTTP 开始/完成/拒绝、任务状态事件、数据库 audit event、解析队列和 Worker、AgentBus、附件入口、OSS 清理、数据库连接/回滚以及未捕获进程错误。
+
+未知异常只记录受限 `error_code`、`error_name`、稳定的 `error_fingerprint`、errno/syscall 和最多 12 个清理后的代码栈帧；不把第三方异常原文复制进日志。请求 query/body、Cookie、Authorization、CSRF、密码、API key、Token、附件 URL/字节和业务原文不进入生产日志。每个 HTTP 响应返回同一个 `x-request-id`，可直接用于跨开始、错误和完成事件检索。部署时应把 `DEPLOYMENT_REVISION` 设置为当前提交或发布编号，避免不同镜像的日志混淆。
+
+Docker Compose 使用 `json-file`，默认每个容器保留 10 个、每个 20 MB 的轮转文件；可在 `.env.production` 用 `LOG_MAX_SIZE` 和 `LOG_MAX_FILES` 调整。服务端只读排障命令会显示容器状态、`/health/ready` 和最近日志，不读取或打印环境文件：
+
+```bash
+sh infra/diagnose-server.sh
+sh infra/diagnose-server.sh --since 2h --match TASK-20260830071915-g7INIT0
+sh infra/diagnose-server.sh --since 2h --match roster_attachment_metadata_missing
+sh infra/diagnose-server.sh --since 30m --match request:example:12345678
+sh infra/diagnose-server.sh --since 30m --all-services
+```
+
+`--match` 是字面量过滤，可使用 request/task/frame/conversation/channel ID、`diagnostic_event` 或 `error_code`。脚本默认最多读取 1,000 行控制面日志，`--tail` 上限为 50,000，且不在仓库生成日志文件。
+
 ## 本地命令
 
 本地命令会自动读取项目根目录 `.env`，不需要先手动 `export` 环境变量。首次部署或换环境时，只需替换该文件；生产 Docker Compose 使用 `.env.production`。
@@ -125,11 +143,12 @@ npm run dev
 
 ## 生产部署
 
-1. 复制 `.env.production.example` 为部署机受保护的 `.env.production`，填入 PostgreSQL URL、`DATABASE_SCHEMA`、字段加密密钥、外部解析 Key 和 OSS 凭据。生产数据库可使用现有 PostgreSQL 实例中的新 Schema；迁移程序会创建 Schema，不会触碰其他 Schema 的测试表。
+1. 复制 `.env.production.example` 为部署机受保护的 `.env.production`，填入 `DEPLOYMENT_REVISION`、PostgreSQL URL、`DATABASE_SCHEMA`、字段加密密钥、外部解析 Key 和 OSS 凭据，并确认 `AGENTBUS_LOG_PAYLOADS=false`。生产数据库可使用现有 PostgreSQL 实例中的新 Schema；迁移程序会创建 Schema，不会触碰其他 Schema 的测试表。
 2. 在正式数据库上线前执行并验证备份：`infra/backup-postgres.sh`。
 3. 使用 `docker compose --env-file .env.production up -d --build` 启动；Compose 会先执行数据库迁移，再启动控制平面。Compose 中的本地 PostgreSQL 仅用于 `--profile local`，生产 `DATABASE_URL` 指向受保护的远程数据库。
 4. 首次启动后在容器内通过 `docker compose exec -e ADMIN_USERNAME=admin -e ADMIN_PASSWORD='replace-with-12-plus-chars' control-plane node .build/control-plane/src/admin-cli.js bootstrap` 创建管理员；不要把密码写入镜像或 Git。
 5. 配置 `infra/Caddyfile` 中的正式域名和 HTTPS，然后在 Chrome 插件中加载对应生产业务页面。
+6. 启动后运行 `sh infra/diagnose-server.sh --since 10m`，确认容器、readiness、`service.listening`、AgentBus session 与当前 `deployment_revision`。
 
 正式环境没有独立 staging。上线前必须完成离线测试、迁移预检查和迁移前备份；恢复检查使用 `infra/restore-check.sh` 指向一次性恢复数据库。