133 lines
12 KiB
Markdown
133 lines
12 KiB
Markdown
# 手机远程控制台上线包(mobile-remote-20260928)
|
||
|
||
状态:**管理端已于 2026-09-28 15:21 部署到生产并验证通过(记录:`C:/kefu/deploy/mobile-remote-deployed.md`)。ZYT 由 ZYT 团队自行发布;桌面端 1.5.1 由管理员在「版本升级」发布。**
|
||
|
||
## 本包内容(管理端服务器 `/opt/im-admin`)
|
||
|
||
| 类型 | 文件 | 说明 |
|
||
|---|---|---|
|
||
| 替换 | `wechat_rpa/admin_api.py` | 注册手机 / 命令通道路由;`/m/` 静态托管;强制下线、停用账号时同时收回手机会话;客户端账号列表多返回 `mobile_session_count` |
|
||
| 替换 | `wechat_rpa/zyt_auth.py` | 新增终端 9 的代登(`login_admin`)、身份复核(`verify_admin_session`)、注销;桌面端原有校验不变 |
|
||
| 新增 | `wechat_rpa/remote_api.py` | `/api/v2/mobile/*`、`/api/v2/desktop/commands/*`、`/api/v2/desktop/status`、`/api/v2/desktop/blacklist*` |
|
||
| 新增 | `wechat_rpa/remote_store.py` | 4 张新表的数据层 |
|
||
| 新增 | `admin-web/apps/mobile-h5/dist/` | 手机 / 平板 H5(`/m/`) |
|
||
| 替换 | `deploy/im-admin/Dockerfile` | 以后整包重建时把 mobile-h5 一起打进镜像 |
|
||
|
||
数据库:启动时 `CREATE TABLE IF NOT EXISTS` 新增 `mobile_sessions`、`desktop_commands`、`desktop_status`、
|
||
`conversation_blacklist`,不改任何已有表。回滚保留这些表(旧代码不会读写)。
|
||
|
||
发布包:`mobile-remote-server-bundle.tar.gz`,522,202 字节,SHA-256
|
||
`dc59f2a6278ae04da1f8a4c6193373317126a2fda184cdf3335004cfd06a751e`(由 `prepare_bundle.py` 生成;源码再改动要重新生成并更新这里)。
|
||
服务器上保存为 `mobile-remote-server-bundle-r2.tar.gz`。
|
||
|
||
**生产基线不是 `C:/kefu` 的 HEAD**:2026-09-23 的 COS 直传发布从 `C:/wechat_rpa/tmp/cos-direct-server-payload`
|
||
替换了生产的 `admin_api.py`、`archive_store.py`(CRLF 换行)。`baseline-snapshot/` 保存了生产上被替换 3 个文件的原样字节,
|
||
`server-baseline.json` 记录其哈希,预检脚本在宿主和容器内再核对一遍,任何漂移即停止。本包的 `admin_api.py`
|
||
= 生产版 + 本次改动(三方合并无冲突;`prepare_bundle.py` 每次打包都重做"HEAD→生产"合并并要求结果不变,
|
||
防止落后的本地副本把生产改动冲掉)。`C:/kefu/wechat_rpa` 的 `admin_api.py`、`archive_store.py`、`archive_api.py`
|
||
已同步到"生产 + 本次改动"(后两个文件本地原本只是落后于生产,同步没有丢任何本地内容)。
|
||
|
||
## 上线顺序
|
||
|
||
1. **ZYT(`C:/zyt`,单独仓库,ZYT 团队自行发布)**:已提交到 `master`(`694c83dc7`、`3cdc812f2`),参考副本见
|
||
`zyt/`:新增终端 9、`LoginValidate` 接受 9、`/adminapi/desktop/session` 同时接受 7 和 9 并返回真实终端;
|
||
`add_wecom_rpa_remote_menu.sql`(隐藏目录"企微客服助手"下 4 个按钮权限,默认不授予任何角色)。
|
||
终端 8 已被 ZYT 的 AI 浏览器占用,所以用 9。ZYT 上线前手机登录会提示
|
||
"ZYT 尚未开通企微客服手机端登录(终端 9)",其余功能不受影响(管理端可以先于 ZYT 上线)。
|
||
**SQL 必须和终端 9 代码同一次上线(或更早)**:ZYT 对"拥有全部菜单"的角色返回 `*`,新菜单项不存在时
|
||
这类角色会被客服后台当成全权限(可控制所有电脑、移出黑名单);SQL 执行后它们就不再是"全部菜单"。
|
||
2. **本包**(下文步骤)。
|
||
3. **HTTPS 入口**:见 `deploy/im-admin/im.zhenyangtang.cn.https.conf.example`(证书 + 公网端口转发 + Nginx)。
|
||
配好之前只能在内网用 HTTP 登录手机端,公网明文登录会被后台拒绝。上线后用手机 4G(不连公司 Wi-Fi)
|
||
打开 `http://im.zhenyangtang.cn:8369/m/` 试登录,应提示改用 HTTPS:如果能登录,说明路由器端口转发改写了
|
||
来源地址(公网客户端看起来像内网),需要调整转发或把 `MOBILE_REQUIRE_HTTPS` 设为 `always`。
|
||
4. **桌面端 1.5.1**(`C:/wechat_rpa`):`build_windows_exe.ps1` → `build_installer.ps1`,在管理端
|
||
「版本升级」先按小比例灰度发布。旧版桌面端在手机上显示"版本过低",不会收到指令。
|
||
5. **灰度**:在 ZYT 角色管理里先给 1~2 位客服所在角色勾选 `wecom_rpa.remote/control`、
|
||
`wecom_rpa.blacklist/add`,主管角色加 `wecom_rpa.blacklist/remove`(需要跨账号控制再加
|
||
`wecom_rpa.remote/all`);试用无问题再全员放开。
|
||
|
||
## 上传(内网模式:SSH 绑定有线网卡)
|
||
|
||
```bash
|
||
ssh -b 192.168.123.43 ps@192.168.110.111 'mkdir -m 700 /home/ps/mobile-remote-20260928'
|
||
scp -o BindAddress=192.168.123.43 C:/kefu/deploy/mobile-remote-20260928/mobile-remote-server-bundle.tar.gz ps@192.168.110.111:/home/ps/mobile-remote-20260928/
|
||
ssh -b 192.168.123.43 ps@192.168.110.111 'cd /home/ps/mobile-remote-20260928 && echo "dc59f2a6278ae04da1f8a4c6193373317126a2fda184cdf3335004cfd06a751e mobile-remote-server-bundle.tar.gz" | sha256sum -c - && tar -xzf mobile-remote-server-bundle.tar.gz'
|
||
```
|
||
|
||
## 部署(在服务器上依次执行)
|
||
|
||
```bash
|
||
export REMOTE_RELEASE_APPROVED=mobile-remote-20260928
|
||
bash /home/ps/mobile-remote-20260928/01-preflight.sh # 基线核对、备份源文件、打回滚镜像标签
|
||
bash /home/ps/mobile-remote-20260928/02-backup-build.sh # 数据库一致性备份 + 候选镜像 + 离线测试(test_remote_api、test_zyt_auth、test_backend、test_archive_api)
|
||
bash /home/ps/mobile-remote-20260928/03-deploy.sh # 放文件、切镜像、只重建 api 容器、04 验证;失败自动回滚
|
||
```
|
||
|
||
`04-verify.sh` 核对:宿主与容器内文件哈希、api 容器健康且无重启、网关健康、4 个新接口匿名访问返回 401、
|
||
`/m/` 返回入口页、4 张新表存在且 `quick_check` 为 ok。不登录、不读取任何聊天或患者数据。
|
||
|
||
手动回滚:
|
||
|
||
```bash
|
||
REMOTE_RELEASE_APPROVED=mobile-remote-20260928 bash /home/ps/mobile-remote-20260928/rollback.sh
|
||
```
|
||
|
||
## 本地验证记录(2026-09-28)
|
||
|
||
- 管理端后端:`test_admin_api`、`test_archive_api`、`test_zyt_order_api`、`test_zyt_patient_client`、
|
||
`test_zyt_auth`、`test_knowledge`、`test_remote_api` 共 224 项通过。新增的 31 项覆盖:登录限流(含 12 个并发
|
||
错误密码最多 4 个到达 ZYT)、"账号不存在"不耗预算、成功登录清零预算、初始密码拒绝、公网 HTTPS 与缺失
|
||
X-Real-IP 时拒绝明文、ZYT 锁定短路、令牌互不通用、跨账号越权、命令去重 / 取代 / 过期 / 长轮询唤醒、
|
||
黑名单权限与同步、`/m/` 托管(缺失资源 404、防嵌入头)。
|
||
- 代码审查:另起两个独立审查(后台 + H5、桌面端 + ZYT),确认的问题均已修复并补了测试。
|
||
- ZYT:`AdminDesktopAuthContractTest`、`AdminDesktopSessionBehaviorTest` 通过(PHP 8.2);SQL 在 MySQL 5.7
|
||
临时库连续执行两次,结果一致(幂等)。
|
||
- 桌面端:新增 30 项测试(黑名单缓存合并、账号切换改绑、服务端拒收条目、以服务端为准的移出、路由缺失的 404
|
||
不删本机拦截、首个网络失败即停止批量移出、命令通道去重 / 过期 / 服务端时钟 / 同步冷却 / 不空转 / 网络异常
|
||
不退出、超时指令作废,主窗口执行指令时的协议检测等待、先等旧线程退出再启动)。另用真实桌面端代码对接真实
|
||
后台:启动指令 0.3 秒内执行并回执,手机端加入 / 移出黑名单几秒内同步到电脑本地缓存,无权限的电脑端移出被拒绝。
|
||
- H5:`vue-tsc`、`vitest` 6 项、生产构建通过;浏览器端到端(假 ZYT + 真实后台 + 模拟电脑)走通登录、
|
||
错误密码提示、远程停止 / 启动、主管切换客服、黑名单加入 / 移出、平板两栏、深色模式、CSP 下图标正常、
|
||
发版后缺失页面代码时自动刷新一次且不循环。
|
||
|
||
- **按生产基线重建后的候选(2026-09-28)**:生产 104 个后端文件 + 本包 4 个文件,本地跑 `test_remote_api`、
|
||
`test_zyt_auth`、`test_admin_api`、`test_archive_api`、`test_backend` 共 241 项,2 项失败——两项在**未改动的生产代码上
|
||
同样失败**(生产镜像里的 `test_admin_api` 早于 9-23 COS 下载地址改动;`test_backend` 仍按旧的两次请求模拟 ZYT
|
||
会话接口),与本次无关;`C:/kefu` 较新的 `test_backend` 对同一候选 72 项全部通过,随包带上服务器跑。
|
||
|
||
## 行为变化与风险
|
||
|
||
- **移出黑名单以服务端为准**,需要 `wecom_rpa.blacklist/remove`:没有这个权限的客服不能再在电脑上移出已同步的
|
||
黑名单(本机刚加、尚未同步的条目仍可直接移出)。加入黑名单在电脑上不需要 ZYT 权限(拉黑是安全方向),
|
||
在手机上需要 `wecom_rpa.blacklist/add`。
|
||
- **ZYT 按来源 IP 锁定登录**(默认 30 分钟错 5 次锁 30 分钟),手机登录全部从服务器出口 IP 发出。后台限流:
|
||
每账号 5 次 / 10 分钟、每客户端 IP 10 次 / 10 分钟、全局"真正发到 ZYT 的密码错误"4 次 / 30 分钟
|
||
(`MOBILE_LOGIN_UPSTREAM_FAILURE_BUDGET`,0 为关闭),并记住 ZYT 返回的锁定时长不再重试。正在进行中的尝试
|
||
也占名额,并发请求无法一起穿过限流;"账号不存在"不消耗全局预算(ZYT 也不计数),任一次密码正确的登录会
|
||
清零预算(与 ZYT 清零计数一致)。如果服务器和办公电脑共用出口 IP,ZYT 一旦锁定也会影响电脑端登录——
|
||
建议 ZYT 侧评估对该出口 IP 放宽阈值或改为按账号计数。
|
||
- **仍在使用初始密码的 ZYT 账号不能登录手机端**(ZYT 返回 `is_paw=0`),提示先到 ZYT 网页后台改密码。
|
||
- **`/m/` 带 CSP、`X-Frame-Options: DENY`**,不能被其他网站嵌入诱导点击;发版后旧页面请求已不存在的
|
||
资源文件会得到 404,前端自动整页刷新一次加载新版本。
|
||
- **(已被 mobile-http-20260928 取代:16:26 起默认 `never`,内外网都可用 HTTP 登录)** ~~公网明文 HTTP 的手机登录被拒绝~~(`MOBILE_REQUIRE_HTTPS=auto`;`always` / `never` 可覆盖)。判断用 Nginx 写入的
|
||
`X-Real-IP`,不信任客户端自带的 `X-Forwarded-For`。
|
||
- **手机会话**最长 30 天,每 10 分钟向 ZYT 复核一次身份与权限;ZYT 终端 9 令牌默认 8 小时无操作过期,过期后需重新
|
||
登录。ZYT 暂时不可达时沿用上次权限、不强制下线。
|
||
- **只能控制正在运行的程序**(包括收在托盘里);程序没开时手机端显示离线,无法远程拉起。
|
||
- **同一台电脑换了 ZYT 账号登录**:本机黑名单缓存改绑新账号,原账号已同步的条目转为"待上传"继续拦截,并上传到
|
||
新账号名下(主管可在手机端查看、移出),不会因为换号而静默放开。
|
||
- 桌面端通道:长轮询 15 秒(短于容器 20 秒的停机宽限);任何网络异常只退避不退出;指令有效期按服务端时钟判断;
|
||
界面线程 45 秒内没执行的指令会作废,不会在回执"超时"之后又被执行。
|
||
|
||
## 与方案的差异
|
||
|
||
- 手机会话单独建表 `mobile_sessions`,没有在 `desktop_devices` 上加 `client_kind`:`desktop_sessions` 有"每账号只有
|
||
一个有效会话"的唯一索引,手机会话写进去会顶掉值班电脑;分表后两种令牌也天然不能互相冒用。
|
||
- 桌面端长轮询是 `POST /api/v2/desktop/commands/poll`(请求体带状态,最长挂起 15 秒,方案中为 25 秒:
|
||
需要短于容器停机宽限,指令本身靠进程内通知即时送达),另加 `POST /api/v2/desktop/status` 在监听状态变化时立即上报。
|
||
- 黑名单变化不走命令,而是长轮询返回的 `blacklist_version`;桌面端版本不一致时调用
|
||
`POST /api/v2/desktop/blacklist/sync`(补传本机新增 + 拉全量)。
|
||
- ZYT 新权限默认不授予任何角色(与此前新增菜单的做法一致),按"灰度"一步在角色里勾选。
|
||
- vben 管理端页面本次未改动:强制下线按钮已同时收回手机会话,接口多返回的 `mobile_session_count` 可在后续加列展示。
|