bitnamicharts/seaweedfs

Bitnami SeaweedFS 镜像文档

镜像概述和主要用途

SeaweedFS 是一个简单且高度可扩展的分布式文件系统。Bitnami 提供的该 Helm Chart 用于在 Kubernetes 集群中快速部署 SeaweedFS，支持生产级别的工作负载，包含经过精心设计的配置、安全增强和维护支持。

https://seaweedfs.github.io

商标说明：本软件包由 Bitnami 打包，提及的商标分属各自公司所有，使用不意味着附属或背书。

核心功能和特性

• 分布式架构：采用主从架构（Master-Volume），支持海量文件存储和高吞吐量
• 元数据分离：元数据与文件数据分离存储，提升性能和可扩展性
• S3 API 兼容：内置 S3 网关，支持 S3 协议访问
• Prometheus 集成：原生支持 Prometheus 指标暴露，便于监控
• 安全增强：支持双向 TLS（mTLS）通信、JWT 访问控制和 S3 认证
• 外部数据库支持：可对接外部 MariaDB/PostgreSQL 存储元数据
• 灵活配置：支持自定义环境变量、Sidecar 容器、Ingress 规则等
• 持久化存储：通过 Persistent Volume Claims 确保数据持久化

使用场景和适用范围

• 大规模文件存储：适用于需要存储海量小文件（如图片、日志）或大文件的场景
• 云原生环境：在 Kubernetes 集群中提供分布式存储服务
• 开发与测试：通过 Bitnami 简化的部署流程快速搭建测试环境
• 生产环境：结合 Bitnami Secure Images 提供硬化工件、CVE 透明度和企业支持（需订阅）

⚠️ 重要通知：Bitnami 镜像目录即将变更

自 2025 年 8 月 28 日起，Bitnami 将升级其公共镜像目录，推出新的 Bitnami Secure Images 计划，提供精选的硬化工件。过渡期间的主要变更包括：

• 首次向社区用户开放热门容器镜像的安全优化版本
• 逐步弃用免费 tier 中的非硬化工件（基于 Debian 的镜像），并移除公共目录中的非最新标签；社区用户将只能访问有限数量的硬化工件（仅 "latest" 标签，用于开发目的）
• 8 月 28 日起，两周内所有现有容器镜像（包括旧版本标签，如 2.50.0、10.6）将从公共目录（docker.io/bitnami）迁移至 "Bitnami Legacy" 仓库（docker.io/bitnamilegacy），且不再更新
• 生产环境和长期支持建议采用 Bitnami Secure Images，包含硬化工件、更小***面、CVE 透明度（通过 VEX/KEV）、SBOM 和企业支持

这些变更旨在通过推广软件供应链完整性最佳实践，提升所有 Bitnami 用户的安全态势。详情参见 https://github.com/bitnami/containers/issues/83267%E3%80%82

前提条件

• Kubernetes 集群版本 1.23+
• Helm 版本 3.8.0+
• 底层基础设施支持 PV 供应器
• 支持 ReadWriteMany 卷（用于部署扩展）

详细使用方法和配置说明

快速部署（TL;DR）

console
helm install my-release oci://registry-1.docker.io/bitnamicharts/seaweedfs

生产环境建议：试用 VMware Tanzu Application Catalog，Bitnami 目录的商业版。

安装 Chart

使用发布名称 my-release 安装 Chart：

console
helm install my-release oci://REGISTRY_NAME/REPOSITORY_NAME/seaweedfs

注意：需替换占位符 REGISTRY_NAME 和 REPOSITORY_NAME。例如，Bitnami 官方仓库使用 REGISTRY_NAME=registry-1.docker.io 和 REPOSITORY_NAME=bitnamicharts。

命令将以默认配置在 Kubernetes 集群中部署 SeaweedFS。参数 部分列出了安装时可配置的参数。

提示：使用 helm list 查看所有发布。

配置细节

资源请求与限制

Bitnami Chart 允许为所有容器设置资源请求和限制（通过 resources 参数）。生产环境必须设置资源请求，并根据实际需求调整。

可通过 resourcesPreset 参数自动应用预设资源配置（参考 https://github.com/bitnami/charts/blob/main/bitnami/common/templates/_resources.tpl#L15%EF%BC%89%EF%BC%8C%E4%BD%86%E7%94%9F%E4%BA%A7%E7%8E%AF%E5%A2%83%E5%BB%BA%E8%AE%AE%E6%89%8B%E5%8A%A8%E9%85%8D%E7%BD%AE%E4%BB%A5%E9%80%82%E9%85%8D%E5%85%B7%E4%BD%93%E9%9C%80%E6%B1%82%E3%80%82%E6%9B%B4%E5%A4%9A%E4%BF%A1%E6%81%AF%E5%8F%82%E8%A7%81 Kubernetes 容器资源管理文档。

Prometheus 指标集成

通过设置 master.metrics.enabled、volume.metrics.enabled、filer.metrics.enabled 或 s3.metrics.enabled 为 true，可启用 Prometheus 指标暴露。这将开放 SeaweedFS 原生 Prometheus 端口，并部署带有自动发现注解的 metrics 服务。

前提条件：集群中需已安装 Prometheus 或 Prometheus Operator。推荐安装 https://github.com/bitnami/charts/tree/main/bitnami/prometheus 或 https://github.com/bitnami/charts/tree/main/bitnami/kube-prometheus%E3%80%82

Prometheus Operator 集成：设置 *.metrics.serviceMonitor.enabled=true（如 master.metrics.serviceMonitor.enabled=true）可部署 ServiceMonitor 对象，需确保集群已安装 Prometheus Operator CRD。

凭证更新

Bitnami Chart 在首次启动时配置凭证，后续变更需手动操作：

1. 参考 https://github.com/seaweedfs/seaweedfs/wiki 更新用户密码
2. 使用新值更新 Secret（替换占位符 SECRET_NAME、ADMIN_ACCESS_KEY_ID 等）：

shell
kubectl create secret generic SECRET_NAME --from-literal=admin_access_key_id=ADMIN_ACCESS_KEY_ID --from-literal=admin_secret_access_key=ADMIN_SECRET_KEY_ID --from-literal=read_access_key_id=READ_ACCESS_KEY_ID --from-literal=read_secret_access_key=READ_SECRET_KEY_ID --dry-run -o yaml | kubectl apply -f -

外部数据库支持

如需 Filer Server 连接外部数据库（而非集群内安装），需禁用内置 MariaDB 并配置外部数据库参数：

console
mariadb.enabled=false
externalDatabase.enabled=true
externalDatabase.store=mariadb  # 或 postgresql
externalDatabase.host=myexternalhost
externalDatabase.user=myuser
externalDatabase.password=mypassword
externalDatabase.database=mydatabase
externalDatabase.port=3306

前置操作：需在外部数据库中手动创建 filemeta 表：

• MariaDB：

  sql
  USE DATABASE_NAME;
  CREATE TABLE IF NOT EXISTS filemeta (
    `dirhash`   BIGINT NOT NULL       COMMENT 'directory 字段 MD5 哈希的前 64 位',
    `name`      VARCHAR(766) NOT NULL COMMENT '目录或文件名',
    `directory` TEXT NOT NULL         COMMENT '父目录完整路径',
    `meta`      LONGBLOB,
    PRIMARY KEY (`dirhash`, `name`)
  ) DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_bin;
  

• PostgreSQL：

  sql
  \c DATABASE_NAME;
  CREATE TABLE IF NOT EXISTS filemeta (
    dirhash     BIGINT,
    name        VARCHAR(65535),
    directory   VARCHAR(65535),
    meta        bytea,
    PRIMARY KEY (dirhash, name)
  );
  

注意：替换 DATABASE_NAME 为实际数据库名。

也可通过 Helm Chart 安装时的 K8s Job 自动创建表，需设置 externalDatabase.initDatabaseJob.enabled=true。

Ingress 配置

若集群已安装 Ingress 控制器（如 https://github.com/bitnami/charts/tree/main/bitnami/nginx-ingress-controller 或 https://github.com/bitnami/charts/tree/main/bitnami/contour%EF%BC%89%EF%BC%8C%E5%8F%AF%E9%80%9A%E8%BF%87 Ingress 暴露 SeaweedFS 服务。

• 启用 Ingress：设置 master.ingress.enabled=true（其他组件如 S3、Filer 类似，通过 s3.ingress.enabled、filer.ingress.enabled 启用）
• 配置主机名：通过 master.ingress.hostname 设置域名
• TLS 配置：通过 master.ingress.tls 添加 TLS 证书
• 多主机支持：通过 master.ingress.extraHosts 和 master.ingress.extraTLS 配置额外主机和 TLS 规则

安全特性

启用安全设置需将 security.enabled=true 和 security.mTLS.enabled=true，支持：

• JWT 访问控制
• 组件间双向 TLS 通信

证书管理：

• Helm 自动生成：设置 security.mTLS.autoGenerated.enabled=true 和 security.mTLS.autoGenerated.engine=helm
• CertManager 生成：需集群已安装 CertManager，设置 security.mTLS.autoGenerated.enabled=true、security.mTLS.autoGenerated.engine=cert-manager，可通过 security.mTLS.autoGenerated.certManager.existingIssuer 指定现有 Issuer/ClusterIssuer

S3 认证：

• 启用：设置 s3.auth.enabled=true
• 自定义配置：创建包含认证配置的 Secret，通过 s3.auth.existingSecret 指定 Secret 名称
• 自动配置：通过 s3.auth.adminAccessKeyId、s3.auth.adminSecretAccessKey（管理员用户）和 s3.auth.readAccessKeyId、s3.auth.readSecretAccessKey（只读用户）设置凭证

额外环境变量

通过 extraEnvVars 添加自定义环境变量：

yaml
master:
  extraEnvVars:
    - name: LOG_LEVEL
      value: error

也可通过 ConfigMap 或 Secret 注入：

• extraEnvVarsCM：指定包含环境变量的 ConfigMap 名称
• extraEnvVarsSecret：指定包含环境变量的 Secret 名称

Sidecar 容器

通过 sidecars 参数添加额外容器（如监控或日志采集器）：

yaml
sidecars:
- name: metrics-exporter
  image: your-exporter-image:latest
  imagePullPolicy: Always
  ports:
  - name: metrics
    containerPort: 9090

若 Sidecar 需暴露端口，通过 service.extraPorts 添加端口定义：

yaml
service:
  extraPorts:
  - name: exporter-port
    port: 9090
    targetPort: 9090

初始化容器

通过 initContainers 参数添加初始化容器：

yaml
initContainers:
  - name: init-task
    image: your-init-image:latest
    imagePullPolicy: Always
    command: ["sh", "-c", "echo 'Initializing...'"]

Pod 亲和性

通过 affinity 参数配置自定义亲和性规则，或使用预设策略（参考 https://github.com/bitnami/charts/tree/main/bitnami/common#affinities%EF%BC%89%EF%BC%9A

• podAffinityPreset：Pod 亲和性预设
• podAntiAffinityPreset：Pod 反亲和性预设
• nodeAffinityPreset：节点亲和性预设

备份与恢复

使用 Velero 备份和恢复持久化卷，参考 Bitnami 备份恢复指南。

持久化存储

Bitnami SeaweedFS 镜像将数据和配置存储在容器的 /bitnami 路径，通过 Persistent Volume Claims 实现数据持久化。持久化相关问题排查参考 Bitnami 持久化卷故障排除指南。

参数说明

全局参数

通用参数

注：完整参数列表请参见 https://github.com/bitnami/charts/blob/main/bitnami/seaweedfs/README.md%E3%80%82

注意事项

• 不可变标签：生产环境强烈建议使用不可变标签（如具体版本号），避免镜像更新导致部署变更。Bitnami 会通过新 Chart 版本更新容器镜像。
• 镜像迁移：2025 年 8 月 28 日起，旧版本镜像将迁移至 docker.io/bitnamilegacy，不再更新，生产环境建议迁移至 Bitnami Secure Images。
• 版本兼容性：确保 Kubernetes 和 Helm 版本满足前提条件，避免部署失败。