# 部署消息网关

部署飞书与 Slack 共用的消息网关，检查实例心跳、频道连接和实际回复。

部署说明 · 模块: deploy · 管理人员 · 部署形态：私有部署 · 已确认产品版本：资料未说明 · 来源：现有文档

消息网关维持飞书和 Slack 的平台连接，并在平台与 AskTable 后端之间转换消息。镜像与服务名仍使用 `asktable-feishu-gateway`，实际由同一个服务承载两个平台。它不包含智能体逻辑，通过 Redis 与主服务通信；私有部署需要单独添加，未使用消息频道时无需部署。

主服务与网关必须使用配套发布的版本。频道协议更新时，两者要同时升级，不能仅更新其中一个。

## 前置条件

| 项目   | 要求                                                                                  |
| ---- | ----------------------------------------------------------------------------------- |
| 基础部署 | 已按 [私有部署（Docker）](https://docs.asktable.com/deploy/docker) 跑起来，`asktable-redis` 在运行 |
| 平台应用 | 飞书准备 App ID、App Secret，并启用长连接与接收消息事件；Slack 准备 Bot Token、App Token，并启用 Socket Mode   |
| 数据   | 项目里已有可用的数据源和数据智能体                                                                   |
| 授权范围 | 已确认这个智能体可以向哪些成员或部门开放                                                                |

平台应用的创建、权限申请与发布步骤见[接入飞书机器人](https://docs.asktable.com/integrations/feishu)或[接入 Slack 机器人](https://docs.asktable.com/integrations/slack)。

## 操作步骤

**加网关服务**

在 `docker-compose.yaml` 里加上这个服务：

```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`。

**启动**

```bash
docker compose up -d asktable-feishu-gateway
```

**确认网关心跳写进了 Redis**

```bash
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`，主服务和网关同步升级 |
| 与定时报告的关系    | 频道是“用户提问、机器人回答”的双向对话；定时推送是另一套，见 [定时分析报告](https://docs.asktable.com/integrations/scheduled-reports) | —                                          |

## 出问题怎么判断

| 现象            | 判定条件                          | 处理                                                                                                                  |
| ------------- | ----------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| 实例心跳没有更新      | `gateway:<实例 ID>` 不存在或时间戳停止更新 | 检查容器状态、网关日志和 Redis 连通性；旧字段残留不代表网关仍在线                                                                                |
| 心跳正常但频道未连接    | 该平台没有生效，或单频道状态缺失、凭证无效         | 在智能体「频道」检查当前平台、连接说明与凭据；心跳正常不等于频道已连接                                                                                 |
| 网关启动即退出       | 日志显示 Redis 连接被拒               | 核对 `REDIS_URL`，确认 `asktable-redis` 正常运行                                                                             |
| 已连接但最近消息没更新   | 平台没有投递本次问题                    | 核对事件订阅、应用发布、机器人是否在群内或频道内，以及问题是否 `@`；先用私聊测试                                                                          |
| 消息处理失败        | 「最近消息」→「详情」中的处理状态失败           | 核对数据源和人员授权，再按具体错误查看主服务日志                                                                                            |
| 回复投递失败        | 分析已完成，但回复状态失败                 | 核对机器人发送权限和目标位置；查看网关日志里的平台错误                                                                                         |
| 用户提问被拒绝或进入待审批 | 白名单开启，人员绑定或智能体授权缺失            | 按[飞书用户权限](https://docs.asktable.com/permissions/feishu)或 [Slack 指南](https://docs.asktable.com/integrations/slack)处理 |
| 停用后收不到新消息     | 当前平台选择「不启用」                   | 重新选择已配置的平台；停用保留凭证和配置                                                                                                |

## 下一步

- [接入飞书机器人](https://docs.asktable.com/integrations/feishu) — 飞书应用的创建、权限与发布
- [接入 Slack 机器人](https://docs.asktable.com/integrations/slack) — Socket Mode 应用与人员授权
- [设置数据访问范围](https://docs.asktable.com/permissions) — 人员、角色与智能体白名单
- [部署 AI 搜索（值索引）](https://docs.asktable.com/deploy/ai-search) — 让飞书里的简称提问也能命中完整值
- [私有部署（Docker）](https://docs.asktable.com/deploy/docker) — 主服务部署与排障表