自定义SageMaker镜像启动报错ResourceNotFoundError：UID/GID匹配异常排查

问题背景 #

自定义SageMaker镜像集成Python格式化工具black，附加到SageMaker域后启动内核时触发ResourceNotFoundError，提示需确保AppImageConfig中的UID/GID与镜像默认值匹配，但本地容器执行id -u/id -g结果为0/0，与配置一致，官方排障指南无效。

核心问题分析 #

虽然本地容器UID/GID匹配，但存在以下潜在不兼容点：

• 基础镜像未配置SageMaker Studio必需的用户环境与内核注册规则
• AppImageConfig中的内核显示名称与镜像内实际注册的内核名称不匹配
• 挂载路径与SageMaker Studio默认运行环境存在权限冲突

解决方案 #

1. 修改Dockerfile，适配SageMaker Studio环境 #

更新Dockerfile，添加用户创建、内核注册、环境切换逻辑：

FROM continuumio/miniconda3:4.9.2

# 创建SageMaker Studio默认运行用户（UID/GID 1000）
RUN useradd -m -s /bin/bash -u 1000 sagemaker-user

COPY environment.yml .
# 更新conda环境并注册内核到系统路径
RUN conda env update -f environment.yml --prune && \
    python -m ipykernel install --name python3 --display-name "Python [conda env: base]"

# 切换到sagemaker-user，匹配Studio运行上下文
USER sagemaker-user
WORKDIR /home/sagemaker-user

2. 修正AppImageConfig配置 #

调整FileSystemConfig与KernelSpecs，匹配镜像内用户环境与内核信息：

{
    "AppImageConfigName": "conda-env-kernel-config",
    "KernelGatewayImageConfig": {
        "KernelSpecs": [
            {
                "Name": "python3",
                "DisplayName": "Python [conda env: base]"
            }
        ],
        "FileSystemConfig": {
            "MountPath": "/home/sagemaker-user",
            "DefaultUid": 1000,
            "DefaultGid": 1000
        }
    }
}

3. 验证镜像内核配置 #

构建镜像后，本地启动容器执行以下命令，确认内核已正确注册：

ls /usr/local/share/jupyter/kernels/python3

应返回包含kernel.json的目录，文件中argv字段需指向conda环境内的Python路径。

4. 重新部署验证 #

• 重新构建镜像并推送到AWS ECR
• 更新SageMaker域的AppImageConfig关联配置
• 重启SageMaker Studio，重新启动内核测试

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