# fn-rustfs

**Repository Path**: dragonlhp/fn-rustfs

## Basic Information

- **Project Name**: fn-rustfs
- **Description**: RustFS for fnOS：把 RustFS（Rust 编写的高性能 S3 兼容对象存储）打包为飞牛 fnOS 应用，内置版本检查/一键升级/版本回退能力。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-01
- **Last Updated**: 2026-10-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# RustFS for fnOS

把 [RustFS](https://github.com/rustfs/rustfs)（Rust 编写的高性能 S3 兼容对象存储）打包成
飞牛 fnOS 应用，并在应用内提供**版本检查 / 一键更新 / 版本回退**能力。

- 应用包名：`rustfs`
- 内置内核：RustFS `linux-x86_64` **musl 静态版**（见下文「为什么必须用 musl」）
- 运行依赖：`nodejs_v24`（用于版本管理服务；RustFS 本体为独立静态二进制）
- 访问方式：控制台走独立端口（默认 `9001`），版本管理页走 fnOS 统一网关 `/app/rustfs`

---

## 一、功能概览

| 能力 | 说明 |
| --- | --- |
| 对象存储服务 | RustFS 内核，S3 API 默认监听 `9000`，Web 控制台默认监听 `9001` |
| 控制台入口 | 应用卡片 →「RustFS 控制台」，**在 fnOS 桌面窗口内内嵌打开**（iframe，非新标签页） |
| 版本管理 | 应用卡片 →「RustFS 版本管理」（仅管理员），检查更新 / 一键升级 / 回退 / 启停 |
| 数据目录 | 共享目录 `rustfs/data`，可在文件管理器中查看；应用通过 `TRIM_DATA_SHARE_PATHS` 定位 |
| 安装向导 | 收集 Access Key、Secret Key、S3 端口、控制台端口、GitHub 加速代理 |
| 安全 | 进程以专用包用户 `rustfs` 运行；管理接口仅管理员可用 |

### 两个桌面入口的设计

| 入口 | 类型 | 地址 | 说明 |
| --- | --- | --- | --- |
| `rustfs.console` | `iframe`（桌面窗口内） | `/app/rustfs/console`（网关） | 管理服务**反向代理**到控制台端口，页面内嵌打开 |
| `rustfs.manager` | `iframe`（桌面窗口内） | `/app/rustfs`（网关） | 版本管理页面，含在新标签页打开控制台的按钮 |

### 控制台为什么要走反向代理

RustFS 控制台是一个 Next.js 应用，有三个特性决定了它不能简单地用 `url` 型入口直接打开：

1. 它使用 **`/rustfs/console/...` 绝对资源路径**，无法直接挂在 `/app/rustfs` 这样的网关子路径下；
2. 它监听在**独立端口**上，而 fnOS 桌面是 **HTTPS**（默认 `https://<host>:5667`），
   在 iframe 里加载 `http://<host>:9001` 会被浏览器按**混合内容**拦截；
3. fnOS 入口配置 **不支持** `${wizard_xxx}` 占位符（实测会原样写入应用中心数据库），
   端口无法直接写进入口。

因此由管理服务做一层**同源反向代理**：

```
浏览器  https://<host>:5667/app/rustfs/console/xxx      ← 与桌面同源，https，可内嵌
   ↓  网关转发到 app.sock
管理服务  http://127.0.0.1:<控制台端口>/rustfs/console/xxx
   ↓  返回文本响应时把 /rustfs/console 改写为 /app/rustfs/console
```

已确认控制台**不使用 WebSocket / EventSource**，也不设置 CSP / `X-Frame-Options`，
JS 中的接口地址由 `location.href` / `origin` 推导，因此该方案可完整工作，
并且**无论安装时把控制台端口改成什么，内嵌入口都始终可用**。

---

## 二、为什么必须用 musl 静态版（重要）

fnOS 基于 Debian 12（glibc **2.36**）。而 RustFS 的 `gnu` 构建要求 **glibc ≥ 2.38/2.39**，
在 fnOS 上直接运行会报：

```
./rustfs: /lib/x86_64-linux-gnu/libc.so.6: version `GLIBC_2.38' not found
```

因此本应用固定使用 **musl 静态链接**发行包：

```
rustfs-linux-x86_64-musl-latest.zip      # 最新
rustfs-linux-x86_64-musl-v<版本>.zip     # 指定版本
```

`scripts/fetch-rustfs.sh` 与版本管理服务都默认使用 musl（可用 `RUSTFS_LIBC=gnu` 覆盖，
但不建议在 fnOS 上使用）。

---

## 三、目录结构

```
fn-rustfs/
├── README.md
├── rustfs.fpk                      # 构建产物（fnpack build 生成）
├── scripts/
│   ├── fetch-rustfs.sh             # 下载 RustFS 发行版二进制到应用包
│   ├── make-icons.py               # 生成图标（纯标准库，无 Pillow）
│   └── build.sh                    # 一键构建 .fpk
├── tools/
│   └── fnpack                      # 打包工具（Linux amd64，1.2.3）
└── rustfs/                         # fnOS 应用包目录
    ├── manifest                    # 应用元数据
    ├── ICON.PNG / ICON_256.PNG     # 应用图标
    ├── app/
    │   ├── bin/
    │   │   ├── rustfs              # 内置内核二进制
    │   │   └── rustfs.version      # 内置内核版本号
    │   ├── manager/                # 版本管理服务（Node.js，零第三方依赖）
    │   │   ├── server.js           # HTTP 服务（监听 Unix Socket）
    │   │   ├── lib/updater.js      # 版本检查 / 下载 / 校验 / 安装 / 回滚
    │   │   ├── lib/zip.js          # 纯 Node.js 实现的 ZIP 流式解压
    │   │   └── public/             # 管理页面（HTML/CSS/JS）
    │   └── ui/                     # 桌面入口配置与图标
    ├── cmd/                        # 生命周期脚本
    ├── config/
    │   ├── privilege               # 运行身份（package/rustfs）
    │   └── resource                # 共享数据目录声明
    └── wizard/                     # 安装 / 升级 / 卸载 / 配置向导
```

---

## 四、构建

```bash
cd fn-rustfs

# 1) 下载 RustFS 内核（默认最新版 musl）
./scripts/fetch-rustfs.sh

#    指定版本 / 更换加速代理 / 关闭代理
RUSTFS_VERSION=1.0.0 ./scripts/fetch-rustfs.sh
GH_PROXY=https://ghfast.top/ ./scripts/fetch-rustfs.sh
GH_PROXY= ./scripts/fetch-rustfs.sh

# 2) 一键构建（含图标生成、JSON 校验、fnpack 打包）
./scripts/build.sh
```

产物：`rustfs.fpk`（约 95 MB，内核约 253 MB 压缩后）。

### 下载源策略

`fetch-rustfs.sh` 与运行时更新都按以下顺序尝试：

1. **官方镜像** `https://dl.rustfs.com/artifacts/rustfs/release/...`（通常最快，无需代理）
2. **GitHub 加速代理**（如 `https://ghproxy.net/`、`https://gh-proxy.com/`、`https://ghfast.top/`）
3. **GitHub 直连**

---

## 五、安装与验证

```bash
# 安装（默认端口 9000 / 9001）
appcenter-cli install-fpk rustfs.fpk

# 端口被占用时，可通过向导变量文件指定其它端口
cat > config.env <<'EOF'
wizard_access_key=rustfsadmin
wizard_secret_key=rustfsadmin123
wizard_s3_port=19100
wizard_console_port=19101
wizard_gh_proxy=
EOF
appcenter-cli install-fpk rustfs.fpk --env config.env

# 启动 / 停止 / 查看
appcenter-cli start rustfs
appcenter-cli stop rustfs
appcenter-cli list
```

安装后在 fnOS 桌面即可看到「RustFS 控制台」与「RustFS 版本管理」两个入口。

---

## 六、应用内更新机制

「RustFS 版本管理」页面提供：

1. **检查更新**：读取 GitHub Releases 最新版本号（GitHub API 直连失败时自动切换到加速代理）；
2. **更新到最新版本**：一键下载、校验、安装、重启。**发现新版本时该按钮才会亮起**；
3. **回退到随包版本**：删除应用内更新的内核，恢复使用应用包内置版本；
4. **按指定版本更新**：无法访问 GitHub API 的环境下，手动填写版本号直接安装；
5. **重启 / 启动 / 停止**：控制 RustFS 本体；
6. **运行日志 / 更新记录**：便于排查。

### 更新流程（与 RustFS 官方安装脚本一致的思路）

```
确定版本 → 下载发行包 → SHA256 校验 → 解压出 rustfs → 试运行 --version 验证
        → 备份当前内核 → 覆盖安装 → 重启服务 → 失败则自动回滚
```

关键点：

- **先下载校验、后停服务**，避免下载失败导致服务不可用；
- 覆盖前备份到 `var/bin/rustfs.bak`，新版本启动失败会**自动回滚**；
- 安装前用 `rustfs --version` 预验证，可立即发现 glibc/架构不匹配等问题；
- 若 GitHub 提供了 `sha256` 摘要，会强制校验文件完整性。

### 版本优先级规则

| 位置 | 说明 |
| --- | --- |
| `var/bin/rustfs` | **应用内更新后的内核（优先使用）** |
| `target/bin/rustfs` | 应用包内置内核（回退兜底） |

应用包升级时（`cmd/upgrade_callback`）会比较两者版本：
**内置版本 ≥ 应用内版本时丢弃覆盖版本**，否则保留应用内更新的较新内核，
避免「升级应用包把用户已更新的内核降级」。

---

## 七、配置说明

安装向导写入的配置保存在 `${TRIM_PKGETC}/rustfs.env`：

| 变量 | 默认值 | 说明 |
| --- | --- | --- |
| `RUSTFS_ACCESS_KEY` | `rustfsadmin` | S3 / 控制台登录密钥 ID |
| `RUSTFS_SECRET_KEY` | `rustfsadmin` | S3 / 控制台登录密钥，**上线后请务必修改** |
| `RUSTFS_S3_PORT` | `9000` | S3 API 端口 |
| `RUSTFS_CONSOLE_PORT` | `9001` | 控制台端口（内嵌入口自动跟随，改后无需改其它文件） |
| `RUSTFS_VOLUME` | 空 | 留空时使用共享目录 `rustfs/data` |
| `RUSTFS_LOG_LEVEL` | `error` | RustFS 日志级别 |
| `RUSTFS_GH_PROXY` | `https://ghproxy.net/` | GitHub 加速代理前缀，留空表示直连 |

> 本机若已安装 MinIO（同样占用 `9000/9001`），安装向导中请改填其它端口，
> 例如 S3 `19100`、控制台 `19101`。

修改密钥或端口：在「应用设置」中重新保存即可（会重写该文件并重启应用）；
也可以手动编辑该文件后重启应用：

```bash
echo 'RUSTFS_SECRET_KEY="your-strong-secret"' >> /var/apps/rustfs/etc/rustfs.env
appcenter-cli stop rustfs && appcenter-cli start rustfs
```

---

## 八、常见问题

**1）启动失败：端口被占用**

```
控制台端口 9001 已被占用，请修改配置后重试。
```

在「应用设置」中改端口，或先停止占用端口的应用。

**2）`GLIBC_2.xx not found`**

说明使用了 gnu 构建。请改用 musl 构建重新打包：

```bash
RUSTFS_LIBC=musl ./scripts/fetch-rustfs.sh && ./scripts/build.sh
```

**3）检查更新失败 / 下载很慢**

在「版本管理 → 高级选项」中更换 GitHub 加速代理，或留空表示直连；
官方镜像 `dl.rustfs.com` 始终优先尝试。也可用「按指定版本更新」绕过 GitHub API。

**4）控制台打不开**

确认应用处于「运行中」，并确认 `http://<NAS 地址>:<控制台端口>/rustfs/console/` 可访问；
若 NAS 防火墙限制了该端口，请放行。

**5）默认密钥不安全**

`rustfsadmin/rustfsadmin` 仅用于首次安装，请立即在安装向导或应用设置中改为强密钥。

---

## 九、开发调试

```bash
# 单独调试版本管理服务（本机 TCP 端口，不走网关）
cd rustfs/app/manager
TRIM_PKGVAR=/tmp/rustfs-dev MANAGER_PORT=18080 \
RUSTFS_BIN_BUNDLED=$PWD/../bin/rustfs \
RUSTFS_BIN_OVERRIDE_DIR=/tmp/rustfs-dev/bin \
/var/apps/nodejs_v24/target/bin/node server.js
# 浏览器访问 http://127.0.0.1:18080/app/rustfs
```

生命周期脚本可脱离 fnOS 自行调用（会自动根据脚本位置推导目录）：

```bash
/var/apps/rustfs/cmd/main start|stop|status|restart
/var/apps/rustfs/cmd/main rustfs-restart|rustfs-wait
```

---

## 十、参考

- RustFS 项目：<https://github.com/rustfs/rustfs>
- RustFS 官方安装/升级脚本思路：<https://rustfs.com/install_rustfs.sh>
- fnOS 应用开发文档：飞牛应用开放平台
- 目录与入口约定参考了本机已安装的 `fn-deepseek-harness` 与 `minio` 应用

## 十一、本机部署记录

本机（thinknas）已于 2026-10-01 完成实测部署，使用端口：

| 项 | 值 |
| --- | --- |
| 应用名 | `rustfs` |
| S3 API | `19100` |
| 控制台 | `19101`（`http://<NAS>:19101/rustfs/console/`） |
| 数据目录 | `/vol1/@appshare/rustfs/data` |
| 运行数据 | `/vol1/@appdata/rustfs`（应用内更新的内核在 `var/bin`） |

> 9000/9001 已被同机 MinIO 占用，故改用 19100/19101。

卸载：

```bash
appcenter-cli uninstall rustfs    # 或从 fnOS 应用中心卸载
```