可选组件
部署消息网关
部署飞书与 Slack 共用的消息网关，检查实例心跳、频道连接和实际回复。
消息网关维持飞书和 Slack 的平台连接，并在平台与 AskTable 后端之间转换消息。镜像与服务名仍使用 asktable-feishu-gateway，实际由同一个服务承载两个平台。它不包含智能体逻辑，通过 Redis 与主服务通信；私有部署需要单独添加，未使用消息频道时无需部署。
主服务与网关必须使用配套发布的版本。频道协议更新时，两者要同时升级，不能仅更新其中一个。
前置条件
| 项目 | 要求 |
|---|---|
| 基础部署 | 已按 私有部署（Docker） 跑起来，asktable-redis 在运行 |
| 平台应用 | 飞书准备 App ID、App Secret，并启用长连接与接收消息事件；Slack 准备 Bot Token、App Token，并启用 Socket Mode |
| 数据 | 项目里已有可用的数据源和数据智能体 |
| 授权范围 | 已确认这个智能体可以向哪些成员或部门开放 |
平台应用的创建、权限申请与发布步骤见接入飞书机器人或接入 Slack 机器人。
操作步骤
加网关服务
在 docker-compose.yaml 里加上这个服务：
services:
# 消息网关：飞书与 Slack 共用
asktable-feishu-gateway:
image: registry.cn-shanghai.aliyuncs.com/datamini/asktable-feishu-gateway:latest
container_name: asktable-feishu-gateway
restart: unless-stopped
depends_on:
- asktable-redis
environment:
REDIS_URL: redis://asktable-redis:6379它和主服务共用同一个 asktable-redis，不要给它加 ports。
启动
docker compose up -d asktable-feishu-gateway确认网关心跳写进了 Redis
docker compose exec asktable-redis redis-cli hgetall at:channel:health出现 gateway:<实例 ID> 字段，且值里的 status 为 ok、时间戳持续更新，说明网关进程正在上报心跳。心跳每 30 秒更新一次，服务端不采用超过 75 秒的心跳；Redis 中留下旧字段也不能证明实例仍在线。它不能证明具体频道已连接。
选择平台并配置频道
打开目标数据智能体 →「频道」→「平台」，选择飞书或 Slack。首次配置需要填写对应凭证并保存，成功后才启用；取消会保留原平台。
| 平台 | 凭证 |
|---|---|
| 飞书 | App ID、App Secret 必填；Encrypt Key、Verification Token 按应用配置选填 |
| Slack | Bot Token（xoxb-）和 App Token（xapp-）必填 |
查看「连接状态」，再发送测试问题。状态每 5 秒刷新；「最近消息」的「详情」分别显示处理与回复投递结果。
用真实问题验证
由一个在授权范围内的成员私聊机器人提问，再把机器人加入测试群或频道并 @ 提问。确认有正确回复，且结果符合该成员的数据权限。实例心跳、连接成功、分析完成和回复投递成功需要分别判断。
关键约束
| 项目 | 值或默认 | 在哪里改 |
|---|---|---|
| 通信方式 | 只走 Redis，网关不监听宿主机端口 | asktable-feishu-gateway 不加 ports |
REDIS_URL | redis://asktable-redis:6379，必须和主服务一致 | 网关的 environment |
| 实例心跳 | 每 30 秒向 at:channel:health 写入 gateway:<实例 ID> | 只用于判断网关实例是否活跃 |
| 单频道状态 | <平台>:channel:<频道 ID>:<实例 ID>，需对应实例心跳有效且配置版本匹配 | 智能体 →「频道」→「连接状态」 |
| 频道凭证 | 存在 AskTable 后端，由后端通过 Redis 推给网关；网关环境变量里不放 App ID | 智能体 →「频道」→「凭证配置」 |
| 渠道偏好 | 默认空，最多 1024 个字符 | 智能体 →「频道」→「通用配置」 |
| 深度推理 | 默认关闭，即用快速模式 | 智能体 →「频道」→「通用配置」 |
| 会话延续 | 私聊和顶层问答按同一人复用，连续 24 小时没有新消息后重建；话题会话不按该窗口过期 | 同一话题只接受最初提问者，群内追问仍需 @ |
| 镜像版本 | 示例使用 latest；正式部署使用与主服务配套的网关镜像 | docker-compose.yaml 的 image，主服务和网关同步升级 |
| 与定时报告的关系 | 频道是“用户提问、机器人回答”的双向对话；定时推送是另一套，见 定时分析报告 | — |
出问题怎么判断
| 现象 | 判定条件 | 处理 |
|---|---|---|
| 实例心跳没有更新 | gateway:<实例 ID> 不存在或时间戳停止更新 | 检查容器状态、网关日志和 Redis 连通性；旧字段残留不代表网关仍在线 |
| 心跳正常但频道未连接 | 该平台没有生效，或单频道状态缺失、凭证无效 | 在智能体「频道」检查当前平台、连接说明与凭据；心跳正常不等于频道已连接 |
| 网关启动即退出 | 日志显示 Redis 连接被拒 | 核对 REDIS_URL，确认 asktable-redis 正常运行 |
| 已连接但最近消息没更新 | 平台没有投递本次问题 | 核对事件订阅、应用发布、机器人是否在群内或频道内，以及问题是否 @；先用私聊测试 |
| 消息处理失败 | 「最近消息」→「详情」中的处理状态失败 | 核对数据源和人员授权，再按具体错误查看主服务日志 |
| 回复投递失败 | 分析已完成，但回复状态失败 | 核对机器人发送权限和目标位置；查看网关日志里的平台错误 |
| 用户提问被拒绝或进入待审批 | 白名单开启，人员绑定或智能体授权缺失 | 按飞书用户权限或 Slack 指南处理 |
| 停用后收不到新消息 | 当前平台选择「不启用」 | 重新选择已配置的平台；停用保留凭证和配置 |
下一步
- 接入飞书机器人 — 飞书应用的创建、权限与发布
- 接入 Slack 机器人 — Socket Mode 应用与人员授权
- 设置数据访问范围 — 人员、角色与智能体白名单
- 部署 AI 搜索（值索引） — 让飞书里的简称提问也能命中完整值
- 私有部署（Docker） — 主服务部署与排障表