开发与工程 · SKILL.md

fnos-fpk-dev

fnos-fpk-dev

【开发与工程】Use when developing fnOS FPK packages, writing lifecycle scripts, or configuring manifest, privilege, resource, wizard, and desktop UI files. Covers package structure, environment variables, packaging, and common platform constraints.

独立 GitHub 快照 · 自动分类 · 以原作者文档为准

Jjianyun8023 / my-skillsApache-2.0

技能说明

GitHub

name: fnos-fpk-dev description: Use when developing fnOS FPK packages, writing lifecycle scripts, or configuring manifest, privilege, resource, wizard, and desktop UI files. Covers package structure, environment variables, packaging, and common platform constraints.

飞牛 fnOS FPK 应用开发

适用场景

新建 fnOS FPK 应用包
编写或调整 manifest、cmd/ 生命周期脚本、wizard/、config/privilege、config/resource
为 FPK 应用添加桌面图标 Web UI
排查打包结构、环境变量或脚本退出码问题

不适用

非 fnOS / FPK 平台的 Docker、Kubernetes 或通用 Linux 打包任务
只调试应用业务代码，不涉及 FPK 目录结构、生命周期或 manifest
需要官方 root 权限发布资格、签名或上架审核流程细节时

应用目录结构

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 资源
`cmd/`	`cmd/`	—	生命周期脚本
`config/`	`config/`	—	privilege + resource
`wizard/`	`wizard/`	—	向导定义
`manifest`	`manifest`	—	应用元信息
`ICON.PNG`	`ICON.PNG`	—	小图标 64x64
—	`var/`	`TRIM_PKGVAR`	运行时数据（系统创建）
—	`etc/`	`TRIM_PKGETC`	静态配置（系统创建）
—	`home/`	`TRIM_PKGHOME`	用户数据（系统创建）
—	`tmp/`	`TRIM_PKGTMP`	临时文件（系统创建）
—	`meta/`	`TRIM_PKGMETA`	元数据（系统创建）
—	`shares/`	—	共享目录（由 resource 定义）

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

核心系统环境变量

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

常用路径变量

变量	说明
`TRIM_APPDEST`	应用可执行文件目录（target）
`TRIM_PKGVAR`	运行时数据目录（var）
`TRIM_PKGETC`	静态配置目录（etc）
`TRIM_PKGHOME`	用户数据目录（home）
`TRIM_PKGTMP`	临时文件目录（tmp）

常用信息变量

变量	说明
`TRIM_APPNAME`	应用名称（来自 manifest appname）
`TRIM_APPVER`	应用版本号（来自 manifest version）
`TRIM_OLD_APPVER`	升级前的版本号（仅在 upgrade 脚本中可用）
`TRIM_SERVICE_PORT`	manifest 中声明的服务端口
`TRIM_USERNAME` / `TRIM_GROUPNAME`	应用专用用户名/组名
`TRIM_RUN_USERNAME`	实际运行用户（root 或 package 用户）
`TRIM_TEMP_LOGFILE`	系统日志文件路径（写入错误信息供前端展示）
`wizard_*`	向导表单字段值（仅在对应 callback 脚本中可用）

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", ... }
        ]
    }
]

表单项类型速查

类型	用途	关键字段
`text`	文本输入	field, label, initValue, rules
`password`	密码输入	field, label, rules
`radio`	单选	field, label, options, initValue
`checkbox`	多选	field, label, options, initValue
`select`	下拉选择	field, label, options, initValue
`switch`	开关	field, label, initValue（字符串 `"true"` / `"false"`）
`tips`	提示文本	helpText（支持HTML）

验证规则

{ "required": true, "message": "必填提示" }
{ "min": 3, "max": 20, "message": "长度限制" }
{ "len": 6, "message": "精确长度" }
{ "pattern": "^[a-zA-Z0-9]+quot;, "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 字段说明

字段	类型	说明
`title`	string	桌面图标显示名称
`icon`	string	图标路径（相对于 ui 目录），`{0}` 为尺寸占位符（系统自动替换为 64/256）
`type`	string	入口方式：`url`（新标签页打开）/ `iframe`（内嵌页面）
`protocol`	string	访问协议：`http` / `https`
`port`	string	应用端口（字符串类型），与 manifest `service_port` 一致
`url`	string	应用访问路径（相对路径，如 `/`、`/admin`）
`allUsers`	boolean	是否所有用户可见，`false` 则仅管理员可见

关键规则

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

协议注意事项

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

模式	config 配置	适用场景
直连（HTTP + IP）	`"protocol": "http", "port": "8080"`	局域网直接访问
反代（HTTPS + 域名）	不声明 `port`，由 fnOS Nginx 反代转发	通过域名/HTTPS 访问

注意：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 完整字段说明：reference.md
实际项目示例：examples.md
官方文档：https://developer.fnnas.com/docs/core-concepts/framework
打包工具：https://developer.fnnas.com/docs/cli/fnpack

常见错误

错误做法	正确做法
把 `ui/` 放在项目根目录而不是 `app/ui/`	始终让桌面 UI 跟随 `app/ -> target/` 映射
`cmd/main status` 返回 1 代表未运行	未运行应返回 `exit 3`
直接 `echo` 报错到 stdout	写入 `${TRIM_TEMP_LOGFILE}` 再 `exit 1`
`manifest` 使用带空格的 `key = value`	使用严格的 `key=value` 格式
硬编码 `/var/apps/com.example.myapp` 之类路径	优先使用 `TRIM_APPDEST`、`TRIM_PKGVAR` 等环境变量
打包前不检查脚本权限和目录结构	先 `chmod +x cmd/*`，再用 `fnpack pack` 验证内容

MAKE IT PART OF YOUR WORKFLOW

安装技能

TERMINAL

npx skills add jianyun8023/my-skills --skill fnos-fpk-dev

复制命令到本地终端执行；安装前请先审查源代码和许可证。

ZIP · 完整技能目录，含资源与许可证

SKILL.md · 仅技能说明原文

仓库 Star: 未同步
许可证: Apache-2.0
版本 / 分支: HEAD · 3f5cbc91
仓库更新时间: 未同步

安装前，请检查技能脚本与权限。

源代码