Docker运行时覆盖环境变量：如何动态指定UID和用户名创建用户

阿华AIGC实验室

2026-5-19

动态在Docker Run阶段指定UID和用户名的解决方案

这个问题我之前也碰到过，核心原因是useradd是在镜像构建阶段执行的，一旦镜像构建完成，里面的用户信息就固定了，没法在docker run阶段直接修改。要实现动态指定UID和用户名，咱们得换个思路——把用户创建的逻辑放到容器启动时来做，用entrypoint脚本处理动态参数。

核心思路

放弃在Dockerfile里提前创建固定用户，而是：

在Dockerfile中安装切换用户所需的工具（比如gosu，比su/sudo更适合容器场景）
编写一个entrypoint脚本，在容器启动时读取环境变量（比如USER_NAME、USER_UID）
脚本中动态创建用户、调整目录权限，最后切换到该用户执行命令
运行容器时通过-e参数传入自定义的用户名和UID

具体实现步骤

1. 编写Dockerfile

FROM ubuntu:latest

# 安装gosu（安全切换用户的工具）和基础依赖
RUN apt-get update && apt-get install -y --no-install-recommends gosu && \
    rm -rf /var/lib/apt/lists/*

# 设置默认的用户名和UID，用户run时可以通过环境变量覆盖
ENV USER_NAME=default
ENV USER_UID=1000

# 创建工作目录（根据你的实际需求调整）
WORKDIR /app

# 复制entrypoint脚本到容器内
COPY entrypoint.sh /usr/local/bin/
RUN chmod +x /usr/local/bin/entrypoint.sh

# 设置entrypoint，CMD的内容会作为参数传给entrypoint
ENTRYPOINT ["entrypoint.sh"]
# 默认执行id命令验证用户，你可以替换成自己的业务命令
CMD ["/usr/bin/id", "-u", "$USER_NAME"]

2. 编写entrypoint.sh脚本

#!/bin/bash
set -e  # 遇到错误立即退出

# 从环境变量获取用户名和UID，没传入的话用默认值
USER_NAME=${USER_NAME:-default}
USER_UID=${USER_UID:-1000}

# 检查用户是否已存在，不存在则创建
if ! id -u "$USER_NAME" >/dev/null 2>&1; then
    # 创建用户：指定UID、bash shell、创建家目录
    useradd -u "$USER_UID" -s /bin/bash -o -c "" -m "$USER_NAME"
fi

# 调整工作目录的权限，确保新用户能读写（根据你的实际目录调整）
chown -R "$USER_NAME:$USER_NAME" /app

# 切换到目标用户执行CMD中的命令，exec确保信号能正确传递
exec gosu "$USER_NAME" "$@"

3. 构建并运行容器

构建镜像：

docker build -t dynamic-user-image .

动态指定用户名和UID运行：

# 自定义用户名myuser，UID1234
docker run -e USER_NAME=myuser -e USER_UID=1234 dynamic-user-image

或者替换默认的CMD命令：

docker run -e USER_NAME=myuser -e USER_UID=1234 dynamic-user-image /bin/bash

适配轻量镜像（比如Alpine）

如果用Alpine镜像，推荐用su-exec代替gosu（体积更小），Dockerfile调整如下：

FROM alpine:latest

# 安装su-exec
RUN apk add --no-cache su-exec

# 其余部分和上面的Ubuntu版一致，仅entrypoint脚本中把gosu换成su-exec
ENV USER_NAME=default
ENV USER_UID=1000
WORKDIR /app
COPY entrypoint.sh /usr/local/bin/
RUN chmod +x /usr/local/bin/entrypoint.sh
ENTRYPOINT ["entrypoint.sh"]
CMD ["/usr/bin/id", "-u", "$USER_NAME"]

entrypoint.sh中把最后一行改成：