Skip to content

About

搭建专属于你的消息推送服务,支持多种消息推送方式,支持 Markdown,基于 Golang 仅单可执行文件,开箱即用

Resources

Stars

4 stars

Watchers

0 watching

Forks

 
 

Repository files navigation

LiuShen Pusher

清羽飞扬自建消息推送服务。项目支持多渠道消息推送、Webhook 转发、通道管理、消息记录、通用 OAuth2 登录、极验校验、页脚备案信息、全局 CSS / JS 注入,以及 Webhook 字段提取后的文本处理。

功能概览

  • 多渠道推送:邮件、企业微信、飞书、钉钉、Bark、Telegram、Discord、WebSocket 客户端、腾讯云告警、自定义通道、通道组等。
  • 推送 API:兼容常见消息推送服务调用方式,支持 GET、POST Form、POST JSON。
  • Webhook 编排:从外部请求 JSON 中提取字段,经过文本处理后构建成消息并推送到指定通道。
  • 管理后台:用户、通道、消息、Webhook、系统设置统一管理。
  • 登录注册:密码登录注册、邮箱验证、通用 OAuth2 登录注册。
  • 安全校验:支持极验行为验证。
  • 站点定制:公告、关于页、首页 iframe、页脚 HTML、ICP 备案、公安备案、全局 CSS / JS 注入。
  • 数据库:默认使用纯 Go SQLite 驱动,不依赖 CGO;也支持通过 SQL_DSN 使用 MySQL。

快速开始

默认管理员账号:

  • 用户名:root
  • 密码:123456

首次登录后请立即在「设置 -> 个人设置」中修改默认密码。

本地开发

环境要求

  • Go 1.18+
  • Node.js 18+,推荐与 Dockerfile 保持一致使用 Node 20
  • npm 或 yarn

项目后端会通过 go:embed 嵌入 web/build,因此直接运行后端前必须先至少构建一次前端,否则会出现:

pattern web/build/index.html: no matching files found

安装依赖

cd web
npm install
cd ..
go mod download

前后端分离开发

启动后端:

PowerShell:

$env:GIN_MODE="debug"
$env:PORT="3000"
go run .

Linux / macOS:

GIN_MODE=debug PORT=3000 go run .

启动前端开发服务:

cd web
npm start

前端开发服务器默认通过 web/package.json 中的 proxy 转发 API 到 http://localhost:3000。

单进程开发或测试运行

如果你希望只启动 Go 服务并访问嵌入式前端:

cd web
npm run build
cd ..
go run .

访问:

http://localhost:3000

常用验证命令

cd web
npm run build
cd ..
go test ./...

注意:go test ./... 依赖 web/build 存在。不要把 npm run build 和 go test ./... 并行执行,因为前端构建会刷新 build 目录,可能导致 Go embed 检查时找不到文件。

部署

Docker Compose 部署

推荐使用 Docker Compose:

version: "3"

services:
  message-pusher:
    image: your-dockerhub-namespace/message-pusher:latest
    restart: unless-stopped
    ports:
      - 3000:3000
    environment:
      - TZ=Asia/Shanghai
      - SESSION_SECRET=please-change-me
    volumes:
      - ./data:/data
      - /etc/localtime:/etc/localtime:ro

请将 your-dockerhub-namespace/message-pusher:latest 替换为你实际推送到 Docker Hub 的镜像名,例如 liushen/message-pusher:latest。

启动:

docker compose up -d

默认 SQLite 数据库会保存在容器工作目录 /data 下,示例中映射到宿主机 ./data。

Docker 命令部署

docker run -d \
  --restart unless-stopped \
  --name message-pusher \
  -p 3000:3000 \
  -e TZ=Asia/Shanghai \
  -e SESSION_SECRET=please-change-me \
  -v "$PWD/data:/data" \
  your-dockerhub-namespace/message-pusher:latest

同样需要把镜像名替换为你自己的 Docker Hub 镜像。

本地构建 Docker 镜像

Dockerfile 会读取根目录的 VERSION 文件写入前端和后端版本号。如果本地没有该文件,可以先创建一个:

echo v0.0.0 > VERSION
docker build -t message-pusher:local .

运行本地镜像:

docker run -d \
  --restart unless-stopped \
  --name message-pusher \
  -p 3000:3000 \
  -e SESSION_SECRET=please-change-me \
  -v "$PWD/data:/data" \
  message-pusher:local

手动部署

git clone https://github.com/LiuShen-Fork/Message-Pusher.git
cd Message-Pusher

cd web
npm install
npm run build
cd ..

go mod download
go build -ldflags "-s -w" -o message-pusher

运行:

./message-pusher --port 3000 --log-dir ./logs

Windows PowerShell:

$env:PORT="3000"
.\message-pusher.exe --log-dir .\logs

Nginx 反向代理

server {
    server_name push.example.com;

    location / {
        client_max_body_size 64m;
        proxy_http_version 1.1;
        proxy_pass http://127.0.0.1:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $remote_addr;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_read_timeout 300s;
        proxy_send_timeout 300s;
    }
}

WebSocket 客户端推送依赖长连接,建议保留 proxy_read_timeout 和 proxy_send_timeout。

配置项

环境变量

变量 说明
PORT 服务监听端口,默认 3000。
GIN_MODE Gin 运行模式。开发时可设为 debug,生产默认 release。
SESSION_SECRET 会话密钥。生产环境必须固定配置,否则重启后登录态会失效。
SQLITE_PATH SQLite 数据库文件路径,默认 message-pusher.db。Docker 中建议使用默认路径并挂载 /data。
SQL_DSN MySQL DSN。设置后使用 MySQL,不再使用 SQLite。
REDIS_CONN_STRING Redis 连接字符串。设置后请求频率限制使用 Redis 存储。

MySQL 示例:

SQL_DSN='root:password@tcp(127.0.0.1:3306)/message_pusher?charset=utf8mb4&parseTime=True&loc=Local'

Redis 示例:

REDIS_CONN_STRING='redis://default:password@127.0.0.1:6379/0'

命令行参数

参数 说明
--port <port> 指定监听端口,默认 3000。
--log-dir <dir> 指定日志目录。未设置时不写入日志文件。
--version 输出版本号并退出。
--help 输出帮助信息并退出。

后台系统设置

使用 root 登录后进入「设置 -> 系统设置」:

  • 服务器地址:请填写外部可访问地址,例如 https://push.example.com。OAuth2 回调、邮件链接等会依赖该地址。
  • 登录与验证:控制密码登录、密码注册、邮箱验证、新用户注册、OAuth2、极验。
  • OAuth2 通用登录:配置显示名称、Client ID、Client Secret、授权地址、令牌地址、用户信息地址、Scopes、用户字段映射。
  • 极验校验:配置极验验证 ID 与极验密钥。
  • SMTP:配置邮件发送,用于邮箱验证、密码重置、邮件通道。
  • 页脚与合规信息:配置自定义页脚 HTML、ICP 备案号、公安备案号。
  • 全局 CSS / JS:注入站点级 CSS 或 JS,可用于统计、样式微调、第三方脚本。

OAuth2 登录配置

系统使用标准 OAuth2 Authorization Code 流程。

后台回调地址显示为:

https://你的域名/oauth/oauth2

OAuth2 服务端需要配置该地址为 Redirect URI / Callback URL。

常见字段映射:

配置 说明
用户 ID 字段 用户信息接口返回 JSON 中的唯一 ID 字段,例如 id、sub。
用户名字段 用户名字段,例如 login、username、preferred_username。
显示名字段 显示名称字段,例如 name、nickname。
邮箱字段 邮箱字段,例如 email。

当前字段映射读取用户信息 JSON 的顶层字段。如果你的 OAuth2 用户信息是嵌套结构,需要先在身份提供方调整 userinfo 返回,或后续扩展字段路径解析。

极验配置

后台填写:

  • 极验验证 ID
  • 极验密钥

启用后,注册、发送邮箱验证码、密码重置会要求完成极验。前端使用极验 v4 脚本,后端会向极验服务端进行二次校验。

页脚、备案与全局注入

备案链接规则

  • ICP 备案号链接固定指向 https://beian.miit.gov.cn/。
  • 公安备案号会提取备案号中的数字,生成:
http://www.beian.gov.cn/portal/registerSystemInfo?recordcode=<备案号数字>

全局 CSS / JS

全局 CSS 会写入页面 <style>;全局 JS 会写入页面 <script>。该功能适合:

  • 添加统计代码
  • 修改少量样式
  • 接入第三方客服或监控脚本

请只填写可信代码。全局 JS 拥有页面执行权限,错误脚本可能影响整个后台。

Webhook 编排

Webhook 用于把外部系统推送来的 JSON 转换为本系统消息。

入口地址:

POST https://你的域名/webhook/<webhook-link>

Webhook 配置分三步执行:

  1. extract_rule:从原始 JSON 中提取字段。
  2. process_rule:对提取后的变量进行文本处理。
  3. construct_rule:用处理后的变量构建消息字段。

提取规则

extract_rule 是 JSON 对象。键是模板变量名,值是 gjson 路径。

示例请求:

{
  "aaa": {
    "bbb": "  ERROR: user 123 failed\nretry later  "
  },
  "url": "https://example.com/detail/123"
}

提取规则:

{
  "description": "aaa.bbb",
  "url": "url"
}

文本处理规则

process_rule 是 JSON 对象。键是提取出的变量名,值是处理步骤数组。步骤会按顺序执行。

支持的处理类型:

type 参数 说明
regex_replace pattern, replacement 正则替换。
replace pattern, replacement 普通字符串替换。
trim trim_cutset 可选 去除首尾空白;设置 trim_cutset 时按指定字符集裁剪。
lower 无 转小写。
upper 无 转大写。
prefix prefix 添加前缀。
suffix suffix 添加后缀。

示例:

{
  "description": [
    {
      "type": "regex_replace",
      "pattern": "\\s+",
      "replacement": " "
    },
    {
      "type": "regex_replace",
      "pattern": "user (\\d+)",
      "replacement": "用户#$1"
    },
    {
      "type": "trim"
    },
    {
      "type": "prefix",
      "prefix": "告警:"
    }
  ]
}

处理结果:

告警:ERROR: 用户#123 failed retry later

构建规则

construct_rule 是最终消息模板,可使用 $变量名 引用处理后的变量。

{
  "title": "外部系统告警",
  "description": "$description",
  "content": "详情:$description",
  "url": "$url"
}

最终会构建为系统消息并投递到 Webhook 绑定的通道。

推送 API

GET

https://你的域名/push/<username>?title=<标题>&description=<描述>&content=<内容>&channel=<通道名>&token=<推送token>

POST JSON

curl -X POST "https://你的域名/push/<username>" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "标题",
    "description": "描述",
    "content": "**Markdown 内容**",
    "channel": "default",
    "token": "your-token"
  }'

POST Form

curl -X POST "https://你的域名/push/<username>" \
  -d "title=标题" \
  -d "description=描述" \
  -d "content=内容" \
  -d "token=your-token"

常用字段:

字段 说明
title 标题,部分通道可能忽略。
description / desp 描述文本。
content 正文内容,部分通道支持 Markdown。
url 消息链接。
channel 通道名称,留空使用默认通道。
token 推送鉴权 token,也可通过 HTTP Authorization 头传入。
to 指定接收用户,支持 @all 或 user1|user2。
async 设置为 true 时异步发送。
render_mode markdown、raw 或 code。

GitHub Actions 构建 Docker 镜像

项目包含 .github/workflows/docker-image.yml,用于构建并推送 Docker Hub 镜像。

触发方式:

  • 推送任意 Git tag,例如 v1.0.0。
  • 在 GitHub Actions 页面手动运行 workflow,并填写 version,例如 v1.0.0。

需要配置的 GitHub Secrets:

名称 说明
DOCKERHUB_USERNAME Docker Hub 用户名。
DOCKERHUB_TOKEN Docker Hub Access Token,不建议使用账号密码。

可选 GitHub Variables:

名称 说明
DOCKERHUB_IMAGE 镜像名,例如 liushen/message-pusher。不配置时默认使用 ${DOCKERHUB_USERNAME}/message-pusher。

构建结果会推送两个 tag:

  • latest
  • 当前 Git tag 或手动输入的 version

示例发布:

git tag v1.0.0
git push origin v1.0.0

更新

Docker Compose:

docker compose pull
docker compose up -d

Docker run:

docker pull your-dockerhub-namespace/message-pusher:latest
docker stop message-pusher
docker rm message-pusher
docker run -d --restart unless-stopped --name message-pusher -p 3000:3000 -v "$PWD/data:/data" your-dockerhub-namespace/message-pusher:latest

手动部署:

git pull
cd web
npm install
npm run build
cd ..
go build -ldflags "-s -w" -o message-pusher

重启服务前请备份数据库文件。

常见问题

Windows 下 SQLite 报 CGO / gcc 错误怎么办?

当前项目已使用纯 Go SQLite 驱动 github.com/glebarez/sqlite,不依赖 CGO。正常情况下不需要安装 gcc,也不需要设置 CGO_ENABLED=1。

如果你仍看到 go-sqlite3 requires cgo,说明依赖或代码没有更新到当前版本,请执行:

go mod tidy
go clean -cache
go test ./...

go run 或 go test 提示 web/build/index.html 不存在?

先构建前端:

cd web
npm run build
cd ..
go run .

Docker 容器中数据在哪里?

默认工作目录是 /data。SQLite 数据库会写入该目录,部署时请挂载持久化卷。

如何切换到 MySQL?

设置 SQL_DSN 环境变量即可。首次启动会自动迁移表结构。

许可证

本项目遵循 MIT License。

About

搭建专属于你的消息推送服务,支持多种消息推送方式,支持 Markdown,基于 Golang 仅单可执行文件,开箱即用

Resources

Stars

4 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages