通过EFC加速OSS访问

运行环境

硬件资源要求

EFC 客户端会占用计算节点的内存和磁盘。请根据是否开启缓存功能来规划资源。

• 未开启缓存功能

  • 内存：常驻内存占用通常小于 1 GiB，建议系统预留至少 5 GiB 可用内存以应对突发负载。

  • 磁盘：无特殊空间要求，仅需保证系统盘有足够空间存储运行日志。

• 开启缓存功能 

  开启缓存后，资源占用主要由缓存介质和索引开销构成。

  • 内存资源

    • 基础占用：同“未开启缓存”模式。

    • 内存缓存：若配置内存作为缓存，将直接占用与配置大小相等的内存。

    • 索引开销：无论使用内存还是磁盘缓存，都需要额外内存维护数据索引。建议预留量约为缓存总容量的 1‰。

    • 计算公式： 总内存占用 ≈ 基础运行内存 + 内存缓存大小 + (内存缓存大小 + 磁盘缓存大小) * 0.001

  • 磁盘资源：

    • 磁盘缓存：若配置磁盘作为缓存介质，将占用配置大小的磁盘空间（例如配置 1 TiB 磁盘缓存，则占用 1 TiB）。

功能限制

• 访问模式：仅支持对 OSS 数据的只读访问。挂载后文件的所有者固定为 root，权限为只读，不支持 chmod 或 chown。

• POSIX 兼容性：兼容 open、close、read、readdir、readdirplus、lookup、getattr 操作；不支持 readlink、write、rename、setattr、link、symlink 等操作。

• 存储类型：仅支持访问标准和低频访问存储类型的 Object。不支持直接访问归档、冷归档或深度冷归档存储类型。

• 路径兼容性：

  • 路径冲突：若 OSS 中同时存在 a/b（文件）和 a/b/（目录），挂载后仅能访问目录 a/b/。

  • 特殊路径：无法访问 Object Key 以 / 开头、包含连续 // 或包含 . / .. 的对象。

• 访问权限：挂载和访问 OSS 至少需要 oss:GetBucketStat、oss:ListObjects、oss:GetObject 权限。

• 数据高可用性：EFC 是只读缓存，不保障数据高可用。缓存数据在特定情况（如机器损坏、节点替换下线等）下可能丢失，引起缓存失效。再次访问对应数据时，会发生回源，引起性能波动。

配置一：基础挂载（快速验证）

此配置用于快速验证 EFC 是否能正常访问您的 OSS Bucket，不启用缓存加速。

使用 STS 凭证挂载（推荐）：

# 创建本地挂载点
mkdir -p /mnt/oss_data

# 执行挂载（请替换为您的 Bucket 域名）
mount -t alinas \
  -o efc,protocol=oss,g_oss_STSFile=/etc/passwd-sts \
  your-bucket.oss-cn-hangzhou.aliyuncs.com:/ /mnt/oss_data

使用 AccessKey 挂载：

# 创建本地挂载点mkdir -p /mnt/oss_data

# 执行挂载（请替换为您的 Bucket 域名）
mount -t alinas \
  -o efc,protocol=oss,passwd_file=/etc/passwd-oss \
  your-bucket.oss-cn-hangzhou.aliyuncs.com:/ /mnt/oss_data

命令解析：

• mount -t alinas：使用 EFC 客户端（alinas 类型）挂载。

• your-bucket.oss-cn-hangzhou.aliyuncs.com:/ /mnt/oss_data：挂载目标配置。其中 your-bucket.oss-cn-hangzhou.aliyuncs.com 是您的 OSS Bucket 域名，/mnt/oss_data 是本地挂载点。

• g_oss_STSFile=/etc/passwd-sts：指定包含 STS 凭证的配置文件路径。

• passwd_file=/etc/passwd-oss：指定包含 OSS AccessKey 的密码文件路径。

更多参数说明请参考挂载参数详解。

验证挂载结果：

# 检查挂载是否成功
df -h | grep /mnt/oss_data
# 列出 OSS 中的文件
ls /mnt/oss_data

如果能看到您 OSS Bucket 中的文件，说明基础挂载成功。接下来可以根据需要启用缓存加速。

配置二：单机缓存模式

在基础挂载的基础上，启用本节点的内存和磁盘缓存，适用于单节点任务或快速测试。

说明：如果您已完成基础挂载，需要先卸载：umount /mnt/oss_data

# 创建磁盘缓存目录
mkdir -p /mnt/cache/

# 挂载并启用单机缓存（使用 STS 凭证）
mount -t alinas \
  -o efc,protocol=oss,g_oss_STSFile=/etc/passwd-sts \
  -o g_tier_DadiIsDistributed=false \
  -o g_tier_DadiMemCacheCapacityMB=1024 \
  -o g_tier_DadiDiskCacheCapacityMB=10240 \
  -o g_tier_DadiDiskCachePath=/mnt/cache/ \
  -o g_server_Port=17871 \
  your-bucket.oss-cn-hangzhou.aliyuncs.com:/ /mnt/oss_data

命令解析：

• mount -t alinas ... your-bucket.oss-cn-hangzhou.aliyuncs.com:/ /mnt/oss_data：使用 EFC 客户端将 OSS Bucket 挂载到本地 /mnt/oss_data 目录。

• g_oss_STSFile=/etc/passwd-sts：指定包含 STS 凭证的配置文件路径。

• g_tier_DadiIsDistributed=false：单机缓存模式，不与其他节点通信。

• g_tier_DadiMemCacheCapacityMB=1024：分配 1 GB 内存用于缓存数据。

• g_tier_DadiDiskCacheCapacityMB=10240：分配 10 GB 磁盘空间用于缓存数据。

• g_tier_DadiDiskCachePath=/mnt/cache/：磁盘缓存文件存放目录。

• g_server_Port=17871：开放 17871 端口，以便后续使用命令行工具查看缓存命中率或执行数据预热。

更多参数说明请参考挂载参数详解。

配置三：分布式缓存集群模式

将多个节点组成一个缓存集群，共享缓存数据，通过 P2P 网络加速数据分发，适用于大规模训练和推理的生产环境。

1. 配置缓存节点列表

在所有节点上创建 /etc/efc/rootlist 文件，填入集群中所有节点的信息：

# 格式: <唯一ID>:<节点内网IP>:<P2P端口>
1:192.168.1.1:17980
2:192.168.1.2:17980
3:192.168.1.3:17980

警告：rootlist 文件在集群中必须完全一致。不一致可能导致部分节点无法加入缓存网络、缓存命中率下降。

2. 在所有节点执行挂载

# 创建磁盘缓存目录
mkdir -p /mnt/cache/

# 挂载并启用分布式缓存（使用 STS 凭证）
mount -t alinas \
  -o efc,protocol=oss,g_oss_STSFile=/etc/passwd-sts \
  -o g_tier_EnableClusterCache=true \
  -o g_tier_DadiIsDistributed=true \
  -o g_tier_DadiAddr=/etc/efc/rootlist \
  -o g_tier_DadiMemCacheCapacityMB=1024 \
  -o g_tier_DadiDiskCacheCapacityMB=10240 \
  -o g_tier_DadiDiskCachePath=/mnt/cache/ \
  -o g_server_Port=17871 \
  your-bucket.oss-cn-hangzhou.aliyuncs.com:/ /mnt/oss_data

命令解析：

• mount -t alinas ... your-bucket.oss-cn-hangzhou.aliyuncs.com:/ /mnt/oss_data：使用 EFC 客户端将 OSS Bucket 挂载到本地 /mnt/oss_data 目录。

• g_oss_STSFile=/etc/passwd-sts：指定包含 STS 凭证的配置文件路径。

• g_tier_EnableClusterCache=true、g_tier_DadiIsDistributed=true：启用 EFC 的核心功能——分布式缓存加速。

• g_tier_DadiAddr=/etc/efc/rootlist：指定集群节点配置文件路径，用于构建 P2P 缓存网络。

• g_tier_DadiMemCacheCapacityMB=1024：分配 1 GB 内存用于缓存数据。

• g_tier_DadiDiskCacheCapacityMB=10240：分配 10 GB 磁盘空间用于缓存数据，缓存文件将存放在 /mnt/cache/ 目录。

• g_server_Port=17871：开放 17871 端口，以便后续使用命令行工具查看缓存命中率或执行数据预热。

更多参数说明请参考挂载参数详解。

数据预热

此功能可提前将数据从 OSS 加载到缓存中，消除首次访问延迟，对模型推理等场景尤其重要。

• 路径要求：预热路径必须是挂载点下的相对路径。

• 任务状态：running（运行中）、completed（已完成）、canceled（已取消）、failed（已失败）。

• 任务被动淘汰机制：预热任务不会无限保留，系统会根据以下规则自动淘汰历史任务记录：

  • 正在预热（running）的任务：只能通过 cancel 命令主动取消，无法被动淘汰。

  • 已完成/已取消/已失败的任务：当满足以下任一条件时会被自动淘汰：

    • 历史预热任务总数超过 10,000 条。

    • 任务记录时间超过 7 天。

缓存监控

此功能用于实时查看缓存的运行状态，如命中率、吞吐量等，是性能调优的关键依据。

查看监控数据

• HTTP 方式（推荐，返回 JSON 格式）

  curl -s "http://localhost:17871/v1/tier"

• 命令行方式（返回文本格式）

  aliyun-alinas-efc-cli -m <挂载点> -r tier

清除监控数据

重置监控计数器（如 tier_read_hit 等指标归零）。

• HTTP方式

  curl -s "http://localhost:17871/v1/tier/clear"

• 命令行方式

  aliyun-alinas-efc-cli -m <挂载点> -r tier -c

缓存扩缩容

在线增删节点

此操作用于动态调整分布式缓存集群的节点数量，无需中断服务。

• 扩容：在所有节点的 rootlist 文件中，添加新节点的 IP 地址。

• 缩容：在所有节点的 rootlist 文件中，删除目标节点的 IP 地址。

  移除节点时，系统采用 LRU（Least Recently Used，最近最少使用） 机制对缓存数据进行淘汰，确保优先保留访问频率高的热点数据，维持缓存命中率。

• 生效机制：EFC 进程会周期性（默认5s）地重新读取 rootlist 文件并自动应用变更。

调整单节点缓存容量

重要：EFC 不支持动态调整单个节点的缓存容量。如需调整，必须卸载并重新挂载文件系统，请在业务低峰期执行。

在重新挂载时，通过修改以下参数来调整缓存容量：

挂载参数动态调整

EFC 提供一个Python脚本工具，用于在不手动卸载的情况下修改挂载参数。该工具的原理是：修改 EFC 的 state 文件（存储启动命令），然后 kill 当前 EFC 进程，进程重启时自动加载新的参数。

• 下载工具

  wget https://aliyun-alinas-eac-ap-southeast-1.oss-ap-southeast-1.aliyuncs.com/cache/efc_runtime_ops.latest.py

• 修改挂载参数

  python3 efc_runtime_ops.py update <本地挂载路径> [-o <更新参数,...>]...

  示例：

  python3 update_state_file.py update /mnt/oss_data \
            -o g_tier_EnableClusterCache=true,g_tier_tier_DadiP2PPort=23456 \
            -o g_tier_BlockSize=1048576

• 回滚

  修改参数时，工具会自动备份旧的state文件。如果修改后 EFC 出现故障，可以回滚恢复：

  python3 efc_runtime_ops.py rollback <本地挂载路径> [备份路径]

  示例：用默认的备份文件路径恢复state文件。

  python3 efc_runtime_ops.py rollback /mnt/oss_data

目录缓存管理

EFC 默认开启目录缓存以加速 ls 等目录遍历操作。如果 OSS 端的目录结构发生变化而 EFC 未能及时感知，可手动清理目录缓存。

目录缓存相关参数（挂载时指定）：

清理目录缓存：

• HTTP方式

  curl -s "http://localhost:17871/v1/action/clear_readdir_cache"

• 命令行方式

  aliyun-alinas-efc-cli -m <挂载点> -r action -k clear_readdir_cache

基础参数

缓存配置参数

元数据与目录缓存参数

运维与高级参数

权限与安全

• 保护密码文件：密码文件权限必须设置为 600，并存放在安全的位置，避免凭证泄露。

• 优先使用 STS：从安全角度考虑，建议优先使用 STS 临时凭证而非长期 AccessKey，降低密钥泄露风险。

• 最小化安全组开放：仅在集群节点之间开放 P2P 通信端口 17980，并严格限制管理端口 17871 的访问来源。

场景化配置建议

数据一致性管理

• 理解最终一致性：EFC 是只读缓存，对 OSS 后端的变更不是实时同步的。应用设计时应能容忍一定的数据延迟。

• 主动刷新：对于需要频繁更新并立即读取的场景，应在应用逻辑中增加调用清除目录缓存接口的步骤。

• 开启元数据缓存：对于元数据不常变化的场景，通过 -o g_metadata_CacheEnable 开启元数据缓存，可以减少对 OSS 的 GetObjectMeta 请求。