飞牛OS 手动安装 fpk 教程：把商店没有的第三方应用装进应用中心
摘要
不依赖应用中心上架，飞牛 fnOS 也能把第三方 .fpk 应用装进系统。拆解 fpk 包结构与安装钩子机制，并用 OpenSurge 实机演示从上传、安全确认、参数向导到运行的全流程。
飞牛OS 手动安装 fpk 教程：把商店没有的第三方应用装进 fnOS 应用中心
飞牛OS（fnOS）的应用中心收录速度很快，但再快也架不住第三方开发者的小众需求——很多好用的 NAS 应用根本没上架，开发者只提供一个 .fpk 安装包。这篇就把「手动导入安装」这条路径彻底讲透：fpk 包里到底装了什么、应用中心点下「安装」后系统做了哪些事、装完之后的数据落在哪里、升级卸载怎么处理才不丢配置。
全文以 OpenSurge fnOS 版 v0.1.1 为实例。它是一款旁路由透明代理网关（mihomo + dnsmasq + nftables，Docker 交付），没有上架飞牛应用中心，只能手动导入；而它的安装包恰好把飞牛的 fpk 机制用得非常完整——参数向导、生命周期钩子、图标同步一样不缺，拿来做教学标本正合适。文中所有界面截图与路径均来自一台真实的 fnOS 机器。
一、fpk 到底是什么
把 .fpk 的扩展名去掉，它就是一个普通的 tar.gz。解开 OpenSurge 的安装包，结构一目了然：
manifest 是整个包的身份证，OpenSurge 的原文如下：
这些字段会原样出现在应用中心的应用详情页里：开发者读的是 maintainer，当前版本读的是 version，来源里的「手动安装」对应 source = thirdparty，应用介绍就是 desc 全文。也就是说，你看到的详情页不是商店后台填的，而是包作者在 manifest 里写死的。
两个值得留意的字段：
platform：x86或arm，决定该下哪个包，装错了会直接失败；source = thirdparty：第三方来源，这正是后面飞牛弹「未经验证应用」安全提示的原因。
二、装之前：确认三件事
1. NAS 的 CPU 架构。 Intel / AMD（N100、N305 这类最常见）选 x86 包；瑞芯微等 ARM64 机型选 arm 包。不确定的话 SSH 上去敲一句 uname -m，x86_64 对应 x86 包，aarch64 对应 arm 包。
2. 从哪里下载。 认准项目的 GitHub Releases 页，不要用论坛转载的来路不明的包。OpenSurge 的发布页在 github.com/funchs/opensurge-fnos/releases/latest，当前版本 0.1.1 提供 x86 / arm 两个包。GitHub 下载慢的话，可以在直链前面加 https://gh-proxy.com/ 前缀加速，实测能从十几 KB/s 提到两百多 KB/s。
3. 应用对网络和权限的要求。 这一步容易被忽略：fpk 只是壳，应用本体可能是 Docker 容器。OpenSurge 的 compose 里声明了 network_mode: host、三个容器能力（NET_ADMIN、NET_RAW、SYS_ADMIN）和 /dev/net/tun 设备映射——它是真网关，要看真实网卡、要建 TUN 设备。装这类应用前，确认镜像能拉下来（拉不动见文末离线方案）、存储空间够用。
三、手动安装全流程（实机演示）
第 1 步：打开应用中心的「手动安装」
应用中心左侧栏最底部就是「手动安装」入口。点开后先选安装位置（存储空间），再选 fpk 来源：从电脑上传，或者 fpk 已经在 NAS 里时用从 NAS 添加。
第 2 步：通过「未经验证应用」安全确认
fpk 上传解析完成后，会先弹一道安全提示：「OpenSurge 由未知发布者提供，未经飞牛验证……」。
这不是安装出错，而是 source = thirdparty 触发的固定流程——飞牛商店的官方应用不弹这个。对第三方包来说，这道提示的意义是让你自己确认包的来路：从项目官方 Release 下载、核对好版本，再点「同意」。
第 3 步：填写安装向导
点同意后进入参数向导。这一步是 fpk 机制里最值得说的设计：向导表单不是写死的界面，而是包作者在 wizard/install 里用 JSON 声明的。OpenSurge 定义了三个字段：
向导字段 | 默认值 | 什么时候要改 |
|---|---|---|
Web GUI 端口 |
| 端口被占用时换一个（100–65535） |
网关网卡名 |
| 多网卡机器想指定某块网卡时填，如 |
NAS 局域网 IPv4 |
| NAS 有多个 IP、或想固定写死时填 |
关键在默认值的语义：向导里的 eth0 和 192.168.1.20 是占位符，不是让你照抄的推荐值。保持不动，安装钩子会在后台自动探测——优先走 NetworkManager（和飞牛「系统设置 → 网络设置」同源数据），查不到再退回内核路由表，探测结果直接写进应用配置。在你改过的机器上，则以你填写的值为准。
这台实测的飞牛机器上，网卡实际叫 enp1s0、IP 是 192.168.31.97，向导全部保持默认，装完落盘的 config.yaml 是：
所以结论很简单：单网卡的普通用户，向导三个字段全部不用动，直接下一步。
第 4 步：安装完成，确认应用状态
安装完成后，应用出现在「已安装」列表里。
点开应用详情页，可以看到 manifest 里的信息被完整呈现：开发者 funchs、来源手动安装、版本 0.1.1、安装位置存储空间2。
同时飞牛桌面会出现应用图标。OpenSurge 的桌面图标走的是外链方式：点击后用浏览器打开 http://<NAS-IP>:61767/enter，而不是内嵌窗口面板——因为它的控制台需要签发 session cookie，必须走完整浏览器会话。
一个真实行为：同版本装不上去
对着已装好的 0.1.1 再次导入同一个 fpk，飞牛会直接拒绝：「无法安装 OpenSurge——已安装相同或更高版本」。
这决定了 fpk 的升级逻辑：没有「检查更新」按钮，升级就是拿更高版本号的 fpk 再走一遍手动安装。数据目录在升级时会保留，后文详述。
四、点下「安装」之后，系统做了什么
向导提交后，飞牛按顺序执行包里 cmd/ 目录的生命周期脚本。以 OpenSurge 为例，安装收尾阶段做了四件事，每一件都值得普通用户知道：
1. 种子化配置文件。 把包内自带的 config.fnos.example.yaml 复制到数据目录作为 config.yaml，并把向导里探测/填写的网卡名和 IP 写进去。已有配置不会覆盖——这条规则对升级同样生效，你的手工改动不会被安装包冲掉。
2. 改写 compose 的监听端口。 包内的 compose 模板里端口是个占位变量，安装钩子把它替换成你在向导里填的值：
这也是 host 网络应用的通用做法：network_mode: host 下 ports: 映射是无效的，端口只能由应用自己监听。
3. 同步图标。 把包根目录的 ICON.PNG / ICON_256.PNG 推送到各个安装根目录，顺手清掉前端的应用图标缓存——飞牛应用中心列表偶发的「装了新版图标还是旧的」就靠这一步修复，顽固时浏览器强制刷新或开无痕窗口即可。
4. 建立目录布局。 这是排查问题最常用的部分，以这台机器（安装在存储空间2）为例：
内容 | 实机路径 |
|---|---|
安装根（compose、ui、图标） |
|
数据目录（config、state） |
|
应用配置 |
|
运行状态与日志 |
|
统一入口（符号链接聚合） |
|
/var/apps/opensurge 是一组软链接：var 指向 @appdata、target 指向 @appcenter……飞牛用这种方式把「按卷存放的真实数据」聚合成稳定路径。记住规律即可：装在哪个存储空间，数据就在哪个卷的 @appdata 下。
之后容器按 compose 拉起。docker ps 里能看到 opensurge，docker inspect 确认它带着 NET_ADMIN/NET_RAW/SYS_ADMIN 三个能力和 /dev/net/tun 设备，重启策略 unless-stopped——开机自启、崩溃自动拉起，无需额外配置。
五、装完之后：以 OpenSurge 为例说两句用法
浏览器打开 http://<NAS-IP>:61767/enter 进入控制台。首次进入建议认准 /enter 这个入口，它会校验访问地址并签发登录会话；直接访问根路径偶尔会提示「安全连接已过期」，换成 /enter 或无痕窗口即可。
控制台共七个页面：总览、网络设置、代理与规则源、设备、策略、连通性、诊断。代理订阅在「代理与规则源」导入，导入时只生成草稿，校验通过后才切换运行配置，不会一上来就动正在跑的网关。
OpenSurge 默认以旁路由方式工作：需要走代理的设备，把网关和 DNS 都指到 NAS 的 IP即可，不用动主路由的 DHCP 设置。想全屋接管，在「网络设置」里切换 DHCP 接管模式，那是进阶玩法。
出问题先看「诊断」页：dnsmasq、mihomo、配置校验、网卡绑定、LAN IP 一列绿勾表示基础链路正常，再结合容器日志定位。
最后是安全边界：61767 端口在局域网内是明文 HTTP，不要把它端口转发到公网。外网访问优先走飞牛 FN Connect（地址形如 https://opensurge.<你的FNID>.fnos.net/，控制面会自动放行该域名）或带 TLS 的反向代理。
六、升级、卸载与数据保留
升级。 拿更高版本号的 fpk 重新走一遍手动安装。升级时 app.tgz 会重新解包（compose 恢复成模板），但安装钩子会读回上次保存的端口和网卡设置重新写好；config.yaml 因为「已存在不覆盖」规则而原样保留，订阅和运行状态都在数据目录里，不受影响。若容器镜像同时有更新，再手动 docker pull 一次对应 tag 后重启应用。
卸载。 应用中心卸载时会弹一个选择：「保留现有文件（便于重新安装后恢复）」或「清除所有数据文件（不可恢复）」。默认保留——日后重装，配置和订阅原样回来。确认不再用了再勾清除，注意清除后不可恢复。
重复安装报错。 见上文：同版本或更低版本会被拒绝，这不是故障。
镜像拉不动。 NAS 访问 ghcr.io 困难时，在有外网的机器上 docker pull --platform linux/amd64 ghcr.io/funchs/opensurge-fnos:v0.1.1，docker save 成 tar 传到 NAS 后 docker load 导入，再启动应用即可。另外 OpenSurge 的 compose 里镜像名写作 ${DOCKER_MIRROR}ghcr.io/...，作者预留了镜像加速前缀变量，有自建加速的用户可以直接利用。
写在最后
手动安装 fpk 的门槛，其实只有「确认架构 → 找对下载源 → 看懂向导」三步。真正值得记住的是三件事：
向导里的默认值可能是占位符，保持不动往往比照着填更安全——安装钩子的自动探测和飞牛网络设置同源，比手填准；
配置只增不毁——安装和升级都不会覆盖已存在的
config.yaml，数据目录独立于安装目录，卸载默认保留；第三方包的安全确认要自己把关——「未经飞牛验证」提示不是形式主义，认准项目官方 Release 再点同意。
至于 OpenSurge 本身，把 mihomo 的透明代理能力做成了完整的飞牛应用：参数向导、生命周期钩子、图标缓存修复脚本一应俱全，x86 与 ARM 双架构，ghcr 镜像公开无需登录。项目地址 github.com/funchs/opensurge-fnos，许可证 GPL-3.0，装好后在 GUI 里导入订阅就能用。