企业官网建设流程全解析

xiaomusic 下载的音乐宿主机打不开？3 种容器用户权限配置一次搞定

【免费下载链接】xiaomusic使用小爱音箱播放音乐，音乐使用 yt-dlp 下载。项目地址: https://gitcode.com/GitHub_Trending/xia/xiaomusic

xiaomusic 用 Docker 部署好，歌也下载成功了，可你一登录宿主机目录想拷文件，却提示「权限不够」——文件全归 root 所有。这篇走一遍容器用户权限配置的 3 条路径，让下载的音乐文件从出生起就属于你的宿主用户。

一分钟看懂根因：一个编号叫 UID

不用钻内核，一个类比就够：

• 每个文件身上都刻着「门禁工号」（UID/GID）。Linux 判断谁能读写，只看编号，不看名字。
• 容器里的进程默认是 root（工号 0）。它在挂载的音乐目录里生成的文件，全都盖着 0 号章。
• 你的宿主普通用户是 1000 之类的工号。看到 0 号章的文件，只能按权限位走，经常写不了、删不掉。
• UNRAID 这类 NAS 尤其明显：下载的音乐属主显示 root，非 root 用户整理目录就会处处碰壁。

所以权限问题的本质就一句话：容器进程的工号和宿主用户的工号对不上。把容器进程的工号改成一样，麻烦就消了。

三条解决路径：按场景选一条

路径一：临时试跑——给 docker run 加一行

最快的验证方式。在你现有的启动命令上加一个-u：

docker run -u 1000:1000 -p 58090:8090 -v /xiaomusic_music:/app/music hanxi/xiaomusic

前面是 UID、后面是 GID，用你宿主用户的编号（id 你的用户名可查）。适合「先快速试一下行不行」的时刻，重建容器时记得带上这行参数。

路径二：长期部署——写进 Compose

正式部署就写进 compose 文件，以后升级镜像、重建容器都不会丢：

services: xiaomusic: image: hanxi/xiaomusic user: "1000:1000" ports: - 58090:8090 volumes: - /xiaomusic_music:/app/music - /xiaomusic_conf:/app/conf restart: always

核心就是user这一行，其余是常规启动配置。/app/music（音乐目录）和/app/conf（配置目录）是容器内固定路径，宿主机侧路径随意。首次启动前先把宿主机目录建好，否则容器会报找不到目录。

路径三：进阶精细控制——用户命名空间映射

多容器混跑、宿主机多用户需要区分归属时，可以启用 user namespace 重映射：在宿主机/etc/subuid、/etc/subgid里为容器用户配一段 UID 区间，启动时加--userns-remap。容器内的 root 会被自动映射成宿主机上的一组普通用户编号，新建文件自然归这个用户。这套方案最彻底，但配置面较大，前两条路满足不了再考虑。

路径怎么选：一张表对比

落地检查清单

• 宿主机执行id，记下目标用户的 UID 和 GID
• Compose 里加上user: "UID:GID"（或 docker run 加-u UID:GID）
• 首次启动前创建宿主机音乐目录与配置目录，并确认该用户可读写
• 重启容器后下载一首歌，用ls -l核对宿主目录里的文件属主
• 容器内路径/app/music、/app/conf不要改动（镜像里已用 VOLUME 声明，见 Dockerfile）

常见踩坑 FAQ

Q：改了 user 之后容器起不来了，报权限错误？ A：容器进程不再是 root，就写不动你挂载的宿主机目录了。启动前先确认音乐目录、配置目录对该用户有读写权限——在宿主机用该用户身份touch一个测试文件验证一下最稳。

Q：换用户会不会影响网页端和音箱设备连接？ A：不会。网页后台和设备列表依赖的是 conf 目录里的配置，与运行用户无关。改完用户后打开后台，确认歌曲列表和设置项都在即可。

Q：UNRAID 挂载的目录，宿主机访问还是提示拒绝？ A：UNRAID 有自己的权限体系，容器 UID 只是其中一环。还要在 UNRAID 侧把对应共享目录的属主对齐到容器使用的 UID，或放开该共享的 guest 访问。关键就一条：容器工号、目录属主、访问用户的工号，三者要能对得上。

收尾

权限问题的本质只是「容器进程的工号要和宿主用户的工号一致」。挑一条适合你的路径，照着清单勾完，xiaomusic 下载的音乐自然归你的宿主用户所有。更多部署细节可参考 docs/index.md。

【免费下载链接】xiaomusic使用小爱音箱播放音乐，音乐使用 yt-dlp 下载。项目地址: https://gitcode.com/GitHub_Trending/xia/xiaomusic