3. CSI 驱动核心接口实现：IdentityServer、ControllerServer、NodeServer

CSI（Container Storage Interface）驱动的核心由三个 gRPC 服务组成：IdentityServer、ControllerServer 和 NodeServer。这三个服务分别负责插件身份声明、存储资源管控和节点挂载操作。理解它们的接口骨架与关键逻辑，是进行性能调优和故障排查的基础。

3.1 IdentityServer：插件身份与健康探测

IdentityServer 是 CSI 驱动启动后最先被调用的服务，负责向容器编排系统（如 Kubernetes）声明插件的身份、能力以及健康状态。它包含两个核心 RPC：GetPluginInfo 和 Probe。

3.1.1 GetPluginInfo 实现骨架

该接口返回插件的名称、版本号以及厂商信息。Kubernetes 外部组件（如 external-provisioner）通过此接口确认驱动是否匹配。

func (s *IdentityServer) GetPluginInfo(ctx context.Context, req *csi.GetPluginInfoRequest) (*csi.GetPluginInfoResponse, error) {
    // 关键逻辑：返回静态定义的插件元数据
    return &csi.GetPluginInfoResponse{
        Name:          "com.example.csi.driver",   // 全局唯一名称
        VendorVersion: "2.1.0",                     // 语义化版本
        Manifest: map[string]string{
            "url": "https://example.com/csi-driver",
        },
    }, nil
}

3.1.2 Probe 实现骨架

Probe 用于检测驱动是否处于健康运行状态。Kubernetes 的 node-driver-registrar 会定期调用此接口，若返回错误，则标记驱动为不健康并触发重启。

func (s *IdentityServer) Probe(ctx context.Context, req *csi.ProbeRequest) (*csi.ProbeResponse, error) {
    // 关键逻辑：检查后端存储连接、共享库状态、goroutine 泄漏等
    if err := s.storageBackend.Ping(); err != nil {
        return nil, status.Errorf(codes.FailedPrecondition, "storage backend unreachable: %v", err)
    }
    return &csi.ProbeResponse{
        Ready: &wrappers.BoolValue{Value: true},
    }, nil
}

3.2 ControllerServer：存储卷生命周期管理

ControllerServer 运行在控制平面节点上，负责处理存储卷的创建、删除、扩容、快照等操作。其中 CreateVolume 和 DeleteVolume 是最核心的两个接口，也是性能压测的重点。

3.2.1 CreateVolume 实现骨架

该接口接收容量、访问模式、参数等请求，调用后端存储 API 创建卷，并返回卷 ID 和属性。

func (s *ControllerServer) CreateVolume(ctx context.Context, req *csi.CreateVolumeRequest) (*csi.CreateVolumeResponse, error) {
    // 1. 参数校验与默认值填充
    volName := req.GetName()
    capRange := req.GetCapacityRange()
    params := req.GetParameters()

    // 2. 调用后端存储创建卷（关键性能路径）
    volID, err := s.backend.CreateVolume(ctx, volName, capRange.GetRequiredBytes(), params)
    if err != nil {
        return nil, status.Errorf(codes.Internal, "failed to create volume: %v", err)
    }

    // 3. 返回卷信息
    return &csi.CreateVolumeResponse{
        Volume: &csi.Volume{
            VolumeId:      volID,
            CapacityBytes: capRange.GetRequiredBytes(),
            VolumeContext: map[string]string{"type": params["type"]},
        },
    }, nil
}

3.2.2 DeleteVolume 实现骨架

删除卷时，需先校验卷是否存在，再调用后端 API 执行删除。

func (s *ControllerServer) DeleteVolume(ctx context.Context, req *csi.DeleteVolumeRequest) (*csi.DeleteVolumeResponse, error) {
    volID := req.GetVolumeId()

    // 1. 幂等性检查：卷不存在时直接返回成功
    exists, err := s.backend.VolumeExists(ctx, volID)
    if err != nil {
        return nil, status.Errorf(codes.Internal, "check volume existence failed: %v", err)
    }
    if !exists {
        return &csi.DeleteVolumeResponse{}, nil
    }

    // 2. 执行删除
    if err := s.backend.DeleteVolume(ctx, volID); err != nil {
        return nil, status.Errorf(codes.Internal, "delete volume failed: %v", err)
    }
    return &csi.DeleteVolumeResponse{}, nil
}

3.3 NodeServer：节点挂载与卸载

NodeServer 运行在每个工作节点上，负责将存储卷挂载到 Pod 的文件系统，以及卸载卷。其性能直接影响 Pod 启动速度和节点稳定性。

3.3.1 NodePublishVolume 实现骨架

该接口将卷挂载到目标路径，通常涉及格式化、挂载、权限设置等操作。

func (s *NodeServer) NodePublishVolume(ctx context.Context, req *csi.NodePublishVolumeRequest) (*csi.NodePublishVolumeResponse, error) {
    targetPath := req.GetTargetPath()
    volID := req.GetVolumeId()
    readonly := req.GetReadonly()

    // 1. 确保目标路径存在
    if err := os.MkdirAll(targetPath, 0750); err != nil {
        return nil, status.Errorf(codes.Internal, "mkdir failed: %v", err)
    }

    // 2. 获取设备路径（如 /dev/sdb）
    devicePath, err := s.mounter.GetDevicePath(volID)
    if err != nil {
        return nil, status.Errorf(codes.NotFound, "device not found: %v", err)
    }

    // 3. 执行挂载（关键性能路径）
    options := []string{"defaults"}
    if readonly {
        options = append(options, "ro")
    }
    if err := s.mounter.Mount(devicePath, targetPath, req.GetVolumeCapability().GetMount().GetFsType(), options); err != nil {
        return nil, status.Errorf(codes.Internal, "mount failed: %v", err)
    }

    return &csi.NodePublishVolumeResponse{}, nil
}

3.3.2 NodeUnpublishVolume 实现骨架

卸载卷并清理目标路径。

func (s *NodeServer) NodeUnpublishVolume(ctx context.Context, req *csi.NodeUnpublishVolumeRequest) (*csi.NodeUnpublishVolumeResponse, error) {
    targetPath := req.GetTargetPath()

    // 1. 卸载文件系统
    if err := s.mounter.Unmount(targetPath); err != nil {
        return nil, status.Errorf(codes.Internal, "unmount failed: %v", err)
    }

    // 2. 清理空目录（非必须，但推荐）
    os.Remove(targetPath) // 忽略错误，目录可能被其他进程占用

    return &csi.NodeUnpublishVolumeResponse{}, nil
}

3.4 核心接口调用流程总览

下图展示了 CSI 驱动三个 Server 之间的协作关系，以及外部组件（如 external-provisioner、node-driver-registrar）如何调用这些接口。

3.5 接口实现关键逻辑对比

3.6 性能调优与故障排查要点

• IdentityServer 优化：Probe 的超时设置应独立于后端默认超时，建议使用 context.WithTimeout 限制在 2-3 秒，避免后端抖动影响驱动健康状态。
• ControllerServer 优化：CreateVolume 应支持并发请求，后端 API 客户端需配置连接池（如 gRPC 连接池大小 ≥ 10）。对于 DeleteVolume，务必实现幂等性，避免重复删除导致 panic。
• NodeServer 优化：NodePublishVolume 中的 os.MkdirAll 和 syscall.Mount 是系统调用热点。建议在挂载前检查目标路径是否已被挂载，避免重复挂载导致错误。
• 故障排查通用步骤：启用 gRPC 详细日志（GRPC_GO_LOG_SEVERITY_LEVEL=info），记录每个接口的入参、耗时和错误。使用 strace 跟踪 NodeServer 的系统调用，定位挂载失败的具体原因。