go-wxpush 开源微信推送服务技术分析

一、概述

1. 项目简介

go-wxpush 是一款基于 Golang 开发的开源微信模板消息推送服务，具有极轻量、易部署、免费额度充足等特点。该项目为开发者和运维人员提供了一种简单高效的消息通知解决方案。

2. 核心特性

A. 超轻量架构

Docker 镜像仅 2MB，占用资源极少，支持一键部署

B. 免费额度充足

每天提供 10 万次推送额度，满足个人和小团队需求

C. 原生体验

微信原生弹窗加声音提醒，消息不遗漏

D. 灵活部署

支持 Docker、直接下载编译文件、自行编译三种部署方式

3. 技术栈

• 开发语言：Golang
• 容器化：Docker
• 跨平台支持：Windows、macOS、Linux

二、系统架构

1. 工作原理

graph LR
    A[用户/API] -->|HTTP请求| B[go-wxpush服务]
    B -->|模板消息| C[微信公众平台]
    C -->|推送| D[微信客户端]
    E[监控脚本] -->|Webhook| B
    F[自动化任务] -->|API调用| B

2. 核心组件

A. HTTP 服务

监听指定端口（默认 5566），接收 GET 和 POST 请求

B. 消息封装

将请求参数封装为微信模板消息格式

C. 微信 API 调用

调用微信测试号接口完成消息推送

D. 多用户支持

支持配置多个接收用户，实现群发功能

三、部署方式

1. 准备工作

A. 获取微信测试号参数

1. 登录微信公众平台接口测试账号
2. 获取 appID 和 appsecret
3. 扫码关注测试号，获取 userid
4. 新增测试模板，获取 template_id

B. 模板格式要求

模板内容格式：内容: {{content.DATA}}

2. Docker 部署（推荐）

A. 拉取镜像

docker pull hezhizheng/go-wxpush:v4

B. 启动容器

docker run -it -d -p 5566:5566 --init --name go-wxpush4 hezhizheng/go-wxpush:v4 \
  -port "5566" \
  -title "测试标题" \
  -content "测试内容" \
  -appid "你的appid" \
  -secret "你的secret" \
  -userid "你的userid" \
  -template_id "你的模板ID" \
  -tz "Asia/Shanghai"

参数说明：

• -port：服务监听端口
• -title：消息标题
• -content：消息内容
• -appid：微信测试号 appID
• -secret：微信测试号 appsecret
• -userid：接收用户微信号
• -template_id：模板 ID
• -tz：时区设置

3. 直接部署

A. 下载编译文件

根据系统类型下载对应平台的可执行文件

B. 启动服务

./go-wxpush_windows_amd64.exe -port "5566" \
  -title "测试标题" \
  -content "测试内容" \
  -appid "你的appid" \
  -secret "你的secret" \
  -userid "你的userid" \
  -template_id "你的模板ID" \
  -base_url "https://push.hzz.cool"

4. 自行编译

A. 编译命令

gox -osarch="windows/amd64" -ldflags "-s -w" \
  -gcflags="all=-trimpath=${PWD}" \
  -asmflags="all=-trimpath=${PWD}"

B. 编译参数说明

• -osarch：目标平台架构
• -ldflags "-s -w"：去除调试信息，减小文件体积
• -gcflags/ -asmflags：去除路径信息

四、API 接口

1. GET 请求方式

A. 接口地址

GET http://127.0.0.1:5566/wxsend

B. 请求参数

C. 请求示例

http://127.0.0.1:5566/wxsend?appid=你的appid&secret=你的secret&userid=你的userid&template_id=你的模板ID&content=保持微笑，代码无bug！

2. POST 请求方式

A. 接口地址

POST http://127.0.0.1:5566/wxsend

B. 请求头

Content-Type: application/json

C. 请求体

{
  "title": "Webhook通知",
  "content": "这是一个通过POST请求发送的自动化消息"
}

D. cURL 示例

curl --location --request POST 'http://127.0.0.1:5566/wxsend' \
  --data-raw '{
    "title": "来自cURL的消息",
    "content": "自动化任务已完成。"
  }'

五、适用场景

1. 服务器监控告警

CPU、内存、磁盘使用率超标实时通知

2. 自动化任务提醒

脚本执行结果、数据同步完成通知

3. 个人日程提醒

重要事项、待办任务定时推送

4. 项目协作通知

代码提交、部署完成、Bug 反馈提醒

5. 爬虫任务通知

数据抓取完成、异常中断告警

六、技术优势分析

1. 轻量级设计

2MB Docker 镜像体现了 Go 语言编译后二进制文件的小巧优势，相比基于 JVM 或 Node.js 的同类方案，资源占用更低。

2. 跨平台支持

Go 语言的跨平台编译能力使得一个代码库可以编译出支持 Windows、macOS、Linux 等多个平台的可执行文件，降低了分发成本。

3. 部署灵活性

提供 Docker、编译文件、自行编译三种部署方式，满足不同用户的技术水平和部署环境需求。

4. 免费服务模式

公网服务 https://push.hzz.cool 为用户提供免部署选项，降低了使用门槛。

七、项目信息

1. 项目地址

GitHub：https://github.com/hezhizheng/go-wxpush

2. 相关项目

wxpushSkin：配合 go-wxpush 使用的消息皮肤切换工具

参考资料

1. 爆款开源工具！2MB 轻量微信推送服务，每天 10 万次免费额度够用了
2. go-wxpush GitHub 仓库