Fanbook 中文文档 下载 App

BOT 开发问题 Token 权限命令无响应排错

Token 问题

问题：调用任何 API 都返回「未授权」

排查步骤：

  1. 确认 Bot Token 是否和机器人管理后台显示的完全一致（复制时多了空格、少了字符都是常见问题）
  2. 确认 Token 没有被重置过（重置后旧 Token 立即失效）
  3. 确认请求 URL 格式正确——Token 应该在 https://a1.fanbook.cn/api/bot/{BotToken}/ 的路径中

问题：Bot Token 疑似泄露

立即做：

  1. 在机器人管家里重置 Token
  2. 同步更新你所有代码里的 Token
  3. 检查是否有异常 API 调用记录（如果 Bot API 提供的话）
  4. 检查服务器日志里有没有可疑请求

预防措施：

权限问题

问题：BOT 无法在频道发消息

排查步骤：

  1. BOT 是否已被加入目标服务器？
  1. BOT 是否有 SEND_MESSAGES 权限？
  1. 目标频道有没有频道级权限覆盖？
  1. BOT 的隐私模式设置？

问题：BOT 无法执行管理员操作（踢人、删消息等）

排查： 管理员操作需要 BOT 有对应的管理类权限（KICK_MEMBERS、MANAGE_MESSAGES 等），普通发消息权限不够。同时检查 BOT 的角色优先级——如果被管理的成员角色优先级更高，BOT 也无法操作。

命令无响应

问题：@BOT 命令没反应

排查步骤：

  1. BOT 是否能在频道发消息？（先解决上一条权限问题）
  2. 隐私模式是否开启？ 开启隐私模式后 BOT 只接收被 @的消息——你 @它了吗？
  3. 命令有没有正确配置？ 在机器人管家或 Bot API 中确认命令列表已添加
  4. BOT 代码有没有在运行？ 检查你部署 BOT 的服务器 / 进程是否正常运行
  5. WebSocket / 长轮询是否正常？ 查看 BOT 是否收到了你发送 @命令的那条消息
  6. 消息是否被敏感词过滤？ 如果命令触发了敏感词规则，消息可能被拦截

问题：BOT 收到了消息但没回复

排查：

  1. 你的消息处理代码有没有正确识别和响应？
  2. 有没有进入无限循环或报错导致代码崩了？
  3. 回复消息有没有因为权限问题被 Fanbook 拦截？
  4. 可以在代码里加 print 日志，看代码执行到哪一步了

长轮询 / WebSocket 问题

问题：长轮询收不到新消息

排查：

  1. 确认 BOT Token 有效
  2. 确认请求参数（offset / limit 等）正确
  3. 隐私模式：如果开启了，BOT 只接收 @它的消息和私聊
  4. 查看 API 错误响应——是不是限流了、是不是权限问题

问题：WebSocket 连接断开

排查：

  1. User Token 有没有过期？过期后需要重新获取
  2. 网络是否稳定？如果频繁断，考虑加自动重连逻辑
  3. 服务器是否在国内？如果 Fanbook WebSocket 服务器在国内，境外服务器连接可能不稳定
  4. 检查官方 API 文档中对 WebSocket 连接的具体要求（心跳、重连间隔等）

API 限流

问题：频繁触发限流错误（错误码 6 或 7）

原因： Fanbook Bot API 有调用频率限制，超过后返回限流错误。

解决方案：

  1. 降低调用频率
   import time
   # 每次 API 调用后至少间隔 300ms
   last_call = 0
   MIN_INTERVAL = 0.3

   def api_call():
       global last_call
       now = time.time()
       wait = MIN_INTERVAL - (now - last_call)
       if wait > 0:
           time.sleep(wait)
       last_call = time.time()
       # 实际调用
  1. 用 WebSocket 替代长轮询——长轮询每秒一次，10 小时就是 36000 次调用，很容易触发限流。WebSocket 只有事件推送时才消耗调用。
  2. 实现退避重试
   def call_with_retry(max_retries=3):
       for i in range(max_retries):
           resp = call_api()
           if resp.get("ok"):
               return resp
           # 如果是限流错误
           if resp.get("error", {}).get("code") in (6, 7):
               wait_time = 2 ** i  # 指数退避：1s → 2s → 4s
               time.sleep(wait_time)
               continue
           # 其他错误不重试
           break
  1. 联系官方申请更高额度——如果你的 BOT 确实需要高频率调用，可以尝试联系 Fanbook 官方申请提高限流阈值。

部署问题

问题：BOT 在本地能跑，部署后不行

排查：

  1. 服务器能不能访问 a1.fanbook.cn？ 在服务器上用 curl 或 ping 测试
  2. 环境变量有没有正确配置？ 本地是 .env 文件，部署后可能忘了设置
  3. 进程有没有在后台保持运行？ 用 systemd / PM2 / Docker 等工具保持进程常驻
  4. Python / Node.js 版本一致吗？ 本地和服务器版本差异可能导致问题

问题：服务器挂了 BOT 就停了

解决方案： 用进程守护工具让 BOT 自动重启：

  [Unit]
  Description=My Fanbook BOT
  After=network.target

  [Service]
  Type=simple
  ExecStart=/path/to/python bot.py
  Restart=always
  RestartSec=5

  [Install]
  WantedBy=multi-user.target
  pm2 start bot.js --name my-fanbook-bot
  pm2 save
  pm2 startup  # 开机自启

综合排错 checklist

遇到 BOT 问题时按这个顺序排查：