容器部署和使用指南¶
Copyright © Quectel Wireless Solutions Co., Ltd. 2026. All rights reserved.
Quectel Pi（RK3576）上使用 Docker 部署和管理容器。当前连接的开发板（M2 Debian 13 trixie）验证为 Docker 26.1.5，内核已内置容器所需配置（overlay2 存储、addrtype 等），仅需切换 iptables 后端即可开箱即用。
容器特点¶
易管理。 轻量级容器化技术，使用 Docker 命令管理容器和镜像，依赖隔离，简化部署流程。
跨平台。 支持 Debian、Ubuntu 等主流发行版，可在多种架构（x86 / ARM）上运行和部署容器。
可移植性。 通过 Dockerfile 和镜像实现环境一致性，便于在不同机器上快速迁移和部署。
高效资源利用。 基于容器化技术，共享主机内核，资源占用低，启动速度快，适合微服务架构。
安装与确认¶
Debian 13 中 docker.io 包仅包含守护进程，命令行工具在独立的 docker-cli 包中，需一并安装。
sudo apt update
sudo apt install -y docker.io docker-cli
docker --version
docker info
终端输出类似如下信息表示安装成功：
Docker version 26.1.5+dfsg1, build a72d7cd
Server Version: 26.1.5+dfsg1
Storage Driver: overlay2
命令 |
用途 |
|---|---|
|
拉取镜像 |
|
运行容器 |
|
查看运行中（或全部）容器 |
|
进入容器终端 |
|
查看容器日志 |
|
停止 / 启动 / 删除容器 |
|
查看本地镜像 |
|
清理未使用的镜像与容器 |
配置 iptables 后端¶
RK3576 内核未启用 nftables 兼容层（CONFIG_NFT_COMPAT），Docker 守护进程在默认 nf_tables 模式下无法创建 NAT 规则，需切换到 legacy 后端。先切换再启动 Docker，避免启动失败残留规则：
sudo update-alternatives --set iptables /usr/sbin/iptables-legacy
sudo update-alternatives --set ip6tables /usr/sbin/ip6tables-legacy
iptables --version # 输出末尾应为 (legacy)
sudo systemctl enable --now docker
若此前已在 nf_tables 模式下启动过 Docker 并失败，可能残留丢弃转发的 nft 规则（容器可运行但无法联网），清理后重启 Docker 即可：
sudo apt install -y nftables
sudo nft flush ruleset
sudo systemctl restart docker
配置镜像源¶
目前国内用户无法直接访问 Docker Hub（DNS 污染导致拉取超时或证书错误），需要配置 Docker 镜像源。编辑 /etc/docker/daemon.json（不存在则新建）：
sudo mkdir -p /etc/docker
sudo tee /etc/docker/daemon.json <<'EOF'
{
"registry-mirrors": [
"https://docker.m.daocloud.io",
"https://docker.1ms.run",
"https://dockerproxy.net"
]
}
EOF
sudo systemctl restart docker
docker info # Registry Mirrors 栏显示配置的源
镜像源地址可能变动，拉取失败时更换为其他可用源（可搜索「docker 镜像加速」获取最新地址）。
验证容器¶
docker pull busybox
docker run --rm busybox echo "Hello from Docker container"
docker run --rm busybox ping -c 3 223.5.5.5
docker run -d -p 8080:80 --name web busybox httpd -f -p 80
curl http://$(hostname -I | awk '{print $1}'):8080/
Hello from Docker container
PING 223.5.5.5 (223.5.5.5): 56 data bytes
3 packets transmitted, 3 packets received, 0% packet loss
端口映射由 Docker 自动生成 DNAT 规则，-p 8080:80 后通过主机 8080 端口即可访问容器，无需手动配置。
添加访问权限¶
将当前用户加入 docker 组，之后执行 docker 命令无需 sudo：
sudo usermod -aG docker $USER
重新登录（或执行 newgrp docker）后生效，验证：
docker ps
常用命令¶
# 后台运行，重启设备后自动恢复
docker run -d --restart unless-stopped --name myapp busybox sleep 3600
# 查看容器 IP
docker inspect -f '{{.NetworkSettings.IPAddress}}' myapp
# 进入容器
docker exec -it myapp sh
镜像管理¶
docker images # 查看本地镜像
docker pull nginx:latest # 拉取镜像
docker rmi nginx # 删除镜像
docker tag nginx myapp:1.0 # 打标签
docker save -o nginx.tar nginx # 导出镜像为文件
docker load -i nginx.tar # 从文件导入镜像
容器生命周期¶
docker run -d --name web nginx # 后台运行
docker ps # 查看运行中容器
docker ps -a # 查看全部（含已停止）
docker logs -f web # 跟随查看日志
docker stop web && docker start web # 停止 / 启动
docker rm web # 删除容器
docker exec -it web bash # 进入容器
docker inspect web # 查看容器详情
数据持久化¶
容器删除后其内部数据会丢失，需通过卷（volume）或目录挂载持久化数据。
卷挂载（推荐）¶
docker volume create mydata # 创建卷
docker run -d -v mydata:/data --name app nginx # 挂载卷到容器
docker volume ls # 查看卷
docker volume rm mydata # 删除卷
目录挂载¶
将主机目录直接映射到容器，适合配置文件和开发调试：
docker run -d -v /home/pi/app:/app --name app nginx
构建自定义镜像¶
通过 Dockerfile 定义应用环境和启动命令，构建可复用的自定义镜像：
mkdir myapp && cd myapp
cat > Dockerfile <<'EOF'
FROM python:3.11-slim
WORKDIR /app
COPY . /app
CMD ["python", "app.py"]
EOF
docker build -t myapp:1.0 .
docker run -d -p 8000:8000 --name myapp myapp:1.0
版本差异¶
功能 |
本平台写法 |
其他平台常见写法 |
|---|---|---|
iptables 后端 |
|
nf_tables（默认） |
存储驱动 |
|
overlay2 / fuse-overlayfs |
docker CLI 包 |
|
包含在 docker.io（旧版 Debian） |
端口映射 |
|
同左 |
注意事项¶
必须先切换 iptables-legacy 再启动 Docker，否则守护进程启动失败。
国内环境访问 Docker Hub 可能超时或失败，需在
/etc/docker/daemon.json配置 registry-mirrors 镜像源。容器可运行但无法联网时，优先检查
nft flush ruleset清理残留规则。将当前用户加入 docker 组可免 sudo 执行：
sudo usermod -aG docker $USER（重新登录后生效）。