龙芯3B6000平台GitLab Runner Docker执行器配置与避坑指南

🚀 30+款热门AI模型一站整合，DeepSeek/GLM/Qwen 随心用，限时 5 折。 👉 点击领海量免费额度

1. 先搞清楚“一键解决”到底解决了什么

在龙芯3B6000这类国产平台上部署GitLab CI/CD，最头疼的不是GitLab Runner本身，而是Docker执行器。很多人卡在第一步：Runner能注册，但流水线任务一跑就报错，不是镜像拉取失败，就是容器启动不了，或者权限各种不对。标题里说的“一键解决”，核心价值就在这里——它不是一个万能脚本，而是一个经过验证的、针对龙芯3B6000平台（LoongArch架构）的GitLab Runner Docker执行器完整配置方案。

这个方案解决的不是“如何安装Docker”或“如何注册Runner”这种通用问题，而是解决了在特定架构下，让GitLab Runner的Docker执行器能稳定、正确地拉起容器来运行CI/CD任务。如果你正在龙芯3B6000上搭建CI/CD环境，并且打算用Docker来隔离构建环境，那这篇文章就是为你准备的。最关键的几个点包括：适配LoongArch架构的Docker镜像源配置、正确的Runner配置文件参数、以及一系列容易忽略但会导致任务失败的权限和路径问题。

我建议你先别急着跑命令，花两分钟看完整个思路。因为很多问题出在配置顺序和细节上，照着做能省下大量排查时间。

2. 环境准备：不只是安装Docker和Runner

在龙芯3B6000上，准备工作比x86平台要更细致。很多人以为yum install docker和curl runner就完事了，结果后面全是坑。

2.1 系统与内核确认

首先，确认你的系统。以常见的Loongnix或统信UOS（龙芯版）为例，先看基础信息：

uname -a # 输出应包含 loongarch64 cat /etc/os-release # 确认系统版本

这一步是基础，确保你后续所有操作都在正确的架构环境下。

2.2 Docker安装与关键配置

安装Docker本身不难，但配置不对，后面全白费。

1. 安装Docker：使用系统包管理器安装。例如在Loongnix上：

   sudo yum install -y docker # 或者使用 dnf sudo dnf install -y docker

2. 启动并设置开机自启：

   sudo systemctl start docker sudo systemctl enable docker

3. 最关键的一步：配置Docker镜像加速与架构适配。这是龙芯平台最大的不同点。默认的Docker Hub可能没有你需要的LoongArch架构镜像，或者拉取极慢。你需要修改Docker守护进程配置（/etc/docker/daemon.json），加入针对LoongArch的镜像仓库。

   { "registry-mirrors": [ "https://your-mirror-for-loongarch.com" ], "exec-opts": ["native.cgroupdriver=systemd"], "log-driver": "json-file", "log-opts": { "max-size": "100m" }, "storage-driver": "overlay2" }

   注意：这里的registry-mirrors地址需要替换为实际可用的、支持LoongArch架构的镜像仓库。国内一些云服务商或社区可能提供了LoongArch的镜像加速服务，这是后续能拉取到镜像的前提。如果找不到公共镜像，你可能需要自己构建基础镜像并推送到私有仓库。

4. 重启Docker使配置生效：

   sudo systemctl daemon-reload sudo systemctl restart docker

5. 验证Docker安装及架构：

   sudo docker info | grep Architecture # 应该输出： Architecture: loongarch64

2.3 GitLab Runner安装

从GitLab官方下载适用于Linux LoongArch64的二进制包。不要用其他架构的包。

# 示例下载命令，版本号请替换为最新 sudo curl -L --output /usr/local/bin/gitlab-runner "https://gitlab-runner-downloads.s3.amazonaws.com/latest/binaries/gitlab-runner-linux-loongarch64" # 赋予执行权限 sudo chmod +x /usr/local/bin/gitlab-runner # 创建Runner用户（推荐，便于权限管理） sudo useradd --comment 'GitLab Runner' --create-home gitlab-runner --shell /bin/bash # 安装并设置为系统服务 sudo gitlab-runner install --user=gitlab-runner --working-directory=/home/gitlab-runner sudo gitlab-runner start

3. 配置Docker执行器：参数里的“魔鬼细节”

安装完只是有了Runner，要让它的Docker执行器工作，配置才是核心。很多人在这里配置不对，导致流水线任务状态一直是pending或failed。

3.1 注册Runner到GitLab

首先，你需要从GitLab项目或群组设置里获取注册令牌（Registration Token）和URL。 然后执行注册命令：

sudo gitlab-runner register

交互过程中，关键选择如下：

• 执行器类型：输入docker。
• 默认镜像：这是一个重要的坑点。对于龙芯平台，你不能填alpine:latest或ubuntu:latest，因为这些镜像默认没有LoongArch版本。你必须填写一个确定存在于你的镜像仓库中、且支持loongarch64架构的镜像，例如你自己构建的loongarch64/centos:7或从可信源获取的镜像。这里填错了，所有任务都会因“镜像拉取失败”而报错。
• 其他设置：如标签（tags）、是否锁定项目等，根据你的需求填写。

3.2 手动编辑配置文件，注入关键参数

注册生成的配置文件（通常在/etc/gitlab-runner/config.toml）往往需要手动调整才能完美工作。找到你刚注册的Runner配置段，重点修改以下部分：

[[runners]] name = "龙芯3B6000 Docker Runner" url = "https://your-gitlab.com" token = "your_runner_token" executor = "docker" [runners.docker] # 1. 使用特权模式（很多构建工具需要） privileged = true # 2. 关闭TLS验证（如果使用内部私有仓库且没有配置证书） tls_verify = false # 3. 指定镜像拉取策略。‘if-not-present’可以避免每次都拉取，加快速度 pull_policy = "if-not-present" # 4. 禁用缓存，避免因为架构不同导致缓存层问题（可选，根据情况调整） disable_cache = false # 5. 绑定宿主机目录到容器，用于缓存（如Maven、npm缓存） volumes = [ "/cache", "/home/gitlab-runner/.m2:/root/.m2:rw", "/var/run/docker.sock:/var/run/docker.sock" # 允许在容器内使用Docker（Docker in Docker） ] # 6. 指定网络模式，通常host模式最省事，但需注意安全 network_mode = "host" # 7. 至关重要的配置：指定辅助镜像。当默认镜像拉取失败时，会尝试拉取此镜像。 # 对于龙芯，这里可以指向一个极小的、肯定能拉到的LoongArch架构镜像。 helper_image = "registry.gitlab.com/gitlab-org/gitlab-runner/gitlab-runner-helper:loongarch64-latest" # 注意：helper_image也需要有loongarch64版本，否则会失败。如果官方没有，你可能需要自己构建。 [runners.cache] # 缓存配置 Type = "s3" Path = "runner" Shared = true [runners.cache.s3] ServerAddress = "s3.amazonaws.com" BucketName = "my-bucket" BucketLocation = "us-east-1"

配置项解读与避坑：

• privileged = true：很多CI/CD任务需要创建设备节点或执行高级系统调用，不开特权模式可能会遇到权限错误。这是解决“容器内操作失败”的常见手段。
• tls_verify = false：如果你用的是内网私有镜像仓库且没有配置HTTPS证书，必须关闭验证，否则拉取镜像会失败。
• volumes中的/var/run/docker.sock：这是实现“Docker in Docker”（DinD）的关键，允许你在CI作业中运行docker build等命令。但绑定此socket有安全风险，仅在你确实需要时才添加。
• helper_image：这是龙芯平台最特殊的配置。GitLab Runner在执行任务前，会先拉取一个辅助镜像来准备环境。如果这个镜像没有对应架构，任务会直接卡在Preparing environment阶段。你必须确保指定的helper_image存在LoongArch版本。
• network_mode = “host”：使用宿主机网络可以避免容器内网络配置的麻烦，特别是需要访问宿主机上其他服务时。但同样需要考虑安全隔离性。

修改完配置后，重启Runner服务：

sudo gitlab-runner restart

4. 验证与调试：从单任务到流水线

配置写好了，不代表就能用了。必须通过实际运行来验证。

4.1 运行一个最简单的测试任务

在你的GitLab项目中，创建一个最简单的.gitlab-ci.yml文件：

test-docker-executor: stage: test tags: - loongarch64 # 这里填写你注册Runner时指定的tag，确保任务被这个Runner接收 script: - uname -a - cat /etc/os-release - echo “Hello from LoongArch64 Docker Container!” image: loongarch64/centos:7 # 使用一个确定存在的LoongArch基础镜像

提交这个更改，触发流水线。然后回到龙芯服务器上查看日志：

# 查看Runner的实时日志，这是最重要的调试信息 sudo gitlab-runner run --debug # 或者查看系统服务日志 sudo journalctl -u gitlab-runner -f

观察日志重点：

1. 任务是否被正确接收：日志中应该显示 job=xxx 被接收。
2. 准备环境阶段：看是否在拉取helper_image和你指定的image。拉取成功与否是第一个关键点。
3. 容器创建阶段：看是否成功创建了容器。
4. 脚本执行阶段：看你的uname -a输出是否是loongarch64，以及脚本命令是否成功执行。

4.2 常见问题与排查链路

如果任务失败了，别慌，按这个顺序查：

1. 现象：Job一直处于pending状态。

   • 排查：Runner没有在运行。执行sudo gitlab-runner status确认。也可能是标签不匹配，检查Job的tags和Runner的tags是否一致。
   • 排查：Runner配置可能错误，用sudo gitlab-runner verify检查连接。

2. 现象：Job失败，日志显示Preparing environment卡住或报错。

   • 排查：helper_image拉取失败。这是龙芯平台最高频的问题。确认你配置的helper_image地址和标签是否正确，且该镜像存在loongarch64版本。可以手动尝试拉取：sudo docker pull registry.gitlab.com/gitlab-org/gitlab-runner/gitlab-runner-helper:loongarch64-latest。
   • 排查：网络问题。检查Docker守护进程的镜像加速器配置，确保能访问外网或内部镜像仓库。

3. 现象：Job失败，日志显示pull access denied或image not found。

   • 排查：.gitlab-ci.yml中指定的image不存在或无权访问。手动docker pull一下你写的镜像名确认。
   • 排查：对于私有镜像仓库，需要在[runners.docker]下配置pull_policy和auth认证信息。

4. 现象：Job失败，日志显示容器内命令执行失败（如权限错误）。

   • 排查：尝试在Runner配置中设置privileged = true。
   • 排查：检查挂载的卷（volumes）路径在宿主机是否存在，权限是否足够（gitlab-runner用户可读可写）。

5. 现象：Job能跑，但速度极慢。

   • 排查：镜像拉取慢。优化Docker镜像加速器配置，或提前将基础镜像手动拉到本地。
   • 排查：网络模式问题。如果作业需要频繁访问外部资源，host模式可能更快；如果访问宿主机服务，确保网络可达。

4.3 进阶：处理复杂的构建场景

单任务跑通后，就可以尝试更真实的场景了。

• Docker in Docker (DinD)：如果你需要在CI作业中构建Docker镜像，除了绑定/var/run/docker.sock，还需要在作业中指定services和variables，并注意权限。

  build-image: stage: build tags: - loongarch64 image: docker:loongarch64-latest # 需要存在此架构的docker客户端镜像 services: - docker:loongarch64-dind # 需要存在此架构的dind镜像 variables: DOCKER_HOST: tcp://docker:2375 DOCKER_TLS_CERTDIR: “” script: - docker build -t my-app .

• 缓存优化：利用volumes挂载缓存目录（如/cache、/root/.m2），可以显著加速后续流水线。在config.toml中配置[runners.cache]可以将缓存存储到分布式存储（如S3），实现Runner节点间的缓存共享。

5. 生产环境考量与维护建议

把Runner调通只是第一步，要用于生产，还得考虑稳定性和维护性。

1. 镜像来源管理：龙芯架构的公共镜像有限。建议搭建私有镜像仓库（如Harbor），并将所有CI需要的基础镜像（包括helper_image）自己构建并推送到私有仓库。这能保证镜像拉取速度和稳定性。
2. Runner配置版本化：将/etc/gitlab-runner/config.toml文件纳入版本控制（如Ansible、Puppet），确保配置变更可追溯、可回滚。
3. 资源监控：龙芯3B6000的性能需要合理规划。监控Runner节点的CPU、内存、磁盘IO和网络，避免多个并发任务拖垮主机。可以在config.toml中通过concurrent参数限制全局并发数，或在每个[[runners]]段通过limit限制单个Runner的并发。
4. 日志收集：将journalctl -u gitlab-runner的日志接入ELK或Graylog等日志系统，便于集中排查问题。
5. 安全加固：
   • 尽量避免使用privileged = true和network_mode = “host”。如果必须用，确保Runner节点本身处于安全的内网环境。
   • 定期更新GitLab Runner和Docker版本，修复安全漏洞。
   • 对私有镜像仓库的访问凭证做好安全管理。

最后，关于“一键解决”：它指的是一套经过验证的、正确的配置组合和问题解决方案，而不是一个真正的万能脚本。在龙芯这样的特定架构下，没有放之四海而皆准的配置。你需要理解每个参数的作用，并根据自己的网络、镜像仓库和安全策略进行调整。核心思路就是：确保每一个Docker镜像（包括默认镜像、辅助镜像、服务镜像）都有对应的LoongArch64版本，并正确配置Runner去找到它们。把这一个原则把握住，大部分问题都能迎刃而解。

🚀 30+款热门AI模型一站整合，DeepSeek/GLM/Qwen 随心用，限时 5 折。 👉 点击领海量免费额度