PushMsg开发与使用文档 v1
CRM 接入 管理控制台
文档中心部署与配置

PUSHMSG DOCUMENTATION

部署与配置

了解 Java 服务、HTTPS 入口和局域网文档站的部署位置与配置。

更新 2026-10-267 分钟阅读

当前部署分为应用服务和文档站两部分。生产文档站通过 https://pmsg.admin.xianboss.com 提供访问，与 Java 消息服务位于 14.103.113.229 的不同目录。原 192.168.0.21 文档站保留为局域网预览环境。

当前部署拓扑

组件 地址或目录 用途
生产文档站 14.103.113.229，/www/wwwroot/pmsg.admin.xianboss.com 本手册、接口说明与下载文件
生产文档入口 https://pmsg.admin.xianboss.com 可信 HTTPS 文档访问
生产管理后台 https://pmsg.admin.xianboss.com/admin/ 管理系统、Key / Secret、OpenID 授权与消息
生产 SSH 入口 14.103.113.229:2022 文档发布与运维
局域网预览站 192.168.0.21，/www/wwwroot/pushmsg.doc 文档预览与参考
局域网预览入口 http://192.168.0.21:8084 局域网直接访问；pushmsg.doc 需内部解析
应用服务 14.103.113.229，/opt/pushmsg Spring Boot 中间件与数据库持久化队列
Java 监听地址 127.0.0.1:18081 仅供应用服务器上的 Nginx 反向代理
CRM / OpenID 域名 https://openid.xianboss.com 可信 HTTPS 业务接口和网页授权入口
原 IP 入口 / 通用接口 https://14.103.113.229 当前使用交付的自签名 IP 证书

运行要求

  • Java 17 或以上；项目固定使用 Spring Boot 3.5.16。
  • Maven 3.6.3 或以上用于构建。
  • MySQL；当前生产使用 MySQL 9，初始迁移与业务队列已完成实际验证。
  • Nginx 用于静态页面、HTTPS 和反向代理；systemd 管理 Java 服务。

构建检查：

mvn verify

自动化测试使用 H2 和本地模拟微信接口，不发送真实微信消息；测试数量以当前构建报告为准。Windows Maven profile 已将协议测试使用的 JDK socket 临时目录设为 %SystemRoot%/Temp。

双凭据与接收人授权升级

本版本通过 Flyway 增加系统 Secret 摘要和接收人授权表，不会自动将历史接收人授予所有系统。旧版单 Key 系统默认无法继续认证，需由管理员在后台轮换为 Key + Secret，为其明确选择通道并添加接收人，随后更新调用系统的服务端配置。

上线后检查新凭据可认证、遗漏 Secret 返回 401、未绑定接收人返回 403 RECIPIENT_FORBIDDEN、其他系统查询消息返回 404。生产验证优先使用状态查询与负向权限测试；实际发送通知需使用明确指定的接收人和业务内容。

环境变量

变量 说明
DB_URL JDBC 连接地址，包含数据库名、字符集与时区设置
DB_USERNAME / DB_PASSWORD 数据库账号与密码，使用独立运行配置保存
PUSHMSG_ADMIN_KEY 至少 32 字符的随机管理员密钥
PUSHMSG_ENCRYPTION_KEY 32 个随机字节的 Base64 编码，用于 AES-256-GCM 加密公众号凭据
SERVER_ADDRESS / SERVER_PORT 默认 127.0.0.1 / 18081
PUSHMSG_PUBLIC_BASE_URL OpenID 授权使用的固定 HTTPS 域名原点
PUSHMSG_CRM_CHANNEL_ID CRM 使用的公众号通道，当前为 xianbao
PUSHMSG_CRM_TEMPLATE_ID CRM 新客户跟进通知的完整模板 ID
PUSHMSG_WORKER_ENABLED 默认 true；关闭时只接收任务而不消费队列
PUSHMSG_POLL_DELAY 队列轮询间隔，默认 1000 毫秒
LOG_FILE 应用日志路径

新部署示例，尖括号内容须替换为实际配置：

$env:DB_URL='jdbc:mysql://127.0.0.1:3306/pushmsg?useUnicode=true&characterEncoding=UTF-8&serverTimezone=Asia/Shanghai'
$env:DB_USERNAME='<数据库账号>'
$env:DB_PASSWORD='<数据库密码>'
$env:PUSHMSG_ADMIN_KEY='<至少32字符的随机管理员密钥>'
$env:PUSHMSG_ENCRYPTION_KEY='<32随机字节的Base64编码>'
java -jar target/pushmsg.jar

已有系统应保留原加密主密钥，否则无法解密数据库中已保存的 AppSecret。生产运行配置不放入公开文档或文档站下载目录。

应用发布

应用发布脚本为 ops/deploy.py，当前目标是生产应用服务器，使用 SSH 主机密钥指纹校验。通过环境变量提供部署凭据：

$env:PUSHMSG_SSH_PASSWORD='<应用服务器SSH密码>'
$env:PUSHMSG_DB_PASSWORD='<数据库密码>'
python ops/deploy.py
python ops/deploy_openid_site.py

先完成 mvn verify 再发布。主脚本上传 Jar、校验 SHA-256、保留旧版本和配置备份、切换版本链接，并检查健康状态。OpenID 站点脚本负责对应域名的静态页面与 Nginx 配置。

脚本会保留既有公开域名及 CRM 配置；首次初始化公众号时可额外通过 PUSHMSG_WECHAT_APP_ID、PUSHMSG_WECHAT_APP_SECRET 提供凭据，日常修改可在管理控制台完成。

应用目录

/opt/pushmsg/current                       当前应用版本链接
/opt/pushmsg/releases/RELEASE_ID/           Jar、源码归档与版本核验记录
/opt/pushmsg/shared/production.env          运行配置，root 600
/opt/pushmsg/shared/logs/                   应用与 IP 入口日志
/opt/pushmsg/shared/backups/                发布前配置备份
/opt/pushmsg/shared/tls/                    IP 入口证书
/etc/systemd/system/pushmsg.service         Java 服务定义
/www/wwwroot/openid.xianboss.com/           OpenID 页面与 CRM 在线文档
/www/wwwroot/pmsg.admin.xianboss.com/       完整生产文档站

systemd 使用独立 pushmsg 系统用户运行 Java，启用故障重启和开机启动。静态文档由独立域名的 Nginx 站点提供访问。

文档站构建与发布

文档站是静态 HTML、CSS、JavaScript 和下载文件，不需要在服务器安装 Node 或 Java。

python -m pip install -r docs-site/requirements.txt
python docs-site/build.py
python ops/deploy_docs.py

上述 requirements 安装固定版本的 markdown-it-py 和用于 SSH 发布的 paramiko，它们仅是本地工具依赖，文档服务器不需要安装。构建输出位于 docs-site/dist。发布脚本默认通过隐藏输入提示读取 SSH 密码；自动化调用可使用 --password-stdin 从安全的标准输入通道提供，不将密码写入命令行参数或文件。

发布脚本默认使用 production 环境，通过固定主机密钥指纹连接 14.103.113.229:2022，先备份到 /opt/pushmsg/shared/backups/docs-<时间>，再更新 /www/wwwroot/pmsg.admin.xianboss.com，并核验 Nginx 配置与 HTTPS 访问结果。具体发布记录和访问入口以脚本输出为准。

按需更新原局域网预览站时，显式选择 lan 环境：

python ops/deploy_docs.py --environment lan

该环境连接 192.168.0.21:22，目录 /www/wwwroot/pushmsg.doc，备份位于 /www/backups/pushmsg-doc/<时间>/，预览地址为 http://192.168.0.21:8084。

发布包只包含已生成的文档资源；.local 中的接入密钥、数据库配置、证书私钥和业务测试记录不属于文档发布内容。

回滚应用版本

先记录当前链接，再确认拟回滚版本及其数据库兼容性：

readlink -f /opt/pushmsg/current
ls -1 /opt/pushmsg/releases

将下面的 RELEASE_ID 替换为已经核验的版本目录名：

ln -sfn /opt/pushmsg/releases/RELEASE_ID /opt/pushmsg/current
systemctl restart pushmsg
curl --fail http://127.0.0.1:18081/actuator/health

Flyway 在启动时执行版本化数据库迁移。回滚 Jar 链接不会回滚数据库结构或数据；需要数据库恢复时，应按已验证的备份方案单独执行。日常检查和备份要求见运行维护。

PushMsg 文档内容以当前部署的接口与配置为准。

输入关键词搜索全部文档。