12 KiB
手机远程控制台上线包(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
已同步到"生产 + 本次改动"(后两个文件本地原本只是落后于生产,同步没有丢任何本地内容)。
上线顺序
- 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 执行后它们就不再是"全部菜单"。 - 本包(下文步骤)。
- 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。 - 桌面端 1.5.1(
C:/wechat_rpa):build_windows_exe.ps1→build_installer.ps1,在管理端 「版本升级」先按小比例灰度发布。旧版桌面端在手机上显示"版本过低",不会收到指令。 - 灰度:在 ZYT 角色管理里先给 1~2 位客服所在角色勾选
wecom_rpa.remote/control、wecom_rpa.blacklist/add,主管角色加wecom_rpa.blacklist/remove(需要跨账号控制再加wecom_rpa.remote/all);试用无问题再全员放开。
上传(内网模式:SSH 绑定有线网卡)
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'
部署(在服务器上依次执行)
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。不登录、不读取任何聊天或患者数据。
手动回滚:
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、vitest6 项、生产构建通过;浏览器端到端(假 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可在后续加列展示。