在国产化技术栈的落地过程中，龙芯平台上的软件生态适配是一个关键且实际的挑战。对于需要容器化部署的应用，Docker 是绕不开的基础设施。然而，在龙芯 3B6000 这类 LoongArch 架构的机器上，直接使用官方仓库的 Docker 安装包通常行不通，因为官方主要提供 x86_64 和 ARM64 架构的包。安装高版本 Docker（如 29.5.1）往往需要从源码编译或寻找适配的 RPM 包，这个过程涉及依赖解决、架构适配和配置调整，稍有不慎就会遇到各种兼容性问题。本文将详细记录在龙芯 3B6000 服务器上，通过 RPM 包成功安装并运行 Docker 29.5.1 的完整过程，涵盖从环境准备、依赖解决、安装配置到验证排错的每一个步骤，目标是提供一份可复现的操作指南。

1. 理解龙芯平台与 Docker 安装的核心挑战

在 x86 或常见的 ARM 服务器上，安装 Docker 通常只需几条 yum 或 apt 命令。但在龙芯 3B6000（LoongArch 架构）上，情况则复杂得多。首要问题是软件源。主流的 Docker 官方仓库和 CentOS/RedHat 的 EPEL 仓库都没有提供 LoongArch 架构的二进制包。这意味着我们无法通过标准的包管理器命令直接安装。

因此，安装路径通常只剩下两种：一是从源码编译，二是寻找第三方已经编译好的、针对 LoongArch 架构的 RPM 包。源码编译耗时耗力，且对编译环境要求高，更适合深度定制。对于大多数生产或测试环境，使用预编译的 RPM 包是更高效的选择。然而，这带来了第二个挑战： 依赖地狱 。Docker 并非一个独立的二进制文件，它依赖 containerd 、 runc 、 libseccomp 等一系列组件，这些组件同样需要适配 LoongArch 架构。一个组件的版本不匹配，就可能导致整个 Docker 服务无法启动。

第三个挑战是 内核兼容性 。Docker 依赖于 Linux 内核的特定功能，如 Cgroups、命名空间、OverlayFS 等。虽然龙芯的 Linux 内核已经支持这些特性，但某些内核模块的版本或配置可能需要调整。例如，存储驱动（如 overlay2 ）和网络功能（如 iptables ）需要确保在内核中已启用且工作正常。

基于以上挑战，本次安装的核心思路是： 寻找一组版本匹配、架构为 LoongArch 的 Docker 及其相关组件的 RPM 包，手动解决依赖关系，然后进行安装和配置 。

2. 环境准备与依赖检查

在开始安装之前，必须对目标系统环境进行彻底的检查和准备。一个清晰的环境基线是后续所有操作成功的基础。

2.1 确认系统与架构信息

首先，登录龙芯 3B6000 服务器，通过以下命令确认系统版本和 CPU 架构。

# 查看操作系统版本
cat /etc/os-release

# 查看内核版本
uname -r

# 查看 CPU 架构
uname -m

对于龙芯 3B6000， uname -m 的输出应为 loongarch64 。本文的操作基于一个常见的发行版环境，例如 Loongnix Server 20 或基于开源社区适配的 CentOS 7/8 龙芯版本。请记录下你的具体系统版本，因为不同发行版的包管理器和基础库可能存在差异。

2.2 检查内核模块与功能支持

Docker 需要一些特定的内核模块。运行以下命令检查它们是否已加载或可用。

# 检查 overlay 文件系统支持
lsmod | grep overlay

# 检查网络桥接和 netfilter 支持（用于 iptables）
lsmod | grep bridge
lsmod | grep nf_conntrack

# 检查 Cgroups 支持
grep cgroup /proc/filesystems

# 检查存储驱动支持，overlay2 是推荐驱动
grep overlay /proc/filesystems

如果 overlay 模块未加载，可以尝试 sudo modprobe overlay 临时加载。要永久生效，需要将其添加到 /etc/modules-load.d/ 下的配置文件中。同时，确保内核配置开启了 CONFIG_OVERLAY_FS 等选项，这通常在龙芯适配的内核中已经完成。

2.3 安装基础工具和配置仓库

确保系统包管理器（如 yum 或 dnf ）可用，并安装一些必要的编译和工具软件，这在后续解决依赖时可能会用到。

# 对于 yum 系系统（如 CentOS、Loongnix）
sudo yum install -y wget curl tar gcc make rpm-build yum-utils

# 对于 apt 系系统（如 UOS、Deepin）
# sudo apt update && sudo apt install -y wget curl tar gcc make dpkg-dev

由于我们要安装 RPM 包，因此系统必须是 RPM 系的（如 CentOS, Fedora, Loongnix）。如果系统是 Debian 系，则需要使用 alien 等工具转换包格式，这不在本文讨论范围内。

3. 获取 LoongArch 架构的 Docker RPM 包

这是最关键的一步。我们需要找到一组版本匹配的 Docker 组件 RPM 包。通常，这些包来源于龙芯社区、操作系统厂商的软件仓库或第三方开发者维护的构建。

3.1 确定包来源

一个可靠的来源是龙芯开源社区或你所使用的操作系统发行版提供的软件仓库。例如，某些龙芯社区镜像站可能提供了 docker-ce 的测试仓库。

你可以先尝试添加社区仓库：

# 示例：添加龙芯社区 EL 8 仓库（请根据你的系统版本调整）
sudo yum-config-manager --add-repo http://mirrors.loongnix.cn/loongnix/loongnix.repo

# 更新仓库缓存
sudo yum makecache

然后搜索 Docker 包：

yum search docker-ce --showduplicates

如果仓库中有 loongarch64 架构的 docker-ce-29.5.1 ，那么可以直接安装，这是最简便的方式。但根据经验，高版本 Docker 可能尚未进入稳定仓库。

3.2 手动下载 RPM 包

如果仓库中没有，就需要手动寻找并下载 RPM 包。你可以从以下途径寻找：

1. 龙芯的软件包构建平台（如 openEuler LoongArch 仓库）。
2. 其他开发者公开的构建结果（GitHub Releases）。
3. 从源码在本地编译生成。

假设我们已经找到了以下必需组件的 RPM 包（版本为示例，请以实际找到的 29.5.1 版本为准）：

• containerd.io-1.6.31-1.loongarch64.rpm
• docker-ce-29.5.1-1.loongarch64.rpm
• docker-ce-cli-29.5.1-1.loongarch64.rpm
• docker-ce-rootless-extras-29.5.1-1.loongarch64.rpm (可选)
• docker-buildx-plugin-0.14.0-1.loongarch64.rpm
• docker-compose-plugin-2.27.1-1.loongarch64.rpm

将这些包下载到服务器的某个目录，例如 /opt/docker-rpms/ 。

sudo mkdir -p /opt/docker-rpms
cd /opt/docker-rpms
# 使用 wget 或 curl 下载上述包，此处为示例命令，实际 URL 需替换
# wget http://example.com/path/to/containerd.io-1.6.31-1.loongarch64.rpm
# wget http://example.com/path/to/docker-ce-29.5.1-1.loongarch64.rpm
# ... 下载其他包

3.3 解决依赖关系

直接使用 rpm -ivh 安装可能会因为缺少依赖而失败。我们可以使用 yum localinstall 命令，它会自动尝试从已配置的仓库中解决依赖。但龙芯仓库可能不包含所有依赖，因此需要手动处理。

首先，尝试安装最底层的依赖 containerd.io ：

cd /opt/docker-rpms
sudo yum localinstall containerd.io-*.rpm

如果报告缺少依赖（如 libseccomp >= 2.3 ），则需要先找到并安装这些依赖的 LoongArch 版本包。同样，可以从系统仓库或龙芯社区仓库搜索安装。

# 示例：从系统仓库安装 libseccomp
sudo yum install libseccomp

如果系统仓库的版本过低，你需要寻找更高版本的 libseccomp RPM 包并手动安装。 依赖解决是一个迭代过程 ，可能需要多次尝试，安装一个包，解决其依赖，再安装下一个。

一个实用的技巧是使用 rpm -qpR 命令查看一个 RPM 包的具体依赖：

rpm -qpR docker-ce-29.5.1-1.loongarch64.rpm

4. 安装 Docker 组件并配置服务

当所有依赖都满足后，就可以安装 Docker 主组件了。

4.1 执行安装

在 /opt/docker-rpms 目录下，执行批量安装：

sudo yum localinstall *.rpm

yum localinstall 会处理包之间的依赖顺序。如果一切顺利，所有包都会被成功安装。

4.2 关键配置调整

安装完成后，Docker 的配置文件位于 /etc/docker/daemon.json 。默认情况下这个文件可能不存在，我们需要创建它并进行一些关键配置，尤其是对于国内环境。

sudo tee /etc/docker/daemon.json <<-'EOF'
{
  "exec-opts": ["native.cgroupdriver=systemd"],
  "log-driver": "json-file",
  "log-opts": {
    "max-size": "100m",
    "max-file": "3"
  },
  "storage-driver": "overlay2",
  "storage-opts": [
    "overlay2.override_kernel_check=true"
  ],
  "registry-mirrors": [
    "https://docker.mirrors.ustc.edu.cn",
    "https://hub-mirror.c.163.com"
  ],
  "live-restore": true,
  "iptables": false
}
EOF

配置项解释：

• native.cgroupdriver=systemd : 让 Docker 使用 systemd 的 cgroup 驱动，这与使用 systemd 作为 init 系统的 Linux 发行版（如 CentOS 8, Loongnix）更兼容。
• log-driver 和 log-opts : 配置日志，防止日志文件无限增长。
• storage-driver : 设置为 overlay2 ，这是当前推荐且性能较好的存储驱动。
• registry-mirrors : 非常重要 。添加国内镜像加速器，可以极大提升拉取镜像的速度。
• iptables : 在龙芯平台上，有时 Docker 自带的 iptables 规则可能与系统冲突，导致网络问题。如果遇到容器无法访问外网或宿主机无法访问容器端口的问题，可以尝试将其设置为 false ，并依靠系统防火墙管理规则。这是一个可能需要根据实际情况调整的选项。

4.3 启动并设置开机自启

配置完成后，启动 Docker 守护进程并设置开机自启。

# 重新加载 systemd 配置
sudo systemctl daemon-reload

# 启动 docker 服务
sudo systemctl start docker

# 设置开机自启
sudo systemctl enable docker

# 查看服务状态，确认是否运行正常
sudo systemctl status docker

如果状态显示为 active (running) ，则说明 Docker 服务已经成功启动。

5. 验证安装与运行测试

服务启动成功只是第一步，我们需要验证 Docker 的核心功能是否完全正常。

5.1 基础命令验证

运行 docker version 和 docker info ，检查客户端和服务器端版本信息，以及系统级配置。

docker version
docker info

docker info 的输出中，需要重点关注以下几行：

• Server Version: 29.5.1 (确认版本)
• OSType: linux
• Architecture: loongarch64 (确认架构)
• Cgroup Driver: systemd (确认配置生效)
• Storage Driver: overlay2 (确认存储驱动)
• Logging Driver: json-file (确认日志驱动)

5.2 运行一个测试容器

为了彻底验证 Docker 的拉取镜像、创建容器、网络和存储功能，我们运行一个最简单的容器。

# 拉取一个 LoongArch 架构的轻量级镜像进行测试
# 这里以 busybox 为例，你需要确认该镜像有 loongarch64 版本
# 如果没有，可以尝试从支持多架构的仓库拉取，或者使用一个已知的 LoongArch 镜像
docker pull busybox:latest

# 运行容器，执行一个简单命令
docker run --rm busybox echo "Hello, LoongArch Docker!"

如果命令成功执行并输出了 “Hello, LoongArch Docker!”，则说明 Docker 引擎、镜像拉取和容器运行功能基本正常。

5.3 测试容器网络与持久化（可选）

进行更深入的测试：

# 测试容器网络：运行一个长期运行的容器并映射端口
docker run -d --name test-nginx -p 8080:80 nginx:alpine
# 注意：nginx:alpine 镜像可能没有 loongarch64 版本，此命令可能失败。
# 更可靠的测试是使用一个已知的、有 LoongArch 版本的镜像，例如：
# docker run -d --name test-web -p 8080:80 httpd:alpine

# 测试宿主机能否访问
curl http://localhost:8080

# 测试容器数据卷
docker run --rm -v /tmp/data:/data busybox sh -c "echo 'test data' > /data/test.txt"
cat /tmp/data/test.txt

6. 常见问题排查与解决方案

在龙芯平台上安装高版本 Docker，几乎一定会遇到各种问题。下面列出典型问题及其排查路径。

6.1 服务启动失败： Failed to start Docker Application Container Engine.

这是最常见的问题。首先使用 journalctl 查看 Docker 服务的详细日志。

sudo journalctl -u docker.service --no-pager -n 50

根据日志中的关键错误信息进行排查：

错误现象	可能原因	检查与解决方案
failed to start daemon: Error initializing network controller: error obtaining controller instance: failed to create NAT chain DOCKER: iptables failed	iptables 版本或规则冲突。	1. 确认 iptables 和 nftables 命令是否存在且版本兼容。 2. 在 /etc/docker/daemon.json 中尝试添加 "iptables": false 。 3. 重启 Docker 服务。
failed to start daemon: Devices cgroup isn‘t mounted	系统未启用 cgroup，或 cgroup 挂载不正确。	1. 检查 /proc/filesystems 是否包含 cgroup 。 2. 检查 /sys/fs/cgroup 目录是否存在且已挂载。 3. 确保内核启动参数正确，可尝试在 GRUB 配置中添加 cgroup_enable=memory swapaccount=1 。
failed to start daemon: error while opening volume store metadata database: timeout	存储驱动初始化失败，可能是文件系统或权限问题。	1. 检查 /var/lib/docker 目录的权限，应为 root:root 。 2. 确认 /etc/docker/daemon.json 中的 storage-driver 是 overlay2 。 3. 检查内核是否支持 overlay2: grep overlay /proc/filesystems 。 4. 尝试清理旧的 Docker 数据（谨慎操作）： sudo rm -rf /var/lib/docker/* 。
failed to start daemon: containerd: ... version mismatch	containerd 版本与 Docker 不兼容。	确保安装的 containerd.io RPM 包版本与 Docker CE 版本匹配。Docker 29.x 通常需要 containerd 1.6.x 或更高版本。

6.2 拉取镜像失败： no matching manifest for linux/loongarch64 in the manifest list

Docker 在拉取镜像时，会根据宿主机的架构（ loongarch64 ）去寻找对应的镜像层。如果该镜像仓库没有提供 LoongArch 架构的镜像，就会报此错误。

解决方案：

1. 寻找替代镜像 ：在 Docker Hub 或其他仓库中搜索明确支持 linux/loongarch64 的镜像。一些基础镜像（如 busybox , alpine , centos ）的社区可能已经提供了 LoongArch 版本。
2. 使用多架构镜像 ：有些镜像（如 hello-world ）是“多架构”的，其 manifest list 包含了多种架构，Docker 会自动选择正确的版本。可以尝试拉取 hello-world 测试。
3. 自行构建镜像 ：这是最根本的解决方案。你需要一个 Dockerfile ，并在龙芯机器上使用 docker build 命令进行构建，生成的镜像就是 LoongArch 架构的。

6.3 容器内部网络不通或端口无法访问

如果容器能运行，但无法访问外部网络，或者宿主机无法通过映射端口访问容器服务。

排查步骤：

1. 检查容器内部网络 ：

   docker run --rm busybox ping -c 4 8.8.8.8
   

2. 检查宿主机 iptables 规则 ：即使 Docker 配置了 "iptables": false ，它仍会操作一些链。运行 sudo iptables -L -n -v 和 sudo iptables -t nat -L -n -v ，查看 DOCKER 链和相关规则是否存在。
3. 检查防火墙 ：宿主机防火墙（如 firewalld ）可能阻止了 Docker 的网桥流量或映射端口。

   sudo firewall-cmd --list-all
   # 如果需要，开放端口或信任 docker 网桥
   sudo firewall-cmd --permanent --zone=trusted --add-interface=docker0
   sudo firewall-cmd --reload
   

4. 检查内核转发 ：确保系统启用了 IP 转发。

   cat /proc/sys/net/ipv4/ip_forward
   # 如果为 0，则启用
   echo 1 | sudo tee /proc/sys/net/ipv4/ip_forward
   # 永久生效：编辑 /etc/sysctl.conf，设置 net.ipv4.ip_forward = 1
   

7. 生产环境最佳实践与后续步骤

在测试环境成功运行 Docker 后，若计划用于生产，还需要考虑以下方面。

7.1 镜像源与安全配置

• 私有镜像仓库 ：在生产环境中，应搭建私有镜像仓库（如 Harbor），并将常用基础镜像推送到私有仓库。在 /etc/docker/daemon.json 中配置 insecure-registries 或配置 TLS 证书。
• 守护进程安全 ：考虑配置 Docker 守护进程的 TLS 认证，以保护远程 API 端口。避免将 Docker 套接字 ( /var/run/docker.sock ) 暴露给非 root 用户或容器。

7.2 资源管理与监控

• 日志轮转 ：确保 /etc/docker/daemon.json 中的 log-opts 配置合理，防止日志占满磁盘。
• 存储管理 ：规划好 /var/lib/docker 的存储位置，最好放在独立的、容量较大的分区或逻辑卷上。定期使用 docker system prune 清理无用镜像、容器和卷。
• 资源限制 ：使用 docker run 的 -m 、 --cpus 等参数为容器设置资源限制，防止单个容器耗尽主机资源。

7.3 持续集成与镜像构建

龙芯平台的 Docker 镜像生态仍在发展中，很多软件没有现成的 LoongArch 镜像。因此， 掌握在龙芯平台上使用 Dockerfile 构建镜像的能力至关重要 。

1. 编写多阶段构建的 Dockerfile ，减少最终镜像体积。
2. 在构建时，注意软件源的替换。在 Dockerfile 中使用龙芯架构的软件源（如 loongnix 源）。
3. 可以将构建好的、业务相关的 LoongArch 镜像推送到私有仓库，供集群内其他龙芯节点使用。

7.4 考虑容器编排

单机 Docker 能满足部分场景，但对于微服务集群，需要考虑容器编排工具。目前，Kubernetes 对 LoongArch 架构的支持也在逐步完善中。可以关注社区进展，在条件成熟时，在龙芯服务器集群上部署 K8s，实现更高效的容器化应用管理。

在龙芯 3B6000 上成功运行 Docker 29.5.1，标志着国产化平台在基础软件生态上又迈出了坚实的一步。这个过程虽然比在 x86 平台上更曲折，但每一步的排查和解决，都是对系统底层原理的一次深入理解。记住，在遇到问题时， journalctl 查看服务日志和 docker info 检查配置永远是起点。