# 工作手机 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 读类与受控写类不能据此宣称全绿，须继续按验收记录复测。
