微信群自动回复加定时微信群发机器人
项目地址：https://github.com/oocsoo/WeChatGroupTask
授权与声明
本项目基于第三方微信云端 SaaS 服务（www.wechatbot.online）提供消息通道，使用前请确保合规。仅供学习与合法业务场景使用，任何滥用（刷屏、骚扰、违规引流）与项目无关。
微信群资料管理
微信群定时任务
一个基于 FastAPI + WebSocket 的微信群智能管理与自动回复系统，支持资料智能分发、定时推送、入群欢迎、同行研判等功能，配套 Web 后台可视化管理。
适用于教培、电商、知识付费等需要在微信群中批量管理客户并按关键词自动发送资料的场景。
目录
功能特性
核心业务
- 关键词自动回复 ：群成员在微信群中
@机器人 关键词即可自动匹配并推送对应资料（图片 / 视频 / Word / PDF / 其他文件）。 - 资料批量管理 ：后台可批量上传、拖拽上传、批量删除资料，支持按 批次（batch_id） 进行归档和隐藏。
- 多维度关键词匹配：按"编号 / 名称模糊匹配 / 关键词列表（逗号分隔）"三种方式匹配。
- 群组化授权：资料与群组建立多对多关联，每个群只能触发被授权的资料。
- 入群欢迎词：新成员入群时自动发送配置好的欢迎词（最多 3 条）。
- 查询回复话术 ：资料发送成功后可附带一条自定义
@用户回复文案。 - 频率限制：每个微信号每分钟触发次数上限（默认 5 次），防刷。
定时任务
- 支持一次性、每日、每周、每月、指定日期等多种调度模式。
- 支持发送文本、图片、文件、视频、以及"指定资料集合 / 批次"。
- 基于 APScheduler 的异步调度，可在后台增删改查任务。
数据分析
- 分发统计：按时间、群组过滤查看分发记录，计算成功率。
- 热门资料排行：按分发次数 TOP N 展示资料。
- 用户统计：汇总用户所在群组、最后触发时间。
- 同行研判：自动对比所有群的成员，找出同时在多个群出现的"同行"账号。
文件存储
- 支持 天翼云 OSS（S3 兼容） 上传，自动清理桶的生命周期规则保证文件不被自动删除。
- OSS 上传失败时自动降级为本地存储（
/uploads/），链接无缝切换。
技术栈
| 层级 | 技术 |
|---|---|
| Web 框架 | FastAPI 0.115 + Uvicorn |
| 数据库 | SQLite + SQLAlchemy 2.0（异步 aiosqlite） |
| 消息通道 | WebSocket（websockets 库） |
| 任务调度 | APScheduler 3.10（AsyncIO 调度器） |
| 对象存储 | boto3（S3 协议，对接天翼云 OSS） |
| 前端模板 | Jinja2 + 原生 HTML/CSS/JavaScript |
| 配置管理 | pydantic-settings（支持 .env） |
工作流程
┌──────────────┐ WebSocket ┌────────────────────┐
│ 微信云端SaaS │ ────────────────► │ websocket_client │
│ (wechatbot) │ 实时消息推送 │ 接收群消息/入群事件 │
└──────────────┘ └──────────┬─────────┘
│
▼
┌────────────────────┐
│ message_handler │
│ 解析 @ 提取关键词 │
│ 频率限制 / 资料查找 │
└──────────┬─────────┘
│
┌───────────────────────┼───────────────────────┐
▼ ▼ ▼
┌────────────────┐ ┌────────────────┐ ┌────────────────┐
│ wechat_service │ │ 数据库 │ │ oss_service │
│ 调用 HTTP API │ │ 资料/群组/记录 │ │ 文件上传下载 │
│ 发送消息 │ │ │ │ │
└────────────────┘ └────────────────┘ └────────────────┘
▲
│
┌────────┴────────┐
│ task_scheduler │
│ APScheduler 定时│
│ 推送资料到群 │
└─────────────────┘项目结构
wxgroupresearch/
├── main.py # FastAPI 入口，挂载路由、生命周期
├── config.py # 配置（Pydantic Settings，读 .env）
├── database.py # 异步 SQLAlchemy 引擎与会话工厂
├── models.py # 数据库模型定义
├── websocket_client.py # WebSocket 长连客户端 + 心跳
├── message_handler.py # 群消息/入群事件处理核心逻辑
├── task_scheduler.py # APScheduler 定时任务调度
├── wechat_service.py # 微信消息发送 HTTP 客户端
├── oss_service.py # 天翼云 OSS (S3) 上传/删除
├── user_service.py # 用户服务 + 频率限制
├── group_collection_service.py # 群组自动收集（写入 group.json）
├── peer_analysis_service.py # 同行研判（跨群取交集）
│
├── api_materials.py # /api/materials 资料管理
├── api_groups.py # /api/groups 群组管理
├── api_tasks.py # /api/tasks 定时任务
├── api_stats.py # /api/stats 分发统计
├── api_peers.py # /api/peers 同行研判
│
├── migrate_db.py # 数据库迁移：batch_id / hidden_batches
├── add_batch_id_to_tasks.py # 迁移脚本
├── add_material_ids_to_tasks.py # 迁移脚本
├── add_query_reply_message.py # 迁移脚本
├── analyze_time.py # 资料创建时间分析小工具
│
├── requirements.txt # Python 依赖
├── start.bat # Windows 启动脚本
├── .env # 环境变量配置（需自行修改）
│
├── templates/ # Jinja2 页面
│ ├── index.html # 首页 Dashboard
│ ├── materials.html # 资料管理
│ ├── groups.html # 群组管理
│ ├── tasks.html # 定时任务
│ ├── stats.html # 统计报表
│ ├── peers.html # 同行研判
│ ├── upload-records.html # 文档查阅 / 上传批次
│ ├── view-all-materials.html # 查看全部资料
│ ├── debug.html # 调试工具
│ └── cache-debug.html # 缓存调试
│
├── static/
│ ├── css/style.css
│ └── js/{groups,materials,tasks}.js
│
├── uploads/ # 本地上传目录（OSS 降级兜底）
├── group.json # 自动收集到的群组列表
├── wechat_bot.db # SQLite 数据库
└── bot.db # 预留数据库模型
定义在 models.py，使用 SQLAlchemy ORM，首次启动时由 database.init_db() 自动建表。
| 表名 | 说明 | 关键字段 |
|---|---|---|
materials |
资料库 | code(唯一编号) / name / keywords / file_type / file_path / file_key / bucket_name / download_url / wechat_url / batch_id / is_active |
groups |
群组 | group_id(微信群ID) / group_name / is_online / welcome_messages(JSON) / query_reply_message |
group_materials |
群组-资料关联 | group_id / material_id |
scheduled_tasks |
定时任务 | task_name / group_id / material_ids(JSON) / message_type / schedule_type(once/daily/weekly/monthly/date) / schedule_time / repeat_config(JSON) / next_run_time |
distribution_records |
分发记录 | group_id / material_id / user_wxid / user_nickname / keyword / success / error_message |
users |
用户 | wxid / nickname / groups(JSON) / last_trigger_time |
rate_limit_records |
频率限制 | user_wxid / minute_key / trigger_time |
hidden_batches |
隐藏的上传批次 | batch_id |
batch_id 机制 ：同一次上传的一组文件会共享一个 batch_id，方便在"文档查阅"页面按批次归档、隐藏、按批次定时推送。hidden_batches 表用于软隐藏某批次，不影响数据本身。
快速开始
1. 环境要求
- Python 3.8+
- Windows / Linux / macOS 均可（项目包含
start.bat，便于 Windows 一键启动）
2. 克隆并安装依赖
bash
pip install -r requirements.txt3. 配置 .env
打开项目根目录下的 .env，把"微信云端 SaaS 服务平台获取"的占位替换成你的真实值：
ini
# 微信机器人配置（在 www.wechatbot.online 获取）
ROBOT_ID=wxid_xxxxxxxxx
TOKEN=wx_xxxxxxxxxxxxxxxx
SERVER_IP=xxx.xxx.xxx.xxx
SERVER_PORT=5555
API_SERVER=xxx.xxx.xxx.xxx
# 天翼云 OSS 配置
OSS_ACCESS_KEY=xxxxxxxx
OSS_SECRET_KEY=xxxxxxxx
OSS_ENDPOINT=https://shanghai-9.zos.ctyun.cn
# 数据库
DATABASE_URL=sqlite+aiosqlite:///./wechat_bot.db
# 频率限制（每分钟触发次数）
RATE_LIMIT_PER_MINUTE=5
# 心跳间隔（秒）
HEARTBEAT_INTERVAL=60OSS bucket 名由
ROBOT_ID小写化并把_替换为-自动生成，无需手动创建，启动时会自动创建并清理生命周期规则。
4. （可选）运行数据库迁移
如果你是从旧版本升级，需要把 batch_id 字段和 hidden_batches 表补齐：
bash
python migrate_db.py
python add_batch_id_to_tasks.py
python add_material_ids_to_tasks.py
python add_query_reply_message.py新建库则无需执行。
5. 启动
Windows：
bash
start.bat其他平台：
bash
python main.py服务启动后：
- Web 管理后台：http://localhost:8000
- WebSocket 客户端会自动连接配置的
SERVER_IP:SERVER_PORT，注册robotid并保持心跳（断线自动重连，延迟指数退避，最大 60s）。
配置说明
所有配置项集中在 config.py，Pydantic Settings 会自动从 .env 读取：
| 配置项 | 默认值 | 说明 |
|---|---|---|
ROBOT_ID |
wxid_xxx |
微信机器人账号 ID |
TOKEN |
wx_xxx |
调用微信 API 的鉴权 Token |
SERVER_IP / SERVER_PORT |
见 .env | WebSocket 服务端地址 |
API_SERVER |
见 .env | 微信消息发送 HTTP API 服务器 |
OSS_ACCESS_KEY / OSS_SECRET_KEY |
- | 天翼云 OSS 凭证 |
OSS_ENDPOINT |
https://shanghai-9.zos.ctyun.cn |
OSS 接入点 |
DATABASE_URL |
sqlite+aiosqlite:///./wechat_bot.db |
异步 SQLite 数据库 |
RATE_LIMIT_PER_MINUTE |
5 |
单用户每分钟最大触发次数 |
HEARTBEAT_INTERVAL |
60 |
WebSocket 心跳间隔（秒） |
API 接口
所有接口均为 JSON，返回通用结构 { "success": bool, "data"|"error": ... }。
资料管理 /api/materials
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | /api/materials/ |
分页查询资料（page、page_size） |
| GET | /api/materials/upload-times |
最近 7 次上传批次（30 秒内自动合并） |
| POST | /api/materials/ |
上传资料（multipart：code / name / keywords / file_type / batch_id / file） |
| PUT | /api/materials/{id} |
修改资料 |
| DELETE | /api/materials/{id} |
删除（物理删除 + 清 OSS + 清群组关联） |
| POST | /api/materials/batch-delete |
批量删除 |
| POST | /api/materials/hide-batch/{batch_id} |
隐藏批次 |
| DELETE | /api/materials/hide-batch/{batch_id} |
取消隐藏 |
群组管理 /api/groups
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | /api/groups/ |
查询所有活跃群组 |
| POST | /api/groups/ |
创建群组（已软删除则重激活） |
| PUT | /api/groups/{id} |
更新群组 |
| DELETE | /api/groups/{id} |
软删除群组 |
| GET | /api/groups/{id}/materials |
查询群组已授权资料 |
| POST | /api/groups/{id}/materials/{mid} |
授权资料到群组 |
| DELETE | /api/groups/{id}/materials/{mid} |
解除授权 |
| POST | /api/groups/{id}/online |
机器人上线（启用回复） |
| POST | /api/groups/{id}/offline |
机器人下线 |
| POST | /api/groups/{id}/send-notification |
向群发送文本通知 |
| GET / PUT | /api/groups/{id}/query-reply-message |
查询/修改查询回复话术 |
| GET | /api/groups/collected |
读取 group.json 自动收集到的群列表 |
定时任务 /api/tasks
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | /api/tasks/ |
查询所有任务 |
| POST | /api/tasks/ |
创建任务，自动计算 next_run_time 并加入调度器 |
| PUT | /api/tasks/{id} |
更新任务，同步调度器 |
| DELETE | /api/tasks/{id} |
删除任务 |
schedule_type 支持 once / date / daily / weekly / monthly；repeat_config 是 JSON 字符串，例如每周一 = {"day_of_week": 0}、每月 5 号 = {"day": 5}。
统计 /api/stats
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | /api/stats/distribution |
分发记录（支持 start_date / end_date / group_id 过滤） |
| GET | /api/stats/summary |
汇总：总量、今日、成功率、活跃群、资料总数、用户数 |
| GET | /api/stats/top_materials |
热门资料 TOP N（limit 参数） |
| GET | /api/stats/users |
用户列表 |
| DELETE | /api/stats/distribution/{id} |
删除分发记录 |
同行研判 /api/peers
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | /api/peers/analysis |
获取所有群共同存在的成员列表（取交集） |
其他
GET /api/robot/status--- 检查机器人在线状态。GET /group.json--- 读取自动收集到的群组 JSON。GET /uploads/{file}--- 静态文件（OSS 降级兜底）。
页面路由
| 路径 | 页面 | 功能 |
|---|---|---|
/ |
首页 | 机器人状态 + 统计卡片 |
/materials |
资料管理 | 批量上传、编辑、删除、拖拽上传 |
/groups |
群组管理 | 群组 CRUD、资料授权、上下线切换、欢迎词配置 |
/tasks |
定时任务 | 任务 CRUD、调度预览 |
/stats |
统计报表 | 分发记录与汇总 |
/peers |
同行研判 | 跨群成员交集分析 |
/upload-records |
文档查阅 | 按批次查看上传记录 |
/view-all-materials |
查看全部资料 | 全量资料浏览 |
/debug · /cache-debug |
调试工具 | 开发辅助 |
消息处理流程
1. 群文本消息（MsgType=1）
位于 message_handler.py，核心流程：
websocket_client接收到AddMsg消息，按类型分派。- 只处理群消息（
FromUserName包含@chatroom）。 - 通过
MsgSource.atuserlist判断是否@了机器人，不@则忽略。 - 去掉
@机器人名和全角/半角空格，得到用户输入的关键词。 - 调用
user_service.check_rate_limit()校验频率限制，超限静默丢弃。 - 从群组授权资料中按 编号精确 → 名称模糊 → 关键词列表（逗号分隔任一命中） 匹配。
- 命中后按
file_type分派到wechat_service.send_image_message / send_video_message / send_file_message / send_text_message。 - 附带发送群组的
query_reply_message（@用户 这是您要查询的资料，请查收）。 - 记录一条
DistributionRecord，并把群组自动写入group.json（group_collection_service.add_group）。
2. 入群事件（MsgType=10002）
- 解析 SysMsg XML 中的
<sysmsgtemplate>，提取新成员昵称与 wxid。 - 查询群组配置的
welcome_messages（JSON 数组），逐条@新成员发送。
3. 频率限制
rate_limit_records 表按"微信号 + 分钟键（YYYYMMDDHHMM）"计数，默认每分钟 5 次，超出拒绝。
定时任务
task_scheduler.py 使用 APScheduler AsyncIOScheduler 管理任务。创建任务时：
- 根据
schedule_type计算首次next_run_time并持久化。 - 触发时查询最新任务状态，按
message_type执行：text→ 发送文本image/video/file→ 发送对应媒体materials→ 按material_ids（JSON 数组）依次推送多个资料
- 一次性任务执行后置
is_active=false；循环任务自动推算下次时间。 - 应用启动时从数据库重载所有
is_active=true的任务；更新/删除任务时同步刷新调度器。
常见问题
Q: 启动时报错连接 OSS 失败？
A: OSS 不可用时会自动降级到本地 uploads/ 目录，不影响主流程；请检查 OSS_ACCESS_KEY / OSS_SECRET_KEY / OSS_ENDPOINT，以及机器人 ID 派生出的 bucket 名是否冲突。
Q: WebSocket 一直重连？
A: 检查 .env 中 SERVER_IP / SERVER_PORT 是否是你账号对应的服务端地址，TOKEN 是否有效；客户端会以指数退避（5s → 60s）持续重连。
Q: 关键词不触发？
A: 依次核查：
- 群组是否已"上线"（
/api/groups/{id}/online）； - 资料是否已授权给该群（群组详情 → 关联资料）；
- 用户是否超过频率限制（默认每分钟 5 次）；
- 用户必须
@机器人昵称后再跟关键词； - 关键词要与
code、name（模糊）、或keywords列表（逗号分隔）之一吻合。
Q: 修改了 .env 不生效？
A: Pydantic Settings 在进程启动时读取一次；修改后需重启服务。
Q: 定时任务时间已过但没执行？
A: 对 daily / weekly / monthly，若今天的时间已过，next_run_time 会自动顺延到下一周期；once 任务默认若时间已过则推到明天。