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

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

## 一、本次更新目标

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

## 二、本次更新内容

| 分类 | 更新内容 | 对应文档 |
|---|---|---|
| 手机安装 | 补齐 Agent APK 安装、权限、自启动、设备绑定和真机安全边界 | [三端安装与纯客宝对接配置手册](../../9、手册/02-操作指南/工作手机三端安装与纯客宝对接配置手册_20260711.md) |
| SDK 部署 | 固化 Docker Compose、健康检查、端口、环境变量和回滚方式 | [工作手机 SDK 存客宝宝塔部署总方案](工作手机SDK_存客宝宝塔部署总方案.md) |
| 服务器接入 | 固化宝塔 Nginx HTTPS/WSS 反向代理，明确 `/ws/` 升级头要求 | [部署总方案](工作手机SDK_存客宝宝塔部署总方案.md) |
| 业务对接 | 固化 BFF 鉴权、设备映射、读类优先和受控写类验收顺序 | [三端安装与纯客宝对接配置手册](../../9、手册/02-操作指南/工作手机三端安装与纯客宝对接配置手册_20260711.md) |
| 规则 | 明确仅使用自有/授权设备，生产密钥只从服务器环境注入，禁止把真密钥写入文档或仓库 | 本文第五节 |
| 验收 | 更新本机已验证、线上未部署、真机待复验的边界，禁止把本机通过当作线上已上线 | [部署验收记录](部署验收记录.md) |
| 仓库 | 本次说明文档随代码提交到公司 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](../README.md)
- 手机与 BFF：[工作手机三端安装与纯客宝对接配置手册](../../9、手册/02-操作指南/工作手机三端安装与纯客宝对接配置手册_20260711.md)
- 宝塔部署：[工作手机 SDK 存客宝宝塔部署总方案](工作手机SDK_存客宝宝塔部署总方案.md)
- 验收记录：[部署验收记录](部署验收记录.md)
- 项目变更：[10、项目管理/开发进度总表](../../10、项目管理/开发进度总表.md)
