技术分享 | NanoBot 对接飞书

type

Post

status

Published

date

Mar 2, 2026

slug

tech-NanoBot

summary

最近龚老师在服务器上想低成本部署一个能随时调用的 AI Agent：NanoBot + 飞书。

前言

想拥有一个 7x24 小时在线的私人 AI 助理，还能通过飞书随时随地与它交互。但过程并非一帆风顺，从网络源卡死、配置文件格式错误，到权限拦截和 API 限流，我整整折腾了一天。

今天，我就把这次在阿里云上从零部署 NanoBot 并对接飞书的完整过程，连同那些容易踩的“坑”，一次性给大家梳理清楚。建议收藏，照着做能省掉你 80% 的排查时间。

一、环境准备

服务器：阿里云 ECS（Ubuntu/CentOS 均可，本文以 Ubuntu 为例）

核心软件：Docker & Docker Compose

目标应用：NanoBot（开源 AI Agent 框架）

交互终端：飞书机器人（Feishu Bot）

龚老师提示：确保你的服务器安全组已放行出站流量（访问外网），入站流量默认无需开放（我们使用 WebSocket 长连接，由服务器主动连飞书）。

二、第一步：构建“中国速度”的 Docker 镜像

拿到 NanoBot 源码后，直接 docker compose build？那你可能会在第一步就卡住半小时。

1. 痛点：网络超时

默认的 Dockerfile 会从 deb.debian.org 拉取系统包，从 pypi.org 拉取 Python 依赖。在国内服务器上，这简直是“龟速”体验，甚至直接超时失败。

2. 解决方案：替换国内源

我们需要修改项目根目录下的 Dockerfile，将源全部替换为阿里云或清华镜像。

关键修改点：

APT 源：Debian Bookworm Slim 镜像不再使用 /etc/apt/sources.list，而是 /etc/apt/sources.list.d/debian.sources。

PyPI 源：在 uv pip install 命令中显式添加 i <https://mirrors.aliyun.com/pypi/simple/。>

NPM 源：在构建 Bridge 时，设置 npm config set registry <https://registry.npmmirror.com>。

优化后的 Dockerfile 片段示例：

龚老师经验：改完 Dockerfile 后，务必加上 --no-cache 参数重新构建，否则 Docker 会偷懒使用旧的缓存层。 docker compose build --no-cache

三、第二步：配置文件与挂载的“玄学”

构建完成后，启动容器却报错 Error: No API key configured？这是最容易让人崩溃的环节。

1. 配置文件位置

NanoBot 默认读取 ~/.nanobot/config.json。在 Docker 环境中，~ 代表容器内的 /root。 关键点：你必须将宿主机的配置文件挂载到容器内。

2. 路径陷阱

在 docker-compose.yml 中，千万不要写 ~/.nanobot:/root/.nanobot。 Docker Compose 对 ~ 的解析有时会出现偏差，导致挂载了一个空目录。 正确做法：使用绝对路径。

3. JSON 格式的严格性

NanoBot 使用 Pydantic 进行配置校验，多一个字段、少一个括号、类型不对，都会导致整个配置文件被丢弃，从而回退到“无配置”状态。

常见错误案例：

错误："allowFrom": "ou_xxxxx" （字符串）

正确："allowFrom": ["ou_xxxxx"] （必须是列表）

错误：保留了 webSearch 字段（新版已移除该配置项）。

后果：日志报 Extra inputs are not permitted，然后服务启动失败。

一份可用的 config.json 模板（请脱敏替换）：

龚老师提示：初次调试时，allowFrom 建议先填你自己的飞书 Open ID（日志报错时会显示），测试通了再改为 ["*"] 开放给所有人。

四、第三步：飞书后台配置的“最后一公里”

容器启动了，日志显示 Feishu channel enabled，但在飞书上发消息却没反应？或者只回你一个点赞表情？

1. 事件订阅是核心

登录飞书开发者后台，进入事件订阅页面。 必须勾选以下事件（缺一不可）：

接收消息_v1.0 (im.message.receive_v1)：这是机器人能“听见”你说话的关键。

获取与发送单聊、群组消息：这是机器人能“开口”回复的权限。

坑点：很多教程只说了要开权限，没说具体要订阅哪个事件。没订阅 接收消息，机器人就是个聋子。

2. 关闭系统自动回复

在飞书后台的机器人设置里，检查是否有“收到消息自动回复”的系统配置。如果有，关掉它。否则当 NanoBot 因限流或处理慢没及时回复时，飞书系统会自作聪明地发一个默认表情（比如点赞），干扰你的判断。

五、第四步：常见报错与“排雷”指南

部署过程中，你可能会遇到以下几个经典报错，我对号入座给你解法：

1. `Connection reset by peer`

现象：curl 测试端口不通，容器反复重启。

原因：配置文件加载失败，导致服务启动中途崩溃。

解法：检查 docker compose logs，重点看有没有 Failed to load config 或 validation error。修正 JSON 格式后强制重启。

2. `Access denied for sender ...`

现象：日志明确说拒绝访问，飞书端无回复。

原因：你的飞书用户 ID 不在 allowFrom 白名单里。

解法：从日志中复制你的 ou_ 开头的 ID，填入 config.json 的 allowFrom 列表中。

3. `Error code: 429 ... TPM limit reached`

现象：配置都对了，也能收到消息，但回复报错 429。

原因：API 提供商（如 CherryAI）的每分钟 Token 限额（TPM） 到了。

解法：

歇一分钟再试（TPM 是滚动计算的）。
调小 config.json 中的 maxTokens 和 maxToolIterations，减少单次消耗。
升级 API 套餐。

4. `processor not found: im.message.reaction.created_v1`

现象：日志里偶尔飘过这个 ERROR。

原因：你在飞书上给消息点了赞，NanoBot 收到了这个事件但没写处理逻辑。

解法：忽略它。这不影响文字聊天。想眼不见为净，就去飞书后台取消订阅“消息表情回应”事件。

六、总结与展望

经过这一番折腾，当你在飞书上发出“你好”，看到 NanoBot 秒回一段深思熟虑的文字时，那种成就感是无与伦比的。

核心成功要素总结：

网络加速：Dockerfile 里的源必须换国内的。

配置严谨：JSON 格式、路径挂载、字段类型，一个都不能错。

权限完备：飞书后台的事件订阅和 API 权限要开全。

白名单机制：调试期务必配置 allowFrom，避免被安全策略拦截。

现在，我的 NanoBot 已经稳稳地跑在阿里云上，成为了我日常工作的得力助手。接下来，我打算给它接入更多工具（搜索、代码解释器），让它真正进化为一个“智能体”。

如果你也在部署过程中遇到了问题，欢迎在评论区留言，龚老师帮你一起把关！

（完）