rclone 接入 Enterprise File Fabric（filefabric 后端）完整指南：配置、Token 体系与同步行为解析

Enterprise File Fabric 是 Storage Made Easy 推出的文件与对象存储统一软件层，可以把多种底层存储整合成一个全局文件系统供用户访问。本文以当前仓库（rclone 官方源码）为基准，系统讲解 rclone 中 filefabric 后端的完整接入流程：从浏览器获取永久 Token、通过 rclone config 交互式建 remote，到文件列表、目录拷贝、时间戳精度、空文件处理、受限字符编码等关键同步语义，并深入 rclone ls/rclone copy 之外值得注意的实现细节（会话 Token 生命周期、服务端复制/移动、版本探测）。读完本文，你将能够独立配置并安全地使用 rclone 同步 Enterprise File Fabric 上的数据，并在排查问题时直接定位到对应源码。

Enterprise File Fabric 与 filefabric 后端

Storage Made Easy 的 Enterprise File Fabric 是一种企业级软件方案，用于“集成并统一各类文件和对象存储，并通过一个全局文件系统对外提供服务”。也就是说，用户面对的是统一命名空间，而背后可能是 S3、本地 NAS、各类云盘等混合存储。

rclone 从 v1.54 起内置了名为 filefabric 的后端（官方文档称其为 “Enterprise File Fabric”）。在 rclone 中，所有后端都通过注册表登记，filefabric 后端的注册逻辑位于 backend/filefabric/filefabric.go：Name: "filefabric"，用户交互时选择 Storage> filefabric 即可。

与很多后端“输入 Access Key / Secret”不同，filefabric 的鉴权模型是永久认证 Token（Permanent Authentication Token）+ 短时会话 Token（Session Token） 两级结构：

1. 用户在浏览器里、从 Enterprise File Fabric 的控制台生成一个永久 Token；
2. rclone 用永久 Token 换取一个通常有效 1 小时的会话 Token；
3. 后续所有 API 调用都携带会话 Token，会话过期后 rclone 会自动用永久 Token 再次换取。

一、交互式配置流程

1.1 准备永久 Token

在浏览器中登录 Enterprise File Fabric，进入用户 Dashboard 的 Security（安全） 区域，找到 "My Authentication Tokens"（我的认证 Token） 条目，点击 Manage 按钮创建一个永久 Token。这类 Token 通常有效期长达数年。

1.2 运行 rclone config

执行交互式配置：

rclone config

随后按提示一步步操作，典型会话如下（[snip] 表示省略了无关的存储类型列表）：

No remotes found, make a new one?
n) New remote
s) Set configuration password
q) Quit config
n/s/q> n
name> remote
Type of storage to configure.
Enter a string value. Press Enter for the default ("").
Choose a number from below, or type in your own value
[snip]
XX / Enterprise File Fabric
   \ "filefabric"
[snip]
Storage> filefabric
** See help for filefabric backend at: https://rclone.org/filefabric/ **

URL of the Enterprise File Fabric to connect to
Enter a string value. Press Enter for the default ("").
Choose a number from below, or type in your own value
 1 / Storage Made Easy US
   \ "https://storagemadeeasy.com"
 2 / Storage Made Easy EU
   \ "https://eu.storagemadeeasy.com"
 3 / Connect to your Enterprise File Fabric
   \ "https://yourfabric.smestorage.com"
url> https://yourfabric.smestorage.com/
ID of the root folder
Leave blank normally.

Fill in to make rclone start with directory of a given ID.

Enter a string value. Press Enter for the default ("").
root_folder_id>
Permanent Authentication Token

A Permanent Authentication Token can be created in the Enterprise File
Fabric, on the users Dashboard under Security, there is an entry
you'll see called "My Authentication Tokens". Click the Manage button
to create one.

These tokens are normally valid for several years.

For more info see: https://docs.storagemadeeasy.com/organisationcloud/api-tokens

Enter a string value. Press Enter for the default ("").
permanent_token> xxxxxxxxxxxxxxx-xxxxxxxxxxxxxxxx
Edit advanced config? (y/n)
y) Yes
n) No (default)
y/n> n
Remote config
Configuration complete.
Options:
- type: filefabric
- url: https://yourfabric.smestorage.com/
- permanent_token: xxxxxxxxxxxxxxx-xxxxxxxxxxxxxxxx
Keep this "remote" remote?
y) Yes this is OK (default)
e) Edit this remote
d) Delete this remote
y/e/d> y

几个要点：

• name> remote 只是示例，你可以起任意名字，后面所有命令都用这个名字。
• url 提供 3 个内置示例：Storage Made Easy US（https://storagemadeeasy.com）、Storage Made Easy EU（https://eu.storagemadeeasy.com），以及你自己的企业实例（形如 https://yourfabric.smestorage.com）。自建实例必须输入企业自己的 URL。
• root_folder_id 一般直接留空（见下文“Root folder ID”一节）。
• permanent_token 粘贴第 1.1 节创建的永久 Token。
• 此时选择 n 跳过高级配置即可；需要自定义编码、查看自动缓存项时才选 y。

在源码层面，url 在 NewFs 中会被去掉尾部 / 再做规范化（strings.TrimSuffix(opt.URL, "/")），若为空则直接报错 url must be set；permanent_token 与 root_folder_id 在选项声明中被标记为 Sensitive，写入配置时会加密保存。

1.3 配置完成后立即使用

假设 remote 名为 remote：

列出 Enterprise File Fabric 顶层目录：

rclone lsd remote:

列出 Enterprise File Fabric 中所有文件：

rclone ls remote:

把本地目录 /home/source 拷贝到 fabric 中的 backup 目录：

rclone copy /home/source remote:backup

二、全部配置选项详解

filefabric 后端的选项定义集中在 backend/filefabric/filefabric.go，对应的运行时结构体是 Options（同文件 L137-L146）。标准选项在 rclone config 的基本流程中出现，高级选项需要选择 “Edit advanced config” 才会看到。

2.1 标准选项（Standard options）

命令行 Flag	Config 键	环境变量	类型	必填	说明
--filefabric-url	url	RCLONE_FILEFABRIC_URL	string	是	要连接的 Enterprise File Fabric URL
--filefabric-root-folder-id	root_folder_id	RCLONE_FILEFABRIC_ROOT_FOLDER_ID	string	否	根文件夹 ID，一般留空
--filefabric-permanent-token	permanent_token	RCLONE_FILEFABRIC_PERMANENT_TOKEN	string	否	永久认证 Token

--filefabric-url

URL of the Enterprise File Fabric to connect to.（要连接的 Enterprise File Fabric 的 URL。）

• Config：url
• Env Var：RCLONE_FILEFABRIC_URL
• Type：string
• Required：true
• Examples：
  • https://storagemadeeasy.com：Storage Made Easy US
  • https://eu.storagemadeeasy.com：Storage Made Easy EU
  • https://yourfabric.smestorage.com：连接到你的企业 File Fabric

--filefabric-root-folder-id

ID of the root folder.（根文件夹的 ID。）

Leave blank normally.（通常留空。）

Fill in to make rclone start with directory of a given ID.（填入后，rclone 将从指定 ID 的目录开始工作。）

• Config：root_folder_id
• Env Var：RCLONE_FILEFABRIC_ROOT_FOLDER_ID
• Type：string
• Required：false

--filefabric-permanent-token

Permanent Authentication Token.（永久认证 Token。）

A Permanent Authentication Token can be created in the Enterprise File Fabric, on the users Dashboard under Security, there is an entry you'll see called "My Authentication Tokens". Click the Manage button to create one.（在 Enterprise File Fabric 用户 Dashboard 的 Security 项下找到 “My Authentication Tokens”，点 Manage 按钮即可创建。此类 Token 通常有效数年。）

• Config：permanent_token
• Env Var：RCLONE_FILEFABRIC_PERMANENT_TOKEN
• Type：string
• Required：false

2.2 高级选项（Advanced options）

命令行 Flag	Config 键	环境变量	类型	默认值	说明
--filefabric-token	token	RCLONE_FILEFABRIC_TOKEN	string	（自动）	会话 Token，rclone 自动写入配置
--filefabric-token-expiry	token_expiry	RCLONE_FILEFABRIC_TOKEN_EXPIRY	string	（自动）	会话 Token 过期时间
--filefabric-version	version	RCLONE_FILEFABRIC_VERSION	string	（自动）	从 fabric 读取到的软件版本
--filefabric-encoding	encoding	RCLONE_FILEFABRIC_ENCODING	Encoding	Slash,Del,Ctl,InvalidUtf8,Dot	后端文件名编码规则
--filefabric-description	description	RCLONE_FILEFABRIC_DESCRIPTION	string	空	remote 的描述（通用选项）

--filefabric-token

Session Token.（会话 Token。）

This is a session token which rclone caches in the config file. It is usually valid for 1 hour.（这是 rclone 缓存在配置文件中的会话 Token，通常有效期为 1 小时。）

Don't set this value - rclone will set it automatically.（不要手动设置，rclone 会自动写入。）

• Config：token
• Env Var：RCLONE_FILEFABRIC_TOKEN
• Type：string
• Required：false
• Advanced：是

源码中会话 Token 的“有效期 1 小时”由常量 tokenLifeTime = 55 * time.Minute 体现——rclone 把过期点设为换发后 55 分钟，留出 5 分钟余量，见 backend/filefabric/filefabric.go 与 getToken。token 获取成功后会立即回写 token 与 token_expiry 到配置文件（f.m.Set(...)）。

--filefabric-token-expiry

Token expiry time.（Token 过期时间。）

Don't set this value - rclone will set it automatically.

• Config：token_expiry
• Env Var：RCLONE_FILEFABRIC_TOKEN_EXPIRY
• Type：string
• Required：false
• Advanced：是

过期时间以 RFC3339 格式存盘；在 NewFs 中会被解析回内存（backend/filefabric/filefabric.go），若解析失败只会告警而不会中断启动。

--filefabric-version

Version read from the file fabric.（从 File Fabric 读取的版本号。）

Don't set this value - rclone will set it automatically.

• Config：version
• Env Var：RCLONE_FILEFABRIC_VERSION
• Type：string
• Required：false
• Advanced：是

版本号来自 RPC 方法 getApplianceInfo 返回的 softwareversionlabel（对应 API 结构体 ApplianceInfo 定义于 backend/filefabric/api/types.go），并写入配置以便下次启动时复用、免去一次网络请求（getApplianceInfo）。

版本号并非可有可无的元信息：setCapabilities() 用字符串比较版本（backend/filefabric/filefabric.go）来决定后端能力——版本 ≥ 2006.02 时，修改时间精度为 1 秒且支持“拷贝时改名”（canCopyWithName）；更老的版本在重命名时可能漂移时间，精度退化为 1 小时，并且服务端复制不允许改名。这直接决定了文件时间戳比较的严格程度与服务端 Copy 的可用性。

--filefabric-encoding

The encoding for the backend.（后端的编码规则。）

See the encoding section in the overview for more info.

• Config：encoding
• Env Var：RCLONE_FILEFABRIC_ENCODING
• Type：Encoding
• Default：Slash,Del,Ctl,InvalidUtf8,Dot
• Required：false
• Advanced：是

--filefabric-description

Description of the remote.（对 remote 的描述，方便在 rclone listremotes 等场景识别用途。）

• Config：description
• Env Var：RCLONE_FILEFABRIC_DESCRIPTION
• Type：string
• Required：false
• Advanced：是

description 属于所有后端通用的基础选项，声明于 fs/registry.go，可用于为每个 remote 补充自由文本说明。

三、直接编辑配置文件 / 使用环境变量

除交互式 rclone config 外，也可以直接编辑 rclone 配置文件，或用环境变量注入。配置片段示例：

[remote]
type = filefabric
url = https://yourfabric.smestorage.com/
root_folder_id =
permanent_token = xxxxxxxxxxxxxxx-xxxxxxxxxxxxxxxx

使用环境变量的等价写法：

export RCLONE_FILEFABRIC_URL="https://yourfabric.smestorage.com/"
export RCLONE_FILEFABRIC_PERMANENT_TOKEN="xxxxxxxxxxxxxxx-xxxxxxxxxxxxxxxx"

环境变量名规则为 RCLONE_ + 后端名大写 + _ + 选项名大写（以连字符分隔的选项转成下划线）。会话 Token、Token 过期时间等自动缓存字段也会写入该 remote 的配置节中，供重启后复用。

四、Root folder ID：把某个子目录当作根

root_folder_id 是 rclone 视为“File Fabric 根”的那个目录（由它的 Folder ID 标识）。

• 留空（默认）：rclone 自己探测并使用正确的根。源码中默认值为 defaultRootID = ""，NewFs 会据此建立目录缓存 dircache.New(f.root, opt.RootFolderID, f)（backend/filefabric/filefabric.go）。
• 填值：可把 rclone 限制在某个特定的目录树内，对只管理某个子空间（如备份目录）非常有用。

4.1 如何找到 Folder ID

Web 界面并不直接展示 Folder ID，但可以用 rclone lsf 查出来。示例（-F ip 表示输出格式为 i（对象 ID）+ p（路径），--dirs-only 只看目录，--csv 输出 CSV 便于解析）：

$ rclone lsf --dirs-only -Fip --csv filefabric:
120673758,Burnt PDFs/
120673759,My Quick Uploads/
120673755,My Syncs/
120673756,My backups/
120673757,My contacts/
120673761,S3 Storage/

那么 "S3 Storage" 这一层的 ID 就是 120673761。lsf 的 --format 字符集见 cmd/lsf/lsf.go：p 为路径、i 为对象 ID、s 为大小、t 为修改时间等。拿到 ID 后即可：

rclone config
# 编辑 remote，将 root_folder_id 填为 120673761

或直接改配置文件后执行 rclone lsd remote:，此时 rclone 看到的顶层就会变成 S3 Storage 目录。

五、时间戳、哈希与同步判定行为

5.1 修改时间（Modification time）

Enterprise File Fabric 允许把文件的修改时间设置到秒级精度。rclone 用这些时间来判断对象是否需要同步。对象元数据中同时存在 fi_modified 与 fi_localtime 两个时间字段，setMetaData 优先采用非零的 fi_localtime，否则回落到 fi_modified（backend/filefabric/filefabric.go）。

修改时间通过 RPC doModifyFile 下发，格式为 UTC 的 2006-01-02 15:04:05（参数时间格式定义于 backend/filefabric/api/types.go，SetModTime 见 backend/filefabric/filefabric.go）。

需要再次强调：时间戳的“可信”精度取决于 fabric 软件版本（见 2.2 节 --filefabric-version）。新版（≥ 2006.02）为 1 秒精度，因此开启增量同步比较是可靠的；老版本精度为 1 小时，同步时可能出现“时间差在 1 小时内却判定为已同步/不同步”的边界情况。

5.2 哈希（Hashes）

Enterprise File Fabric 当前不支持任何数据哈希。 源码中 Fs.Hashes() 返回 hash.None（backend/filefabric/filefabric.go），Object.Hash() 一律返回 hash.ErrUnsupported（同文件 L1078-L1081）。

这带来一个实际影响：rclone check、rclone sync 等需要“内容校验”的场景无法用 md5/sha1 比对，rclone 会退化为“按大小 + 修改时间”比较。若你确实需要端到端数据完整性校验，建议先同步到本地（或某个支持哈希的后端）后再跑一次 checksum。

六、文件名限制与编码

6.1 受限字符

与其他后端一致，filefabric 使用 rclone 的 默认受限字符替换机制：当检测到云端不允许的字符时，rclone 会透明地把它们替换成形似的 Unicode 全角字符，并在下载/解析时反向还原。filefabric 后端的默认编码是：

Slash,Del,Ctl,InvalidUtf8,Dot

即默认替换 /、DEL、全部控制字符（0x00–0x1F）、非法 UTF-8 字节，以及作为完整文件名的 . / ..（防止与当前目录、父目录产生歧义）。更细的说明与可调字符集见 docs/content/overview.md。

6.2 非法 UTF-8 字节

fabric 的 API 走 JSON 传输，JSON 字符串必须合法 UTF-8，因此非法 UTF-8 字节也会被替换（invalid-utf8 规则），例如 latin1 等非 UTF-8 本地文件系统产生的文件名会先被编码为合法形式再上传。

若需要调整编码行为，可在高级配置中修改 encoding（--filefabric-encoding），例如完全关闭编码用 --filefabric-encoding Raw。注意：编码规则同时作用于“列出目录时解码”与“上传/建目录时编码”，代码中分别通过 Enc.ToStandardName/Enc.ToStandardPath 与 Enc.FromStandardName/Enc.FromStandardPath 完成双向转换，参见 listAll 与 CreateDir。

七、空文件（Empty files）的处理约定

Enterprise File Fabric 本身不支持真正的空文件。rclone 的应对策略是：

• 上传空文件时，把它作为一个包含单个空格的文件上传，并赋予一个特殊 MIME 类型 application/vnd.rclone.empty.file；
• 读取阶段，凡是带有该 MIME 类型的文件都被 rclone 视作空文件。

这与源码中的实现完全对应：

• 常量 emptyMimeType = "application/vnd.rclone.empty.file"（backend/filefabric/filefabric.go）；
• 上传时若 size == 0，contentType 被强制设为 emptyMimeType（backend/filefabric/filefabric.go），随后写入 fi_contenttype；
• Size() 读到该 MIME 时返回 0（同文件 L1090-L1093）；
• Open() 读到该 MIME 时直接返回空 Reader，不再走下载 RPC（同文件 L1186-L1201）。

也就是说，对用户而言 remote: 里的空文件行为是自洽的：rclone ls 显示 0 字节，rclone cat/下载得到空内容。

八、底层实现纵深：RPC、Token 生命周期与上传/复制管线

8.1 一切皆走 /api/rpc.php

所有 API 调用都由 rpc() 统一封装（backend/filefabric/filefabric.go）：方法 POST 到 <url>/api/rpc.php，请求体为 application/x-www-form-urlencoded，携带 function（方法名）、token（会话 Token）、apiformat=json 及方法参数。每次调用都经由 pacer 节流并处理重试：

• 可重试的 HTTP 状态码集合包含 429/500/502/503/504/509（L207-L215）；
• 业务错误码 login_token_expired 会触发 Token 失效标记，从而在下次调用前自动刷新（shouldRetry）；
• 特定后台错误（error_background）会按 2 的指数递增地额外休眠等待（L217-L230）。

8.2 会话 Token 的自动刷新机制

getToken()（backend/filefabric/filefabric.go）按以下顺序判断是否需要换发新会话 Token：

1. 上次调用发现 login_token_expired；
2. 内存中 Token 为空（首次使用）；
3. tokenExpiry 早于当前时间（或配置里读到的 token_expiry 已过期）。

需要刷新时调用 getTokenByAuthToken，把 authtoken（永久 Token）交给 fabric，换回新的会话 Token；随后把新 Token 与新过期时间写回配置文件，并顺带调用 getApplianceInfo 刷新版本信息。整个流程加锁保护（tokenMu），多个协程并发时不会重复换发。

8.3 目录缓存与路径解析

rclone 对“路径 → 目录 ID”建立缓存（lib/dircache）。新建 Fs 时如果 root_folder_id 留空，则从空 root 开始按需逐级解析；目录 ID 在 List 的过程中被缓存进 dirCache（backend/filefabric/filefabric.go），从而减少后续查询次数。另外：

• 后端声明了 CaseInsensitive: true 特性——目录查找使用大小写不敏感匹配（FindLeaf 中 strings.EqualFold）；
• 若构造 remote 的根路径本身是文件而非目录，NewFs 会返回 fs.ErrorIsFile，此时 rclone 会正确地把该文件当作单文件 remote 处理（见 backend/filefabric/filefabric.go）。

8.4 上传的三阶段管线

Object.Update()（backend/filefabric/filefabric.go）展示了 filefabric 的上传流程：

1. doInitUpload：初始化上传。文件名做编码处理；fi_localtime/fi_modified 都带上目标时间；fi_size 已知则一并上报；返回 uploadcode。
2. PUT 数据：直接把文件体 PUT 到 /cgi-bin/uploader/uploader1.cgi/<base64文件名>?<uploadcode>；若中途出错或进程被中断，会调用 doAbortUpload 取消上传（通过 lib/atexit 保证善后）。
3. doCompleteUpload：携带 uploadcode、远端时间与服务器回报的文件大小完成收尾；若 fabric 返回的 MIME 与本地推断不一致，还会追加一次 doModifyFile 修正 fi_contenttype。

值得一提的细节：上传阶段会发送本地通过 fs.MimeType 推断的 Content-Type；这对应后端特性声明 WriteMimeType: true，因此 rclone 可以在后续 serve http/WebDAV 等场景回读 MIME（ReadMimeType: true）。

8.5 服务端操作：复制、移动与回收站

Fs 还实现了一批可选接口（文件末尾的接口断言）：

• 服务端复制 Copy：调用 doCopyFile，并携带 options=allownoextension 防止 fabric 给无扩展名文件乱加后缀；新版（canCopyWithName）才允许在复制时改名。
• 服务端移动 Move / DirMove：内部先判断“是否换目录”和“是否改名”，若两者都发生，会先把对象改成一个带随机后缀的临时名字再移动，最后改回目标名，从而避免覆盖目标目录中的同名文件（见 move()，backend/filefabric/filefabric.go）。文件用 doMoveFiles/doRenameFile，目录用 doMoveFolders/doRenameFolder。
• 移动/改名是异步任务：涉及移动的操作通过 getUserBackgroundTasks 轮询后台任务直到完成（waitForBackgroundTask，backend/filefabric/filefabric.go）。
• 清空回收站 CleanUp：对应 RPC emptyTrashInBackground。
• Rmdir 与 Purge：分别对应“非空检查后删除目录”（doDeleteFolder）与“无条件删除”；文件删除走 doDeleteFile，删除时 completedeletion=n，即文件先进回收站。

由于后端声明 CanHaveEmptyDirectories: true，空目录可以被保留与传输，这与 S3 等“无目录概念”的后端行为不同。

九、测试与验证

rclone 仓库针对 filefabric 提供了一套基于 fstest 框架的集成测试入口：backend/filefabric/filefabric_test.go 通过 fstests.Run 对名为 TestFileFabric: 的 remote 跑全套文件系统接口测试（覆盖建目录、读写、改名、移动、删除、时间戳等行为）。如果你自建了 fabric 实例，可仿照该文件用 rclone config 建好 TestFileFabric remote 后运行：

go test ./backend/filefabric/ -run TestIntegration

以此验证你的环境与 rclone 版本的兼容性。API 响应结构体集中定义于 backend/filefabric/api/types.go，排查“某个返回字段没被使用”时可直接在这里确认字段映射。

十、常见问题速查

现象	原因与排查
报错 url must be set	url 未配置，见 NewFs
会话中 Token 自动刷新、日志出现 Token expired - refreshing	正常现象：会话 Token 有效 55 分钟，到期自动用永久 Token 换发
同步后文件时间与源端偏差在 1 小时以内	fabric 版本过老（< 2006.02），时间精度被降为 1 小时
rclone check 无法做哈希比对	后端不支持任何哈希（hash.None），只能按大小+时间比对
空文件显示为 0 字节但实际云端为 1 个空格	设计如此：以 application/vnd.rclone.empty.file 标记空文件
中文/全角标点文件名行为异常	文件名编码默认 Slash,Del,Ctl,InvalidUtf8,Dot，可通过 --filefabric-encoding 调整（详见 encoding 说明）

小结

filefabric 后端让 rclone 可以像操作本地文件系统一样操作 Storage Made Easy 的 Enterprise File Fabric：配置上只需 URL + 永久 Token，运行期会话 Token 自动维护；同步语义上支持秒级时间戳（受软件版本影响）、不支持哈希、对空文件与受限文件名有专门约定。阅读对应源码（后端主体 backend/filefabric/filefabric.go、API 结构体 backend/filefabric/api/types.go、集成测试 backend/filefabric/filefabric_test.go）即可在任何层级精确理解它的行为边界，从而安全地把它纳入你的备份与同步体系。