workphone-sdk/开发文档/8、部署/06-存客宝宝塔/部署前置条件与端口清单.md

工作手机 SDK · 存客宝宝塔部署前置条件与端口清单

更新：2026-07-14 目标：把 SDK 服务部署到存客宝（纯客宝）所在的宝塔服务器，并让自有授权 Android 工作机通过 Agent WebSocket 接入。

1. 服务器条件

项目	要求	说明
宝塔	已安装 Docker、Docker Compose、Nginx	SDK 推荐 Docker 托管，宝塔只负责站点/反代
资源	至少 2 核、4 GB RAM、10 GB 可用磁盘	多设备和日志量增加时按设备数扩容
网络	手机能访问 HTTPS/WSS 域名	不建议把 8899 直接暴露公网
安全	API Key、TLS、宝塔防火墙白名单	禁止使用仓库默认密钥

本次实际服务器：Ubuntu，15 GiB 内存、约 40 GiB 可用磁盘；Docker 27.1.2、Compose 2.29.1，满足条件。

2. 端口与域名

端口/路径	用途	暴露策略
8899 容器端口	SDK REST、控制台、WebSocket	仅本机或内网；Nginx 反代
wpsdk.quwanzhi.com:443	手机 Agent 与存客宝业务访问	已开放，TLS/WSS
/api/v3/	SDK API	反代到 127.0.0.1:8899
/ws/	设备 Agent WebSocket	必须配置 Upgrade/Connection 头
8898/UDP	局域网发现	只在手机与服务器同一局域网时开放

3. 设备与对接条件

• 设备必须是公司自有或明确授权的 Android 工作机。
• 设备端使用 wss://域名/ws/device/{device_id}，不能把 127.0.0.1 写入 APK 配置。
• 设备主动上报是主链路，平台主动拉取只做断链或验收兜底。
• 存客宝 BFF 通过 SDK 标准接口访问设备，前端不得直连 ADB、Frida 或设备端口。

WORKPHONE_SDK_URL=https://wpsdk.quwanzhi.com
WORKPHONE_SDK_API_KEY=<服务器环境变量注入>
WORKPHONE_DEVICE_PAIRING_TOKEN=<服务器环境变量注入>

4. 禁止入库内容

• 宝塔账号、SSH 密码、宝塔 API Key、MongoDB/Redis 密码。
• 生产 API Key、手机授权数据、设备私钥和真实业务数据。
• 任何带真实密钥的 .env、配置备份或日志。