m2-gateway agent 发布记录

本页记录公开发布的 m2-gateway agent 版本。版本号符合 SemVer。

下载地址固定指向当前 stable： https://api.gateway.wechas.com/static/m2-gateway.exe （也可通过 Client API 自动获取每台主机专属安装包）

0.3.2 — 2026-05-23

channel: stable SHA-256: 9a4830108d39fcdb2c07a928e41ceee84a5fd3933b3230fcb75e101bcc933de3 大小: 2.69 MB(2,821,120 bytes) 版本固定 URL: /static/m2-gateway-0.3.2.exe 回滚到 0.3.1: /static/m2-gateway-0.3.1.exe

修 P0 bug:0.3.1 在镜像 OOBE finalize 阶段(SetupComplete.cmd 跑 / LocalSystem 身份 / Administrator 未首次互动登录)调 install-template 时,创建 m2-gateway-worker AtLogOn task 失败 exit 31 SCHTASKS_FAILED,导致跨云镜像 provision 链路被卡。0.3.2 是镜像团队的可用版本,强烈推荐立即升级。

根因

install-template 用命令行模式 schtasks /create /sc onlogon ... /it /f,不带 /ru。schtasks 默认绑 caller 身份生成 task XML,LocalSystem 调用时 <UserId> 被 set 成 SYSTEM,但 SYSTEM 不是合法 AtLogOn target → schtasks 报 (40,4):UserId: 失败。

Fixed

  • 改 XML import 路径:install_template::install_worker_task 生成 task XML (UTF-16 LE + BOM,Windows Task Scheduler 强制要求),Principal 用 <GroupId>S-1-5-32-544</GroupId> = BUILTIN\Administrators 内置 SID, 永远存在,不依赖 user profile 初始化。任意 Administrators 组成员登录都触发 worker,符合 0.3.0 设计意图(worker 在 user session 跑)
  • D 兜底:install-template 在创建 worker task 失败时,从 hard error 改为 warn + 继续后续 firewall + service start。host 在中枢可见为 service running + worker task pending 的部分可用状态,避免装机彻底失败 导致 host 完全不上线

验证

dev 机器跑 install-template + schtasks /query /tn m2-gateway-worker /xml:

Run As User: Administrators
Principal: <GroupId>S-1-5-32-544</GroupId>
Trigger:   <LogonTrigger />
Command:   C:\Program Files\m2-gateway\m2-gateway.exe
Arguments: --mode=worker

✅ task 注册成功,绑 group SID 不绑 user account。

升级说明

自动(推荐):0.3.1 主机通过中枢 admin push-upgrade 收 SelfUpdate cmd, 零中断升级。已存在的 m2-gateway-worker task 会被 /f 覆盖更新为新 XML (GroupId Principal),原 user binding 也升级。

镜像团队手动:直接把 0.3.2 binary 打进新镜像(C:\Program Files\m2-gateway\), 配合简化版 SetupComplete.cmd + IMAGE-BUILD-SPEC 跑 Packer。

0.3.1 — 2026-05-22

channel: stable SHA-256: 00338446b1751b7eb9ff1d7b660892afc9f642c0915e5fbfd0d1d9efc1788ae9 大小: 2.69 MB(2,818,048 bytes,跟 0.3.0 持平) 版本固定 URL: /static/m2-gateway-0.3.1.exe(供 pin) 回滚到 0.3.0: /static/m2-gateway-0.3.0.exe

install-template 分级失败码 + 跨云镜像装机链路修复,配合 m2aicli 团队跨云 provision 路径落地。完全向后兼容 0.3.0,无破坏性改动。

兼容性承诺

  • ✅ install-template CLI 老参数集全部保留,语义不变,不加任何参数预校验
  • ✅ setup.conf JSON 字段名 + 类型不变
  • ✅ DPAPI protect 失败仍 warn + 写明文 seed fallback(0.3.0 老行为保留)
  • ✅ ws client 默认协议(L1 secret_key AES-CBC + bid)不变
  • ✅ 成功路径(exit 0)完全不变
  • ⚠️ 失败路径 exit code 细分:0.3.0 失败统一返 1,0.3.1 失败按错误分类返 20/21/30/31/32(详见 Added §)。调用脚本如果硬编码 errorlevel == 1 作为失败 标志需改成 errorlevel NEQ 0;绝大多数脚本写的是 NEQ 0,不受影响
  • ⚠️ 失败时 stderr 新增 JSON 输出({"code":"...","exit":N,"msg":"...","hint":"..."}), 不解析 stderr 的调用方完全不受影响

Added

  • install-template 分级失败码 + stderr JSON 输出(失败时):
    • 20 = binary copy 失败(目标位置占用 / 权限不足)
    • 21 = setup.conf 写入失败(磁盘满 / %ProgramData% 权限)
    • 30 = sc create m2-gateway-svc 失败
    • 31 = schtasks /create m2-gateway-worker 失败
    • 32 = netsh advfirewall 失败
    • 1 = 其它未分类内部错误(跟 0.3.0 默认 exit 1 一致)
    • stderr 单行 JSON:{"code":"<CODE>","exit":N,"msg":"<details>","hint":"<remediation>"}, 供 SetupComplete.cmd / m2aicli vm_provision.py 解析做精细错误分类
  • install_token 默认 TTL 延长:5 分钟 → 15 分钟(中枢侧 INSTALL_TOKEN_TTL 环境变量仍可覆盖)。跨云 provision 链路(cloudbase-init 拉 IMDS + 镜像启动 + AutoLogon 触发)最坏 90-120 秒,5 分钟容错太薄

Fixed

  • install-template 在 install.ps1 路径下自杀的潜在 bug:
    • 老代码 taskkill /F /IM m2-gateway.exe 不带 PID 过滤,当 install.ps1 从临时 目录 spawn install-template 时,会匹配到当前进程自己导致父进程被强杀
    • 修复 = 加 /FI "PID ne <self_pid>" 显式排除当前 PID,只杀同名的别的进程
    • 实测验证:dev 机器跑 install-template 完整跑通 setup.conf → service → task → sc start → exit 0

升级说明

自动(推荐):0.3.0 主机通过中枢 admin push-upgrade 收到 SelfUpdate cmd, 零中断升级到 0.3.1(走 0.3.0 已实装的 service-aware selfupdate 链路)。

手动:下载新版 binary 覆盖 C:\Program Files\m2-gateway\m2-gateway.exe, 然后 sc restart m2-gateway-svc。原 setup.conf / scheduled task / 防火墙规则保留。

老协议客户:0.3.1 完全兼容老 install-template CLI + 老 setup.conf 格式 + 老 ws 协议,选择不升级也无影响,自行决定升级时点。

开发者集成参考

  • TEMPLATE-VM-PREP §3.2 重构为双变体: §3.2.1 简化版主推(Vcflux / cloudbase-init 已配 AutoLogon,SetupComplete 只装 agent → 退出,无 reboot,SLA 60-90s)
  • IMAGE-BUILD-SPEC 新文档: 镜像构建标准 —— 4 套 cloudbase-init.conf(vSphere/阿里/腾讯/华为)+ unattend.xml + 组策略预配 + Packer JSON 骨架 + 8 项镜像验收清单
  • install-template 退出码契约:见 TEMPLATE-VM-PREP §3.6

0.3.0 — 2026-05-21

channel: stable SHA-256: 4329271c340eb7f212041668879186b12d8075b279b21e8b8e34c16b91d2acfb 大小: 2.68 MB（增 ~400 KB，主要是 windows-service crate + 新 IPC/状态机模块）

Master-Worker 架构重设计，解决 0.2.x 跑在 Windows Session 0 下 ConPty 不可用 导致 user-web 终端面板 ws 1011 关闭的根本问题。架构对齐 Tailscale 的 tailscaled service + tailscale-ipn.exe tray 模型，进程职责清晰拆分。

架构变更

agent 由单一进程拆为两个进程协同：

  • Master（Windows Service m2-gateway-svc，Session 0，SYSTEM token）
    • HTTP :23456 + WS 上行中枢 + controls dispatch
    • 不操作桌面、零跨 session spawn
  • Worker（user 登录 session，medium IL，WinSta0\Default）
    • 由 install-template 注册的 Scheduled Task AtLogOn 在用户登录时由 OS 拉起
    • systray + 配置 UI + ConPty 子会话
    • IPC client 接 master pipe，接受 master 转发的 SHELL_SESSION_*

Added

  • --mode CLI：service / worker / master（== 兼容路径，无 --mode）
  • 进程间 IPC：named pipe \\.\pipe\m2-gateway-svc + line-delimited JSON envelope
  • Session 状态机（对接 m2aicli RFC）：
    • 8 状态枚举 cold_boot / autologon_active / locked / logged_off / rdp_seized_console / rdp_disconnected / multi_user / session_lost
    • 每 30s 心跳上报 current_state / active_sessions / capabilities
    • admin web 详情页可见，admin API GET /v1/admin/hosts/:id 暴露
  • RFC §6 标准化错误码：cmd_resp envelope 加 error_code 字段
    • NO_USER_SESSION / WORKER_NOT_READY / CONPTY_INIT_FAILED / MULTI_SESSION_AMBIGUOUS / SESSION_DISCONNECTED / PRECONDITION_NOT_READY
  • user-web 终端面板 fallback 模式：host 进入 NO_USER_SESSION 时自动切到 EXEC_SHELL 单次命令模式，不再 ws 1011 黑屏。带”重连 PTY”按钮
  • 0.2.x → 0.3.x 自动迁移：老 host 通过 selfupdate 收到 0.3.0 binary 后， detect legacy 状态（HKLM\Run 存在 + 无 service）→ 自动跑 install-template 装 service + AtLogOn task + 删 HKLM\Run → helper.cmd 延迟 sc start → 新 service 接管。零中断升级

Fixed

  • user-web 终端面板 ws closed: code=1011 reason=closing —— 根本原因是 agent 跑在 Session 0 没桌面，ConPTY API 不可用。现在 master 转发 SHELL_SESSION_* 到 user session 的 worker，worker 跑真 ConPty 流式回中枢。
  • selfupdate 后 service 不重启 —— selfupdate-helper.cmd 现在 service-aware： detect m2-gateway-svc 存在 → sc start + schtasks /run worker， 无 service 时走老兼容路径。
  • selfupdate 后 service 因 Windows TIME_WAIT 重 bind :23456 失败 —— master 启动时 retry bind 30 次 × 5s sleep（覆盖默认 240s TIME_WAIT 上限）。

升级说明

自动（推荐）：老 0.2.x 主机会通过中枢 admin push-upgrade 收到 SelfUpdate cmd， 零中断自动迁移到 service + worker 架构。验证升级成功的标志：

  • https://admin.gateway.wechas.com/hosts/<id> 详情页 “Session 状态” Card 出现
  • installed_version = “0.3.0”

手动：下载 m2-gateway-0.3.0.exe 直接覆盖 C:\Program Files\m2-gateway\m2-gateway.exe，然后运行 m2-gateway.exe --install-template（含有效 setup.conf 的话）。

开发者集成参考

  • 能力契约文档：docs/api/CAPABILITIES.md —— 8 状态 × 4 能力矩阵 + 错误码 + 心跳 schema + 集成方最佳实践
  • 模板机 + sysprep 批量部署指南：docs/api/TEMPLATE-VM-PREP.md —— golden image / VMware / 公有云 marketplace 镜像装机流程、完整 SetupComplete.cmd 模板、sysprep 前 cleanup 脚本、6 个常见坑
  • OpenAPI：api-docs/openapi.yaml 加 SessionState / Capabilities / HeartbeatPayload / AgentErrorCode 5 个 schema

0.2.2 — 2026-05-16

channel: stable SHA-256: 4acfe91ce9f4dbc2d34805ff520a35fea8b605c16705071d52261081e009c987 大小: 2.27 MB（与 0.2.1 持平）

修复

vCenter GuestOps / 静默批量装机场景的 4 个 install-template bug：

  • install-template 现在真的会写注册表 —— 历史版本里 HKLM\Run 写入是空 stub， reboot 后 agent 不会自启动。本版用 Win32 RegSetValueExW 真正写 HKLM\\SOFTWARE\\Microsoft\\Windows\\CurrentVersion\\Run。
  • AutoLogon 启动时自动进 headless 模式 —— 注册表命令现在带 --no-gui， agent 直接进 server 模式监听 :23456 并连 wss，不再卡在 GUI 等待。
  • setup.conf 向后兼容 —— ws_url 字段同步写入 url 字段，让任何按旧规范 读 url 的工具链都能正确拿到 wss URL。
  • headless 自愈 —— 早期 reboot/login 阶段 desktop 未就绪时，GUI 创建失败 不再退出整个进程，而是降级到 headless 继续跑 http/ws。

谁应该升级

  • ✅ 静默批量装机场景（vCenter GuestOps / Ansible / IaC）—— 强烈推荐
  • ✅ 0.2.1 已上线主机 —— 通过 admin 灰度推送 升级
  • ⏭️ 个人主机（双击 install.exe 装机正常） —— 可选；旧版本仍可用

升级方式

A. 新装主机

无需操作。通过 installer 端点下载的 ps1 / cmd / exe 都已经是 0.2.2。

B. 已上线 0.2.1 主机灰度推送

由运营 / 客户管理员在 admin 控制台触发：

POST /v1/admin/hosts/{id}/push-upgrade
Content-Type: application/json
{ "version": "0.2.2" }

agent 收到 SelfUpdate 控制帧后：

  1. 从 exe_url 下载新 exe
  2. SHA-256 校验
  3. helper.cmd 自重启换装
  4. 整个过程不掉线、不丢未完成请求

C. 客户自行重装

旧 ps1 / install.exe 仍可在客户机上跑，会自动拉取最新 stable。

0.2.1 — 2026-04-15

channel: stable（已被 0.2.2 替代） SHA-256: 686624e1a8cfcfd91679a931a037a4ec5b0e02e476caa88ecb72763b81f54dc1

初始 v0.2.x 系列，引入 agent 主动连 wss（M3-08）。

⚠️ 已知问题（在 0.2.2 修复）： --install-template 后 reboot 不会自启动； GuestOps / 静默装机场景不可用。可单独下载备份留作回滚： https://api.gateway.wechas.com/static/m2-gateway-v0.2.1-pre-installfix.exe.bak

升级建议

我们对 agent 采用滚动更新策略：

  • 新版会作为 stable channel 推到 中枢 gateway_versions 表
  • 老版不主动 yank，保留可回滚
  • 重大不兼容会另开 minor / major 版本号并提前公告

如果你的业务系统强依赖某个版本（比如基于 0.2.1 的特定二进制行为做了自动化）， 可以在主机详情页 pin version，中枢不会自动推升级。