WePush Next 对外使用指南

WePush Next 是由用户自行下载、安装、部署和运维的开源产品，不依赖官方公共 SaaS、账号注册、计费订阅或云 KMS/Secret Manager。数据、密钥和运行环境均由用户掌控；完整定位和后续计划见《产品目标、边界与路线图》。

本文面向第一次下载和使用 WePush Next 的用户，适用于 1.1.0 稳定自部署版。

1.1.0 提供明确的 1.x API、配置、数据库和 Agent 协议兼容承诺。Desktop 与发行包未使用商业代码签名；请只从项目 GitHub Release 下载，并在运行前校验 SHA256SUMS。详见《兼容性策略》和 UNSIGNED-NOTICE.md。

1. 先选择需要的组件

WePush Next 由多个可以独立使用的组件组成：

组件	用途	第一次体验是否需要
Service	保存配置和运行数据，提供 WebUI、OpenAPI 与 Service API，并可在本机执行任务	必需
WebUI	浏览器中的可视化配置、运行中心、动态 API 文档	已包含在 Service 发行包中
Desktop UI	Electron 桌面管理界面，连接并管理已安装的本机 `127.0.0.1:18990` Service	可选
Agent	从 Service 接收任务并在独立节点执行，适合远程或分布式部署	本地体验不需要
Remote Java SDK	供其他 Java 应用通过 Service API 集成 WePush	按需，`1.1.0` 附件已包含
Embedded Java SDK	在 Java 应用进程内直接装配 Engine 和 Provider，不需要 Service	按需，`1.1.0` 附件已包含
Core / Engine	Service 与 Agent 内部的执行引擎	不需要单独安装

发行包的统一脚本负责安装 Standalone Service；Desktop UI 不重复内嵌 Service，但可以检测、启动、停止已安装的本机 Service，读取日志和生成脱敏诊断。

Classic 与 Next 是彼此独立的两条产品线。Classic 继续提供成熟的桌面批量推送能力；Next 当前内置 HTTP、SMTP Email、飞书/钉钉/企微机器人、阿里云短信、微信公众号、小程序和企业微信应用消息。两者没有自动迁移或共享数据要求，可以并行安装和使用。

2. 下载与系统要求

官方下载页：

WePush Next 1.1.0 Stable

发行附件：

文件	内容或平台
`wepush-next-1.1.0-linux-<arch>.tar.gz`	Linux 完整包，内含 Java Runtime，推荐首次安装
`wepush-next-1.1.0-macos-<arch>.zip`	macOS 完整包，内含 Java Runtime，推荐首次安装
`wepush-next-1.1.0-windows-<arch>.zip`	Windows 完整包，内含 Java Runtime 和离线 WinSW
`wepush-next-1.1.0.tar.gz` / `.zip`	使用系统 Java 21+ 的精简便携包；内容不含 Java Runtime
`wepush-next-desktop-1.1.0-<os>-<arch>.*`	对应平台的 Desktop 管理界面
`wepush-next-java-sdk-1.1.0.zip`	Remote Java SDK、Embedded Java SDK 及其 POM/JAR 依赖闭包
`wepush-provider-{cmpp,smgp,sgip,smpp}-1.1.0.zip`	可选运营商短信 Agent 签名插件；各自附带 `.sha256`
`wepush-provider-trusted-key-1.1.0.env`	官方插件签名 Key ID/公钥的 Agent 环境配置；附带 `.sha256` 并列入统一 `SHA256SUMS`
`SHA256SUMS`	全部附件的 SHA-256
`wepush-next-1.1.0-sbom.cdx.json`	CycloneDX SBOM

完整包运行 Service/Agent 不要求预装 Java。精简包、从源码构建和任一种 Java SDK 需要 Java 21 或更高版本：

java -version

发行工作流按目标 Runner 架构生成附件；文件名中的 <arch> 以 Release 实际列出的 x64 或 arm64 为准。

校验下载文件

下载 SHA256SUMS 后，计算目标文件的 SHA-256，并与其中同名行比较：

Linux：

sha256sum wepush-next-1.1.0.tar.gz
grep 'wepush-next-1.1.0.tar.gz$' SHA256SUMS

macOS：

shasum -a 256 wepush-next-1.1.0.tar.gz
grep 'wepush-next-1.1.0.tar.gz$' SHA256SUMS

Windows PowerShell：

Get-FileHash .\wepush-next-1.1.0.zip -Algorithm SHA256
Select-String -Path .\SHA256SUMS -Pattern 'wepush-next-1.1.0.zip$'

两个值必须完全一致。Desktop 包也使用相同方法校验。

3. 五分钟安装：Standalone

Standalone 默认只监听 127.0.0.1:18990，使用 SQLite、本地 Artifact Store 和内嵌 Engine，不需要 PostgreSQL、对象存储或 Agent。

下载当前操作系统的完整包并解压。统一入口默认只安装 Standalone Service；安装末尾会验证 Readiness、数据库迁移版本和不会访问网络的 Provider Dry Run。

Linux

tar -xzf wepush-next-1.1.0-linux-x64.tar.gz
cd wepush-next-1.1.0
sudo ./install/install.sh

macOS

ditto -x -k wepush-next-1.1.0-macos-arm64.zip .
cd wepush-next-1.1.0
sudo ./install/install.sh

Windows PowerShell

Expand-Archive .\wepush-next-1.1.0-windows-x64.zip .\wepush-next
Set-Location .\wepush-next\wepush-next-1.1.0
Set-ExecutionPolicy -Scope Process Bypass
& .\install\install.ps1

安装完成后打开：

WebUI：http://127.0.0.1:18990/
健康检查：http://127.0.0.1:18990/actuator/health/readiness
OpenAPI：http://127.0.0.1:18990/openapi.yaml

也可以在另一个终端验证：

curl --fail http://127.0.0.1:18990/actuator/health/readiness
curl --fail http://127.0.0.1:18990/api/v1/system/info

需要便携运行而不安装系统服务时，Linux/macOS 在解压目录执行 ./bin/wepush-service；Windows 执行 install\windows\run-service.ps1。便携模式应从解压目录启动，使默认 .local 数据与该目录保持在一起。完整包优先使用内含 Runtime，精简包自动使用系统 Java。

4. 可选：使用 Desktop UI

先按上一节安装 Service，再解压对应平台的 Desktop 附件：

Linux：运行 wepush-next-desktop-1.1.0-linux-x64/WePush Next/wepush-next。
macOS：打开 wepush-next-desktop-1.1.0-macos-arm64/WePush Next.app。
Windows：运行 wepush-next-desktop-1.1.0-windows-x64\WePush Next\WePush Next.exe。

Desktop 会连接本机 http://127.0.0.1:18990。设置页可以检测、启动、停止 Service，读取最近日志并生成不包含 Token/Secret 的诊断；涉及系统服务或插件目录的写操作会请求操作系统管理员授权。

Desktop 的 API Token 通过 Electron safeStorage 写入操作系统原生安全存储；如果 Linux 桌面没有可用 Keyring，Desktop 会拒绝以弱后端持久化。浏览器 WebUI 默认只写 sessionStorage，关闭标签页后即清除，不再使用长期 localStorage。

由于发行包没有商业签名，macOS Gatekeeper 或 Windows SmartScreen 可能显示未知开发者/发布者。只有在文件来自项目 Release 且 SHA-256 校验一致时，才使用系统提供的“打开”流程；不要全局关闭系统安全能力。

不想安装 Desktop 时，直接使用浏览器 WebUI 即可，两种 UI 连接的是同一套 Service API 和数据。

4.1 `1.1.0` 设置与主题

顶部主题选择支持亮色、暗色和跟随系统；选择保存在本地浏览器偏好中，不会上传。
系统管理员可在设置页为当前 Workspace 设置 Agent、活动 Run、总发送并发、Artifact 容量和默认保留期。降低上限不会自动删除资源；超过新上限时，新增操作会给出可诊断拒绝。
“生成诊断包”会由 Service 返回结构化脱敏 ZIP；仍应把它视为内部运维资料，不要公开上传。
“检查版本”只有点击时才查询 GitHub 的稳定 next-v* Release，不会后台检查、自动下载或发送遥测。
Account 的认证熔断面板显示跨 Run 认证失败和冷却状态。先修正 Secret/凭据，再由管理员复位；网络失败、限流或 Recipient 错误不会计入认证熔断。
运营商短信使用 Release 中独立的 CMPP/SMGP/SGIP/SMPP 签名插件。安装前校验 SHA256SUMS 并配置发行公钥；这些插件当前处理主动提交和长短信，不处理状态报告或上行短信。

5. 完成第一次安全 Dry Run

下面的流程只验证 Account → Message → Audience → Job → Engine → Provider 全链路。HTTP Provider 的 Dry Run 不会向配置的远端地址发送 HTTP 请求。

5.1 创建 HTTP 账号

打开 Providers。
选择内置的 HTTP Provider。
账号名称填写 Preview HTTP。
baseUrl 填写 https://example.com。
connectTimeout 保持 PT5S。
allowPrivateAddresses 保持关闭，auth 保持 NONE 或不配置。
点击“保存账号”。

只有明确受信的内部 HTTP 服务才应启用 allowPrivateAddresses。默认关闭可避免任务访问本机、局域网和云元数据地址。

5.2 创建消息

进入“消息”，选择 HTTP Provider，并填写：

名称：Preview message
方法：POST
路径：/messages
Headers：{"Content-Type":"application/json"}
Body Template：

{
  "name": "",
  "mobile": ""
}

模板变量使用 ``，运行时从每个 Recipient 的 fields 中取值。保存消息后会形成不可变修订。

5.3 创建受众

进入“受众”，新建 UTF-8 CSV 文件：

itemId,mobile,name
alice,13000000000,Alice
bob,13100000000,Bob

填写受众名称并选择 CSV；TXT 也受支持，每个非空行作为一条 Recipient。
选择 itemId 列，把 mobile、name 映射到同名 Recipient 字段。
点击“上传并预览”，核对总行数、接受数、错误数和重复数。
有错误时先下载错误行 CSV；重复 itemId 只保留首次出现的记录。
点击“确认并生成 Snapshot”。

itemId 应在同一受众中保持稳定且唯一；字段必须覆盖消息模板引用的变量。更新已有受众时请选择目标受众，提交后会生成新的不可变 Snapshot，不会改变既有 Run。

5.4 创建任务并运行

进入“任务与调度”。
选择刚创建的账号、消息和受众。
保持较小的目标并发，例如 2。
保存任务。
在右侧任务卡片点击 Dry Run。
进入“运行中心”，查看状态、计数、事件和每条 Recipient 的结果。

正常情况下，两条结果会以 Provider Code DRY_RUN 成功完成。该过程不会请求 example.com/messages。

6. 正式 HTTP 发送

完成 Dry Run 后，在任务卡片点击“正式发送”。界面会先展示 Provider/版本、账号、受众及数量、完整策略、目标并发、限速和预计执行规模。只有再次点击“我已核对，开始发送”才会创建真实 Run；确认令牌五分钟有效，并绑定当前资源版本，资源变化后必须重新核对。

将 dryRun 设为 false 会真实访问 HTTP 目标。请先使用专用测试端点、小范围受众和服务端幂等机制验证，不要把上面的 example.com 示例用于正式运行。

运行结束后进入“运行中心”。PARTIAL 或 FAILED Run 可以选择 FAILED、UNKNOWN、UNSENT 状态并点击失败重发；Service 会显示匹配 Item 数量，再创建带来源 Run ID 的新 Run。重发使用来源 Run 的冻结 Snapshot，不会混入之后编辑的 Message 或 Audience。

直接调用 API 时同样必须先获取确认上下文：

curl --request POST \
  http://127.0.0.1:18990/api/v1/workspaces/ws_default/jobs/<JOB_ID>/run-confirmation

curl --request POST \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: replace-with-a-unique-value' \
  --data '{"dryRun":false,"policyOverrides":{},"reason":"manual-live-run","confirmationToken":"<TOKEN_FROM_PREVIOUS_RESPONSE>"}' \
  http://127.0.0.1:18990/api/v1/workspaces/ws_default/jobs/<JOB_ID>/runs

开启 API Security 后还需添加：

Authorization: Bearer <TOKEN>

HTTP Provider 不跟随重定向，默认阻止私有地址，限制响应体大小，并支持配置成功状态码与幂等 Header。正式接入前应按目标系统的认证、限流、超时和幂等约定完成配置。

SMTP、机器人、短信和微信系渠道使用相同的 Account → Message → Audience → Job → Dry Run → 正式确认流程。每个渠道的最小 Account、Message、Recipient、SecretRef、连接测试边界、限流和 Provider Code 处理见《内置 Provider 指南》。所有正式发送都使用用户自己的渠道账号与额度，WePush 不提供集中账号、代充值或平台代理发送。

7. API 文档与 Java SDKs

WebUI 的“API 文档”会读取 Service 提供的 OpenAPI，支持查看请求 Schema、生成请求和动态调试。写操作发送前会二次确认；权限、审计和同源限制仍由 Service 强制执行。

Remote Java SDK 是 Service API 客户端，不依赖 Core、Engine 或具体 Provider。beta.1 发行包和独立 SDK 压缩包都包含它，安装说明见 Java SDK README。

最小示例：

try (var client = WePushClient.builder()
        .endpoint(URI.create("http://127.0.0.1:18990"))
        .build()) {
    var system = client.system().info();
    var providers = client.providers().list();
    var workspace = client.workspace("ws_default");
    var runs = workspace.runs();
}

Embedded Java SDK 依赖 Core Engine，但不依赖 Service、Agent、数据库或 Spring；应用显式注册允许的 Provider，并直接传入执行快照和 Recipient：

var store = new InMemoryExecutionStore();
try (var engine = WePushEngine.builder()
        .provider(new HttpProviderFactory())
        .resultSink(store)
        .eventSink(store)
        .build()) {
    var summary = engine.start(spec, recipients)
            .completion().toCompletableFuture().join();
}

beta.1 发行包和独立 Java SDK 附件同时包含 Embedded SDK 与所需依赖。完整依赖、配置、资源所有权和示例见 Embedded Java SDK README。

8. 何时需要 Agent

默认内嵌执行模式下，Service 自己调用 Core Engine，本地体验不需要 Agent。以下情况再部署 Agent：

任务需要在另一台主机或受控网络中执行。
希望 Service 只承担控制面，执行资源独立扩缩容。
不同执行节点需要安装不同 Provider 插件。
需要借助 Lease、Fencing、心跳和远端 Artifact 回传管理分布式运行。

Agent 使用 Service 的 19090 gRPC 控制流。跨主机部署必须使用 Enrollment、长期 Credential 和 TLS/mTLS，不应沿用回环开发的明文配置。完整步骤见部署与运维文档。

9. 安装为系统服务

统一 install/install.sh 或 install/install.ps1 默认安装 Standalone Service。高级部署可直接调用平台目录下的安装器并传入 service、agent 或 all。

Linux / systemd

tar -xzf wepush-next-1.1.0-linux-x64.tar.gz
sudo ./wepush-next-1.1.0/install/install.sh
systemctl status wepush-next-service

macOS / launchd

从普通登录用户的终端使用 sudo，安装器会将该用户作为非 root 服务用户：

ditto -x -k wepush-next-1.1.0-macos-arm64.zip .
sudo ./wepush-next-1.1.0/install/install.sh
launchctl print system/com.fangxuele.wepush-next.service

无人值守安装需要显式设置已经存在的 WEPUSH_SERVICE_USER。

Windows Service

以管理员 PowerShell 执行：

Expand-Archive .\wepush-next-1.1.0-windows-x64.zip .\release
Set-ExecutionPolicy -Scope Process Bypass
& .\release\wepush-next-1.1.0\install\install.ps1
Get-Service WePushNextService

Windows 发行包已经携带并再次校验固定版本 WinSW；安装阶段不访问网络。精简包也携带 WinSW，只有 Java 由系统提供。

配置路径、备份、升级、卸载、Server/HA、PostgreSQL、S3 与插件步骤见部署与运维文档。

10. 数据、备份与安全

便携 Standalone 默认保存：

SQLite：.local/data/wepush-next.db
Secret 主密钥：.local/secrets/master-key.json
Artifact：.local/artifacts

系统服务安装后的路径因操作系统而异，具体以部署文档和生成的 service.env 为准。正式 backup 会停止相关服务，写入格式/版本/内容清单和每个文件的 SHA-256，再调用 Restore 校验；restore 会先保留恢复前副本，替换后执行安装健康门，失败则自动恢复原数据。数据库、Secret 主密钥、Artifact、Agent Identity、Journal、Event/Completion Outbox 和插件必须作为一个一致备份恢复。

默认无认证模式仅允许 Service 监听回环地址。不要直接把 127.0.0.1 改成 0.0.0.0。非回环监听必须同时启用 API Security、设置强 Bootstrap Token，并在网络入口配置 TLS；Server 模式还会强制 PostgreSQL、S3-compatible Artifact Store 和 Agent gRPC TLS。

11. 常见问题

UI 显示 Service 未连接

确认 http://127.0.0.1:18990/actuator/health/readiness 可访问。
确认 Java 版本是 21 或更高。
检查 18990 是否被其他程序占用。
Desktop 当前只连接本机 127.0.0.1:18990。

Service 启动后看不到 WebUI

使用发行包中的 bin/wepush-service，或按 Windows 便携命令设置 WEPUSH_WEB_ROOT。
确认解压目录下存在 web/index.html。
直接从源码 JAR 启动时需要先构建 WebUI，或单独设置静态资源目录。

HTTP 运行报告 `SSRF_BLOCKED`

目标解析到了私有、回环或受限地址。只有目标确实是受信内部服务时，才在 Account 中开启 allowPrivateAddresses；不要为了绕过未知错误而开启。

API 返回 `401` 或 `403`

Service 已开启安全模式。把 Bootstrap Token 或已签发 Token 填入 WebUI“设置 → 当前 API Token”；命令行请求使用 Authorization: Bearer <TOKEN>。

操作系统阻止 Desktop 首次启动

先核对来源和 SHA-256。校验不一致时立即删除文件；校验一致时使用操作系统针对单个应用提供的确认流程，不要关闭 Gatekeeper、SmartScreen 或终端安全软件。

12. 反馈与进一步文档

普通问题和功能建议可提交 GitHub Issue。安全漏洞不要公开披露，请按 SECURITY.md 中的方式私下报告。