场景三:Windows PC 内置 WSL 再内置 Docker
本场景适用于只有一台 Windows PC 的开发者:在 Windows 上启用 WSL2 并安装 Ubuntu 22.04,再在 WSL 内安装 Docker,用预置好开发工具的 wukun 镜像容器编译。与场景一的差别在于编译环境装在哪:场景一把工具链直接装进 WSL;本场景装进 Docker 容器,由镜像统一提供,环境损坏时删掉容器重建即可,WSL 本身不受影响。

开发环境说明
编译所需的工具都在 wukun 镜像里,容器一启动就是可用的编译环境:
| 项目 | 内容 |
|---|---|
| 镜像地址 | swr.cn-north-4.myhuaweicloud.com/hi_spark/wukun:docker-v1.2.0-rc2 |
| 基础系统 | Ubuntu 22.04.4 LTS |
| ARM 工具链 | arm-v01c02-linux-musleabi-gcc |
| 预装工具 | git、repo、curl、wget、picocom、tftpd-hpa、Rust 1.94、Python 3.10、CMake 3.22 |
创建容器时会预留 SSH 端口映射(
2200:22):平时一条命令直接进入容器,想换 VS Code 等 SSH 工具时无需重建容器(见文末可选章节)。串口透传与 TFTP 烧写也放在文末,需要时再配置。
前置要求
- 以管理员身份运行 PowerShell,后续所有 Windows 端命令均在此窗口执行。
- 若电脑已启用 WSL(
wsl --version有版本输出),可跳过第一步,直接从第二步开始。 - 电脑上不要安装 Docker Desktop:它会随 WSL 启动在后台自行运行,干扰本文安装的 Docker CE。
第一步:启用 WSL2 功能
PowerShell(管理员)
先检测 WSL 是否已启用:
- 有版本输出(如
WSL 版本: 2.x.x.x):WSL 已启用,跳过本步、无需重启,直接进入第二步。 -
报错或无输出:执行以下命令启用 WSL2 并安装内核(
--no-distribution仅装平台,发行版在第二步安装):
执行后重启系统,重启后继续后续步骤。
若网络失败或太慢,改为离线安装:从
https://github.com/microsoft/WSL/releases下载 WSL 内核安装包wsl.x.x.x.x.x64.msi(如wsl.2.7.3.0.x64.msi,国内可改用
https://gh-proxy.com/https://github.com/microsoft/WSL/releases/download/2.7.3/wsl.2.7.3.0.x64.msi),执行msiexec /i D:\wsl.2.7.3.0.x64.msi /quiet /norestart后重启。
第二步:安装 Ubuntu 22.04
PowerShell(管理员)
# 安装 Ubuntu 22.04(WSL 内核已在第一步安装)
wsl --install -d Ubuntu-22.04 --web-download
# 验证安装(Version 应为 2)
wsl --list --verbose
安装完成后若自动进入 Ubuntu 并提示创建用户名/密码:直接关闭该窗口(或随意创建一个),本文所有 WSL 内命令均以 root 身份执行(见第三步),默认用户稍后由 wsl.conf 固定为 root。
磁盘空间与安装位置:默认安装到 C 盘,完整环境(Ubuntu 系统 + Docker + wukun 镜像 + 源码与编译产物)建议预留 30 GB 以上。希望装到 D 盘:在安装命令后追加
--location "D:\WSL\Ubuntu-22.04";若提示不支持,可安装后用wsl --manage Ubuntu-22.04 --move "D:\WSL\Ubuntu-22.04"迁移。若网络失败或太慢,改为提前下载系统文件离线安装:
- 浏览器打开
https://mirrors.aliyun.com/ubuntu-releases/22.04/,下载ubuntu-22.04.5-wsl-amd64.wsl(约 344 MB)保存到D:\,再执行:
第三步:在 WSL 内安装 Docker CE
以 root 身份进入 Ubuntu(在线安装的发行版首次进入是普通用户,本文所有 WSL 内命令均以 root 执行):
磁盘空间与安装位置:默认安装到 C 盘,完整环境(Ubuntu 系统 + Docker + wukun 镜像 + 源码与编译产物)建议预留 30 GB 以上。希望装到 D 盘:在安装命令后追加 --location "D:\WSL\Ubuntu-22.04";若提示不支持,可安装后用 wsl --manage Ubuntu-22.04 --move "D:\WSL\Ubuntu-22.04" 迁移。
以下命令在 WSL 终端(root) 内逐段执行。
3.1 配置华为云 apt 源
cp /etc/apt/sources.list /etc/apt/sources.list.bak 2>/dev/null || true
cat > /etc/apt/sources.list << 'EOF'
deb https://mirrors.huaweicloud.com/ubuntu/ jammy main restricted universe multiverse
deb https://mirrors.huaweicloud.com/ubuntu/ jammy-updates main restricted universe multiverse
deb https://mirrors.huaweicloud.com/ubuntu/ jammy-backports main restricted universe multiverse
deb https://mirrors.huaweicloud.com/ubuntu/ jammy-security main restricted universe multiverse
EOF
apt-get update
若 apt-get update 报 DNS 错误,先执行:
再重新 apt-get update。
3.2 安装OpenSSH和Docker CE(华为云源)
# 安装 OpenSSH
DEBIAN_FRONTEND=noninteractive apt-get install -y openssh-server
sed -i 's/^#\?PermitRootLogin.*/PermitRootLogin yes/' /etc/ssh/sshd_config
# 安装 Docker CE(华为云源)
apt-get install -y ca-certificates curl gnupg lsb-release
install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://mirrors.huaweicloud.com/docker-ce/linux/ubuntu/gpg \
| gpg --dearmor -o /etc/apt/keyrings/docker.gpg
chmod a+r /etc/apt/keyrings/docker.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] \
https://mirrors.huaweicloud.com/docker-ce/linux/ubuntu \
$(lsb_release -cs) stable" > /etc/apt/sources.list.d/docker.list
apt-get update -qq
DEBIAN_FRONTEND=noninteractive apt-get install -y \
docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
3.3 配置 Docker 随 WSL 启动
WSL 内不启用 systemd,改用 wsl.conf 的 boot.command 在 WSL 启动时拉起 Docker 服务:
cat > /etc/wsl-boot.sh << 'EOF'
#!/bin/bash
service ssh start
service docker start
EOF
chmod +x /etc/wsl-boot.sh
cat > /etc/wsl.conf << 'EOF'
[user]
default=root
[boot]
systemd=false
command=/bin/bash /etc/wsl-boot.sh
EOF
exit # 在 WSL 里执行,退回 PowerShell
[user] default=root把默认登录用户固定为 root,之后wsl -d Ubuntu-22.04进入即为 root 终端。
3.4 重启 WSL 并验证
PowerShell(管理员)
wsl --shutdown # 在 PowerShell 里执行,关闭 WSL(用于让 wsl.conf/.wslconfig 生效)
Start-Sleep -Seconds 8
wsl -d Ubuntu-22.04 -u root -- docker info # 能看到 Server Version 即安装成功
第四步:获取镜像并创建容器
获取镜像有两种方式,任选其一:
- 方式一(推荐):直接拉取预构建镜像,开箱即用,速度快。
- 方式二:使用源码仓库中的 Dockerfile 本地构建镜像,适用于需要定制或无法访问远程镜像仓库的场景。
方式一:拉取预构建镜像(推荐)
WSL 终端(root)
# 拉取 wukun 镜像(约需几分钟,失败可重试)
docker pull swr.cn-north-4.myhuaweicloud.com/hi_spark/wukun:docker-v1.2.0-rc2
方式二:使用 Dockerfile 本地构建镜像
无需完整源码仓库,只需下载两个文件即可本地构建开发镜像。构建脚本会自动从华为云下载 ARM 交叉编译器和 Rust 工具链,Dockerfile 内所有网络资源均已配置国内镜像源。
WSL 终端(root)
# 创建构建目录
mkdir -p /root/make_docker_image && cd /root/make_docker_image
# 下载 Dockerfile 和构建脚本
curl -fSL -o Dockerfile \
"https://api.gitcode.com/api/v5/repos/HiSpark/hi_aiot_solution/raw/tools/make_docker_image/Dockerfile?ref=master"
curl -fSL -o build_docker_image.sh \
"https://api.gitcode.com/api/v5/repos/HiSpark/hi_aiot_solution/raw/tools/make_docker_image/build_docker_image.sh?ref=master"
chmod +x build_docker_image.sh
# (可选)根据需要裁剪软件包,减小镜像体积
# vi Dockerfile
# 构建镜像(默认名称 wukun:1.1.0,约需 10-20 分钟)
# 也可指定名称和版本:bash build_docker_image.sh wukun 1.1.0
bash build_docker_image.sh
构建完成后,脚本会自动在当前目录生成 wukun-1.1.0.tar 导出文件,可通过 docker load -i wukun-1.1.0.tar 导入到其他机器。
构建前提:WSL 中已安装 Docker 且 daemon 正在运行(第三步已配置自动启动);磁盘剩余空间 30 GB 以上。
创建容器
无论使用哪种方式获取镜像,创建容器的命令相同。
WSL 终端(root)
# 创建开发容器(仅映射 SSH 端口 2200:22)
# 方式一用户:
docker run -d --name wukun1 --privileged \
-p 2200:22 \
swr.cn-north-4.myhuaweicloud.com/hi_spark/wukun:docker-v1.2.0-rc2
# 方式二用户(镜像名不同):
# docker run -d --name wukun1 --privileged \
# -p 2200:22 \
# wukun:1.1.0
PowerShell(管理员)
# 放行容器 SSH 端口
New-NetFirewallRule -DisplayName "SSH-Container-TCP2200" `
-Direction Inbound -Protocol TCP -LocalPort 2200 `
-Action Allow -Profile Any
第五步:进入容器
方式一:直接进入(本地)
wsl -d Ubuntu-22.04 -u root -- service docker start # 在powershell中启动 wsl 守护进程
wsl -d Ubuntu-22.04 -u root -- docker start wukun1 # 在powershell中启动容器(如果容器已关闭)
wsl -d Ubuntu-22.04 -u root -- docker exec -it wukun1 bash # 从 PowerShell 直达容器(提示符变为root@<容器ID>:)
方式二:通过 SSH 连接(支持 VS Code 远程开发)
先在容器内开启 root 登录并设置密码:
wsl -d Ubuntu-22.04 -u root -- service docker start # 在powershell中启动 wsl 守护进程
wsl -d Ubuntu-22.04 -u root -- docker start wukun1 # 在powershell中启动容器(如果容器已关闭)
wsl -d Ubuntu-22.04 -u root -- docker exec -it wukun1 bash # 从 PowerShell 直达容器(提示符变为root@<容器ID>:)
容器内执行:
sed -i 's/^#\?PermitRootLogin.*/PermitRootLogin yes/' /etc/ssh/sshd_config
passwd root # 自行设定 root 密码
service ssh restart
exit # 退出容器,回到 WSL
随后在 Windows 上用 SSH 工具连接:
| 工具 | 连接信息 |
|---|---|
| 主机 / Host | 127.0.0.1(本机连接)或 Windows 局域网 IP(外部机器) |
| 端口 / Port | 2200 |
| 用户名 | root |
| 密码 | 上一步设置的 root 密码 |
VS Code Remote-SSH:安装 Remote - SSH 插件 → Ctrl+Shift+P → Remote-SSH: Connect to Host → 输入 ssh root@127.0.0.1 -p 2200。
MobaXterm / XShell:新建 SSH 会话,主机 127.0.0.1,端口 2200,用户名 root。
VS Code 首次连接会在容器内自动安装 VS Code Server,需要几分钟,保持网络畅通。
可选:在容器内使用 picocom 连接开发板串口
容器默认无法直接访问 Windows 宿主机的 USB 设备,若需在容器内用 picocom 连接开发板串口,需先在 Windows 侧安装 usbipd-win,再把设备透传进 WSL,第四步创建容器时已加 --privileged,容器能直接访问 WSL 里出现的串口节点,无需重建容器。透传后节点类型由芯片决定:CH343P(官方板 J1318 调试口芯片,CDC-ACM 类)→ /dev/ttyACM0;CH340 / CP210x / FTDI(USB-serial)→ /dev/ttyUSB0。
使用场景:在容器内直接查看开发板启动日志与内核输出、与 U-Boot 交互、经串口命令行调试,全程无需切换到 Windows 侧串口工具。
对后续在容器中使用 Agent 的帮助:透传后 /dev/ttyACM0 是容器内的普通设备,后续在容器中运行的 AI Agent(命令行编码助手等)可直接读写串口,自动完成「观察启动输出 → 定位问题 → 修改代码」的调试闭环,无需人工在 Windows 侧中转串口操作。
1. 安装 usbipd-win 并加载驱动
PowerShell(管理员)
winget install dorssel.usbipd-win --silent --accept-package-agreements --accept-source-agreements
# 安装后重新打开 PowerShell 刷新 PATH
winget 下载失败时,从
https://github.com/dorssel/usbipd-win/releases手动下载 MSI:x64 选usbipd-win_x64.msi,ARM 架构选usbipd-win_arm64.msi。安装后若执行
usbipd提示「不是内部或外部命令」,多为 PATH 未刷新:重新打开管理员 PowerShell 即可。
进入 WSL 加载串口驱动:
# WSL 终端(root)
modprobe ch341 2>/dev/null; modprobe cp210x 2>/dev/null; modprobe cdc_acm 2>/dev/null
若希望每次 WSL 启动自动加载,把上面那行加进 3.3 的 /etc/wsl-boot.sh,放在 service ssh start 之前,然后 wsl --shutdown 重启 WSL。
2. 透传串口设备并连接
Windows 端PowerShell(管理员)
插好开发板 USB 串口线后执行:
usbipd list # 找串口设备的 BUSID(如 2-3,CH340/CP210x 标注黄色)
usbipd bind --busid <BUSID> --force # 绑定(每台设备只需一次)
usbipd attach --wsl Ubuntu-22.04 --busid <BUSID>
wsl -d Ubuntu-22.04 -u root -- ls /dev/ttyACM* /dev/ttyUSB* # 确认设备节点出现(CH343P→ttyACM0;CH340 类→ttyUSB0)
设备透传后重启容器,让 --privileged 容器看到新设备:
Windows 端PowerShell(管理员)
wsl -d Ubuntu-22.04 -u root -- docker restart wukun1
wsl -d Ubuntu-22.04 -u root -- docker exec -it wukun1 bash
3.通过串口进入 / 退出板端
板端通过容器里的串口(picocom)连接,进入后提示符为板端的 ~ #(Linux)或 U-Boot 的 # / =>:
picocom -b 115200 /dev/ttyACM0 # 在容器里执行,进入板端串口(CH343P→ttyACM0;CH340 类→ttyUSB0,按 ls 实测改);退回容器:按 `Ctrl+A` 再按 `Ctrl+X`(退出 picocom)
如果进入后显示
#/=>,示板端正处于 U-Boot 引导加载程序 模式,输入exit即可进入Linux系统。
wsl --shutdown、Windows 重启或 USB 重新插拔后,需重新执行usbipd attach,再docker restart wukun1。若提示
Permission denied:容器内执行chmod 666 /dev/ttyACM0(CH340 类板则改对应/dev/ttyUSB0)。串口被独占:
usbipd attach相当于把串口从 Windows「拔下」交给 WSL 独占,此时 Windows 侧工具(Xshell 等)无法识别该串口。切回 Windows 用usbipd detach --busid <BUSID>;若之前用usbipd bind --busid <BUSID> --force强绑定过,detach 无效,需usbipd unbind --busid <BUSID>。detach 后仍不可见的,物理重插 USB 线一般能恢复。
可选:在容器内运行 TFTP server 供开发板烧写
为开发板提供烧写镜像:把编译产物放入容器的 TFTP 目录,开发板 U-Boot 通过网线用 tftpboot 命令直接下载烧写,免去 TF 卡来回插拔。wukun 镜像预装了 tftpd-hpa,无需在容器内额外安装。
要用 TFTP,需重建容器追加 UDP 69 端口映射与目录挂载。重建前先开启镜像网络——WSL2 默认 NAT 网络下开发板访问不到容器。因此需先开启镜像网络(WSL 与 Windows 共用同一 IP),开发板即可像访问 PC 一样访问 WSL 中的 TFTP server。仅基础编译不需要本章,可在需要网络烧写时再配置。
对后续在容器中使用 Agent 的帮助:镜像网络 + TFTP 就绪后,烧写镜像只需拷贝到 /srv/tftp 即可供开发板 tftpboot 下载烧写。后续在容器中运行的 AI Agent 可在编译完成后自动把镜像拷入 /srv/tftp;再配合上一章的串口直连,即可实现「编译 → 烧写 → 串口观察 → 修复」的全流程自动化
1. 开启镜像网络(前置条件)
需 Windows 11 22H2 及以上、WSL 2.0.0 及以上。在 PowerShell(管理员) 中执行:
PowerShell(管理员)
# networkingMode=mirrored 依赖 IPv6,先确保启用(设为 0 = 全部启用;该项未设置时系统默认即全部启用,可跳过)
Set-ItemProperty "HKLM:\SYSTEM\CurrentControlSet\Services\Tcpip6\Parameters" `
-Name "DisabledComponents" -Value 0 -Type DWord
# 写入 .wslconfig(内容为纯 ASCII,用 ascii 编码写入,避免 UTF-8 BOM 导致部分 WSL 版本解析失败)
@"
[wsl2]
networkingMode=mirrored
dnsTunneling=true
firewall=true
autoProxy=true
"@ | Out-File "$env:USERPROFILE\.wslconfig" -Encoding ascii
注意:
Out-File会整个覆盖已有的.wslconfig。若文件已存在且有其他配置,改用记事本手动编辑,在文件末尾追加上面[wsl2]那段:
配置后执行 wsl --shutdown,再次进入 WSL 即生效(IPv6 设置需重启系统)。验证:在 WSL 内 ip -4 addr,其中一块网卡的 IP 应与 Windows ipconfig 中物理网卡的 IP 一致。
Windows 10 用户:镜像网络需 Windows 11 22H2 及以上,Windows 10 无法使用;且 Windows 内置的
netsh interface portproxy端口转发仅支持 TCP,无法转发 TFTP 的 UDP 69 端口。建议改为在 Windows 侧运行 TFTP server(如 tftpd64),根目录设为D:\tftp,之后在 WSL 内把镜像拷到/mnt/d/tftp、开发板tftpboot的serverip设为 Windows IP 即可,其余流程相同(防火墙放行 UDP 69 见下文第 3 步)。
2. 重建容器(追加 TFTP 端口与目录挂载)
PowerShell(管理员)
# 创建 TFTP 共享目录
New-Item -ItemType Directory -Path "D:\tftp" -Force
# 删除旧容器
wsl -d Ubuntu-22.04 -u root -- docker stop wukun1
wsl -d Ubuntu-22.04 -u root -- docker rm wukun1
重建会清除容器内
/root/workspace的源码与编译产物。需保留的话,重建前备份:docker cp wukun1:/root/workspace D:\workspace-backup,或重建时一并挂载-v /mnt/d/workspace:/root/workspace。
重建并启动,在之前第四步基础上追加 --network host(表示容器使用宿主机网络模式,该模式下容器直接使用 WSL 的网络栈,不会获得独立 IP,容器 IP 与 WSL IP 完全一致)、-v /mnt/d/tftp:/srv/tftp、-v /mnt/d/workspace:/root/workspace,启动命令同时拉起 ssh 和 tftpd-hpa::
wsl -d Ubuntu-22.04 -u root -- docker run -d --name wukun1 --privileged `
--network host `
-v /mnt/d/tftp:/srv/tftp `
-v /mnt/d/workspace:/root/workspace `
--entrypoint /bin/sh `
swr.cn-north-4.myhuaweicloud.com/hi_spark/wukun:docker-v1.2.0-rc2 `
-c "sed -i 's|#Port 22|Port 2200|' /etc/ssh/sshd_config; sed -i 's|#PermitRootLogin prohibit-password|PermitRootLogin yes|' /etc/ssh/sshd_config; echo 'root:root' | chpasswd; service ssh start; service tftpd-hpa start; tail -f /dev/null"
容器 SSH 密码 设为
root,VS Code 连接方式:ssh root@127.0.0.1 -p 2200。
3. Windows 防火墙放行 UDP 69
镜像网络下,发往 WSL 的入站流量由 Hyper-V 防火墙管控(.wslconfig 中 firewall=true),需为 WSL 放行 TFTP 端口。在 PowerShell(管理员) 中执行:
New-NetFirewallHyperVRule -Name "WSL TFTP" -DisplayName "WSL TFTP" `
-Direction Inbound -VMCreatorId '{40E0AC32-46A5-438A-A0B2-2B479E8F2E90}' `
-Protocol UDP -LocalPorts 69 -Action Allow
找不到
New-NetFirewallHyperVRule(Windows 版本过低)时改用经典规则:New-NetFirewallRule -DisplayName "TFTP-WSL2-UDP69" -Direction Inbound -Protocol UDP -LocalPort 69 -Action Allow -Profile Any
4. 为开发板提供镜像
- 组网:开发板与 PC 网线直连,或接入同一交换机(同网段)。
- 配置 IP:镜像网络下 WSL 共用 Windows 的 IP,在 Windows「设置 → 网络 → 以太网」中把有线网卡设为静态 IP(如
192.168.1.2/24)。 - 放置镜像:在容器内把编译产物复制到 TFTP 目录:
- 开发板下载:在开发板 U-Boot 命令行中执行(加载地址、文件名按芯片手册与实际产物调整):
出现
setenv ethaddr 00:5e:4d:0e:d2:b1 setenv ipaddr 192.168.1.10 # 开发板 IP(与 PC 同网段) setenv serverip 192.168.1.2 # PC / WSL 共用 IP tftpboot <加载地址> <镜像文件>#递增的传输进度并提示传输成功,即表示 TFTP server 工作正常,随后即可按 U-Boot 流程烧写。
常见问题
| 现象 | 原因 / 解决 |
|---|---|
启用 WSL 报 0x80370102 |
BIOS/UEFI 未开启虚拟化(Intel VT-x / AMD-V),进 BIOS 开启后重试 |
wsl --install --from-file 失败 |
需 WSL 2.4.10+(用 wsl --version 检查);确认文件已完整下载、磁盘剩余充足 |
| apt-get update 报 DNS 错误 | 手动写入 /etc/resolv.conf,方法见 3.1 说明 |
docker info 报 Cannot connect to the Docker daemon |
WSL 重启后 Docker 服务需几秒拉起,稍候重试;仍失败按下方命令手动启动 |
SSH 报 REMOTE HOST IDENTIFICATION HAS CHANGED,或密码框不弹出直接 Permission denied |
容器重建过,本机 known_hosts 里留着旧密钥;执行 ssh-keygen -R "[127.0.0.1]:2200" 后重连(外部机器替换为对应的 局域网IP:2200) |
SSH 连接超时 / Connection refused |
依次确认:容器在运行(docker ps)、端口映射存在(docker port wukun1)、容器内 sshd 已启动(docker exec wukun1 service ssh start) |
容器内找不到 /dev/ttyACM* |
先确认 USB 设备已透传进 WSL(wsl -d Ubuntu-22.04 -u root -- ls /dev/ttyACM*);容器以 --privileged 运行但需重启才能看到新设备:docker restart wukun1;仍无效执行 modprobe ch341 && modprobe usbserial |
开发板 tftpboot 一直超时 |
按顺序检查:镜像网络是否生效(WSL 与 Windows IP 一致)、容器内 tftpd-hpa 是否运行(docker exec wukun1 service tftpd-hpa status)、防火墙是否放行 UDP 69、双方 IP 是否同网段(见「TFTP」一节) |