tianmo
61b93f590c
- 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 连接器下载物 - 打包用源码暂未入库，仅保留安装包与文档 影响面：飞牛端新增应用包与文档，网页端代码未改动。
119 lines
5.8 KiB
Markdown
119 lines
5.8 KiB
Markdown
# 飞牛 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` 中排除。
|
||
- 包的形态、端口、入口配置一旦上架，跨版本要保持稳定，改端口等于改变用户访问方式。
|