Dify生产级部署实战：用K8s+NFS实现高可用AI应用平台（1.1.3版）
最近在帮几个团队落地AI应用平台，发现大家从Docker Compose的单机体验，过渡到Kubernetes生产环境时，总会遇到一堆“水土不服”的问题。社区版Dify本身没提供K8s的官方部署方案，这让很多技术负责人在规划高可用架构时有点无从下手。我自己也是踩了不少坑，从网络策略到存储持久化，从组件健康检查到安全隔离，每个环节都可能成为线上服务的“阿喀琉斯之踵”。
这篇文章，我就结合最近在1.1.3版本上的实战经验，聊聊怎么用Kubernetes StatefulSet配合NFS存储，把一个社区版的Dify，部署成能扛住生产流量、方便弹性伸缩的稳定平台。我们不止是让服务跑起来，更要关注稳定性设计、资源规划和那些官方文档里没写的企业级技巧。如果你正打算把Dify推向生产，或者已经在单机环境用得很顺手，想升级架构，那接下来的内容应该能帮你省下不少排查的时间。
1. 架构设计与核心组件规划
把Dify搬到K8s上，首先得理解它的组件构成和彼此间的依赖关系。这不像部署一个简单的Web应用，它是一套包含AI工作流执行、向量检索、插件管理的微服务集合。盲目地把所有东西塞进Pod里，很快就会在网络连通性、数据持久化和资源竞争上栽跟头。
Dify在K8s环境下的典型架构，可以看作由三层服务组成：
- 数据层：提供基础的数据持久化能力，是状态的核心。
- 中间件与服务层：运行业务逻辑，处理安全与网络代理。
- 接入层：对外提供统一的访问入口。
为了高可用，我们需要为有状态的服务（如数据库）选用StatefulSet，为无状态的服务（如Web前端）选用Deployment。下面这个表格梳理了各个组件的部署类型、关键配置以及生产环境需要特别注意的点：
| 组件 | 部署类型 (K8s资源) | 核心功能 | 生产环境特别注意 |
|---|---|---|---|
| PostgreSQL | StatefulSet | 关系型数据库，存储应用、工作流、用户等元数据。 | 需配置连接池、定期备份策略、以及合理的存储类（如SSD）。 |
| Redis | StatefulSet | 缓存与会话存储，提升API响应速度。 | 启用持久化（AOF/RDB），配置内存淘汰策略，避免内存溢出。 |
| Weaviate | StatefulSet | 向量数据库，用于AI模型的嵌入向量存储与检索。 | 对I/O性能敏感，建议使用高性能存储，并关注内存分配。 |
| Dify API | StatefulSet / Deployment | 核心后端服务，处理所有RESTful API请求。 | 需配置多副本实现负载均衡，并设置就绪和存活探针。 |
| Dify Worker | StatefulSet / Deployment | 异步任务处理器，执行工作流、文件处理等耗时操作。 | 任务队列需持久化，避免Pod重启导致任务丢失。 |
| Dify Web | Deployment | 前端用户界面。 | 纯静态资源，可配置多副本，通过Ingress暴露。 |
| Plugin Daemon | Deployment | 插件生命周期管理服务。 | 需要稳定连接到PostgreSQL创建插件相关的数据库。 |
| Sandbox | Deployment | 安全代码执行环境，用于运行工作流中的自定义代码节点。 | 安全隔离是重中之重，需配置严格的安全上下文和资源限制。 |
| SSRF-Proxy | Deployment | 正向代理，控制Sandbox等组件的出站网络访问，防止SSRF攻击。 | 网络策略配置是关键，需明确允许访问的外部地址。 |
| Nginx | Deployment | 反向代理，统一流量入口，路由到后端各服务。 | 配置优化（连接数、缓冲区）、SSL/TLS终止、健康检查。 |
提示：对于
PostgreSQL、Redis、Weaviate这类有状态服务，使用StatefulSet能保证Pod拥有稳定的网络标识（如postgres-0）和持久化存储卷的绑定关系，这在故障恢复和扩缩容时至关重要。
确定了架构，接下来就要解决一个更实际的问题：数据往哪存？生产环境可不能容忍Pod一重启，数据就全没了。
2. 持久化存储方案：NFS与StorageClass的抉择
在K8s里做持久化，方案很多，从云厂商的块存储（如AWS EBS、Azure Disk）到开源的分布式存储（如Ceph、Longhorn）。这次我们选择NFS（Network File System），主要是看中它的简单、通用和对多读多写（ReadWriteMany）模式的原生支持。Dify的多个组件（如API、Worker）可能需要同时读写同一个配置文件或上传目录，ReadWriteMany访问模式是刚需。
不过，直接使用静态配置的NFS PV（PersistentVolume）会面临管理难题：每次需要新存储卷都得手动创建PV和PVC。更优雅的方式是使用动态存储供给（Dynamic Provisioning）。这就需要用到StorageClass和对应的nfs-clientProvisioner。
2.1 部署NFS Client Provisioner
nfs-client是一个外部Provisioner，它会监听K8s集群中的PVC创建请求，并自动在指定的NFS服务器上创建对应的目录，然后动态生成PV与之绑定。部署它通常需要一个有足够权限的ServiceAccount和对应的授权。
首先，创建一个StorageClass对象，指明使用nfs-client作为供给器：
# storageclass-nfs.yaml apiVersion: storage.k8s.io/v1 kind: StorageClass metadata: name: nfs-client provisioner: k8s-sigs.io/nfs-subdir-external-provisioner parameters: archiveOnDelete: "false" # 删除PVC时，是否归档数据（false表示删除） reclaimPolicy: Delete volumeBindingMode: Immediate应用这个配置：kubectl apply -f storageclass-nfs.yaml。
接下来，部署nfs-client-provisioner。你需要准备一个Deployment，其中包含Provisioner的容器镜像，并配置好NFS服务器的地址和共享路径。这里以nfs-subdir-external-provisioner这个社区项目为例：
# nfs-provisioner-deploy.yaml apiVersion: apps/v1 kind: Deployment metadata: name: nfs-client-provisioner namespace: kube-system # 通常部署在kube-system命名空间 spec: replicas: 1 selector: matchLabels: app: nfs-client-provisioner strategy: type: Recreate template: metadata: labels: app: nfs-client-provisioner spec: serviceAccountName: nfs-client-provisioner containers: - name: nfs-client-provisioner image: registry.k8s.io/sig-storage/nfs-subdir-external-provisioner:v4.0.2 volumeMounts: - name: nfs-client-root mountPath: /persistentvolumes env: - name: PROVISIONER_NAME value: k8s-sigs.io/nfs-subdir-external-provisioner - name: NFS_SERVER value: 192.168.1.100 # 替换为你的NFS服务器IP - name: NFS_PATH value: /data/nfs-share # 替换为你的NFS共享路径 volumes: - name: nfs-client-root nfs: server: 192.168.1.100 path: /data/nfs-share别忘了创建对应的ServiceAccount和RBAC权限。部署成功后，当创建声明使用storageClassName: nfs-client的PVC时，Provisioner就会自动工作。
2.2 为Dify组件配置PVC
有了动态供给，我们可以为每个需要持久化的组件创建PVC。但这里有个设计考量：是每个组件一个独立的PVC，还是共享一个大的PVC通过子目录隔离？
- 独立PVC：隔离性好，便于配额管理和单独备份。但会创建大量PV，管理稍显复杂。
- 共享PVC + 子目录：管理简单，所有数据在一个卷内。但缺乏隔离，一个组件写满可能影响其他组件。
对于Dify，我倾向于折中方案：为数据库类核心组件（PostgreSQL, Redis, Weaviate）使用独立PVC，确保性能和稳定性；为应用层的共享数据（如上传的文件、临时工作空间）使用一个共享PVC。以下是PostgreSQL的PVC示例：
# postgres-pvc.yaml apiVersion: v1 kind: PersistentVolumeClaim metadata: name: postgres-data-pvc namespace: dify spec: accessModes: - ReadWriteOnce storageClassName: nfs-client # 指向我们创建的StorageClass resources: requests: storage: 20Gi # 根据实际数据量调整在对应的StatefulSet中，将这个PVC挂载到容器的数据目录即可。这样，即使postgres-0这个Pod被调度到其他节点，它的数据也会跟着走。
注意：在NFS服务器上，建议提前规划好目录结构，并设置好适当的权限（如
chmod 777），避免Pod因权限问题无法写入。例如，可以提前创建/data/nfs-share/dify/postgres/data这样的目录。
3. 关键组件部署详解与避坑指南
组件一个个部署上线，每一步都可能遇到预期之外的问题。我挑几个最容易出错的环节重点说说。
3.1 PostgreSQL：不仅仅是启动数据库
很多人以为把PostgreSQL的镜像跑起来就完事了，但在K8s网络环境下，连接认证是第一个拦路虎。Dify的api和plugin-daemon都需要连接PostgreSQL，而它们的Pod IP是动态分配的。
问题根源：PostgreSQL默认的pg_hba.conf文件只信任本地（127.0.0.1）连接。在Docker Compose里，容器间通过links或自定义网络，可以用服务名通信，且往往被视为“本地”。但在K8s，来自其他Pod的连接会被视为来自不同IP的主机。
解决方案：必须在PostgreSQL容器初始化后，修改pg_hba.conf，添加允许K8s集群内部网段连接的规则。这可以通过一个初始化容器（initContainer）来完成，或者在Pod启动后执行脚本。更稳妥的做法是构建一个自定义的PostgreSQL镜像，将配置预先写好。如果手动操作，可以进入容器执行：
# 进入PostgreSQL Pod kubectl -n dify exec -it postgres-0 -- bash # 编辑pg_hba.conf，在文件末尾添加一行 echo "host all all 10.42.0.0/16 md5" >> /var/lib/postgresql/data/pg_hba.conf # 重启PostgreSQL服务（或重启Pod）这里10.42.0.0/16需要替换为你的K8s集群Pod网段（Canal/Flannel等网络插件的网段）。使用md5密码认证是必须的。
另一个坑：数据库初始化。Dify的配置中指定了数据库名（如POSTGRES_DB=dify），但PostgreSQL的某些健康检查命令可能依赖默认的postgres数据库。如果健康检查失败，Pod会不断重启。解决方法是在初始化时，同时创建dify和postgres两个数据库。
3.2 Sandbox与SSRF-Proxy：安全隔离的双重保障
这是Dify生产部署中安全性的核心。Sandbox负责执行用户在工作流中编写的Python、Node.js等代码，必须严防其逃逸，访问或破坏宿主系统。SSRF-Proxy则是一个网络层面的“守门人”。
Sandbox的安全机制：
- Seccomp/AppArmor：限制容器可用的系统调用，这是第一道防线。
- 只读根文件系统：将容器根文件系统挂载为只读，对必须写的目录（如
/tmp）单独挂载空Dir或内存卷。 - 非root用户运行：在Dockerfile或K8s SecurityContext中指定以非root用户（如
nobody）运行。 - 资源限制：严格限制CPU和内存请求与上限，防止资源耗尽攻击。
在K8s部署中，我们需要在
sandbox的Deployment配置里显式声明这些安全设置：# sandbox-deployment.yaml 片段 spec: securityContext: runAsUser: 65534 # nobody用户 runAsGroup: 65534 fsGroup: 65534 seccompProfile: type: RuntimeDefault containers: - name: sandbox securityContext: allowPrivilegeEscalation: false readOnlyRootFilesystem: true capabilities: drop: - ALL volumeMounts: - name: tmp-volume mountPath: /tmp volumes: - name: tmp-volume emptyDir: {}SSRF-Proxy的配置：它本质上是一个配置了严格规则的Squid代理。所有来自Sandbox的出站网络请求都必须经过它。我们需要通过ConfigMap来定义
squid.conf，明确允许访问的外部域名或IP段，禁止一切其他访问。例如，只允许访问特定的AI模型API端点（如api.openai.com）和必要的包管理仓库（如pypi.org）。# ssrf-proxy的ConfigMap示例 (squid.conf片段) acl allowed_domains dstdomain .openai.com .pypi.org .python.org http_access allow allowed_domains http_access deny all这样，即使Sandbox内的恶意代码试图访问内网敏感服务或任意外网地址，也会被SSRF-Proxy拦截。
3.3 健康检查与就绪探针优化
生产环境的应用必须能告诉K8s“我是否健康”以及“我是否准备好接收流量”。默认的镜像可能没有配置，或者配置不够精确。
- PostgreSQL：使用
pg_isready命令作为就绪探针（readinessProbe），比简单的端口检查更可靠。 - Redis：使用
redis-cli ping命令。 - Weaviate：检查其REST API的健康端点（如
/v1/.well-known/ready）。 - Dify API：检查其
/health端点（如果提供），或者对/console/api/setup进行轻量级HTTP GET检查（注意避免触发业务逻辑）。 - Nginx：检查
/或自定义的健康检查端点。
在StatefulSet或Deployment中配置示例：
# api-statefulset.yaml 片段 containers: - name: api readinessProbe: httpGet: path: /health port: 5001 initialDelaySeconds: 30 # 给予足够的启动时间 periodSeconds: 10 failureThreshold: 3 livenessProbe: httpGet: path: /health port: 5001 initialDelaySeconds: 60 periodSeconds: 20 failureThreshold: 3合理的探针配置能确保在应用真正准备好之前，不会被加入Service的负载均衡池，也能在应用僵死时及时重启恢复。
4. 网络、配置与运维进阶
当所有组件都运行起来后，如何让它们协同工作，并方便地对外提供服务，是接下来的重点。
4.1 服务发现与内部通信
K8s的Service为Pod提供了稳定的DNS名称。在Dify各组件的环境变量配置中（通常通过ConfigMap管理），数据库的连接地址就应该使用Service名，例如：
POSTGRES_HOST=postgres-svc.dify.svc.cluster.localREDIS_HOST=redis-svc.dify.svc.cluster.local
这样，无论后端Pod的IP如何变化，应用都能通过固定的DNS名称找到它们。cluster.local是K8s集群的默认域名。
4.2 集中化配置管理
Dify有大量的环境变量需要配置，从数据库连接串到第三方API密钥。在K8s中，强烈建议使用ConfigMap和Secret来管理。
- ConfigMap：存储非敏感的配置，如功能开关、日志级别、服务端点。
apiVersion: v1 kind: ConfigMap metadata: name: dify-api-config namespace: dify data: LOG_LEVEL: "INFO" CONSOLE_API_URL: "http://nginx-svc" - Secret：存储敏感信息，如数据库密码、API密钥。务必使用
stringData字段或加密工具（如kubeseal）管理。apiVersion: v1 kind: Secret metadata: name: dify-db-secret namespace: dify type: Opaque stringData: POSTGRES_PASSWORD: "your_strong_password_here"
然后在Deployment或StatefulSet中，通过envFrom或valueFrom引用这些配置。
4.3 对外暴露与Ingress配置
最后一步是让用户能访问到Dify的Web界面。我们之前部署的Nginx Service类型是NodePort，这在开发测试时方便，但在生产环境通常使用Ingress配合域名。
假设你使用的是ingress-nginx控制器，可以创建如下Ingress规则：
apiVersion: networking.k8s.io/v1 kind: Ingress metadata: name: dify-ingress namespace: dify annotations: kubernetes.io/ingress.class: "nginx" # 可根据需要添加更多注解，如SSL重定向、超时设置等 spec: rules: - host: dify.yourcompany.com # 你的域名 http: paths: - path: / pathType: Prefix backend: service: name: nginx-svc # 指向你的Nginx Service port: number: 80配置DNS，将域名解析到Ingress控制器的公网IP或负载均衡器IP。如果需要HTTPS，可以通过cert-manager自动申请和续期Let‘s Encrypt证书，并在Ingress注解中配置TLS。
4.4 监控与日志
一个上线后的生产系统，可观测性必不可少。
- 监控：为每个Deployment和StatefulSet定义合理的资源请求（requests）和限制（limits）。使用Prometheus采集各Pod和容器的CPU、内存、网络指标。为关键服务（如API、数据库）设置自定义的业务指标和告警规则。
- 日志：采用边车模式（Sidecar）或DaemonSet（如Fluentd、Filebeat）收集所有容器的标准输出和错误日志，并统一发送到Elasticsearch、Loki或云厂商的日志服务，方便集中查询和审计。
部署完成后，别急着庆祝，一定要做全面的功能测试：创建应用、配置模型供应商、运行工作流、测试插件安装。特别是网络策略和安全隔离部分，可以尝试在Sandbox代码中访问非白名单地址，验证SSRF-Proxy是否生效。
把Dify社区版部署到K8s生产环境，确实比一键Docker Compose复杂不少，但换来的高可用、弹性伸缩和便于运维的能力，对于承载真实业务流量的平台来说是值得的。整个过程里，最耗时间的往往不是YAML文件的编写，而是对各个组件在生产环境下的交互细节和异常情况的理解。希望这篇实战总结，能帮你绕开我踩过的那些坑，更平滑地完成这次架构升级。如果在部署中遇到其他具体问题，多看看组件的日志，那里面通常藏着最直接的答案。
