# chatbot（微信对话回调服务） 本项目是一个基于 FastAPI 的微信对话开放平台回调服务，核心目标是： - 接收并解密公众号私信回调（接口 A） - 根据关键词回复用户（支持 H5 卡片） - 后台触发抓包接口 B 获取会话列表 - 将用户资料同步到 PocketBase --- ## 一、当前实现状态 ### 1) 回调入口（接口 A） - 支持 `POST /` - 支持 `POST /wechat/thirdapi` - 支持加密请求体解析 - 支持解密后明文为 JSON / XML 两种格式 ### 2) 关键词回复 内置规则： - 包含 `电子书`：返回“数字游民”H5 内容 - 包含 `群`：返回“异度星球”H5 内容 - 其他内容：返回默认引导文案 ### 3) 接口 B（抓包） 用于拉取会话列表（数据同步用途）： - `https://chatbot.weixin.qq.com/miniopenai/manualservice/getaccessstautuslist` ### 4) PocketBase 同步 将用户资料写入 `wechat_private_users`，字段包含： - `userid` - `channel_id` - `nick` - `avatar` - `source_query` - `source_message_id` - `source_message_time` - `matched_last_msg` - `matched_last_msg_id` - `matched_last_msg_time` - `raw_contact` --- ## 二、项目结构 ```text chatbot/ ├── main.py # 回调主流程、关键词逻辑、B同步、PB写库、调试接口 ├── crypto_utils.py # AES加解密、签名 ├── config.py # 应用配置（A/B/PB） ├── run.py # 启动入口（8001） ├── requirements.txt # 依赖 └── README.md ``` --- ## 三、快速启动 ### 1) 安装依赖 ```bash pip install -r requirements.txt ``` ### 2) 启动 ```bash python run.py ``` 默认端口： - `http://0.0.0.0:8001` --- ## 四、配置说明（config.py） ### 1) 接口 A 配置 - `APP_ID` - `TOKEN` - `ENCODING_AES_KEY` 这些值必须与微信对话平台后台一致。 ### 2) PocketBase 配置 - `PB_URL` - `PB_ADMIN_EMAIL` - `PB_ADMIN_PASSWORD` - `PB_COLLECTION` 当前策略： - Windows 本地调试默认使用 `PB_DOMAIN_URL` - 非 Windows 默认使用 `PB_INTERNAL_URL` - 若设置环境变量 `PB_URL`，优先使用环境变量 ### 3) 接口 B 配置 - `PM_SYNC_AUTHTOKEN` - `PM_SYNC_DEFAULT_WXBOT_BID` 说明：B 是后台同步数据源，不影响 A 主回复链路。 --- ## 五、回调处理流程 1. 微信平台回调到 A（`/` 或 `/wechat/thirdapi`） 2. 服务端读取 body 并解密 3. 解析为统一字段（`UserId`、`Query`、`Timestamp` 等） 4. 关键词命中后生成回复内容 5. 主流程优先返回（保证用户体验） 6. 后台异步触发 B 接口 7. 匹配用户并同步到 PocketBase --- ## 六、接口清单 ### 1) 业务接口 - `POST /` - `POST /wechat/thirdapi` ### 2) 调试接口 - `GET /health` - `GET /debug/echo` - `POST /debug/sync-test` ### 3) 调试页面 - `GET /private-message` 用于测试 B 查询、Token 分析、用户列表展示。 --- ## 七、PocketBase 集合建议 集合名：`wechat_private_users` 建议索引： - `userid + channel_id` 组合索引 - 或 `source_message_id` 唯一索引（若来源稳定唯一） --- ## 八、常见问题排查 ### Q1：回调收到了但用户没看到回复 - 检查 `APP_ID/TOKEN/ENCODING_AES_KEY` 是否和后台一致 - 检查回调 URL 是否为当前服务地址 - 查看日志中是否有解密失败/解析失败 ### Q2：B 接口正常，PB 失败 通常是 PB 地址或认证路径问题： - 已兼容 `/api/admins/auth-with-password` - 已兼容 `/api/collections/_superusers/auth-with-password` ### Q3：B 或 PB 失败会不会影响用户回复 不会。当前设计是： - 关键词回复优先 - B/PB 为后台任务，失败只记日志 --- ## 九、参考文档 - 微信开放文档（发送客服消息）： --- ## 十、后续优化建议 - 将关键词规则做成数据库配置化 - 增加持久化幂等（避免服务重启后重复处理） - 增加结构化日志和告警 - 将敏感配置迁移到环境变量统一管理