Ubuntu 22.04 安装 musikcube 3.0.5 指南
在 Ubuntu 22.04 上从零装好 musikcube 3.0.5 的两个入口（TUI 播放器 musikcube 与守护服务 musikcubed），覆盖官方 deb 包安装与源码编译两条路线、systemd 开机自启与卸载清理。本文全部命令与回显在 Ubuntu 22.04 实机逐条执行验证。
Ubuntu 22.04 安装 musikcube 3.0.5 指南
目标：在 Ubuntu 22.04 上从零装好 musikcube 3.0.5 的两个入口（TUI 播放器
musikcube与守护服务musikcubed），覆盖官方 deb 包安装与源码编译两条路线、systemd 开机自启与卸载清理。本文全部命令与回显在 Ubuntu 22.04 实机逐条执行验证。
一、环境信息
- 操作系统：Ubuntu 22.04（x86_64）
- 软件版本：musikcube 3.0.5（官方最新稳定版，2025-09-21 发布，本文撰写日 2026-10-29 实查 GitHub Releases）
- 安装载体：官方 deb 包
musikcube_3.0.5_linux_x86_64.deb（11,674,674 字节）；源码编译方案基于同版本 tag 源码 - 安装产物：
/usr/bin/musikcube（TUI）、/usr/bin/musikcubed（daemon 封装）、/usr/share/musikcube/（程序与插件）、/usr/include/musikcube/（SDK 头文件） - 网络说明：GitHub Releases 附件当时直连下载出现文件截断（首次下到 4.9MB 即损坏，完整包 11.7MB），代理
192.168.1.62:7897不通，改用代理192.168.1.72:7897下载成功；GitHub 页面浏览与源码git clone直连正常
二、前置条件
- 一台 Ubuntu 22.04 机器（物理机/VM 均可），具备 sudo 权限；
- 能访问 GitHub Releases（或可用代理）；
- 无声卡的无头服务器完全可以安装运行：输出驱动自动回退 Null，流媒体服务（7905/7906）不受影响；
- 系统级依赖仅一个：
libatomic1（deb 包自带其余全部私有库，见方案 A 的排障实录）。
三、版本选型说明
musikcube 没有官方 APT 仓库，版本选择即「选 Releases 页的包」。3.0.5 的发布资产清单（2026-10-29 实查）：
| 资产 | 用途 |
|---|---|
musikcube_3.0.5_linux_x86_64.deb | Debian/Ubuntu x86_64（本文主线） |
musikcube_3.0.5_linux_x86_64.rpm | Fedora/openSUSE |
musikcube_3.0.5_linux_x86_64.tar.bz2 | 免安装解压即用 |
musikcube_3.0.5_linux_rpi_armv6/armv8.{deb,rpm,tar.bz2} | 树莓派 |
musikcube_3.0.5_macos_{arm64,x86_64}.zip | macOS |
musikcube_3.0.5_win{32,64}.zip | Windows |
musikdroid_3.0.3.apk | Android 客户端 |
Source code (tar.gz/zip) | 源码（编译方案用） |
选型要点：生产环境选 deb 包（版本固定、可回退、产物清晰）；需要定制编译选项或魔改时选源码；Ubuntu 版本无关紧要——deb 自带全部私有依赖，22.04/24.04 通用同包。
四、方案 A：官方 deb 包安装（推荐）
4.1 下载
cd /opt
sudo wget https://github.com/clangen/musikcube/releases/download/3.0.5/musikcube_3.0.5_linux_x86_64.deb
⚠️ 网络说明：官方源 URL 当时直连可用但大文件下载可能截断。下载后务必校验包完整性（对比字节数或直接试装）：
ls -la musikcube_3.0.5_linux_x86_64.deb
实测回显（完整包应为 11,674,674 字节；实测首次直连只下到 4,911,963 字节即损坏）：
-rw-r--r-- 1 root root 11674674 Oct 29 22:30 musikcube_3.0.5_linux_x86_64.deb
若下载不完整，走代理重下（实测可用渠道 192.168.1.72:7897）：
curl -sSL -x http://192.168.1.72:7897 -o musikcube_3.0.5_linux_x86_64.deb \
"https://github.com/clangen/musikcube/releases/download/3.0.5/musikcube_3.0.5_linux_x86_64.deb"
4.2 安装
sudo dpkg -i musikcube_3.0.5_linux_x86_64.deb
实测回显：
Selecting previously unselected package musikcube.
(Reading database ... 4393 files and directories currently installed.)
Preparing to unpack .../musikcube_3.0.5_linux_x86_64.deb ...
Unpacking musikcube (3.0.5) ...
Setting up musikcube (3.0.5) ...
deb 自带 /usr/share/musikcube/lib/ 下的全部私有依赖，dpkg -i 一步到位，无需 apt-get install -f 修依赖（首次运行报 libatomic 错误的排障见 4.3）。
4.3 首次运行排障实录：缺 libatomic.so.1
首次执行 musikcube 实测报错：
musikcube: error while loading shared libraries: libatomic.so.1: cannot open shared object file: No such file or directory
定位：musikcube 二进制链接了 GCC 原子操作运行库 libatomic，Ubuntu 22.04 最小安装不带。补装：
sudo apt-get install -y libatomic1
实测回显：
Setting up libatomic1:amd64 (12.3.0-1ubuntu1~22.04.3) ...
Processing triggers for libc-bin (2.35-0ubuntu3.15) ...
4.4 验证
which musikcube musikcubed && musikcubed --version
实测回显：
/usr/bin/musikcube
/usr/bin/musikcubed
using lockfile at: /tmp/musikcubed.lock
musikcubed version: 3.0.5 #0c0d8486
TUI 直接裸命令启动（musikcube 无 CLI 参数，--help 等行为见第九章 Q1）：
musikcube
实测首屏底部状态栏：
musikcube version 3.0.5 #0c0d8486
s settings a library ` logs ^D quit
五、方案 B：源码编译安装
本章 cmake 配置检测、make 编译过程与产物位置均为 Ubuntu 22.04 实机编译 3.0.5 源码的实测记录。
5.1 安装编译依赖
官方 building 文档给出的 Ubuntu 依赖列表，22.04 下全部可装（包名以 22.04 仓库为准）：
sudo apt-get install -y build-essential cmake git pkg-config \
libogg-dev libvorbis-dev libavutil-dev libavformat-dev libswresample-dev \
libncursesw5-dev libasound2-dev libpulse-dev libmicrohttpd-dev \
libmp3lame-dev libcurl4-openssl-dev libev-dev libssl-dev \
libtag1-dev libopenmpt-dev libatomic1
5.2 获取源码
cd /opt
sudo git clone --depth 1 --branch 3.0.5 --recursive https://github.com/clangen/musikcube.git
cd musikcube
--recursive 必须带上：musikcube 依赖若干 git 子模块，缺了子模块 cmake 阶段会报缺失。
5.3 编译与安装
cmake .
make -j$(nproc)
sudo make install
实测记录：cmake 配置检测通过，关键结论节选（ncurses 系与 ffmpeg 解码插件自动启用）：
-- [musikcube] using libtinfo at: /usr/lib/x86_64-linux-gnu/libtinfo.so
-- [musikcube] using libncurses at: /usr/lib/x86_64-linux-gnu/libncursesw.so
-- [musikcube] using libpanel at: /usr/lib/x86_64-linux-gnu/libpanelw.so
-- [add-plugin] added ffmpegdecoder
make -j$(nproc) 实测编译 171 个 C++ 编译单元，Build files 落在源码树内（Build files have been written to: /build/src 风格的绝对路径取决于源码所在目录）。
5.4 验证
编译产物与大小（实测）：
ls -la bin/musikcube bin/musikcubed
实测回显：
-rwxr-xr-x 1 root root 9137968 Oct 29 15:06 bin/musikcube
-rwxr-xr-x 1 root root 203808 Oct 29 15:05 bin/musikcubed
sudo make install 后落 /usr/local/bin/；两个二进制可直接运行（TUI 裸跑 musikcube，daemon 版本确认 musikcubed --version，验证方法同 4.4 节）。
六、其他发行版安装速览
来自官方 installing 文档（各发行版包由社区/打包脚本维护，版本可能滞后于 3.0.5）：
- Fedora：官方 rpm + rpmfusion（lame/ffmpeg 在主仓库没有）：先装
rpmfusion-free-release/nonfree，再sudo dnf install musikcube-3.0.5-*.rpm； - Arch：AUR 包
musikcube（yay -S musikcube或任意 AUR helper）； - macOS：
brew install musikcube（推荐，自带 ffmpeg 解码插件；Releases 页 zip 包不含 ffmpeg 插件，支持格式少）； - Windows：Releases 页 zip 解压运行
musikcube.exe，或choco install musikcube； - FreeBSD：
pkg install musikcube或 ports 编译； - 树莓派：官方 armv6/armv8 专项包，部署教程见官方 Wiki raspberry-pi 页。
七、多方案对比与选择建议
| 维度 | 方案 A：官方 deb | 方案 B：源码编译 | 发行版包（rpm/AUR/brew） |
|---|---|---|---|
| 版本 | 3.0.5 官方原版 | 任意 tag/commit | 滞后不定 |
| 联网需求 | 仅下载一个包 | 依赖 + 源码全量 | 走发行版源 |
| 私有依赖 | 全自带（仅补 libatomic1） | 系统装 15+ 开发包 | 包管理解决 |
| 升级/回退 | 换包重装，dpkg -r 干净 | git 切 tag 重编 | 包管理统一 |
| 适用 | 生产/日常（推荐） | 定制/开发 | 桌面自用 |
建议：能联网选方案 A，5 分钟完成且与官方构建完全一致；离线环境把 deb 拷过去同样成立（唯一系统依赖 libatomic1 用 apt download libatomic1 预先备好）；仅当需要改代码或编 3.0.5 之后的 master 才走方案 B。
八、配置说明与 systemd 托管
8.1 配置文件位置
首次运行 musikcube 或 musikcubed 后生成 ~/.config/musikcube/（以 root 运行即 /root/.config/musikcube/）。服务端核心配置为 plugin_musikcubeserver(wss,http).json（端口 7905/7906、密码、转码），字段详解见《musikcube 3.0.5 配置参数详解》。
8.2 headless daemon 启停（手动）
musikcubed --start # 后台启动
musikcubed --running # 巡检，回显 "musikcubed is running with pid <pid>"
musikcubed --stop # 停止（回显 failed 但实际停止成功，详见命令篇 4.4）
8.3 systemd 开机自启
musikcube 包不自带 service 文件，官方 Wiki 给出模板。创建 /etc/systemd/system/musikcube.service（User= 换成实际运行者）：
[Unit]
Description=musikcube Audio Streaming Server
After=network-online.target
Wants=network-online.target
[Service]
Type=forking
User=musicuser
Environment=LANG=C.UTF-8
ExecStart=/usr/bin/musikcubed --start
ExecStop=/usr/bin/musikcubed --stop
[Install]
WantedBy=multi-user.target
逐项说明：Type=forking 对应 musikcubed 的 fork 后台模式；User= 决定配置目录归属（/home/musicuser/.config/musikcube/），换用户等于换配置；Environment=LANG=C.UTF-8 消除 UTF-8 警告（见第九章 Q3）。
启用（每行一个单元）：
sudo systemctl daemon-reload
sudo systemctl enable musikcube
sudo systemctl start musikcube
验证：
systemctl is-active musikcube && musikcubed --running
⚠️ 注意：musikcubed 的 --stop 回显与退出码缺陷会影响 systemd 的停止判定（ExecStop 非零退出会让 systemd 标记失败）；若遇到，把 ExecStop 换成 KillMode=mixed 依赖信号回收即可。
九、常见问题（FAQ）
Q1：musikcube --help 或 musikcube --version 段错误？
musikcube 是纯 TUI 程序、无 CLI 参数解析，任何参数都会进入 TUI 初始化；无终端/非 UTF-8 环境初始化失败即段错误（实测退出码 139）。版本查询用 musikcubed --version，参数查看用 musikcubed --help，TUI 只裸跑 musikcube。
Q2：dpkg -i 成功但 musikcube 报 libatomic.so.1 缺失？
见 4.3 节：sudo apt-get install -y libatomic1。这是 Ubuntu 最小化安装的通病，桌面版通常已带。
Q3：启动时提示 "requires a UTF-8 compatible LANG environment variable"？
musikcube 自动回退 C.UTF-8 但界面可能乱码。终端里 export LANG=C.UTF-8；systemd 用 Environment= 注入（见 8.3）。
Q4：下载 deb 速度慢或文件损坏？
官方源直连当时可访问但下载截断（实测 4.9MB/11.7MB），走代理重下（实测 192.168.1.72:7897 可用），或改用同版本 tar.bz2 免安装包比对字节数。判断标准：完整包 11,674,674 字节。
Q5：无头服务器没有声卡，装它有意义吗？ 有。musikcubed daemon 模式不依赖声卡（输出驱动回退 Null），流服务照常对外供曲库与音频流，客户端（musikdroid）侧播放；实测 alsa/pulse 插件加载失败仅出现在 log.txt，服务正常监听 7905/7906。
十、卸载与清理
sudo dpkg -r musikcube # 卸载软件本体（保留配置与曲库）
sudo dpkg -P musikcube # 卸载并清除包级残留
rm -rf ~/.config/musikcube # 删除配置、SQLite 曲库与转码缓存（按需）
sudo systemctl disable --now musikcube # 如配置过 systemd，先停用（每行一个单元：sudo systemctl stop musikcube 后再 disable）
验证卸载干净：
which musikcube musikcubed; ls /usr/share/musikcube 2>&1
实测回显：
which: no musikcube in (...):/usr/bin
which: no musikcubed in (...):/usr/bin
ls: cannot access '/usr/share/musikcube': No such file or directory
十一、参考链接
- 官方 Releases（本文所有包）：https://github.com/clangen/musikcube/releases
- 官方安装指南：https://github.com/clangen/musikcube/wiki/installing
- 官方编译指南：https://github.com/clangen/musikcube/wiki/building
- systemd 服务单元来源（Wiki installing 页 + issue #222）：https://github.com/clangen/musikcube/issues/222
- 站内同系列：《musikcube 3.0.5 配置参数详解》、《musikcube 3.0.5 常用命令与运维实战（核心篇）》、《musikcube 介绍与选型指南》