# wechat-mp-message-push

**Repository Path**: m5-work/wechat-mp-message-push

## Basic Information

- **Project Name**: wechat-mp-message-push
- **Description**: 微信消息推送系统是一个基于Flask开发的后台管理系统，用于管理微信公众号消息推送、模板消息发送、自动回复规则设置等功能。该系统支持多微信账号管理、消息推送任务调度、推送记录查询等核心功能，为企业和开发者提供便捷的微信消息管理解决方案。
- **Primary Language**: Unknown
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-02-12
- **Last Updated**: 2026-02-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 微信消息推送系统

## 项目简介

微信消息推送系统是一个基于 **Flask** 开发的后台管理系统，旨在为微信公众号提供便捷的消息管理能力。系统支持多账号管理、模板消息的创建与推送、任务调度、关键词自动回复以及用户权限管理，是企业和开发者实现微信消息自动化的理想解决方案。

## 项目应用

<div align=center>  
<img src="https://dfs.m5.work/d/image/mp.jpg" width=40%> </div>

- **微信公众号：M5Bot短讯**

## 技术栈

- **后端框架**: Flask 2.0.1
- **数据库**: MySQL (SQLAlchemy ORM)
- **任务队列**: Redis + Celery (异步任务处理)
- **认证授权**: JWT (Flask-JWT-Extended)
- **前端**: HTML + CSS + JavaScript (Bootstrap 风格)
- **依赖管理**: python-dotenv, requests, xmltodict

## 项目结构

```
wxmsg/
├── api/                 # RESTful API 接口模块
│   ├── auth.py          # 用户认证 (登录/登出/刷新)
│   ├── account.py       # 公众号账号管理
│   ├── template.py      # 模板消息管理
│   ├── push.py          # 消息推送接口
│   └── reply.py         # 自动回复规则接口
├── config/              # 配置文件
│   ├── config.py        # Flask 及基础配置
│   └── wechat.py        # 微信错误码配置
├── message/             # 消息业务逻辑
│   ├── push.py          # 推送处理逻辑
│   └── template.py      # 模板同步与处理
├── models/              # 数据库模型
│   ├── account.py       # 公众号账号
│   ├── template.py      # 消息模板
│   ├── record.py        # 推送记录
│   ├── reply_rule.py    # 自动回复规则
│   ├── task.py          # 定时任务
│   ├── web_user.py      # 后台用户
│   └── user_message.py  # 用户消息
├── tasks/               # Celery 异步任务
│   └── push.py          # 消息推送任务
├── utils/               # 工具类
│   ├── weixin/          # 微信 SDK (Auth, Client, Callback, Token)
│   ├── crypto.py        # 加密/签名验证
│   ├── http.py          # HTTP 请求封装
│   └── xml.py           # XML 解析与生成
├── web/                 # Web 前端页面
│   ├── static/          # 静态资源 (CSS, JS)
│   └── templates/       # HTML 模板
├── app.py               # 应用入口
└── requirements.txt     # Python 依赖列表
```

## 核心功能

### 1. 微信账号管理
支持添加、编辑、删除多个微信公众号账号，并自动维护 `access_token`。

### 2. 模板消息管理
支持从微信服务器同步模板库，并在本地进行管理（增删改查），支持模板预览。

### 3. 消息推送
- **即时推送**: 手动向单个或批量用户发送模板消息。
- **定时推送**: 创建定时任务，由 Celery 异步执行。
- **推送记录**: 详细记录每次推送的状态与结果。

### 4. 自动回复
- **关键词回复**: 根据用户发送的关键词自动匹配规则并回复。
- **关注/事件回复**: 用户关注公众号时自动发送欢迎信息。
- **消息类型回复**: 支持文本、图片、图文等多种回复类型。

### 5. Web 后台管理
- 用户登录/登出 (JWT 认证)。
- 密码修改。
- 简洁的 Web 界面管理所有功能。

## 快速开始

### 环境要求

- Python 3.7+
- MySQL 5.7+
- Redis 5.0+

### 安装步骤

1. **克隆项目**
   ```bash
   git clone <项目地址>
   cd wxmsg
   ```

2. **创建虚拟环境**
   ```bash
   python -m venv .venv
   ```

3. **激活虚拟环境**
   - Windows:
     ```bash
     .venv\Scripts\activate
     ```
   - Linux/Mac:
     ```bash
     source .venv/bin/activate
     ```

4. **安装依赖**
   ```bash
   pip install -r requirements.txt
   ```

5. **配置环境变量**
   复制 `.env_template` 为 `.env` 并修改数据库和 Redis 配置：
   ```bash
   # 数据库连接
   DATABASE_URL=mysql+pymysql://username:password@localhost:3306/wxmsg
   
   # Redis 连接
   REDIS_URL=redis://localhost:6379/0
   
   # JWT 密钥
   SECRET_KEY=your_secret_key
   ```

6. **启动应用**
   ```bash
   # 启动 Flask 主服务
   python app.py
   ```

7. **启动 Celery Worker**
   (在新的终端窗口中执行，用于处理异步推送任务)
   ```bash
   celery -A tasks worker --loglevel=info
   ```

8. **访问系统**
   浏览器访问：`http://localhost:5000/web`

   **默认登录账号**：
   - 用户名：`admin`
   密码：`admin123`

## API 文档

所有 API 均需在 Header 中携带 `Authorization: Bearer <token>` 进行认证 (除登录接口)。

### 认证接口
- `POST /api/auth/login` - 用户登录
- `POST /api/auth/logout` - 用户登出
- `POST /api/auth/refresh` - 刷新访问令牌

### 公众号账号接口
- `GET /api/accounts` - 获取账号列表
- `POST /api/accounts` - 添加账号
- `PUT /api/accounts/<id>` - 更新账号信息
- `DELETE /api/accounts/<id>` - 删除账号

### 模板消息接口
- `GET /api/templates` - 获取模板列表
- `POST /api/templates` - 创建模板
- `PUT /api/templates/<id>` - 更新模板
- `DELETE /api/templates/<id>` - 删除模板
- `GET /api/templates/wechat/<account_id>` - 从微信同步模板

### 消息推送接口
- `POST /api/push/immediate` - 立即推送消息
- `POST /api/push/scheduled` - 创建定时推送任务
- `GET /api/push/tasks` - 获取任务列表
- `GET /api/push/tasks/<task_id>` - 获取任务详情
- `GET /api/push/records` - 获取推送记录

### 自动回复接口
- `GET /api/reply/rules` - 获取回复规则列表
- `POST /api/reply/rules` - 创建回复规则
- `PUT /api/reply/rules/<id>` - 更新回复规则
- `DELETE /api/reply/rules/<id>` - 删除回复规则
- `GET /api/reply/messages` - 获取用户消息记录

## 微信回调配置

要在公众号上启用自动回复等功能，需要配置服务器回调：

1. 登录 **微信公众平台**。
2. 进入 **开发 -> 基本配置**。
3. 修改服务器配置：
   - **服务器地址 (URL)**: `http://你的域名/wechat/callback`
   - **令牌 (Token)**: 在系统后台的公众号管理中配置
   - **消息加密方式**: 根据需要选择 (系统支持明文/加密模式)
4. 启用配置后，系统将自动处理微信推送的消息和事件。

## 常见问题

### 1. 微信 Access Token 获取失败
- 检查 `.env` 中配置的 `AppID` 和 `AppSecret` 是否正确。
- 确保服务器网络可以访问微信 API (`api.weixin.qq.com`)。
- 确认公众号已认证（部分权限需要认证资质）。

### 2. 模板消息发送失败
- 确认模板 `ID` 与使用的公众号匹配。
- 检查模板变量 (`data`) 的格式是否与微信要求一致。
- 确保接收者的 `openid` 有效且属于该公众号。

### 3. 自动回复不生效
- 确认微信后台的服务器配置已启用。
- 检查回复规则中的关键词是否设置正确（注意大小写和空格）。
- 前往"自动回复"页面检查规则是否处于"启用"状态。

---

**版本**: 1.0.0  
**更新日期**: 2026-02-12