常见BUG：xiaomusic 程序试图启动并监听 8090 端口，但发现该端口已经被另一个进程（或者是 xiaomusic 之前未正常退出的僵尸进程）占用，导致启动失败并退出。
以下是几种解决办法，请根据你的运行环境选择：
方法一：查找并结束占用端口的进程（推荐）
如果你是在 Linux 或 macOS 直接运行（非 Docker），或者你可以进入 Docker 容器内部：
1. 查找占用 8090 端口的进程 ID (PID)： 在终端执行：
lsof -i :8090
# 或者
netstat -tunlp | grep 8090
Plain Text
1. 杀掉该进程： 假设上一步查到的 PID 是 1234（请替换为实际显示的数字）：
```
kill -9 1234
```
Plain Text
### 重启 xiaomusic： 再次尝试启动程序。
查询端口占用情况
在 SSH 命令行中，执行以下命令检查端口（重点检查 10000 端口，这是极空间的 web 登录端口）。这些命令会列出所有监听端口和占用进程。
- 检查所有 TCP/UDP 监听端口（推荐使用 ss，更现代）：
```
lsof -i :8090
```
# 或者
netstat -tunlp | grep 8090
Bash
```
ss -tuln
```
Plain Text
- 输出示例：会显示如 tcp LISTEN 0 128 :10000 :\* 表示 10000 端口被占用。
- 过滤特定端口：ss -tuln | grep:10000
- 备选命令（如果 ss 不可用，使用 netstat，需要安装 net-tools）：
```
netstat -tuln | grep :10000
```
Plain Text
- 检查端口占用进程详情（使用 lsof，需确保已安装）：
```
lsof -i :10000
```
Plain Text
- 输出会显示进程 ID (PID)、用户、命令等，如：
```
COMMAND PID USER FD TYPE DEVICE SIZE/OFF NODE NAME
```
node 12345 root 10u IPv4 67890 0t0 TCP *:10000 (LISTEN)
Plain Text
这表示 10000 端口被 PID 12345 的 node 进程占用（极空间 web 服务可能基于 Node.js 或类似）。
- 检查所有端口占用汇总：
```
ss -tuln | awk '{print $5}' | cut -d: -f2 | sort -u
```
Plain Text
这会列出所有独特占用端口号（如 22, 80, 10000 等）。
常见极空间端口：
- 22: SSH
- 80/443: HTTP/HTTPS（可能重定向到 10000）
- 10000: Web 登录界面
- 其他：如 445 (SMB), 139 (NetBIOS), 基于你的配置。
如果命令显示端口被占用，记录 PID 和命令名。
步骤 3: 如果端口被占用，如何解除占用（确保无服务运行）
警告 ：杀死进程前，确保这是你自己的设备，且进程不是 critical 系统服务。误杀可能导致数据丢失或设备重启。优先检查进程是否为极空间服务（e.g., zspace-web 或类似），如果是的，先尝试重启服务而不是直接杀。
1. 确认进程详情：
```
ps -p <PID> -o pid,ppid,cmd
```
Plain Text
替换 <PID> 为步骤 2 中查到的 PID。这会显示进程命令，确保不是重要服务（如极空间的核心 daemon）。
1. 安全杀死进程（先尝试优雅停止）：
- 发送 SIGTERM（温和 kill）：
```
kill <PID>
```
Plain Text
- 如果无效，强制 kill：
```
kill -9 <PID>
```
Plain Text
- 验证端口已释放：
```
ss -tuln | grep :10000
```
Plain Text
如果无输出，则端口空闲。
1. 如果是服务导致占用（e.g., 极空间 web 服务）：
- 检查服务状态：
```
systemctl status zspace-web # 假设服务名为 zspace-web，根据实际调整
```
Plain Text
- 停止服务：
```
systemctl stop zspace-web
```
Plain Text
- 重启服务（如果需要恢复）：
```
systemctl restart zspace-web
```
\
1. 确保无服务运行后再检查：
- 运行 ps aux | grep <command\_name>（替换 <command\_name> 为步骤 2 中的命令，如 node）。
- 如果无进程，则端口安全释放。
- 如果端口仍占用，可能是 zombie 进程或内核问题，重启设备：
```
reboot
\
注意事项
- 权限 ：命令可能需要 root 权限，加 sudo 前缀（e.g., sudo ss -tuln）。如果未 sudo，输出可能不完整。
- 安全 ：只在本地网络操作，避免暴露端口到公网。杀死进程后，监控日志：tail -f /var/log/syslog 或极空间日志路径。
- 如果命令不可用 ：极空间是定制 Linux，可能缺少工具。使用 apt install net-tools lsof 安装（如果支持 Debian 包）。
- 替代工具 ：如果 PuTTY 不便，可用 Windows 的 OpenSSH 或 Linux 的 ssh 命令：ssh [email protected]。
- 如果问题持久，检查极空间官网文档或论坛（zspace.com 或类似），搜索 "端口占用"。
如果连接或命令失败，提供更多错误细节，我可以进一步指导。
---
XiaoMusic 项目地址：
[https://xdocs.hanxi.cc/](https://xdocs.hanxi.cc/)
微信小程序：
[https://github.com/F-loat/xiaoplayer](https://github.com/F-loat/xiaoplayer)
1️⃣ 基础文档
- [💬 FAQ问题集合](https://github.com/hanxi/xiaomusic/issues/99)
- [如何修改默认的8090端口](https://github.com/hanxi/xiaomusic/issues/19)
- [如何配置网络歌单](https://github.com/hanxi/xiaomusic/issues/78)
- [如何添加m3u格式文件的电台](https://github.com/hanxi/xiaomusic/issues/88)
- [xiaomusic极空间安装教程](https://github.com/hanxi/xiaomusic/issues/297)
- [docker compose 命令行安装教程](https://github.com/hanxi/xiaomusic/issues/360)
- [1Panel 安装运行 xiaomusic 教程](https://github.com/hanxi/xiaomusic/issues/600)
2️⃣ 进阶文档
- [设置项功能介绍](https://github.com/hanxi/xiaomusic/issues/333)
- [采用config.json配置方式](https://github.com/hanxi/xiaomusic/issues/94)
- [ios系统上的捷径配置](https://github.com/hanxi/xiaomusic/issues/96)
- [【插件】自定义口令功能](https://github.com/hanxi/xiaomusic/issues/105)
- [定时任务配置格式](https://github.com/hanxi/xiaomusic/issues/182)
- [yt-dlp cookies 文件上传功能](https://github.com/hanxi/xiaomusic/issues/210)
- [如何批量下载歌曲](https://github.com/hanxi/xiaomusic/issues/212)
- [设备分组播放](https://github.com/hanxi/xiaomusic/issues/65#issuecomment-2215736529)
- [如何播放小雅alist里的歌曲](https://github.com/hanxi/xiaomusic/issues/128#issuecomment-2232867180)
- [如何添加 网易云音乐playlist](https://github.com/hanxi/xiaomusic/issues/269)
- [相关工具推荐](https://github.com/hanxi/xiaomusic/issues/285)
## 3️⃣ 其他安装文档
Note
下面教程可能比较旧，只供参考
- [群晖docker安装 xiaomusic](https://github.com/hanxi/xiaomusic/issues/101)
- [NAS部署教程](https://post.m.smzdm.com/p/avpe7n99/)
- [群晖部署教程](https://post.m.smzdm.com/p/a7px7dol/)
- [QNAS部署教程](https://post.smzdm.com/p/a5xz5x63/)
- [视频教程-群晖1](https://www.bilibili.com/video/BV1ZZpweHEtT/)
- [视频教程-群晖2](https://www.bilibili.com/video/BV1JXxXeBEdY/)
- [视频教程-拾光坞N3](https://www.bilibili.com/video/BV1q629YMEG6/)
- [TechHive](https://mp.weixin.qq.com/s/4a41muFtPaFKtHeZYu795w)
- [弹个AI](https://mp.weixin.qq.com/s/sIsKxB7Y8b83AhnvaWiMog)
- [简单免费！教你用绿联NAS联动小爱音箱，私人音乐库也能语音点播](https://post.m.smzdm.com/p/a8pldgg7/)
- [飞牛教程](https://mp.weixin.qq.com/s?t=pages/image_detail&__biz=MzkxODc1NDMwOA==&mid=2247483725&idx=1&sn=2d615f14733b9bf989557fa766b4e1fc)