WinArena 开发调试实战指南：Dev/Azure 双模式、Golden Image 复用与 Windows 11 VM 排障流程

WinArena 开发调试实战指南：Dev/Azure 双模式、Golden Image 复用与 Windows 11 VM 排障流程

【免费下载链接】cuaScale computer-use 2.0 with open-source drivers, cross-OS fleets, and benchmarks for training, evaluation, and data generation.项目地址: https://gitcode.com/GitHub_Trending/cua/cua

WinArena（Windows Arena，WAA）是 cua-bench 中一套在 Docker 容器内通过 QEMU/KVM 运行 Windows 11 虚拟机、驱动 AI Agent 完成 Windows 桌面任务的基准测试系统。本文基于 Development-Tips.md 整理出一套面向二次开发与排障的完整工作流：从run-local.sh的dev/azure双模式切换、共享文件夹热更新，到 Golden Image 快照备份复用、三处关键日志定位、交互式容器调试，再到容器内外与 Windows VM 中 CUA Computer Server 的连通性验证与端口转发。读完本文，你将能够独立完成 WinArena 本地开发环境的搭建、镜像制备、故障定位与远程代理调试。

一、先理解 WAA 的整体运行架构

在进入开发技巧之前，先明确 WinArena 的核心组件拓扑（详见 infra/README.md）：

Linux 容器 (trycua/winarena:latest) ├── Client (start_client.sh -> python run.py) │ ├── NaviAgent / ClaudeAgent │ └── SoM (Set-of-Mark) 处理、a11y 无障碍树 └── Windows 11 VM (QEMU/KVM) └── CUA Computer Server (Flask, 端口 5000) ├── PyAutoGUI / UIA 自动化 └── 任务执行环境

Client 通过 HTTP 与 VM 内的 CUA Computer Server 通信（默认地址172.30.0.2:5000），由 Server 完成截图、点击、输入、读取无障碍树、执行 Windows 命令等动作。mode参数正是在这套架构上为"开发调试"与"规模化跑测"两种场景提供的开关。

二、Dev/Azure 双模式：mode参数与共享文件夹热更新

run-local.sh中提供了一个mode参数，用于切换两种运行形态。从源码看，默认值为azure（见 run-local.sh）：

• azure（默认）：面向大规模基准测试优化，镜像制备脚本在构建时被固化进镜像，全程自动化执行；
• dev：面向src/win-arena-container/vm/setup下初始化脚本与 Python Server 的开发测试，会额外挂载一个共享文件夹，让 Docker 宿主与容器内的 Windows 11 VM 互通。

在dev模式下，run.sh会把宿主上的vm/setup目录以 bind mount 方式挂载为容器内的/shared（见 run.sh），Windows VM 内部则通过 Samba 将该目录映射为\\host.lan\Data。这意味着在宿主上修改vm/setup下的脚本，改动会立即出现在 Windows 11 VM 中，无需重建镜像即可迭代。

制备 Golden Image

首次开发时，先用dev模式完成 Windows 环境的一次性初始化：

cd libs/cua-bench/tasks/winarena_adapter/infra/scripts ./run-local.sh --mode dev --prepare-image true

一键启动完整环境

镜像制备完成后，即可一次性启动 VM 与 Client 进程：

./run-local.sh --mode dev --start-client true

dev 模式的挂载结构

mode=dev时的目录流向如下（对应 run.sh 中的路径解析逻辑）：

Host (仓库内) Container Windows VM infra/vm/setup/ ──────────────> /shared/ ───────> \\host.lan\Data infra/vm/storage/ ─────────────> /storage (VM 磁盘，保持持久化) client/（构建期 COPY）─────────> /client

需要说明的是，--mount-server挂载仅对dev模式生效（见run.sh的 help 输出 run.sh）；azure模式下 setup 脚本在构建阶段即复制进容器，不再依赖宿主目录。这一点也是 infra/README.md 中"Unified to dev mode which copies to/shared/"这一经验教训的直接体现。

三、run-local.sh参数全解：从默认值到完整用法

run-local.sh与run.sh共享同一套参数解析（run-local.sh在读取config.json中的 API Key 后，把全部参数原样透传给run.sh），完整的参数清单如下（默认值取自 run-local.sh）：

几个值得注意的源码细节：

• run.sh会对config.json中的密钥做校验：必须设置OPENAI_API_KEY，或同时设置AZURE_API_KEY与AZURE_ENDPOINT，否则脚本直接报错退出（见 run-local.sh）；
• run.sh在启动容器时会自动检查--platform linux/amd64、--device=/dev/kvm、--cap-add NET_ADMIN等选项，并对browser_port/rdp_port做端口映射（run.sh）；
• 容器内实际的 VM 启动与健康检查由 entry_setup.sh 完成：它在后台启动 VM，然后循环请求${VM_IP}:${SERVER_PORT}/status，直到 CUA Computer Server 返回 200 才继续。

四、复用 Golden Image 快照：多 VM 场景的捷径

如果你已经用dev或azure模式完成过一次 Windows 镜像初始化，就可以直接复用该镜像快速创建新的 VM，避免重复约一小时的全量安装。复用方法是将infra/vm/storage目录下的所有 Windows 镜像文件整体备份：

libs/cua-bench/tasks/winarena_adapter/infra/vm/storage/ ├── data.img ├── windows.base ├── windows.boot ├── windows.mac ├── windows.rom ├── windows.vars └── windows.ver

结合 infra/README.md 中的 Golden Image 策略，推荐的标准流程是：

1. 制备：./run-local.sh --mode dev --prepare-image true，等待 Windows 初始化完成（约 1 小时），人工验证软件安装无误；
2. 优雅关机：通过 CUA Server 执行关机命令，确保磁盘状态一致：

   curl -X POST http://172.30.0.2:5000/cmd \ -H "Content-Type: application/json" \ -d '{"command": "run_command", "params": {"command": "shutdown /s /t 5"}}'

3. 备份：将整个storage目录复制到安全位置（如/backup/golden-storage）；
4. 复用：需要新 VM 时，把备份内容恢复回storage目录，再以--start-client true启动即可。

该策略在大规模批量跑测时尤为关键，可以把"每次跑测都从头安装 Windows"的高昂成本压缩到一次。

五、日志定位：三个关键日志入口

WinArena 的错误可能发生在两个阶段——Golden Image 制备阶段与 VM 运行阶段，对应的日志入口也不同：

1. 制备阶段：PowerShell 初始化日志

执行./run-local.sh --prepare-image true期间发生错误，应查看 Windows 初始化脚本（setup.ps1 等）运行时写入的日志文件：

libs/cua-bench/tasks/winarena_adapter/infra/vm/setup/ps_script_log.txt

该文件由容器内的 Windows VM 在执行安装脚本时生成，记录了安装过程中的每条 PowerShell 输出与报错堆栈，是排查"应用没装上""服务没启动"类问题的第一现场。

2. 运行阶段：CUA Computer Server 日志

运行在 Windows 11 VM 内的 Python Server（Flask）日志位于：

libs/cua-bench/tasks/winarena_adapter/infra/vm/setup/server/server.log

从 server/main.py 可以看到，Server 默认把日志写入server.log，并挂接了自定义的Logger类：它会捕获未捕获异常（excepthook）并写入日志，同时把werkzeug的请求日志也一并记录，因此你在server.log中既能看到 Agent 发来的每条 HTTP 请求，也能看到 Python 侧的异常回溯。

3. 容器入口健康检查

若 VM 迟迟"起不来"，可以观察 entry_setup.sh 的循环输出——它会每 5 秒打印一次等待信息，直到GET /status返回 200。这部分输出直接打印在容器 stdout 上，可通过docker logs winarena查看。

六、交互模式：不起 VM 与 Client，先调试容器本身

在开发新的 Agent 或任务扩展时，通常不希望容器一启动就自动拉起 VM 和 Client 两个进程。此时使用--interactive true：

cd libs/cua-bench/tasks/winarena_adapter/infra/scripts ./run-local.sh --interactive true

从 run.sh 的源码可以看到：当interactive=true时，entrypoint 参数会被置空，容器以/bin/bash为入口直接进入 shell。容器启动成功后，你可以在容器内手动、分步启动各进程：

# 手动启动 Windows VM（QEMU） ./start_vm.sh # 手动启动基准测试 Client ./start_client.sh

这样拆分启动的好处是：可以先确认容器网络（dnsmasq 分配的 172.30.0.0/24 网段）、VM 磁盘挂载状态都正常，再单独调试任一方。start_client.sh内部最终会调用python run.py --agent ... --model ... --som_origin ... --a11y_backend ...（见 start_client.sh），你可以直接在命令行追加--result-dir、--json-name、--diff-lvl（normal/hard）等参数进行针对性验证。

七、连通性测试：验证 Windows 11 VM 是否就绪

当 Golden Image 制备完成、准备运行 Agent 之前，建议先验证 VM 内的 Python Server 已完整启动并开始监听连接。对于已初始化过的 VM，启动过程通常不超过 1 分钟。

首先 attach 到正在运行的容器：

cd libs/cua-bench/tasks/winarena_adapter/infra/scripts ./run-local.sh --connect true

--connect的实现是直接对已存在的容器执行docker exec <container_name> /bin/bash（见 run.sh），不会重新构建镜像或新建容器。

进入容器后，请求 CUA Computer Server 的截图接口：

curl -v -X GET http://20.20.20.21:5000/screenshot # 预期结果：HTTP/1.1 200 OK

返回200 OK即代表 VM 内 Flask Server 已经就绪、可以接收 Agent 的自动化指令。需要提醒的是：dev 模式下 VM 的实际 IP 可能为20.20.20.21（dnsmasq 网段随模式变化），而生产/Azure 场景默认是172.30.0.2（infra/README.md 中明确记录了"Client 默认 20.20.20.21 而实际 VM 是 172.30.0.2"这一易错点）。以 entry_setup.sh 中的健康检查逻辑（GET /status直到 200）为准是最稳妥的。

八、从 Docker 外部连接 Python Server：socat 端口转发

当你在 Docker 宿主（或宿主机外）调试 Agent，而 Agent 进程不在容器内时，需要在已 attach 的容器中为相关端口（5000、9222、1337）建立代理服务器，把请求转发到容器内 Windows Server 的 IP：

# 1. 连接正在运行的 docker cd libs/cua-bench/tasks/winarena_adapter/infra/scripts ./run-local.sh --connect true # 2. 依次为 5000/9222/1337 建立 socat 转发，将请求转发至 Windows Server 在容器内的 IP echo -n 5000 9222 1337 | xargs -d ' ' -I% bash -c 'socat tcp-listen:%,fork tcp:172.30.0.2:%'

其中：

• 5000：CUA Computer Server 主端口（截图、点击、输入、无障碍树等全部自动化指令）；
• 9222：浏览器远程调试端口（Chrome DevTools Protocol，供 Agent 读取浏览器 DOM 状态）；
• 1337：其他需要暴露的辅助服务端口（可按需增减）。

xargs -d ' ' -I%会把5000、9222、1337逐个填入%占位符，从而为每个端口各起一个socat tcp-listen:<port>,fork监听，实现"宿主端口 → 容器内 VM IP 端口"的双向转发。请在命令中把172.30.0.2替换为你容器内的实际 VM IP（可通过docker exec内的ip addr或entry_setup.sh的日志确认）。

九、一套完整的开发调试工作流

综合以上要点，推荐按如下顺序组织你的 WinArena 本地开发循环：

1. 首次初始化：./run-local.sh --mode dev --prepare-image true（约 1 小时，生成 Golden Image）；
2. 迭代脚本：编辑vm/setup下脚本，在 Windows VM 内执行\\host.lan\Data\install.bat（对应 install.bat），无需重建镜像；
3. 故障定位：制备阶段问题看ps_script_log.txt，运行阶段问题看server/server.log，启动卡顿看docker logs winarena；
4. 容器调试：./run-local.sh --interactive true分步执行start_vm.sh/start_client.sh；
5. 连通性确认：./run-local.sh --connect true后curl http://<vm-ip>:5000/screenshot应返回 200；
6. 外部代理调试：容器内用 socat 转发 5000/9222/1337，即可从容器外驱动 Windows VM；
7. 规模化跑测：切回./run-local.sh --mode azure --start-client true，或使用 run_azure_batch.py 在 Azure Batch 上并行调度。

这套流程覆盖了 WinArena 从镜像制备、脚本热更新、日志排障到跨容器代理调试的完整开发闭环，是你在 cua-bench 上基于 Windows 桌面任务开发、验证 Agent 与评测逻辑时的日常工具箱。

【免费下载链接】cuaScale computer-use 2.0 with open-source drivers, cross-OS fleets, and benchmarks for training, evaluation, and data generation.项目地址: https://gitcode.com/GitHub_Trending/cua/cua