siyu-bank/workphone-sdk
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: publish workphone SDK deployment and API docs

Browse Source
This commit is contained in:
Manus AI
2026-07-14 18:10:52 +08:00
commit 021d633cc1
534 changed files with 122391 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

173
开发文档/5、接口/02-业务对接/工作手机SDK公网API对接文档_20260714.md Normal file
View File

@@ -0,0 +1,173 @@
# 工作手机 SDK 公网 API 对接文档
> 更新：2026-07-14
> 生产地址：`https://wpsdk.quwanzhi.com`
> OpenAPI：`https://wpsdk.quwanzhi.com/openapi.json`
> Swagger：`https://wpsdk.quwanzhi.com/docs`
## 1. 对接条件
- 所有业务接口使用 HTTPS；手机主动连接使用 WSS。
- 外部应用从服务器安全环境读取 API Key，请勿写入前端源码、APK、日志或仓库。
- 请求头：`X-API-Key: <由运维安全提供>`；也兼容 `Authorization: Bearer <API_KEY>`。
- 当前生产真机 ID：`xgfe65eimrrofyws`；MD5：`ed25814d9c92b3430696dc96c2142b5f`。
- 健康探针 `/health`、`/ready` 无需 Key；控制接口无 Key或错误 Key均返回 401。
## 2. 最小调用样例
### curl
```bash
export WORKPHONE_URL='https://wpsdk.quwanzhi.com'
export WORKPHONE_API_KEY='<从服务器密钥管理获取>'
curl -fsS "$WORKPHONE_URL/api/v3/devices" \
-H "X-API-Key: $WORKPHONE_API_KEY"
curl -fsS -X POST "$WORKPHONE_URL/api/v3/hook/execute" \
-H "X-API-Key: $WORKPHONE_API_KEY" \
-H 'Content-Type: application/json' \
-d '{"device_id":"xgfe65eimrrofyws","platform":"wechat","action":"ping","params":{}}'
```
### JavaScript / Node.js
```js
const response = await fetch(`${process.env.WORKPHONE_URL}/api/v3/hook/execute`, {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'X-API-Key': process.env.WORKPHONE_API_KEY,
},
body: JSON.stringify({
device_id: 'xgfe65eimrrofyws',
platform: 'wechat',
action: 'get_profile',
params: {},
}),
});
if (!response.ok) throw new Error(`WorkPhone HTTP ${response.status}`);
const result = await response.json();
```
### Python
```python
import os
import requests
result = requests.post(
f"{os.environ['WORKPHONE_URL']}/api/v3/hook/execute",
headers={"X-API-Key": os.environ["WORKPHONE_API_KEY"]},
json={
"device_id": "xgfe65eimrrofyws",
"platform": "wechat",
"action": "get_contacts",
"params": {"limit": 20},
},
timeout=35,
)
result.raise_for_status()
print(result.json())
```
## 3. 核心接口
| 用途 | 方法与路径 | 说明 |
|---|---|---|
| 健康 | `GET /health` | 服务状态与在线设备数，无需 Key |
| 就绪 | `GET /ready` | 数据库与服务启动门禁，无需 Key |
| 设备列表 | `GET /api/v3/devices` | WS/ADB 统一设备列表 |
| 设备详情 | `GET /api/v3/devices/{device_id}` | 项目、能力、连接信息 |
| 当前应用 | `GET /api/v3/adb/devices/{device_id}/app/current` | WS 设备也支持 |
| 启动应用 | `POST /api/v3/adb/devices/{device_id}/app/start` | Body：`{"package":"com.tencent.mm"}` |
| 真机截图 | `POST /api/v3/adb/devices/{device_id}/screenshot` | 返回 PNG Base64 |
| UI 树 | `GET /api/v3/adb/devices/{device_id}/ui-tree` | MIUI 状态变化时可能受系统限制 |
| 微信统一执行 | `POST /api/v3/hook/execute` | 推荐的单设备微信 RPC 入口 |
| 批量执行 | `POST /api/v3/fleet/execute` | 多设备、项目或全部在线设备 |
| 能力清单 | `GET /api/v3/wechat/actions` | 读取服务器当前动作清单 |
### 截图响应与解码
```json
{
"code": 200,
"message": "ok",
"data": {
"image_base64": "<PNG_BASE64>",
"mime_type": "image/png",
"size": 245296,
"path": "<手机应用缓存路径>"
},
"channel_used": "websocket/agent"
}
```
```js
const png = Buffer.from(result.data.image_base64, 'base64');
```
## 4. 已验收的微信读类动作
以下动作于 2026-07-14 通过公网域名真实调用，通道均为 `server/frida`：
`ping`、`get_hook_status`、`get_wechat_version`、`get_process_info`、`get_profile`、`check_account_status`、`get_device_info`、`get_network_info`、`get_storage_info`、`get_contacts`、`get_groups`、`get_labels`、`get_recent_messages`、`get_safety_center`、`check_restrictions`。
调用格式统一：
```json
{
"device_id": "xgfe65eimrrofyws",
"platform": "wechat",
"action": "get_wechat_version",
"params": {}
}
```
## 5. 批量调用
```json
POST /api/v3/fleet/execute
{
"device_ids": ["xgfe65eimrrofyws"],
"platform": "wechat",
"action": "get_profile",
"params": {},
"hook_only": true,
"timeout": 60,
"max_concurrency": 3
}
```
涉及发消息、发朋友圈、好友、群、支付、账号资料修改等写类操作时，调用方必须增加业务审批、目标白名单、幂等键、审计日志和人工确认，不允许仅凭 HTTP 200 判断业务成功。
## 6. 浏览器跨域
生产服务已放行标准 OPTIONS 预检；真实 GET/POST 仍要求 API Key。验证结果：
- `OPTIONS /api/v3/devices`：200；
- `Access-Control-Allow-Origin`：回显请求 Origin；
- `Access-Control-Allow-Headers`：包含 `X-API-Key`。
不建议把长期 API Key 放在浏览器；正式业务应由存客宝 BFF 代调。
## 7. 错误处理
| HTTP | 含义 | 调用方处理 |
|---:|---|---|
| 400/422 | 动作或参数错误 | 不重试，修正请求 |
| 401 | API Key 缺失或错误 | 停止调用并告警 |
| 404 | 设备或路径不存在 | 刷新设备列表 |
| 429 | 风控暂停或限流 | 按业务策略延迟 |
| 503 | 设备 WS、Frida 隧道或 Hook 不在线 | 指数退避，先查 `/health` 与设备状态 |
| 500 | 服务端或 RPC 执行异常 | 记录 request ID，有限重试 |
成功判定必须同时检查 HTTP 状态、`code`、`success`、`channel_used` 及动作业务字段；截图还要检查 `data.image_base64` 非空。
## 8. 安全与生产边界
- API Key 与手机 pairing token 必须分离，禁止相互替代。
- pairing token 只用于手机 WSS 绑定，不提供给业务调用方。
- 当前 Frida 经手机→443/WSS→宝塔反向隧道，公网不开放 Frida 端口。
- 微信 8.0.69、Android 13、Agent 5.0.1 已验收。
- 朋友圈图文发布在本轮两次返回“内容未发表”，不能标记成功；其他写类需要白名单逐项确认。

80
开发文档/5、接口/06-验收与矩阵/2026-07-14_公网SDK完整测试汇总.md Normal file
View File

@@ -0,0 +1,80 @@
# 2026-07-14 公网 SDK 完整测试汇总
## 结论
生产 SDK、WSS、宝塔 Frida RPC、15 项微信读类、应用启动、当前应用、真机截图、UI 树、鉴权与 CORS 已通过。朋友圈发布两次失败；其他对外写类尚需确认后执行，不能纳入“全功能成功”。
## 环境
| 项目 | 当前值 |
|---|---|
| 生产地址 | `https://wpsdk.quwanzhi.com` |
| 设备 | Redmi 2312DRAABC / Android 13 |
| 设备 ID | `xgfe65eimrrofyws` |
| 设备 MD5 | `ed25814d9c92b3430696dc96c2142b5f` |
| 微信 | 8.0.69 |
| Agent | 5.0.1 |
| 项目 | `cunkebao` |
| Hook | 宝塔 `server/frida`，96 actions / 26 modules |
## 测试结果
| 分类 | 通过 | 失败/待确认 | 状态 |
|---|---:|---:|---|
| 服务健康与就绪 | 2 | 0 | ✅ |
| 微信安全读类 | 15 | 0 | ✅ |
| 设备控制 | 4 | 0 | ✅ 修复后复验 |
| 外部鉴权 | 4 | 0 | ✅ |
| 浏览器 CORS | 1 | 0 | ✅ 修复后复验 |
| 5 路并发 ping | 5 | 0 | ✅ 全部 HTTP 200 |
| 朋友圈发布 | 0 | 2 次失败 | ❌ 微信提示内容未发表 |
| 其他写类 | 0 | 待人工确认 | ⏳ |
### 微信读类
全部 HTTP 200，通道 `server/frida`：`ping`、`get_hook_status`、`get_wechat_version`、`get_process_info`、`get_profile`、`check_account_status`、`get_device_info`、`get_network_info`、`get_storage_info`、`get_contacts`、`get_groups`、`get_labels`、`get_recent_messages`、`get_safety_center`、`check_restrictions`。
### 设备控制
- `app_start`：通过，公网启动微信。
- `app_current`：初测 404；增加 WS fallback 后 HTTP 200。
- `screenshot`：初测假成功无图片；APK 增加 PNG Base64 后通过，1080×2400。
- `ui_tree`：本轮 HTTP 200；MIUI 特定页面仍可能限制 uiautomator，必须检查正文。
截图证据：`开发文档/8、部署/06-存客宝宝塔/images/公网API真机截图_20260714.png`。
### 鉴权与 CORS
- `/health` 无 Key：200。
- `/api/v3/devices` 无 Key：401；错误 Key：401；正确 Key：200。
- 不存在设备：404“设备不存在”。
- OPTIONS 初测 401；放行预检后复验 200，允许 `X-API-Key`。
- 5 路公网并发 `ping` 全部 HTTP 200，耗时约 3.31 秒，通道均为 `server/frida`；测试后设备仍在线。
### 朋友圈失败
- 配图、文字、公开范围均完成。
- 首次发表及重新发送均提示“内容未发表”。
- 证据：`朋友圈首次发布失败_20260714.png`、`朋友圈重试失败_20260714.png`。
## 本轮修复
1. 控制台统一附加 API Key，401 不再伪装成“0 台设备”。
2. 宝塔侧增加真实 Frida Session/RPC 桥。
3. `/app/current` 对 WS 设备增加 fallback。
4. Android 截图返回完整 PNG Base64，并改用应用缓存解决读取权限。
5. API 鉴权中间件放行 CORS OPTIONS 预检。
6. Android 前台服务增加 AgentEngine 单实例锁，避免重复 START 创建两条 WS。
## 当前错误与风险
| ID | 问题 | 影响 | 当前状态 |
|---|---|---|---|
| `SNS-01` | 朋友圈内容上传失败 | 朋友圈写类不可交付 | 待查账号限制/上传网络 |
| `WS-01` | SDK 重启后曾出现双 Engine | 设备短时离线 | 已修，持续观察 |
| `MIUI-01` | MIUI 普通 ADB/ATX 注入受限 | UI 自动化不稳定 | Root sendevent 可兜底 |
| `WRITE-01` | 发消息等写类未获本轮确认 | 不能声称全量通过 | 等待白名单测试 |
## 验收口径
“HTTP 200”不等于业务成功。必须检查业务字段、通道、真实数据或截图。朋友圈按失败记录；未测试写类不做成功结论。

BIN
开发文档/8、部署/06-存客宝宝塔/images/公网API真机截图_20260714.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 240 KiB

BIN
开发文档/8、部署/06-存客宝宝塔/images/工作手机新图标_20260714.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 270 KiB

BIN
开发文档/8、部署/06-存客宝宝塔/images/工作手机新图标真机桌面_20260714.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 2.3 MiB

BIN
开发文档/8、部署/06-存客宝宝塔/images/朋友圈重试失败_20260714.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 894 KiB

BIN
开发文档/8、部署/06-存客宝宝塔/images/朋友圈首次发布失败_20260714.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 1.1 MiB

66
开发文档/8、部署/06-存客宝宝塔/交付更新说明_20260712.md Normal file
View File

@@ -0,0 +1,66 @@
# 工作手机 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)

64
开发文档/8、部署/06-存客宝宝塔/公司NAS_WebStation与工作手机SDK配置.md Normal file
View File

@@ -0,0 +1,64 @@
# 公司 NAS Web Station 与工作手机 SDK 配置
> 更新：2026-07-12
## 结论
工作手机 SDK 是 FastAPI + WebSocket 服务，不能直接作为 PHP 网站放进 Web Station 的站点根目录运行。正确分工是：
```text
Container Manager
└─ workphone-sdk-nas :8899 ← FastAPI、控制台、WebSocket、Mongo、Redis
DSM 登录门户/反向代理（可选）
└─ workphone 域名 :443 ← 反代到 127.0.0.1:8899
Web Station（可选）
└─ 仅放静态说明页、下载页或前端构建产物
```
## NAS 已登记的运行目录
- 项目目录：`/volume1/docker/workphone-sdk`
- Compose：`docker-compose.nas.yml`
- SDK：`workphone-sdk-nas`
- 控制台：`http://192.168.110.101:8899/hub`
- 健康检查：`http://192.168.110.101:8899/health`
- WebSocket：`ws://192.168.110.101:8899/ws/device/{device_id}`
## Container Manager 操作
在 DSM → Container Manager → 项目中打开 `workphone-sdk`：
1. 项目路径选择 `/volume1/docker/workphone-sdk`。
2. Compose 文件选择 `docker-compose.nas.yml`。
3. 确认 `.env` 保留在 NAS，不从本机覆盖。
4. 点击“构建”并“启动”。
5. 等待 `workphone-mongo-nas` 健康后，再确认 `workphone-sdk-nas` 为运行中。
6. 查看日志，确认没有 Mongo/Redis 连接错误。
## Web Station 配置建议
如果只需要访问 SDK 控制台，不必建立 Web Station 网站，直接使用 NAS 内网 8899 即可。
如果需要统一域名和 HTTPS：
1. 在 DSM → 控制面板 → 登录门户 → 高级 → 反向代理新增规则。
2. 来源协议 HTTPS、来源主机填 SDK 域名、来源端口 443。
3. 目标协议 HTTP、目标主机 `127.0.0.1`、目标端口 `8899`。
4. 开启 WebSocket 支持；`/ws/` 不能被静态站点规则吞掉。
5. 手机 Agent 地址改为 `wss://<SDK域名>/ws/device/{device_id}`。
## 验收
```bash
curl -fsS http://192.168.110.101:8899/health
curl -fsS http://192.168.110.101:8899/ready
curl -fsS http://192.168.110.101:8899/api/v3/integration/manifest
```
页面验收：`/hub` 可打开；容器重启后 SDK 自动恢复；手机 Agent 能上线并持续心跳；存客宝 BFF 能通过 API Key 访问 SDK。
## 当前状态
2026-07-12 已从本机同步最小运行集到 NAS 目录，并保留 NAS 原有 `.env`。由于当前 SSH 用户无法通过 sudo 操作 Container Manager，容器启动尚未完成；不把“文件已同步”标记为“服务已上线”。

66
开发文档/8、部署/06-存客宝宝塔/工作手机SDK_存客宝宝塔部署总方案.md Normal file
View File

@@ -0,0 +1,66 @@
# 工作手机 SDK · 存客宝宝塔部署总方案
> 版本：v1.1 · 更新：2026-07-14 · 当前线上域名：`https://wpsdk.quwanzhi.com`
## 1. 目标架构
```text
手机 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 反代核心配置
```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. 验收命令
```bash
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 读类与受控写类不能据此宣称全绿，须继续按验收记录复测。

94
开发文档/8、部署/06-存客宝宝塔/线上部署与真机验收_20260714.md Normal file
View File

@@ -0,0 +1,94 @@
# 工作手机 SDK · 线上部署与真机验收（2026-07-14）
## 目标与结果
将工作手机 SDK 部署到存客宝宝塔 Docker，通过 `wpsdk.quwanzhi.com` 提供 HTTPS/WSS，让授权 Redmi 真机扫码/配置后主动连接，并验证设备管理与微信安全读类链路。
当前结论：线上服务、鉴权、CORS、WSS 真机、设备控制、宝塔 Frida RPC 和 15 项微信读类均已通过；朋友圈发布失败，其他写类仍需白名单逐项验收。
## 线上架构
```text
Android 工作手机
└─ WSS + pairing token
└─ wpsdk.quwanzhi.com:443（宝塔 Nginx / TLS）
└─ 127.0.0.1:8899（workphone-sdk-baota）
├─ workphone-mongo-baota
└─ workphone-redis-baota
纯客宝/存客宝 BFF
└─ HTTPS + X-API-Key → wpsdk.quwanzhi.com/api/v3/
```
## 实际部署文件
- `sdk/docker-compose.baota.yml`：宝塔生产 Compose。
- `sdk/.env.baota.example`：仅变量模板，无真实密钥。
- `sdk/deploy/baota/wpsdk.quwanzhi.com.conf`：HTTPS/WSS 反代。
- `sdk/scripts/deploy_baota_wpsdk.sh`：上传、构建、启动、证书与 Nginx 校验。
- 服务器目录：`/www/wwwroot/workphone-sdk`。
## 手机绑定
生产二维码由受 API Key 保护的 `/api/v3/qrcode/generate` 生成，内容至少包含：
- `server`: `wss://wpsdk.quwanzhi.com/ws/device`
- `project`: `cunkebao`
- `pairing_token`: 仅服务器环境注入
手机端点击“扫描系统二维码”完成绑定。二维码含配对令牌，禁止截图入库、发群或写进文档。
## 验收证据
| 层级 | 结果 |
|---|---|
| DNS | `wpsdk.quwanzhi.com` → `42.194.245.239` |
| 容器 | Mongo、Redis、SDK 均 healthy |
| SDK | `/health` healthy，`/ready` true |
| 安全 | 无 Key 401；有 Key 200；8899 仅绑定本机 |
| TLS | Let's Encrypt，证书有效至 2026-09-25 |
| 真机 | Redmi 2312DRAABC / Android 13 / Agent 5.0.1 |
| WSS | 真机在公网 SDK 显示 online |
| 设备 ID | 管理与业务字段提供 MD5：`ed25814d9c92b3430696dc96c2142b5f` |
| 微信读类 | `ping` 与 `get_wechat_version` 均由公网 Fleet→WSS→APK 成功回执；微信 8.0.69 |
| 密钥保护 | 日志与 API 不回显配对令牌 |
| 令牌轮换 | 本轮曾进入调试输出的旧配对令牌已撤销；新令牌已下发并重新绑定成功 |
| Frida 服务 | Root 可用，Frida 16.5.6 在非默认端口可达，APK 回执 `frida_server_ready=true` |
| 微信 Hook/RPC | 宝塔 `server/frida` 已持有微信 Session 并取得真实 RPC 回执，能力目录为 96 actions / 26 modules |
| 微信读类 | 15 项公网读类均 HTTP 200：资料、联系人、群、标签、近期消息、账号安全及设备信息等 |
| 设备控制 | 启动应用、当前应用、UI 树、1080×2400 PNG 截图均已通过 |
| 浏览器调用 | CORS OPTIONS=200，允许外部网页携带 `X-API-Key` |
| 并发 | 5 路公网 `ping` 并发 5/5 HTTP 200，通道均为 `server/frida` |
## 安全调用样例
```bash
curl -fsS https://wpsdk.quwanzhi.com/health
curl -fsS https://wpsdk.quwanzhi.com/ready
curl -X POST https://wpsdk.quwanzhi.com/api/v3/fleet/execute \
-H 'X-API-Key: <从服务器安全环境获取>' \
-H 'Content-Type: application/json' \
-d '{
"device_ids": ["<device_id>"],
"platform": "wechat",
"action": "get_wechat_version",
"params": {}
}'
```
## 回滚
1. 只处理 `/www/wwwroot/workphone-sdk` 与 `wpsdk.quwanzhi.com` 独立站点，不改存客宝其他容器。
2. 在服务器目录使用上一个发行包/镜像重新执行 Compose。
3. 执行 `nginx -t` 后再 reload。
4. 验证原有宝塔站点、SDK `/health` 和手机重连。
## 未完成边界
- APK 面板中的本地 Hook 状态与宝塔 `server/frida` 是两条通道；本轮以服务器真实 Session/RPC 回执验收，不能把 APK 面板灰色误判为服务器 RPC 失效。
- 朋友圈图文发布两次均由微信提示“内容未发表”，按失败记录，未伪报成功。
- 发消息、群发、加友、朋友圈互动等写类仍需测试白名单和操作前确认。
- 还需完成纯客宝/存客宝 BFF 业务页面验收及 24 小时稳定性。
完整明细：[公网 SDK 完整测试汇总](../../../5、接口/06-验收与矩阵/2026-07-14_公网SDK完整测试汇总.md)；外部调用：[公网 API 对接文档](../../../5、接口/02-业务对接/工作手机SDK公网API对接文档_20260714.md)。

44
开发文档/8、部署/06-存客宝宝塔/部署前置条件与端口清单.md Normal file
View File

@@ -0,0 +1,44 @@
# 工作手机 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 或设备端口。
```ini
WORKPHONE_SDK_URL=https://wpsdk.quwanzhi.com
WORKPHONE_SDK_API_KEY=<服务器环境变量注入>
WORKPHONE_DEVICE_PAIRING_TOKEN=<服务器环境变量注入>
```
## 4. 禁止入库内容
- 宝塔账号、SSH 密码、宝塔 API Key、MongoDB/Redis 密码。
- 生产 API Key、手机授权数据、设备私钥和真实业务数据。
- 任何带真实密钥的 `.env`、配置备份或日志。

47
开发文档/8、部署/06-存客宝宝塔/部署验收记录.md Normal file
View File

@@ -0,0 +1,47 @@
# 工作手机 SDK · 存客宝宝塔部署验收记录
> 更新：2026-07-14 · 状态：线上 SDK、真机 WSS、服务器 Frida RPC 与安全读类已通过；写类继续验收
## 0. 2026-07-14 本轮更新
- 部署目录：`/www/wwwroot/workphone-sdk`；Compose：`docker-compose.baota.yml`。
- 公网域名：`https://wpsdk.quwanzhi.com`；手机地址：`wss://wpsdk.quwanzhi.com/ws/device`。
- API Key 鉴权与设备配对令牌分离；令牌已从客户端日志和管理 API 响应中脱敏。
- 调试阶段进入输出的旧配对令牌已在服务器轮换撤销，真机使用新令牌重新绑定成功。
- Android Agent 5.0.1 已覆盖安装到授权 Redmi 真机并自动重连。
## 1. 当前证据
| 检查项 | 结果 | 证据 |
|---|---|---|
| 宝塔 Compose | ✅ | Mongo、Redis、SDK 三容器均 healthy |
| 本机绑定端口 | ✅ | SDK 仅 `127.0.0.1:8899`，公网不直暴露 8899 |
| 公网健康 | ✅ | `/health` healthy；`/ready` true |
| HTTPS 证书 | ✅ | Let's Encrypt，CN=`quwanzhi.com`，有效至 2026-09-25 |
| API 鉴权 | ✅ | 无 Key `/api/v3/devices`=401；带 Key=200 |
| WSS 真机 | ✅ | Redmi 2312DRAABC，Android 13，公网在线 |
| 设备 MD5 | ✅ | `ed25814d9c92b3430696dc96c2142b5f` |
| 微信版本读类 | ✅ | Fleet 真链路返回微信 8.0.69，`channel=no_root_pkg` |
| 配对令牌脱敏 | ✅ | 日志及设备 API 均不含 `?token=`/`pairing_token` |
| Frida 服务 | ✅ | Root 可用；Frida 16.5.6 非默认端口可达；公网回执 `frida_server_ready=true` |
| 微信 Hook/RPC | ✅ | 宝塔 `server/frida` 取得真实 RPC 回执，96 actions / 26 modules |
| 微信读类 | ✅ | 15 项读类 HTTP 200，覆盖资料、联系人、群、标签、消息、安全与设备信息 |
| 设备控制 | ✅ | 启动应用、当前应用、UI 树、PNG 真机截图修复后复验通过 |
| 外部网页调用 | ✅ | API Key 鉴权正确；CORS OPTIONS=200；5 路并发 5/5 通过 |
| 朋友圈发布 | ❌ | 两次均提示“内容未发表”，截图已归档，不计成功 |
| 其他写类 | ⏳ | 发消息、群发、加友、朋友圈互动需白名单和操作前确认 |
## 2. 已整理
- 宝塔部署架构、端口、环境变量、Nginx WebSocket 配置和验收顺序。
- 设备主动上报主链路与平台拉取兜底链路。
- 存客宝 BFF 统一鉴权与设备绑定字段要求。
## 3. 待继续
- 使用白名单目标完成单聊、群消息、加友和朋友圈互动等受控写类回执。
- 排查朋友圈上传失败原因，并以微信最终页面和 API 回执双重验收。
- 配置纯客宝/存客宝 BFF 的 `WORKPHONE_SDK_URL` 与服务器 API Key，并验证业务端设备状态。
- 执行 24 小时稳定性与服务器重启后的容器自启、真机自动重连验收。
真实密钥只保存在服务器 `.env`；二维码中含短期/生产配对令牌，不写入文档或仓库。