启用userns-remap前必须配置/etc/subuid和/etc/subgid：文件需存在、可读、格式正确（username:subuid_start:count），且用户名须为宿主机真实用户，同一用户在两文件中起始UID与数量必须一致；禁用"default"，应显式指定如"userns-remap": "dockremap"，重启docker守护进程后验证/proc/self/uid_map确认映射生效。
启用 userns-remap 前必须检查 /etc/subuid 和 /etc/subgid
不配置这两个文件，userns-remap 启动后容器会直接失败，报错类似 docker: Error response from daemon: user namespace not supported on this system 或更隐晦的 invalid argument。Docker 守护进程启动时会读取它们来分配子 UID/GID 范围，不是“有就行”，而是格式、权限、归属都得对。
必须确保：
-
/etc/subuid和/etc/subgid存在且可读（权限建议644） - 每行格式为
username:subuid_start:count，例如dockremap:100000:65536 - 用户名必须是宿主机上真实存在的用户（不能是容器内用户）
- 同一用户在两个文件中的
subuid_start和count必须完全一致
常见错误是复制粘贴时多空格、用中文冒号、或写成 root 用户——root 不能用于 userns-remap，Docker 会拒绝加载。
daemon.json 中的 userns-remap 配置不能只写 default
"userns-remap": "default" 看似省事，但实际会触发 Docker 自动创建 dockremap 用户并写入 /etc/subuid，而这个过程不可控：它可能用错 UID 范围、与已有服务冲突、甚至因权限不足静默失败。生产环境必须显式指定用户名，例如：
{
"userns-remap": "dockremap"
}
这样 Docker 才会严格按 /etc/subuid 中定义的 dockremap 行来映射。改完配置后必须重启守护进程：sudo systemctl restart docker，且确认无报错（sudo journalctl -u docker --since "1 hour ago" | grep -i userns）。
容器内 UID 0 不再等于宿主机 root，但挂载目录仍需手动适配
启用 userns-remap 后，容器内 root（UID 0）被映射到宿主机上一个非特权范围（如 100000），这确实隔离了权限，但不自动解决挂载目录的读写问题。比如：
使用 Python 脚本下载 Docker 镜像并打包为 tar 文件。用户说“下载镜像”“拉取镜像”“pull xxx”“帮我下载 nginx 镜像”等时触发。支持 SOCKS5 代理直连（推荐）和国内镜像站加速两种模式。
- 宿主机目录
/data属主是alice:alice（UID 1000），权限drwxr-xr-x - 容器内进程以
UID 0运行 → 实际对应宿主机UID 100000 -
UID 100000对/data没有任何权限 → 仍报Permission denied
所以必须配合挂载策略：
- 挂载时加
:ro（只读）避免写入需求 - 或提前给宿主机目标目录加 ACL，允许子 UID 范围访问：
sudo setfacl -m u:100000:rwx /data - 或改目录属主为映射起始 UID：
sudo chown 100000:100000 /data（仅限测试环境）
验证映射是否生效不能只看 docker info
docker info | grep -i userns 显示 Userns-Remap: dockremap 只说明配置加载成功，不代表每个容器都真正启用了命名空间。真实验证要进容器查 /proc/self/uid_map：
$ docker run --rm -it alpine sh -c 'cat /proc/self/uid_map'
0 100000 65536
这一行表示：容器内 UID 0～65535 映射到宿主机 UID 100000～165535。如果看到 0 0 4294967295，说明该容器没走 user namespace（比如用了 --privileged 或某些 volume driver 会绕过）。
另一个关键点：userns-remap 与 --user 参数冲突。若容器启动时显式指定 --user 1000，Docker 会忽略 userns-remap 映射，直接尝试用宿主机 UID 1000 运行——而这 UID 往往不在子范围里，导致启动失败。所以二者不要混用。
最易被忽略的是：启用 userns-remap 后，所有绑定挂载（-v）的路径必须由宿主机上子 UID 范围内的用户可访问，否则容器连启动都卡在 mount 阶段；而这个限制不会在 docker run 命令中报具体路径错误，只会泛泛提示 operation not permitted。
