# aarch64_nas_filemanager

**Repository Path**: windstarry/aarch64_nas_filemanager

## Basic Information

- **Project Name**: aarch64_nas_filemanager
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-13
- **Last Updated**: 2026-08-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# DinguxCommander (aarch64 / NAS 移植分支)

DinguxCommander 是一款面向掌机固件的「双栏 commander 风格」文件管理器，灵感来自
Norton Commander / Midnight Commander：左侧为源面板、右侧为目标面板，可在两栏间
复制、移动、删除文件。

本仓库是上游 [DinguxCommander](http://beyondds.free.fr/) 的**移植分支**，在保留原版
双栏操作体验的基础上，针对 Rocknix、ee4.7、darkOS 三个系统
做了如下扩展：

* **NAS 网络挂载桥**：通过 `networkManager` 支持 SMB/CIFS 与 NFS，挂载到 `<程序目录>/nas/<profile>`
  （基目录 `AppDir()` 为二进制所在目录，即 port 包内 `DinguxCommander_SDL2` 同级的 `nas/` 子目录；早期设计的 `/mnt/network` 路径已废弃），
  在 **X 键（System Actions 系统操作）菜单**中直接「连接 NAS / 断开 NAS」（随 `-DKORIKI` 编译；非 KORIKI 构建无此菜单）。
* **用户态 NFS 后端（libnfs）**：在 `INasBackend` 抽象之上实现 `UserspaceNfsBackend`，通过 vendored 的 libnfs 4.0.0 在用户态直接完成 NFS 读写，**无需设备内核 nfs 模块 / `mount.nfs`**，
  使 NAS 在 ArkOS、Buildroot 等缺失内核 NFS 能力的固件上可用；文件浏览 / 复制 / 移动 / 改名 / 删除 / 建目录 / 文本查看均按路径前缀路由到用户态后端，失败时自动回退 POSIX。
* **中文 CJK 字体**：`sdl_ttf_multifont` 多字体回退渲染（西文 `default.ttf` + 中文
  `DroidSansFallback.ttf`），菜单与文件名正确显示中文。
* **屏幕键盘（OSK）**：`keyboard` / `text_edit` 提供掩码输入，用于 NAS 登录名 / 密码。
* 图片查看器、文本查看器、文件类型图标等原有能力均保留。

## 功能特性

* 多选文件的复制、移动、删除
* 查看文件 / 执行文件
* 重命名文件或目录
* 新建目录
* 统计所选文件 / 目录占用的磁盘空间
* 显示磁盘信息（已用 / 可用 / 总计）
* 连接 / 断开 NAS（SMB、NFS；NFS 走用户态 libnfs 后端，无需内核 nfs 模块）

## 构建

前置条件：

* **aarch64 交叉编译工具链**在 `PATH` 中（或进入 `portmaster-builder:aarch64-latest` 构建容器）。
* SDL2 开发头文件与库：`SDL2` + `SDL2_image` + `SDL2_ttf` + `SDL2_gfx`。
* **libnfs（用户态 NFS 后端，已 vendoring 进仓库）**：无需在系统中安装，构建时由 `third_party/libnfs/` 提供头文件与共享库；若需从源码重建，执行
  `docker run --rm -v "$PWD":/work -w /work ghcr.io/monkeyx-net/portmaster-build-templates/portmaster-builder:aarch64-latest bash tools/build_libnfs.sh`
  （基于仓库内 `third_party/libnfs-4.0.0` 源码，**零下载**重建，仅当 `configure` 缺失时才 `./bootstrap`）。

构建某个目标：

```bash
make -f SDL2.aarch64.Makefile
# 产物： output/DinguxCommander_SDL2
```

清理构建产物：

```bash
make -f SDL2.aarch64.Makefile clean
```

## 部署到设备

构建产物可打包为自包含的设备端 port 包（`deploy/FileManager/`，结构沿用 OpenDingux 端口布局）：

```
deploy/FileManager/
├── FileManager.sh            # 启动器（修正二进制名、LF 换行、chmod +x 兜底）
├── DinguxCommander_SDL2      # aarch64 二进制（含用户态 NFS 后端）
├── commander.cfg             # 运行时配置（按键映射 / 默认路径 / 语言）
├── lib/                      # 自包含依赖（libarchive 闭包 + libnfs.so.13 等，均为真实文件）
└── res/                      # 字体与文件类型图标（default.ttf / DroidSansFallback.ttf / *.png）
```

将整个 `FileManager/` 目录复制到设备的端口目录（如 Rocknix 的
`/roms/ports/`），由前端（SimpleMenu / EmulationStation 等）作为端口启动，
或直接 `sh ./FileManager.sh`。
启动器导出 `LD_LIBRARY_PATH=$GAMEDIR/lib` 与 `SDL_TTF_FONT`，并以 `--res-dir "$GAMEDIR/res"`
定位资源，故整个目录可置于任意路径运行（路径无关）；二进制内置
`RUNPATH=$ORIGIN/lib`，属自包含发布，无需在系统层安装 SDL2_gfx / libnfs。

## NAS 真机能力探测与验证

`tools/verify-nas-device.sh` 用于在宿主机驱动真机上的 NAS 能力探测、部署与挂载自测：

```bash
# 1) 探测设备内核能力（cifs/nfs 模块、mount 工具、NAS 挂载基目录 AppDir()/nas 可写性）
NAS_SSH=root@<设备IP> ./tools/verify-nas-device.sh probe

# 2) 一键串联：探测 →（若达门禁 A）部署 tarball →（可选）挂载自测
NAS_SSH=root@<设备IP> ./tools/verify-nas-device.sh all

# 3) 单独对某个协议做裸挂载自测
NAS_SSH=root@<设备IP> ./tools/verify-nas-device.sh selftest SMB   # 需设 NAS_HOST/NAS_SHARE/NAS_USER/NAS_PASS
NAS_SSH=root@<设备IP> ./tools/verify-nas-device.sh selftest NFS
```

传输通道三选一：SSH（`NAS_SSH=user@host`，可加 `NAS_SSH_PORT`）、ADB（`NAS_ADB=1`）、
或已挂载 SD 卡（`NAS_SD=/mnt/sdcard/App`，脚本会暂存并给出手动步骤）。

门禁判定（见 `deliverables/gstack/` 下的架构决策文档 ADR-001 §5）：
SMB 需内核 `cifs` 模块 + `mount.cifs`；NFS 需 `nfs` 模块 + `mount.nfs`。
达到「门禁 A」时才走内核挂载桥；否则 SMB 需补用户态 `libsmbclient` 降级（MVP 未做用户态 NFS）。

> 注：自用户态 NFS 后端（libnfs）落地后，**NFS 不再依赖内核 `nfs` 模块 / `mount.nfs`**，
> 上述门禁仅对 SMB/CIFS 的内核挂载路径生效；NFS 走 `UserspaceNfsBackend` 在用户态直接读写。

## 目录结构

```
.
├── src/                       # 全部源码（commander 核心 + networkManager / 多字体 / 键盘）
├── res/                       # 字体与文件类型图标（default.ttf, DroidSansFallback.ttf, *.png）
├── SDL2.aarch64.Makefile       # 构建配置（aarch64 / SDL2，已接入 vendored libnfs）
├── third_party/                # vendored 依赖（libarchive / libnfs 源码与编译产物）
├── tools/
│   ├── verify-nas-device.sh   # NAS 真机探测 / 部署 / 自测驱动
│   └── build_libnfs.sh        # 基于仓库源码重建 libnfs（零网络下载）
├── deploy/FileManager/        # 自包含设备端 port 包（二进制 + lib/ + res/ + 启动脚本）
├── 文件管理工具-Commander/    # 旧版 port 包布局（历史遗留，优先用 deploy/）
├── deliverables/gstack/       # 架构决策与实现文档（ADR、NAS 挂载设计、探测脚本等）
└── LICENSE.txt
```

## 近期进展（dev 分支）

本分支近期围绕「用户态 NFS 后端」完成了一系列改造，主要成果：

* **用户态 NFS 后端（libnfs 4.0.0，vendoring 进仓库）**：新增 `INasBackend` 抽象
  + `UserspaceNfsBackend` + `NasBackendRegistry`（按路径前缀路由到对应后端单例），
  浏览器 / 复制 / 移动 / 改名 / 删除 / 建目录 / 文本查看均自动路由到用户态 NFS，
  失败时回退 POSIX。设备无需内核 nfs 模块或 `mount.nfs`。
* **健壮性与线程安全**：libnfs 上下文操作加锁修复竞态；共享路径前导 `/` 规范化；
  预览前预检，>64 MiB 或音视频文件直接拒绝预览以避免 tmpfs OOM；分块流式传输支持中途取消。
* **下载进度 / 速度实时上报（修复）**：流式拷贝新增每 1 MiB 块的 `onProgress` 回调，
  实时累加进进度计数，进度对话框可正确显示百分比与 EMA 速度（此前 NAS 下载进度条冻结、速度为 0）。
* **构建链自包含**：libnfs 以源码形式入库（`third_party/libnfs-4.0.0`），并提供
  `tools/build_libnfs.sh` 从仓库源码零下载重建到 `third_party/libnfs`；
  `SDL2.aarch64.Makefile` 已接入 vendored libnfs 头文件 / 库与打包。
* **部署包**：`deploy/FileManager/` 为自包含 port 包（二进制 + `lib/` 依赖 + `res/` + `commander.cfg` + 启动脚本）。

## 操作按键

* D-pad         Move
* L1 / R1       Page up / page down
* L2 / R2       Page to top / page to bottom
* A             For a directory: open
  For a file: view or execute
* B             Go to parent directory / cancel
* X             System actions:
  - Select all items
  - Select no items
  - Create new directory
  - Display disk information
  - Quit program
* Y             Actions on selected items:
  - Copy to destination directory
  - Move to destination directory
  - Rename (appears only if 1 item is selected)
  - Delete
  - Display disk used
* SELECT        Select highlighted item.
  Selected items are displayed in red.
* START         Open highlighted directory in destination panel.
  If a file is highlighted, open current directory in destination panel.

> 以上为 `commander.cfg` 中 `gamepad_*` 的默认映射，可按设备 / 手感在其中重映射
> （改完即生效，且退出时会被持久化保存，无需重编）。
> Rocknix（SDL2）构建下，「连接 NAS / 断开 NAS」菜单项随 `-DKORIKI` 编译进
> `X`（系统操作）菜单。

本 aarch64 / NAS 分支在 upstream 基础上增加了 NAS 挂载桥、CJK 多字体渲染与屏幕键盘，
相关架构与实现决策记录在 `deliverables/gstack/` 中。