5.7 KiB
5.7 KiB
FlyPic 飞牛 NAS 打包部署指南
本指南介绍如何将 FlyPic 打包成飞牛 fnOS 应用包(.fpk)并部署到飞牛 NAS。
前置要求
开发环境(Windows/Mac/Linux)
- Node.js 18+
- Docker Desktop(用于编译 Linux 版本依赖)
飞牛 NAS
- fnOS 0.9.27+
- fnpack 命令行工具(系统预装或通过
npm install -g fnpack安装)
一、构建应用
使用 Docker 构建(推荐)
此方法使用 node:22-slim (Debian) 镜像编译原生模块,确保与飞牛 fnOS (Debian 系) 的 glibc 兼容。
# 确保 Docker Desktop 正在运行
node scripts/build.js
构建过程:
- 构建前端 (Vite)
- 复制后端代码到
flypic/app/server/ - 复制前端产物到
flypic/app/server/public/ - 使用 Docker 安装 Linux glibc 版本依赖
- 修复脚本换行符 (CRLF → LF)
构建完成后,flypic 目录即可上传到飞牛。
二、上传到飞牛 NAS
将整个 flypic 文件夹上传到飞牛 NAS,可以使用:
- 飞牛文件管理器
- SFTP/SCP
- SMB 共享
建议上传到用户目录,如:/vol1/1000/flypic
三、打包 .fpk 文件
SSH 登录到飞牛 NAS,执行:
# 进入应用目录
cd /vol1/1000/flypic
# 打包应用
fnpack build
成功后会生成 flypic_1.0.0_all.fpk 文件。
四、安装应用
方法一:通过飞牛应用中心安装
- 打开飞牛 fnOS 桌面
- 进入「应用中心」→「手动安装」
- 选择生成的
.fpk文件 - 按照安装向导完成安装
方法二:命令行安装
appcenter-cli install-fpk flypic_1.0.0_all.fpk
五、配置应用
安装完成后,首次使用需要:
-
配置授权目录:在飞牛应用设置中,为 FlyPic 添加素材库文件夹的访问权限
-
添加素材库:打开 FlyPic,添加素材库时输入完整路径,如:
/vol1/1000/图片库/vol2/photos
目录结构说明
flypic/
├── ICON.PNG # 应用图标 64x64
├── ICON_256.PNG # 应用图标 256x256
├── manifest # 应用清单
├── app/
│ ├── server/ # 应用服务器
│ │ ├── server.js # 主入口
│ │ ├── package.json # 依赖配置
│ │ ├── node_modules/ # Linux glibc 依赖 (~57MB)
│ │ │ ├── @img/sharp-linux-x64/ # Sharp 原生模块
│ │ │ ├── better-sqlite3/ # SQLite 原生模块
│ │ │ └── ...
│ │ ├── public/ # 前端静态文件 (Vite 构建产物)
│ │ ├── src/ # 后端源码
│ │ │ ├── routes/ # API 路由
│ │ │ ├── services/ # 业务逻辑
│ │ │ ├── models/ # 数据模型
│ │ │ └── config/ # 配置
│ │ ├── database/ # 数据库模块
│ │ └── utils/ # 工具函数
│ └── ui/
│ └── config # UI 入口配置
├── cmd/
│ ├── main # 启动/停止脚本
│ ├── install_init # 安装前脚本
│ ├── install_callback # 安装后脚本
│ ├── uninstall_init # 卸载前脚本
│ ├── uninstall_callback # 卸载后脚本
│ ├── upgrade_init # 升级前脚本
│ ├── upgrade_callback # 升级后脚本
│ ├── config_init # 配置前脚本
│ └── config_callback # 配置后脚本
├── config/
│ ├── privilege # 权限配置
│ └── resource # 资源配置 (数据共享目录)
└── wizard/
└── install # 安装向导配置
关键配置文件
manifest (应用清单)
appname=flypic
version=1.0.0
desc=飞图 - 专为飞牛 fnOS 设计的轻量、快速、稳定的图像素材检索浏览应用
arch=x86_64
display_name=FlyPic
maintainer=ZangXincz
source=thirdparty
service_port=15002
install_dep_apps=nodejs_v22
config/resource (资源配置)
{
"data-share": [
{
"name": "FlyPic数据",
"path": "data",
"mode": "rw",
"desc": "FlyPic 应用数据存储目录"
}
]
}
常见问题
Q: 应用启动失败,显示"异常退出"
A: 检查以下几点:
- 确保使用
node scripts/build.js构建,包含 Linux glibc 版本的 node_modules - 检查应用日志:
/var/apps/flypic/var/info.log - 确保端口 15002 未被占用
- 确保依赖应用 nodejs_v22 已安装
Q: Sharp 或 SQLite 报错
A: 原生模块需要正确的 Linux 版本:
- 必须使用 Docker (node:22-slim, Debian) 构建
- 不能使用 Alpine 镜像(musl libc 不兼容)
- 不能直接在 Windows/Mac 上 npm install
Q: 无法访问素材库文件夹
A: 在飞牛应用设置中配置授权目录,添加素材库路径的访问权限。
Q: 如何更新应用?
A:
- 重新构建:
node scripts/build.js - 上传到飞牛并打包:
fnpack build - 在应用中心选择「更新」或重新安装
Q: 如何查看应用日志?
A: SSH 登录后查看:
cat /var/apps/flypic/var/info.log
开发调试
本地开发时,可以分别启动前后端:
# 终端 1:启动后端
cd backend
npm install
npm run dev
# 终端 2:启动前端
cd frontend
npm install
npm run dev
访问 http://localhost:5173 进行开发调试。
技术栈
- 后端: Node.js + Express + Sharp + better-sqlite3 + Socket.IO
- 前端: React + Vite + TailwindCSS + Zustand
- 运行时: nodejs_v22 (飞牛应用依赖)
- 端口: 15002