workphone-sdk/开发文档/8、部署/06-存客宝宝塔/工作手机SDK_存客宝宝塔部署总方案.md

工作手机 SDK · 存客宝宝塔部署总方案

版本：v1.1 · 更新：2026-07-14 · 当前线上域名：https://wpsdk.quwanzhi.com

1. 目标架构

手机 Agent → HTTPS/WSS → 宝塔 Nginx（443/TLS）
                         → workphone-sdk Docker（127.0.0.1:8899）
                         → MongoDB/Redis + 存客宝 BFF

2. 部署步骤

1. 宝塔 API 只读检查现有站点、Node 项目、容器、端口、磁盘和防火墙。
2. 确认 8899 未被占用，且不会影响存客宝现有站点。
3. 创建独立目录，上传 sdk/ 或审计后的发行包；不上传本机 .env。
4. 写入生产环境变量：API_KEY、MONGO_URI、MONGO_DB、REDIS_URL、AI_BRAIN_ENABLED。
5. 用 sdk/docker-compose.baota.yml 构建启动，SDK 只监听 127.0.0.1:8899。
6. 宝塔创建独立域名 wpsdk.quwanzhi.com 并反代到 127.0.0.1:8899，启用 TLS。
7. 配置存客宝 BFF 的 SDK URL 与 API Key，先健康检查，再设备读类验收。
8. 手机安装 Agent，填写 WSS 地址，完成真实设备绑定。

3. Nginx 反代核心配置

location / {
    proxy_pass http://127.0.0.1:8899;
    proxy_http_version 1.1;
    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_read_timeout 300s;
}
location /ws/ {
    proxy_pass http://127.0.0.1:8899;
    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;
}

4. 验收命令

curl -fsS https://wpsdk.quwanzhi.com/health
curl -fsS https://wpsdk.quwanzhi.com/ready
curl -i https://wpsdk.quwanzhi.com/api/v3/devices  # 未带 Key 应为 401

随后验证 BFF 鉴权、设备 Agent WSS 上线、心跳、设备列表、截图读类接口，以及使用测试设备/联系人完成一条受控写类任务并保留回执。重启后还要验证容器自启与设备重连。

5. 回滚

只回滚独立的 workphone-sdk 容器、站点和 Nginx 配置，不修改存客宝现有站点。恢复后执行 nginx -t、原站点健康检查，并让设备切回原 SDK WSS 地址。

6. 当前执行结论（2026-07-14）

• 已通过 SSH 别名 cunkebao 部署到 /www/wwwroot/workphone-sdk。
• workphone-sdk-baota、workphone-mongo-baota、workphone-redis-baota 三个容器健康。
• 公网 /health 为 healthy，/ready 为 true；未授权 API 返回 401，授权设备列表返回 200。
• 真机 Redmi 2312DRAABC 已通过 wss://wpsdk.quwanzhi.com/ws/device 上线，设备 MD5 为 ed25814d9c92b3430696dc96c2142b5f。
• 公网 Fleet 读类动作已读到真机微信 8.0.69；配对令牌不再出现在日志和管理 API。
• Hook 当前仍未点亮，联系人/消息等 Hook 读类与受控写类不能据此宣称全绿，须继续按验收记录复测。