flutter_nfs

一个高性能、跨平台的 Flutter 用户态 (User-Space) NFS 客户端，基于 libnfs 构建。

传统的 NFS 挂载通常依赖于操作系统内核支持（在移动设备上通常需要 Root 权限），而 flutter_nfs 完全运行在用户态应用程序进程中。这使得它非常适合需要在无特权环境下访问网络存储的应用场景，例如游戏模拟器、媒体播放器或文件管理器。

🚀 核心特性

用户态实现: 完全运行在应用层，无需 Root 权限，无需内核驱动支持。
跨平台: 支持 Android、iOS、macOS、Windows 和 Linux。
高性能:
- 零拷贝架构 (Zero-Copy): 数据直接从网络 Socket 读取到 Dart Uint8List 缓冲区，最大限度减少内存拷贝。
- 块缓存 (Block Cache): 内置 128KB 环形缓冲区缓存，优化顺序读取性能（特别适合流媒体或模拟器加载 ROM）。
- 连接池: 高效管理 nfs_context 连接。
异步与线程安全: 所有操作均在独立的后台 Isolate 中运行，确保 UI 线程始终保持 60fps 流畅。
API 功能全面: 支持 NFSv3/v4 协议，包括文件创建、写入、目录列表和权限管理。

📦 安装

在 pubspec.yaml 中添加 flutter_nfs：

dependencies:
  flutter_nfs: ^0.1.0

🛠️ 使用指南

1. 初始化

初始化客户端以启动后台 Worker Isolate。

import 'package:flutter_nfs/flutter_nfs.dart';

final client = NfsClient();
await client.init();

2. 连接 NFS 服务器

使用 URL 挂载 NFS 共享目录。支持标准的 nfs:// 协议格式。

// 格式: nfs://<server>/<export_path>
await client.mount('nfs://192.168.1.100/volume1/shared');

注意: 默认情况下，libnfs 可能会尝试使用特权端口。对于非 Root 环境（移动设备常见情况），请确保您的 NFS 服务器允许非安全端口（通常在 /etc/exports 中配置 insecure 选项）。

3. 文件操作

列出目录

final entries = await client.listDir('/');
for (var entry in entries) {
  print('${entry.name} - ${entry.isDirectory ? "目录" : "文件"}');
}

读取文件

// 从偏移量 0 读取 1024 字节
final bytes = await client.read('/data.txt', 0, 1024);

写入文件

final content = utf8.encode('Hello NFS');
// 写入数据到偏移量 0
await client.write('/new_file.txt', content, 0);

文件管理

// 创建文件夹
await client.mkdir('/new_folder');

// 创建空文件
await client.createFile('/new_folder/empty.txt');

// 重命名/移动
await client.rename('/new_folder/empty.txt', '/new_folder/renamed.txt');

// 删除文件
await client.delete('/new_folder/renamed.txt');

🏗️ 架构设计

flutter_nfs 采用分层架构以确保安全性和性能：

Dart API (NfsClient): 运行在主 Isolate 中的高级异步 API。
Worker Isolate: 专用的后台线程，处理所有 FFI 调用，防止阻塞 UI。
FFI Bridge: Dart ffi 绑定层，连接原生 C 函数。
Native Core (libnfs):
- Shared Library: 处理 NFS 协议 (RPC, XDR) 的 C 库。
- NfsPool: 连接池管理器，支持多并发上下文。
- BlockCache: C++ 实现的环形缓冲区，通过预读取减少小 IO 调用次数。

🧩 支持的操作

操作	描述
`mount`	连接挂载 NFS 共享。
`listDir`	列出目录内容及元数据。
`read`	读取文件字节范围。
`write`	写入数据到文件。
`createFile`	创建新空文件。
`mkdir`	创建新目录。
`delete`	删除文件 (`unlink`)。
`rmdir`	删除目录。
`rename`	重命名或移动文件/目录。
`truncate`	截断/调整文件大小。
`chmod`	修改文件权限。
`chown`	修改文件所有者。
`stat`	获取文件大小和属性。

📝 许可证

本项目采用 MIT 许可证。内部使用的 libnfs 库采用 LGPL/GPL 许可证。

FilesExpand file tree

README_CN.md

Latest commit

History