Files
kefu/deploy/mobile-remote-20260928/RELEASE.md
T
2026-09-29 15:52:07 +08:00

133 lines
12 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 手机远程控制台上线包(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` 可在后续加列展示。