CRMEB 与上报中枢排障 Runbook

面向研发与运维：三条接入路径、落库位置、管理台入口与常见误判（IP / host）。无需登录即可阅读。

矩阵自测 ↔ 授权台

商城 oauth_platform_api_matrix_test.php 通过 cURL 出站打 oauth_base。updatewebinfo 默认不写入与 .version 一致的升级云凭证行；若系统设置开启「updatewebinfo → 升级云探测行」，则会在表中 upsert 固定 __updatewebinfo_probe__（disabled）便于自测对照。数据流、必接路径、后台仍空的两大类原因、工单清单见专页：/docs/matrix-oauth。

一、三条路径（择一或组合）

开放 API 注册：POST /api/v1/instances/register（HMAC 产品签名）→ 创建实例 + 授权 + 首条接入流水。
管理台预建：/admin/instances/create → 同上逻辑，操作者记入管理审计。
CRMEB updatewebinfo：/index.php/admin/server.upgrade_api/updatewebinfo（表单 POST）→ 按归一化 host 匹配已有实例写心跳；未匹配可走自动开通（系统设置）或写入 crmeb.updatewebinfo_unmatched 审计。

二、数据落库对照

事件	实例表	心跳流水	审计
register / 预建	新建行	`source=register`	管理操作或系统事件
API heartbeat	更新快照	`source=heartbeat`	—
CRMEB 匹配成功	更新快照 + `extra` 含 CRMEB 字段	同上，`extra.source=crmeb_updatewebinfo`	通常无未匹配记录
CRMEB 未匹配 / 冲突 / 自动开通	自动开通成功则新建实例	匹配或开通成功后写入	`crmeb.updatewebinfo_*`

三、排障决策（简版）

商城称「已上报」
  ├─ 先看 JSON 里 resolved_site_host / hint
  ├─ 中枢管理台「实例列表」host 是否同字面相等或可泛域名匹配？
  │    否 → 「审计」筛 crmeb.updatewebinfo_unmatched，看 body_ip / host / uid；点「预建实例」带 host
  │    是 → 「实例详情」时间线是否有 CRMEB 心跳？
  │           否 → 是否多实例冲突（审计 ambiguous）或心跳写入异常（查 PHP 日志）
  │           是 → 「接入流水」应有 reported_ip / version / vcode
  └─ IP 对不齐？
        核对 .env TRUSTED_PROXY_IPS 与 Nginx X-Real-IP / X-Forwarded-For
        「接入源 IP」≠ POST 字段 ip（上报 IP）

四、管理台入口速查

接入流水 — 已绑定实例的注册/心跳；列含 vcode、extra。
审计 — CRMEB 未匹配等；支持 uid 筛选（MySQL JSON）；每条可「查看」脱敏 JSON。
实例 — 快照与详情时间线；可按 extra.uid 筛选（MySQL）。
仪表盘 — 近 24h / 7 日 CRMEB 审计汇总。

五、与商城探测脚本

若商城仓库提供 public/oauth_license_probe.php，建议联调顺序与本文「三条路径」一致：先确认能打到中枢域名，再测 register 或预建，最后测 updatewebinfo 与返回的 matched_instance_id / received_uid。

六、三套「云端」能力与中枢边界（CRMEB 对照）

商城侧存在多套与升级/云相关的逻辑，协议与域名均不同；本中枢（授权台）的覆盖范围如下，避免误以为「已对接 oauth」即替代官方全部云端。

代号	典型基址 / 路径	本中枢
A · UpgradeService	/index.php/admin/server.upgrade_api/* 表单 POST，JSON：`code/msg/data`；含 `token`	已实现：与升级包登记、`/public/uploads/upgrade/*.zip`、审计一致。见开放 API 文档中 CRMEB 小节。
B · upgrade.crmeb.net	`/api/login`、`/api/upgrade/list`、`current_list`、`agreement`、`download`、`status`、`log`；签名 SHA256、`Access-Token: Bearer`	已实现（兼容层）：基址路径前缀 `/crmeb-upgrade`，例如 `https://您的域/crmeb-upgrade/api/login`。商城 `UpgradeServices` 常量改为此前缀即可。须在管理台维护「升级云凭证」与「CRMEB 升级包」；下载链指向本站 `/public/uploads/upgrade/`。
C · shop Open API	/api/open/* JSON：`status/msg/data`；头 `X-APP-ID`、`System-Version` 等	兼容层：`version_list`、`version_info`、`new_version_count`、`get_version_auth`、`upgrade_log` 与 A 共用升级包数据；可用环境变量 `CRMEB_OPEN_API_ENABLED`、`CRMEB_OPEN_API_APP_IDS` 关闭或限制 AppId。`upgrade_log` 写入审计 `crmeb.open.upgrade_log`。

商城侧将 app/services/system/UpgradeServices.php 中 http://upgrade.crmeb.net 整段基址替换为 https://您的授权域/crmeb-upgrade（无末尾斜杠，路径保持 /api/login 等相对部分不变）。与 /api/open/*、server.upgrade_api/* 为三套不同入口。

升级云凭证表：在签名校验通过的 /crmeb-upgrade/api/* 请求上，中枢按 app_id + host（归一化） 自动建档（多站点可共用同一 App Id/Key）；updatewebinfo 自测流量不会写入该表。可在系统设置关闭「自动开通」并改为「手动预置」。

七、中枢自检命令（研发 CI）

在部署目录 report-license 下执行（需已 composer install 与数据库）：

php think rl:crmeb-consistency — updatewebinfo 匹配后实例与心跳流水字段一致
php think rl:check-doc-links — 扫描视图/README 中 /docs/* 是否断裂
php tests/audit_sanitizer_test.php — 审计脱敏键名

仓库根亦可 php scripts/check_doc_links.php 调用上述 check-doc-links。

与《上报授权系统-需求与设计》及 design-system 下规划文档一致维护；第六节与 CRMEB 升级对接调研文档（A/B/C）对齐；矩阵自测专页见 /docs/matrix-oauth。