# 飞牛 fnOS fpk 打包与部署

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

## 1. 一次性准备

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

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

```text
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`，改这两行（飞牛按版本号识别升级，重打包务必递增）：

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

**第二步，执行打包**：

```text
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 里：

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

## 4. 安装到飞牛

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

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

```text
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. 包形态说明（重要，避免走回头路）

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

```ini
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` 中排除。
- 包的形态、端口、入口配置一旦上架，跨版本要保持稳定，改端口等于改变用户访问方式。