Skip to content

README.md

Latest commit

 

History

History
183 lines (129 loc) · 12.6 KB

README.md

File metadata and controls

183 lines (129 loc) · 12.6 KB
Raw

WePush Next

WePush Next 是与 Classic 完全独立的新产品线。Classic 与 Next 可以按需拥有重复代码，彼此不建立共享源码依赖。

产品定位：WePush Next 是开源、可下载、可安装、由用户自行部署和运维的消息推送产品。项目不建设官方公共 SaaS、注册计费订阅、公共租户平台或云 KMS/Secret Manager 集成。正式范围和分版本计划见《产品目标、边界与路线图》。

当前版本：1.2.0 Stable。下载 next-v1.2.0。Desktop 与安装包按项目约定不使用商业代码签名；下载后必须验证同一 Release 中的 SHA256SUMS。发行边界和升级承诺见 UNSIGNED-NOTICE.md、《兼容性策略》、《升级与回滚指南》与 docs/releases/1.2.0.md。

第一次下载和使用请从《WePush Next 对外使用指南》开始。渠道账号、模板、Recipient、SecretRef、限流和错误语义见《内置 Provider 指南》。

1.2.0 提供 Codex MCP / Skill 接入，支持查询和创建资源、空跑、授权发送及运行控制，快速配置见下方「AI 助手接入」。

下载与安装

正式发行物统一位于 next-v1.2.0 GitHub Release：

使用方式 选择的发行物
推荐的 Standalone 安装 与操作系统、架构匹配的 wepush-next-1.2.0-<os>-<arch> 完整包，已包含 Java Runtime
已有 Java 25+ 或分组件部署 wepush-next-1.2.0.tar.gz 或 wepush-next-1.2.0.zip 精简包
只使用管理界面 与操作系统、架构匹配的 wepush-next-desktop-1.2.0-<os>-<arch>
Java 集成 wepush-next-java-sdk-1.2.0.zip
运营商短信 Agent 插件 wepush-provider-{cmpp,smgp,sgip,smpp}-1.2.0.zip 及 wepush-provider-trusted-key-1.2.0.env

下载后先验证 SHA256SUMS。安装运营商插件时，还必须校验信任公钥文件及各插件的旁路 .sha256；不要从插件 ZIP 或第三方页面获取替代公钥。完整资产说明和升级步骤见 1.2.0 Release Notes。

完整包解压后执行统一 Standalone 安装入口：

# Linux / macOS
sudo ./install/install.sh
# Windows 管理员 PowerShell
Set-ExecutionPolicy -Scope Process Bypass
& .\install\install.ps1

安装完成前会检查 Service Readiness、Flyway 数据库版本和本地 Provider Dry Run。需要便携运行或已有 Java 25+ 时，可选择精简包；分组件部署仍可直接使用 install/<os>/install.* service|agent|all。

AI 助手接入（MCP / Skill）

启动 Next Service 并配置渠道账号后，打开 设置 → AI 助手接入，核对 Service URL 与当前 Workspace：

  • **Desktop：**点击 一键接入 Codex 安装 MCP + Skill，或选择 仅安装 Skill；使用 Desktop 自带运行时，无需另装 Node.js。其他支持 stdio MCP 的客户端可使用 导出通用 MCP 配置。
  • **WebUI / 新构建发行包：**下载页面提供的独立安装器，或使用发行包中的 ai/wepush-ai.mjs，通过 Node.js 24+ 执行安装命令：
node ./wepush-ai.mjs install --target codex --url http://127.0.0.1:18990 --workspace ws_default

安装后重新连接 Codex MCP，必要时重启 Codex。MCP 名称为 wepush，Skill 位于 ~/.agents/skills/wepush，可与 Classic 的 wepush-classic 同时安装。启用 Service 认证时，在 AI 客户端环境中设置 WEPUSH_API_TOKEN；安装器不复制登录 Token。

助手可以发现 Provider Schema、查询现有资源、创建消息/受众/任务、执行 Dry Run、准备与提交正式发送，以及查询结果、暂停、恢复或取消运行。正式发送需核对预览并取得覆盖内容与受众的用户授权；网络超时后保留原请求编号，先查询运行结果。

完整工具列表、权限要求、其他客户端配置及排错见《AI 助手接入指南》。Classic 的入口与执行范围见《Classic 接入指南》。

验证 Java 工程

cd next
./mvnw verify

完整构建、三平台安装、Server/HA、Agent Enrollment、插件升级和恢复步骤见 docs/deployment-and-operations.md。安全问题请按 SECURITY.md 私下报告。

启动 Service

cd next
./mvnw -pl service/service-app -am package -DskipTests
java -jar service/service-app/target/wepush-next-service.jar

Service 默认只监听 127.0.0.1:18990。启动后可访问：

  • http://127.0.0.1:18990/actuator/health
  • http://127.0.0.1:18990/api/v1/system/info
  • http://127.0.0.1:18990/api/v1/providers
  • http://127.0.0.1:18990/api/v1/agents
  • http://127.0.0.1:18990/openapi.yaml

本地无认证模式只允许监听回环地址；将 WEPUSH_BIND_ADDRESS 改为非回环地址时必须同时开启 WEPUSH_SECURITY_ENABLED=true 并配置足够强度的 WEPUSH_BOOTSTRAP_TOKEN，否则 Service 拒绝启动。

Standalone 数据默认保存到 .local/data/wepush-next.db，可通过 WEPUSH_DATABASE_PATH 指定其他位置。Service 首次启动会运行 Flyway 迁移并创建 ws_default 工作区。

Secret 默认使用本地信封加密：密文进入 SQLite，主密钥单独保存到 .local/secrets/master-key.json。可通过 WEPUSH_MASTER_KEY_PATH 修改路径，或使用 WEPUSH_MASTER_KEY_BASE64 注入 32-byte Base64 主密钥。已有密文但主密钥缺失、权限不安全或认证失败时，Service 会失败关闭，不会生成新密钥覆盖。

Artifact 默认保存到 .local/artifacts，SQLite 只保存元数据、SHA-256、大小和生命周期状态。可通过 WEPUSH_ARTIFACT_ROOT 修改根目录；临时结果导出默认保留 24 小时，可通过 WEPUSH_EXPORT_RETENTION 使用 ISO-8601 Duration 调整。Service 会按 WEPUSH_RETENTION_INTERVAL 周期回收过期且未 Pin/Legal Hold 的文件。

启动 WebUI 开发环境

cd next/ui
pnpm install
pnpm check
pnpm dev

WebUI 默认运行在 http://127.0.0.1:5173，开发代理连接本地 Service。界面、API Client、Schema Renderer、设计 Token 与 Electron Desktop 外壳均在同一个 pnpm Workspace 内。

启动 Agent

cd next
./mvnw -pl agent/agent-app -am package -DskipTests
java -jar agent/agent-app/target/wepush-next-agent.jar

Agent 默认主动连接 127.0.0.1:19090 的 gRPC 双向控制流，发送 Hello 和周期心跳，断线后使用带抖动的指数退避重连；Sequence 与 Lease Fence Journal 默认保存在 .local/agent/agent-state.properties。

常用环境变量：

  • WEPUSH_AGENT_ID：稳定 Agent 身份，默认 local-agent。
  • WEPUSH_SERVICE_HOST / WEPUSH_AGENT_GRPC_PORT：Service gRPC 地址，默认 127.0.0.1:19090。
  • WEPUSH_AGENT_GRPC_TOKEN：仅用于回环开发/Bootstrap 的共享 Token；正式 Agent 使用 Enrollment Credential。
  • WEPUSH_AGENT_GRPC_PLAINTEXT：本地开发默认 true；远端部署应关闭并使用 TLS。
  • WEPUSH_AGENT_STATE_PATH：Agent Journal 文件位置。

Service 的 gRPC 端口默认只绑定回环地址。暴露到非回环地址时强制 TLS，HTTP Lease/Artifact 与 gRPC 都拒绝匿名 Agent；正式生产通过一次性 Enrollment 获取长期 Credential 和客户端证书，并使用 mTLS。共享 Token 只保留为回环开发兼容入口。

要把 Run 交给独立 Agent 执行，Service 使用以下配置启动：

WEPUSH_EXECUTION_MODE=remote \
WEPUSH_AGENT_PUBLIC_BASE_URL=http://127.0.0.1:18990 \
java -jar service/service-app/target/wepush-next-service.jar

远端模式会按 Provider ID/版本和可用容量选择在线 Agent，持久化带 Epoch/Fencing Token 的 Lease。Agent 校验冻结 Execution Spec 与 Audience 的 SHA-256 后 ACK，随后使用同一 Core Engine 执行，并经 gRPC 回传事件、Item Result、命令确认和 Run Summary。

需要 Secret 的远端 Run 会使用 Agent 在 Hello 中发布的会话级 X25519 公钥。Service 只解析冻结配置中实际引用的最小 Secret 集，使用一次性 X25519、HKDF-SHA-256 和 AES-256-GCM 加密，并绑定 Agent、Run、Lease、Epoch、Fencing Token 与过期时间。Agent 仅在内存中解密，运行结束立即清零，不写入 Journal。正式跨主机部署仍应关闭明文 gRPC 并配置 TLS；Secret Envelope 不替代 Agent 身份认证和传输层安全。

Java SDKs

Next 提供两种独立 SDK。Remote SDK 通过 HTTP 调用 Service，只依赖公开 service-api，不依赖 Core、Engine 或具体 Provider：

稳定发行包在 sdk/ 中附带可安装到本地 Maven Repository 的 POM/JAR，步骤见 sdk/README.md。

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 agents = client.agents().list();
    var workspace = client.workspace("ws_default");
    var runs = workspace.runs();
    var artifacts = workspace.runArtifacts(runs.getFirst().id());
}

Embedded SDK 则在调用方 JVM 内直接运行 Engine，显式装配所需 Provider，不启动 Service、Agent 或数据库：

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();
}

从源码安装、依赖声明和完整示例见 sdk/README.md 与 sdk/embedded-java/README.md。1.2.0 发行包和独立 Java SDK 附件同时提供 Remote SDK、Embedded SDK、HTTP Provider 与标准渠道 Provider；CMPP、SMGP、SGIP、SMPP 则作为独立签名 Agent 插件发布，不进入 Embedded SDK 的默认依赖。

1.2.0 已交付基线

  • Core API、Provider SPI、虚拟线程 Engine，以及 HTTP、SMTP Email、飞书/钉钉/企微机器人、阿里云短信、微信公众号、小程序和企业微信应用消息 Provider；CMPP、SMGP、SGIP、SMPP 以四个独立签名插件交付。
  • Agent Protocol、Protobuf/gRPC 双向控制流、Sequence/Fencing Runtime、持久 Journal、加密 Secret Envelope、远端 Core 执行适配与常驻 Agent 包。
  • Service 分层、SQLite/PostgreSQL/Flyway、Workspace 资源治理、跨 Run 账号认证熔断、资源编辑/不可变修订/分页、流式 Audience Import、正式发送确认、关联重发、真实总览、Agent 注册/心跳/持久 Lease、信封加密 Secret Store、Result/Command/Artifact 持久化、SSE，以及可切换的内嵌/远端执行器。
  • PostgreSQL LISTEN/NOTIFY 低延迟唤醒、结构化脱敏诊断包、手动版本检查、Nginx/Traefik/Kubernetes 自建模板，以及 Agent Presigned Multipart Artifact（最大 5 TiB）。
  • 相互独立的 Remote Java SDK、Embedded Java SDK 和 TypeScript API Client。
  • React WebUI、亮色/暗色/跟随系统主题、低分辨率和键盘可访问性、动态 Provider/SecretRef Schema、渠道消息示例、资源生命周期、CSV/TXT 导入、Dry Run/正式确认/结果/失败重发闭环、真实 Workspace 和运行总览、动态 API 文档、Electron 安全外壳和共享前端 packages。
  • Codex MCP / Skill 接入：Desktop 一键安装，WebUI 与发行包提供 wepush-ai.mjs；正式发送仍走既有确认令牌和 Workspace 权限。
  • Java 25 构建与运行基线；完整包内置 Java 25 运行时，精简包和 Java SDK 需要系统 Java 25+。
  • 一体化 Standalone/离线 Windows 安装、含 Java Runtime 完整包、正式备份恢复、升级健康门与自动回退；Desktop 提供本机 Service 运维、系统安全 Token 存储和签名插件 Stage/Activate/Rollback。
  • 架构、单元、契约、浏览器 E2E、Desktop 冒烟、三平台安装/恢复/失败升级以及定时长稳矩阵。

产品范围和迭代优先级以 docs/product-scope-and-roadmap.md 为准；模块边界和实现细节以 docs/architecture-and-high-level-design.md、docs/detailed-design.md、docs/implementation-status.md、docs/deployment-and-operations.md 及 docs/adr/ 为准。