GitLab Runner Shell执行器无法执行Docker命令的解决咨询

问题场景 #

使用GitLab Runner Shell执行器，配置的.gitlab-ci.yml测试部署任务如下：

# Test Deploy
test-job1:
  stage: test
  tags:
    - shell-testing
  only:
    - testing
  variables:
    GIT_STRATEGY: none
  script:
    - whoami
    - pwd
    - echo "docker pull $CI_REGISTRY_TEST/$CI_PROJECT_PATH_SLUG:$CI_COMMIT_SHA"
    - docker pull $CI_REGISTRY_TEST/$CI_PROJECT_PATH_SLUG:$CI_COMMIT_SHA
    - docker run -d -p 8000:8000 $CI_REGISTRY_TEST/$CI_PROJECT_PATH_SLUG:$CI_COMMIT_SHA

执行错误信息 #

任务执行时出现超时错误：

Running with gitlab-runner 16.1.0 (865283c5)
  on app-testing-shell [some ID], system ID: [some other ID]
Preparing the "shell" executor
00:00
Using Shell (bash) executor...
Preparing environment
00:01
Running on app-testing...
Getting source from Git repository
00:00
Skipping Git repository setup
Skipping Git checkout
Skipping Git submodules setup
Executing "step_script" stage of the job script
$ whoami
gitlab-runner
$ pwd
/home/gitlab-runner/builds/[some ID]/0/root/py-helloworld-flask-docker-example
$ echo "docker pull $CI_REGISTRY_TEST/$CI_PROJECT_PATH_SLUG:$CI_COMMIT_SHA"
docker pull [REGISTRY IP]:443/root-py-helloworld-flask-docker-example:12f06021fcbcddea450b91e6972ad95341d34fb8
$ docker pull $CI_REGISTRY_TEST/$CI_PROJECT_PATH_SLUG:$CI_COMMIT_SHA
Post "http://dockerservice:2375/v1.24/images/create?fromImage=[REGISTRY IP]%3A443%2Froot-py-helloworld-flask-docker-example&tag=12f06021fcbcddea450b91e6972ad95341d34fb8": dial tcp [?SOME OTHER PUBLIC IP?]:2375: i/o timeout
ERROR: Job failed: exit status 1

手动执行验证 #

手动切换到gitlab-runner用户执行相同命令可正常完成：

$ sudo su - gitlab-runner
$ whoami
gitlab-runner
$ cd /home/gitlab-runner/builds/[some ID]/0/root/py-helloworld-flask-docker-example
$ docker pull [REGISTRY IP]:443/root-py-helloworld-flask-docker-example:12f06021fcbcddea450b91e6972ad95341d34fb8
12f06021fcbcddea450b91e6972ad95341d34fb8: Pulling from root-py-helloworld-flask-docker-example
d52e4f012db1: Already exists
7dd206bea61f: Already exists
2320f9be4a9c: Already exists
6e5565e0ba8d: Already exists
d3797e13cc41: Already exists
70f90dfe001b: Already exists
bd75605de417: Already exists
3d0e1a4b14bc: Already exists
73ee9fc7cab0: Pull complete
76f48c27aa39: Pull complete
Digest: sha256:4ba2eba4fc8afff2dfe4e7ad80f49aee001afb9385eb522a4898bbaacbed6617
Status: Downloaded newer image for [REGISTRY IP]:443/root-py-helloworld-flask-docker-example:12f06021fcbcddea450b91e6972ad95341d34fb8
[REGISTRY IP]:443/root-py-helloworld-flask-docker-example:12f06021fcbcddea450b91e6972ad95341d34fb8

问题核心 #

GitLab Runner执行Job时的环境变量与手动切换用户后的环境不一致，导致Docker客户端被错误配置为连接远程http://dockerservice:2375地址，而非本地默认的Unix Socket，最终引发连接超时。

解决办法 #

1. 显式指定Docker守护进程Socket路径 #

在.gitlab-ci.yml的variables中添加DOCKER_HOST配置，强制Docker客户端使用本地Socket：

# Test Deploy
test-job1:
  stage: test
  tags:
    - shell-testing
  only:
    - testing
  variables:
    GIT_STRATEGY: none
    DOCKER_HOST: unix:///var/run/docker.sock
  script:
    - whoami
    - pwd
    - echo "docker pull $CI_REGISTRY_TEST/$CI_PROJECT_PATH_SLUG:$CI_COMMIT_SHA"
    - docker pull $CI_REGISTRY_TEST/$CI_PROJECT_PATH_SLUG:$CI_COMMIT_SHA
    - docker run -d -p 8000:8000 $CI_REGISTRY_TEST/$CI_PROJECT_PATH_SLUG:$CI_COMMIT_SHA

或者在script中临时设置环境变量：

export DOCKER_HOST=unix:///var/run/docker.sock
docker pull $CI_REGISTRY_TEST/$CI_PROJECT_PATH_SLUG:$CI_COMMIT_SHA

2. 排查并清理错误的环境变量 #

在Job的script开头添加环境变量打印命令，对比手动执行时的环境：

env | grep -i docker

找到DOCKER_HOST被错误设置的来源（比如GitLab Runner全局配置、项目级变量、服务器系统环境变量），移除对应的错误配置。

3. 确认gitlab-runner用户的Docker权限（可选） #

虽然手动执行正常，但可再次确认用户已加入docker组：

sudo usermod -aG docker gitlab-runner

执行后重启GitLab Runner服务：

sudo systemctl restart gitlab-runner

内容的提问来源于stack exchange，提问作者Temp Worker Here