Xiaji-go/docs/multi-platform-channel-deploy.md

Xiaji-Go 多平台渠道配置与回调部署说明

已支持平台

• 官方 QQ Bot（qqbot_official）
• Telegram Bot（telegram）
• 飞书 Bot（feishu）

配置优先级

• 启动时：数据库 channel_configs > config.yaml
• 建议使用后台页面维护渠道配置：/channels

后台入口

• 渠道配置页：/channels
• 渠道 API：
  • GET /api/v1/admin/channels
  • PATCH /api/v1/admin/channels/:platform
  • POST /api/v1/admin/channels/:platform/test
• 审计查询：GET /api/v1/admin/audit

回调地址

• 飞书 webhook: POST /webhook/feishu

飞书事件订阅配置

1. 在飞书开发者后台启用事件订阅
2. 请求网址填：https://<你的域名>/webhook/feishu
3. 订阅事件：im.message.receive_v1
4. 将 verification_token、app_id、app_secret 写入渠道 secrets JSON

渠道 secrets JSON 示例

telegram

{
  "token": "123456:ABCDEF"
}

qqbot_official

{
  "appid": "102857798",
  "secret": "xxxxxx"
}

feishu

{
  "app_id": "cli_xxx",
  "app_secret": "xxx",
  "verification_token": "xxx",
  "encrypt_key": "optional"
}

连接测试说明

• Telegram：调用 getMe
• QQ：调用 getAppAccessToken
• 飞书：调用 tenant_access_token/internal

测试成功会把渠道状态写成 ok，失败写成 error。

幂等去重

• 三平台入站统一落 message_dedup，避免重复处理：
  • telegram: tg:<update_id>
  • qqbot_official: qq:<type>:<message_id>
  • feishu: event_id（回退 message_id）

运行建议

• 对公网暴露前请加 HTTPS（飞书回调必需）
• 建议将管理后台放在内网或反代鉴权后访问
• 定期审计 audit_logs 里渠道配置修改记录