文件组件提供对本地文件的读写操作，支持文件读取、写入、删除和列表查询。

1. 文件读取 (fileRead)

读取指定路径的文件内容。支持读取单个文件或使用 Glob 模式批量读取多个文件。

配置

字段	说明	类型	默认值
path	文件路径或 Glob 模式，支持变量替换。如果是相对路径，优先相对于 context 中的 workDir，如果未配置，则相对于当前进程工作目录。	string	/tmp/data.txt
dataType	数据类型，支持 text 和 base64。	string	text
recursive	是否递归查找子目录，默认 false。仅在 path 使用 Glob 模式时有效。	boolean	false

示例

读取单个文件

{
  "path": "/tmp/data.txt",
  "dataType": "text"
}

批量读取

{
  "path": "/tmp/*.log",
  "dataType": "text"
}

批量读取时，多个文件的内容将通过换行符 \n 拼接。

2. 文件写入 (fileWrite)

将数据写入到指定文件。

配置

字段	说明	类型	默认值
path	文件路径，支持变量替换。如果是相对路径，优先相对于 context 中的 workDir，如果未配置，则相对于当前进程工作目录。	string	/tmp/data.txt
content	写入的内容，支持变量替换。	string/binary	${data}
append	是否追加写入。	boolean	false

示例

{
  "path": "/tmp/output.txt",
  "content": "${data}",
  "append": true
}

3. 文件删除 (fileDelete)

删除指定的文件。

配置

字段	说明	类型	默认值
path	文件路径或 Glob 模式，支持变量替换。如果是相对路径，优先相对于 context 中的 workDir，如果未配置，则相对于当前进程工作目录。	string	/tmp/data.txt

输出

执行成功后，会在 metadata 中增加 deletedCount 字段，表示删除的文件数量。

4. 文件列表 (fileList)

列出匹配指定模式的文件路径列表。

配置

字段	说明	类型	默认值
path	文件路径模式，支持变量替换。如果是相对路径，优先相对于 context 中的 workDir，如果未配置，则相对于当前进程工作目录。	string	/tmp/*.txt
recursive	是否递归查找子目录。	boolean	false

输出

返回一个包含文件路径的 JSON 数组字符串。

5. 动态路径与常用函数

组件配置（如 path）支持使用 ${} 语法进行变量替换和函数调用。您可以使用 now() 函数来创建基于时间的文件夹或文件。

• now()

  返回当前时间的 time.Time 值。

  例如：now().Year() == 2024

更多函数参考 Expr 语言定义 (opens new window)。

示例

创建包含日期的文件路径：

./${now().Format("20060102")}/data.txt

内容换行示例

在写入文件内容时，如果需要添加换行符，可以使用如下语法：

${msg.data+'\n'}

安全性与风险提示

File 组件提供了强大的文件系统操作能力，但也带来了潜在的安全风险。

⚠️ 风险提示

1. 默认无限制：默认情况下（未配置 filePathWhitelist），File 组件可以访问和修改运行进程权限范围内的任何文件。
2. 误删风险：fileDelete 组件结合 Glob 模式（如 *）使用时，如果配置不当，可能导致大量文件被误删。
3. 系统文件风险：如果 RuleGo 进程以 root 或管理员权限运行，恶意或错误的配置可能导致系统关键文件（如 /etc/passwd, C:\Windows\System32 下的文件）被读取、修改或删除，导致系统崩溃或敏感信息泄露。

🛡️ 最佳实践

为了降低风险，请务必遵循以下最佳实践：

1. 权限控制（白名单与工作目录）

   RuleGo 提供了路径白名单和工作目录两种机制共同进行文件访问控制：

   • 配置路径白名单（强制推荐）：在生产环境中，配置 filePathWhitelist，将文件操作严格限制在特定的业务目录下。这是防止非法访问系统文件的基础防线。

     // 只允许访问 /tmp 和 /var/log/myapp 目录下的文件
     config.Properties.PutValue("filePathWhitelist", "/tmp,/var/log/myapp,/data/*/log")
     

   • 利用工作目录（WorkDir）：通过动态设置 workDir，可以将相对路径限制在指定目录下。实现安全的多租户隔离。

2. 多租户权限控制

   在多租户场景下，可以通过 types.WithContext(ctx) 动态传递 workDir，从而控制当前请求的文件操作根目录。这可以实现不同用户或租户的文件隔离。

   // 在执行规则链时，通过 Context 传递当前租户的工作目录
   // KeyWorkDir = "workDir"
   ctx := context.WithValue(context.Background(), "workDir", "/data/tenant_123")
   ruleEngine.OnMsg(msg, types.WithContext(ctx))
   

   当组件配置的 path 为相对路径（如 data.txt）时，File 组件会优先将其解析为 ${workDir}/data.txt（例如 /data/tenant_123/data.txt），从而确保租户只能访问其授权目录下的文件。

3. 最小权限原则

   不要以 root 或 Administrator 身份运行 RuleGo 进程。创建一个专用的低权限用户，并只授予其对必要目录（如配置的白名单目录）的读写权限。

4. 容器化隔离

   建议在 Docker 或 K8s 容器中运行 RuleGo。通过 Volume 挂载，仅将宿主机的特定目录映射到容器内，利用容器的隔离特性限制文件系统的访问范围。

5. 输入校验

   如果 path 或 content 字段使用了变量替换（如 ${data}），请确保输入数据的来源是可信的，或在规则链的前置节点中对数据进行严格的校验和清洗，防止路径遍历攻击（尽管白名单机制可以防御路径遍历，但多重防御更为安全）。

6. 谨慎使用 Glob 删除

   在使用 fileDelete 组件时，尽量指定精确的文件路径。如果必须使用 Glob 模式，请务必进行严格的测试，并确保匹配模式不会意外覆盖到父目录或其他重要文件。