在 OpenWrt 路由器上安装 Docker 并不是所有设备都适合，但如果是 x86_64 软路由或高性能 ARM64 设备，完全可以把一些轻量级服务容器化，减少对路由器自身运行环境的影响。相比直接在系统里装各种软件，Docker 带来的隔离性和镜像管理会让后续升级和回滚更省心。接下来会按条件检查、依赖安装、Docker 部署、网络与存储调整、常见问题排查的顺序展开，所有命令都基于 OpenWrt 22.03 及之后的版本。
安装前必须核对的三件事
OpenWrt 是一个高度精简的嵌入式 Linux 发行版，默认固件里并没有为容器运行准备所有内核组件。动手安装之前，先确认你的路由器和固件是否满足基本条件，否则后面会遇到一堆莫名其妙的报错。
第一是硬件架构。Docker 本体和大多数镜像都优先支持 x86_64 和 aarch64。如果你的路由器是 MIPS 或 mipsel 架构，虽然 OpenWrt 软件源中也可能存在 Docker 包，但镜像生态很差，很多官方镜像没有对应架构标签，实际可用性不高。可以用 uname -m 查看硬件架构，如果输出 x86_64 或 aarch64，就可以继续；如果是 mips 或 mipsel，建议考虑改用其他轻量方案。
第二是内核版本与模块。Docker 需要 cgroups、namespaces、bridge、veth、overlay filesystem 等内核特性。OpenWrt 官方固件通常已经带了基础 namespace 支持，但 veth、br_netfilter、ip6tables 等模块可能没有默认加载。可以通过 opkg list-installed | grep kmod 查看已装模块，或直接安装缺失项。
第三是存储空间。路由器上的 flash 通常很小，需要外接 U 盘或使用大容量 eMMC/NVMe 设备，并格式化为 ext4 或 f2fs。至少预留 1GB 以上可用空间给 Docker 镜像和容器层。可以用 df -h 检查挂载点。
# 查看架构 uname -m # 查看内核版本 uname -r # 查看磁盘剩余空间 df -h
用 opkg 安装 Docker 及依赖
确认环境没有问题后，就可以通过 OpenWrt 自带的包管理器安装 Docker。目前 OpenWrt 22.03 和 23.05 的软件源中都提供了 dockerd 和 docker-ce 包，前者是守护进程，后者包含 CLI 工具。可以先执行 opkg update 刷新软件列表。
安装 Docker 之前，建议先把与网络和存储相关的内核模块装上。虽然有些模块在安装 docker 时会作为依赖自动拉取，但显式安装能避免版本不匹配带来的问题。常见需要的有 kmod-veth、kmod-br-netfilter、kmod-ip6tables、kmod-nf-nathelper 等。如果是桥接网络，kmod-br-netfilter 尤其关键，它能保证桥接流量经过 iptables。
下面是安装依赖和 Docker 的命令。如果软件源里找不到 docker-ce，也可以只安装 dockerd，再通过静态二进制方式补充 CLI。不过对绝大多数用户来说，直接安装 docker-ce 更简单。
opkg update opkg install kmod-veth kmod-br-netfilter kmod-ip6tables kmod-nf-nathelper opkg install dockerd docker-ce
安装完成后，先不要急着启动。OpenWrt 的启动脚本是 /etc/init.d/dockerd，可以用以下命令设置开机自启并手动启动。首次启动时，dockerd 会创建默认的存储目录和网络环境，如果内核模块缺失，通常会在这里报错。
/etc/init.d/dockerd enable /etc/init.d/dockerd start
启动后建议运行 docker info 查看存储驱动和网络组件。如果看到 Storage Driver: overlay2 或者 vfs，说明守护进程已经正常拉起来。若出现 Cannot connect to the Docker daemon，可以先查看 logread -e dockerd 的输出定位原因。
存储驱动与网络模式怎么选择
OpenWrt 上的 Docker 最容易在存储驱动上踩坑。Linux 桌面发行版通常默认使用 overlay2，但 overlay2 依赖内核的 overlay filesystem 功能，部分 OpenWrt 内核没有开启或模块未加载。此时 Docker 会退回到 vfs。vfs 不做任何写时复制优化，每层文件都是完整复制，占用空间大、速度慢，但在资源有限的路由器上反而更稳定。如果你发现 docker info 显示 Storage Driver: vfs，并不意味着安装失败，只是性能会差一些。
想要强制使用 overlay2，可以先尝试安装 kmod-overlay 和 kmod-fs-overlay 等相关模块，并重启 dockerd。但并不是所有 ARM 路由器的内核都支持，遇到 error initializing graphdriver 时，建议直接改用 vfs。要修改存储驱动，可以编辑 /etc/config/dockerd 或 /etc/docker/daemon.json，增加 storage-driver 选项。
{
"storage-driver": "vfs",
"iptables": true,
"ip6tables": true
}
网络部分同样需要确认。Docker 默认会创建 docker0 网桥，并通过 iptables 做源地址转换，使容器能够访问外网。这一步依赖内核的 bridge 和 netfilter 模块。如果前面没有安装 kmod-br-netfilter，就会出现容器内 ping 不通外部地址的问题。还要确保系统开启了 IP 转发，可以用 sysctl net.ipv4.ip_forward 查看，若为 0，可以通过 sysctl -w net.ipv4.ip_forward=1 临时开启，或写入 /etc/sysctl.conf 持久化。
对于路由器的防火墙，容器映射的端口需要在 /etc/config/firewall 中放行，或者直接使用 docker run -p 8080:80 后，在 LuCI 界面增加对应的通信规则。否则宿主机能访问，但局域网其他设备访问不到容器端口。
运行测试容器并排查常见问题
当 Docker 服务正常后，可以运行一个轻量级容器验证整个链路。建议使用 nginx:alpine 或 hello-world 这类小镜像。运行以下命令会在后台启动一个 nginx，并将宿主机的 8080 端口映射到容器的 80 端口。如果镜像拉取很慢，可以先配置国内镜像加速地址，但本文不展开。
docker run -d --name web-test -p 8080:80 nginx:alpine docker ps curl http://127.0.0.1:8080
如果容器运行正常但局域网其他设备无法访问，先检查 OpenWrt 防火墙是否拒绝 8080 端口。如果容器启动后立即退出，可以使用 docker logs web-test 查看输出。常见原因是镜像架构不匹配，例如在 aarch64 路由器上拉了仅支持 amd64 的镜像。遇到这种情况，需要在镜像名后指定对应架构，或使用多架构镜像。
内存是路由器上最紧张的资源。OpenWrt 设备通常只有 512MB 到 2GB 内存，而 Docker 加上容器服务很容易占用几百 MB。建议为容器设置内存限制，例如 docker run -m 128m --memory-swap 128m，避免单个容器把整机内存耗尽导致路由器死机。同时尽量把 Docker 数据目录放在外置高速存储上，减少对内置 flash 的写入压力。
最后一个常见问题是 OpenWrt 升级后 Docker 不可用。因为固件升级会替换系统文件，之前安装的 opkg 包和内核模块可能会丢失或版本不匹配。升级后最好重新执行依赖安装和 Docker 安装步骤，并恢复 /etc/docker 下的配置和镜像数据。如果数据目录在外置盘上，重新安装后指定回原目录即可继续使用已有容器。
