IM Webhook Bridge 使用文档（当前系统版）

多租户 IM 消息桥接系统 — 配置与操作指南。本页与 v2.1.x 实现对齐：RBAC v2、通知中心、运营策略与队列、在线客服（WebSocket + /agent/ 工作台）、租户侧 AI 与知识库、管理端「系统排障助手」（与客服 AI 隔离）、会话质检与 KPI 报表、企微语音 ASR 等。环境变量 AI_ENABLED=false 时仍会执行 initAI(app) 注册 AI 管理路由；该变量在 app.js 中目前仅区分启动日志文案，未在 ai-intercept 等路径做统一短路——实际是否自动回复以 ai_switches 及租户配置为准。反向代理后建议配合 TRUST_PROXY=1。顶部导航中 Agent Beta 对应超级管理员「AI 中心」早期测试入口；客服工作台 打开 /agent/。

1. 系统概述

IM Webhook Bridge 是一个多租户的 IM 消息桥接系统，支持企业微信和飞书两大平台。系统提供以下核心能力：

• H5 操作面板: 在企业 IM 内嵌的 H5 页面中展示自定义菜单（按钮/表单），用户操作后自动向指定 Webhook URL 发送请求
• 消息推送 API: 外部系统（如影刀 RPA）通过 HTTP API 向 IM 用户推送消息
• 消息回调转发: 接收 IM 平台的消息事件并转发到指定 Webhook
• Web / APP 在线客服: WebSocket 实时会话、可选租户用户登录、AI 自动回复与转人工、客服工作台 /agent/
• 管理端「系统排障助手」: 面向内部运维/管理员的独立 AI 对话（与租户客服 AI 数据与代码路径隔离），结合本地知识索引、代码片段命中与高分历史样本，输出可执行排障建议；支持导出报告与准确率反馈自学习
• 运营与可观测: 运营策略、通知中心（邮件/短信队列）、KPI 看板、会话质检（规则 + LLM、报表与低分告警）等

系统支持两种应用模式：

• 自建应用模式: 客户在自己的企微/飞书后台创建应用，提供 CorpID、AgentId、Secret 等凭证
• 代开发/ISV 模式: 服务商创建应用模板，客户通过扫码授权即可使用，无需客户自行创建应用

2. 部署与启动

环境要求

• Node.js >= 14
• 公网可访问的域名和 HTTPS 证书（IM 平台回调需要 HTTPS）

安装与启动

cd im-bridge
npm install
node server.js

服务默认监听 3001 端口。建议使用 Nginx 反向代理配置 HTTPS。

持久化配置目录（避免升级覆盖）

租户、套件、管理员密码等主配置由 lib/config-store.js 读写；企微/飞书 suite_ticket 由 lib/suite-store.js 持久化。当前默认路径为应用目录的上一级下的独立目录（与代码分离，同步代码时不会覆盖）：

• Linux 生产常见路径：/app/im-bridge-data/config.json、/app/im-bridge-data/.suite-tickets.json
• 本地开发（与仓库并列）：…/im-bridge-data/config.json 等
• 可通过环境变量 IM_BRIDGE_DATA_DIR 指定绝对路径，覆盖默认目录
• 若新目录尚无文件，启动时会自动从旧路径（应用根目录下的 config.json / .suite-tickets.json）复制一份，便于迁移
• 保存配置前会在数据目录下 config-backups/ 保留最近若干份快照，便于回滚

推荐使用项目内 scripts/safe-deploy.sh 做发布：默认先备份上述关键文件，再用 rsync 同步代码并排除 node_modules、data/ 等，降低误覆盖风险。

Nginx 配置示例

参考项目中的 aiops-nginx.conf 文件进行配置，确保：

• 启用 HTTPS（443 端口）
• 反向代理到 localhost:3001
• WebSocket 支持（如需要）

健康探针（负载均衡 / 容器编排 / 监控）

• GET /health/live：仅表示 Node 进程已启动并响应 HTTP，不访问 MongoDB；适合作为负载均衡器或 K8s livenessProbe。
• GET /health/ready：对 MongoDB 执行 ping；若配置了 REDIS_URL 则再对 Redis PING。任一依赖不可用时返回 HTTP 503，JSON 形如 {"ok":false,"reason":"..."}；适合 readinessProbe 与发布编排。

管理后台顶栏「存活」「就绪」打开的是 /admin/health-live.html、/admin/health-ready.html（页内 fetch 调用 JSON 接口），避免在浏览器地址栏直接打开 /health/ready 时因 HTTP 503 被浏览器当成「整页错误」而看不到 JSON 中的 reason。自动化探活仍请直接请求 GET /health/live、GET /health/ready。所有 HTTP 响应（含错误）会带上 X-Request-Id；客户端也可传入合法的 X-Request-Id 或 X-Trace-Id（字母数字与 ._@-，最长 128 字符）以贯通日志与审计。

运维相关环境变量（可选）

• JSON_BODY_LIMIT：express.json / urlencoded 的 body 上限，默认 2mb；大文件上传走 multipart 路由，不受此项限制。
• BUSINESS_EVENTS_TTL_DAYS：若设置正整数，为 MongoDB 集合 business_events 启用按创建时间的 TTL（天）；未设置则长期保留。
• STRUCTURED_ACCESS_LOG=1：访问日志改为单行 JSON，并包含 requestId 字段。
• REDIS_URL：若设置，GET /health/ready 会在 MongoDB ping 通过后对 Redis 执行 PING；失败则整体验证返回 503。
• METRICS_ENABLED=1：开启 GET /metrics（Prometheus 文本格式：uptime、Node 堆/外部内存、HTTP 响应计数按方法与 2xx/4xx/5xx；/health/* 与 /metrics 本身不计入，便于对接 Prometheus + Grafana）。
• TRUST_PROXY=1：部署在 Nginx/负载均衡后时建议开启，以便限流、日志使用 X-Forwarded-For 中的客户端 IP（与 Express trust proxy 一致）。
• RATE_LIMIT_ENABLED=0：关闭公网接口限流（仅建议本地调试）。默认开启；管理端/客服台登录已有独立防刷逻辑。
• 限流阈值（每分钟，可按需调大）：RATE_LIMIT_PUSH_PER_IP_SLUG_PER_MIN（默认 120，推送 API）、RATE_LIMIT_CHANNEL_MESSAGE_PER_IP_SLUG_PER_MIN（默认 60，Web 渠道 REST 发消息）、RATE_LIMIT_TENANT_LOGIN_PER_USER_PER_MIN（默认 5，租户用户登录，按 IP+slug+用户名）、RATE_LIMIT_TENANT_PASSWORD_PER_IP_PER_MIN（默认 30，改密）、RATE_LIMIT_OPS_CALLBACK_PER_IP_PER_MIN（默认 120，/api/ops/callback）。超限返回 HTTP 429 与 Retry-After。未对企微/飞书 /api/callback、/api/suite 限流，避免误伤平台回调。
• 语音转文字（企微 AMR）：运行时读取 TENCENT_SECRET_ID、TENCENT_SECRET_KEY，可选 TENCENT_ASR_REGION（默认 ap-shanghai），见 lib/tencent-asr.js。仓库根目录 .env.example 目前以阿里云语音/OSS 示例为主，部署时请按实际选用的 ASR/OSS 提供方与代码路径核对，勿仅凭示例文件名假设已全部覆盖。
• 调度循环间隔（单位毫秒，代码侧最小 1000）：OPS_LOOP_INTERVAL_MS（默认 5000，运营引擎）、KPI_ALERT_LOOP_INTERVAL_MS（默认 60000）、KPI_DAILY_LOOP_INTERVAL_MS（默认 300000）、NOTIFICATION_LOOP_INTERVAL_MS（默认 5000，通知中心 worker）、KB_URL_REFRESH_LOOP_INTERVAL_MS（默认 60000，知识库 URL 刷新）、QC_LOOP_INTERVAL_MS（默认 60000，质检循环）。定义见 server.js。

3. 首次登录与密码设置

1. 浏览器访问 https://你的域名/admin/
2. 首次打开时显示 "首次使用，请设置管理密码" 提示
3. 输入管理密码（不少于4位字符），点击 "设置密码并登录"
4. 密码使用 bcrypt 加密存储，后续登录需输入相同密码

注意: 密码设置后无法通过界面修改。如需重置，需手动编辑持久化目录中的 config.json（默认 im-bridge-data/config.json），删除其中的 adminPassword 字段。

4. 自建应用模式配置

适用场景：客户在自己的企微/飞书后台已有应用，或只需为单个企业配置。

步骤 1: 创建租户

1. 登录管理后台，点击左侧侧边栏的 "+" 按钮
2. 填写以下信息：
   • 租户名称: 客户公司名或项目名
   • URL标识 (slug): 可留空自动生成随机标识，也可手动填写（仅限小写字母/数字/连字符）
3. 确认"启用"开关打开，点击 "保存"

步骤 2: 添加渠道并配置凭证

1. 进入租户详情 → 渠道管理 Tab → 点击 "+ 添加渠道"
2. 选择渠道类型（企业微信/飞书），应用模式选 "自建应用"
3. 填写平台凭证：
   • 企业微信: 企业ID (CorpID)、应用AgentId、应用Secret
   • 飞书: App ID、App Secret
4. 点击 "保存凭证"

步骤 2: 配置企微后台（企业微信自建应用）

1. 登录企微管理后台 > 应用管理 > 找到对应应用
2. 在"网页授权及JS-SDK"中设置可信域名为你的系统域名
3. 在"企业可信IP"中添加你服务器的公网 IP
4. 在应用主页设置 H5 页面地址（可选，后续在页面管理中获取具体链接）

5. 代开发/ISV 模式配置

适用场景：作为服务商，一个应用模板供多个客户企业授权使用。

前置条件

• 已在企业微信服务商后台注册为服务商
• 已创建代开发应用模板（模板ID以 dk 开头）并上线发布
• 或已创建第三方应用（套件ID以 ww 开头）

步骤 1: 配置全局服务商凭证

重要: 此步骤必须在创建 ISV 租户之前完成！

1. 登录管理后台，点击左侧侧边栏的 齿轮图标 (全局配置)
2. 在"企业微信 服务商配置"卡片中填写：
   • Suite ID: 代开发模板ID（dk开头）或第三方应用套件ID（ww开头）
   • Suite Secret: 应用的 Secret（注意：不是 ProviderSecret）
   • Suite Token: 自定义字符串，后续需填入服务商后台
   • Suite EncodingAESKey: 43位字符，自定义或随机生成
   • 服务商 CorpID (代开发必填): 服务商企业的 CorpID
   • ProviderSecret (代开发必填): 在服务商后台 > 服务商信息中获取
3. 点击 "保存全局配置"

步骤 2: 在服务商后台配置回调 URL

重要: 必须先完成步骤 1 保存配置后，再执行此步骤！

1. 登录企业微信服务商后台
2. 进入 应用管理 > 找到代开发应用模板
3. 在 "数据回调URL" 处填入: https://你的域名/api/suite/wechat/callback
4. 填入与步骤 1 相同的 Token 和 EncodingAESKey
5. 点击"保存"进行验证

步骤 3: 等待 suite_ticket 推送

1. 回调 URL 验证通过后，企微服务器会每 10 分钟 推送一次 suite_ticket
2. 在全局配置页面中观察状态徽章
3. 状态变为绿色 "Ticket 已就绪" 后，即可进行后续操作

注意: 首次配置可能需要等待最多 10 分钟。suite_ticket 已做磁盘持久化，服务重启后会自动恢复。

步骤 4: 创建 ISV 租户

1. 点击左侧 "+" 按钮创建新租户
2. 进入租户详情 → 渠道管理 Tab → 添加企微渠道
3. 应用模式选择 "代开发/ISV"（凭证由授权回调自动填入）

6. 客户授权流程

前置条件: 已完成第 5 节的步骤 1-4，且 Ticket 状态为"已就绪"

步骤 1: 生成授权链接

1. 在管理后台中选中 ISV 租户
2. 进入 渠道管理 Tab，找到企微渠道卡片（需已选择 ISV 模式）
3. 点击渠道卡片中的 "生成授权链接" 按钮
4. 点击 "复制" 按钮复制链接

步骤 2: 客户扫码授权

1. 将授权链接发送给客户的企业微信管理员
2. 客户管理员在 企业微信 中打开此链接（或电脑端扫码）
3. 客户确认授权信息后，点击 "同意授权"
4. 授权完成后系统自动：接收回调 > 交换永久授权码 > 填充凭证 > 状态变为"已授权"

步骤 3: 验证授权结果

1. 刷新管理后台页面
2. 查看租户详情：ISV 授权状态显示 "已授权"，凭证已自动填充
3. 如果授权状态未更新，检查服务器日志中 [suite-callback] 相关错误

7. 页面与菜单管理

创建 H5 页面

1. 选中目标租户，切换到 "页面管理" 标签页
2. 点击 "+ 新建页面"
3. 填写页面名称、URL标识 (slug)、图标、是否启用
4. 保存后，页面卡片上会显示 H5 链接: https://域名/t/{租户slug}/h5/{页面slug}
5. 将此链接配置到企微应用的"工作台主页"或"自定义菜单"中

创建菜单

1. 展开目标页面卡片，点击 "+ 新建菜单"
2. 填写菜单信息：
   • 菜单名称: H5 页面中显示的按钮名称
   • 类型: 直接触发（点击即执行）/ 表单提交（需填写表单）
   • Webhook URL: 用户操作后系统 POST 请求的目标地址
   • 表单字段 (表单模式): text/textarea/number/date/select/checkbox
   • 固定参数: JSON 格式，每次请求自动附带
   • 自定义请求头: JSON 格式，附加到 HTTP 头

8. 推送消息 API

用于让外部系统（如影刀 RPA）向 IM 用户推送消息。

步骤 1: 生成 API Key

1. 选中租户 → 渠道管理 Tab
2. 找到目标 IM 渠道卡片（企微/飞书）
3. 在卡片底部的 "推送消息 API" 区域，点击 "生成 API Key"

注意: 推送 API Key 是渠道级别的，每个 IM 渠道独立管理自己的 Key。Web/APP 渠道不支持推送 API。

步骤 2: 调用推送 API

完整 API (推荐):

curl -X POST 'https://域名/api/push/{slug}/message' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -d '{
    "toUser": "用户ID",
    "msgType": "text",
    "content": {"text": "你好，这是一条推送消息"}
  }'

简易 Webhook (适合不支持自定义 Header 的场景):

curl -X POST 'https://域名/api/push/{slug}/webhook?key=YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"content": "消息内容"}'

简易 Webhook 默认发送给 @all（全员）

消息类型

toUser 格式: 单个用户 "userId123"，多个用户 ["userId1","userId2"]，全员 "@all"

9. 接收消息回调

用于接收企微/飞书中用户发送的消息，并转发到你的服务。回调配置位于 IM 渠道卡片内。

自建应用模式

1. 选中租户 → 渠道管理 Tab → 找到目标 IM 渠道卡片（企微/飞书）
2. 在卡片底部的 "接收消息回调配置" 区域：
   • 复制 回调 URL: https://域名/api/callback/{slug}
   • 设置 Token 和 EncodingAESKey（需与企微/飞书后台一致）
   • 设置 消息转发 Webhook URL（可选，用于将消息转发到你的服务）
3. 点击 "保存回调配置"
4. 然后到企微管理后台 > 应用 > "接收消息服务器配置" 中填入相同的 URL、Token 和 AESKey 并验证

重要: 必须先在 IM Bridge 中保存配置，再到企微后台验证。回调配置是渠道级别的，每个 IM 渠道独立管理。

ISV/代开发模式

ISV/代开发模式下，消息通过套件回调接收（suite-callback.js），无需在渠道卡片中配置回调地址。渠道卡片中会显示提示信息："ISV/代开发模式下，消息通过套件回调接收，无需配置此处的回调地址"。

10. Webhook 请求格式

用户在 H5 页面触发菜单操作时，系统向 Webhook URL 发送 POST 请求：

{
  "source": "im-bridge",
  "tenant": { "id": "租户ID", "name": "租户名称", "slug": "slug", "platform": "wechat" },
  "page":   { "id": "页面ID", "name": "页面名称", "slug": "页面slug" },
  "user":   { "userId": "企微用户ID", "name": "用户姓名", "department": "部门" },
  "menu":   { "id": "菜单ID", "name": "菜单名称", "type": "direct/form" },
  "data":   { "固定参数key": "value", "表单字段key": "用户填写的值" },
  "timestamp": "2024-01-01T00:00:00.000Z"
}

data 字段包含菜单固定参数和用户表单数据的合并结果。

11. 常见问题排查

12. 系统排障助手（内部 AI · 机制）

系统排障助手是面向内部人员（管理员、运营、客服主管等）的独立 AI 能力：帮助快速理解「配置、租户、渠道、工作台、权限」等问题，并给出可在管理后台内操作的排查步骤。它与租户侧在线客服 AI（拦截用户消息、知识库 RAG、会话）在代码路径、Mongo 集合、检索索引与反馈数据上完全隔离，避免与终端用户对话数据混用。

12.1 从哪里进入、和哪些功能并列

• 管理后台顶部右侧链接「排障助手」：打开排障对话与数据分析区；也可通过地址 /admin/?tab=troubleshoot 直达。
• 与「客服工作台」（/agent/ 新标签页）不同：后者是接待终端用户的坐席界面；排障助手仅服务内部排障与协作。
• 与「Agent Beta」不同：后者（超级管理员）进入的是AI 中心（系统级 LLM/人设等配置与测试），不是客服工作台。
• 客服台侧若集成排障入口，调用的是同一套 /api/agent/... 排障 API，数据仍写入排障专用集合，不会写入租户 ai_conversations 客服会话。

12.2 与「在线客服 AI」对照

12.3 交互分类：寒暄 vs 排障咨询

服务端在调用大模型前会做轻量规则分类（无额外 LLM）：

• 寒暄 / 闲聊（smalltalk）：如「你好」「谢谢」「在吗」及带语气词的变体（「你好啊」等）。返回一句固定风格的友好短回复，不走结构化排障 JSON，不展示「反馈准确率」评分卡片，也不做无意义的代码库全文检索。
• 排障咨询（troubleshooting）：包含异常、配置、现象描述或帮助类关键词，或附带截图等附件时，按排障处理：拉取上下文与检索结果，生成结构化 JSON（根因、步骤、风险等），前端压缩为一段可读说明，并展示导出本次报告与准确率反馈（0/50/75/100）。
• 排障路径下，即使用户表述与索引措辞不完全一致，也会尽量允许反馈打分，便于持续收集真实使用体验（具体策略以当前 lib/ops-assistant/service.js 为准）。

12.4 请求处理流程（从提问到回复）

12.5 检索与证据（回答依据）

• 系统知识库（system-kb.js）：从当前部署仓库构建的索引，匹配运维文档、说明类内容。
• 实时代码命中：在本地代码树中做片段级检索，用于对齐真实实现（如路由、配置项名称），减少「臆测不存在的配置项」。
• 高分历史样本：仅使用历史反馈为 75% / 100% 的问答对作为参考；低分记录不参与检索强化。
• 发布版本窗口：样本附带发布版本号；学习检索时只采纳当前发布版本与上一版本内的样本，避免过期实现误导新版本。

12.6 结构化输出、导出与反馈

• 排障回复在模型侧约定为固定字段的 JSON（如根因列表、步骤、风险、置信度等），经校验后与规则兜底合并，再映射为前端「一段话 + 导出」。
• 导出本次报告：可生成 Markdown 报告，便于粘贴到工单或内部群。
• 反馈准确率：0/50/75/100 四档单选，每条消息仅可提交一次；用于后续自学习与质量分析。

12.7 评分与自学习规则

• 仅 75 / 100 分纳入「可学习」样本池，参与后续相似问题检索。
• 100 分样本在检索排序上优先于 75 分。
• 0 / 50 分保留审计与学习分析价值，但不作为正向范例注入提示词。

12.8 版本窗口（示意图）

版本号来自管理端前端配置的 APP_VERSION（与排障助手展示版本一致）。

12.9 数据集合与代码路径

13. 配置项索引（通用说明 & 影响面）

本节按真实配置来源归纳高信号项，便于审计与排障。未列出的字段不代表不存在（可能为低频或仅内部使用）；若需全量字段语义，以代码读取路径为准。涉及历史数据形状变更时，须按仓库数据兼容规则走迁移脚本、双读等流程，本文不给出破坏性操作指引。

13.1 config.json（lib/config-store.js）

默认位于数据目录（见上文「持久化配置目录」），可通过 IM_BRIDGE_DATA_DIR 重定向。HTTP API 前缀以 app.js 挂载为准：管理端 /api/admin/*。

13.2 环境变量

下列变量由 app.js、server.js 或业务库直接读取。.env.example 仅覆盖部分场景（如阿里云语音），运行实例请以实际 .env 与代码为准。

13.3 MongoDB 文档型配置（代码显式读取的集合）

以下为当前代码路径中直接 getCollection(...) 读取、且承担配置/开关职责的集合（不含纯业务流水表全枚举）。

会话集合并存说明：统一客服会话存储等路径还使用集合 conversations（见 lib/conversation-store.js），与 ai_conversations 职责不同；若排障时发现「列表/队列 ID 对不上」，需分别核对两条链路的读写集合，任何合并或迁移须在专项迁移与双读方案下进行。

13.4 管理后台界面与落库/接口（简述）

13.5 界面存在但 API 未实现或未消费 runtime 的配置（核实截至当前仓库）

下列项在 AI 中心前端 public/admin/ai/ai-admin.js 中有请求，但 ai/routes/ai-admin.js 未注册对应路由，面板会收到 404 或非预期响应，属「界面预留 / 待接通」：

• 租户统计看板：GET /api/admin/ai/tenant/:tenantId/stats/overview、.../stats/trend、.../stats/hot-questions
• 模型用量与预算：/api/admin/ai/model-usage/*（含 call-sites、tenant/.../model-usage/stats、budget、daily、test-connection 等）
• 评价统计：GET /api/admin/ai/tenant/:tenantId/feedback/stats

已落库但拦截链未使用：ai_tenant_config.businessHours 由 PUT /api/admin/ai/tenant/:tenantId/config 写入并在 GET 中返回，但 ai/middleware/ai-intercept.js 未引用该字段——非工作时间话术不会在当前 AI 拦截路径自动生效，除非后续版本在拦截器中接入。

13.6 延伸阅读（仓库内）

架构细化、数据流与探活约定见本页下文「系统架构」各节及 docs/ARCHITECTURE.md（若部署包含该文件）。

附录: 代开发 ISV 配置完整流程

按照以下顺序操作（顺序很重要）：

阶段一: 服务商准备（一次性）

阶段二: 为客户创建租户和渠道

阶段三: 客户授权

阶段四: 业务配置

注意: ISV 模式下消息通过套件回调（suite-callback.js）自动接收，渠道卡片中无需配置接收消息回调。推送 API Key 在渠道卡片内独立管理。

系统架构

可视化系统架构图 — 由 Mermaid 实时渲染

A1. 系统总览

展示从客户端（企微/飞书/Web/APP）经接入层、AI处理层、回复路由层到人工客服系统和管理后台的完整数据流，包含租户用户认证体系：

A2. 多渠道消息流转时序

展示一条用户消息从发送到 AI 回复（或转人工）的完整处理链路：

A3. 目录结构与模块职责

各目录和模块的分层关系：

A4. 数据架构 (ER图)

核心数据实体及其关系（含租户用户体系和渠道级配置）：

A5. 客服在线检测与心跳机制

客服在线状态的完整生命周期，包括心跳超时自动离线（1分钟）：

A6. 平台适配器模式

所有平台实现统一的 sendMessage() 接口，新增平台只需注册新适配器：

A7. 部署架构

生产环境的物理部署拓扑：

A8. 前端页面结构

A9. 多渠道配置说明

每个租户支持同时接入多个通讯渠道。IM 渠道（企微/飞书）独立管理凭证、回调配置和推送 API Key；Web/APP 渠道管理聊天页面配置。

渠道类型与功能矩阵

链接防枚举 (随机 Slug)

新建租户时，若不手动指定 slug，系统自动生成 8 位随机 hex（如 a3f7b1e2），使每个租户的聊天链接无法被推测。已有租户的自定义 slug 保持不变。

租户用户认证体系

每个租户可配置独立的用户账户体系（tenant-user-model.js），用于 Web/APP 渠道的登录认证：

• 用户账户存储在 MongoDB，密码使用 bcrypt(10) 加密
• 支持单个创建、批量生成（前缀+数量）、CSV 导入
• 可选首次登录强制修改密码
• 当租户有用户账户时，Web 聊天页自动切换为登录模式；无用户时保持匿名模式
• 登录后通过 session token 进行 WebSocket 认证

主渠道与向后兼容

标记为"主渠道"的 IM 渠道，其 credentials、mode、callbackToken、apiKey 会自动同步到租户顶层字段。这保证了 callback.js、push-api.js、suite-callback.js 等仍通过 tenant.credentials 读取凭证的代码能正常工作。

配置持久化路径

多租户主配置默认写入 外置数据目录下的 config.json（见上文「持久化配置目录」），不再依赖应用根目录内的同名文件，以便升级同步代码时不被覆盖。

自动迁移机制

系统启动时 config-store.js 的 backfillDefaults() 自动执行：

• 旧格式租户补齐 channels[] 数组
• 租户顶层 callbackToken/callbackAESKey/apiKey 迁移到主 IM 渠道
• 主渠道数据反向同步到租户顶层（向后兼容）

渠道管理操作

在管理后台 → 租户详情 → 渠道管理 Tab 中可进行：

• 添加新渠道（企微/飞书/Web/APP）
• IM 渠道：切换应用模式（自建/ISV）、配置凭证、回调、推送 API Key
• Web/APP 渠道：配置聊天标题、欢迎消息、获取聊天页链接
• 设置主渠道、启用/停用、删除渠道
• ISV 模式下直接生成授权链接（无需回到基本信息页）

A10. 租户用户认证体系

Web/APP 渠道支持可选的租户用户认证，认证流程如下：

管理端操作

在管理后台 → 租户详情 → 用户管理 Tab 中：

• 单个创建用户（用户名/密码/显示名/启用/强制改密）
• 批量生成用户（前缀 + 起始编号 + 数量，系统生成随机密码）
• CSV 导入用户
• 重置密码、启用/停用、删除用户

A11. 健康探针、请求 ID 与业务事件

与「可观测性、排障、发布」相关的 HTTP 行为与数据落库；与业务功能章节正交。

探针与关联头

请求级 X-Request-Id / X-Trace-Id 与 AI、回调、推送等路径对齐。

业务事件查询

GET /api/admin/business-events（参数 tenantId、type、traceId、source、startDate、endDate、page、limit）或页面 /admin/business-events.html。

• 超级管理员：tenantId 可选；省略则查全部租户。
• 普通管理员：必须传 tenantId，且仅能查询自己有权限的租户；否则返回 400 / 403。

典型 type：push_message_sent、ai_message_received、ai_reply_sent、ai_transfer_human、ai_llm_failed、callback_channel_inbound、callback_channel_reject、callback_webhook_forward_failed、suite_wechat_inbound、suite_wechat_post_error、suite_feishu_callback_error 等（以代码为准）。

进程信号

SIGTERM / SIGINT：停止通知 Worker → 关闭 WebSocket → 关闭 HTTP → 关闭 Mongo 连接。

本地自检：node scripts/verify-ops-health.js；发布树检查：node scripts/verify-release-tree.js。

版本更新日志

按时间倒序记录系统重大功能迭代

功能对标分析

IM Bridge 与主流商业客服系统（网易七鱼、沃丰 UDESK）的能力对比 — 本表已按当前系统实现修订（2026-03-28）

一、核心功能对比

难度评级: S 简单（1-2 文件） M 中等（3-5 文件） H 较难（多模块联动） X 极难（大量 UI 工程）。已持平项和话务相关项不标注。

二、AI 个性化控制能力对比

难度评级: S 简单 M 中等 H 较难 X 极难。已持平项不标注。

三、总结

四、推荐实施路径

按「投入产出比」排序，优先做 AI 编程能高效完成且业务价值大的功能。约 60-70% 的差距功能可通过 AI 编程达到接近主流产品的水平，主要瓶颈在复杂前端交互（可视化编排、监控大屏、CRM 面板）。

在线客服 KPI 对标（七鱼 / UDESK）

面向当前系统（RBAC v2、队列与运营策略、通知中心、会话质检与 KPI 看板、管理端 AI 中心「Agent Beta」入口、/agent/ 客服工作台）给出的 KPI 产品能力清单与实施优先级。

一、P0（必须上线）

二、P1（对齐商业产品体验）

• 多维钻取：按租户/渠道/技能组/坐席/时段筛选，支持环比同比。
• 班次与峰谷：小时热力图、班次负载分析、峰值预警。
• 转接与主管介入：转接成功率、主管强插率、介入后解决率。
• AI 协同 KPI：AI 命中率、AI 转人工原因 TopN、建议回复采纳率。
• 通知闭环：SLA/差评/积压阈值告警（邮件/短信/站内）与处理追踪。

三、P2（高阶运营能力）

• 目标管理：KPI 目标值、达成率、红黄绿灯、部门排行。
• 预测能力：会话量预测、排班建议、资源利用率优化。
• 质检联动：自动质检分与人工质检结果联合分析。
• 经营视角：服务成本、人效、渠道 ROI、客户生命周期服务表现。

四、指标口径（建议统一）

五、当前系统实施建议（可直接排期）

1. 先做 P0 仪表盘：优先上线 FRT/AHT/CSAT/排队/SLA 5 组核心指标。
2. 打通告警链路：与通知中心联动，支持超阈值自动告警。
3. 增加多维筛选：优先支持“租户 + 渠道 + 技能组 + 坐席 + 时间”。
4. 补齐 AI 协同指标：新增 AI 命中/转人工/建议采纳率统计。