0 Fork 0

Files

T

tianmo 61b93f590c 新增飞牛 fpk 打包部署文档与 1.0.2 安装包

- Document/飞牛fpk打包与部署.md：记录 fnpack 准备、改版本号、npm run pack:fnos 打包、安装到 fnOS、装完必查项、常见排障与上架前待办；并记下入口形态从 CGI 改为端口服务的原因（CGI 入口在目标设备上桌面图标不注册、「打开」无反应）
- release/fnos/SpineParticle-1.0.2.fpk：端口服务形态安装包，service_port=27850、依赖 nodejs_v22，桌面图标与「打开」正常，包内自带 Windows/macOS 连接器下载物
- 打包用源码暂未入库，仅保留安装包与文档

影响面：飞牛端新增应用包与文档，网页端代码未改动。

2026-10-10 15:27:56 +08:00

5.8 KiB

Raw Blame History

飞牛 fnOS fpk 打包与部署

把网页粒子编辑器打包成飞牛 fnOS 应用包（.fpk），装到 NAS 后从桌面图标直接打开。本文是完整流程，照着做即可重复出包。

1. 一次性准备

打包机：开发用的 Mac/Windows/Linux 即可，需要 Node 环境（项目本来就有）。

fnpack：飞牛官方的打包工具，从 https://developer.fnnas.com/docs/cli/fnpack/ 下载对应平台版本（本项目实测 fnpack-1.2.3-darwin-arm64）：

chmod +x fnpack-1.2.3-darwin-arm64
mv fnpack-1.2.3-darwin-arm64 /usr/local/bin/fnpack   # 或任意位置，后面用 FNPACK 指定
fnpack --help

目标设备：已初始化的飞牛 fnOS，管理员账号，有可用存储空间，开发机可访问。

2. 目录与职责

路径	作用
`src/`	前端源码，编辑器本体
`dist/`	vite 构建产物，网页端和飞牛包共用这一份
`packaging/fnos/SpineParticle/`	fnOS 包工程：`manifest`、`cmd/`、`config/`、`app/ui/`、`app/server/`、图标
`scripts/build-fnos-package.mjs`	把 `dist/` 复制进包的 `app/www/` 并调用 fnpack
`release/fnos/`	打好的 `.fpk`（已加入 `.gitignore`，不入库）

包工程里 app/www/ 由脚本生成，不要手改，改了也会被下次打包覆盖。

3. 打包

第一步，改版本号：编辑 packaging/fnos/SpineParticle/manifest，改这两行（飞牛按版本号识别升级，重打包务必递增）：

version=1.0.3
changelog=这次改了什么，面向用户写一句话

第二步，执行打包：

npm run pack:fnos

它等价于 npm run build && node scripts/build-fnos-package.mjs：先做 vue-tsc 类型检查和 vite 构建，然后清空 app/www/、复制 dist/（自动排除 .DS_Store）、调用 fnpack build，最后把产物移到 release/fnos/。

产物：release/fnos/SpineParticle-<version>.fpk，当前约 2.6MB。

如果 fnpack 不在 PATH 里：

FNPACK=/path/to/fnpack npm run pack:fnos

4. 安装到飞牛

方式一（图形界面）：飞牛桌面 → 应用中心 → 左下角「手动安装」→ 选 .fpk。

方式二（命令行，需 SSH 到 NAS）：

appcenter-cli install-fpk SpineParticle-1.0.3.fpk

安装完成后 cmd/install_callback 会自动启动内置静态服务；如果应用中心显示未运行，手动点一次「启动」。装好刷新一次飞牛桌面（F5 或重新登录），桌面图标才会出现。

5. 装完必须验证的几项

检查项	预期
桌面图标	出现「Spine粒子编辑器」，点开是编辑器界面（`http://<飞牛地址>:27850/`）
应用中心状态	显示运行中，可启动/停止
预设下拉	能加载出预设列表（读取 `/Preset/index.json`）
连接器下载	帮助弹窗第 9 节两个下载按钮可用，能下到 exe 和 zip
远程备用入口	`<飞牛地址>/cgi/ThirdParty/SpineParticle/index.cgi/` 也能打开
连接器联动	本机启动连接器后，导出区显示「连接器可用 · Spine 已就绪」

6. 包形态说明（重要，避免走回头路）

当前用的是端口服务形态：

service_port=27850
install_dep_apps=nodejs_v22
ctl_stop=true

app/server/server.mjs 是 Node 写的静态服务，把 app/www 挂到 27850 端口，cmd/main 负责启停，桌面入口配置在 app/ui/config，指向该端口。

为什么不用 CGI 入口：/cgi/ThirdParty/{appname}/index.cgi/ 这套（纯静态、不占端口）在开发机上打包校验能通过，页面直连也能打开，但在目标设备上桌面入口始终没注册——表现就是桌面没有图标、应用中心「打开」点了没反应。试过补 protocol/port 字段也无效，换成端口服务后立即正常。所以后续请沿用端口形态。

app/ui/index.cgi 保留着，仅作为远程访问备用入口，和端口走同一份 www。

7. 常见问题

现象	处理
桌面没有图标 / 「打开」没反应	确认应用状态是运行中；刷新（F5）或重新登录飞牛桌面
安装报依赖错误	确认 `manifest` 里 `install_dep_apps=nodejs_v22`，且设备能安装该运行时
端口被占用	同时改两处并保持一致：`manifest` 的 `service_port`、`app/ui/config` 的 `port`，然后重打包
外网点图标打不开	端口形态需要该端口可达；外网请用 `/cgi/ThirdParty/SpineParticle/index.cgi/`
页面白屏或资源 404	前端构建已改为相对路径（vite `base: './'`），若做过路径相关改动，先跑 `npm run build` 再用新 `dist` 打包
服务起不来	看设备上 `/var/apps/SpineParticle/var/app.log`
安装异常	看设备上 `/var/log/trim_app_center/error.log`

8. 上架应用中心前待办

替换图标：packaging/fnos/SpineParticle/ 下 ICON.PNG(64×64)、ICON_256.PNG(256×256)，以及 app/ui/images/icon_64.png、icon_256.png，规格 sRGB、圆角方形、单文件 ≤1MB。目前是脚本生成的占位图。
核对 manifest 里的 maintainer、maintainer_url、distributor、os_min_version（现填 Yeomai / gitlab 地址 / 1.0.0）。
准备真实界面截图和测试材料。
通过飞牛开发者先锋群 / 开发者后台提交。

9. 提交代码时注意

dist/ 在版本库里是跟踪状态，重新构建会带出 assets 的增删（文件名带哈希），要和源码改动一起提交，否则别人拉下来跑出的页面和打包不一致。
packaging/fnos/SpineParticle/app/www/、release/fnos/、以及包工程根目录的 *.fpk 都是构建产物，已在 .gitignore 中排除。
包的形态、端口、入口配置一旦上架，跨版本要保持稳定，改端口等于改变用户访问方式。

5.8 KiB Raw Blame History Unescape Escape