企业官网建设流程全解析

• 桌面应用
• 音视频
• 前端

Feishin 是一款基于 Electron 的现代自托管音乐播放器，本文围绕其在当前仓库（gh_mirrors/fe/feishin）中的完整部署链路展开：从桌面客户端、AppImage、Docker 三种安装方式，到 MPV/Web 播放器后端与 Navidrome、Jellyfin、OpenSubsonic 服务器的接入配置，再到SERVER_*、REMOTE_URL、PUBLIC_PATH、FS_等环境变量的深度用法与源码级原理。读完本文，你将能够独立完成 Feishin 的安装、服务器接入、批量预设配置与常见故障排查。

项目概览与核心特性

Feishin 是开源项目 Sonixd 的完全重写版本（README 中明确标注"Rewrite of Sonixd"），定位是一个面向自托管音乐服务的前端播放器。它本身不托管音乐，而是作为"播放器客户端"对接你自建的 Navidrome、Jellyfin 或任何兼容 OpenSubsonic 协议的服务器，把浏览、搜索、播放、歌词、智能歌单等功能统一到一个现代界面中。

README 列出的核心特性包括：

从 package.json 的依赖声明可以看到其技术底座：Electron 43 + React 19 + Vite（electron-vite）构建，UI 使用 Mantine 9，状态管理采用 zustand，服务端数据缓存使用 TanStack React Query，并集成了node-mpv、mpris-service（Linux 媒体键）、discord-rpc、butterchurn（可视化）等能力。

在源码结构上，src/renderer/api 目录下并列存在jellyfin/、navidrome/、subsonic/三套 API 实现，并通过统一的 controller.ts 对外暴露，从实现层面印证了"一套播放器、三类服务协议"的架构设计。

安装与部署

桌面客户端（推荐方式）

桌面客户端是官方推荐的使用方式：下载最新版桌面安装包后即可使用，它同时支持 MPV 与 Web 两种播放器后端，且内置了歌词获取能力（Web 版无内置歌词抓取）。

macOS 注意事项

• 如果你运行的是 macOS 12（Monterey）或更高版本，首次打开时需要先解除应用的隔离（quarantine）限制，否则应用会被系统拦截无法启动；
• 为了让媒体键（媒体播放/暂停键）生效，系统会提示允许 Feishin 成为Trusted Accessibility Client（受信任的辅助功能客户端）。授权后需要重启 Feishin，隐私设置才会真正生效。

Linux 注意事项

Feishin 已发布到 Flathub，Linux 用户可以直接通过 Flatpak 渠道安装。

此外，仓库提供了一条轻量级安装路径：根目录下的 install-feishin-appimage 脚本。它负责下载最新.AppImage、赋予执行权限、下载桌面环境所需的图标，并生成.desktop文件将 Feishin 加入应用启动器。从仓库检出该脚本后，用法如下：

# 基本安装：将 AppImage 安装到指定应用目录 dir=/your/application/directory sh install-feishin-appimage "$dir"

脚本支持两个可选参数：

# 以原生 Wayland 模式运行（Electron 中属于实验特性，非官方支持） sh install-feishin-appimage "$dir" wayland-native # 卸载：删除下载的 AppImage、图标与 desktop 条目 sh install-feishin-appimage "$dir" remove

从脚本源码（install-feishin-appimage）可以确认几个实现细节：

• 仅支持x86_64与aarch64架构（aarch64 会被映射为 arm64 产物名）；
• wayland-native模式会附加--enable-features=UseOzonePlatform,WaylandWindowDecorations --ozone-platform-hint=auto启动参数；
• 脚本会自动探测sysctl kernel.unprivileged_userns_clone与kernel.userns_restrict，若非特权用户命名空间被禁用，则自动追加--no-sandbox标志；
• 图标安装到$XDG_DATA_HOME/icons/hicolor/{32,64,128,256,512}x512/apps/，desktop 文件由 feishin.desktop.tmpl 模板经envsubst渲染生成。

安装完成后条目应立刻出现在应用启动器中；如果没有，注销并重新登录（等待约 10 秒），或使用桌面环境提供的重载入口功能。

Web 版本与 Docker

Feishin 提供在线托管的 Web 版本（Web 客户端仅支持 Web 播放器后端），同时也发布官方 Docker 镜像（托管于ghcr.io的ghcr.io/jeffvli/feishin，标签包括latest）。基础运行命令：

# 运行最新版本，映射 9180 端口 docker run --name feishin -p 9180:9180 ghcr.io/jeffvli/feishin:latest # 或基于仓库本地构建 docker build -t feishin . docker run --name feishin -p 9180:9180 feishin

从 Dockerfile 可以看到镜像的构建思路：使用 Node 23 镜像执行pnpm run build:web构建纯前端产物，再以nginxinc/nginx-unprivileged:alpine-slim（非 root 运行）作为运行时，通过 nginx 模板（ng.conf.template）渲染出settings.js与站点配置，最终对外暴露9180端口。

Docker Compose 安装

README 提供了可直接使用的 Compose 片段，同样适用于 Portainer：

services: feishin: container_name: feishin image: 'ghcr.io/jeffvli/feishin:latest' restart: unless-stopped environment: - SERVER_NAME=jellyfin # pre-defined server name - SERVER_LOCK=true # When true AND name/type/url are set, only username/password can be toggled - SERVER_TYPE=jellyfin # the allowed types are: jellyfin, navidrome, subsonic. These values are case insensitive - SERVER_URL= # http://address:port or https://address:port - REMOTE_URL= # http://address or https://address - LEGACY_AUTHENTICATION=false # When SERVER_LOCK is true, sets the legacy (plaintext) authentication flag for Subsonic/OpenSubsonic servers - ANALYTICS_DISABLED=true # Set to true to disable Umami analytics tracking ports: - 9180:9180 # Alternatively, to restrict to only localhost, - 127.0.0.1:9180:8190

仓库内的 docker-compose.yaml 提供了另一个带示例值（SERVER_URL=http://localhost:8096）的参考版本。若要只允许本机访问，可将端口映射改为127.0.0.1:9180:9180。

初始配置：连接你的音乐服务器

第一步：配置 MPV 播放器路径

首次启动会弹出提示，要求选择 MPV 二进制的路径。如果你尚未安装 MPV，可以前往 mpv.io 的安装说明下载，或使用系统包管理器安装。填入路径后需要重启应用。

FAQ 补充了一个关键经验：MPV 不可用或播放状态快速在暂停/播放之间切换时，先在设置页重新设置 MPV 路径并重启；仍未解决则重装 MPV。已知可用的版本为v0.35.x与v0.36.x，而v0.34.x是已知有问题的版本。

第二步：添加服务器

重启后应用会提示选择服务器。点击Open menu按钮 →Manage servers→ 在弹窗中点击Add server，填写所有适用信息。必须输入服务器的完整 URL，包含协议与端口，例如：

https://navidrome.my-server.com http://192.168.0.1:4533

针对不同服务器的实操建议：

• Navidrome：创建服务器时建议勾选 "Save password"，并在 Navidrome 服务端配置中把SessionTimeout调大（例如 72 小时），以获得最佳体验；
• Linux 用户：默认的密码存储使用libsecret。kwallet4/5/6同样受支持，但必须显式在 设置 > Window > Passwords/secret store 中切换。

登录页面的实现（src/renderer/features/login/routes/login-route.tsx）显示：当通过环境变量预设服务器后，登录表单只保留用户名/密码（Jellyfin 还支持 Quick Connect），服务名、类型、URL 等字段均从window.SERVER_*读取且不可编辑。

支持的服务器生态

Feishin 支持任何实现了Navidrome、Jellyfin或OpenSubsonic 兼容 API的音乐服务器。README 列出了以下经过验证的兼容实现：

• Navidrome
• Jellyfin
• OpenSubsonic 兼容服务器：Airsonic-Advanced、Ampache、Astiga、Funkwhale、Gonic、LMS、Nextcloud Music、Supysonic、Qm-Music 等
• Plex：并非原生支持，需要社区维护的 Feishin fork（由 lux032 维护）才能对接 Plex

环境变量深度配置

环境变量是 Feishin 在 Web/Docker 场景下实现"开箱即用"的关键。其注入机制为：Docker 容器内 nginx 使用 settings.js.template 模板，用环境变量值替换占位符后生成settings.js，浏览器加载后写入window对象；渲染进程再从中读取（见 src/preload/local-settings.ts 与 src/renderer/global.d.ts 的Window类型声明）。

PUBLIC_PATH：子路径托管

如果你希望把 Feishin 托管在某个子路径（而非根路径/），设置：

PUBLIC_PATH=/feishin

该值会被注入 ng.conf.template 的location ${PUBLIC_PATH}与location ${PUBLIC_PATH}/settings.js中，同时 Dockerfile 中其默认值为/。注意该变量仅对 nginx 部署形态生效。

服务器硬编码与锁定

以下四个变量组合使用，可将服务器信息直接预置到登录页，实现"仅需输入账号密码"的部署：

当SERVER_LOCK=true时，用户只能切换用户名/密码，无法修改服务器名称、类型与地址。与之配套的还有：

源码佐证：在 src/preload/local-settings.ts 中，toServerType()将字符串归一化为jellyfin/navidrome/subsonic三种类型（非法值返回null），env对象仅在SERVER_TYPE有效时才对SERVER_LOCK、LEGACY_AUTHENTICATION取值；src/renderer/features/action-required/utils/window-properties.tsx 中isServerLock()、isLegacyAuth()则对boolean | 'true'两种形态做了兼容判断。

REMOTE_URL：内外网地址分离

当你的服务器对"集成应用"使用内部通信地址、但对用户暴露了另一个公网地址时（典型场景：Navidrome 配置了独立的ShareURL），将公网地址填入：

REMOTE_URL=https://share.your-server.com

Feishin 将使用该地址作为对外分享/访问的基准，解决内外网地址不一致导致的链接失效问题。

ANALYTICS_DISABLED：关闭遥测

Docker/Web 版本默认集成 Umami 分析跟踪。设置为true后，分析脚本将完全不加载、所有跟踪被禁用：

ANALYTICS_DISABLED=true

FS_ 前缀：首次运行的设置覆盖

App 设置（主题、语言、侧边栏选项、播放行为、歌词、Auto DJ、CSS、字体等）可以在首次运行时通过FS_前缀的环境变量批量预设。这些变量经由 settings.js.template 注入，并由 src/renderer/store/env-settings-overrides.ts 中定义的ENV_SETTING_SPECS逐项解析合并进设置状态。

解析规则（源码parseValue）：

• bool 类型：接受true/1/false/0（大小写不敏感），非法值忽略；
• enum 类型：值必须命中白名单集合，例如主题名、homeFeatureStyle的multiple/single、sideQueueType的sideDrawerQueue/sideQueue等，否则忽略；
• num 类型：必须是有限数字，且部分字段带有范围裁剪（如primaryShade裁剪到 0–9、sidebarPlaylistFolderTreeIndent裁剪到 0–64、followScrollAlignment裁剪到 -50–50、歌词 padding 裁剪到 0–20）；
• string 类型：原样传入，部分字段skipIfEmpty（空串视为未设置）；
• 特殊转换：FS_GENERAL_ACCENT必须匹配rgb(r, g, b)正则；FS_PLAYBACK_FILTERS需为合法的播放器过滤器 JSON 数组（每个对象须含合法的field/operator/value）；FS_CSS_CONTENT会经过 CSS 消毒后再注入。

常见示例：

# 预设主题与语言（完整取值见 docs/ENV_SETTINGS.md） FS_GENERAL_THEME=defaultDark FS_GENERAL_LANGUAGE=de # 预设强调色（仅接受 rgb() 格式） FS_GENERAL_ACCENT=rgb(53, 116, 252) # 关闭播放 Scrobble FS_PLAYBACK_SCROBBLE_ENABLED=false # 开启 Discord Rich Presence FS_DISCORD_ENABLED=true # 注入自定义 CSS（需同时开启） FS_CSS_ENABLED=true FS_CSS_CONTENT='body { font-size: 14px; }'

完整的变量清单（覆盖 General、Playback、Discord、Lyrics、Lyrics display、Auto DJ、CSS、Font 八个分组，含默认值与取值范围）见 docs/ENV_SETTINGS.md。注意：这些FS_变量仅对Web 构建生效，且只在没有已持久化设置的首次运行时起作用。

FAQ 与故障排查

MPV 失效或快速切换暂停/播放状态

首先核对 MPV 二进制路径：进入设置页重新选择路径并重启应用。若问题依旧，重装 MPV。版本经验：v0.35.x、v0.36.x可正常工作，v0.34.x是已知的损坏版本。

Linux 下 SUID sandbox 报错

报错信息为"The SUID sandbox helper binary was found, but is not configured correctly"。原因是系统禁用了非特权用户命名空间（sysctl kernel.unprivileged_userns_clone返回 0）。两种修复方式：

1. 启用非特权命名空间；
2. 让chrome-sandbox成为 Setuid：

chmod 4755 chrome-sandbox sudo chown root:root chrome-sandbox

README 特别提醒：Ubuntu 24.04 引入了影响命名空间行为的破坏性变更，需要参考对应发行版发布说明中的安全改进部分处理。

如何添加自定义主题

桌面版支持自定义主题：将 JSON 文件放入 Themes 文件夹（设置 → General → Theme → Open Folder）即可。文件格式与示例见 docs/CUSTOM_THEMES.md。仓库内还内置了 30 余套内置主题（见 src/shared/themes 下的ayu-dark、catppuccin-mocha、dracula、tokyo-night、one-dark等目录），支持深浅色独立配置。

开发与构建

项目使用 Nodev23.11.0构建与测试，基于 electron-vite 搭建。包管理器为 pnpm（packageManager: pnpm@11.5.2）。常用命令一览：

从 package.json 的 scripts 可以看到：build实际串联build:electron与build:remote；而 Docker 镜像构建（Dockerfile）只执行build:web。发布侧则通过 electron-builder.yml 及 alpha/beta 两个变体配置管理多通道发布。

翻译贡献

项目的多语言翻译托管在 Weblate 平台（37 种语言文件见 src/i18n/locales），包括zh-Hans、zh-Hant、ja、de等，贡献者可通过 Weblate 提交翻译。

许可证

Feishin 采用 GNU General Public License v3.0 开源协议发布。

• 桌面应用
• 音视频
• 前端