workphone-sdk/开发文档/8、部署/06-存客宝宝塔/交付更新说明_20260712.md

工作手机 SDK · 2026-07-12 交付更新说明

更新日期：2026-07-12
适用版本：工作手机 SDK、手机 Agent、工作手机中台、存客宝/纯客宝 BFF
文档状态：已整理，可用于公司 Gitea 代码交接；线上宝塔部署仍以验收记录为准

一、本次更新目标

把工作手机项目的手机安装、服务器部署、存客宝/纯客宝对接、运行规则和验收边界统一整理到开发文档，便于研发、运维和后续接手人员按同一套步骤执行。

二、本次更新内容

分类	更新内容	对应文档
手机安装	补齐 Agent APK 安装、权限、自启动、设备绑定和真机安全边界	三端安装与纯客宝对接配置手册
SDK 部署	固化 Docker Compose、健康检查、端口、环境变量和回滚方式	工作手机 SDK 存客宝宝塔部署总方案
服务器接入	固化宝塔 Nginx HTTPS/WSS 反向代理，明确 /ws/ 升级头要求	部署总方案
业务对接	固化 BFF 鉴权、设备映射、读类优先和受控写类验收顺序	三端安装与纯客宝对接配置手册
规则	明确仅使用自有/授权设备，生产密钥只从服务器环境注入，禁止把真密钥写入文档或仓库	本文第五节
验收	更新本机已验证、线上未部署、真机待复验的边界，禁止把本机通过当作线上已上线	部署验收记录
仓库	本次说明文档随代码提交到公司 Gitea siyu-bank/workphone-sdk	项目根目录 Git 远程

三、手机安装步骤

1. 使用公司自有或明确授权的 Android 工作机。
2. 安装 sdk/releases/20260711/workphone-agent-v5.0.1-release.apk，并按交付手册核对 SHA-256。
3. 开启网络、自启动、后台无限制、通知、无障碍和项目所需权限。
4. 配置 SDK 的 HTTPS/WSS 地址，完成设备注册。
5. 在 SDK 控制台确认 device_id、Agent WS、Hook/Frida、微信状态和最后心跳。
6. 将 device_id 绑定到纯客宝/存客宝；先做状态和读类验证，最后才做测试白名单内的受控写类验证。

四、服务器部署步骤

1. 在宝塔服务器做只读检查：系统、磁盘、Docker、端口、防火墙、现有站点和数据库。
2. 为工作手机 SDK 使用独立目录和独立站点，确认 8899 不与现有服务冲突。
3. 上传代码或发行包，不上传本机 .env、密钥、数据库备份和临时日志。
4. 通过服务器安全环境注入 API_KEY、MONGO_URI、MONGO_DB、REDIS_URL、WORKPHONE_REGISTRY_TOKEN 等变量。
5. 执行 Compose 配置检查、构建和启动，确认容器监听 127.0.0.1:8899。
6. 宝塔 Nginx 以 HTTPS 反代 SDK；/ws/ 必须透传 Upgrade 和 Connection: upgrade。
7. 按“健康检查 → BFF 鉴权 → 设备 WSS 上线与心跳 → 读类 → 受控写类回执”的顺序验收。
8. 重启服务器和手机后复验容器自启、设备重连、日志和回滚路径。

五、运行与安全规则

• 只操作公司自有或明确授权的设备、账号、联系人、群和测试数据。
• Root、Frida、ADB、Hook 仅用于授权测试和设备运维；没有真机证据不得标记为完成。
• 前端不得直接调用 Frida、ADB 或手机底层；统一经 BFF 和 SDK 标准接口。
• 生产密钥、数据库密码、令牌、账号口令只从服务器环境变量或密钥管理系统注入。
• 读类通过后再做写类；写类必须有白名单、测试对象、请求回执和可回滚记录。
• /health、/ready、设备心跳和 BFF 鉴权异常必须真实暴露，不得用假成功状态掩盖离线。
• 线上未建立远程管理证据时，只能记录“本机已验证”，不能写成“服务器已上线”。
• 更新和部署均保留日期、提交号、变更内容、验收证据和未完成项。

六、2026-07-12 验证边界

• 本机 SDK 健康检查、Compose 配置、集成契约和中台构建已有记录。
• 宝塔公网管理面、线上 SDK/WSS、真实在线手机和 24 小时稳定性仍需在远程管理通道恢复后复验。
• 本文不宣称线上已经部署完成；线上状态以 部署验收记录.md 的最新证据为准。

七、接手入口

• 总入口：8、部署 README
• 手机与 BFF：工作手机三端安装与纯客宝对接配置手册
• 宝塔部署：工作手机 SDK 存客宝宝塔部署总方案
• 验收记录：部署验收记录
• 项目变更：10、项目管理/开发进度总表