install-windows-3-11

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Install Windows 3.11

安装Windows 3.11

Overview

概述

This skill provides guidance for setting up legacy Windows virtual machines (particularly Windows 3.11) using QEMU with web-based remote access. The core challenge is not just launching the VM, but verifying it reaches a usable state and providing reliable remote access.

本内容提供了使用QEMU搭建旧版Windows虚拟机（尤其是Windows 3.11）并配置基于Web的远程访问的指南。核心挑战不仅是启动虚拟机，还包括验证虚拟机进入可用状态，并提供可靠的远程访问。

Critical Success Criteria

关键成功标准

Before marking any VM setup task complete, verify:

The VM actually boots to the expected state - Screenshots, VNC connection tests, or QMP display queries must confirm the desktop/expected state
Web interface is fully functional - End-to-end test through the browser, not just service status checks
Keyboard/mouse input works - Verify input actually affects VM state, not just that commands are accepted

在标记任何虚拟机搭建任务完成前，需验证以下内容：

虚拟机实际启动至预期状态 - 需通过截图、VNC连接测试或QMP显示查询确认桌面/预期状态
Web界面完全可用 - 通过浏览器进行端到端测试，而不只是检查服务状态
键盘/鼠标输入正常工作 - 验证输入确实会影响虚拟机状态，而不只是命令被接受

Approach

实施步骤

Phase 1: Environment Assessment

阶段1：环境评估

Before installing anything:

Check QEMU version requirements in task description - note any specific version compatibility statements
Audit existing nginx configuration to understand current server blocks
Identify required ports and check for conflicts
Determine the disk image format and any special QEMU flags needed

在进行任何安装操作前：

查看任务描述中的QEMU版本要求 - 记录任何特定的版本兼容性说明
检查现有nginx配置，了解当前的服务器块
确定所需端口并检查是否存在冲突
确定磁盘镜像格式以及所需的特殊QEMU参数

Phase 2: QEMU Configuration

阶段2：QEMU配置

When configuring QEMU for legacy operating systems:

Memory allocation: Windows 3.11 typically needs 16-64MB RAM. Check image documentation for requirements
VNC setup: Use
```
-vnc :1
```
for display 1 (port 5901). Consider
```
-vnc :1,share=ignore-disconnects
```
for stability
QMP socket: Enable with
```
-qmp unix:/path/to/qmp.sock,server,nowait
```
for programmatic control
Display: Legacy OS may need specific display settings like
```
-vga std
```
or
```
-vga cirrus
```

Example QEMU command structure:

bash

qemu-system-i386 \
  -m 32 \
  -hda /path/to/disk.img \
  -vnc :1 \
  -qmp unix:/tmp/qmp.sock,server,nowait \
  -vga std

为旧版操作系统配置QEMU时：

内存分配：Windows 3.11通常需要16-64MB内存。请查看镜像文档了解具体要求
VNC设置：使用
```
-vnc :1
```
指定显示1（端口5901）。为提升稳定性，可考虑使用
```
-vnc :1,share=ignore-disconnects
```
QMP套接字：通过
```
-qmp unix:/path/to/qmp.sock,server,nowait
```
启用，以实现程序化控制
显示设置：旧版系统可能需要特定的显示设置，如
```
-vga std
```
或
```
-vga cirrus
```

示例QEMU命令结构：

bash

qemu-system-i386 \
  -m 32 \
  -hda /path/to/disk.img \
  -vnc :1 \
  -qmp unix:/tmp/qmp.sock,server,nowait \
  -vga std

Phase 3: Web Access Stack

阶段3：Web访问栈配置

The typical stack for web-based VNC access:

Browser → nginx (port 80) → websockify → VNC server (QEMU)

nginx configuration approach:

First, examine
```
/etc/nginx/nginx.conf
```
for existing server blocks
Check if
```
sites-enabled
```
is included in the main config
Create configuration in the appropriate location to avoid conflicts
Test configuration with
```
nginx -t
```
before reloading

websockify setup:

bash

websockify --web=/usr/share/novnc 6080 localhost:5901

Key parameters:

```
--web
```
serves noVNC static files
Port 6080 is the WebSocket endpoint
Target is the VNC port (5901 for display :1)

基于Web的VNC访问的典型架构：

浏览器 → nginx（端口80） → websockify → VNC服务器（QEMU）

nginx配置方法：

首先，查看
```
/etc/nginx/nginx.conf
```
中的现有服务器块
检查主配置中是否包含
```
sites-enabled
```
在合适的位置创建配置，避免冲突
重新加载前使用
```
nginx -t
```
测试配置

websockify搭建：

bash

websockify --web=/usr/share/novnc 6080 localhost:5901

关键参数说明：

```
--web
```
用于提供noVNC静态文件
端口6080是WebSocket端点
目标地址为VNC端口（显示:1对应端口5901）

Phase 4: Boot Verification

阶段4：启动验证

This is the most commonly failed step. Never assume boot succeeded based on process status alone.

Verification strategies:

QMP display query: Send
```
{"execute": "query-status"}
```
to check VM state
VNC screenshot: Use
```
vncsnapshot
```
or similar to capture current display

QMP screendump:

{"execute": "screendump", "arguments": {"filename": "/tmp/screen.ppm"}}

Connect via VNC client: Actually view the display, not just test connectivity

Boot timing considerations:

Legacy OS may need user interaction to complete boot (pressing Enter, clicking OK)
Implement polling rather than fixed sleep delays
Consider boot sequence: BIOS → DOS → Windows (multiple stages)

这是最容易出错的步骤。绝不要仅根据进程状态就假设启动成功。

验证策略：

QMP状态查询：发送
```
{"execute": "query-status"}
```
检查虚拟机状态
VNC截图：使用
```
vncsnapshot
```
或类似工具捕获当前显示内容

QMP屏幕转储：

{"execute": "screendump", "arguments": {"filename": "/tmp/screen.ppm"}}

通过VNC客户端连接：实际查看显示内容，而不只是测试连通性

启动时间注意事项：

旧版系统可能需要用户交互才能完成启动（如按Enter键、点击确认）
采用轮询方式，而非固定的延迟等待
考虑启动顺序：BIOS → DOS → Windows（多阶段过程）

Phase 5: Input Verification

阶段5：输入验证

After establishing QMP connection:

Send test keystrokes and verify display changes
Each QMP connection requires capability negotiation first:
json
```
{"execute": "qmp_capabilities"}
```

Then send keys:

json

{"execute": "send-key", "arguments": {"keys": [{"type": "qcode", "data": "ret"}]}}

建立QMP连接后：

发送测试按键并验证显示变化
每个QMP连接都需要先进行能力协商：
json
```
{"execute": "qmp_capabilities"}
```

然后发送按键指令：

json

{"execute": "send-key", "arguments": {"keys": [{"type": "qcode", "data": "ret"}]}}

Common Pitfalls

常见问题

QEMU Version Compatibility

QEMU版本兼容性

If task specifies "compatible with QEMU X.Y.Z" but a different version is installed:

Document the version mismatch
Test if the image actually boots with the available version
Report any compatibility issues observed

如果任务要求“兼容QEMU X.Y.Z”但安装的是其他版本：

记录版本不匹配情况
测试镜像是否能在现有版本下正常启动
报告观察到的任何兼容性问题

nginx Configuration Conflicts

nginx配置冲突

Symptoms: 502 Bad Gateway, connection refused

Prevention:

Always audit existing nginx config before adding new server blocks
Check for conflicting
```
listen
```
directives
Verify upstream (websockify) is running before nginx tries to proxy to it

症状：502 Bad Gateway、连接被拒绝

预防措施：

添加新服务器块前，务必检查现有nginx配置
检查是否存在冲突的
```
listen
```
指令
在nginx尝试代理前，验证上游服务（websockify）是否已运行

Premature Task Completion

提前标记任务完成

Never mark "VM booted successfully" without:

Visual confirmation (screenshot or VNC connection)
Or QMP state verification showing expected state

绝不要在没有以下验证的情况下标记“虚拟机启动成功”：

可视化确认（截图或VNC连接查看）
或QMP状态验证显示预期状态

QMP Socket Issues

QMP套接字问题

Stale socket files from previous runs cause connection failures
Always clean up
```
/tmp/*.sock
```
or equivalent before starting QEMU
Use
```
socat
```
or
```
nc
```
to test socket connectivity

之前运行留下的陈旧套接字文件会导致连接失败
启动QEMU前，务必清理
```
/tmp/*.sock
```
或类似路径下的文件
使用
```
socat
```
或
```
nc
```
测试套接字连通性

Boot Detection

启动检测

Arbitrary

sleep

commands are unreliable. Instead:

Poll QMP status at intervals
Check for specific display content changes
Implement timeout with failure handling

使用任意

sleep

命令不可靠。替代方案：

定期轮询QMP状态
检查显示内容的特定变化
实现带失败处理的超时机制

Verification Checklist

验证清单

Before declaring task complete:

QEMU process is running (check with
```
pgrep
```
or
```
ps
```
)
VNC port is listening (
```
ss -tlnp | grep 5901
```
)
Websockify is running and connected to VNC
nginx is proxying correctly (test with curl to WebSocket endpoint)
Visual confirmation of expected OS state (screenshot or live view)
Keyboard input affects VM display (send test key, verify change)
Web interface loads in browser and connects to VM

在宣布任务完成前：

QEMU进程正在运行（使用
```
pgrep
```
或
```
ps
```
检查）
VNC端口处于监听状态（
```
ss -tlnp | grep 5901
```
）
Websockify正在运行并已连接到VNC
nginx代理配置正确（通过curl测试WebSocket端点）
可视化确认操作系统处于预期状态（截图或实时查看）
键盘输入会影响虚拟机显示（发送测试按键，验证变化）
Web界面可在浏览器中加载并连接到虚拟机

Resources

资源

references/

参考资料/

Refer to

references/qemu_legacy_os.md

for detailed QEMU flags and compatibility notes for legacy operating systems.

Refer to

references/novnc_nginx_config.md

for production-ready nginx configuration templates.

请查看

references/qemu_legacy_os.md

获取旧版操作系统对应的详细QEMU参数和兼容性说明。

请查看

references/novnc_nginx_config.md

获取生产环境可用的nginx配置模板。