150 lines
6.2 KiB
Markdown
150 lines
6.2 KiB
Markdown
# 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`，每个应用拥有独立的子目录。
|
||
|
||
```text
|
||
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 数据结构
|
||
|
||
```json
|
||
{
|
||
"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 | ✅ | 版本更新记录。<br>**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)
|
||
|
||
```json
|
||
{
|
||
"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*
|