From 2caa3f1b9b372bb04eec5fc96560a8433b9de306 Mon Sep 17 00:00:00 2001 From: heppen Date: Thu, 21 Dec 2023 16:54:04 +0800 Subject: [PATCH] add README --- README.md | 179 ++++++++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 154 insertions(+), 25 deletions(-) diff --git a/README.md b/README.md index d2664df..a237930 100644 --- a/README.md +++ b/README.md @@ -1,37 +1,166 @@ -# filemanagement_dfs_service +# hmdfs 分布式文件系统 -#### 介绍 -Distributed file services provide cross device, POSIX compliant file access capabilities. On the basis of distributed soft bus dynamic networking, it provides a unified, logical, and tree shaped file system hierarchy for each device node on the network. +分布式文件系统提供跨设备的文件访问能力，适用于如下场景： -#### 软件架构 -软件架构说明 +- 两台设备组网，A 设备可以无感读取和修改 B 设备的文件。 +- 边缘服务器可以自动同步组网中多个嵌入式设备中的文件数据。 -#### 安装教程 +hmdfs 在分布式软总线动态组网的基础上，为网络上各个设备结点提供一个全局一致的访问视图，支持开发者通过基础文件系统接口进行读写访问，具有高性能、低延时等优点。 -1. xxxx -2. xxxx -3. xxxx +其包括如下几个核心模块: -#### 使用说明 +- distributed_file_daemon：分布式文件管理常驻用户态服务，负责接入设备组网、数据传输能力，并负责挂载 hmdfs。 -1. xxxx -2. xxxx -3. xxxx +- hmdfs(Harmony Distributed File System)：分布式文件系统核心模块，是一种面向移动分布式场景的、高性能的、基于内核实现的、堆叠式文件系统。 -#### 参与贡献 +## 约束 -1. Fork 本仓库 -2. 新建 Feat_xxx 分支 -3. 提交代码 -4. 新建 Pull Request +### 接口支持情况 +分布式文件管理当前不支持或有限支持如下 VFS 系统调用： -#### 特技 +- symlink：不支持。 +- mmap：仅支持读。 +- rename：仅支持同目录操作。 -1. 使用 Readme\_XXX.md 来支持不同的语言，例如 Readme\_en.md, Readme\_zh.md -2. Gitee 官方博客 [blog.gitee.com](https://blog.gitee.com) -3. 你可以 [https://gitee.com/explore](https://gitee.com/explore) 这个地址来了解 Gitee 上的优秀开源项目 -4. [GVP](https://gitee.com/gvp) 全称是 Gitee 最有价值开源项目，是综合评定出的优秀开源项目 -5. Gitee 官方提供的使用手册 [https://gitee.com/help](https://gitee.com/help) -6. Gitee 封面人物是一档用来展示 Gitee 会员风采的栏目 [https://gitee.com/gitee-stars/](https://gitee.com/gitee-stars/) +### 规格 + +- 最大目录层级 + + 与被堆叠文件系统，即 data 分区所用文件系统，如 ext4、f2fs 等保持一致。 +- 最大文件名长度 + + 取决于 680B 与被堆叠文件支持长度的最小值。f2fs 和 ext4 均为 255B。 +- 最大单文件大小 + + 取决于 $2^{64}$B 与被堆叠文件系统支持最大单文件大小的最小值。ext4 单文件最大为 16TB，f2fs 单文件最大为 3.94TB。 + +### 环境约束 + +- 运行环境的有线网卡名称必须是 `eth0` ，无线网卡的名称必须是 `wlan0` 。可使用 `ip a` 命令查看当前环境的网卡名称，如果没有 `eth0` 或者 `wlan0` 的网卡，那么 softbus_server 会启动失败，功能失效。解决方案参考 [常见问题](#常见问题)。 + +- openEuler 的内核版本需要是 5.10.x，可以通过使用 `uname -r` 查看内核版本。 + +- openEuler 各个设备在同一个网段中，并且设备之间网络通畅，防火墙未拦截 softbus 的数据包。 + +## 说明 + +### 安装 + +说明：如果碰到步骤未成功执行，可参考后面 [常见问题](#常见问题) 进行解决。 + +1. 完整地使用分布式文件系统，需要安装 `hmdfs` 和 `filemanagement_dfs_service` 两个软件包。使用以下命令安装： + ```shell + sudo dnf install hmdfs filemanagement_dfs_service + ``` + +1. 安装 hmdfs 文件系统。安装 hmdfs 之后会提供一个 `hmdfs.ko` 文件，其存放在 `/lib/modules/$(uname -r)/hmdfs` 目录下，需要插入该 ko 来安装 hmdfs 文件系统： + ```shell + cd /lib/modules/$(uname -r)/hmdfs + insmod hmdfs.ko + ``` + + *注意: 如果 /lib/modules/$(uname -r)/hmdfs/ 目录下没有 hmdfs.ko 文件，是因为 hmdfs 工程构建时依赖的内核版本和当前运行环境内核版本不一致，可以在 /lib/modules 其他内核版本目录下查找 hmdfs.ko 文件* + + *注意: 如果是树莓派环境，请直接使用 [基于 22.03-LTS-SP3 raspberry-pi kernel 编译出来的 hmdfs.ko](https://gitee.com/heppen/hmdfs_test/blob/dev/out/hmdfs_sp3_rasp.ko)* + +### 配置 + +1. 后续有服务启动依赖 `libsec_shared.z.so` 这个动态库，而在 openEuler 下这个动态库叫做 `libboundscheck.so`（由 `libboundscheck` 软件包提供），因此需要在 `/usr/lib64` 下软链接出一个 `libsec_shared.z.so`： + ```shell + ln -s /usr/lib64/libboundscheck.so /usr/lib64/libsec_shared.z.so + ``` + +1. 配置每个设备的 SN 号。目前 `softbus_sever` 等服务获取设备的 `udid` 还是使用 `/etc/SN` 文件中设置的 SN 号，因此需要在每台 openEuler 设置 **不同的 SN 号**。 + ```shell + echo "111" > /etc/SN # 注意：不同设备设置不同的数值 + ``` + +### 使用 + +分布式文件系统的使用分为两块：` 挂载 hmdfs 目录 ` 和 ` 启动 distributed_file_daemon 服务 `。注意：**以下步骤需要在每台 openEuler 设备下执行**。 + +#### 挂载 hmdfs 目录 + +1. 挂载 hmdfs 目录，可以直接使用 `mount` 命令进行挂载，保持 OpenHarmony 的目录结构一样，挂载 `/data/service/el2/100/non_account` 到 `/mnt/hmdfs/100/non_account`。 + ```shell + mkdir -p /data/service/el2/100/non_account + mkdir -p /mnt/hmdfs/100/non_account + sudo mount -t hmdfs -o merge,local_dst="/mnt/hmdfs/100/non_account" "/data/service/el2/100//non_account" "/mnt/hmdfs/100/non_account" + ``` + + 挂载之后，可以使用 `df -h` 命令查看新增了挂载的目录，并且挂载目录下会有 `device_view` 和 `merge_view` 两个目录： + ```txt + ├── device_view + │   └── local + └── merge_view + ``` + +#### 启动 dfs_service 服务 + +安装 `filemanagement_dfs_service` 及其依赖的软件包后，相关的可执行二进制会存放在 `/system/bin/` 目录下，库文件会存放在 `/system/lib64` 下。 + +1. 启动 `dfs_service` 分布式文件服务： + + ```shell + cd /system/bin + ./start_services.sh dfs + ``` + +1. 停止 `dfs_service` 分布式文件服务： + + ```shell + cd /system/bin + ./stop_service.sh dfs + ``` + +### 功能使用 + +每台 openEuler 设备启动完 distributed_file_daemon 之后，可以在挂载的 `/mnt/hmdfs/100/non_account` 下看到远端设备的目录（示例是只有两台 openEuler 设备互联）： +```txt +├── device_view +│   ├── fceda1e26c36d1dd0ba65c00d71c1ab619fcf088ad2adf33cd1e2f396dc70ee2 +│   └── local +└── merge_view +``` + +⽬录下会有两个⽂件视图：device_view 是分设备的视图，local 是本地⽂件视图，另外⼀个是远端设备的⽂件视图；merge_view 是合并视图，多个设备的⽂件都在这⼀个⽬录。 + +后续需要跨设备进行⽂件操作，只需要操作 device_view 下⾯远端设备⽬录下的⽂件即可。 + +## 常见问题 + +* 启动各个服务日志一直在报错 `Binder Driver died`。 + + 原因：说明系统未开启 binder，可以查看 `/dev/binder` 文件是否存在，如果不存在则说明未开启 binder。 + + 解决办法：参考 [communication_ipc 仓 openEuler-22.03-LTS-SP3 分支的 README](https://gitee.com/src-openeuler/communication_ipc/blob/openEuler-22.03-LTS-SP3/README.md) 开启 binder。 + +* 无法插入 `hmdfs.ko` 文件，报错 `insmod: ERROR: could not insert module hmdfs.ko: Invalid parameters`。 + + 原因：hmdfs 编译时依赖的 kernel 版本和现在运行环境不一致或者当前系统未开启。 + + 解决方法一：编译一个和运行环境内核匹配的 `hmdfs.ko`，然后插入该 ko 文件使用。 + + 解决方法二：更换和 SP3 的 kernel 版本一致的 openEuler 版本。 + +* 树莓派 22.03-LTS-SP3 openEuler版本下，无法插入 `hmdfs.ko` 文件，报错 `insmod: ERROR: could not insert module hmdfs.ko: Invalid module format`. + + 原因：树莓派使用的 kernel 版本是树莓派特有版本，而 repo 源中 hmdfs 软件在工程构建时依赖的是服务器 22.03-LTS-SP3 版本的内核，所以无法插入。 + + 解决方法：使用 [基于 22.03-LTS-SP3 raspberry-pi kernel 编译出来的 hmdfs.ko](https://gitee.com/heppen/hmdfs_test/blob/dev/out/hmdfs_sp3_rasp.ko) + +* `softbus_server` 服务未成功起来，报错 `GetNetworkIfIp ifName:eth0 fail`。 + + 原因：使用命令 `ip a` 查看当前系统的网卡名称，查看是否有 `eth0` 有线网卡名。 因为 `softbus_server` 是通过 `eth0` 这个有线网卡名来获取 ip 等信息，如果没有 `eth0` 网卡则无法启动 `softbus_server`。 + + 解决方法一：修改网卡名称为 `eth0`。 + + 解决方法二：修改 `softbus_server` 源码，将依赖的有线网卡名称改成当前系统的网卡名。 + +* 多台 openEuler 设备拉起 `softbus_server` 服务之后，但是在 `distributed_file_daemon` 服务的日志显示未发现上线设备。 + + 原因：设备之间的网络不通，或者开启了防火墙把 `softbus` 的数据拦截了。 + + 解决：检查网络是否通畅。（如果不影响业务，可通过 `systemctl stop firewalld.service` 暂时关闭防火墙进行测试）。 -- Gitee