> 本教程按 2026-09 在本机实际安装成功的全过程整理。环境：Windows + WSL2 Ubuntu 24.04， 容器内 Ubuntu 20.04 + Python 3.8 + rknn-toolkit2 2.3.2，产出镜像 `rknn-toolkit2:2.3.2`、 常驻容器 `rknn-dev`。所有文件在 `D:\rknn_setup\`。

## 0\. 网络现实（先读，决定整个安装路径）

国内网络下 Docker Hub 拉不动镜像，且常见镜像站大多不可用（实测：DaoCloud、1ms.run 卡死； 清华 TUNA / 中科大 403 反爬；xtom.hk 403）。**实测稳定可用的只有华为云和阿里云**：

-   Ubuntu 基础镜像 → 华为云 ubuntu-base rootfs（`docker import` 导入，绕开 Docker Hub）
-   容器内 apt → `mirrors.huaweicloud.com`
-   容器内 pip → `mirrors.aliyun.com/pypi/simple/`
-   GitHub 大文件（rknn wheel、fork 源码）→ `api.github.com` 带 `Accept: application/vnd.github.raw` 头下载可靠

## 1\. WSL2 宿主机准备

```bash
# Windows PowerShell（管理员）确认 WSL2
wsl -l -v
wsl -d Ubuntu          # 进入 WSL（本机用户 uesr）

# WSL 内安装并启动 docker
sudo apt update && sudo apt install -y docker.io
sudo service docker start
sudo usermod -aG docker $USER   # 重新登录后可免 sudo
docker version
```

## 2\. 制作 ubuntu:20.04 基础镜像（绕开 Docker Hub）

```bash
cd /mnt/d/rknn_setup
# 下载华为云的官方 rootfs（约 28MB）
wget https://mirrors.huaweicloud.com/ubuntu-base/focal/base/ubuntu-base-20.04-base-amd64.tar.gz
# 校验（对照官方 SHA256SUMS）
wget https://mirrors.huaweicloud.com/ubuntu-base/focal/SHA256SUMS
sha256sum ubuntu-base-20.04-base-amd64.tar.gz   # 与 SHA256SUMS 中对应行一致才继续
# 导入为镜像
docker import --change 'CMD ["/bin/bash"]' ubuntu-base-20.04-base-amd64.tar.gz ubuntu:20.04
docker images   # 应看到 ubuntu:20.04
```

## 3\. 准备构建文件（D:\\rknn\_setup\\）

### 3.1 下载 rknn-toolkit2 2.3.2 的 cp38 wheel

rknn-toolkit2 **不在 PyPI 上**，只能从 GitHub 仓库拿：

```bash
cd /mnt/d/rknn_setup
curl -sSL -H "Accept: application/vnd.github.raw" -o \
  rknn_toolkit2-2.3.2-cp38-cp38-manylinux_2_17_x86_64.manylinux2014_x86_64.whl \
  "https://api.github.com/repos/airockchip/rknn-toolkit2/contents/rknn-toolkit2/packages/rknn_toolkit2-2.3.2-cp38-cp38-manylinux_2_17_x86_64.manylinux2014_x86_64.whl"
# 校验：whl 是 zip
python3 -c "import zipfile;print(len(zipfile.ZipFile('rknn_toolkit2-2.3.2-cp38-cp38-manylinux_2_17_x86_64.manylinux2014_x86_64.whl').namelist()))"
```

### 3.2 apt 源文件 `sources_huawei.list`

```bash
deb http://mirrors.huaweicloud.com/ubuntu/ focal main restricted universe multiverse
deb http://mirrors.huaweicloud.com/ubuntu/ focal-updates main restricted universe multiverse
deb http://mirrors.huaweicloud.com/ubuntu/ focal-backports main restricted universe multiverse
deb http://mirrors.huaweicloud.com/ubuntu/ focal-security main restricted universe multiverse
```

### 3.3 `Dockerfile_rknn`

```bash
FROM ubuntu:20.04
COPY sources_huawei.list /etc/apt/sources.list
ENV DEBIAN_FRONTEND=noninteractive
RUN apt-get update \
    && apt-get install -y python3 python3-dev python3-pip gcc vim libprotobuf-dev zlib1g zlib1g-dev libsm6 ca-certificates \
    && apt-get install -y libgl1 libglib2.0-0 android-tools-adb
RUN cd /usr/bin && ln -sfn idle3 idle && ln -sfn pydoc3 pydoc && ln -sfn python3 python \
    && ln -sfn python3-config python-config && ln -sfn pip3 pip
RUN python -m pip install --upgrade pip -i https://mirrors.aliyun.com/pypi/simple/
RUN pip3 config set global.index-url https://mirrors.aliyun.com/pypi/simple/
COPY rknn_toolkit2-2.3.2-cp38-cp38-manylinux_2_17_x86_64.manylinux2014_x86_64.whl \
     rknn_toolkit2-2.3.2-cp38-cp38-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
RUN pip3 install torch==1.10.1
RUN pip3 install rknn_toolkit2-2.3.2-cp38-cp38-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
```

> 说明：2.3.2 官方要求 torch==1.10.1（仅 ONNX 导出路径用到），必须先装 torch 再装 wheel。

## 4\. 构建镜像

```bash
cd /mnt/d/rknn_setup
docker build -f Dockerfile_rknn -t rknn-toolkit2:2.3.2 .
# 产物约 7.6GB；pip 非终端无进度条，属正常，耐心等
docker images
```

构建常见报错：

| 报错 | 原因与处理 |
| --- | --- |
| `repository not signed` / 403 | apt 源被反爬，确认用的是 sources\_huawei.list |
| `torchvision==x not found` 且版本列表从 0.17 起 | 脚本跑在 WSL 宿主机（Python 3.12）而非容器里，所有命令要在 `docker build`/`docker exec` 内执行 |
| ensurepip 失败 | 缺 venv 组件（只在容器内装 venv 时遇到）：`apt-get install -y python3.8-venv python3.8-distutils` |

## 5\. 启动常驻容器

```bash
docker run -itd --name rknn-dev --shm-size 4g -v /mnt/d:/mnt/d rknn-toolkit2:2.3.2 bash
docker exec -it rknn-dev bash      # 进入
# 重启电脑/WSL 后恢复：
sudo service docker start && docker start rknn-dev
```

## 6\. 验证（verify.sh + test\_convert.py）

```bash
docker exec rknn-dev bash /mnt/d/rknn_setup/verify.sh
# 期望: RKNN import + init OK
docker exec rknn-dev bash -c "python3 /mnt/d/rknn_setup/test_convert.py"
# 期望: CONVERT OK: xxxxx bytes -> /tmp/mini.rknn   ← 端到端 ONNX→RKNN 打通
```

## 7.（可选）YOLO11-OBB 导出环境

转换自训练模型还需要 airockchip fork + 隔离 venv（容器内执行）：

```bash
apt-get install -y python3.8-venv python3.8-distutils curl
python3 -m venv ~/yoloenv --system-site-packages     # 复用容器里的 torch 1.10.1
mkdir -p ~/rknn-fork && cd ~/rknn-fork
curl -sSL -o f11.tar.gz "https://api.github.com/repos/airockchip/ultralytics_yolo11/tarball/main"
tar xzf f11.tar.gz && mv airockchip-ultralytics_yolo11-* ultralytics_yolo11 && rm f11.tar.gz
```

> 关键点：必须用 `airockchip/ultralytics_yolo11`（8.3.9，含 C3k2/C2PSA，支持 OBB 导出）， **不是** `ultralytics_yolov8`（主分支 8.2.82，没有 YOLO11）。8.4.41 训练的 checkpoint 可正常加载。

## 8\. 日常使用（都在 Windows 侧一条命令）

```bash
:: .pt → INT8 .rknn（rk3588/rk3576）
D:\rknn_setup\rknn_yolo11obb\rknn_convert.bat D:\yolov5\runs\obb\runs\train\exp-16\weights\best.pt D:\datasets\DCIM\yolo_obb_dataset_clean\images\val rk3576,rk3588

:: 精度评估（模拟器）
D:\rknn_setup\rknn_yolo11obb\rknn_eval.bat D:\...\best.onnx
D:\rknn_setup\rknn_yolo11obb\rknn_eval.bat D:\...\best_rk3588_i8.rknn rk3588
```

## 9\. 踩坑备忘

1.  **模拟器不支持 `load_rknn` 推理**：`init_runtime(target=None)` 会报错，必须 `load_onnx`+`build` 进程内重建（评估脚本 `eval_rknn_acc.py` 已处理）。
2.  **复杂命令别经 `wsl.exe ... bash -c '多层引号'` 直传**：变量、sed 转义会被吃掉。写成脚本文件放 /mnt/d，容器内 `bash xxx.sh`。
3.  **conda/wsl 双 python 干扰**：任何 "包找不到/版本不对" 先确认 `python3 --version` 是容器里的 3.8。
4.  导出的 ONNX 是 RKNN 优化结构（去 DFL/后处理，OBB 为 3×69 通道分支+1 角度图），板端解码参考 `detect_video_board.py`。

本教程按 2026-09 在本机实际安装成功的全过程整理。环境：Windows + WSL2 Ubuntu 24.04， 容器内 Ubuntu 20.04 + Python 3.8 + rknn-toolkit2 2.3.2，产出镜像 rknn-toolkit2:2.3.2、 常驻容器 rknn-dev。所有文件在 D:\rknnsetup\。 \. 网络现实（先读，决定整个安装路径） 国内网络下

WSL2 RKNN 开发环境（Docker）安装教程

前端

Windows+WSL2环境下的RKNN-Toolkit2完整安装教程，实测成功方案。国内网络下绕开Docker Hub，采用华为云rootfs+阿里云pip源策略，提供完整Dockerfile配置、常见报错解决方案、YOLO11-OBB导出环境搭建及日常转换评估命令。适合RK3588/RK3576平台模型转换开发。

Android

Windows

容器

Docker

Python

GitHub

Ubuntu

2026上云采购 | AI焕新·智启新局

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

WSL2 RKNN 开发环境（Docker）安装教程-腾讯云开发者社区-腾讯云

WSL2 RKNN 开发环境（Docker）安装教程

WSL2 RKNN 开发环境（Docker）安装教程

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐