边缘网关开发计划（一）：在 Rock 5T 上部署 Docker

### 文章目录

[目录](#文章目录目录 @[toc] 1. 系统目标 2. 当前环境 3. Docker 是什么 4. Docker Compose 是什么 5. 安装前环境检查 6. Docker 安装过程 7. Docker 官方源访问失败问题问题现象原因分析后续报错 8. NodeSource 源干扰问题 9. 改用国内 Docker CE 镜像源 10. 启动 Docker 服务 11. Docker Hub 镜像拉取问题 12. 配置 Docker 镜像加速 13. 使用 Mosquitto 镜像验证 Docker 14. 配置普通用户执行 Docker 15. 当前系统状态)
[@[toc]](#文章目录目录 @[toc] 1. 系统目标 2. 当前环境 3. Docker 是什么 4. Docker Compose 是什么 5. 安装前环境检查 6. Docker 安装过程 7. Docker 官方源访问失败问题问题现象原因分析后续报错 8. NodeSource 源干扰问题 9. 改用国内 Docker CE 镜像源 10. 启动 Docker 服务 11. Docker Hub 镜像拉取问题 12. 配置 Docker 镜像加速 13. 使用 Mosquitto 镜像验证 Docker 14. 配置普通用户执行 Docker 15. 当前系统状态)
[1. 系统目标](#文章目录目录 @[toc] 1. 系统目标 2. 当前环境 3. Docker 是什么 4. Docker Compose 是什么 5. 安装前环境检查 6. Docker 安装过程 7. Docker 官方源访问失败问题问题现象原因分析后续报错 8. NodeSource 源干扰问题 9. 改用国内 Docker CE 镜像源 10. 启动 Docker 服务 11. Docker Hub 镜像拉取问题 12. 配置 Docker 镜像加速 13. 使用 Mosquitto 镜像验证 Docker 14. 配置普通用户执行 Docker 15. 当前系统状态)
[2. 当前环境](#文章目录目录 @[toc] 1. 系统目标 2. 当前环境 3. Docker 是什么 4. Docker Compose 是什么 5. 安装前环境检查 6. Docker 安装过程 7. Docker 官方源访问失败问题问题现象原因分析后续报错 8. NodeSource 源干扰问题 9. 改用国内 Docker CE 镜像源 10. 启动 Docker 服务 11. Docker Hub 镜像拉取问题 12. 配置 Docker 镜像加速 13. 使用 Mosquitto 镜像验证 Docker 14. 配置普通用户执行 Docker 15. 当前系统状态)
[3. Docker 是什么](#文章目录目录 @[toc] 1. 系统目标 2. 当前环境 3. Docker 是什么 4. Docker Compose 是什么 5. 安装前环境检查 6. Docker 安装过程 7. Docker 官方源访问失败问题问题现象原因分析后续报错 8. NodeSource 源干扰问题 9. 改用国内 Docker CE 镜像源 10. 启动 Docker 服务 11. Docker Hub 镜像拉取问题 12. 配置 Docker 镜像加速 13. 使用 Mosquitto 镜像验证 Docker 14. 配置普通用户执行 Docker 15. 当前系统状态)
[4. Docker Compose 是什么](#文章目录目录 @[toc] 1. 系统目标 2. 当前环境 3. Docker 是什么 4. Docker Compose 是什么 5. 安装前环境检查 6. Docker 安装过程 7. Docker 官方源访问失败问题问题现象原因分析后续报错 8. NodeSource 源干扰问题 9. 改用国内 Docker CE 镜像源 10. 启动 Docker 服务 11. Docker Hub 镜像拉取问题 12. 配置 Docker 镜像加速 13. 使用 Mosquitto 镜像验证 Docker 14. 配置普通用户执行 Docker 15. 当前系统状态)
[5. 安装前环境检查](#文章目录目录 @[toc] 1. 系统目标 2. 当前环境 3. Docker 是什么 4. Docker Compose 是什么 5. 安装前环境检查 6. Docker 安装过程 7. Docker 官方源访问失败问题问题现象原因分析后续报错 8. NodeSource 源干扰问题 9. 改用国内 Docker CE 镜像源 10. 启动 Docker 服务 11. Docker Hub 镜像拉取问题 12. 配置 Docker 镜像加速 13. 使用 Mosquitto 镜像验证 Docker 14. 配置普通用户执行 Docker 15. 当前系统状态)
[6. Docker 安装过程](#文章目录目录 @[toc] 1. 系统目标 2. 当前环境 3. Docker 是什么 4. Docker Compose 是什么 5. 安装前环境检查 6. Docker 安装过程 7. Docker 官方源访问失败问题问题现象原因分析后续报错 8. NodeSource 源干扰问题 9. 改用国内 Docker CE 镜像源 10. 启动 Docker 服务 11. Docker Hub 镜像拉取问题 12. 配置 Docker 镜像加速 13. 使用 Mosquitto 镜像验证 Docker 14. 配置普通用户执行 Docker 15. 当前系统状态)
[7. Docker 官方源访问失败问题](#文章目录目录 @[toc] 1. 系统目标 2. 当前环境 3. Docker 是什么 4. Docker Compose 是什么 5. 安装前环境检查 6. Docker 安装过程 7. Docker 官方源访问失败问题问题现象原因分析后续报错 8. NodeSource 源干扰问题 9. 改用国内 Docker CE 镜像源 10. 启动 Docker 服务 11. Docker Hub 镜像拉取问题 12. 配置 Docker 镜像加速 13. 使用 Mosquitto 镜像验证 Docker 14. 配置普通用户执行 Docker 15. 当前系统状态)
[问题现象](#文章目录目录 @[toc] 1. 系统目标 2. 当前环境 3. Docker 是什么 4. Docker Compose 是什么 5. 安装前环境检查 6. Docker 安装过程 7. Docker 官方源访问失败问题问题现象原因分析后续报错 8. NodeSource 源干扰问题 9. 改用国内 Docker CE 镜像源 10. 启动 Docker 服务 11. Docker Hub 镜像拉取问题 12. 配置 Docker 镜像加速 13. 使用 Mosquitto 镜像验证 Docker 14. 配置普通用户执行 Docker 15. 当前系统状态)
[原因分析](#文章目录目录 @[toc] 1. 系统目标 2. 当前环境 3. Docker 是什么 4. Docker Compose 是什么 5. 安装前环境检查 6. Docker 安装过程 7. Docker 官方源访问失败问题问题现象原因分析后续报错 8. NodeSource 源干扰问题 9. 改用国内 Docker CE 镜像源 10. 启动 Docker 服务 11. Docker Hub 镜像拉取问题 12. 配置 Docker 镜像加速 13. 使用 Mosquitto 镜像验证 Docker 14. 配置普通用户执行 Docker 15. 当前系统状态)
[后续报错](#文章目录目录 @[toc] 1. 系统目标 2. 当前环境 3. Docker 是什么 4. Docker Compose 是什么 5. 安装前环境检查 6. Docker 安装过程 7. Docker 官方源访问失败问题问题现象原因分析后续报错 8. NodeSource 源干扰问题 9. 改用国内 Docker CE 镜像源 10. 启动 Docker 服务 11. Docker Hub 镜像拉取问题 12. 配置 Docker 镜像加速 13. 使用 Mosquitto 镜像验证 Docker 14. 配置普通用户执行 Docker 15. 当前系统状态)
[8. NodeSource 源干扰问题](#文章目录目录 @[toc] 1. 系统目标 2. 当前环境 3. Docker 是什么 4. Docker Compose 是什么 5. 安装前环境检查 6. Docker 安装过程 7. Docker 官方源访问失败问题问题现象原因分析后续报错 8. NodeSource 源干扰问题 9. 改用国内 Docker CE 镜像源 10. 启动 Docker 服务 11. Docker Hub 镜像拉取问题 12. 配置 Docker 镜像加速 13. 使用 Mosquitto 镜像验证 Docker 14. 配置普通用户执行 Docker 15. 当前系统状态)
[9. 改用国内 Docker CE 镜像源](#文章目录目录 @[toc] 1. 系统目标 2. 当前环境 3. Docker 是什么 4. Docker Compose 是什么 5. 安装前环境检查 6. Docker 安装过程 7. Docker 官方源访问失败问题问题现象原因分析后续报错 8. NodeSource 源干扰问题 9. 改用国内 Docker CE 镜像源 10. 启动 Docker 服务 11. Docker Hub 镜像拉取问题 12. 配置 Docker 镜像加速 13. 使用 Mosquitto 镜像验证 Docker 14. 配置普通用户执行 Docker 15. 当前系统状态)
[10. 启动 Docker 服务](#文章目录目录 @[toc] 1. 系统目标 2. 当前环境 3. Docker 是什么 4. Docker Compose 是什么 5. 安装前环境检查 6. Docker 安装过程 7. Docker 官方源访问失败问题问题现象原因分析后续报错 8. NodeSource 源干扰问题 9. 改用国内 Docker CE 镜像源 10. 启动 Docker 服务 11. Docker Hub 镜像拉取问题 12. 配置 Docker 镜像加速 13. 使用 Mosquitto 镜像验证 Docker 14. 配置普通用户执行 Docker 15. 当前系统状态)
[11. Docker Hub 镜像拉取问题](#文章目录目录 @[toc] 1. 系统目标 2. 当前环境 3. Docker 是什么 4. Docker Compose 是什么 5. 安装前环境检查 6. Docker 安装过程 7. Docker 官方源访问失败问题问题现象原因分析后续报错 8. NodeSource 源干扰问题 9. 改用国内 Docker CE 镜像源 10. 启动 Docker 服务 11. Docker Hub 镜像拉取问题 12. 配置 Docker 镜像加速 13. 使用 Mosquitto 镜像验证 Docker 14. 配置普通用户执行 Docker 15. 当前系统状态)
[12. 配置 Docker 镜像加速](#文章目录目录 @[toc] 1. 系统目标 2. 当前环境 3. Docker 是什么 4. Docker Compose 是什么 5. 安装前环境检查 6. Docker 安装过程 7. Docker 官方源访问失败问题问题现象原因分析后续报错 8. NodeSource 源干扰问题 9. 改用国内 Docker CE 镜像源 10. 启动 Docker 服务 11. Docker Hub 镜像拉取问题 12. 配置 Docker 镜像加速 13. 使用 Mosquitto 镜像验证 Docker 14. 配置普通用户执行 Docker 15. 当前系统状态)
[13. 使用 Mosquitto 镜像验证 Docker](#文章目录目录 @[toc] 1. 系统目标 2. 当前环境 3. Docker 是什么 4. Docker Compose 是什么 5. 安装前环境检查 6. Docker 安装过程 7. Docker 官方源访问失败问题问题现象原因分析后续报错 8. NodeSource 源干扰问题 9. 改用国内 Docker CE 镜像源 10. 启动 Docker 服务 11. Docker Hub 镜像拉取问题 12. 配置 Docker 镜像加速 13. 使用 Mosquitto 镜像验证 Docker 14. 配置普通用户执行 Docker 15. 当前系统状态)
[14. 配置普通用户执行 Docker](#文章目录目录 @[toc] 1. 系统目标 2. 当前环境 3. Docker 是什么 4. Docker Compose 是什么 5. 安装前环境检查 6. Docker 安装过程 7. Docker 官方源访问失败问题问题现象原因分析后续报错 8. NodeSource 源干扰问题 9. 改用国内 Docker CE 镜像源 10. 启动 Docker 服务 11. Docker Hub 镜像拉取问题 12. 配置 Docker 镜像加速 13. 使用 Mosquitto 镜像验证 Docker 14. 配置普通用户执行 Docker 15. 当前系统状态)
[15. 当前系统状态](#文章目录目录 @[toc] 1. 系统目标 2. 当前环境 3. Docker 是什么 4. Docker Compose 是什么 5. 安装前环境检查 6. Docker 安装过程 7. Docker 官方源访问失败问题问题现象原因分析后续报错 8. NodeSource 源干扰问题 9. 改用国内 Docker CE 镜像源 10. 启动 Docker 服务 11. Docker Hub 镜像拉取问题 12. 配置 Docker 镜像加速 13. 使用 Mosquitto 镜像验证 Docker 14. 配置普通用户执行 Docker 15. 当前系统状态)

1. 系统目标

本篇目标是在 Rock 5T 上完成 Docker 和 Docker Compose 的部署，为后续边缘网关多服务运行环境做准备。

后续 Rock 5T 计划运行的服务包括：

text 复制代码

Rock 5T / RK3588
└── Docker Compose
    ├── Mosquitto：MQTT Broker
    ├── Node-RED：MQTT 调试与规则编排
    ├── Home Assistant：本地智能设备 UI
    ├── RoomEdge Core：自研边缘网关核心
    ├── MCP Server：后续给 AI Agent 调用
    └── AI Inference：后续接入 RKNN / NPU 推理

本篇完成后的验证目标：

text 复制代码

1. Docker Engine 安装成功
2. Docker Compose Plugin 安装成功
3. Docker 服务可以正常启动
4. Docker 镜像可以正常拉取
5. Docker 容器可以正常运行
6. 普通用户可以执行 docker 命令

2. 当前环境

Rock 5T 通过 SSH 登录后，先检查系统环境。

检查命令：

bash 复制代码

cat /etc/os-release
uname -a
dpkg --print-architecture
lscpu | head -30
free -h
df -h
lsblk
docker --version || true
docker compose version || true
systemctl is-active docker || true

实际环境：

text 复制代码

开发板：Rock 5T
芯片：Rockchip RK3588
系统：Debian GNU/Linux 12 bookworm
内核：Linux 6.1.84-8-rk2410
架构：arm64 / aarch64
内存：15GiB
根分区：115GB
剩余磁盘：约 86GB
Docker：未安装
Docker 服务状态：inactive

当前环境具备运行 Docker 多服务栈的基础条件。

3. Docker 是什么

Docker 是一种容器化平台，可以把应用及其运行依赖打包成镜像，并以容器的方式运行。

在 Rock 5T 边缘网关项目中，Docker 的作用是隔离不同服务的运行环境，例如：

text 复制代码

Mosquitto 使用自己的容器环境
Node-RED 使用自己的容器环境
Home Assistant 使用自己的容器环境
自研 RoomEdge Core 使用自己的容器环境

这样做的好处是：

text 复制代码

1. 避免不同服务之间的依赖冲突
2. 方便统一启动、停止和升级
3. 方便迁移到其他开发板或服务器
4. 方便开源项目复现环境
5. 方便后续通过 Docker Compose 管理整套服务

4. Docker Compose 是什么

Docker Compose 用于管理多个 Docker 容器。

它通过一个 compose.yaml 文件描述整套服务，例如：

text 复制代码

services:
  mosquitto
  nodered
  homeassistant
  roomedge-core

后续只需要执行：

bash 复制代码

docker compose up -d

就可以一次性启动整套边缘网关服务。

在本项目中，Docker Compose 会作为 Rock 5T 边缘网关的基础部署方式。

5. 安装前环境检查

初始状态下，系统没有安装 Docker：

bash 复制代码

docker --version || true
docker compose version || true
systemctl is-active docker || true

输出：

text 复制代码

bash: docker: command not found
bash: docker: command not found
inactive

说明当前需要安装：

text 复制代码

Docker Engine
Docker CLI
containerd
Docker Buildx Plugin
Docker Compose Plugin

6. Docker 安装过程

先更新 apt 并安装基础工具：

bash 复制代码

sudo apt update
sudo apt install -y ca-certificates curl

创建 apt keyrings 目录：

bash 复制代码

sudo install -m 0755 -d /etc/apt/keyrings

原计划使用 Docker 官方源：

bash 复制代码

sudo curl -fsSL https://download.docker.com/linux/debian/gpg \
  -o /etc/apt/keyrings/docker.asc

但是这里遇到了网络问题。

7. Docker 官方源访问失败问题

问题现象

下载 Docker 官方 GPG key 时失败：

text 复制代码

curl: (35) Recv failure: Connection reset by peer

继续执行权限修改命令时：

bash 复制代码

sudo chmod a+r /etc/apt/keyrings/docker.asc

报错：

text 复制代码

chmod: cannot access '/etc/apt/keyrings/docker.asc': No such file or directory

原因分析

Docker 官方 GPG key 没有下载成功，所以 /etc/apt/keyrings/docker.asc 文件不存在。

如果此时继续添加 Docker 官方 apt 源，会导致后续 apt update 签名验证失败。

后续报错

添加 Docker 官方源后执行：

bash 复制代码

sudo apt update

报错：

text 复制代码

The following signatures couldn't be verified because the public key is not available:
NO_PUBKEY 7EA0A9C3F273FCD8

E: The repository 'https://download.docker.com/linux/debian bookworm InRelease' is not signed.

继续安装 Docker：

bash 复制代码

sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

报错：

text 复制代码

Package docker-ce is not available
Package docker-ce-cli is not available
Unable to locate package containerd.io
Unable to locate package docker-buildx-plugin
Unable to locate package docker-compose-plugin

这个问题不是 Docker 没有 arm64 包，而是 Docker apt 源没有被正确启用。

8. NodeSource 源干扰问题

执行 apt update 时，还出现了 NodeSource 源错误：

text 复制代码

Could not connect to deb.nodesource.com:443 (127.0.0.1)

查看 apt 源目录：

bash 复制代码

ls /etc/apt/sources.list.d/

发现存在：

text 复制代码

nodesource.sources

当前阶段暂时不需要 NodeSource，因此先临时禁用，而不是删除。

禁用命令：

bash 复制代码

sudo mkdir -p /etc/apt/sources.list.d/disabled

sudo mv /etc/apt/sources.list.d/nodesource.sources \
  /etc/apt/sources.list.d/disabled/nodesource.sources

后续需要恢复时：

bash 复制代码

sudo mv /etc/apt/sources.list.d/disabled/nodesource.sources \
  /etc/apt/sources.list.d/nodesource.sources

sudo apt update

9. 改用国内 Docker CE 镜像源

先清理之前失败的 Docker 源配置：

bash 复制代码

sudo rm -f /etc/apt/sources.list.d/docker.sources
sudo rm -f /etc/apt/keyrings/docker.asc

重新创建 keyrings 目录：

bash 复制代码

sudo install -m 0755 -d /etc/apt/keyrings

下载 Docker GPG key：

bash 复制代码

curl -fsSL https://mirrors.aliyun.com/docker-ce/linux/debian/gpg \
  | sudo tee /etc/apt/keyrings/docker.asc > /dev/null

设置权限：

bash 复制代码

sudo chmod a+r /etc/apt/keyrings/docker.asc

添加 Docker CE apt 源：

bash 复制代码

sudo tee /etc/apt/sources.list.d/docker.sources > /dev/null <<EOF
Types: deb
URIs: https://mirrors.aliyun.com/docker-ce/linux/debian
Suites: bookworm
Components: stable
Architectures: arm64
Signed-By: /etc/apt/keyrings/docker.asc
EOF

更新 apt：

bash 复制代码

sudo apt update

安装 Docker：

bash 复制代码

sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

10. 启动 Docker 服务

安装完成后，启动 Docker：

bash 复制代码

sudo systemctl enable docker
sudo systemctl start docker

查看 Docker 版本：

bash 复制代码

docker --version

输出：

text 复制代码

Docker version 29.4.1, build 055a478

查看 Docker Compose 版本：

bash 复制代码

sudo docker compose version

输出：

text 复制代码

Docker Compose version v5.1.3

查看 Docker 容器状态：

bash 复制代码

sudo docker ps

输出：

text 复制代码

CONTAINER ID   IMAGE     COMMAND   CREATED   STATUS    PORTS     NAMES

当前没有容器运行，这是正常状态。

11. Docker Hub 镜像拉取问题

安装完成后，尝试运行：

bash 复制代码

sudo docker run hello-world

输出：

text 复制代码

Unable to find image 'hello-world:latest' locally

随后长时间无响应。

这个现象说明：

text 复制代码

Docker 服务本身已经正常
但是从 Docker Hub 拉取镜像存在网络问题

因此需要配置 Docker 镜像加速。

12. 配置 Docker 镜像加速

创建 Docker daemon 配置文件：

bash 复制代码

sudo mkdir -p /etc/docker

sudo tee /etc/docker/daemon.json > /dev/null <<'EOF'
{
  "registry-mirrors": [
    "https://docker.1ms.run",
    "https://docker.xuanyuan.me",
    "https://docker.m.daocloud.io"
  ],
  "log-driver": "json-file",
  "log-opts": {
    "max-size": "50m",
    "max-file": "3"
  }
}
EOF

重启 Docker：

bash 复制代码

sudo systemctl daemon-reload
sudo systemctl restart docker

查看镜像源是否生效：

bash 复制代码

sudo docker info | grep -A 10 "Registry Mirrors"

输出：

text 复制代码

Registry Mirrors:
 https://docker.1ms.run/
 https://docker.xuanyuan.me/
 https://docker.m.daocloud.io/

说明镜像加速配置已经生效。

13. 使用 Mosquitto 镜像验证 Docker

因为后续边缘网关项目需要 MQTT Broker，所以直接使用 Mosquitto 镜像验证 Docker 是否可用。

拉取镜像：

bash 复制代码

sudo docker pull eclipse-mosquitto:2

输出：

text 复制代码

2: Pulling from library/eclipse-mosquitto
Pull complete
Status: Downloaded newer image for eclipse-mosquitto:2
docker.io/library/eclipse-mosquitto:2

运行 Mosquitto 帮助命令：

bash 复制代码

sudo docker run --rm eclipse-mosquitto:2 mosquitto -h

输出：

text 复制代码

mosquitto version 2.1.2

mosquitto is an MQTT v5.0/v3.1.1 broker.

Usage: mosquitto [-c config_file] [-d] [-h] [-p port] [-v]

说明 Docker 已经可以正常：

text 复制代码

1. 拉取镜像
2. 创建容器
3. 运行容器
4. 删除临时容器

14. 配置普通用户执行 Docker

默认情况下，执行 Docker 命令需要 sudo。

为了后续开发方便，将当前用户加入 docker 用户组：

bash 复制代码

sudo usermod -aG docker $USER
newgrp docker

验证：

bash 复制代码

docker ps

输出：

text 复制代码

CONTAINER ID   IMAGE     COMMAND   CREATED   STATUS    PORTS     NAMES

说明当前用户已经可以直接执行 Docker 命令。

注意：

text 复制代码

docker 用户组权限较高。
个人开发板上可以这样配置。
生产环境或公司服务器上需要谨慎使用。

15. 当前系统状态

当前 Rock 5T 上 Docker 环境状态：

text 复制代码

Docker Engine：已安装
Docker Compose Plugin：已安装
Docker 服务：已启动
Docker 镜像加速：已配置
Mosquitto 镜像：已成功拉取
普通用户 docker 权限：已配置

当前验证命令：

bash 复制代码

docker --version
docker compose version
docker ps
docker images

当前已验证镜像：

text 复制代码

eclipse-mosquitto:2

当前项目基础状态：

text 复制代码

Rock 5T / RK3588
└── Docker
    └── 可运行 arm64 容器

后续边缘网关服务可以基于 Docker Compose 继续部署。