在 Windows 上使用 JuiceFS

注意

这是一份针对 JuiceFS 云服务的文档，如果你想了解如何在 Windows 上使用 JuiceFS 社区版请查看这里。

虽然在 Windows 上还可以通过 WSL 2 来使用 JuiceFS，但由于 WSL 2 需要硬件虚拟化，云主机往往无此条件，因此需要按照本文介绍的方式来使用 JuiceFS。

准备工作

目前 Windows 客户端不支持多用户，也就是说，A 账号挂载了 JuiceFS，只有 A 账号看得见这个挂载点，B 账号则没法使用。如果你的场景要求多账号使用同一个 JuiceFS 挂载点，请通过 Samba 在 Windows 上使用 JuiceFS，见下方相关章节。

安装依赖

安装以下依赖：

Windows 需要通过 WinFsp 带来 FUSE 支持，因此请先下载安装 WinFsp，如果下载不顺利，也可以直接从我们的镜像下载安装包（非最新版）。安装的时候请选择“全部安装”。
下载 juicefs.exe，也就是 JuiceFS 的 Windows 客户端。
下载 install.bat 到与 juicefs.exe 相同目录，然后双击执行安装。这个脚本的内容很简单，作用是为 WinFsp 增加 JuiceFS 配置，让我们可以通过 net use 命令挂载 JuiceFS。

如果你的系统启用了防火墙，则可能需要提前将 juicefs.exe 加入防火墙允许通过的应用列表中，JuiceFS 客户端的一些高级功能（比如缓存组）不可避免地涉及到需要客户端之间相互通信，因此需要在防火墙上进行放通。

配置 JuiceFS Windows 客户端

Windows 下无法使用 juicefs auth 命令来生成配置文件，需要从别处获取。在任意一台已经挂载了 JuiceFS 的 Linux 或者 macOS 机器上都能轻松获得（这台机器上最好不要有特殊的挂载配置，避免 Windows 客户端继承预期之外的特殊配置），配置文件是一个 JuiceFS 内的隐藏文件，假使挂载点为 /jfs，用这条命令获取配置文件模板：sudo cat /jfs/.jfsconfig > jfs.conf。

打开 jfs.conf，针对 Windows 机器情况修改部分参数：

CacheDir 需要视情况进行修改，比如 C:\jfsCache。
Mountpoint 挂载点可以用 * 替代，表示自动寻找某个可用的盘符。
如果配置文件的来源节点是通过 IAM 策略免密访问对象存储的，那么 jfs.conf 中将不包含对象存储的密钥，你需要自行添加 AccessKey / SecretKey。也正因此，我们推荐在先前步骤中获取一份包含完整认证信息的 jfs.conf。
如果配置文件缺少 Meta.Password，可以从 Linux / macOS 机器上查看 ~/.juicefs/$VOL_NAME.conf，从其中获取。
.jfsconfig 中的配置项，命名未必与 juicefs mount 的参数相仿，比如名为 --writeback 的挂载参数，实际对应着配置文件中的 AsyncUpload 字段。因此如果最初采集配置的机器开启了 --writeback，而你并不需要在 Windows 客户端启用，则需要调整该配置。
调整完毕以后，你也许会注意到，配置文件里仍有一些类似 "CommonPath": "/tmp/fuse_fd_comm.25029" 的配置，里边仍保留着 Unix file path，不用担心，这并不影响 Windows 客户端正常工作。

最后，将 jfs.conf 移动到 juicefs.exe 所在的目录，就可以开始操作挂载了。

挂载文件系统

Windows 上可以通过以下方法操作挂载：

前台挂载（任选其一）
- 双击运行 juicefs.exe，会弹出命令行窗口，观察到打印出 service started 就表示挂载成功，此时会出现一个新的盘符。
- 打开命令提示符终端或者 PowerShell，切换到 juicefs.exe 所在目录，执行：
```
.\juicefs.exe -c <volume>.conf -m Z:
```
后台挂载（任选其一）
- 打开命令提示符终端或者 PowerShell，运行 net use * \\juicefs\jfs 命令。
- 请参考 Windows 官方文档了解如何映射网络驱动器，其中「驱动器」可任意选择一个可用的驱动器号，「文件夹」填写 \\juicefs\jfs。

注意，如果 juicefs.exe 的运行用户和使用用户不匹配，会导致没有权限访问，这时候你需要修改运行用户：为 juicefs.exe 加上 -o uid=197108（本地管理员的 UID 是固定值，但你也可以为 juicefs.exe 加上 -trace * 参数，从日志里面再次确认运行用户）。

挂载多个子目录

在多用户场景下，我们可以为每一个用户生成不同的 JuiceFS 客户端令牌，并且配置好文件系统访问路径权限和用量配额，这些都可以在控制台的相应标签页方便配置。

配置子目录权限（ACL），注意子目录最后一级目录名应该是独一无二的，因为在后续的挂载命令中，JuiceFS 客户端会通子目录的最后一级目录名来查找配置文件，如果存在最后一级目录同名的情况，配置文件名将会冲突。

设置 ACL 时，子目录并不需要预先创建出来，挂载时会自动初始化。

ACL

控制配额：

quota

如果要为大量用户批量创建和设置令牌，可以使用控制台 API，通过脚本调用完成。

多用户的令牌和权限配置完毕，为每一个用户单独创建配置文件，就可以开始挂载了：

按照上方挂载单个文件系统的步骤，获取配置文件模板，保存成为 [subdir].conf，注意这里保存的配置文件名需要与子目录最后一级保持一致，以上方截图中权限受限的令牌为例，配置文件应保存为 team1.conf。
打开配置文件，修改 Meta.Subdir，其中 Subdir 就是子目录完整路径。
使用 net use T: \\juicefs\<VOL_NAME>\[subdir] 挂载即用可，其中 <VOL_NAME> 为文件系统的名称。以上方截图中权限受限的令牌为例，挂载命令如下：
```
net use T: \\juicefs\testvol\teams\team1
```

卸载文件系统

取决于 JuiceFS 文件系统的挂载方式，要用一下步骤卸载文件系统：

如果 juicefs.exe 在前台运行，可以直接 Ctrl+C 杀掉进程，完成卸载。
在驱动器上点右键，断开。该操作如果报错“此网络连接不存在”，可以继续尝试用下方的命令行方式操作卸载。
在 PowerShell 执行 net use，确认 JuiceFS 挂载盘符。
假设 JuiceFS 挂载到了 Z:，执行命令：net use Z: /delete。如果该节点只挂载了一个 JuiceFS 文件系统，也可以执行 net use * /delete 来卸载所有文件系统。
如果执行命令后发现 JuiceFS 挂载并未消失断开，可以打开任务管理器 - 详细信息，找到 juicefs 进程并结束（如果挂载了多个目录，将“命令行”一列显示出来，通过具体命令来定位到需要结束的进程）：

Samba 网关

挂载 JuiceFS

准备好用于运行 Samba 的 Linux 服务器后，参考快速上手创建和挂载 JuiceFS 文件系统。针对 Samba 场景，挂载的时候推荐做一些针对性的参数调优：

sudo juicefs mount smb-gateway /mnt/jfs \
  --update-fstab \
  --cache-dir /dev/shm \
  --no-posix-lock \
  --no-bsd-lock \
  --buffer-size 1000

部署 Samba 网关

安装 Samba 以及相关工具：

# Debian 及衍生版本
apt install -y samba cifs-utils

# RHEL 及衍生版本
yum install -y samba* cifs-utils

将挂载好的 JuiceFS 目录 /jfs 配置为共享目录，假设共享路径名字叫 juicefs（即可以通过 \\HOST\juicefs 访问到该目录），将以下内容添加到 /etc/samba/smb.conf：

/etc/samba/smb.conf
[juicefs]
    writable = yes
    browseable = yes
    read only = No
    comment = JuiceFS
    create mask = 0664
    directory mask = 0777
    guest ok = Yes
    path = /jfs
    read list = root
    valid users = root
    write list = root

配置完成后，启动 Samba：

systemctl enable --now {smb,nmb}
# 打印出监听端口，在对端确认网络畅通，如果无法访问，则先行解决网络或安全组问题
lsof -PiTCP | grep smb

为 Samba 添加 root 用户 smbpasswd -a root，会提示输入密码，设置密码。该用户便是之后在 Windows 上访问 Samba 所用的账号。

用类似下方命令验证 Samba 可以顺利挂载：

# 测试协议、网络畅通，打印出可供挂载的文件系统
smbclient -U root -L <Samba-IP>
# 推荐先在 Linux 下挂载，验证可用
mount -t cifs -o username=root,password=xxx //<Samba-IP>/juicefs /mnt/samba
# 在 Windows 下挂载
net use Z: \\<Samba-IP>\juicefs "<password>" /user:root

对于多节点 Samba 集群，我们建议避免采用 CTDB 搭建 Samba 集群，从实践看来在高并发场景下资源消耗较大。如果水平扩展需要，可以部署多个无状态的单个 Samba 节点，将这一系列 Samba 节点地址配置成同一个 DNS 域名，以 DNS 轮询方式来做负载均衡。

多用户支持

Samba 支持多用户，在配置文件中声明多个共享文件系统，并恰当配置每一个文件系统的子目录和用户，就能实现多用户支持，同时对每个用户的挂载目录进行控制。

配置文件的撰写也十分简单，注意所挂载的子目录需要提前创建好，相关用户也需要用 smbpasswd 创建并设置密码。

/etc/samba/smb.conf
[bob]
    writable = yes
    browseable = yes
    read only = No
    comment = JuiceFS for bob
    create mask = 0664
    directory mask = 0777
    guest ok = Yes
    path = /jfs/bob
    read list = bob
    valid users = bob
    write list = bob

[alice]
    writable = yes
    browseable = yes
    read only = No
    comment = JuiceFS for alice
    create mask = 0664
    directory mask = 0777
    guest ok = Yes
    path = /jfs/alice
    read list = alice
    valid users = alice
    write list = alice

问题排查

挂载 CIFS 失败

常见错误比如：

CIFS VFS: \\xxx\xxx BAD_NETWORK_NAME: \\xxx\xxx：说明文件系统名称不对，请用上方步骤中介绍的 smbclient 罗列出服务端可供挂载的文件系统，检查是否存在。
CIFS VFS: cifs_mount failed w/return code = -13：该错误码表明认证失败，请检查用户名和密码。

net use 命令报错

对于 JuiceFS Windows 客户端，通过 net use 挂载文件系统的能力是 WinFsp 提供的，因此当 net use 命令报错时，我们难以在 WinFsp 空间内排查和解决问题，这时候推荐直接用 juicefs.exe 前台运行模式挂载，可以加上 -v 参数打印更为丰富的日志：

.\juicefs.exe -c <volume>.conf -m Z: -v

由于 JuiceFS Windows 客户端不支持多用户，如果你已经用用户 A 挂载了 JuiceFS 或者 Samba，再用用户 B 挂载时，将会看到类似下方报错：

发生系统错误 1219.

不允许一个用户使用一个以上用户名与服务器或共享资源的多重连接。中断此服务器或共享资源的所有连接，然后再试一次。

此时需要检查是否还有窗口存在未关闭的网络连接，或者尝试通过 net use * /delete 命令断开网络连接。有关 net use 命令的详细说明请参考官方文档。

文件权限错误

挂载了 Samba，但遭遇类似 permission denied 错误，此时需要确保 SELinux 关闭。在所有 Samba 节点上执行：

setenforce 0
sed -i 's/SELINUX=enforcing/SELINUX=disabled/g' /etc/sysconfig/selinux
sed -i 's/SELINUX=enforcing/SELINUX=disabled/g' /etc/selinux/config

域账号无法访问 Samba 挂载点

用户 A 挂载了 Samba，用域账号 B 是无权限访问文件系统的。因此如果你的场景允许，请直接用 B 来执行挂载，这样一来，作为挂载的执行用户，B 就有权限访问挂载点，绕过了权限问题。

准备工作​

安装依赖​

配置 JuiceFS Windows 客户端​

挂载文件系统​

挂载多个子目录​

卸载文件系统​

Samba 网关​

挂载 JuiceFS​

部署 Samba 网关​

多用户支持​

问题排查​

挂载 CIFS 失败​

net use 命令报错​

文件权限错误​

域账号无法访问 Samba 挂载点​