WeChatPadProBusiness Docker 一键部署教程：安装、代理、HTTPS 与升级

这不是一份只告诉你执行 docker compose up -d 的教程。本教程配套的部署包已经把环境检查、客户端密钥引导、端口冲突检查、Redis 初始化、服务依赖、API 就绪检测和镜像版本输出整合进安装脚本，目标是让首次部署可以验证，后续升级可以回滚。

86b880cd1be77f3494612227078d5e77e1fa9da628665bfb2e0176a312780314

一、部署包里有什么

docker-deploy/
├── README.md
├── install.sh
├── check-proxy.sh
├── docker-compose.release.yml
├── .gitignore
└── config/
    └── app.conf.example

• install.sh：一键检查环境、初始化配置、拉取镜像并等待 API 就绪。
• docker-compose.release.yml：编排 prepare、Redis 与主程序三个服务。
• check-proxy.sh：连续检测 SOCKS5 节点质量，密码不会进入命令历史。
• app.conf.example：公开配置模板，不包含真实客户端密钥。
• .gitignore：阻止私有配置和运行数据被误提交。

公开包不包含 config/app.conf、data/、Docker Hub Token、客户端密钥、代理密码或 Redis 密码。首次运行时会在服务器本地生成私有配置。

二、环境要求

• Linux x86-64 服务器，不使用 macOS/Windows Docker Desktop 部署本配置。
• Docker Engine 24+。
• Docker Compose v2.20+。
• 建议至少 2 核 CPU、2 GB 内存，并预留持久数据空间。
• 端口 18062、18089、18080、16379 未被占用。

uname -m
docker version
docker compose version
ss -ltnp | grep -E ':(18062|18089|18080|16379)\b' || true

uname -m 应返回 x86_64。尚未安装 Docker 时，可先阅读本站的 Docker Compose 从 Ubuntu 安装到生产上线。

三、为什么使用 host 网络

主程序需要让 SOCKS5、DNS、IPv4/IPv6、路由和公网出口与 Linux 宿主机保持一致，因此 Compose 使用 network_mode: host。这种模式不经过 Docker bridge NAT，容器也不会获得独立 IP。

host 网络下，Compose 的 PORTS 列为空是正常现象；配置文件里的监听端口就是宿主机端口。

代价是网络隔离更弱，端口会直接监听在宿主机上。因此必须通过云安全组和防火墙控制公网入口。Docker 官方也明确说明，host 模式共享宿主机网络栈，端口映射不会生效。

四、下载并校验文件

mkdir -p /opt/knowhub
cd /opt/knowhub

curl -fLO https://bbs.knowhub.cloud/wp-content/uploads/downloads/wechatpadprobusiness-docker-deploy-20260820-r2.zip
curl -fLO https://bbs.knowhub.cloud/wp-content/uploads/downloads/wechatpadprobusiness-docker-deploy-20260820-r2.zip.sha256

sha256sum -c wechatpadprobusiness-docker-deploy-20260820-r2.zip.sha256

看到 OK 后再解压：

sudo apt update
sudo apt install -y unzip
unzip wechatpadprobusiness-docker-deploy-20260820-r2.zip
cd docker-deploy
chmod +x install.sh check-proxy.sh

五、拉取公开镜像

WeChatPadProBusiness 使用公开 Docker Hub 镜像，不需要执行 docker login。可以先手动验证拉取：

docker pull wechatpadpro/wechatpadprobusiness:v2026.08.18.1

如果这里出现网络超时，先检查服务器访问 Docker Hub 的网络与 DNS；如果拉取成功，再继续运行安装脚本。

六、执行首次安装

cd /opt/knowhub/docker-deploy
./install.sh

第一次运行会进行以下操作：

1. 从 config/app.conf.example 创建权限为 600 的 config/app.conf。
2. 检查 Linux、x86-64、Docker、Compose、配置格式和端口占用。
3. 当 user_token_key 为空时，引导打开 访问控制页面创建客户端密钥。
4. 在终端无回显读取密钥，确认后写入私有配置。
5. 拉取指定镜像，再启动 prepare、Redis 和主程序。
6. 自动生成独立 Redis 密码，并等待 API 在 120 秒内就绪。
7. 输出镜像名、版本、Build ID、Image ID 和 Repo Digest。

一个客户端密钥只对应一套服务器部署。测试环境、新服务器或保留旧服务器并行运行时，都应创建新的客户端密钥。

七、验证部署结果

docker compose -f docker-compose.release.yml ps
docker compose -f docker-compose.release.yml logs --tail=100 wechatpad
curl -I http://127.0.0.1:18062/
ss -ltnp | grep -E ':(18062|18089|18080|16379)\b'

• 主程序应为运行状态。
• Redis 健康检查应通过。
• 本机 API 返回有效 HTTP 响应。
• Redis 只监听 127.0.0.1:16379。
• 日志中没有循环重启、密钥错误或 Redis 连接失败。

八、配置 Nginx HTTPS 与 WebSocket

生产 API 不应直接通过公网 HTTP 访问。域名证书配置完成后，可将 Nginx 反向代理到本机 API：

location / {
    proxy_pass http://127.0.0.1:18062;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
}

location /ws/ {
    proxy_pass http://127.0.0.1:18089;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
    proxy_read_timeout 3600s;
}

sudo nginx -t
sudo systemctl reload nginx

浏览器先通过带认证头的 HTTPS API 调用 /api/Runtime/WebSocketTicket 获取短时票据，再连接：

wss://YOUR_DOMAIN/ws/sync?ticket=SHORT_LIVED_TICKET

九、端口与安全组策略

• 443：对外提供 HTTPS/WSS。
• 18062：API，不向公网任意来源直接开放。
• 18089：WebSocket，不向公网任意来源直接开放。
• 18080：人脸验证入口，只允许当前验证手机的公网来源 IP。
• 16379：Redis，必须保持 127.0.0.1，绝不开放公网。

host 模式绕过了 Compose 端口映射这一层，安全边界必须落在云安全组、宿主机防火墙、Nginx 和应用认证上。修改规则后要从公网和本机分别验证，不要只看面板显示。

十、检测 SOCKS5 代理

./check-proxy.sh 203.0.113.10:1080 '代理用户名' 5

脚本会在终端安全读取密码并连续检测五次。基础检测应达到 5/5 且返回 HTTP 302；最终仍要以 GetQR 和扫码后的 CheckUuid 成功为准。

• connection refused：节点或端口拒绝连接。
• general SOCKS server failure：代理服务端拒绝目标。
• connection reset by peer / EOF：节点中途断开。
• timeout awaiting response headers：代理或上游响应过慢。

十一、升级、备份与回滚

cd /opt/knowhub/docker-deploy
cp config/app.conf "config/app.conf.backup-$(date +%Y%m%d_%H%M%S)"
tar czf "data-backup-$(date +%Y%m%d_%H%M%S).tar.gz" config data
./install.sh

需要锁定指定镜像版本时：

WECHATPAD_IMAGE=wechatpadpro/wechatpadprobusiness:版本标签 ./install.sh

升级与重启都不要删除 config/ 和 data/。其中包含客户端配置、Redis 数据、设备身份、登录会话与人脸 CA。回滚时恢复配置和数据备份，并将镜像标签改回上一版本。

十二、常见问题

• Compose 的 PORTS 列为空：host 网络的正常表现，使用 ss 查看实际监听。
• 提示端口被占用：检查宿主机现有进程，确认后修改 config/app.conf，不要随意结束未知进程。
• API 120 秒未就绪：查看 prepare、redis、wechatpad 三个服务的最近日志。
• 502 Bad Gateway：先在宿主机执行 curl http://127.0.0.1:18062/，再检查 Nginx 上游和错误日志。
• 扫码一直转圈：若直连成功、使用 Proxy 失败，应重点检查 SOCKS5 稳定性，不要反复修改 Redis。
• 人脸页面无法访问：确认 18080 来源 IP 白名单、手机公网 IP 和 pad_face_public_base_url。

上线检查清单

[ ] ZIP 的 SHA-256 校验通过
[ ] config/app.conf 权限受限且未提交到 Git
[ ] 客户端密钥只用于当前这一套部署
[ ] Redis 仅监听 127.0.0.1:16379
[ ] API 与 WebSocket 通过 HTTPS/WSS 对外服务
[ ] 18062、18089 未向公网任意来源开放
[ ] 18080 只允许实际验证手机来源 IP
[ ] 日志、状态、API 和 WebSocket 均已验证
[ ] config/ 与 data/ 已建立异机备份
[ ] 已记录当前镜像版本和回滚版本

官方参考

• Docker Host Network 官方说明
• Compose Services 与 depends_on 条件
• Ubuntu 安装 Docker Engine
• Docker Compose 生产环境指南