龙芯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 折。 👉 点击领海量免费额度