GitLab Runner中Docker Compose容器崩溃：无写入权限问题排查

问题描述 #

在GitLab环境使用Docker Runner构建用于测试的Keycloak容器镜像，通过Docker Compose挂载./data:/opt/keycloak/data/目录预配置数据，但容器启动后崩溃。该配置在本地机器运行正常，仅GitLab环境出现问题。

流水线配置 #

build-keycloak-test-image:
  stage: build-keycloak-test-image
  before_script:
    - echo $CI_REGISTRY_PASSWORD | docker login -u $CI_REGISTRY_USER --password-stdin $CI_REGISTRY
    - apk add --no-cache curl
    - chmod +x ./keycloak/test/build.sh
  script:
    - cd ./keycloak/test/
    - sh ./build.sh
    - docker push $KEYCLOAK_TEST_IMAGE
  only:
    - tags

构建脚本 #

#!/bin/bash
KEYCLOAK_URL="${KEYCLOAK_TEST_GEN_URL:-http://localhost:8889}"
HEALTH_ENDPOINT="/health"

rm -fr ./data/*
mkdir ./data
chmod -R 777 ./data/
docker compose up -d
# ...

容器启动日志 #

2024-09-13 15:07:03,053 INFO  [org.keycloak.common.Profile] (main) Preview features enabled: token-exchange
2024-09-13 15:07:12,589 INFO  [io.quarkus.deployment.QuarkusAugmentor] (main) Quarkus augmentation completed in 10289ms
...（省略重复日志）
2024-09-13 15:07:23,912 ERROR [org.keycloak.quarkus.runtime.cli.ExecutionExceptionHandler] (main) For more details run the same command passing the '--verbose' option. Also you can use '--help' to see the details about the usage of the particular command.

Docker Compose配置 #

services:
  keycloak:
    image: quay.io/keycloak/keycloak:23.0.6
    ports:
      - "8889:8080"
    command:
      - start-dev
    volumes:
      - ./data:/opt/keycloak/data/
    environment:
      KEYCLOAK_ADMIN: "admin"
      KEYCLOAK_ADMIN_PASSWORD: "mypass"
      KC_HEALTH_ENABLED: true
      KC_METRICS_ENABLED: true
      KC_HOSTNAME_STRICT: false
      KC_HTTP_ENABLED: false
      KC_FEATURES: "token-exchange"
      PROXY_ADDRESS_FORWARDING: true
    networks:
      - gitlab
      - default
networks:
  gitlab:
    name: gitlab-network

观察结果 #

脚本会创建data目录并设置777权限，Git Runner环境中该目录属主为root：

# ls /builds/dev/project/keycloak/test/ -lah
total 24K
drwxrwxrwx    3 root     root        4.0K Sep 13 15:06 .
drwxrwxrwx    7 root     root        4.0K Sep  4 12:56 ..
...
drwxrwxrwx    2 root     root        4.0K Sep 13 15:06 data

问题原因及解决方案 #

1. HTTP配置冲突 #

Docker Compose中设置了KC_HTTP_ENABLED: false，但start-dev模式默认依赖HTTP端口（8080）提供服务，且未配置HTTPS证书，导致Keycloak无法启动监听端口，直接崩溃。

解决：
修改环境变量，启用HTTP：

KC_HTTP_ENABLED: true

2. 挂载目录权限映射问题 #

GitLab Runner中创建的data目录属主为root，而Keycloak容器默认使用非root用户（uid=1000）运行。即使设置了777权限，部分环境的安全策略（如SELinux、容器用户权限限制）会阻止非root用户写入root属主的目录。

解决：
在构建脚本中添加属主修改命令，将data目录的属主改为容器内Keycloak用户的uid：

rm -fr ./data/*
mkdir ./data
chmod -R 777 ./data/
chown -R 1000:1000 ./data/  # 新增这一行
docker compose up -d

3. 启用详细日志排查 #

当前日志未提供具体错误细节，建议在Docker Compose的command中添加--verbose参数，获取更详细的启动错误信息：

command:
  - start-dev
  - --verbose

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