Files
flypic/飞牛打包部署指南.md
2025-12-04 18:11:27 +08:00

5.7 KiB
Raw Permalink Blame History

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

构建过程:

  1. 构建前端 (Vite)
  2. 复制后端代码到 flypic/app/server/
  3. 复制前端产物到 flypic/app/server/public/
  4. 使用 Docker 安装 Linux glibc 版本依赖
  5. 修复脚本换行符 (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 文件。

四、安装应用

方法一:通过飞牛应用中心安装

  1. 打开飞牛 fnOS 桌面
  2. 进入「应用中心」→「手动安装」
  3. 选择生成的 .fpk 文件
  4. 按照安装向导完成安装

方法二:命令行安装

appcenter-cli install-fpk flypic_1.0.0_all.fpk

五、配置应用

安装完成后,首次使用需要:

  1. 配置授权目录:在飞牛应用设置中,为 FlyPic 添加素材库文件夹的访问权限

  2. 添加素材库:打开 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: 检查以下几点:

  1. 确保使用 node scripts/build.js 构建,包含 Linux glibc 版本的 node_modules
  2. 检查应用日志:/var/apps/flypic/var/info.log
  3. 确保端口 15002 未被占用
  4. 确保依赖应用 nodejs_v22 已安装

Q: Sharp 或 SQLite 报错

A: 原生模块需要正确的 Linux 版本:

  • 必须使用 Docker (node:22-slim, Debian) 构建
  • 不能使用 Alpine 镜像(musl libc 不兼容)
  • 不能直接在 Windows/Mac 上 npm install

Q: 无法访问素材库文件夹

A: 在飞牛应用设置中配置授权目录,添加素材库路径的访问权限。

Q: 如何更新应用?

A:

  1. 重新构建:node scripts/build.js
  2. 上传到飞牛并打包:fnpack build
  3. 在应用中心选择「更新」或重新安装

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