aPush 使用指南

自托管推送中转站 · 从任意入口，抵达任意终端。本指南覆盖安装、接入、配置与排障全流程。

1工作原理

来源 Source→字段解析→策略匹配→字段改写→模板渲染→渠道投递 ×N

解析：自动识别 title / content / appName / url 等字段的几十种常见别名（subject、body、msg、desp…），无法识别的字段全部归入 metadata，模板里用 {{metadata.xxx}} 取用。
匹配：按策略条件（来源、关键词、正则、时间段、星期）判断放行或拦截；多条策略命中时取第一条。
投递：命中后向策略勾选的每个渠道各推一份，每次投递独立记录成败与耗时，流转记录页可查。

2安装部署

前置要求：Node.js ≥ 18、MySQL 8.x

git clone https://github.com/5hux1n/apush.git
cd apush
npm install
cp .env.example .env      # 编辑数据库等配置
node install.js           # 初始化向导：建库建表、设置面板密码
npm start                 # 启动，默认端口 25717

.env 变量	默认	说明
`PORT`	25717	服务端口
`AUTH_PASSWORD`	空	管理面板密码。留空 = 不设防，公网部署务必设置
`DB_HOST` / `DB_PORT`	127.0.0.1 : 3306	MySQL 地址
`DB_NAME` / `DB_USER` / `DB_PASS`	—	库名与账号
`BARK_SERVER`	api.day.app	全局 Bark 服务器（渠道里留空时用它）

生产守护与反代

npm i -g pm2
pm2 start server.js --name apush && pm2 save

Nginx / Caddy / frp 反代 443 → 127.0.0.1:25717 即可，无特殊 header 要求；注意把 proxy_read_timeout 调到 ≥ 60s（界面用长轮询，太短会频繁重连）。

3登录管理面板

浏览器打开 http://<服务器IP>:25717/：

设置了 AUTH_PASSWORD 时输入密码登录。密码只用于换取会话令牌（服务端内存，24h 有效），后续请求经 x-auth-token 头携带，不重复传输密码。
连续错 5 次锁定 10 分钟（防爆破）。
四个菜单：策略配置 · 通道来源 · 流转记录 · 系统日志。

4四个核心概念

概念	作用	关键字段
来源 Source	消息入口，决定 Webhook 路径与解析方式	`path`、`auth_token`、`parser_mode`（auto/raw）
渠道 Channel	消息出口，8 种类型	`name`、`type`、`config`、`template`
策略 Rule	哪些消息 → 发到哪些渠道 → 长什么样	关键词、时间窗、目标渠道、渠道模板、rewrite
模板 Template	控制最终推送排版	`{{变量}}` 占位符

⚠️ 没有启用中的策略命中时，消息会被直接拦截（blocked），一条也不发。新装完请先建策略再测试。

5接收消息（Webhook 接口）

统一入口（GET / POST 均可，自动处理 CORS 预检）：/api/webhook（默认来源）或 /api/webhook/<path>

# ① Query 参数（iPhone 快捷指令 GET 场景）
curl "http://IP:25717/api/webhook/iphone?title=你好&content=正文&appName=测试&token=***"

# ② JSON body（脚本 / 服务告警场景）
curl -X POST http://IP:25717/api/webhook \
  -H "Content-Type: application/json" \
  -d '{"title":"磁盘告警","content":"使用率 92%","appName":"Prometheus"}'

# ③ 纯文本（来源 parser_mode = raw 时，整段进 message）
curl -X POST http://IP:25717/api/webhook/nas -H "Content-Type: text/plain" -d "任意格式原文"

鉴权：来源设置了 auth_token 时，三处任选：body.token → ?token=*** → Authorization: Bearer <token>（按此优先级）。不符返回 403 token 无效。

响应：立即返回 {success, matched_rule, action, delivered, failed, deliveries[]} —— 投递明细同步可见，无需查库。

6渠道配置速查

类型	config 字段	要点
`bark`	`server?`, `bark_key`	server 留空用 `BARK_SERVER`；可配 JSON 模板扩展 group / sound / icon / level
`wecom` 企微应用	`corpid`, `corpsecret`, `agentid`, `touser?`, `wecom_msgtype`	必配可信企业 IP 白名单，否则 60020；msgtype：text / markdown / textcard / news
`wecom-bot` 群机器人	`webhook_key`, `wecom_msgtype`	群 Webhook URL 中 `key=` 后面那段
`dingtalk`	`webhook_token`, `secret?`, `atMobiles?`, `msgtype`	机器人开「加签」才填 secret（自动签名）；开「关键词」则消息必须含关键词
`feishu`	`webhook_url`, `secret?`	飞书群自定义机器人
`tg`	`bot_token`, `chat_id`	chat_id 支持 `@username` 或数字 ID
`email`	`host`, `port`, `secure`, `auth.user`, `auth.pass`, `to`	465 → secure:true；587 → false（自动 STARTTLS）；pass 用授权码非登录密码
`webhook` 下游	`url`, `method?`, `headers?`	把消息按模板 POST 给任何系统（n8n / 自建 API 等）

💡 渠道卡片的「测试」按钮会真实发一条样例消息（占配额，钉钉/企微注意频控）。想零副作用预览所有渠道的渲染结果，去演示站用「🧪 模拟推送」。

7策略与模板

匹配条件（全部为「与」关系）

关键词：多个词按 AND / OR 组合；勾选正则后每个词按正则匹配（对 appName + title + content 拼接文本做不区分大小写匹配）
时间窗（HH:MM~HH:MM）+ 生效星期（0~6）
来源限定：* 全部来源，或指定来源

rewrite 规则（提取 / 清洗）

[{ "source": "message", "match": ".*?(\\d{6}).*", "replace": "$1",
   "target": "message", "use_regex": true, "use_regex_flags": "is" }]

含义：从正文提取 6 位数字并只把数字写回 message —— 配合 Bark 模板实现「验证码短信只推 6 位码」。字段可填内置名（title/content/message/url/metadata.xxx），也可填解析前的原始 key。多条规则按序执行。

模板变量与优先级

{{title}} {{content}} {{message}}（content 别名） {{app_name}} {{url}} {{source}} {{time}} {{metadata.任意字段}}

渲染优先级：策略渠道模板覆盖 → 渠道自身模板 → 内置默认模板（按渠道类型与 msgtype 自动选择版式）。

8典型接入示例

📱 iPhone 短信验证码 → Bark 只推 6 位码

来源：path=iphone，auto 解析，设 auth_token
渠道：Bark（App 内复制 key）

策略：来源限定 iphone + 关键词「验证码」→ 目标 Bark；rewrite 提取 6 位数字；Bark 渠道模板（JSON）：

{"title":"🔐 {{app_name}} 验证码","body":"{{content}}","group":"验证码",
 "sound":"bell","level":"timeSensitive","isArchive":1}

快捷指令：自动化触发「收到包含"验证码"的信息」→ 动作「获取 URL 内容」：
```
http://IP:25717/api/webhook/iphone?title=【{{文本}}】&content={{文本}}&appName=信息&token=***
```

🖥️ 服务器告警 → 钉钉 + Telegram 双发

建两条渠道 + 一条策略：来源 *、关键词「告警」（或正则 deploy|部署|构建 做 CI 通知），勾选两个渠道即可分流。

🔗 转发到下游系统

渠道类型选 Webhook，模板写任意 JSON 字符串，收到的消息就会按该格式 POST 给 n8n / 自建 API / 任何支持 Webhook 的平台。

9常见问题 FAQ

界面显示「离线」？ 长轮询断了。检查服务存活与反代超时（proxy_read_timeout ≥ 60s）。
消息全被拦截？ 最常见：没有启用中的策略，或关键词/来源/时间窗不匹配。到「流转记录」点开消息看明细，或在演示站用「🧪 模拟推送」重放观察匹配追踪。
企业微信收不到？ 应用「可信企业 IP」白名单必配；60020 即 IP 不在白名单。
钉钉 310000？ 安全设置要对齐：加签 → 渠道填 secret；关键词 → 消息必须含该词。
TG 429/430？ 限流，降低频率（默认约 20 条/分钟）。
忘记密码？ AUTH_PASSWORD 是唯一凭据，改 .env 重启即可，数据库不存密码。

🧪 想先零风险体验全部功能？演示站 apush.me：免注册、全站只读、内置模拟推送沙箱。