部署飞书网关

飞书网关（asktable-feishu-gateway）只做两件事：维持飞书 IM 的长连接，以及在飞书和 AskTable 后端之间转换消息。它不含智能体逻辑，通过 Redis 与主服务通信，因此主服务侧不需要为它加任何配置。私有部署里这个容器不随主 compose 一起装。不接飞书就不用加它，主服务功能不受影响。

前置条件

项目	要求
基础部署	已按私有部署（Docker）跑起来，`asktable-redis` 在运行
飞书应用	已创建企业自建应用并启用机器人，拿到 App ID 和 App Secret
事件订阅	飞书应用已启用长连接，订阅「接收消息 v2.0」
数据	项目里已有可用的数据源和数据智能体
授权范围	已确认这个智能体可以向哪些成员或部门开放

飞书应用侧的创建、权限申请和发布步骤见接入飞书机器人。

操作步骤

加网关服务

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

services:
  # 飞书网关：接入飞书 IM 时才需要
  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

出现形如 feishu:<实例 ID> 的字段，值里 status 是 ok，说明网关活着。网关每 30 秒写一次这个心跳。

在智能体上配飞书频道

打开目标数据智能体 → 顶部标签「频道」→「飞书」，填这几个字段：

字段	必填
App ID	是
App Secret	是
Encrypt Key	否，飞书开了消息加密才填
Verification Token	否

保存后页面下方出现「运行状态」卡片，里面有连接状态和最后事件两项，右上角是「刷新」按钮。

在飞书里验一次

由一个在授权范围内的成员私聊机器人提问，再把机器人拉进测试群 @ 它提问。两处都能拿到回答，就算接通了。

关键约束

项目	值或默认	在哪里改
通信方式	只走 Redis，网关不监听宿主机端口	`asktable-feishu-gateway` 不加 `ports`
`REDIS_URL`	`redis://asktable-redis:6379`，必须和主服务一致	网关的 `environment`
心跳	每 30 秒往 `at:channel:health` 写一个 `feishu:<实例 ID>` 字段	—
频道状态判定	`at:channel:health` 里有 `feishu:` 字段就是已连接状态，没有就是未连接状态	—
频道凭证	存在 AskTable 后端，由后端通过 Redis 推给网关；网关环境变量里不放 App ID	智能体 →「频道」→「飞书」
渠道偏好	默认空，最多 1024 个字符	同上
深度推理	默认关闭，即用快速模式	同上
会话映射	每个飞书用户一条独立会话，键 `at:channel:session:{channel_id}:{sender_id}`，24 小时过期	—
镜像标签	只有 `latest`（网关按 commit 打标签，不跟随主版本号）	`docker-compose.yaml` 的 `image`；升级用 `docker compose pull`
与定时报告的关系	频道是“用户提问、机器人回答”的双向对话；定时推送是另一套，见定时分析报告	—

出问题怎么判断

现象	判定条件	处理
连接状态显示为未连接	`docker compose exec asktable-redis redis-cli hgetall at:channel:health` 里没有 `feishu:` 开头的字段	网关没起来或连不上 Redis：看 `docker compose ps`，再看 `docker compose logs asktable-feishu-gateway`
心跳有但状态仍是未连接	智能体「频道」→「飞书」里这个频道没启用	保存频道配置后重新打开该智能体
网关启动即退出	`docker compose logs asktable-feishu-gateway` 里 Redis 连接被拒	`REDIS_URL` 写错，或 `asktable-redis` 没在运行
私聊机器人没反应	最后事件显示为暂无事件	飞书应用没开长连接或没订阅「接收消息 v2.0」，去飞书开放平台核对
群里 `@` 没反应，私聊正常	私聊有回答，群里最后事件不更新	机器人没被拉进群，或群消息相关权限没发布
回复内容出现处理失败提示	卡片正文以“⚠️ 处理失败：”开头	这是后端处理失败，按提示里的错误去查主服务日志，网关本身没问题
用户提问后没权限	该成员不在智能体「频道」→「人员」白名单里	按设置数据访问范围给人员或角色授权
心跳字段过一会儿消失了	距离上次写入超过 30 秒且网关已停止	容器挂了，看 `docker compose ps` 与日志

下一步

接入飞书机器人 — 飞书应用的创建、权限与发布
设置数据访问范围 — 人员、角色与智能体白名单
部署 AI 搜索（值索引） — 让飞书里的简称提问也能命中完整值
私有部署（Docker） — 主服务部署与排障表

部署与运维

选择接入方式

飞书机器人

网页嵌入

开发与自动化

定时分析报告

部署飞书网关

前置条件

操作步骤

关键约束

出问题怎么判断

下一步

​前置条件

​操作步骤

​关键约束

​出问题怎么判断

​下一步

前置条件

操作步骤

关键约束

出问题怎么判断

下一步