Docker镜像环境变量传递异常及用户ID修改权限问题排查

问题解答 #

1. UID变量是否未读取.env文件中的值？ #

是的。Dockerfile中的ARG是镜像构建阶段的变量，仅在构建镜像时生效，构建完成后就会固化到镜像中。而docker-compose的env_file是给容器运行阶段传递环境变量的，两者属于完全独立的生命周期。拉取现成镜像的用户，镜像早已构建完成，运行时的环境变量根本无法影响构建阶段生成的用户UID。

2. 默认值是否覆盖了环境变量的值？ #

不是默认值覆盖，而是运行时的环境变量根本没参与构建过程。构建镜像时，ARG UID=1000的默认值1000已经被用来创建laravel用户，运行时的USER_ID/GROUP_ID和这个预先创建好的用户没有任何关联。

Entrypoint脚本报错解决 #

报错原因 #

• 进程占用：如果容器启动时已切换到laravel用户，进程1属于该用户，usermod无法修改正在被进程占用的用户ID。
• 权限不足：修改系统用户/组需要root权限，若entrypoint以非root用户执行，会出现Permission denied。

解决方案 #

修改Dockerfile和entrypoint脚本，让容器先以root身份完成用户UID/GID的修改，再切换到laravel用户运行后续命令：

1. 更新Dockerfile

# 替换为你的基础镜像，示例用PHP官方镜像
FROM php:8.2-fpm

ENV USER=laravel

# 安装su-exec（用于安全切换用户，Debian/Ubuntu环境）
RUN apt-get update && apt-get install -y --no-install-recommends su-exec \
    && rm -rf /var/lib/apt/lists/*

# 创建用户目录（先不指定UID/GID）
RUN mkdir -p /home/$USER/.composer

# 复制entrypoint脚本并赋予执行权限
COPY start.sh /start.sh
RUN chmod +x /start.sh

# 不设置USER指令，默认以root启动容器
ENTRYPOINT ["/start.sh"]

2. 编写start.sh脚本

#!/bin/bash
set -e

# 读取运行时环境变量，默认值设为1000
USER_ID=${USER_ID:-1000}
GROUP_ID=${GROUP_ID:-1000}

# 清理可能存在的同名用户/组
userdel -f $USER || true
groupdel -f $USER || true

# 动态创建匹配UID/GID的组和用户
groupadd -g $GROUP_ID $USER
useradd -u $USER_ID -g $GROUP_ID -G www-data,root -d /home/$USER $USER

# 修复目录权限
chown -R $USER:$USER /home/$USER

# 切换到laravel用户执行后续命令（exec让目标进程成为容器进程1，保证信号正常传递）
exec su-exec $USER "$@"

3. docker-compose配置

拉取镜像的用户只需在docker-compose中配置env_file即可：

services:
  php:
    image: your-image-name
    env_file: .env
    # 其他配置（如挂载卷、端口映射等）...

对应的.env文件：

USER_ID=1001
GROUP_ID=1001

这样启动容器时，会动态创建匹配用户本地UID/GID的laravel用户，完美解决权限映射问题。

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