第4章 Docker环境搭建

第4章：Docker环境搭建

好，咱们进入实战环节的第一步——搭环境。

说实话，很多同学学FPGA加速，最后卡住的不是算法，不是编译流程，而是环境没配好。我见过太多人花了两三天装各种依赖，最后心态崩了。所以这一章，我带你用Docker一把梭哈，省去所有烦恼。

4.1 为什么要用Docker？

FINN的依赖项非常多：Python 3.8、PyTorch、ONNX、Vivado、Pynq……光版本冲突就能让你头疼半天。

我个人习惯是：能用容器解决的问题，绝不动宿主机环境。Docker把FINN所需的一切打包好，你拉下来就能用。说白了，就是“开箱即用”。

核心优势：

环境隔离：不影响你本机的Python或Vivado
版本锁定：FINN官方镜像经过测试，不会出现“在我电脑上能跑”的尴尬
快速重建：搞坏了？删掉容器，重新run一个，几秒钟搞定

4.2 安装Docker

先确认你的系统。我假设你用的是Ubuntu 20.04或22.04，Windows用户建议用WSL2。

4.2.1 Ubuntu安装Docker

# 更新包索引
sudo apt update

# 安装依赖
sudo apt install apt-transport-https ca-certificates curl software-properties-common

# 添加Docker官方GPG密钥
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add -

# 添加稳定版仓库
sudo add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable"

# 安装Docker CE
sudo apt update
sudo apt install docker-ce docker-ce-cli containerd.io

# 验证安装
sudo docker --version

嗯，这里要注意：别忘记把当前用户加入docker组，否则每次都要sudo，很烦人。

sudo usermod -aG docker $USER
# 然后退出终端重新登录，或者执行 newgrp docker

4.2.2 Windows用户（WSL2）

如果你用Windows，我建议装Docker Desktop，并启用WSL2后端。具体步骤不展开了，记住一点：BIOS里要开启虚拟化。我曾经帮一个学员远程排查，搞了半天发现他BIOS没开VT-x……

4.3 拉取FINN镜像

FINN官方提供了多个版本的Docker镜像。我个人推荐用最新的稳定版，比如 finn:latest 或者带日期的版本。

# 拉取FINN镜像（约2.3GB，耐心等待）
docker pull xilinx/finn:latest

# 查看本地镜像
docker images

为什么会这么大？因为里面预装了Vivado HLS、PyTorch、ONNX Runtime等一堆东西。第一次拉取确实慢，但一劳永逸。

小技巧：如果你在公司网络受限，可以试试换国内镜像源。在 /etc/docker/daemon.json 中添加：

{
  "registry-mirrors": ["https://docker.mirrors.ustc.edu.cn"]
}

然后重启Docker：sudo systemctl restart docker

4.4 验证环境

镜像拉下来后，咱们跑一个简单的测试，确保一切正常。

# 启动容器，挂载当前目录到 /workspace
docker run -it --rm \
  -v $(pwd):/workspace \
  xilinx/finn:latest \
  /bin/bash

# 进入容器后，检查Python和FINN
python3 --version
# 应该输出 Python 3.8.x

# 检查FINN是否可用
python3 -c "import finn; print(finn.__version__)"
# 如果没报错，说明环境OK

我习惯再跑一个最简单的网络测试：

# 在容器内执行
cd /workspace
python3 -m finn.examples.simple_mlp

如果看到类似 FINN build complete 的输出，恭喜你，环境搭建成功！

注意：第一次运行示例可能会下载一些模型权重，需要联网。如果网络不好，可以提前下载好放到挂载目录里。

4.5 常见问题排查

这里我总结几个我踩过的坑，以及帮学员解决过的问题。

问题	现象	解决方案
Docker拉取超时	`Error response from daemon: Get ... net/http: request canceled`	换国内镜像源，或者用代理。我一般用中科大的源。
权限不足	`Got permission denied while trying to connect to the Docker daemon socket`	执行 `sudo usermod -aG docker $USER` 然后重新登录。
容器内无法使用GPU	`RuntimeError: CUDA error: no kernel image is available`	安装 `nvidia-docker2`，启动时加 `--gpus all` 参数。
Vivado路径找不到	`vivado: command not found`	确保宿主机安装了Vivado，并在启动容器时挂载 `-v /opt/Xilinx:/opt/Xilinx`。
磁盘空间不足	`no space left on device`	清理Docker缓存：`docker system prune -a`。或者把镜像存到外置硬盘。

避坑指南：

我曾经因为磁盘空间不足，编译到一半报错，白白浪费了3个小时。所以建议至少留出20GB空闲空间。
还有一次，我忘了挂载Vivado目录，结果容器里找不到 vivado_hls，排查了半天才发现是挂载路径写错了。
如果你用Windows，记得把项目放在WSL2的文件系统里（比如 /home/username/project），而不是Windows的 C:\ 盘，否则IO性能会差很多。

4.6 本章小结

到这步，你的Docker环境应该已经跑起来了。总结一下我们做了什么：

安装了Docker引擎
拉取了FINN官方镜像
运行了容器并验证了环境
了解了常见问题的解决方法

下一章，我们会正式进入FINN的编译流程。到时候你会发现，环境搭好了，后面的路就顺了。

课后练习：

尝试用 docker commit 把你修改过的容器保存为新镜像
写一个 docker-compose.yml 文件，一键启动FINN开发环境
试试在容器内运行 finn.build.build 看看会不会报错

公众号:蓝海资料掘金营，微信deep3321

📚 课程目录