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

12 KiB
Raw Blame History

手机远程控制台上线包(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 绑定有线网卡)

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、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 可在后续加列展示。