基于 Django、Celery 与 Windows UI Automation 的微信自动化管理工具

YuYuWechat 用于批量发送消息、定时发送消息和文件、检测聊天记录、记录执行日志并在异常时报警

V3 当前只支持 Windows 10/11、微信 4.1.8 和简体中文界面。需要控制微信 3.x 时，请切换到 V2 分支并使用 YuYuWechatV2_Server。

• 功能概览
• 系统结构
• 运行要求
• 部署 V3 服务端
• 服务端接口
• 部署管理客户端
• 配置自动化任务
• 自动领取红包和转账
• 日志与可靠性
• 开发与测试
• 常见问题

• 批量发送不同文本消息
• 使用五段式 Cron 表达式定时、循环发送消息
• 定时发送服务端本地文件
• 获取聊天记录并按时间分块检测关键词或正则表达式
• 获取聊天中的图片、视频以及临时下载链接
• 置顶或取消置顶指定聊天
• 手动领取红包、收取转账
• 监听未读单聊，自动领取红包和转账，并可发送感谢消息
• 服务端请求串行执行，避免多个请求同时抢占微信窗口
• 客户端任务日志、服务端请求日志、漏执行检测和邮件报警
• Django Admin 数据管理、数据库备份和自定义脚本

flowchart LR
    Browser["浏览器"] --> Client["YuYuWechatV2_Client<br/>Django 管理端"]
    Client --> Tasks["Celery 定时任务"]
    Client -->|"HTTP /wechat/*"| Server["YuYuWechatV3_Server"]
    Tasks -->|"HTTP /wechat/*"| Server
    Server --> Queue["单队列 / 单 Worker"]
    Queue --> Bridge["wechat_bridge"]
    Bridge --> Core["pywechat / pyweixin"]
    Core --> Weixin["PC 微信 4.1.6+"]
    Client --> PostgreSQL[(PostgreSQL)]
    Tasks --> Redis[(Redis)]

项目分为三个主要部分：

• YuYuWechatV3_Server：部署在安装微信的 Windows 电脑上，接收 HTTP 请求并执行微信 UI 自动化。
• YuYuWechatV2_Client：管理页面和定时任务中心，可部署在 Windows、macOS 或 Linux。
• pywechat/pyweixin：V3 使用的微信 4.x 自动化核心库。源码部署时必须与 V3 服务端保持同仓、同级目录结构。

V3 保留了服务端全局任务队列和互斥锁。即使多个客户端同时连接同一个服务端，微信操作也会按顺序执行。

• Windows 10 或 Windows 11
• Python 3.10+，推荐 Python 3.11
• PC 微信 4.1.8
• 微信界面语言为简体中文，即 zh-CN
• Windows 用户已经登录微信
• 桌面保持解锁，运行期间不能进入锁屏或睡眠状态

微信 4.x 可能默认隐藏部分 UI Automation 元素。根据 pywechat/Weixin4.0.md 的说明，建议首次配置时执行以下操作：

1. 完全退出微信。
2. 在启动微信前打开 Windows 讲述人，可使用 Win + Ctrl + Enter。
3. 启动微信并登录，保持讲述人运行约 5 分钟。
4. 关闭讲述人，然后再启动 YuYuWechat V3 服务端。
5. 在 Windows 电源设置中关闭自动睡眠、自动息屏和锁屏。

如果接口提示无法定位微信主窗口，先重复以上流程，而不是修改 UI 定位代码。

V3 建议用户在 Windows 上从 v3 分支源码自行编译。仓库已经提供 YuYuWechatV3_Server/build_pyinstaller_windows.bat，不需要手动安装和调用 PyInstaller。

编译前确认：

• 已安装 Python 3.10+，推荐 Python 3.11。
• 已完整获取仓库，pywechat 和 YuYuWechatV3_Server 必须是同级目录。
• 已关闭正在运行的 YuYuWechatV3_Server.exe。
• 电脑可以访问 Python 包索引，脚本需要安装构建依赖。

获取源码并编译：

git clone -b v3 https://github.com/xieyumc/YuYuWechat.git
cd YuYuWechat\YuYuWechatV3_Server
.\build_pyinstaller_windows.bat

脚本每次都会删除旧 dist。不要直接把生产数据库和日志长期放在源码的 dist 目录中；重新编译前请备份 dist\YuYuWechatV3_Server\db.sqlite3 和 logs，或者把编译结果复制到单独的运行目录。

编译成功后，进入产物目录并初始化：

cd dist\YuYuWechatV3_Server
.\YuYuWechatV3_Server.exe migrate
.\YuYuWechatV3_Server.exe createsuperuser

每次运行服务端前，都必须先完全退出微信，打开 Windows 讲述人，再启动并登录微信。确认微信已经登录后，最后启动 YuYuWechat V3 服务端。不要先登录微信再打开讲述人。

按上述顺序准备完成后，启动服务端：

.\YuYuWechatV3_Server.exe

不带参数启动时，服务端默认监听 0.0.0.0:8000。运行数据保存在 EXE 同目录的 db.sqlite3，滚动日志保存在 logs/server.log。

编译结果采用 PyInstaller 目录模式。部署或备份时必须复制整个 dist\YuYuWechatV3_Server 文件夹，不能只复制 EXE，因为程序依赖同目录的 _internal。

源码目录需要保持如下结构：

YuYuWechat/
├── pywechat/
└── YuYuWechatV3_Server/

在 Windows PowerShell 中运行：

cd YuYuWechatV3_Server
py -3.11 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -r requirements.txt
python manage.py migrate
python manage.py createsuperuser

运行服务端前，必须先完全退出微信，打开 Windows 讲述人，再启动并登录微信。确认微信已经登录后，最后执行服务端启动命令。不要先登录微信再打开讲述人。

python manage.py runserver 0.0.0.0:8000 --noreload

服务端会自动从仓库根目录的 pywechat 加载 pyweixin。如果移动了目录，服务端会返回 pywechat core library not found。

启动后访问：

• 服务端首页：http://127.0.0.1:8000/
• Django Admin：http://127.0.0.1:8000/admin/
• Swagger：http://127.0.0.1:8000/api/schema/swagger-ui/
• Redoc：http://127.0.0.1:8000/api/schema/redoc/

在 Admin 中打开 WeChatConfig。V3 只使用第一条配置记录，各字段含义如下：

服务端首页也提供自动领取状态、启停按钮、感谢消息和微信窗口尺寸配置。首页保存窗口尺寸时会关闭最大化模式，以保持微信单栏布局。

旧客户端依赖的接口路径、请求字段和主要响应结构保持兼容。完整字段和在线调试以 Swagger 为准。

聊天记录继续返回兼容旧客户端的三元组结构：

{
  "status": "success",
  "dialogs": [
    ["用户发送", "2026年7月10日 09:30", "你好"],
    ["用户发送图片", "2026年7月10日 09:31", "/wechat/media_cache/.../image.png"]
  ]
}

测试服务端连接：

Invoke-RestMethod -Uri http://127.0.0.1:8000/wechat/ping/

发送消息：

$body = @{name = "文件传输助手"; text = "YuYuWechat V3 测试消息"} | ConvertTo-Json
Invoke-RestMethod `
  -Uri http://127.0.0.1:8000/wechat/send_message/ `
  -Method Post `
  -ContentType "application/json; charset=utf-8" `
  -Body $body

V3 服务端接口当前没有 API Token 鉴权，并且微信操作接口允许跨站调用。请只在可信局域网中部署，使用 Windows 防火墙限制来源 IP，不要直接把 8000 端口暴露到公网。

V3 继续使用 YuYuWechatV2_Client。客户端负责页面、数据、Celery 定时任务和错误报警，服务端负责实际操作微信。

客户端 Compose 会启动以下服务：

• mona233/yuyuwechatv2_client:latest
• Redis，作为 Celery 消息队列
• PostgreSQL，保存客户端业务数据

准备 postgres_data 和 backups 目录后运行：

cd YuYuWechatV2_Client
docker compose up -d

第一次使用需要创建管理账号：

docker exec -it yuyuwechatv2_client python manage.py createsuperuser

如果通过 HTTPS 访问客户端，需要在 docker-compose.yml 的 CSRF_TRUSTED_ORIGINS 中加入实际域名。

源码运行需要 PostgreSQL 和 Redis。默认配置可在 YuYuWechatV2_Client/YuYuWechatV2_Client/settings.py 中查看或通过环境变量覆盖。

cd YuYuWechatV2_Client
python -m pip install -r requirements.txt
python manage.py migrate
python manage.py createsuperuser
python manage.py runserver 127.0.0.1:7500 --insecure

Celery Worker 和 Beat 需要分别运行：

celery -A YuYuWechatV2_Client worker --loglevel=info
celery -A YuYuWechatV2_Client beat --loglevel=info

打开 http://127.0.0.1:7500/ 登录，在首页填写 V3 服务端的 IP 和端口，例如：

192.168.50.10:8000

点击测试连接，成功后保存。客户端会继续调用兼容的 /wechat/* 接口，不需要修改现有任务数据。

访问客户端 Admin：http://127.0.0.1:7500/admin/。

创建 WechatUser 时，username 必须填写微信中能够准确搜索到的好友备注或群聊名称。V3 会优先匹配本地搜索结果，名称不准确可能导致找不到联系人。

ScheduledMessage 的关键字段：

• is_active：是否启用任务。
• user：关联的微信用户。
• text：发送内容。
• cron_expression：五段式 Cron 表达式，顺序为“分 时 日 月 周”。
• execution_count：剩余执行次数，0 表示不再执行。
• execution_skip：需要跳过的执行次数。

ScheduledFileMessage.file_path 必须是 V3 服务端 Windows 电脑上的绝对路径，而不是客户端容器中的路径。

常用 Cron 示例：

* * * * *       # 每分钟
0 * * * *       # 每小时整点
0 9 * * *       # 每天 09:00
0 9 * * 1       # 每周一 09:00
*/10 * * * *    # 每 10 分钟

MessageCheck 会调用 V3 的聊天记录接口，并根据关键词或正则表达式决定是否生成错误日志。可使用以下命令从现有定时消息批量生成检测任务：

cd YuYuWechatV2_Client
python manage.py generate_message_checks

生成规则可在 client_app/management/commands/generate_message_checks.py 中调整。

在客户端 Admin 中配置 EmailSettings：

• SMTP 主机和端口
• TLS 或 SSL
• 邮箱账号和授权码
• 发件人地址
• 逗号分隔的收件人列表

Celery 正常运行后，客户端会定期检查未发送的错误日志并发送报警邮件。

V3 可以扫描未读单聊，领取红包并收取转账。群聊红包会跳过，避免自动处理群聊资金消息。

使用方式：

1. 打开 V3 服务端首页 http://127.0.0.1:8000/。
2. 设置微信单栏窗口尺寸、检查间隔和感谢消息。
3. 点击“启用自动领取红包/转账”。
4. 在首页观察累计数量、最近扫描时间、最近事件和错误信息。

感谢消息支持以下占位符：

• {friend} 或 {name}：好友名称
• {payment_type}：红包或转账

也可以调用 /wechat/claim_payment/ 手动处理某位好友，或者调用 /wechat/run_auto_payment_once/ 扫描一次未读单聊。

资金相关 UI 自动化受微信界面变化、屏幕缩放和弹窗状态影响较大。首次使用必须先用测试账号和小额场景验证，不要把自动领取结果作为账务系统的唯一依据。

• 所有微信动作进入同一个服务端队列串行执行。
• 每次服务端请求记录 queued、running、success 或 failed 状态。
• 服务端记录请求参数、返回结果、错误、耗时和客户端 IP。
• 发布包运行日志保存在 logs/server.log，单文件最大 2 MB，保留 5 个轮转文件。
• 客户端会检测服务连通性、微信状态和定时任务遗漏，并将异常写入 ErrorLog。
• 发送文本后会读取聊天记录进行结果确认；失败时客户端会记录发送错误。

服务端日志可通过 Admin 或以下接口查看：

GET /wechat/request_logs/?limit=100&offset=0

cd YuYuWechatV3_Server
python manage.py check
python manage.py test wechat_app

服务端测试会使用 mock 验证桥接层、请求队列、媒体缓存、自动领取状态和旧接口兼容性；真实微信 UI 操作仍需要在 Windows 桌面环境手工验证。

必须在 Windows 上构建，并保持 pywechat 与 YuYuWechatV3_Server 为同级目录。直接运行仓库提供的构建脚本：

cd YuYuWechatV3_Server
.\build_pyinstaller_windows.bat

脚本会自动创建 .venv-pyinstaller、安装依赖、检查 Windows 自动化模块并调用 YuYuWechatV3_Server.spec。构建产物位于 dist/YuYuWechatV3_Server/，发布时应压缩整个目录，而不是只上传 EXE。

cd YuYuWechatV2_Client
python manage.py test client_app

客户端默认使用 PostgreSQL，执行测试前需要准备可连接的测试数据库。

源码部署时，确认 pywechat/ 与 YuYuWechatV3_Server/ 位于同一个仓库根目录。批处理生成的编译产物已经内置核心库，不需要额外复制。

检查 WeChatConfig.path，微信 4.x 的可执行文件名是 Weixin.exe，不是旧版的 WeChat.exe。

确认微信版本、简体中文界面、登录状态和桌面解锁状态。完全退出微信后，按前文流程先启动讲述人，再登录微信。

file_path 必须存在于运行 V3 服务端的 Windows 电脑上。客户端部署在 Docker 或其他机器时，不能直接使用客户端本地路径。

微信 UI 操作为全局串行。前一个任务未完成时，后续请求会排队，这是为避免发错联系人而设计的。

媒体文件保存在系统临时目录，默认 6 小时后清理。需要长期保存时，应在链接有效期内下载到自己的存储中。

• v3 分支：微信 4.1.6+，使用 YuYuWechatV3_Server 和 pyweixin。
• V2 分支：微信 3.x，使用原 YuYuWechatV2_Server。
• 管理客户端目前仍为 YuYuWechatV2_Client，两套服务端接口保持兼容。

• pywechat：V3 的微信 4.x UI 自动化核心。
• easyChat：V2 服务端早期核心实现。
• NodeSupport：项目赞助支持。

本项目仅用于 UI Automation 技术交流和个人学习。请遵守微信软件许可、所在地法律法规和数据隐私要求，不得用于骚扰、欺诈、非法资金操作或其他违法用途。UI 自动化无法保证在所有微信版本、屏幕缩放和系统环境中稳定运行，使用者应自行验证并承担使用风险。