使用超大UID添加用户时Docker Build挂起，求解决方案或规避方法

当尝试使用超大UID（例如1000123456）构建Docker镜像时，docker build会在执行RUN useradd命令的步骤持续挂起，同时还会占用大量磁盘空间（单次构建甚至能占用数百GB）。

复现步骤 #

$ touch Dockerfile
$ echo FROM ubuntu:latest >> Dockerfile
$ echo RUN useradd -m -s /bin/bash -N -u 1000123456 jovyan >> Dockerfile
$ docker build --tag mirekphd/test-uid .
Sending build context to Docker daemon  2.048kB
Step 1/2 : FROM ubuntu:latest
 ---> d2e4e1f51132
Step 2/2 : RUN useradd -m -s /bin/bash -N -u 1000123456 jovyan
 ---> Running in 04707e01aefc

补充背景 #

该问题常出现在为调试硬编码Openshift/OKD命名空间允许范围内的UID场景中，挂起后清理容器可回收大量空间：

$ docker system prune -f
Deleted Containers:
04707e01aefcda9ce9840389f1d59821e1ddb7dac535d416f99447e657ec5309
c3fc96209790ee7aa0c2c10bec2459e8ec3dbcc1dc7cfdd0a3e12960a28b9437
1ed4985b3e27eaff6394fd0243713573473ab59c9a82db865e40ebb40a391892

Total reclaimed space: 648.1GB

解决方案与规避方法 #

1. 运行时指定UID，跳过构建阶段创建 #

Docker镜像构建阶段不需要提前创建大UID用户，直接在容器启动时通过--user参数指定即可：

docker run --user 1000123456 mirekphd/test-uid

针对Openshift/OKD场景，平台会自动分配符合范围的UID，完全无需在镜像中硬编码用户，直接使用基础镜像的默认用户即可。

2. 手动创建家目录，避免useradd -m的异常写入 #

如果必须在构建阶段创建用户，不要用-m参数让useradd自动创建家目录，改为手动创建目录并修改权限，跳过系统处理大UID元数据的逻辑：

FROM ubuntu:latest
RUN groupadd -g 1000123456 jovyan && \
    useradd -s /bin/bash -N -u 1000123456 jovyan && \
    mkdir -p /home/jovyan && \
    chown -R 1000123456:1000123456 /home/jovyan

3. 尝试用adduser替代useradd #

部分Linux发行版中adduser是useradd的友好封装，对大UID的处理更稳定，可尝试替换使用：

FROM ubuntu:latest
RUN adduser --disabled-password --gecos "" --uid 1000123456 jovyan

注意：不同发行版的adduser参数可能有差异，需根据基础镜像调整。

4. 修改系统UID范围限制（不推荐） #

部分系统默认通过/etc/login.defs中的UID_MAX限制用户UID范围，修改该值可允许创建大UID用户，但此操作会影响整个系统，且不一定能解决Docker构建挂起问题，仅作为最后尝试选项：

FROM ubuntu:latest
RUN sed -i 's/UID_MAX\t\t60000/UID_MAX\t\t2000000000/' /etc/login.defs && \
    useradd -m -s /bin/bash -N -u 1000123456 jovyan

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