GitLab CI执行docker exec报错：无法进入已停止容器

在GitLab CI Runner中执行docker exec -u user app-php php -v时触发错误：

OCI runtime exec failed: exec failed: cannot exec a container that has stopped: unknown
Cleaning up project directory and file based variables 00:01
ERROR: Job failed: exit code 126

本地Ubuntu、Fedora或macOS环境执行相同操作完全正常。以下是相关信息：

报错前任务输出 #

Running with gitlab-runner 17.3.1 (66269445)
  on run01-docker ahzDDsscB, system ID: s_1241bf653f96
Preparing the "docker" executor 00:01
Using Docker executor with image docker:latest ...
Using locally found image version due to "if-not-present" pull policy
Using docker image sha256:*** for docker:latest with digest docker@sha256:*** ...
Preparing environment 00:01
Running on runner-ahzddsscb-project-69-concurrent-0 via run01...
Getting source from Git repository 00:01
Fetching changes with git depth set to 20...
Reinitialized existing Git repository in ***
Checking out 67e5047a as detached HEAD (ref is develop)...
Skipping Git submodules setup
Executing "step_script" stage of the job script 00:02
Using docker image sha256:*** for docker:latest with digest docker@sha256:*** ...
$ cd app
$ docker-compose pull --quiet --ignore-pull-failures
$ docker-compose up -d --remove-orphans --no-recreate
 Container app-php  Created
 Container app-php  Starting
 Container app-php  Started
$ docker ps
CONTAINER ID   IMAGE                                                 COMMAND                  CREATED          STATUS                  PORTS                                     NAMES
ddbd9feef6d9   0af54085b408                                          "dockerd-entrypoint.…"   2 seconds ago    Up Less than a second   2375-2376/tcp                             runner-ahzddsscb-project-69-concurrent-0-04cc20a5becb9be5-build
56b35d69a5db   docker.***.**/docker/docker-registry/php:8.1   "docker-entrypoint.s…"   13 minutes ago   Up Less than a second   443/tcp, 9001/tcp, 0.0.0.0:8990->80/tcp   app-php

版本信息 #

• Gitlab v17.3.3-ee
• Docker v27.3.1
• Docker Compose v2.29.7

Gitlab CI配置 #

image:
    name: docker:latest
stages:
    - build
build app:
    script:
        - cd app
        - docker-compose pull --quiet --ignore-pull-failures
        - docker-compose up -d --remove-orphans --no-recreate
        - docker ps
        - docker exec -u user app-php php -v
    stage: build
    tags:
        - docker

Docker Compose配置 #

version: "3.7"
services:
    php:
        image: 'docker.domain.fr/docker/docker-registry/php:8.1'
        container_name: 'app-php'
        environment:
            DOCKER_USER_UID: 1000
            DOCKER_USER_GID: 1000
        ports:
            - '8990:80'
        working_dir: '/application'
        volumes:
            - '.:/application:delegated'
            - './nginx.conf:/etc/nginx/conf.d/default.conf'

Runner配置 #

...
[[runners]]
    name = "run01-docker"
    executor = "docker"
    ...
    [runners.docker]
        ...
        image = "docker:latest"
        privileged = true
        ...
        volumes = ["/var/run/docker.sock:/var/run/docker.sock",...]

1. 排查容器退出原因 #

虽然docker ps显示容器处于Up Less than a second状态，但执行docker exec时容器可能已经停止。在docker ps之后、docker exec之前添加以下命令排查：

$ docker logs app-php
$ docker inspect app-php --format '{{.State.Status}}'

重点关注：

• 挂载的nginx.conf是否在CI环境中缺失或权限异常
• /application目录权限是否与容器内UID/GID（1000）匹配
• 容器entrypoint脚本是否执行失败

2. 修正目录挂载差异 #

本地环境的./对应项目根目录，但CI环境中是Runner临时目录，挂载逻辑可能不兼容：

• 先验证CI环境中app目录下的文件是否存在：

  $ cd app && ls -la
  

• 尝试去掉delegated挂载选项，或改为ro只读挂载测试
• 先以root身份进入容器，排除用户权限问题：

  $ docker exec -u root app-php php -v
  

3. 避免复用停止状态的旧容器 #

--no-recreate参数会复用已存在的同名容器（即使容器已停止），改为强制重建：

$ docker-compose up -d --remove-orphans --force-recreate

4. 验证Runner环境Docker权限 #

在脚本中添加docker ps -a查看所有容器状态，确认app-php是否真的在运行，或是否存在重复创建的容器。

5. 增加容器启动延迟 #

容器显示Started但可能未完全初始化，添加延迟后再执行docker exec：

$ sleep 5 && docker exec -u user app-php php -v

内容的提问来源于stack exchange，提问作者David