RapidFS Cache Service组件使用手册

更新时间：2026-06-09

一、快速入门

1.1 前置条件

已部署 Kubernetes 集群（CCE/自建K8s），并且完成RapidFS Cache Service组件安装（安装步骤详见章节二详细部署）

CCE：通过Helm模版安装 RapidFS Cache Service组件
自建K8s：通过RapidFS Cache Service部署包安装

已创建 RapidFS Master 托管实例（Cache接入类型：容器引擎CCE、自有Kubernetes集群），并获得以下信息用于创建部署组：

rapidfsID: RapidFS 实例 ID
rapidfsToken: RapidFS 实例访问令牌
region: 部署区域

RapidFS Master托管实例必须和Kubernetes集群网络互通（如果网络不通，创建的部署组状态为PermissionDenied）

RapidFS部署组负载（Pod）依赖7000～9000端口，对于公有云场景需要vpc安全组开放7000-9000

1.2 部署组示例

YAML

1apiVersion: rapidfs.baidu.com/v1alpha1
2kind: RapidFSCacheDeploy
3metadata:
4  name: my-cache-deploy
5  namespace: default
6spec:
7  # 部署组实际负载的副本数
8  replicas: 3
9  # rapidfs实例id
10  rapidfsID: "your-rapidfs-id"
11  # rapidfs实例token
12  rapidfsToken: "your-token"
13  storage:
14  - mediumtype: MEM
15    volumeType: emptyDir
16    quota: "50Gi"

1.3 创建并验证

Kubernetes集群侧检查

                Bash
                
                # 创建 部署组
kubectl apply -f my-cache-deploy.yaml

# 查看状态
kubectl get rfscd

# 查看详细信息
kubectl describe rfscd my-cache-deploy

# 查看 Pod
kubectl get pods -o wide -l "rapidfs.baidu.com/cachedeploy=my-cache-deploy"

RapidFS Master托管实例侧验证

请在百度公有云数据湖存储加速工具 → 实例 → Cache 节点管理查看部署组和节点信息

二、详细部署

2.1 前置依赖

组件依赖Kruise，需要通过 Helm 模版安装Kruise组件（公有云CCE）

2.2 容器环境组件安装

分CCE和自建K8s两种情况：

2.2.1 CCE集群

登录百度云容器引擎控制台
进入Helm → Helm 模版 → 百度智能云模版
检查安装参数中的region，必须和实际的地域对应

搜索 RapidFS Cache Service，点击安装，等待安装完成
查看 RapidFS缓存控制器Token：查看 kube-system namespace下的 ConfigMap rapidfs-cache-service-config 资源，获取data.rapidfsCacheControllerToken 属性值记为RapidFS缓存控制器Token，用于RapidFS实例与容器环境交互的身份识别；

2.2.2 自建K8s集群

                Bash
                
            

                # 1. 安装，必须填入region参数，否则组件安装失败，如果是在B区安装，请询问rapidfs 同学确定region
# 1.1 获取EKS/自建K8S的服务地址: ${CLUSTER-IP} ${PORT}, EKS和自建K8S需要指定集群的实际服务地址
# NAME         TYPE        CLUSTER-IP   EXTERNAL-IP   PORT(S)   AGE
# kubernetes   ClusterIP   10.96.0.1    <none>        443/TCP   2y22d
kubectl get service kubernetes
# 1.2 获取集群可用的调度器: ${SchedulerName}，EKS和自建K8S需要指定集群的实际的调度器
# 1.3 将values.yaml中的deployEnv设置为 eks
# 1.4 解压部署包，修改values.yaml文件的region、kubernetesServiceHost、kubernetesServicePort、schedulerName、manager.schedulerName 内容
helm install rapidfs-cache-service --namespace kube-system .

# 2. 获取 RapidFS缓存控制器ID 和 RapidFS缓存控制器Token
# RapidFS缓存控制器ID: data.rapidfsCacheControllerID
# RapidFS缓存控制器Token: data.rapidfsCacheControllerToken
kubectl get configmap rapidfs-cache-service-config -n kube-system -o yaml
            

2.3 创建 RapidFS Master 托管实例

按顺序进行控制台操作：数据湖存储加速工具 → 实例 → 创建实例选择部署模式：Master托管，根据Cache接入类型选择容器引擎CCE 或者自有Kubernetes集群

2.4 创建部署组

部署组配置

YAML

1apiVersion: rapidfs.baidu.com/v1alpha1
2kind: RapidFSCacheDeploy
3metadata:
4  name: cache-deploy-demo                 # 部署组名称
5  namespace: default                      # 部署组所在命名空间
6spec:
7  rapidfsToken: "your-rapidfs-token"      # rapidfs master托管实例 实例Token
8  rapidfsID: "rapidfs-xxxxxxxxxxxx"       # rapidfs master托管实例 实例ID
9  replicas: 3                             # 部署组实际负载的副本数量
10  region: "bj"                            # rapidfs master托管实例 所在地域
11
12  resources:                              # rapidfs部署组的资源设置，对rapidfs数据负载（pod）生效
13    request:
14      cpu: "2"
15      memory: "4Gi"
16    limits:
17      cpu: "4"
18      memory: "8Gi"
19
20  storage:                                # 提供给rapidfs部署组 数据负载的存储配置，注意，可以设置多个存储，但不能同时设置MEM 和 SSD 介质类型的 storage
21    - mediumtype: MEM
22      volumeType: emptyDir
23      path: /data/rapidfs-cache
24      quota: "4Gi"
25    - mediumtype: SSD
26      volumeType: hostPath
27      path: /data/rapidfs-cache
28      quota: "100Gi"
29
30  nodeSelector:                           # rapidfs部署组的nodeSelector，对rapidfs数据负载（pod）生效，"disktype: ssd"只是示例
31    disktype: ssd
32
33  tolerations:                            # rapidfs部署组的tolerations，对rapidfs数据负载（pod）生效
34    - key: "rapidfs"
35      operator: "Equal"
36      value: "cache"
37      effect: "NoSchedule"
38
39  affinity:                               # rapidfs部署组的affinity，对rapidfs数据负载（pod）生效
40    nodeAffinity:
41      requiredDuringSchedulingIgnoredDuringExecution:
42        nodeSelectorTerms:
43        - matchExpressions:
44          - key: node-type
45            operator: In
46            values: cache
47          
48  systemConfig:                           # 系统配置，除非用户有明确需求，否则不建议用户直接修改，修改前请和rapidfs同学确认
49    - fs.aio-max-nr: "10485760"
50    - vm.max_map_count: "655350"
51
52  serviceConfig:                          # 服务配置，不建议用户修改
53    - min_log_level: "0"

三、部署组配置说明

3.1 必填字段

字段	类型	说明	示例
replicas	integer	Dataserver 副本数	10
rapidfsID	string	RapidFS 实例 ID	"rapidfs-xHiwZKQ5q7jX"
storage	array	存储配置列表	见下方说明

3.2 存储配置（storage）

注意：对于一个部署组，不能同时设置MEM类型和SSD类型的storage，只能设置一种

YAML

1storage:
2  # MEM 存储（内存）
3  - mediumtype: MEM           # 存储介质：MEM 或 SSD
4    volumeType: emptyDir      # 卷类型：MEM 建议用 emptyDir
5    quota: "50Gi"             # 存储配额
6    
7  # SSD 存储（固态硬盘）
8  - mediumtype: SSD
9    volumeType: hostPath      # 卷类型：SSD 建议用 hostPath
10    path: /ssd-disk           # 挂载路径（hostPath 必填）
11    quota: "500Gi"

3.3 资源配置（resources）

YAML

1resources:
2  request:                    # 最小资源请求
3    memory: "1Gi"
4    cpu: "1"
5  limits:                     # 最大资源限制
6    memory: "128Gi"
7    cpu: "16"

推荐配置：

memory (request/limit)	cpu (request/limit)
20Gi / 128Gi	4 / 16

未设置或低于最低要求时，Controller 会自动校准

3.4 调度配置

3.4.1 节点选择器（nodeSelector）

YAML

1nodeSelector:
2  node-type: cache            # 只调度到带此标签的节点

3.4.2 亲和性（affinity）

部署组的实际负载配置了Pod之间的反亲和性，同一个部署组的Pod不会调度在同一个节点上

YAML

1affinity:
2  nodeAffinity:
3    requiredDuringSchedulingIgnoredDuringExecution:
4      nodeSelectorTerms:
5      - matchExpressions:
6        - key: node-type
7          operator: In
8          values: [cache]

3.4.3 污点容忍（tolerations）

YAML

1tolerations:
2- key: "dedicated"
3  operator: "Equal"
4  value: "rapidfs-cache"
5  effect: "NoSchedule"

3.5 高级配置

除非有特殊要求，否则不建议用户通过systemConfig 和 serviceConfig修改配置

3.5.1 系统配置（systemConfig）

YAML

1systemConfig:
2- fs.aio-max-nr: "10485760"
3- vm.max_map_count: "655350"

3.5.2 服务配置（serviceConfig）

YAML

1serviceConfig:
2- min_log_level: "0"
3- comlog_quota_size: "1024"

四、状态查看

4.1 部署组状态查看

                Bash
                
            

                # 查看所有 部署组 及状态
kubectl get rfscd

# 示例输出
NAME                 PHASE     REPLICAS   READY   CLUSTER ADDRESS          AGE
my-cache-deploy      Ready     10         10      192.168.1.100:8000       1h

# 查看详细信息
kubectl describe rfscd my-cache-deploy

# 查看状态详情
kubectl get rfscd my-cache-deploy -o yaml

# 查看迁移进度
kubectl get rfscd my-cache-deploy -o jsonpath='{.status.excludingNodes}' | jq

# 详细负载查看（如果部署组已经Ready，可以不用关注）
# 查看 部署组的实际负载Pod
kubectl get pods -l rapidfs.baidu.com/instance=my-cache-deploy

# 查看 部署组的实际负载Pod 详情
kubectl describe pod <pod-name>

# 查看 部署组的实际负载Pod 日志
kubectl logs <pod-name> -c app
            

4.2 部署组状态说明

Phase	说明	处理建议
Starting	正在创建 Pod	等待 Pod 启动
Ready	所有 Pod 就绪	正常运行
Partial	部分 Pod 未就绪	检查 Pod 状态
Scaling	正在缩容	等待数据迁移完成
PermissionDenied	无操作权限	检查权限配置

五、常用运维操作

5.1 部署组扩容

YAML

1# 将副本数从 10 扩容到 15
2spec:
3  replicas: 15
4  rapidfsToken: "your-token"

5.2 部署组缩容（普通缩容）

YAML

1# 将副本数从 15 缩容到 10
2spec:
3  replicas: 10
4  rapidfsToken: "your-token"

普通缩容会随机选择节点下线，不保证数据安全

5.3 指定节点缩容（带数据迁移）

场景：下线指定节点，确保数据安全迁移

YAML

1spec:
2  replicas: 9                         # 目标副本数
3  rapidfsToken: "your-token"
4  excludeNodeGroup:                   # 要下线的节点列表
5  - "node-1"
6  - "node-2"

流程说明：

RapidFS 自动迁移数据到其他节点
迁移完成后，删除对应 Pod，并从 excludeNodeGroup 中移除已下线节点

查看迁移进度：

                Bash
                
                kubectl get rfscd my-cache-deploy -o jsonpath='{.status.excludingNodes}'

5.4 节点迁移

场景：节点维护前，迁移数据到其他节点，建议用户结合部署组亲和性自行进行定向迁移

YAML

1spec:
2  replicas: 10                        # 副本数不变
3  excludeNodeGroup:                   # 指定迁移源节点
4  - "node-to-migrate"

迁移完成后：

YAML

1spec:
2  replicas: 10
3  excludeNodeGroup: []                # 清空列表

5.5 更新调度策略

                Bash
                
            

                # 更新节点选择器
kubectl patch rfscd my-cache-deploy --type=merge -p '
{
  "spec": {
    "nodeSelector": {
      "node-type": "cache-ssd"
    }
  }
}'

# 更新污点容忍
kubectl patch rfscd my-cache-deploy --type=merge -p '
{
  "spec": {
    "tolerations": [
      {"key": "dedicated", "operator": "Equal", "value": "rapidfs", "effect": "NoSchedule"}
    ]
  }
}'
            

5.6 删除部署组

Bash

1kubectl delete rfscd my-cache-deploy

删除部署组会同时删除所有 Dataserver Pod 和相关资源，请确保数据已备份或迁移

六、故障排查

6.1 部署组一直处于 Starting 状态

可能原因：

节点资源不足
镜像拉取失败
节点调度失败

排查步骤：

                Bash
                
                # 查看 Pod 状态，可能是亲和性不满足、污点容忍不满足、节点选择不满足
kubectl get pods -l rapidfs.baidu.com/cachedeploy=my-cache-deploy

# 查看 Pending Pod 原因
kubectl describe pod <pending-pod> | grep -A 10 Events

# 查看节点资源，可能是节点资源不足
kubectl describe nodes | grep -A 5 "Allocated resources"

6.2 部署组处于 PermissionDenied 状态

可能原因：

rapidfsID 或 rapidfsToken 错误
RapidFS 控制台未授权此操作
RapidFS Cache Service安装时设置了错误的region，造成所有部署组创建/更新请求都被拒绝

排查步骤：

                Bash
                
                # 查看状态信息
kubectl get rfscd my-cache-deploy -o jsonpath='{.status.message}'

# 检查配置
kubectl get rfscd my-cache-deploy -o yaml | grep -E "rapidfsID|rapidfsToken"

# 查看 RapidFS Master托管实例的token信息是否更新；

6.3 缩容卡在 Scaling 状态

可能原因：

数据迁移慢
网络问题

排查步骤：

                Bash
                
                # 查看迁移进度
kubectl get rfscd my-cache-deploy -o jsonpath='{.status.excludingNodes}' | jq

# 查看迁移节点状态
kubectl get rfscd my-cache-deploy -o json | jq '.status.excludingNodes[] | select(.phase=="Decommissioning")'

# 查看 RapidFS Master托管实例 Cache节点管理 节点缓存数据情况

6.4 Pod 启动失败

常见错误：

                Bash
                
                # 查看错误信息
kubectl describe pod <pod-name> | grep -A 10 "Error"

# 常见错误处理
# 1. 端口冲突：检查节点端口占用
# 2. 系统参数设置失败：检查节点权限
# 3. 存储挂载失败：检查存储路径和权限

6.5 日志查看

                Bash
                
                # Controller 日志
kubectl logs -n rapidfs-system deployment/rapidfs-controller -f

# Dataserver Pod 日志
kubectl logs <pod-name> -c app -f

# InitContainer 日志
kubectl logs <pod-name> -c sysctl-config
kubectl logs <pod-name> -c port-allocator

七、最佳实践建议

7.1 资源规划

节点选择：选择高性能节点，建议使用 SSD 存储
资源预留：为部署组负载预留足够资源，避免资源争抢
网络规划：使用 HostNetwork，确保端口不冲突

7.2 数据性能

节点下线前确保完成缩容：节点下线前确保数据已迁移
使用指定节点缩容：避免普通缩容导致数据丢失
监控迁移进度：缩容时监控 excludingNodes 状态

7.3 性能优化

合理设置副本数：根据业务需求设置，避免过度扩容
优化资源配置：根据实际负载调整 CPU/内存配置

7.4 监控告警

可以配置监控指标：

部署组 Phase 状态
Pod 就绪数量
节点资源使用率

八、常见问题

1.如何查看 Controller ID？

答：

Bash

1kubectl get configmap rapidfs-cache-service-config -n kube-system -o yaml
2# RapidFS缓存控制器ID: data.rapidfsCacheControllerID
3# RapidFS缓存控制器Token: data.rapidfsCacheControllerToken

2.如何修改已创建部署组的存储配置？

答：不建议修改部署组的存储配置，修改存储配置后会清理rapidfs加载的缓存数据，造成读取变慢。存储配置支持在线修改，目前需要手动触发Pod重建，之会应用新的配置，建议生效后发起预热。

3.缩容后 excludeNodeGroup 何时清空？

答：缩容完成后，Controller 会自动从 excludeNodeGroup 中移除已下线节点。

4.是否支持跨 namespace 部署？

答：支持。可在不同 namespace 创建部署组。

评价此篇文章

有帮助没帮助

Cache节点管理

百舸全托管资源池类型Cache节点

数据湖存储加速工具 RapidFS

RapidFS Cache Service组件使用手册

一、快速入门

1.1 前置条件

1.2 部署组示例

1.3 创建并验证

二、详细部署

2.1 前置依赖

2.2 容器环境组件安装

2.2.1 CCE集群

2.2.2 自建K8s集群

2.3 创建 RapidFS Master 托管实例

2.4 创建 部署组

三、部署组配置说明

3.1 必填字段

3.2 存储配置（storage）

3.3 资源配置（resources）

3.4 调度配置

3.4.1 节点选择器（nodeSelector）

3.4.2 亲和性（affinity）

3.4.3 污点容忍（tolerations）

3.5 高级配置

3.5.1 系统配置（systemConfig）

3.5.2 服务配置（serviceConfig）

四、状态查看

4.1 部署组状态查看

4.2 部署组状态说明

五、常用运维操作

5.1 部署组扩容

5.2 部署组缩容（普通缩容）

5.3 指定节点缩容（带数据迁移）

5.4 节点迁移

5.5 更新调度策略

5.6 删除部署组

六、故障排查

6.1 部署组 一直处于 Starting 状态

6.2 部署组 处于 PermissionDenied 状态

6.3 缩容卡在 Scaling 状态

6.4 Pod 启动失败

6.5 日志查看

七、最佳实践建议

7.1 资源规划

7.2 数据性能

7.3 性能优化

7.4 监控告警

八、常见问题

2.4 创建部署组

6.1 部署组一直处于 Starting 状态

6.2 部署组处于 PermissionDenied 状态