xiaomusic Docker 容器部署：用户权限（UID/GID）配置的 3 种方式一次讲清
【免费下载链接】xiaomusic使用小爱音箱播放音乐，音乐使用 yt-dlp 下载。项目地址: https://gitcode.com/GitHub_Trending/xia/xiaomusic
如果你在 UNRAID 或 NAS 上用 Docker 跑过 xiaomusic，大概率撞过这个坑：容器把歌下完了，回到宿主机一看，音乐目录里每个文件的属主都是 root，普通用户连拷贝都不行。原因只有一个——容器里的用户权限没配。
读完这篇，你能自己把 xiaomusic 容器的 UID/GID 调成和宿主机用户一致，之后新生成的文件直接归你所有，不用再手动 chown 兜底。
为什么下载的音乐会变成 root 所有
- 容器默认以 root 身份运行，容器内所有文件操作都相当于"root 签的字"。
- 歌曲落到映射进容器的 /app/music 目录，属主记录为容器内用户（即 UID 0 的 root），宿主机上自然对应 root。
- 宿主机普通用户没有读写 UID 0 文件的权限，复制、播放都会被拒。
顺带说一句安全：整个服务长期跑在 root 下也是坏习惯，一旦容器被攻破，攻击者拿到的是完整权限。这次修权限，顺手把它一起改掉。
如何把容器 UID/GID 配成宿主机用户
先记住一个核心参数：Docker 的-u <UID>:<GID>决定容器内进程以哪个用户、哪个组运行（UID 是用户编号，GID 是组编号）。后面的 Composeuser字段作用完全一样，理解一次即可。
临时启动：docker run 加一个参数就行
平时习惯用命令启动的话，在原有命令里加一行-u：
docker run -d \ -v /xiaomusic_music:/app/music \ -v /xiaomusic_conf:/app/conf \ -u 1000:1000 \ hanxi/xiaomusic把1000:1000换成宿主机账号的真实 UID 和 GID。适合正式部署前的快速验证：跑起来下首歌，看新文件属主对不对，不对就改数字重来。
长期部署：Docker Compose 的 user 字段
生产环境建议把配置写进 compose 文件，重启、升级都不会丢：
services: xiaomusic: image: hanxi/xiaomusic user: "1000:1000" volumes: - /xiaomusic_music:/app/music - /xiaomusic_conf:/app/confuser与image同级即可，镜像名以 README.md 中 Docker 部署一节为准。改完文件执行docker compose up -d生效。适合长期使用：命令不用敲第二遍，配置一眼可见，注意 UID/GID 要和宿主机实际用户一致。
进阶：关于 PUID/PGID 与用户命名空间映射
有些镜像支持 PUID/PGID 环境变量来设置用户，但 xiaomusic 自身没有内置这类变量，在它的设置里找不到很正常，-u/user就是正解。如果你的宿主机需要更细粒度的 UID 映射，Docker 还支持用户命名空间重映射（配合 /etc/subuid 和 /etc/subgid 文件），配置偏折腾，只建议多用户、严格隔离的场景再考虑。
动手前照着做这 3 步检查
- ✅ 查清目标用户编号：在宿主机执行
id 用户名，记下 uid= 和 gid= 后面的数字。 - ✅ 确认挂载目录：/xiaomusic_music、/xiaomusic_conf 两个目录的属主和权限要允许该用户读写（Dockerfile 里声明的就是 /app/music 和 /app/conf 两个卷）。
- ✅ 改完配置重建容器：
docker compose up -d，播放一首歌触发下载，再用ls -ln查看新文件属主是否已是自己的账号。
第 3 步通过后，说明这条链路完全修好，之后生成的文件归属正确，既不用 chown，也不用把目录权限开到 777 这种危险做法。
守住最小权限原则，现在就去重启你的容器
容器用能完成任务的最小身份运行就好。改完 user 之后如果某个目录还报权限错，正确姿势是修那个目录的属主，而不是退回去用 root 跑。现在回到你的机器，把 xiaomusic 容器重建一次，几分钟的事。
【免费下载链接】xiaomusic使用小爱音箱播放音乐，音乐使用 yt-dlp 下载。项目地址: https://gitcode.com/GitHub_Trending/xia/xiaomusic
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
