在飞牛fnOS发布你的第一个第三方应用完整教程:fnos-apps从脚手架到CI自动发布实战

原创2026-10-25 17:49:471,391 阅读
文章标签:构建工具CI/CD

在飞牛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 执行链路:

  1. 自动发现:入口 workflow 检测到 apps/memos/ 与 scripts/apps/memos/meta.env 存在,无需任何白名单配置;
  2. 版本检查:运行 get-latest-version.sh,再经 scripts/ci/resolve-release-tag.sh 确定发布标签(标签已存在则幂等跳过);
  3. 矩阵构建:x86 + arm 双架构并行构建;
  4. 创建 Release:上传双架构 .fpk 文件,自动渲染 Release Notes(含国内镜像下载链接);
  5. 更新 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 可一键管理仓库内所有应用的安装与更新。

登录后查看全文
fnos-apps