首页/资讯中心/详情

ARM设备Docker实战：从安装到多架构镜像构建完整指南

ARM设备Docker实战：从安装到多架构镜像构建完整指南
📅 发布时间：2026/8/1 10:43:36

1. 项目概述：为什么要在ARM上折腾Docker？

如果你手头有一块树莓派，或者任何一块国产的ARM开发板（比如香橙派、瑞芯微RK系列、全志H系列），你可能会觉得它就是个“小玩具”，跑跑脚本、做个智能家居网关就到头了。但今天我想跟你聊聊，怎么把这些“小玩具”变成真正的生产力工具，核心就是Docker。你可能在x86服务器上玩Docker玩得很溜，命令敲得飞起，但一到ARM环境，docker pull下来的镜像经常跑不起来，报一堆exec format error，瞬间就懵了。这背后的原因，就是架构差异。

简单来说，我们常用的电脑和服务器（Intel/AMD）是x86_64架构，而树莓派这类板子用的是ARM架构（通常是arm64，也叫aarch64）。一个为x86编译的二进制程序，没法直接在ARM芯片上运行，反之亦然。Docker镜像里打包的正是这些二进制程序和应用依赖。所以，直接在ARM设备上拉取默认的、为x86构建的镜像，自然会失败。

那为什么还要在ARM上玩Docker呢？原因很实在：低成本、低功耗、场景贴合。用树莓派搭建一个24小时不间断运行的轻量级家庭服务器，跑个博客、挂个下载器、做智能家居中枢，电费几乎可以忽略不计。国产ARM芯片的板子更是性价比突出，在边缘计算、物联网网关、轻量级测试环境等场景下大有可为。掌握在ARM上配置Docker和构建多架构镜像的能力，意味着你能统一开发与部署环境，真正实现“一次构建，到处运行”的容器化理想，哪怕这个“到处”包含了从云端x86大服务器到角落里的ARM小盒子。

接下来，我会带你从零开始，完成三件事：第一，在树莓派/ARM设备上干净利落地安装和配置Docker；第二，理解并搞定让ARM跑起来的关键——如何获取和运行ARM架构的镜像；第三，也是最具价值的，教你如何自己构建同时支持x86和ARM的多架构镜像，彻底打破架构壁垒。

2. 核心准备：为你的ARM设备选择并安装操作系统

在安装Docker之前，一个稳定、可靠且软件源丰富的操作系统是基石。很多人拿到树莓派，直接用官方的Raspberry Pi OS（以前叫Raspbian），这没问题，它基于Debian，对硬件支持最完善。但对于想追求更通用或最新软件环境的，或者使用的是其他国产ARM板，就需要斟酌了。

2.1 主流操作系统选择与考量

对于树莓派，你有这些选择：

  • Raspberry Pi OS (Debian系)：官方首选，开箱即用，硬件驱动、GPIO库支持最完美。适合绝大多数应用，尤其是涉及硬件交互的项目。
  • Ubuntu Server for ARM：Canonical官方维护，软件包更新更激进，社区资源庞大。如果你熟悉Ubuntu，或者需要某些只在Ubuntu源里较新的软件，这是很好的选择。注意选择对应的arm64版本。
  • 其他发行版：如Alpine Linux（极度轻量，适合纯容器环境）、Manjaro ARM等，适合有特定偏好的用户。

对于国产ARM开发板（如香橙派、友善电子等），情况复杂一些：

  • 厂商提供的系统：通常基于Ubuntu或Debian的某个版本定制，包含了必要的内核驱动和硬件加速库。强烈建议起步时使用厂商推荐的系统镜像，这是避免后续各种硬件兼容性玄学问题的最快路径。
  • 社区维护的镜像：一些热门板子（比如瑞芯微RK3588系列）有活跃的社区，会维护更纯净、更新颖的Armbian或Ubuntu原生镜像。这适合在熟悉板子后，追求更干净系统的进阶用户。

注意：无论选择哪个系统，在安装Docker前，请务必通过uname -m或arch命令确认你的系统架构。对于近几年产的树莓派4B、5以及国产板子，输出应该是aarch64，这代表64位ARM。如果是armv7l，则是32位ARM。64位系统是更推荐的选择。

2.2 系统基础配置与避坑指南

烧录好系统镜像，首次启动后，别急着装Docker，先做好这几件小事，能让你后续流程顺畅数倍。

1. 扩展文件系统（仅针对树莓派等使用SD卡的情况）对于树莓派，使用官方镜像工具或Raspberry Pi Imager烧录后，系统可能只占用了SD卡的一部分空间。运行sudo raspi-config，选择Advanced Options->Expand Filesystem，重启后即可使用整张卡的空间。

2. 更换软件源（加速关键）默认的国外源在国内访问速度可能很慢。更换为国内镜像源能极大提升软件安装和更新的体验。

  • 对于 Raspberry Pi OS / Debian：
    sudo sed -i 's|deb.debian.org|mirrors.ustc.edu.cn|g' /etc/apt/sources.list sudo sed -i 's|security.debian.org|mirrors.ustc.edu.cn/debian-security|g' /etc/apt/sources.list # 如果是 Raspberry Pi OS，可能还需要更新raspi.list中的源 sudo sed -i 's|archive.raspberrypi.org|mirrors.ustc.edu.cn/archive.raspberrypi.org|g' /etc/apt/sources.list.d/raspi.list
  • 对于 Ubuntu：
    sudo sed -i 's|ports.ubuntu.com|mirrors.ustc.edu.cn|g' /etc/apt/sources.list

修改后，执行sudo apt update更新软件列表。

3. 设置静态IP（针对需要固定地址的场景）如果你打算把这台ARM设备作为服务器长期运行，一个固定的局域网IP会省去很多麻烦。修改/etc/dhcpcd.conf文件（Debian系常见）或/etc/netplan/下的配置文件（Ubuntu新版本），添加静态IP配置。

4. 实操心得：关于超频与散热网络热词里有“树莓派3b+超频”，这反映了大家对ARM设备性能的压榨需求。适当的超频确实能提升体验，但务必做好散热！一个小的散热片加上风扇，对于树莓派4B及以上是必需品，尤其是跑Docker这种可能持续负载的服务。超频操作通常在sudo raspi-config的Performance Options中，或者直接编辑/boot/config.txt。我的经验是，如果没有主动散热，宁可不要超频，稳定性远比那一点性能提升重要。

3. Docker引擎的安装与深度配置

系统就绪，现在可以安装Docker了。在ARM上安装Docker，最推荐使用Docker官方提供的一键安装脚本或仓库安装，这能保证你获得兼容性最好的版本。

3.1 官方脚本安装：最省心的方式

Docker官方提供了一个便捷的安装脚本，它会自动检测你的系统并安装合适的版本。

curl -fsSL https://get.docker.com -o get-docker.sh sudo sh get-docker.sh

执行后，脚本会自动完成添加Docker仓库、安装Docker引擎（docker-ce）、命令行工具（docker-ce-cli）以及容器运行时（containerd.io）等一系列操作。安装完成后，建议将当前用户加入docker组，这样就不用每次都sudo了：

sudo usermod -aG docker $USER

重要：执行此命令后，你需要完全退出当前终端会话并重新登录，或者重启系统，用户组变更才会生效。否则，你会持续遇到“权限被拒绝”的错误。

3.2 仓库安装：更可控的选择

如果你希望更清晰地控制安装过程，或者系统版本比较特殊，可以采用仓库安装。

# 1. 卸载旧版本（如果有） sudo apt remove docker docker-engine docker.io containerd runc # 2. 安装依赖工具 sudo apt update sudo apt install -y ca-certificates curl gnupg # 3. 添加Docker官方GPG密钥和仓库 sudo install -m 0755 -d /etc/apt/keyrings curl -fsSL https://download.docker.com/linux/debian/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg sudo chmod a+r /etc/apt/keyrings/docker.gpg echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/debian $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null # 4. 安装Docker引擎 sudo apt update sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

这里的命令是针对Debian系的，如果你是Ubuntu，仓库地址中的debian需要替换为ubuntu。$(dpkg --print-architecture)会自动识别你的架构（如arm64），确保拉取正确的安装包。

3.3 安装后关键配置与验证

安装完成，先别急着跑容器，几个配置能让后续使用更顺手。

1. 配置Docker镜像加速器这是在国内环境必须做的一步，否则docker pull速度会慢到怀疑人生。修改或创建/etc/docker/daemon.json文件：

{ "registry-mirrors": [ "https://docker.mirrors.ustc.edu.cn", "https://hub-mirror.c.163.com", "https://mirror.baidubce.com" ] }

你可以选择一个或多个镜像加速地址。编辑保存后，重启Docker服务使配置生效：

sudo systemctl restart docker

2. 验证安装与基本操作运行一个最简单的ARM架构容器来测试整个环境是否工作正常：

docker run --rm arm64v8/hello-world

这个arm64v8/hello-world镜像是Docker官方提供的、专为ARM64架构构建的测试镜像。如果一切顺利，你会看到一段“Hello from Docker!”的欢迎信息。这个命令的--rm参数表示容器退出后自动删除，避免留下无用的容器。

3. 常见问题排查

  • docker: command not found：安装未成功，或者安装后没有重新登录终端使PATH生效。可以尝试sudo apt install docker.io安装旧版本测试，或者检查安装日志。
  • Cannot connect to the Docker daemon：Docker服务没有启动，或者当前用户没有docker组权限。执行sudo systemctl start docker启动服务，并确认已按上述步骤将用户加入docker组且已重新登录。
  • exec format error：这通常是因为你尝试运行了一个非ARM架构的镜像。这是接下来我们要解决的核心问题。

4. 理解与获取ARM架构的Docker镜像

当你第一次在树莓派上docker run nginx时，很可能就会遇到上面提到的exec format error。这是因为Docker Hub上很多官方镜像的latest标签默认指向amd64（即x86_64）架构的镜像。我们需要学会如何找到并拉取正确的ARM版本。

4.1 镜像架构标签的奥秘

Docker镜像可以通过标签来指定架构和操作系统。一个完整的镜像名格式是：[仓库地址]/[命名空间]/[镜像名]:[标签]。对于多架构镜像，标签策略是关键。

  • 显式架构标签：很多官方镜像提供了明确的架构标签，例如：

    • nginx:latest（默认，可能是amd64）
    • nginx:alpine（默认，可能是amd64）
    • arm64v8/nginx:latest（ARM64架构的nginx）
    • arm32v7/nginx:latest（ARMv7 32位架构的nginx）
    • nginx:latest-arm64（另一种标签风格）

    对于nginx、redis、python等流行镜像，通常存在一个独立的命名空间（如arm64v8）来存放ARM构建。你需要去Docker Hub的对应镜像页面查看“Tags”标签页，寻找包含arm64、aarch64或arm的标签。

  • 多架构清单镜像（Manifest List）：这是更现代、更优雅的解决方案。像hello-world:latest这样的镜像，实际上是一个“清单列表”，它包含了指向amd64、arm64、arm/v7等多个架构具体镜像的指针。当你docker pull hello-world:latest时，Docker客户端会自动根据你的机器架构拉取对应的镜像实体。越来越多的官方镜像正在采用这种方式。

4.2 如何寻找和拉取ARM镜像

方法一：使用docker pull指定全名如果你知道ARM镜像的确切名称，直接拉取即可：

docker pull arm64v8/ubuntu:22.04 docker pull arm64v8/python:3.11-slim

方法二：在Docker Hub上搜索访问 hub.docker.com ，搜索你需要的软件，比如nginx。进入官方镜像页面，点击“Tags”标签。在搜索框输入arm64，过滤出所有ARM64架构的标签。你会看到类似1.25-alpine这样的标签，旁边可能会有小图标或linux/arm64的说明，这就是支持ARM64的。

方法三：使用docker manifest命令探查（需要开启实验性功能）这是一个非常强大的工具，可以查看一个镜像标签支持哪些架构。首先，在~/.docker/config.json中启用实验性功能（如果不存在就创建）：

{ "experimental": "enabled" }

然后，你可以使用（注意，docker manifest命令需要先docker manifest inspect，但拉取清单需要不同命令，更常用的是docker buildx）：

# 查看镜像支持哪些架构 docker buildx imagetools inspect nginx:latest

这个命令会输出一个JSON，其中manifests数组里会列出该镜像标签支持的所有平台（如linux/amd64，linux/arm64）。

4.3 搭建私有ARM镜像仓库的实用技巧

在企业内网或需要加速大量镜像拉取的场景，搭建一个本地镜像仓库缓存（如Harbor）很有用。但需要注意，简单的镜像仓库只是存储镜像，它本身不转换架构。你需要做的是：

  1. 在你的ARM设备上，拉取你需要的ARM架构基础镜像（如arm64v8/ubuntu）。
  2. 给这个镜像打上符合你私有仓库规范的标签，例如my-registry.com/library/ubuntu:22.04-arm64。
  3. 将其推送到你的私有仓库：docker push my-registry.com/library/ubuntu:22.04-arm64。
  4. 在其他ARM设备上，就可以从你的私有仓库拉取这个镜像了。

关键在于，你需要主动去拉取ARM版本的镜像并推送到仓库，而不是简单地把x86的镜像推上去。你可以编写脚本，定期从Docker Hub同步常用的ARM基础镜像到你的私有仓库，供内网开发测试使用。

5. 构建多架构Docker镜像：一次构建，处处运行

拉取现成的ARM镜像解决了“用”的问题，但当我们自己开发应用需要打包成镜像时，如何制作一个既能跑在x86服务器又能跑在树莓派上的镜像呢？这就需要用到多架构镜像构建。其核心是创建一个“清单列表”，里面包含了指向不同架构具体镜像的指针。

5.1 传统交叉编译与构建的困境

最朴素的想法是：我在x86开发机上，用交叉编译工具链编译出ARM的可执行文件，然后打包进镜像。这当然可行，但非常麻烦：

  1. 需要配置复杂的交叉编译环境。
  2. 如果依赖本地库（libxxx.so），还需要确保这些库也是ARM版本的。
  3. 构建脚本不通用，难以融入CI/CD流程。

5.2 使用Buildx：官方推荐的多架构构建神器

Docker Buildx是Docker官方推出的扩展构建工具，它原生支持多平台构建，其底层利用了QEMU进行硬件模拟，让你可以在x86机器上构建出ARM架构的镜像，反之亦然。

1. 启用并创建Buildx构建器高版本Docker Desktop默认已安装并启用Buildx。在Linux上，你可能需要手动安装docker-buildx-plugin包（我们前面安装的完整命令已包含）。然后，创建一个新的支持多架构的构建器实例：

# 创建并使用一个多架构构建器 docker buildx create --name multi-arch-builder --driver docker-container --bootstrap --use

这个命令会创建一个基于容器驱动的构建器，它内部使用QEMU来模拟其他架构的CPU。

2. 编写支持多架构的Dockerfile你的Dockerfile本身不需要为多架构做特殊改动，但需要遵循一些最佳实践：

  • 尽量使用多架构基础镜像：例如，使用python:3.11-slim而不是python:3.11-slim-bullseye，因为前者是多架构清单镜像，后者可能只是特定架构的单一镜像。在Dockerfile开头使用FROM --platform=$TARGETPLATFORM是一种更明确的写法，但需要配合Buildx参数。
  • 避免在Dockerfile中执行架构相关的硬编码操作：比如，不要写死apt-get install -y package:amd64这样的包名。

一个简单的示例Dockerfile：

# 使用多架构镜像作为基础 FROM python:3.11-slim WORKDIR /app COPY requirements.txt . RUN pip install --no-cache-dir -r requirements.txt COPY . . CMD ["python", "app.py"]

3. 使用Buildx进行多架构构建与推送这是最关键的一步。假设我们要构建一个支持linux/amd64和linux/arm64的镜像：

docker buildx build \ --platform linux/amd64,linux/arm64 \ -t your-username/your-app:latest \ -t your-username/your-app:v1.0 \ --push .

解释一下参数：

  • --platform：指定要构建的目标平台列表，用逗号分隔。
  • -t：为生成的镜像打标签。同一个标签会被附加到所有架构的镜像上，并最终汇集到清单列表。
  • --push：构建完成后，自动将所有架构的镜像以及清单列表推送到镜像仓库（如Docker Hub）。如果不加此参数，构建结果只存在于本地构建缓存中，无法直接使用docker run。
  • .：构建上下文路径。

执行这个命令后，Buildx会：

  1. 分别为linux/amd64和linux/arm64两个平台各构建一个独立的镜像层。
  2. 将这两个独立的镜像推送到仓库。
  3. 创建一个名为your-username/your-app:latest的“清单列表”，其中包含指向这两个具体镜像的指针。

4. 验证多架构镜像构建并推送成功后，你可以在任何机器上拉取这个镜像，Docker会自动选择匹配的架构：

# 在x86电脑上，会自动拉取amd64版本 docker pull your-username/your-app:latest # 在树莓派上，会自动拉取arm64版本 docker pull your-username/your-app:latest

你也可以用之前提到的命令查看清单：

docker buildx imagetools inspect your-username/your-app:latest

5.3 多架构构建的进阶技巧与避坑指南

  • QEMU模拟的性能问题：在x86上构建ARM镜像（或反之）时，由于需要QEMU进行指令集模拟，构建速度会非常慢，尤其是需要编译大量代码时。解决方案是使用原生ARM构建节点。你可以将树莓派或其他ARM服务器作为Buildx的远程构建节点，加入到你的多架构构建器中，这样构建ARM镜像时就会直接在ARM机器上原生执行，速度极快。这需要配置Docker守护进程的远程TCP端口和证书，属于进阶用法。
  • COPY --from跨平台问题：在多阶段构建中，如果FROM的基础镜像和COPY --from的源镜像平台不一致，可能会失败。确保你的多阶段构建中所有阶段都明确指定或兼容目标平台。
  • 构建缓存：为不同平台构建时，缓存是分开的。合理利用--cache-from和--cache-to参数可以加速后续构建。
  • CI/CD集成：在GitHub Actions、GitLab CI等环境中，都有现成的Action或Runner支持Buildx多架构构建。核心思路就是在任务中启用QEMU并创建多架构构建器。

6. 实战：从零部署一个ARM原生应用栈

理论说再多，不如动手做一遍。让我们用一个经典的Web应用栈（Nginx + Python Flask + Redis）来实战，全部在树莓派上以Docker容器方式运行，并使用Docker Compose编排。

6.1 应用结构与Dockerfile编写

假设我们有一个简单的Flask计数器应用，它使用Redis存储访问次数。

项目结构：

my-counter-app/ ├── docker-compose.yml ├── flask-app/ │ ├── Dockerfile │ ├── app.py │ └── requirements.txt └── nginx/ └── nginx.conf

flask-app/app.py:

from flask import Flask import redis import os app = Flask(__name__) # 从环境变量获取Redis主机名，在Docker Compose中会链接 redis_host = os.environ.get('REDIS_HOST', 'localhost') redis_client = redis.Redis(host=redis_host, port=6379, decode_responses=True) @app.route('/') def hello(): count = redis_client.incr('hits') return f'Hello from ARM Docker! This page has been viewed {count} times.' if __name__ == '__main__': app.run(host='0.0.0.0', port=5000)

flask-app/requirements.txt:

flask==2.3.3 redis==4.6.0

flask-app/Dockerfile:

# 使用多架构支持的Python slim镜像 FROM python:3.11-slim WORKDIR /app COPY requirements.txt . # 使用国内PyPI镜像加速安装 RUN pip install --no-cache-dir -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple COPY . . CMD ["python", "app.py"]

nginx/nginx.conf:

events { worker_connections 1024; } http { upstream flask_app { server flask:5000; # 使用Docker Compose中的服务名‘flask’ } server { listen 80; location / { proxy_pass http://flask_app; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; } } }

6.2 Docker Compose编排文件解析

docker-compose.yml:

version: '3.8' services: redis: image: arm64v8/redis:7-alpine # 指定ARM64版本的Redis container_name: counter-redis restart: unless-stopped volumes: - redis_data:/data command: redis-server --appendonly yes # 开启持久化 flask: build: ./flask-app # 使用我们编写的Dockerfile构建 container_name: counter-flask restart: unless-stopped environment: - REDIS_HOST=redis # 通过服务名连接Redis depends_on: - redis nginx: image: arm64v8/nginx:alpine # 指定ARM64版本的Nginx container_name: counter-nginx restart: unless-stopped ports: - "8080:80" # 将宿主机的8080端口映射到容器的80端口 volumes: - ./nginx/nginx.conf:/etc/nginx/nginx.conf:ro # 挂载自定义配置 depends_on: - flask volumes: redis_data: # 定义命名卷，持久化Redis数据

这个Compose文件定义了三个服务，它们会在同一个自定义网络中自动互联，flask服务可以通过redis这个主机名访问Redis容器。

6.3 启动、管理与验证

在项目根目录（my-counter-app/）下，执行：

# 启动所有服务（在后台运行） docker-compose up -d # 查看运行状态 docker-compose ps # 查看实时日志 docker-compose logs -f flask # 停止服务 docker-compose down # 停止并删除数据卷（谨慎使用） docker-compose down -v

启动后，打开浏览器，访问http://你的树莓派IP:8080。每次刷新页面，计数器都会增加，这说明Flask应用和Redis都在正常工作，而Nginx则充当了反向代理。

这个实战案例展示了在ARM设备上，通过Docker Compose编排多容器应用的标准流程。你可以轻松地将flask替换成任何其他应用，将redis替换成MySQL、PostgreSQL等其他ARM可用的数据库镜像。

7. 性能调优、监控与日常维护

让服务跑起来只是第一步，如何让它跑得稳、跑得快，才是更重要的。

7.1 ARM设备上Docker的性能调优

  • 存储驱动：对于树莓派（使用SD卡），默认的overlay2存储驱动是合适的。但如果你使用了外接USB 3.0 SSD，性能会得到巨大提升。在/etc/docker/daemon.json中可以配置存储驱动，但通常不需要改动。
  • 内存与交换空间：ARM设备内存有限（常见1GB-8GB）。务必监控容器内存使用，避免内存耗尽导致系统崩溃。可以通过docker stats命令实时查看。适当增加交换空间（swap）可以作为缓冲，但注意SD卡上的交换分区频繁读写会损伤卡并降低性能。更好的方法是优化应用内存使用，或为设备增加内存（如果支持）。
  • CPU限制：在docker run或Compose文件中，可以使用--cpus或cpus选项为容器分配CPU份额，防止某个容器吃光所有CPU资源，影响宿主机和其他容器。

7.2 简易监控与日志管理

  • 基础监控命令：
    # 查看容器实时资源占用 docker stats # 查看所有容器的状态 docker ps -a # 查看指定容器的详细配置和状态 docker inspect <container_name>
  • 日志查看与导出：
    # 查看容器最新日志 docker logs <container_name> # 跟踪实时日志 docker logs -f <container_name> # 将日志导出到文件 docker logs <container_name> > app.log 2>&1
    对于生产环境，建议将容器日志通过json-file或syslog驱动配置，集中收集到日志服务器（如ELK栈），但这对ARM设备可能负担较重，简易方案是定期清理旧日志。

7.3 数据持久化与备份策略

容器本身是无状态的，重要数据必须持久化。

  • 绑定挂载（Bind Mount）：将宿主机目录映射到容器内，如-v /home/pi/app-data:/data。管理简单，备份直接对宿主机目录操作即可。
  • 命名卷（Named Volume）：Docker管理的存储区域，如Compose示例中的redis_data。位置由Docker管理（通常在/var/lib/docker/volumes/下），备份时需要先找到对应目录。
  • 备份建议：对于数据库等关键数据，除了卷备份，更应在容器内使用导出命令（如mysqldump，redis-cli SAVE）进行逻辑备份，并将备份文件传输到其他安全位置。可以利用cron定时任务执行备份脚本。

7.4 常见问题与故障排查实录

  1. 容器启动失败，日志显示standard_init_linux.go:228: exec user process caused: exec format error

    • 原因：99%是因为镜像架构与宿主机不匹配。你运行了一个x86的镜像在ARM上。
    • 解决：确认你拉取或构建的是ARM架构的镜像。使用docker image inspect --format='{{.Architecture}}' <image_name>查看镜像架构。

  2. docker pull或docker build速度极慢

    • 原因：网络连接Docker Hub不畅。
    • 解决：确保已正确配置国内镜像加速器（/etc/docker/daemon.json）。对于docker build中RUN apt-get update慢，可以在Dockerfile中更换Debian/Ubuntu的软件源为国内源。

  3. 宿主机磁盘空间不足

    • 原因：Docker镜像、容器和卷会持续占用空间。
    • 解决：定期清理。
      # 删除所有已停止的容器 docker container prune # 删除所有未被使用的镜像（悬空镜像） docker image prune # 删除所有未被使用的卷（谨慎！确保数据已备份） docker volume prune # 一键清理所有未被使用的资源 docker system prune -a

  4. Docker服务无法启动，报错关于iptables或cgroup

    • 原因：系统内核或相关模块不支持，或者与已有服务冲突。
    • 解决：首先更新系统sudo apt update && sudo apt upgrade。对于树莓派，确保使用的是官方或兼容的64位内核。极少情况下需要修改/boot/cmdline.txt添加cgroup相关参数。如果之前安装过旧版本Docker，请彻底卸载清理后再安装新版本。

  5. 在Compose中，服务之间无法通过服务名通信

    • 原因：服务依赖启动顺序问题，或者网络配置问题。
    • 解决：使用depends_on仅控制启动顺序，不保证应用已就绪。更健壮的做法是在应用内添加重试逻辑，或者使用healthcheck。确保所有服务在同一个默认的Compose网络中（默认会自动创建）。