在飞牛fnOS发布你的第一个第三方应用完整教程:fnos-apps从脚手架到CI自动发布实战
在飞牛fnOS发布你的第一个第三方应用完整教程:fnos-apps从脚手架到CI自动发布实战
fnos-apps 是飞牛 fnOS NAS 的第三方应用商店仓库,收录 175 款自托管应用的 .fpk 安装包(Plex、Jellyfin、Immich、qBittorrent、Vaultwarden 等),并每日自动同步上游版本。本文是一份面向新手的手把手指南:教你借助这个仓库的脚手架和 CI 流水线,从零发布自己的第一个 fnOS 第三方应用——从一条命令生成骨架,到推送后自动构建双架构安装包并发布。全程只需 Bash 基础,无需任何编译语言。
一、认识 fnos-apps:第三方应用商店是如何运作的 📦
fnos-apps 采用 monorepo + 纯 Bash 架构:每个应用只负责"下载上游官方产物 → 合并共享生命周期框架 → 打包成 .fpk",CI 每日自动检测上游新版本并发布。
它支持两种打包模式:
| 打包模式 | 适用场景 | 典型应用 |
|---|---|---|
| 原生二进制 | Go/Rust 单文件、.deb 提取、自带运行时 | qBittorrent、Memos、Syncthing |
| Docker 容器 | 依赖复杂(.NET、Python venv、多服务+数据库) | Immich、Kavita、tinyMediaManager |
整个项目的核心分工如下:
| 目录 | 职责 |
|---|---|
apps/<app>/fnos/ |
应用"身份证":manifest、启动脚本、权限、图标 |
scripts/apps/<app>/ |
构建合约:版本探测 + 下载组装逻辑 |
shared/cmd/ |
所有应用共享的生命周期框架(启停/升级/卸载) |
scripts/ |
脚手架、通用打包器、测试脚本 |
💡 核心原则:只下载并重新打包官方产物,绝不修改上游业务逻辑;所有应用默认以非 root 用户运行。
📖 深入阅读:docs/adding-new-apps.md(新增应用指南)、docs/fnos-developer-guide.md(fnOS 官方开发规范整理版)
二、发布流程全景:5 步走完整个链路 🗺️
① 克隆仓库 → ② 脚手架生成骨架 → ③ 填写应用定义+构建合约
→ ④ 本地构建 + 三层测试 → ⑤ 推送 main,CI 自动发布
无需创建任何 CI workflow 文件——CI 会自动发现 apps/ 下的新应用,这是本项目最省心的设计。
三、第一步:克隆仓库并生成应用骨架
3.1 克隆仓库
git clone https://gitcode.com/gh_mirrors/fn/fnos-apps
cd fnos-apps
3.2 一条命令生成脚手架
项目提供了 scripts/new-app.sh 脚手架工具,只需三个参数:
./scripts/new-app.sh memos "Memos" 5230
# ↑应用slug ↑显示名称 ↑监听端口
执行后自动生成两套目录,全部带 TODO 标记等待你填写:
| 生成位置 | 生成内容 |
|---|---|
apps/memos/fnos/ |
manifest、cmd/service-setup、bin/memos-server、config/、ui/、health.json |
apps/memos/ |
CHANGELOG.md、README.md、update_memos.sh |
scripts/apps/memos/ |
meta.env、get-latest-version.sh、build.sh、release-notes.tpl |
脚手架输出末尾会打印 14 条下一步操作清单,照着做即可。
四、第二步:填写应用定义(apps//fnos/)
4.1 manifest:应用的"身份证"
以 apps/memos/fnos/manifest 为参考,必填字段一览:
| 字段 | 示例 | 说明 |
|---|---|---|
appname |
memos |
系统内唯一标识 |
version |
0.26.1 |
构建时自动更新 |
display_name |
Memos |
应用中心显示名 |
desc |
轻量级自托管笔记服务... |
面向用户的中文描述 |
service_port |
5230 |
监听端口,须与应用默认一致 |
desktop_applaunchname |
memos.Application |
桌面入口 ID |
source |
thirdparty |
固定值 |
⚠️ 格式要求:
Key = value固定宽度对齐(值从第 16 列开始),L1 静态检查会校验。
4.2 启动配置:service-setup 与启动包装脚本
- cmd/service-setup:声明
SERVICE_COMMAND(启动命令)、PID_FILE、LOG_FILE三个变量即可,启停逻辑由共享框架接管,不要重复编写 common/installer 脚本。 bin/memos-server:启动包装脚本,负责设置环境变量后exec真实二进制。
4.3 权限、防火墙与图标
| 文件 | 作用 |
|---|---|
config/privilege |
JSON 格式声明运行用户;"run-as": "package" 表示以应用专用用户(非 root)运行 |
<App>.sc |
防火墙端口转发规则 |
ICON.PNG / ICON_256.PNG |
64×64 与 256×256 应用图标(建议从 Dashboard Icons 获取,风格统一) |
ui/config |
桌面入口:标题、端口、访问路径 |
五、第三步:编写构建合约(scripts/apps//)
构建合约是 CI 与你的应用之间的"接口规范",共 4 个文件(接口定义见 scripts/apps/README.md):
| 文件 | 职责 | 关键约定 |
|---|---|---|
meta.env |
静态元数据 | FILE_PREFIX、RELEASE_TITLE、DEFAULT_PORT 必填 |
get-latest-version.sh |
探测上游最新版本 | 必须向 stdout 输出 VERSION=x.y.z |
build.sh |
下载上游产物并组装 | 在当前目录产出 app.tgz,退出码 0 表示成功 |
release-notes.tpl |
Release 日志模板 | 支持 ${VERSION}、${CHANGELOG} 等变量 |
以 Memos 为例,版本探测逻辑(scripts/apps/memos/get-latest-version.sh)就是查询上游 GitHub 仓库的最新 tag 后输出 VERSION=0.26.1;构建脚本(scripts/apps/memos/build.sh)则是"下载对应架构 tar 包 → 解压 → 复制 fnOS 启动脚本与 ui 目录 → 打包 app.tgz"。
💡 选 Docker 模式时,
build.sh只需复制docker-compose.yaml、用sed把${VERSION}占位符替换为真实版本再打包——镜像由用户安装时自动拉取。
六、第四步:本地构建与三层测试 🧪
6.1 本地构建
每个应用自带 update_<app>.sh 脚本(如 apps/memos/update_memos.sh),它封装了版本探测、下载、打包全流程,底层调用共享库 scripts/lib/update-common.sh:
cd apps/memos
./update_memos.sh # 最新版本,自动检测架构
./update_memos.sh --arch arm # 强制构建 ARM 版
./update_memos.sh 0.26.1 # 指定版本
产物输出到仓库根目录 dist/,命名格式 <slug>_<version>_x86.fpk。通用打包器 scripts/build-fpk.sh 会自动把 app.tgz 的 md5 写入 manifest 的 checksum 字段,并合并 shared/cmd/ 框架。
6.2 三层测试(合入前必须全过)
| 层级 | 命令 | 验证内容 |
|---|---|---|
| L1 静态检查 | bash scripts/test/static-check.sh memos |
manifest 字段、图标尺寸、遗留 TODO、端口一致性、shellcheck |
| L2 包契约 | bash scripts/test/verify-fpk.sh dist/memos_0.26.1_x86.fpk |
包结构完整性、md5 校验和、ELF 架构匹配 |
| L3 安装生命周期 | bash scripts/test/run-fpk-tests.sh dist/memos_0.26.1_x86.fpk |
容器内真实执行 安装→启动→探活→停止→卸载→残留检查 |
探活行为由 apps/<app>/fnos/health.json 控制(HTTP 路径、超时时间、期望状态码)。首发版本跳过升级测试即可;从第二个版本起,建议追加 --upgrade-from dist/<旧>.fpk 验证用户数据持久性。
⚠️ 顺序不能反:先把 L1 跑干净再做 L2/L3,否则同样的问题会在每层刷屏。
七、第五步:推送 main,让 CI 自动发布 🚀
提交并推送后,流水线全自动完成剩下的工作:
git add apps/memos scripts/apps/memos
git commit -m "feat: add Memos app (memos, port 5230)"
git push origin main
CI 执行链路:
- 自动发现:入口 workflow 检测到
apps/memos/与scripts/apps/memos/meta.env存在,无需任何白名单配置; - 版本检查:运行
get-latest-version.sh,再经 scripts/ci/resolve-release-tag.sh 确定发布标签(标签已存在则幂等跳过); - 矩阵构建:x86 + arm 双架构并行构建;
- 创建 Release:上传双架构
.fpk文件,自动渲染 Release Notes(含国内镜像下载链接); - 更新 apps.json:应用中心数据源随之刷新,你的应用即刻被商店发现。
版本标签采用命名空间格式,例如 memos/v0.26.1。若需修复打包问题但上游版本未变,手动触发构建并指定 revision=r2,CI 会自动追加 -r2、-r3 修订后缀。发布后 CI 每日 08:00(UTC)定时检查上游新版本,自动跟进——发布只是开始,更新从此免费。
八、常见坑位与发布检查清单 ✅
三个历史上真实踩过、代价昂贵的坑:
| 坑 | 正确做法 |
|---|---|
向导 initValue 写成布尔值 |
必须是字符串,否则 fnOS 直接拒绝解析整个安装向导 |
在 service_postinst 里 sed 改 compose / 写 .env |
无效!容器先于该钩子创建。正确写法:environment: - APP_PASSWORD=${wizard_password:-changeme} 直接在 compose 中引用 |
| 版本替换用 perl 或其他工具 | 必须用 sed -i.bak "s/\${VERSION}/${VERSION}/g",否则可能污染整个 compose 文件 |
提交前对照清单(完整版见 docs/adding-new-apps.md 第 11 节):
- [ ] manifest 的
appname/display_name/service_port/desc填写完整,无遗留 TODO - [ ]
ICON.PNG(64×64)、ICON_256.PNG(256×256)、ui/images/64.png三张图标齐全 - [ ]
config/privilege配置了正确的非 root 运行用户 - [ ]
.sc防火墙规则、health.json探活参数已调优 - [ ] 构建合约 4 个文件齐全且可独立运行
- [ ] L1 / L2 / L3 测试全部通过,输出粘贴到 PR 描述中
- [ ]
CHANGELOG.md含## YYYY-MM-DD格式的首发条目(CI 会自动提取进 Release Notes)
九、相关文档导航 📚
| 文档 | 内容 |
|---|---|
| docs/adding-new-apps.md | 新增应用完整指南:两种打包模式、生命周期钩子、目录结构 |
| docs/fnos-developer-guide.md | fnOS 官方开发规范:manifest 字段、环境变量、向导、运行时依赖 |
| docs/release-new-app.md | 新应用发布流程:本地验证、实机安装测试、发布后维护 |
| scripts/apps/README.md | 构建合约接口规范(meta.env / build.sh 契约细节) |
| AGENTS.md | 项目知识库:架构约定、反模式、历史踩坑记录 |
现在,回到终端,敲下 ./scripts/new-app.sh <你的应用> "<显示名>" <端口> 这一行命令,你的第一个 fnOS 应用距离上架只差一次 push。
延伸阅读:完整变更记录见 CHANGELOG.md;应用商店入口应用 fnOS Apps 可一键管理仓库内所有应用的安装与更新。