FnDepot 应用源构建规范

版本: 1.0.0 最后更新: 2025-11-30

1. 概述 (Overview)

FnDepot 是运行于 FNOS 上的去中心化第三方应用管理器。本文档详细定义了 FnDepot 应用源（Repository）的构建规范、目录结构及元数据标准。开发者需严格遵循本规范，以确保应用源能被 FnDepot 客户端正确解析、索引及分发。

2. 仓库规范 (Repository Standards)

为了保证解析效率与编写方便，项目在制作时大量采用了飞牛官方开发文档的键名，方便开发者识别。应用源仓库必须满足以下硬性条件：

项目	要求	说明
托管平台	GitHub	目前仅支持 GitHub 托管的仓库。
仓库可见性	Public	仓库必须设为公开，私有仓库无法被客户端索引。
仓库命名	FnDepot	[强制] 仓库名称必须严格命名为 FnDepot（大小写敏感）。
分支策略	main	客户端默认拉取默认分支的内容。

3. 目录结构 (Directory Structure)

FnDepot 采用扁平化的目录结构。仓库根目录必须包含全局索引文件 fnpack.json，每个应用拥有独立的子目录。

FnDepot/                      # [Root] 仓库根目录
│
├── fnpack.json               # [Core] 全局元数据索引文件
│
├── {app_name}/               # [Dir] 应用目录 (名称即为 Unique ID)
│   ├── ICON.PNG              # [Asset] 应用图标 (强制全大写)
│   ├── {app_name}.fpk        # [Bin] 安装包 (文件名须与目录名一致)
│   ├── README.md             # [Doc] 应用详情文档 (Markdown)
│   └── Preview/              # [Asset] 预览图目录
│       ├── 01.png
│       └── 02.jpg
│
└── ... (其他应用目录)

3.1 命名约定

• 应用唯一标识 (app_name)：
  • 仅允许使用 小写字母 (a-z)、数字 (0-9) 和 连字符 (-)。
  • 应用目录名称必须与 fnpack.json 中的键名（Key）完全一致。
• 大小写敏感：Linux 文件系统对大小写敏感，请严格遵守文件名规范（特别是 ICON.PNG）。

4. 元数据规范 (fnpack.json)

fnpack.json 是应用源的核心数据库，位于仓库根目录。它是一个标准的 JSON 对象，其键（Key）为应用的 app_name。

4.1 数据结构

{
  "unique-app-id": {
    "display_name": "String",
    "version": "String",
    "desc": "String",
    "labels": "String",
    "author": "String",
    "author_url": "String",
    "bug_report_url": "String",
    "install_type": "Enum",
    "size": "String",
    "history": {
      "version_number": "String"
    }
  }
}

4.2 字段定义表

字段	类型	必填	描述与约束
Key	String	✅	应用唯一标识。必须与应用文件夹名称完全一致。
display_name	String	✅	客户端展示的应用名称（UI 显示用）。
version	String	✅	当前版本号（建议遵循 SemVer 规范，如 1.0.0）。
desc	String	✅	应用简介。支持使用 \n 进行换行控制。
labels	String	✅	分类标签。多个标签使用半角逗号 , 分隔（无空格）。
download_url	String	可选	下载地址。建议 Release 发布后填写；若 fpk 小于 100MB 可不填写。
author	String	✅	开发者或维护团队名称。
author_url	String	✅	开发者主页/仓库链接 (HTTP/HTTPS)。
bug_report_url	String	✅	问题反馈链接 (HTTP/HTTPS)。
install_type	String	✅	安装目标路径类型。"系统空间" 或 "存储空间"。
size	String	✅	安装包体积。仅填写数字，单位默认为 MB。
history	Object	✅	版本更新记录。 Key: 版本号; Value: 更新日志内容。

5. 资源文件规范 (Assets Specification)

5.1 图标 (ICON.PNG)

• 路径: /{app_name}/ICON.PNG
• 格式: PNG
• 尺寸: 建议 256x256
• 注意: 文件名必须为 ICON.PNG（全大写），否则客户端无法获取。

5.2 安装包 (.fpk)

• 路径:
  • 模式1（fpk < 100MB）：/{app_name}/{app_name}.fpk
  • 模式2（fpk ≥ 100MB）：通过 Release 发布
• 格式: FNOS 标准安装包格式 (.fpk)
• 注意: 文件名必须严格匹配 {app_name}.fpk。

5.3 预览图 (Preview/)

• 路径: /{app_name}/Preview/
• 支持格式: .png, .jpg, .jpeg, .webp 等

6. 完整配置示例 (Configuration Example)

{
  "fntermx": {
    "display_name": "FntermX 终端",
    "desc": "专为飞牛 NAS 打造的现代化 Web 终端\n支持 SSH 连接与会话管理",
    "labels": "工具,终端,SSH,DevOps",
    "version": "1.0.8",
    "author": "EWEDL",
    "author_url": "https://github.com/EWEDLCM",
    "bug_report_url": "https://github.com/EWEDLCM/FntermX/issues",
    "install_type": "系统空间",
    "size": "15",
    "history": {
      "v1.0.8": "性能优化与 Bug 修复",
      "v1.0.7": "新增深色模式支持",
      "v1.0.0": "Initial Release"
    }
  }
}

7. 维护与更新 (Maintenance)

FnDepot 客户端包含自动同步机制。开发者只需对 GitHub 仓库进行常规的 Git 操作即可完成发布：

1. 更新二进制文件：替换对应的 .fpk 文件。
2. 更新元数据：修改 fnpack.json 中的 version 字段并追加 history 记录。
3. 推送 (Push)：将更改推送到 GitHub 的默认分支。

客户端会在同步源信息时检测到 version 字段变更，正确响应状态。

8. 法律与免责声明 (Disclaimer)

• 责任限制：FnDepot 仅提供分发协议与索引服务。应用开发者需对其提交的代码安全性、稳定性及版权合规性负全部责任。
• 安全合规：严禁在应用源中包含恶意代码、后门程序或未经授权的侵权内容。违规仓库将被 FnDepot 索引服务拉黑并公示。
• 数据安全：开发者应在文档中明确告知用户应用的权限要求及潜在风险。

---

FnDepot Protocol Version 1.0