## 1. 持久化方案简介 在使用 Kubernetes (K8s) 时，存储方案的选择至关重要。对于群晖 (Synology) NAS 用户，推荐使用官方提供的 CSI 驱动，它支持动态创建存储资源并挂载给 Pod。 ### 1.1 iSCSI 方案 (本项目推荐) - **特点**：非常适合个人、家庭用户及中小企业，追求性能、稳定且配置轻量。 - **适用场景**：**数据库类应用**、虚拟化存储、对 I/O 性能要求较高的有状态服务。 - **原理**：基于块级（Block-level）存储，当 Pod 申请存储空间时，CSI 驱动通过 API 调用群晖 DSM，在 NAS 上自动创建 iSCSI LUN 和 Target，并将其映射给 K8s 节点。 - **优势**：性能最接近原生硬盘，延迟低，支持空间回收（Thin Provisioning），且无需复杂的集群维护。 - **项目地址**：[Synology CSI Driver](https://github.com/SynologyOpenSource/synology-csi) ### 1.2 SMB/NFS 方案 - **特点**：配置简单，属于文件级（File-level）共享，性能相对 iSCSI 稍逊。 - **适用场景**：**简单文件存储**、多 Pod 共享数据、静态资源托管、低频访问的备份数据。 - **差异**： - **NFS**：Linux 环境兼容性好，支持多读多写（RWX）。 - **SMB**：更适合 Windows 混合环境。 ### 1.3 其他方案 (如 Ceph) - **Ceph**：功能极度强大，支持块、文件和对象存储。但其架构复杂，对内存、计算资源及网络带宽要求较高，运维成本大，更适合大规模企业级数据中心。 - **对比**：对于拥有群晖 NAS 的个人或家庭用户，Ceph 过重，iSCSI 方案在满足生产级稳定性的同时提供了更好的易用性。 - **注意**：本文目前仅专注于**群晖 iSCSI 方案**的实现与配置，其他存储方案（如 Ceph 的部署与调优）将在日后另行介绍。 --- ## 2. 配置步骤 ### 2.1 先决条件 - **Kubernetes**: v1.19 或更高版本。 - **Synology NAS**: - DSM 7.0 或更高版本。 - DSM UC 3.1 或更高版本。 - **环境准备**: - （可选）若需自行编译：Go v1.21+。 - （可选）若需**快照**功能：需安装 Snapshot Controller，参考 [Volume Snapshot CRDs](https://github.com/kubernetes-csi/external-snapshotter/tree/v4.0.0/client/config/crd) 及 [Common Snapshot Controller](https://github.com/kubernetes-csi/external-snapshotter/tree/v4.0.0/deploy/kubernetes/snapshot-controller)。 ### 2.2 注意事项 1. **存储初始化**：在安装驱动前，必须在 DSM 上至少创建一个存储池（Storage Pool）和存储空间（Volume）。 2. **网络连通性**：确保所有 Kubernetes 节点均能访问 DSM 管理地址。 ### 2.3 安装过程 支持通过脚本或 Helm 两种方式部署。 #### 1. 克隆仓库 ```bash git clone https://github.com/SynologyOpenSource/synology-csi.git cd synology-csi ``` #### 2. 配置连接信息 复制模板文件并编辑 `config/client-info.yml`，配置 DSM 的连接参数： - `host`: DSM 的 IP 地址。 - `port`: 默认为 5000 (HTTP) 或 5001 (HTTPS)。 - `https`: 是否启用加密连接。 - `username`/`password`: 具备管理权限的账号。 #### 3. 方案一：服务器脚本部署 (推荐) 直接使用预编译镜像安装： ```bash # 安装完整功能 (包含快照) ./scripts/deploy.sh install --all # 仅安装基本功能 ./scripts/deploy.sh install --basic ``` > **脚本主要操作：** > - 创建 `synology-csi` 命名空间。 > - 创建包含凭据的 `client-info-secret`。 > - 创建默认存储类 `synology-iscsi-storage` (回收策略：Retain)。 > - (仅全量安装) 创建快照类 `synology-snapshotclass` (回收策略：Delete)。 #### 4. 方案二：本地 Helm 部署 ```bash # 创建命名空间并配置安全策略 kubectl create ns synology-csi kubectl label ns synology-csi pod-security.kubernetes.io/enforce=privileged --overwrite # 创建配置密钥 kubectl create secret -n synology-csi generic client-info-secret --from-file=./config/client-info.yml # 部署 cd deploy/helm make up ``` 需要更多自定义配置可以修改 `values.yml` 进行定制。 #### 5. 方案三：Helm 仓库部署 官方仓库默认会安装所有类型的存储后端存储类，并且包含 Retain 和 Delete 两种模式。 添加仓库： ``` helm repo add synology-csi-chart https://christian-schlichtherle.github.io/synology-csi-chart ``` 安装： ``` helm upgrade -i <release-name> synology-csi-chart/synology-csi -n synology-csi --create-namespace ``` 卸载： ``` helm delete <release-name> -n synology-csi ``` 如果需要定制安装，可以将 Chart 下载的本地进行修改，**要注意 Helm Chart 仓库和本地配置存在差别，不要使用仓库里的 `values.yaml`**。推荐在 `local.yaml` 中对默认参数进行覆盖。 ``` helm pull --untar synology-csi-chart/synology-csi cd synology-csi && vim local.yaml ``` #### 6. 验证状态 ```bash kubectl get pods -n synology-csi ``` 通过 Helm 运行测试， 运行测试会创建 iSCSI/SMB/NFS 三种类型的 PersistentVolumeClaim 并将其挂载到 Pod 运行 fio 测试吞吐量。如果测试通过，这些 PersistentVolumeClaim 和 Pods 会自动被移除。 ``` # 随机读写测试 helm test -n synology-csi # 查看资源状态 kubectl describe pods -n synology-csi -l helm.sh/template=test.yaml ``` --- ## 3. 存储类 (StorageClass) 配置详解 驱动正常运行后，需定义 StorageClass 来按需分配存储。 ### 3.1 iSCSI 协议示例 ```yaml apiVersion: storage.k8s.io/v1 kind: StorageClass metadata: name: synostorage-iscsi provisioner: csi.san.synology.com parameters: fsType: 'btrfs' dsm: '192.168.1.1' location: '/volume1' formatOptions: '--nodiscard' reclaimPolicy: Retain allowVolumeExpansion: true ``` ### 3.2 SMB/CIFS 协议示例 使用 SMB 前必须先创建包含账号信息的 Secret： ```yaml apiVersion: v1 kind: Secret metadata: name: cifs-csi-credentials namespace: default stringData: username: <账号> password: <密码> --- apiVersion: storage.k8s.io/v1 kind: StorageClass metadata: name: synostorage-smb provisioner: csi.san.synology.com parameters: protocol: "smb" dsm: '192.168.1.1' location: '/volume1' csi.storage.k8s.io/node-stage-secret-name: "cifs-csi-credentials" csi.storage.k8s.io/node-stage-secret-namespace: "default" reclaimPolicy: Delete allowVolumeExpansion: true ``` ### 3.3 NFS 协议示例 ```yaml apiVersion: storage.k8s.io/v1 kind: StorageClass metadata: name: synostorage-nfs provisioner: csi.san.synology.com parameters: protocol: "nfs" dsm: "192.168.1.1" location: '/volume1' mountPermissions: '0755' mountOptions: - nfsvers=4.1 reclaimPolicy: Delete allowVolumeExpansion: true ``` --- ## 4. 参数配置指南 | 参数名称 | 类型 | 描述 | 默认值 | 支持协议 | | :--- | :--- | :--- | :--- | :--- | | `dsm` | string | 指定 NAS 的 IP 地址。该 IP 必须已经在 `client-info.yml` 中定义。 | - | 全部 | | `location` | string | 指定在哪个存储空间创建 LUN 或共享文件夹（例如 `/volume1`）。 | - | 全部 | | `protocol` | string | 选择后端存储协议。可选值为 `iscsi` (默认)、`smb` 和 `nfs`。 | `iscsi` | 全部 | | `fsType` | string | 仅适用于 iSCSI 协议，支持 `ext4` 和 `btrfs`。SMB 协议将自动使用 `cifs`。 | `ext4` | iSCSI | | `formatOptions` | string | 传递给 `mkfs` 的附加参数。 | - | iSCSI | | `enableSpaceReclamation` | string | 是否为精简配置 (Thin Provisioned) 的 Btrfs LUN 启用空间回收功能。 | `false` | iSCSI | | `enableFuaSyncCache` | string | 是否启用强制单元访问 (FUA) 和 SCSI 同步缓存命令。 | `false` | iSCSI | | `mountPermissions` | string | 挂载后的文件夹权限。非零值将触发 `chmod` 操作。 | `0750` | NFS | | `csi.storage.k8s.io/node-stage-secret-*` | string | 指定 SMB 挂载所需的 Secret 名称和命名空间。 | - | SMB | - 对于SSD固态，建议启用强制单元访问 (FUA) 和 SCSI 同步缓存命令，可以降低因意外关机而导致的存储损坏风险。也可以在创建后在 SAN Manager 中更改。 --- ## 5. 卸载驱动 若需移除驱动，可执行： ```bash ./scripts/uninstall.sh ``` Loading... ## 1. 持久化方案简介 在使用 Kubernetes (K8s) 时，存储方案的选择至关重要。对于群晖 (Synology) NAS 用户，推荐使用官方提供的 CSI 驱动，它支持动态创建存储资源并挂载给 Pod。 ### 1.1 iSCSI 方案 (本项目推荐) - **特点**：非常适合个人、家庭用户及中小企业，追求性能、稳定且配置轻量。 - **适用场景**：**数据库类应用**、虚拟化存储、对 I/O 性能要求较高的有状态服务。 - **原理**：基于块级（Block-level）存储，当 Pod 申请存储空间时，CSI 驱动通过 API 调用群晖 DSM，在 NAS 上自动创建 iSCSI LUN 和 Target，并将其映射给 K8s 节点。 - **优势**：性能最接近原生硬盘，延迟低，支持空间回收（Thin Provisioning），且无需复杂的集群维护。 - **项目地址**：[Synology CSI Driver](https://github.com/SynologyOpenSource/synology-csi) ### 1.2 SMB/NFS 方案 - **特点**：配置简单，属于文件级（File-level）共享，性能相对 iSCSI 稍逊。 - **适用场景**：**简单文件存储**、多 Pod 共享数据、静态资源托管、低频访问的备份数据。 - **差异**： - **NFS**：Linux 环境兼容性好，支持多读多写（RWX）。 - **SMB**：更适合 Windows 混合环境。 ### 1.3 其他方案 (如 Ceph) - **Ceph**：功能极度强大，支持块、文件和对象存储。但其架构复杂，对内存、计算资源及网络带宽要求较高，运维成本大，更适合大规模企业级数据中心。 - **对比**：对于拥有群晖 NAS 的个人或家庭用户，Ceph 过重，iSCSI 方案在满足生产级稳定性的同时提供了更好的易用性。 - **注意**：本文目前仅专注于**群晖 iSCSI 方案**的实现与配置，其他存储方案（如 Ceph 的部署与调优）将在日后另行介绍。 --- ## 2. 配置步骤 ### 2.1 先决条件 - **Kubernetes**: v1.19 或更高版本。 - **Synology NAS**: - DSM 7.0 或更高版本。 - DSM UC 3.1 或更高版本。 - **环境准备**: - （可选）若需自行编译：Go v1.21+。 - （可选）若需**快照**功能：需安装 Snapshot Controller，参考 [Volume Snapshot CRDs](https://github.com/kubernetes-csi/external-snapshotter/tree/v4.0.0/client/config/crd) 及 [Common Snapshot Controller](https://github.com/kubernetes-csi/external-snapshotter/tree/v4.0.0/deploy/kubernetes/snapshot-controller)。 ### 2.2 注意事项 1. **存储初始化**：在安装驱动前，必须在 DSM 上至少创建一个存储池（Storage Pool）和存储空间（Volume）。 2. **网络连通性**：确保所有 Kubernetes 节点均能访问 DSM 管理地址。 ### 2.3 安装过程 支持通过脚本或 Helm 两种方式部署。 #### 1. 克隆仓库 ```bash git clone https://github.com/SynologyOpenSource/synology-csi.git cd synology-csi ``` #### 2. 配置连接信息 复制模板文件并编辑 `config/client-info.yml`，配置 DSM 的连接参数： - `host`: DSM 的 IP 地址。 - `port`: 默认为 5000 (HTTP) 或 5001 (HTTPS)。 - `https`: 是否启用加密连接。 - `username`/`password`: 具备管理权限的账号。 #### 3. 方案一：服务器脚本部署 (推荐) 直接使用预编译镜像安装： ```bash # 安装完整功能 (包含快照) ./scripts/deploy.sh install --all # 仅安装基本功能 ./scripts/deploy.sh install --basic ``` > **脚本主要操作：** > - 创建 `synology-csi` 命名空间。 > - 创建包含凭据的 `client-info-secret`。 > - 创建默认存储类 `synology-iscsi-storage` (回收策略：Retain)。 > - (仅全量安装) 创建快照类 `synology-snapshotclass` (回收策略：Delete)。 #### 4. 方案二：本地 Helm 部署 ```bash # 创建命名空间并配置安全策略 kubectl create ns synology-csi kubectl label ns synology-csi pod-security.kubernetes.io/enforce=privileged --overwrite # 创建配置密钥 kubectl create secret -n synology-csi generic client-info-secret --from-file=./config/client-info.yml # 部署 cd deploy/helm make up ``` 需要更多自定义配置可以修改 `values.yml` 进行定制。 #### 5. 方案三：Helm 仓库部署 官方仓库默认会安装所有类型的存储后端存储类，并且包含 Retain 和 Delete 两种模式。 添加仓库： ``` helm repo add synology-csi-chart https://christian-schlichtherle.github.io/synology-csi-chart ``` 安装： ``` helm upgrade -i <release-name> synology-csi-chart/synology-csi -n synology-csi --create-namespace ``` 卸载： ``` helm delete <release-name> -n synology-csi ``` 如果需要定制安装，可以将 Chart 下载的本地进行修改，**要注意 Helm Chart 仓库和本地配置存在差别，不要使用仓库里的 `values.yaml`**。推荐在 `local.yaml` 中对默认参数进行覆盖。 ``` helm pull --untar synology-csi-chart/synology-csi cd synology-csi && vim local.yaml ``` #### 6. 验证状态 ```bash kubectl get pods -n synology-csi ``` 通过 Helm 运行测试， 运行测试会创建 iSCSI/SMB/NFS 三种类型的 PersistentVolumeClaim 并将其挂载到 Pod 运行 fio 测试吞吐量。如果测试通过，这些 PersistentVolumeClaim 和 Pods 会自动被移除。 ``` # 随机读写测试 helm test -n synology-csi # 查看资源状态 kubectl describe pods -n synology-csi -l helm.sh/template=test.yaml ``` --- ## 3. 存储类 (StorageClass) 配置详解 驱动正常运行后，需定义 StorageClass 来按需分配存储。 ### 3.1 iSCSI 协议示例 ```yaml apiVersion: storage.k8s.io/v1 kind: StorageClass metadata: name: synostorage-iscsi provisioner: csi.san.synology.com parameters: fsType: 'btrfs' dsm: '192.168.1.1' location: '/volume1' formatOptions: '--nodiscard' reclaimPolicy: Retain allowVolumeExpansion: true ``` ### 3.2 SMB/CIFS 协议示例 使用 SMB 前必须先创建包含账号信息的 Secret： ```yaml apiVersion: v1 kind: Secret metadata: name: cifs-csi-credentials namespace: default stringData: username: <账号> password: <密码> --- apiVersion: storage.k8s.io/v1 kind: StorageClass metadata: name: synostorage-smb provisioner: csi.san.synology.com parameters: protocol: "smb" dsm: '192.168.1.1' location: '/volume1' csi.storage.k8s.io/node-stage-secret-name: "cifs-csi-credentials" csi.storage.k8s.io/node-stage-secret-namespace: "default" reclaimPolicy: Delete allowVolumeExpansion: true ``` ### 3.3 NFS 协议示例 ```yaml apiVersion: storage.k8s.io/v1 kind: StorageClass metadata: name: synostorage-nfs provisioner: csi.san.synology.com parameters: protocol: "nfs" dsm: "192.168.1.1" location: '/volume1' mountPermissions: '0755' mountOptions: - nfsvers=4.1 reclaimPolicy: Delete allowVolumeExpansion: true ``` --- ## 4. 参数配置指南 | 参数名称 | 类型 | 描述 | 默认值 | 支持协议 | | :--- | :--- | :--- | :--- | :--- | | `dsm` | string | 指定 NAS 的 IP 地址。该 IP 必须已经在 `client-info.yml` 中定义。 | - | 全部 | | `location` | string | 指定在哪个存储空间创建 LUN 或共享文件夹（例如 `/volume1`）。 | - | 全部 | | `protocol` | string | 选择后端存储协议。可选值为 `iscsi` (默认)、`smb` 和 `nfs`。 | `iscsi` | 全部 | | `fsType` | string | 仅适用于 iSCSI 协议，支持 `ext4` 和 `btrfs`。SMB 协议将自动使用 `cifs`。 | `ext4` | iSCSI | | `formatOptions` | string | 传递给 `mkfs` 的附加参数。 | - | iSCSI | | `enableSpaceReclamation` | string | 是否为精简配置 (Thin Provisioned) 的 Btrfs LUN 启用空间回收功能。 | `false` | iSCSI | | `enableFuaSyncCache` | string | 是否启用强制单元访问 (FUA) 和 SCSI 同步缓存命令。 | `false` | iSCSI | | `mountPermissions` | string | 挂载后的文件夹权限。非零值将触发 `chmod` 操作。 | `0750` | NFS | | `csi.storage.k8s.io/node-stage-secret-*` | string | 指定 SMB 挂载所需的 Secret 名称和命名空间。 | - | SMB | - 对于SSD固态，建议启用强制单元访问 (FUA) 和 SCSI 同步缓存命令，可以降低因意外关机而导致的存储损坏风险。也可以在创建后在 SAN Manager 中更改。 --- ## 5. 卸载驱动 若需移除驱动，可执行： ```bash ./scripts/uninstall.sh ``` 最后修改：2026 年 01 月 24 日 © 允许规范转载 打赏 赞赏作者 支付宝微信 赞 如果觉得我的文章对你有用，请随意赞赏
