Ubuntu 24.04 安装 NymphCast 0.2-alpha0 指南

目标：在 Ubuntu 24.04 上从源码编译安装 NymphCast 接收端（nymphcast_server）与 CLI 客户端（nymphcast_client），完成 systemd 服务托管与推流验证。已在 Ubuntu 24.04（x86_64）实测「官方脚本自动化」与「手动分步编译」两条路径并记录全部排障过程。

一、环境信息

本文全部命令与回显在以下环境实测采集（实测日期 2026-10-29）：

操作系统：Ubuntu 24.04 LTS（x86_64）
NymphCast 版本：v0.2-alpha0（GitHub tag，commit 3f50059，编译版本串 v0.2-alpha0.20241108）
工具链：g++ 13.3.0（Ubuntu 13.3.0-6ubuntu2~24.04.1）、make、git、pkg-config
关键库版本（实测 pkg-config --modversion 与 ffmpeg -version）：FFmpeg（libavcodec）60.31.102、SDL2 2.30.0、FreeType 26.1.20、FFmpeg 6.1.1-3ubuntu5
安装路径：二进制 /usr/local/bin/，配置 /usr/local/etc/nymphcast/，应用与壁纸 /usr/local/share/nymphcast/
服务托管：systemd 用户服务 /etc/systemd/user/nymphcast.service

⚠️ 发行版前提：本文实测于 Ubuntu 24.04。Ubuntu 22.04 无法直接编译——其 FFmpeg 为 4.4 系列，低于官方要求的 v5.1+（排障实录见十、常见问题 Q1）。22.04 用户请升级系统或改用 24.04/Debian 13+。

二、前置条件

系统依赖（编译 NymphCast 服务端与两个依赖库所需，官方 dependencies.sh 的 Debian 清单）：

apt -y install git g++ make sudo pkg-config libsdl2-image-dev libsdl2-dev \
  libpoco-dev libswscale-dev libavcodec-dev libavdevice-dev libavformat-dev \
  libavutil-dev libpostproc-dev libswresample-dev libfreetype6-dev \
  libfreeimage-dev rapidjson-dev libcurl4-gnutls-dev

安装完成后验证关键组件版本（实测回显）：

g++ --version | head -1
ffmpeg -version | head -1
pkg-config --modversion libavcodec sdl2 freetype2

g++ (Ubuntu 13.3.0-6ubuntu2~24.04.1) 13.3.0
ffmpeg version 6.1.1-3ubuntu5 Copyright (c) 2000-2023 the FFmpeg developers
60.31.102
2.30.0
26.1.20

网络可达 GitHub：三个源码仓库（NymphCast、NymphRPC、libnymphcast）都托管在 GitHub，编译期需 clone 两个依赖库。网络受限环境提前配置代理（本文实测环境通过代理完成，示例 export http_proxy=http://192.168.1.72:7897 https_proxy=http://192.168.1.72:7897，具体以所在网络为准）。
磁盘与内存：完整编译（含 GUI 相关目标文件）约需 2 GB 磁盘与 2 GB 可用内存；make -j4 编译服务端约 5–10 分钟（x86_64 四核实测）。

三、版本选型说明

NymphCast 的发布节奏与选型建议（GitHub Releases 实查，2026-10-29）：

版本线	发布时间	说明	适用
v0.1（稳定线）	2022-04-22	官方 README 认定的当前稳定版	追求保守
v0.2-alpha0（最新 Release）	2024-11-09 发布，2025-04-23 更新资产	v0.2 开发线首个 alpha：字幕/URL 推流增强、ffplay 播放内核重构、GUI 集成	想要新特性、可接受 alpha
master 分支	持续开发	不建议锁定部署	仅开发跟踪

预编译包情况（Release 资产实查）：

版本	提供的预编译资产
v0.2-alpha0	Android APK ×2（服务端 App、Player）、Windows 安装器 ×2（Server、Player）
v0.1	树莓派 armv6l Bullseye tar.gz、Windows 安装器 ×3、Android APK

结论：Linux x86_64 没有官方预编译包，源码编译是唯一官方路径（Alpine/FreeBSD 有社区软件源包，不在本文范围）。本文选择 v0.2-alpha0——它是最新 Release，也是官方主推的开发线。编译与运行链路如下：

NymphRPC（RPC 库） → LibNymphCast（客户端协议库） → nymphcast_server / nymphcast_client

服务端与 CLI 客户端都依赖前两个库，必须先装库再编应用。

四、方案 A：官方脚本自动化安装（setup.sh + install_linux.sh）

4.1 方案说明

官方提供两个脚本完成"依赖安装 → 依赖库编译 → 应用编译 → 安装部署"全自动流程：

setup.sh：装系统依赖、clone 并编译安装 NymphRPC 与 LibNymphCast、编译服务端二进制；
install_linux.sh：检测已编译产物、执行 make install 部署、交互式询问运行形态（audio/video/screensaver/gui）并覆盖活动配置、可选安装自启动。

适合网络通畅、想一步到位的场景。

4.2 安装步骤

1. 获取源码（clone v0.2-alpha0 tag）：

git clone --depth 1 --branch v0.2-alpha0 https://github.com/MayaPosch/NymphCast.git
cd NymphCast

实测回显（节选）：

Cloning into 'NymphCast'...
remote: Enumerating objects: 6851, done.
Updating files: 100% (6851/6851), done.

确认版本：

git log --oneline -1

3f50059 Update release notes & protocol for v0.2-alpha0.

2. 运行 setup.sh（依赖已在二、前置条件装好的情况下，脚本会补装 NymphRPC/LibNymphCast 并编译服务端）：

sh setup.sh

实测日志关键行（输出节选，实测首尾）：

UPDATE: 
PACKAGE: 
Linux
Installing NymphRPC...
Installing LibNymphCast...
（中略：两个依赖库与 server 的完整编译输出）

结束后核对产物：

ls -la src/server/bin/x86_64-linux-gnu/nymphcast_server

-rwxr-xr-x 1 root root 5705360 Oct 29 15:32 src/server/bin/x86_64-linux-gnu/nymphcast_server

3. 运行 install_linux.sh 部署（交互式：第一问输入运行形态 audio，第二问输入 N 跳过自启动——自启动由本文七、的 systemd 用户服务承接）：

printf 'audio\nN\n' | sh install_linux.sh

实测回显（节选）：

Detected Linux system. Proceeding with installation...
NymphCast Server binary found, skipping compilation...
TARGET: x86_64-linux-gnu
install -d /usr/local/bin/ \
	-d /usr/local/etc/nymphcast/ \
	-d /usr/local/share/nymphcast/apps/ \
	-d /usr/local/share/nymphcast/wallpapers/ \
	-d /usr/local/etc/avahi/services/
install -m 755 bin/x86_64-linux-gnu/nymphcast_server /usr/local/bin/
install -m 644 *.ini /usr/local/etc/nymphcast/
cp -r apps/* /usr/local/share/nymphcast/apps/
chmod --recursive a+X /usr/local/share/nymphcast/apps/

验证"audio"选择已覆盖活动配置（实测 diff 一致）：

diff /usr/local/etc/nymphcast/nymphcast_config.ini src/server/nymphcast_audio_config.ini && echo '活动配置已切换为 audio 形态'

活动配置已切换为 audio 形态

4.3 实测排障：setup.sh 静默失败陷阱

实测在未配置代理的网络里运行 setup.sh，出现连锁失败：

Cloning into 'NymphRPC'...
fatal: unable to access 'https://github.com/MayaPosch/NymphRPC.git/': Recv failure: Connection reset by peer
Installing NymphRPC...
make: *** NymphRPC/: No such file or directory.  Stop.
（后略）
ffplay/ffplay.h:32:10: fatal error: nymph/nymph.h: No such file or directory
make: *** [Makefile:210: obj/x86_64-linux-gnu/NymphCastServer.o] Error 1

排查结论（实测确认的两个事实）：

setup.sh 内部 clone NymphRPC/LibNymphCast 不继承部分代理配置场景（clone 直连被重置），且 clone 失败后脚本不中断，make -C NymphRPC/ 找不到目录、依赖库缺失，最终 server 编译报 nymph/nymph.h 缺失；
脚本退出码失真：全程失败但 echo $? 仍为 0（SETUP_RC=0），不能靠退出码判断成败。

处置方法：确保网络可达 GitHub（或先按五、手动方案装好两个依赖库——setup.sh 检测到 /usr/lib/libnymphrpc.so、/usr/lib/libnymphcast.so 存在时会打印 Skipping installation. 跳过克隆），重跑后以"是否产出 src/server/bin/x86_64-linux-gnu/nymphcast_server"为成败判据。

五、方案 B：手动分步编译安装

5.1 方案说明

把官方脚本做的事拆成三步手工执行：编译安装 NymphRPC → 编译安装 LibNymphCast → 编译安装 server/client。适合需要控制安装细节、或在脚本失败后接管的场景。本方案与方案 A 产物完全一致，二选一即可。

5.2 编译安装 NymphRPC

cd /root
git clone --depth 1 https://github.com/MayaPosch/NymphRPC.git
cd NymphRPC
make lib
make install

make lib 实测收尾（链接共享库）：

g++ -o lib/x86_64-linux-gnu/libnymphrpc.so.0.1 -I src  -g3 -std=c++17 -O0 -DPOCO_NO_AUTOMATIC_LIB_INIT -fext-numeric-literals -fPIC -shared -Wl,-soname,libnymphrpc.so.0.1 obj/shared/x86_64-linux-gnu/src/callback_request.o …（中略：11 个目标文件）… obj/shared/x86_64-linux-gnu/src/worker.o -lPocoNet -lPocoUtil -lPocoFoundation -lPocoJSON  -pthread

make install 实测收尾：

cd /usr/lib && \
	if [ -f libnymphrpc.so ]; then \
		rm libnymphrpc.so; \
	fi && \
	ln -s libnymphrpc.so.0.1 libnymphrpc.so

验证（头文件与库就位）：

ls /usr/include/nymph/nymph.h /usr/lib/libnymphrpc.so.0.1

/usr/include/nymph/nymph.h
/usr/lib/libnymphrpc.so.0.1

5.3 编译安装 LibNymphCast

cd /root
git clone --depth 1 https://github.com/MayaPosch/libnymphcast.git
cd libnymphcast
make
make install

make 实测收尾：

g++ -o lib/x86_64-linux-gnu/libnymphcast.so.0.2 -I src -g3 -std=c++17 -O0 -DPOCO_NO_AUTOMATIC_LIB_INIT -fext-numeric-literals -fPIC -shared -Wl,-soname,libnymphcast.so.0.2 obj/shared/x86_64-linux-gnu/src/bytebauble.o obj/shared/x86_64-linux-gnu/src/nyansd.o obj/shared/x86_64-linux-gnu/src/nymphcast_client.o obj/shared/x86_64-linux-gnu/src/nymphcast_client_c.o -lnymphrpc -lPocoNet -lPocoUtil -lPocoFoundation -lPocoJSON

5.4 编译安装服务端

cd /root/NymphCast    # 方案 A 已 clone 的源码；纯手动路径同样从 clone 开始
cd src/server
make -j4
make install

make -j4 实测最终链接命令（节选，完整命令极长）：

g++ -o bin/x86_64-linux-gnu/nymphcast_server obj/x86_64-linux-gnu/NymphCastServer.o …（中略：GUI/ffplay/AngelScript/LCDapi 等 200 余个目标文件）… -lnymphrpc -lnymphcast -lPocoUtil -lPocoNet -lPocoNetSSL -lPocoJSON -lPocoData -lPocoDataSQLite -lPocoFoundation -lswscale -lavcodec -lavdevice -lavformat -lavutil -lswresample -lavfilter -lSDL2_image -Langelscript/angelscript/lib-x86_64-linux-gnu -langelscript -lfreetype -lcurl -lfreeimage -lstdc++fs `pkg-config --libs freetype2` `sdl2-config --libs` -pthread -latomic -lGL -lasound
strip -S --strip-unneeded bin/x86_64-linux-gnu/nymphcast_server

make install 实测回显：

TARGET: x86_64-linux-gnu
install -d /usr/local/bin/ \
	-d /usr/local/etc/nymphcast/ \
	-d /usr/local/share/nymphcast/apps/ \
	-d /usr/local/share/nymphcast/wallpapers/ \
	-d /usr/local/etc/avahi/services/
install -m 755 bin/x86_64-linux-gnu/nymphcast_server /usr/local/bin/
install -m 644 *.ini /usr/local/etc/nymphcast/
cp -r apps/* /usr/local/share/nymphcast/apps/
chmod --recursive a+X /usr/local/share/nymphcast/apps/
install -m 644 wallpapers/*.jpg /usr/local/share/nymphcast/wallpapers/

5.5 部署 systemd 服务文件

make install-systemd

实测回显：

TARGET: x86_64-linux-gnu
sed -e 's:@BIN@:/usr/local/bin/nymphcast_server:g' -e 's:@CONFIG@:/usr/local/etc/nymphcast/nymphcast_config.ini:g' -e 's:@APPS@:/usr/local/share/nymphcast/apps/:g' -e 's:@WALLPAPERS@:/usr/local/share/nymphcast/wallpapers/:g' systemd/nymphcast.service > /etc/systemd/user/nymphcast.service

服务文件内容（实测 cat /etc/systemd/user/nymphcast.service）：

[Unit]
Description=NymphCast audio/video casting server

[Service]
ExecStart=/usr/local/bin/nymphcast_server -c /usr/local/etc/nymphcast/nymphcast_config.ini -a /usr/local/share/nymphcast/apps/ -w /usr/local/share/nymphcast/wallpapers/
Restart=always
RestartSec=5

[Install]
WantedBy=default.target

要点：这是一个 systemd 用户级服务（/etc/systemd/user/ + WantedBy=default.target），由每个用户的 systemd 用户实例管理，无 root 常驻；Restart=always 崩溃 5 秒后自动拉起。

5.6 编译安装 CLI 客户端

客户端在 src/client，产物为 nymphcast_client（Makefile 无 install 目标，手动复制）：

cd /root/NymphCast/src/client
make
cp bin/nymphcast_client /usr/local/bin/

make 实测收尾：

g++ -o bin/nymphcast_client obj/NymphCastClient.o obj/sarge.o -lnymphcast -lnymphrpc -lPocoNet -lPocoUtil -lPocoFoundation -lPocoJSON -lstdc++fs

六、方案对比与选择建议

维度	方案 A（官方脚本）	方案 B（手动分步）
命令量	3 条（clone + setup.sh + install_linux.sh）	10 余条，逐步可控
依赖库处理	脚本自动 clone/编译/安装	手动逐库执行，可复用已装库
失败可见性	低（失败不中断、退出码失真，见 4.3）	高（每步独立验证）
交互	install_linux.sh 两问（形态/自启动）	无交互，形态自选复制配置
适用	网络通畅、快速部署	内网受限、脚本失败接管、需要定制安装路径

选择建议：首次安装、网络可达 GitHub 时用方案 A；内网隔离机器（先把三个仓库离线搬入）、或 setup.sh 因 clone 失败翻车的环境用方案 B——它也是理解 NymphCast 三层编译依赖的最短路径。

七、systemd 服务托管

使用 make install-systemd 部署的用户服务托管接收端（服务文件见 5.5）：

systemctl --user daemon-reload
systemctl --user enable nymphcast
systemctl --user start nymphcast

enable 实测回显：

Created symlink /root/.config/systemd/user/default.target.wants/nymphcast.service → /etc/xdg/systemd/user/nymphcast.service.

状态验证（实测）：

systemctl --user --no-pager status nymphcast

● nymphcast.service - NymphCast audio/video casting server
     Loaded: loaded (/etc/xdg/systemd/user/nymphcast.service; enabled; preset: enabled)
     Active: active (running) since Thu 2026-10-29 15:06:18 UTC; 3s ago
   Main PID: 3960 (nymphcast_serve)
      Tasks: 8 (limit: 2506)
     Memory: 15.1M (peak: 16.0M)
        CPU: 50ms
     CGroup: /system.slice/…/user@0.service/app.slice/nymphcast.service

⚠️ 前置要求：systemctl --user 需要 systemd 用户管理器（systemd 真机）。root 场景先执行 loginctl enable-linger root 让用户实例常驻，否则用户服务只在登录会话内存活。无声卡机器还需给服务环境注入 SDL 哑音频驱动：systemctl --user set-environment SDL_AUDIODRIVER=dummy（详见十、Q2）。

常用管理命令（每行一个单元）：

systemctl --user stop nymphcast       # 停止
systemctl --user restart nymphcast    # 重启（改配置后必做）
systemctl --user disable nymphcast    # 取消自启动
journalctl --user -u nymphcast --no-pager -n 20    # 查看最近 20 行服务日志

八、安装验证

1. 版本验证（实测）：

nymphcast_server --version
nymphcast_client --version

Detected Host Little Endian.
Dispatcher: Setting max pool size to 10 workers.
NymphCast version: v0.2-alpha0.20241108

Detected Host Little Endian.
Dispatcher: Setting max pool size to 10 workers.
NymphCast client version: v0.1-release.20220408

（客户端版本串停留在 v0.1-release.20220408 属上游现状——v0.2-alpha0 源码树未更新 src/client/version.mk，以服务端版本串为准。）

2. 安装产物核对（实测）：

ls /usr/local/bin/nymphcast* && ls /usr/local/etc/nymphcast/ && ls /usr/local/share/nymphcast/apps/

/usr/local/bin/nymphcast_client
/usr/local/bin/nymphcast_server
nymphcast_audio_config.ini
nymphcast_config.ini
nymphcast_gui_config.ini
nymphcast_screensaver_config.ini
nymphcast_video_config.ini
apps.html
apps.ini
hellocast
soundcloud

3. 端到端推流验证：启动接收端后，用 ffmpeg 生成 30 秒测试音频并从本机推流（同机验证 -i 用默认 127.0.0.1；跨机见《NymphCast 0.2-alpha0 常用 CLI 命令与工具详解》）：

export SDL_AUDIODRIVER=dummy    # 无声卡环境；接音箱的真机去掉这行
nymphcast_server -c /usr/local/etc/nymphcast/nymphcast_audio_config.ini \
  -a /usr/local/share/nymphcast/apps/ -w /usr/local/share/nymphcast/wallpapers/ &
sleep 3
ffmpeg -y -f lavfi -i 'sine=frequency=440:duration=30' -acodec pcm_s16le -ar 44100 -ac 2 /root/test_tone.wav
nymphcast_client -f /root/test_tone.wav

推流实测回显（节选，实测首尾）：

Opening file /root/test_tone.wav
Press Ctrl+c to quit.
（播放约 30 秒）
Shutting down client...

客户端随播放结束自动退出（约 30 秒后），接收端日志出现 Found audio stream: 0. 与 SetDuration. 30 即链路全通：

Format WAV / WAVE (Waveform Audio), duration -9223372036854775808 usInput #0, wav, from '':
  Duration: 00:00:30.00, bitrate: 1411 kb/s
  Stream #0:0: Audio: pcm_s16le ([1][0][0][0] / 0x0001), 44100 Hz, 2 channels, s16, 1411 kb/s
Finding audio stream...
Found audio stream: 0.
A: 0, V: -1, S: -1
SetDuration. 30

九、配置说明

安装后 5 个 INI 配置文件与"活动配置"机制（nymphcast_config.ini 为 systemd 服务实际加载的文件，换形态即把对应 profile 覆盖到它）：

cp /usr/local/etc/nymphcast/nymphcast_video_config.ini /usr/local/etc/nymphcast/nymphcast_config.ini   # 例：切换为音视频接收形态
systemctl --user restart nymphcast

9 个参数（fullscreen/disable_video/enable_gui/buffer_size/enable_lcdproc 等）的逐项含义、默认值与实测行为见《NymphCast 0.2-alpha0 配置参数详解》。接收端还监听 UDP+TCP 4004（发现与会话推流），如启用了 Avahi 可用 src/server/avahi/install.sh 注册 _nymphcast._tcp 服务（部署到 /usr/local/etc/avahi/services/，防火墙需放行对应端口）。

十、常见问题

Q1：Ubuntu 22.04 上编译报 'AVChannelLayout' does not name a type？

实测报错原文：

ffplay/types.h:119:5: error: 'AVChannelLayout' does not name a type; did you mean 'AVFilterChannelLayouts'?
  119 |     AVChannelLayout ch_layout;
make: *** [Makefile:210: obj/x86_64-linux-gnu/NymphCastServer.o] Error 1

定位：v0.2-alpha0 的播放内核基于 FFmpeg 5.1+ 的 AVChannelLayout API（官方依赖清单明确要求 ffmpeg v5.1+），Ubuntu 22.04 的 FFmpeg 为 4.4（libavcodec 58）无此类型。解决：换 Ubuntu 24.04（FFmpeg 6.1，本文实测通过）或 Debian 13+；坚持 22.04 需自行编译新版 FFmpeg 后再编 NymphCast，成本高于升级系统。

Q2：无声卡服务器上接收端起不来或推流无声？

NymphCast 经 SDL2 输出音频，机器无音频设备时需启用 SDL 哑音频驱动：

export SDL_AUDIODRIVER=dummy   # 前台启动前执行
# systemd 托管则注入用户服务环境：
systemctl --user set-environment SDL_AUDIODRIVER=dummy && systemctl --user restart nymphcast

该模式下推流、解码、状态回调全部正常（本文全部验证即在此模式完成），只是不出声；接音箱的真机不要设置，让 SDL 直接走 ALSA/PulseAudio。

Q3：systemd 服务反复重启（status=127 / status=1）？

实测两类原因与定位方法：

status=127：动态库缺失。ldd /usr/local/bin/nymphcast_server | grep 'not found' 列出缺失项——除 apt 装的运行库外，libnymphrpc.so.0.1、libnymphcast.so.0.2 是自编译库（位于 /usr/lib/），换机部署时容易漏带；补齐后 ldconfig 再重启。
status=1：启动期错误（如 -a/-w 指向的 apps/wallpapers 目录缺失，日志报 Failed to parse the 'apps/apps.ini' file.）。用 journalctl --user -u nymphcast -n 20 看具体报错，补齐目录或修正服务文件路径。

Q4：第二个客户端推流被拒？

接收端同一时刻只允许一个投送会话，第二个客户端报 Failed to cast file ... to server ...，接收端日志出现：

2 - 10463.3	NymphCastServer	1013	Trying to start a new session with session already active. Abort.		- NymphCastServer.cpp

等当前会话客户端正常退出后即可再推（实测连续推流成功）；会话卡死时 systemctl --user restart nymphcast 释放。

Q5：setup.sh 全部报错但 $? 为 0？

脚本缺陷：内部 clone 失败不中断、不回传错误码（实录见 4.3）。判成败只认产物文件与 nymphcast_server --version 回显；内网环境直接走方案 B。

十一、卸载与清理

官方提供 uninstall_linux.sh（根目录，官方自注 experimental），实测在 systemd 机器上执行 systemctl --user disable 并删除服务文件后，由 make uninstall 移除安装产物；实测回显（在无 systemd 的环境会走 OpenRC 分支并报一条 rm: cannot remove '/usr/local/etc/init.d/nymphcast': No such file or directory，可忽略，继续完成清理）：

rm -r /usr/local/share/nymphcast/
rm -r /usr/local/etc/nymphcast/
rm /usr/local/bin/nymphcast_server
Uninstalling NymphCast complete.

注意：该脚本不清以下三项，需手动补删（实测核对）：

rm -f /usr/local/bin/nymphcast_client                  # CLI 客户端（手动 cp 的，脚本不管）
rm -rf /usr/lib/libnymphrpc.so* /usr/lib/libnymphcast.so* /usr/include/nymph   # 两个依赖库
rm -rf /root/NymphCast /root/NymphRPC /root/libnymphcast                      # 源码目录（按实际路径）

清理后核对无残留：

ls /usr/local/bin/nymphcast* /usr/local/etc/nymphcast 2>&1

ls: cannot access '/usr/local/bin/nymphcast*': No such file or directory
ls: cannot access '/usr/local/etc/nymphcast': No such file or directory

十二、参考链接

官方服务端编译文档：https://github.com/MayaPosch/NymphCast/blob/master/doc/building_nymphcast_server.md
官方仓库与 README：https://github.com/MayaPosch/NymphCast
Releases 页（版本与预编译资产，查询日期 2026-10-29）：https://github.com/MayaPosch/NymphCast/releases
NymphRPC 仓库：https://github.com/MayaPosch/NymphRPC
LibNymphCast 仓库：https://github.com/MayaPosch/libnymphcast
站内实操篇：《NymphCast 0.2-alpha0 配置参数详解》（INI 参数全解）、《NymphCast 0.2-alpha0 常用 CLI 命令与工具详解》（推流与服务管理命令）、《NymphCast 介绍与选型指南》（架构、生态与选型）