siyu-bank/workphone-sdk
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
fbea77f32d30c673166f2af46af232a110566845
workphone-sdk/开发文档/8、部署/06-存客宝宝塔/工作手机SDK_存客宝宝塔部署总方案.md
Manus AI fbea77f32d fix: persist pairing token before agent startup
2026-08-08 22:03:04 +08:00

9.6 KiB
Raw Blame History

title, date, status
title date status
工作手机SDK · 存客宝宝塔部署总方案 2026-08-05 已发布

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

目标：将工作手机服务部署到 纯客宝塔（bt），并绑定 阿里云域名（默认 wpsdk.quwanzhi.com，可替换成你的域名）

一、目标与已验证前置

  • 服务源：本仓库 sdk/
  • 运行方式：Docker Compose（宝塔内通过 SSH 部署）
  • 对外域名：wpsdk.quwanzhi.com
  • 对外端口：443
  • 入口：https://wpsdk.quwanzhi.com/hub
  • API/WebSocket：https://wpsdk.quwanzhi.com/ws/device

二、服务器端准备

2.1 宝塔主机要求

  • 已安装 Docker / docker compose
  • 已开启网站：wpsdk.quwanzhi.com
  • 已安装 Nginx
  • 已打开 80/443 入站

2.2 准备 SSH 与目录

建议：

  • TARGET=root@你的宝塔IP
  • REMOTE_DIR=/www/wwwroot/workphone-sdk

三、服务器端变量

在宝塔主机目录 REMOTE_DIR 放置 .env（示例在仓库 sdk/.env.nas.example，宝塔版需补充更多变量）：

# 必填
API_KEY=随机32字节以上
DEVICE_PAIRING_TOKEN=随机32字节以上
CONSOLE_USERNAME=admin
CONSOLE_PASSWORD=随机复杂密码
MONGO_ROOT_USERNAME=workphone
MONGO_ROOT_PASSWORD=随机强密码

# 非必填（可按需）
WORKPHONE_LAN_IP=192.168.x.x
WORKPHONE_BIND_SERVER=wss://wpsdk.quwanzhi.com/ws/device
WORKPHONE_PUBLIC_WSS=wss://wpsdk.quwanzhi.com/ws/device
AI_BRAIN_ENABLED=false
AI_BRAIN_API_URL=https://kr-ai.quwanzhi.com
AI_BRAIN_API_KEY=

# 可选（企业网线下线方式）
ADB_SERVER_SOCKET=tcp:192.168.x.x:5037

建议 API_KEY 与 DEVICE_PAIRING_TOKEN 写入密码管理，不在公开聊天公开。

四、发布文件

执行（本机）:

cd /Users/karuo/Documents/开发/2、私域银行/工作手机
export TARGET=root@你的宝塔IP
export REMOTE_DIR=/www/wwwroot/workphone-sdk
bash sdk/scripts/deploy_baota_wpsdk.sh

该脚本会完成：

  1. 同步 app/ agent/ Dockerfile .env docker-compose.baota.yml
  2. 上传 Nginx 站点配置到 /www/server/panel/vhost/nginx/wpsdk.quwanzhi.com.conf
  3. 容器启动（仅映射本机回环 127.0.0.1:8899）
  4. 重载 nginx

五、宝塔 Nginx 配置要点

本仓库配置文件： /Users/karuo/Documents/开发/2、私域银行/工作手机/sdk/deploy/baota/wpsdk.quwanzhi.com.conf

关键点：

  • proxy_pass http://127.0.0.1:8899;
  • proxy_set_header Upgrade $http_upgrade;
  • proxy_set_header Connection "upgrade";（WS 必须）

六、阿里云域名指向（dns）

6.1 域名 DNS 记录

  • 记录类型：A
  • 主机记录：wpsdk
  • 记录值：宝塔服务器外网 IP
  • TTL：600（或默认）

6.2 微信端手机扫码绑定提示词

二维码页/扫码绑定请使用域名：https://wpsdk.quwanzhi.com/hub，避免硬编码 IP。

七、验收命令（每次发布后跑）

# 健康检查
curl -I https://wpsdk.quwanzhi.com/health

# 登录页
curl -I https://wpsdk.quwanzhi.com/hub

# WebSocket 配置可达
curl -X POST http://127.0.0.1:8899/api/v3/health 2>/dev/null || true

八、故障排查

  • 如果站点返回 502/500：先看宝塔错误日志（Nginx）+ docker compose -f docker-compose.baota.yml logs -f sdk
  • 如果扫码可见但不在线：确认 APK 的 ws 地址是 wss://wpsdk.quwanzhi.com/ws/device
  • 如果控制台无法触摸：确认 docker compose logs 有 websocket connected 并回传心跳
  • 如果外网解析到错误 IP：先在本地 dig +short wpsdk.quwanzhi.com 与宝塔机器 ping 比对

九、2026-08-08 线上核验记录

  • https://wpsdk.quwanzhi.com/health 返回 HTTP 200，服务版本为 3.0.0，当前在线设备数为 0。
  • 未登录访问 /hub 返回 HTTP 401 API Key 无效，说明生产环境已开启鉴权，扫码页面需要先用管理员账号登录。
  • /api/v3/qrcode/generate 未携带线上匹配密钥时返回 HTTP 401，二维码路由本身已发布，空白区域是未完成登录或生成前的初始状态。
  • 本机 sdk/.env 中存在 API Key，但与公网服务当前使用的 API Key 不一致；需要在宝塔 /www/wwwroot/workphone-sdk/.env 对齐后重启容器。
  • 对齐后验收顺序：打开 /hub?tab=devices → 管理员登录 → 点击“扫描服务器并作为绑定基准” → 点击“生成绑定二维码” → 手机端扫码 → 回到设备列表观察 WS 在线数。
  • 本轮只做了公网只读核验和本地页面、文档更新，未执行远程上传、容器重启或真实设备写操作。

九、上线后交付物

  • 已执行命令列表
  • .env（脱敏后）
  • https://wpsdk.quwanzhi.com/hub
  • docker ps 关键容器：workphone-mongo-baota / workphone-redis-baota / workphone-sdk-baota

十、2026-08-05 部署复盘（本次最新发布）

  • 执行命令：
    • cd /Users/karuo/Documents/开发/2、私域银行/工作手机
    • TARGET=cunkebao REMOTE_DIR=/www/wwwroot/workphone-sdk bash sdk/scripts/deploy_baota_wpsdk.sh
  • 结果：部署成功，容器与 Nginx 重载完成，输出显示 部署完成：https://wpsdk.quwanzhi.com/health。
  • 当前容器状态（发布后采集）：
    • workphone-mongo-baota：Up (healthy)
    • workphone-redis-baota：Up (healthy)
    • workphone-sdk-baota：Up (healthy)，127.0.0.1:8899 对外服务可达
  • 外网校验：
    • https://wpsdk.quwanzhi.com/health：HTTP/2 200
    • https://wpsdk.quwanzhi.com/hub：HTTP/2 401（控制台需登录鉴权）
  • 注意：/hub 返回 401 为鉴权网关行为，非部署失败；需用控制台账号登录后访问。
  • 主要配置文件：
    • sdk/docker-compose.baota.yml
    • sdk/deploy/baota/wpsdk.quwanzhi.com.conf
    • sdk/scripts/deploy_baota_wpsdk.sh

2026-08-08｜存客宝宝塔-本轮最新发布（继续）

  • 执行时间：2026-08-08（北京时间）
  • 执行命令：
    • cd /Users/karuo/Documents/开发/2、私域银行/工作手机
    • TARGET=cunkebao REMOTE_DIR=/www/wwwroot/workphone-sdk bash sdk/scripts/deploy_baota_wpsdk.sh
  • 部署结果：
    • 同步与构建成功，Nginx 配置加载成功。
    • 已输出 部署完成：https://wpsdk.quwanzhi.com/health
  • 验证：
    • curl -ksS https://wpsdk.quwanzhi.com/health 返回 {"status":"healthy","version":"3.0.0"}
    • docker compose -f docker-compose.baota.yml ps 显示：workphone-sdk-baota 为 Up ... (healthy)
    • 服务器本地 curl http://127.0.0.1:8899/health 返回同样健康状态。
  • 访问说明：
    • 控制台页面可能返回 401（鉴权网关）是正常行为；需登录后使用 /hub。

2026-08-08｜扫码版本差异复核

  • 复核结论：本地 sdk/app/static/hub.html 已包含“扫码绑定手机”面板和 POST /api/v3/qrcode/generate 调用；用户反馈线上页面仍为旧版，按“线上未同步”处理。
  • 根因：此前完成了本地页面和 v1.0 交付包更新，但没有在本轮执行宝塔远程同步，因此本地与线上版本存在差异。
  • 正式发布命令：TARGET=cunkebao REMOTE_DIR=/www/wwwroot/workphone-sdk bash sdk/scripts/deploy_baota_wpsdk.sh。
  • 发布后必须验证：登录 https://wpsdk.quwanzhi.com/hub?tab=devices，确认“扫码绑定手机”面板、扫描服务器按钮、生成绑定二维码按钮均出现，再执行手机扫码。
  • 回滚方式：使用发布前保存的 app/ 目录和 Docker 镜像重新执行 docker compose -f docker-compose.baota.yml up -d --build，再重载 Nginx。
  • 本轮已完成本地发布准备和源码路由校验；远程同步和容器重启需在宝塔主机执行。

2026-08-08 21:47 扫码绑定与失效设备清理修复

  • 现象：设备页顶部“扫描”实际执行 ADB 扫描，未直接展示绑定二维码，造成扫码入口混淆。
  • 处理：设备页新增 📷 扫码绑定，点击后切回绑定区并自动调用 POST /api/v3/qrcode/generate 渲染二维码；原按钮明确改名为 📡 扫描 ADB。
  • 绑定内容：二维码仅包含当前服务 WSS 地址和配对令牌，控制台使用管理员会话，外部服务使用 API Key。
  • 清理能力：新增 DELETE /api/v3/devices/{device_id}；仅允许删除离线登记设备，在线设备返回 409，历史命令记录保留审计。
  • 验收：本地 pytest tests/test_qrcode_bind_and_offline_delete.py -q 通过；上线后回读二维码生成、页面标识、离线删除保护及健康状态。

2026-08-08 21:48 上线验收结果

  • workphone-sdk-baota 已重建并显示 healthy。
  • 服务器内网 POST /api/v3/qrcode/generate：HTTP 200，success=true，返回 PNG Data URL，二维码中含 wss://wpsdk.quwanzhi.com/ws/device。
  • 页面源码回读确认 openBindQRCode、扫码绑定、扫描 ADB、删除失效设备 均已上线。
  • DELETE /api/v3/devices/__verification_missing_device__ 返回 HTTP 404，确认删除接口受设备存在性校验保护；在线设备另有 HTTP 409 保护。
  • 公网健康检查：https://wpsdk.quwanzhi.com/health 返回 healthy；当前 devices_online=0，等待手机扫描二维码并完成 WSS 注册。

2026-08-08 22:00 已扫码未注册修复

  • 根因：手机扫码后 SetupActivity 以异步 SharedPreferences.apply() 写入 pairing_token，随即启动 Agent；首次启动存在令牌尚未落盘的竞态，WSS 握手未带 token。
  • 修复：扫码绑定字段改为单个 Editor 原子 commit() 成功后再启动 AgentForegroundService。
  • APK：/static/downloads/workphone-agent-latest.apk，SHA-256：b50a96b9475e365a377e0ac9d7efbf40fba04ac357fb660001829946cc3ad601。
  • 验收口径：安装修复包后重新扫码；服务端日志应出现 WSS 连接与 设备注册，/health 的 devices_online 应大于 0。