xiaomusic 修改默认 8090 端口指南docker-compose 端口映射失效问题排查与正确配置【免费下载链接】xiaomusic使用小爱音箱播放音乐音乐使用 yt-dlp 下载。项目地址: https://gitcode.com/GitHub_Trending/xia/xiaomusic导读使用小爱音箱播放音乐的开源项目 xiaomusic 默认在 8090 端口提供服务很多用户在 Docker 部署时习惯将容器端口映射为宿主机其他端口如80:8090却发现播放失败——日志里依然请求http://IP:8090而非映射后的地址。本文以 docs/issues/19.md 的实战问题为骨架结合 config.py、music_library.py、README.md 等源码与文档讲清楚port与public_port两个端口参数的真实含义、播放 URL 的生成链路并给出 docker-compose、Docker CLI、反向代理、后台设置四种改端口方案读完即可正确配置任意端口的 xiaomusic。问题现象映射端口后播放失败日志仍调用 8090Issue #19 描述的典型场景是用户在 docker-compose 中把容器端口映射为宿主机 80 端口ports: - 80:8090结果播放失败从日志可以看到程序依旧拼接出http://10.0.0.4:8090/...这样的播放地址而不是映射后的 80 端口。日志中关键的一行是xiaomusic | [02/21/24 15:29:29] INFO 播放 xiaomusic.py:461 xiaomusic | http://10.0.0.4:8090/music/%E5%AE% xiaomusic | 89%E6%B2%B3%E6%A1%A5%E5%8C%97.mp3把映射还原成8090:8090后一切恢复正常。这个现象的根本原因并不在 Docker而在于xiaomusic 生成音乐播放 URL 时使用的端口不来自 Docker 映射规则而是来自自身配置中的端口参数。只改 Docker 的ports映射而应用内部仍认为自己在 8090 端口就会生成无法访问的播放地址小爱音箱自然拿不到音频流。端口参数拆解port 与 public_port 各管什么xiaomusic 有两个与端口相关的配置项定义在 config.pyport: int int(os.getenv(XIAOMUSIC_PORT, 8090)) # 监听端口 public_port: int int(os.getenv(XIAOMUSIC_PUBLIC_PORT, 58090)) # 歌曲访问端口两者作用完全不同配置项环境变量默认值作用portXIAOMUSIC_PORT8090服务监听端口即 HTTP 服务实际绑定的端口也是xiaomusic进程监听的端口public_portXIAOMUSIC_PUBLIC_PORT58090对外公布的歌曲访问端口拼接在播放 URL 中0表示与监听端口一致对应的config-example.json中也保留着这两项默认值见 config-example.json{ port: 8090, public_port: 58090 }后台设置页面static/tailwind/setting.html中同样有这两个字段其中public_port被标注为外网访问端口(0表示跟监听端口一致)。需要特别说明当前仓库的默认public_port已是 58090这是与 Issue #19 讨论时期默认 8090不同的新默认值说明项目已经针对歌曲访问端口必须独立配置做了调整。但从源码逻辑上看只要修改了port而不同步修改public_port仍可能出现播放 URL 端口不一致的问题因此下面的配置原则依然适用。播放 URL 是如何拼出来的源码调用链之所以只改 Docker 映射无效是因为播放 URL 完全由配置拼接生成与 Docker 无关。核心逻辑在 music_library.py 的_get_file_url# 构造URL encoded_name urllib.parse.quote(filename) url f{self.config.hostname}:{self.config.public_port}/music/{encoded_name} return try_add_access_control_param(self.config, url)URL 由三部分组成hostname默认http://192.168.2.5见 config.py通常改成局域网内 NAS/主机的 IPpublic_port歌曲访问端口这是播放地址里真正出现的端口号路径/music/歌曲名如果歌曲在music_path子目录下则会带上子目录。类似的拼接还出现在封面图 URLmusic_library.py和在线音乐代理 URLmusic_library.py中全部使用hostname:public_port组合。也就是说public_port是贯穿所有对外资源地址的关键参数。而服务实际监听端口则来自port配置在 cli.py 中读取port int(config.port)因此整个链路可以概括为HTTP 服务监听port默认 8090播放时用hostname public_port拼出对外可访问的 URL小爱音箱去访问这个 URL 拉取音频流如果public_port对应的端口上根本没有服务例如只改了 Docker 映射、没改配置请求就会失败。正确改端口的方案三个数字必须一致Issue #19 中维护者 hanxi 给出的结论非常明确如果换端口需要三个数字一致。即environment中的XIAOMUSIC_PORT、ports的宿主机端口与容器端口保持一致environment: XIAOMUSIC_PORT: 6874 ports: - 6874:6874这样服务监听6874播放 URL 也拼出6874Docker 又把6874原样暴露全链路端口一致播放自然正常。评论区补充的说明也印证了这一点XIAOMUSIC_PORT可以按需设置但要求上下两处端口都设置成同一个值例如environment: XIAOMUSIC_PORT: 5678 ports: - 5678:5678更完整的解释Issue #19 评论 5把 docker-compose 中两者的对应关系归纳为ports: - aaaa:bbbb environment: XIAOMUSIC_PORT: bbbb # 对应配置中的 port监听端口修改后需要重启 XIAOMUSIC_PUBLIC_PORT: aaaa # 对应配置中的 public_port外网访问端口0 表示跟监听端口一致结论是Docker 环境中一般不需要修改 bbbb容器内监听端口也就是不必设置XIAOMUSIC_PORT。如果只是想换一个对外访问的端口只需要把两处 aaaa 改成同一数字并同步设置XIAOMUSIC_PUBLIC_PORT。实战配置示例方案一docker-compose 换端口监听端口不变保持容器内 8090 不变只把对外暴露端口改成 5678同时把public_port指到 5678services: xiaomusic: image: hanxi/xiaomusic container_name: xiaomusic restart: always environment: XIAOMUSIC_HOSTNAME: http://192.168.2.5 # 改成宿主机局域网 IP XIAOMUSIC_PUBLIC_PORT: 5678 # 对外访问端口 ports: - 5678:8090 volumes: - /xiaomusic_music:/app/music - /xiaomusic_conf:/app/conf后台访问地址为http://NAS_IP:5678。方案二docker-compose 连监听端口一起换按 Issue #19 的三数一致原则把监听端口、映射端口、public_port 全部设为同一值services: xiaomusic: image: hanxi/xiaomusic environment: XIAOMUSIC_PORT: 6874 # 监听端口 XIAOMUSIC_PUBLIC_PORT: 6874 # 歌曲访问端口 ports: - 6874:6874方案三Docker CLI 运行Docker CLI 与 compose 等价注意环境变量与-p映射的配合docker run -p 5678:8090 \ -e XIAOMUSIC_HOSTNAMEhttp://192.168.2.5 \ -e XIAOMUSIC_PUBLIC_PORT5678 \ -v /xiaomusic_music:/app/music \ -v /xiaomusic_conf:/app/conf \ hanxi/xiaomusicREADME 中也明确提醒README.md58090是 NAS 本地端口8090是容器端口不要去修改容器端口后台访问地址为http://NAS_IP:58090。这与Docker 环境中不需要修改XIAOMUSIC_PORT的结论一致。方案四反向代理场景如果使用 Nginx 等反向代理转发localhost:aaaa即宿主机的对外映射端口则XIAOMUSIC_PUBLIC_PORT应设置成代理的监听端口environment: XIAOMUSIC_PUBLIC_PORT: 8080 # 反向代理监听端口 ports: - 5678:8090server { listen 8080; server_name music.example.com; location / { proxy_pass http://127.0.0.1:5678; } }这样播放 URL 会生成http://hostname:8080/music/...流量经反向代理转发到实际服务既隐藏了内部端口也解决了播放地址端口不一致的问题。非 Docker 环境pip / 开发模式改端口通过 pip 安装或源码运行时同样遵循监听端口与播放地址端口两套逻辑# 查看帮助 xiaomusic --help # 使用配置文件启动config.json 参考 config-example.json xiaomusic --config config.json # 默认监听 8090 直接启动 xiaomusic默认监听端口 8090后台 API 文档地址为http://localhost:8090/docs见 README.md。如果要把监听端口改成 8080并让播放 URL 也指向 8080需要同时设置XIAOMUSIC_PORT与XIAOMUSIC_PUBLIC_PORTexport XIAOMUSIC_PORT8080 export XIAOMUSIC_PUBLIC_PORT8080 xiaomusic或者写入config.json{ hostname: http://192.168.2.5, port: 8080, public_port: 8080 }开发模式下pdm run xiaomusic.py默认监听端口同样是 8090修改端口后记得重启服务使其生效。避坑提醒settings.json 会覆盖环境变量Issue #19 评论 5 特别强调了一个关键点setting 文件存在时会覆盖环境变量。xiaomusic 启动时会把配置文件中的设置读取并覆盖已有配置相关逻辑在 xiaomusic.py# 尝试从设置里加载配置 config_data self.config_manager.try_init_setting() if config_data: self.update_config_from_setting(config_data)配置文件的路径由conf_path决定默认为conf/setting.json见 config.py 的getsettingfile方法。也就是说如果conf/setting.json中已经写入过旧的端口值即使你改了环境变量或 docker-compose启动时也会被文件中的旧值覆盖启动过之后修改端口应该直接修改settings.json或者在后台设置页面修改后保存而不是只改环境变量在后台修改配置会通过 api/routers/system.py 的/api/system/modifiysetting接口更新配置并落盘涉及port、hostname等 HTTP 服务器相关配置时还会触发reset_http_server重置 HTTP 服务。因此排查改了端口不生效问题时第一件事就是检查conf/setting.json里是否残留了旧端口。小结排查/配置项结论只改 Dockerports映射无效播放 URL 由应用配置生成与映射无关port/XIAOMUSIC_PORT服务监听端口修改后需要重启public_port/XIAOMUSIC_PUBLIC_PORT播放 URL 中出现的对外端口0表示与监听端口一致Docker 最佳实践不改容器内端口只改对外映射端口 同步XIAOMUSIC_PUBLIC_PORT反向代理XIAOMUSIC_PUBLIC_PORT设为代理监听端口代理转发到实际端口配置优先级conf/setting.json覆盖环境变量改端口后需同步修改或后台保存最终验证查看日志中播放 http://IP:PORT/music/...一行的端口是否可访问修改 xiaomusic 端口时牢记两个原则一播放地址端口来自public_port而不是 Docker 映射二配置文件会覆盖环境变量。把握住这两点无论 Docker、反向代理还是 pip 部署都能让端口修改一次到位。【免费下载链接】xiaomusic使用小爱音箱播放音乐音乐使用 yt-dlp 下载。项目地址: https://gitcode.com/GitHub_Trending/xia/xiaomusic创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
xiaomusic 修改默认 8090 端口指南：docker-compose 端口映射失效问题排查与正确配置
xiaomusic 修改默认 8090 端口指南docker-compose 端口映射失效问题排查与正确配置【免费下载链接】xiaomusic使用小爱音箱播放音乐音乐使用 yt-dlp 下载。项目地址: https://gitcode.com/GitHub_Trending/xia/xiaomusic导读使用小爱音箱播放音乐的开源项目 xiaomusic 默认在 8090 端口提供服务很多用户在 Docker 部署时习惯将容器端口映射为宿主机其他端口如80:8090却发现播放失败——日志里依然请求http://IP:8090而非映射后的地址。本文以 docs/issues/19.md 的实战问题为骨架结合 config.py、music_library.py、README.md 等源码与文档讲清楚port与public_port两个端口参数的真实含义、播放 URL 的生成链路并给出 docker-compose、Docker CLI、反向代理、后台设置四种改端口方案读完即可正确配置任意端口的 xiaomusic。问题现象映射端口后播放失败日志仍调用 8090Issue #19 描述的典型场景是用户在 docker-compose 中把容器端口映射为宿主机 80 端口ports: - 80:8090结果播放失败从日志可以看到程序依旧拼接出http://10.0.0.4:8090/...这样的播放地址而不是映射后的 80 端口。日志中关键的一行是xiaomusic | [02/21/24 15:29:29] INFO 播放 xiaomusic.py:461 xiaomusic | http://10.0.0.4:8090/music/%E5%AE% xiaomusic | 89%E6%B2%B3%E6%A1%A5%E5%8C%97.mp3把映射还原成8090:8090后一切恢复正常。这个现象的根本原因并不在 Docker而在于xiaomusic 生成音乐播放 URL 时使用的端口不来自 Docker 映射规则而是来自自身配置中的端口参数。只改 Docker 的ports映射而应用内部仍认为自己在 8090 端口就会生成无法访问的播放地址小爱音箱自然拿不到音频流。端口参数拆解port 与 public_port 各管什么xiaomusic 有两个与端口相关的配置项定义在 config.pyport: int int(os.getenv(XIAOMUSIC_PORT, 8090)) # 监听端口 public_port: int int(os.getenv(XIAOMUSIC_PUBLIC_PORT, 58090)) # 歌曲访问端口两者作用完全不同配置项环境变量默认值作用portXIAOMUSIC_PORT8090服务监听端口即 HTTP 服务实际绑定的端口也是xiaomusic进程监听的端口public_portXIAOMUSIC_PUBLIC_PORT58090对外公布的歌曲访问端口拼接在播放 URL 中0表示与监听端口一致对应的config-example.json中也保留着这两项默认值见 config-example.json{ port: 8090, public_port: 58090 }后台设置页面static/tailwind/setting.html中同样有这两个字段其中public_port被标注为外网访问端口(0表示跟监听端口一致)。需要特别说明当前仓库的默认public_port已是 58090这是与 Issue #19 讨论时期默认 8090不同的新默认值说明项目已经针对歌曲访问端口必须独立配置做了调整。但从源码逻辑上看只要修改了port而不同步修改public_port仍可能出现播放 URL 端口不一致的问题因此下面的配置原则依然适用。播放 URL 是如何拼出来的源码调用链之所以只改 Docker 映射无效是因为播放 URL 完全由配置拼接生成与 Docker 无关。核心逻辑在 music_library.py 的_get_file_url# 构造URL encoded_name urllib.parse.quote(filename) url f{self.config.hostname}:{self.config.public_port}/music/{encoded_name} return try_add_access_control_param(self.config, url)URL 由三部分组成hostname默认http://192.168.2.5见 config.py通常改成局域网内 NAS/主机的 IPpublic_port歌曲访问端口这是播放地址里真正出现的端口号路径/music/歌曲名如果歌曲在music_path子目录下则会带上子目录。类似的拼接还出现在封面图 URLmusic_library.py和在线音乐代理 URLmusic_library.py中全部使用hostname:public_port组合。也就是说public_port是贯穿所有对外资源地址的关键参数。而服务实际监听端口则来自port配置在 cli.py 中读取port int(config.port)因此整个链路可以概括为HTTP 服务监听port默认 8090播放时用hostname public_port拼出对外可访问的 URL小爱音箱去访问这个 URL 拉取音频流如果public_port对应的端口上根本没有服务例如只改了 Docker 映射、没改配置请求就会失败。正确改端口的方案三个数字必须一致Issue #19 中维护者 hanxi 给出的结论非常明确如果换端口需要三个数字一致。即environment中的XIAOMUSIC_PORT、ports的宿主机端口与容器端口保持一致environment: XIAOMUSIC_PORT: 6874 ports: - 6874:6874这样服务监听6874播放 URL 也拼出6874Docker 又把6874原样暴露全链路端口一致播放自然正常。评论区补充的说明也印证了这一点XIAOMUSIC_PORT可以按需设置但要求上下两处端口都设置成同一个值例如environment: XIAOMUSIC_PORT: 5678 ports: - 5678:5678更完整的解释Issue #19 评论 5把 docker-compose 中两者的对应关系归纳为ports: - aaaa:bbbb environment: XIAOMUSIC_PORT: bbbb # 对应配置中的 port监听端口修改后需要重启 XIAOMUSIC_PUBLIC_PORT: aaaa # 对应配置中的 public_port外网访问端口0 表示跟监听端口一致结论是Docker 环境中一般不需要修改 bbbb容器内监听端口也就是不必设置XIAOMUSIC_PORT。如果只是想换一个对外访问的端口只需要把两处 aaaa 改成同一数字并同步设置XIAOMUSIC_PUBLIC_PORT。实战配置示例方案一docker-compose 换端口监听端口不变保持容器内 8090 不变只把对外暴露端口改成 5678同时把public_port指到 5678services: xiaomusic: image: hanxi/xiaomusic container_name: xiaomusic restart: always environment: XIAOMUSIC_HOSTNAME: http://192.168.2.5 # 改成宿主机局域网 IP XIAOMUSIC_PUBLIC_PORT: 5678 # 对外访问端口 ports: - 5678:8090 volumes: - /xiaomusic_music:/app/music - /xiaomusic_conf:/app/conf后台访问地址为http://NAS_IP:5678。方案二docker-compose 连监听端口一起换按 Issue #19 的三数一致原则把监听端口、映射端口、public_port 全部设为同一值services: xiaomusic: image: hanxi/xiaomusic environment: XIAOMUSIC_PORT: 6874 # 监听端口 XIAOMUSIC_PUBLIC_PORT: 6874 # 歌曲访问端口 ports: - 6874:6874方案三Docker CLI 运行Docker CLI 与 compose 等价注意环境变量与-p映射的配合docker run -p 5678:8090 \ -e XIAOMUSIC_HOSTNAMEhttp://192.168.2.5 \ -e XIAOMUSIC_PUBLIC_PORT5678 \ -v /xiaomusic_music:/app/music \ -v /xiaomusic_conf:/app/conf \ hanxi/xiaomusicREADME 中也明确提醒README.md58090是 NAS 本地端口8090是容器端口不要去修改容器端口后台访问地址为http://NAS_IP:58090。这与Docker 环境中不需要修改XIAOMUSIC_PORT的结论一致。方案四反向代理场景如果使用 Nginx 等反向代理转发localhost:aaaa即宿主机的对外映射端口则XIAOMUSIC_PUBLIC_PORT应设置成代理的监听端口environment: XIAOMUSIC_PUBLIC_PORT: 8080 # 反向代理监听端口 ports: - 5678:8090server { listen 8080; server_name music.example.com; location / { proxy_pass http://127.0.0.1:5678; } }这样播放 URL 会生成http://hostname:8080/music/...流量经反向代理转发到实际服务既隐藏了内部端口也解决了播放地址端口不一致的问题。非 Docker 环境pip / 开发模式改端口通过 pip 安装或源码运行时同样遵循监听端口与播放地址端口两套逻辑# 查看帮助 xiaomusic --help # 使用配置文件启动config.json 参考 config-example.json xiaomusic --config config.json # 默认监听 8090 直接启动 xiaomusic默认监听端口 8090后台 API 文档地址为http://localhost:8090/docs见 README.md。如果要把监听端口改成 8080并让播放 URL 也指向 8080需要同时设置XIAOMUSIC_PORT与XIAOMUSIC_PUBLIC_PORTexport XIAOMUSIC_PORT8080 export XIAOMUSIC_PUBLIC_PORT8080 xiaomusic或者写入config.json{ hostname: http://192.168.2.5, port: 8080, public_port: 8080 }开发模式下pdm run xiaomusic.py默认监听端口同样是 8090修改端口后记得重启服务使其生效。避坑提醒settings.json 会覆盖环境变量Issue #19 评论 5 特别强调了一个关键点setting 文件存在时会覆盖环境变量。xiaomusic 启动时会把配置文件中的设置读取并覆盖已有配置相关逻辑在 xiaomusic.py# 尝试从设置里加载配置 config_data self.config_manager.try_init_setting() if config_data: self.update_config_from_setting(config_data)配置文件的路径由conf_path决定默认为conf/setting.json见 config.py 的getsettingfile方法。也就是说如果conf/setting.json中已经写入过旧的端口值即使你改了环境变量或 docker-compose启动时也会被文件中的旧值覆盖启动过之后修改端口应该直接修改settings.json或者在后台设置页面修改后保存而不是只改环境变量在后台修改配置会通过 api/routers/system.py 的/api/system/modifiysetting接口更新配置并落盘涉及port、hostname等 HTTP 服务器相关配置时还会触发reset_http_server重置 HTTP 服务。因此排查改了端口不生效问题时第一件事就是检查conf/setting.json里是否残留了旧端口。小结排查/配置项结论只改 Dockerports映射无效播放 URL 由应用配置生成与映射无关port/XIAOMUSIC_PORT服务监听端口修改后需要重启public_port/XIAOMUSIC_PUBLIC_PORT播放 URL 中出现的对外端口0表示与监听端口一致Docker 最佳实践不改容器内端口只改对外映射端口 同步XIAOMUSIC_PUBLIC_PORT反向代理XIAOMUSIC_PUBLIC_PORT设为代理监听端口代理转发到实际端口配置优先级conf/setting.json覆盖环境变量改端口后需同步修改或后台保存最终验证查看日志中播放 http://IP:PORT/music/...一行的端口是否可访问修改 xiaomusic 端口时牢记两个原则一播放地址端口来自public_port而不是 Docker 映射二配置文件会覆盖环境变量。把握住这两点无论 Docker、反向代理还是 pip 部署都能让端口修改一次到位。【免费下载链接】xiaomusic使用小爱音箱播放音乐音乐使用 yt-dlp 下载。项目地址: https://gitcode.com/GitHub_Trending/xia/xiaomusic创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
