# 容器部署和使用指南

***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` 包中，需一并安装。

```bash
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
```

| **命令** | **用途** |
| --- | --- |
| `docker pull <镜像>` | 拉取镜像 |
| `docker run <镜像> <命令>` | 运行容器 |
| `docker ps [-a]` | 查看运行中（或全部）容器 |
| `docker exec -it <容器> sh` | 进入容器终端 |
| `docker logs <容器>` | 查看容器日志 |
| `docker stop/start/rm <容器>` | 停止 / 启动 / 删除容器 |
| `docker images` | 查看本地镜像 |
| `docker system prune` | 清理未使用的镜像与容器 |

# 配置 iptables 后端

RK3576 内核未启用 nftables 兼容层（`CONFIG_NFT_COMPAT`），Docker 守护进程在默认 nf_tables 模式下无法创建 NAT 规则，需切换到 legacy 后端。先切换再启动 Docker，避免启动失败残留规则：

```bash
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 即可：

```bash
sudo apt install -y nftables
sudo nft flush ruleset
sudo systemctl restart docker
```

# 配置镜像源

目前国内用户无法直接访问 Docker Hub（DNS 污染导致拉取超时或证书错误），需要配置 Docker 镜像源。编辑 `/etc/docker/daemon.json`（不存在则新建）：

```bash
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 镜像加速」获取最新地址）。

# 验证容器

```bash
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：

```bash
sudo usermod -aG docker $USER
```

重新登录（或执行 `newgrp docker`）后生效，验证：

```bash
docker ps
```

# 常用命令

```bash
# 后台运行，重启设备后自动恢复
docker run -d --restart unless-stopped --name myapp busybox sleep 3600
# 查看容器 IP
docker inspect -f '{{.NetworkSettings.IPAddress}}' myapp
# 进入容器
docker exec -it myapp sh
```

## 镜像管理

```bash
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             # 从文件导入镜像
```

## 容器生命周期

```bash
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）或目录挂载持久化数据。

## 卷挂载（推荐）

```bash
docker volume create mydata                     # 创建卷
docker run -d -v mydata:/data --name app nginx  # 挂载卷到容器
docker volume ls                                # 查看卷
docker volume rm mydata                         # 删除卷
```

## 目录挂载

将主机目录直接映射到容器，适合配置文件和开发调试：

```bash
docker run -d -v /home/pi/app:/app --name app nginx
```

# 构建自定义镜像

通过 Dockerfile 定义应用环境和启动命令，构建可复用的自定义镜像：

```bash
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 后端 | `iptables-legacy`（内核未启用 NFT_COMPAT） | nf_tables（默认） |
| 存储驱动 | `overlay2`（内核内置 OVERLAY_FS） | overlay2 / fuse-overlayfs |
| docker CLI 包 | `docker-cli`（Debian 13 起独立包） | 包含在 docker.io（旧版 Debian） |
| 端口映射 | `docker run -p` 自动配置 | 同左 |

# 注意事项

- 必须先切换 iptables-legacy 再启动 Docker，否则守护进程启动失败。

- 国内环境访问 Docker Hub 可能超时或失败，需在 `/etc/docker/daemon.json` 配置 registry-mirrors 镜像源。

- 容器可运行但无法联网时，优先检查 `nft flush ruleset` 清理残留规则。

- 将当前用户加入 docker 组可免 sudo 执行：`sudo usermod -aG docker $USER`（重新登录后生效）。