飞牛 fnOS FPK 应用开发

应用目录结构

FPK 安装后的标准目录结构：

/var/apps/[appname]
├── cmd/                    # 生命周期脚本（必须）
│   ├── main                # 启停和状态检查
│   ├── install_init        # 安装前
│   ├── install_callback    # 安装后
│   ├── uninstall_init      # 卸载前
│   ├── uninstall_callback  # 卸载后
│   ├── upgrade_init        # 更新前
│   ├── upgrade_callback    # 更新后
│   ├── config_init         # 配置前
│   └── config_callback     # 配置后
├── config/
│   ├── privilege           # 权限声明（JSON）
│   └── resource            # 资源/能力声明（JSON）
├── wizard/
│   ├── install             # 安装向导（JSON）
│   ├── uninstall           # 卸载向导（JSON）
│   ├── upgrade             # 更新向导（JSON）
│   └── config              # 配置向导（JSON）
├── manifest                # 应用身份信息（key=value）
├── ICON.PNG                # 小图标 64x64
├── ICON_256.PNG            # 大图标 256x256
├── LICENSE                 # 隐私协议（可选）
├── etc -> /vol[x]/@appconf/[appname]    # 静态配置
├── home -> /vol[x]/@apphome/[appname]   # 用户数据
├── target -> /vol[x]/@appcenter/[appname] # 可执行文件（TRIM_APPDEST）
│   └── ui/                 # 桌面图标 Web UI 配置（可选，由 desktop_uidir 指定）
│       ├── images/
│       │   ├── icon-64.png   # 64x64 桌面图标
│       │   └── icon-256.png  # 256x256 桌面图标
│       └── config            # 入口配置文件（JSON）
├── tmp -> /vol[x]/@apptemp/[appname]    # 临时文件（TRIM_PKGTMP）
├── var -> /vol[x]/@appdata/[appname]    # 运行时数据（TRIM_PKGVAR）
├── meta -> /vol[x]/@appmeta/[appname]   # 应用元数据（TRIM_PKGMETA）
└── shares/                 # 数据共享目录（由 resource 定义）

开发目录与安装目录映射

关键：app/ 目录对应安装后的 target（TRIM_APPDEST），桌面 UI 配置必须放在 app/ui/ 下。

核心系统环境变量

所有 cmd/ 脚本中可用，完整列表见 reference.md。

常用路径变量

常用信息变量

cmd/main 脚本（必须）

管理应用的启停和状态检查：

#!/bin/bash
PID_FILE="${TRIM_PKGVAR}/app.pid"

case $1 in
start)
    # 启动应用，成功返回 0，失败返回 1
    # TODO: 替换为实际启动命令
    exit 0
    ;;
stop)
    # 停止应用，成功返回 0，失败返回 1
    # TODO: 替换为实际停止命令
    exit 0
    ;;
status)
    # 运行中返回 0，未运行返回 3
    if [ -f "$PID_FILE" ]; then
        pid=$(cat "$PID_FILE" | tr -d '[:space:]')
        if [ -n "$pid" ] && kill -0 "$pid" 2>/dev/null; then
            exit 0
        fi
        rm -f "$PID_FILE"
    fi
    exit 3
    ;;
*)
    exit 1
    ;;
esac

关键规则：

• status 返回 exit 0 = 运行中，exit 3 = 未运行
• 错误时写入 $TRIM_TEMP_LOGFILE 后 exit 1，不要直接 echo
• 系统会定期轮询 status 检查健康状态

manifest 文件

key=value 格式（等号前后无空格），定义应用基本信息：

appname=com.example.myapp                # 唯一标识（必须）
version=1.0.0                            # 版本号 x[.y[.z]][-build]
display_name=我的应用                      # 显示名称
desc=应用描述，支持HTML                    # 应用介绍
platform=x86                             # x86 | arm | all（V1.1.8+）
source=thirdparty                        # 固定值
maintainer=开发者名称
distributor=发布者名称
service_port=8080                        # 服务端口
checkport=true                           # 启动前检查端口占用
os_min_version=0.9.0                     # 最低系统版本
install_dep_apps=mariaDB:redis           # 依赖应用（冒号分隔，支持版本号 app1>2.0:app2）
desktop_uidir=ui                         # Web UI 目录（相对于应用根目录，即 target）
desktop_applaunchname=com.example.myapp.main  # 入口 ID（对应 ui/config 中 .url 下的 key）
ctl_stop=true                            # 显示启停按钮
install_type=                            # root 安装到系统分区，空则用户选择
changelog=修复已知问题                      # 更新日志（升级时展示）

注意：

• arch 已废弃，使用 platform 替代，不支持多个值填写。
• desktop_applaunchname 必须与 app/ui/config 中 .url 下定义的入口 key 一致。
• ctl_stop=false 时隐藏启停按钮和运行状态，适用于无进程应用。
• install_type=root 时安装到系统分区 /usr/local/apps/@appcenter/，为空时用户选择 /vol${x}/@appcenter/。
• install_dep_apps 格式：app1>2.2.2:app2:app3，> 表示最低版本要求。

config/privilege（权限声明）

{
    "defaults": {
        "run-as": "package"
    },
    "username": "myapp",
    "groupname": "myapp"
}

• run-as: "package" — 应用用户运行（推荐，安全）
• run-as: "root" — root 权限运行（仅官方合作开发者可发布）
• 未指定 username / groupname 时默认使用 manifest 中的 appname
• 完整说明（含 folder-permission）见 reference.md

config/resource（资源声明）

支持三种资源类型，常用的是 data-share：

{
    "data-share": {
        "shares": [
            {
                "name": "myapp-data",
                "permission": {
                    "rw": ["myapp"]
                }
            }
        ]
    }
}

• permission 数组中填写 privilege 中定义的 username（未定义则为 manifest appname）
• 声明的共享目录自动创建在 shares/ 下
• 权限类型：rw（读写）、ro（只读）
• 其他资源类型（usr-local-linker、docker-project）见 reference.md

wizard（用户向导）

JSON 数组格式，每个元素是一个步骤页面：

[
    {
        "stepTitle": "步骤标题",
        "items": [
            { "type": "text|password|radio|checkbox|select|switch|tips", ... }
        ]
    }
]

表单项类型速查

验证规则

{ "required": true, "message": "必填提示" }
{ "min": 3, "max": 20, "message": "长度限制" }
{ "len": 6, "message": "精确长度" }
{ "pattern": "^[a-zA-Z0-9]+$", "message": "正则验证" }

获取向导输入

向导 field 字段名直接作为环境变量名，在对应 callback 脚本中读取：

LOKI_URL="${wizard_loki_url:-默认值}"

桌面图标配置（Desktop UI）

为应用添加 fnOS 桌面图标，点击后在浏览器中打开应用 Web UI。

开发时目录结构

app/
└── ui/                     # 对应 manifest 的 desktop_uidir = ui
    ├── images/
    │   ├── icon-64.png     # 64x64 桌面图标
    │   └── icon-256.png    # 256x256 桌面图标
    └── config              # 入口配置文件

重要：app/ 目录 = 安装后的 target（TRIM_APPDEST）。ui/ 必须放在 app/ 下，否则 fnpack 打包时会报 no such file or directory 错误。

manifest 必填字段

desktop_uidir=ui
desktop_applaunchname=com.example.myapp.main

app/ui/config 格式

入口定义在 .url key 下，key 名必须以 appname 为前缀：

{
    ".url": {
        "com.example.myapp.main": {
            "title": "我的应用",
            "icon": "images/icon-{0}.png",
            "type": "url",
            "protocol": "http",
            "port": "8080",
            "url": "/",
            "allUsers": true
        }
    }
}

config 字段说明

关键规则

• 图标 {0} 是尺寸占位符，系统自动替换为 64/256，必须提供两个尺寸文件
• .url 下的 key 名必须以 manifest appname 为前缀
• desktop_applaunchname 指定默认入口（应用中心"打开"按钮使用）
• port 是字符串类型，应与 manifest service_port 一致

协议注意事项

fnOS 桌面点击图标时，URL 拼接逻辑：{protocol}://{当前浏览器hostname}:{port}{url}

注意：HTTPS 页面中声明 protocol: "http" 会导致协议降级和端口不可达。完整的协议适配说明和多入口配置见 reference.md。

生命周期脚本流程

安装：install_init → 解压文件 → install_callback

卸载：uninstall_init → 删除文件 → uninstall_callback

更新：upgrade_init → 替换文件 → upgrade_callback

配置：config_init → 更新环境变量 → config_callback

卸载保留 var 和 shares 目录（保护用户数据）。

错误处理（V1.1.8+）

脚本中遇到错误时，写入 TRIM_TEMP_LOGFILE 后 exit 1：

if [ ! -f "$TRIM_PKGETC/config.conf" ]; then
    echo "配置文件不存在，应用启动失败！" > "${TRIM_TEMP_LOGFILE}"
    exit 1
fi

系统会将内容以 Dialog 对话框形式展示给用户。

打包工具 fnpack

使用 fnpack 命令行工具创建和打包 FPK 应用：

# 创建应用项目骨架
fnpack create myapp

# 打包为 .fpk 文件
fnpack pack [项目目录]

• 下载地址：https://developer.fnnas.com/docs/cli/fnpack
• 打包前确保 app/ 目录包含所有需要部署到 target 的文件
• 桌面图标的 ui/ 目录必须放在 app/ 下，否则打包报错

Bash 脚本安全实践

所有 cmd/ 脚本建议遵循：

• 变量加双引号："$TRIM_PKGVAR" 而非 $TRIM_PKGVAR，防止路径含空格时出错
• 错误写入日志：遇到错误必须写入 "${TRIM_TEMP_LOGFILE}"，不要直接 echo 到 stdout
• 明确退出码：成功 exit 0，失败 exit 1，status 未运行 exit 3
• 用 $TRIM_APPNAME 构建路径：不要硬编码 /var/apps/com.example.myapp，用 /var/apps/${TRIM_APPNAME}
• heredoc 生成 JSON 时注意转义：用户输入的特殊字符（引号、反斜杠）可能破坏 JSON 格式，建议在 callback 中校验

调试技巧

• 模拟环境变量：本地测试脚本时，手动 export TRIM_PKGVAR=/tmp/test-var 等模拟环境
• 查看错误日志：脚本失败后查看 $TRIM_TEMP_LOGFILE 中写入的内容
• 验证打包内容：fnpack pack 生成的 .fpk 实质是压缩包，可解压检查文件结构是否正确
• 检查脚本权限：常见问题是脚本缺少执行权限，确保 chmod +x cmd/*
• Docker 应用调试：在 fnOS 终端中手动执行 docker compose 命令排查容器启动失败

开发检查清单

• manifest 包含所有必填字段（key=value 格式，无空格）
• cmd/main 正确处理 start/stop/status
• status 返回码正确（0=运行中, 3=未运行）
• config/privilege 权限声明合理（优先 package）
• wizard/install 提供合理默认值和验证规则
• callback 脚本正确读取 wizard 环境变量
• 错误信息写入 $TRIM_TEMP_LOGFILE
• 图标文件：ICON.PNG(64x64) + ICON_256.PNG(256x256)
• 脚本有执行权限（chmod +x cmd/*）
• 桌面图标（如需要）：app/ui/config 格式正确、.url key 下使用 appname 前缀、app/ui/images/ 包含 64 和 256 尺寸图标
• 使用 fnpack pack 打包并在 fnOS 上测试安装

详细参考

• manifest 完整字段说明：reference.md
• 实际项目示例：examples.md
• 官方文档：https://developer.fnnas.com/docs/core-concepts/framework
• 打包工具：https://developer.fnnas.com/docs/cli/fnpack