Kubernetes部署Dify AI平台：从Docker Compose到K8s原生YAML完整迁移指南

1. 项目概述与核心价值

最近在折腾AI应用开发平台，发现Dify这个工具确实挺有意思，它把大模型应用开发的门槛降得很低。不过，官方主要提供了Docker Compose的部署方式，对于已经将生产环境全面容器化、并且用上了Kubernetes的团队来说，直接套用会有点水土不服。手动把docker-compose.yaml翻译成K8s的YAML，不仅要处理服务发现、配置管理，还得考虑存储、网络策略这些，一套下来也挺费劲。

这就是dify-k8s这个项目出现的原因。它本质上是一个将Dify官方Docker Compose部署方案，完整、忠实地“翻译”成Kubernetes原生资源定义（YAML文件）的项目。我研究了一下当前v1.9.2版本的实现，它的核心价值在于：为已经在K8s生态中的团队，提供了一条部署和运维Dify的“最短路径”。你不用再从头去写Deployment、Service、ConfigMap，这个项目已经帮你把官方的最佳实践打包好了，同时保留了几乎所有的可配置项，比如对象存储（OSS）的集成、向量数据库的切换等，让你能在享受K8s强大编排能力的同时，无缝使用Dify的全部功能。

简单来说，如果你熟悉Kubernetes的基本操作（kubectl apply），那么借助这个项目，你可以在几分钟内就在自己的K8s集群里拉起一套功能完整的Dify环境，无论是用于内部AI工具开发、快速原型验证，还是作为生产环境的基础，都非常合适。

2. 项目架构与设计思路解析

2.1 从Docker Compose到Kubernetes的映射逻辑

要理解dify-k8s，首先得看明白它是如何把Docker Compose的那套东西“搬”到Kubernetes里的。Dify官方docker-compose.yaml定义了多个服务：前端（web）、后端API（api）、工作节点（worker）、Celery Beat调度器，以及依赖的PostgreSQL、Redis等。在K8s里，这些服务会被映射成不同的资源对象。

1. 无状态服务容器化：像api、worker、web这类无状态的应用，被定义为Kubernetes的Deployment。这是最自然的映射，Deployment确保了指定数量的Pod副本始终运行，并且方便滚动更新。项目里的YAML会为每个这样的服务创建对应的Deployment，并配置好资源请求与限制、健康检查探针等。
2. 有状态服务与数据持久化：数据库（PostgreSQL）和消息队列（Redis）是有状态的，在K8s里通常用StatefulSet来管理，但为了简化，这个项目也可能用Deployment配合持久化卷来实现。最关键的一点是数据持久化。项目默认配置了PersistentVolumeClaim（PVC），这意味着你的Pod重启或迁移后，数据不会丢失。这是生产部署的必备条件。
3. 网络与服务发现：Docker Compose通过服务名实现内部网络通信。在K8s中，这是通过Service资源实现的。dify-k8s会为api、postgres、redis等创建ClusterIP类型的Service，形成一个内部网络，让apiPod能通过postgres:5432这样的地址访问数据库。前端（web）服务则通常会被暴露为一个NodePort或LoadBalancer类型的Service，以便从集群外部访问。
4. 配置管理：Docker Compose中的环境变量（environment）在K8s中最佳实践是使用ConfigMap和Secret。dify-k8s的YAML文件里，你会看到大量的环境变量定义，它们被直接编码在Deployment里，或者引用自ConfigMap。对于数据库密码、API密钥等敏感信息，强烈建议用户将其改为从Secret中读取，这是项目留给使用者的优化空间。

2.2 核心配置项的保留与扩展性

项目说明中强调“All configuration items are retained”，这是它的另一个精髓。Dify本身有很多通过环境变量控制的配置，比如：

• LOG_LEVEL：日志级别。
• CONSOLE_API_URL：后端API地址，在K8s内部需要指向api服务的ClusterIP。
• 各类数据库连接字符串（POSTGRES_*,REDIS_*）。
• 文件存储配置（STORAGE_TYPE为s3时，需要配S3_*系列参数）。
• 向量数据库配置（VECTOR_STORE为weaviate或qdrant时，需要配对应参数）。

dify-k8s的YAML文件完整地保留了这些环境变量。这意味着，官方Docker文档里提到的任何配置方式，在这里几乎都能找到对应的环境变量设置。如果你想启用OSS上传，不是去修改代码或构建新的镜像，而只需按照官方指引，找到YAML文件中对应服务的环境变量部分，将STORAGE_TYPE改为s3，并填上S3_ENDPOINT、S3_BUCKET_NAME等参数即可。这种设计保证了项目与官方进展的同步性，也给了使用者最大的灵活性。

2.3 存储设计与StorageClass依赖

“Currently, YAML will do PVC storage. If it is not needed, please handle it yourself.” 这句话点出了一个关键前置依赖和一份责任声明。

关键依赖：PVC需要后端有StorageClass（存储类）来动态提供PersistentVolume（PV）。所以，在部署前，你的Kubernetes集群必须已经配置了至少一个默认的StorageClass，或者你需要手动修改YAML，为每个PVC指定一个已存在的StorageClass。对于云厂商的托管K8s服务（如阿里云ACK、腾讯云TKE），这通常是开箱即用的。对于自建集群（如使用Rancher、Kubeadm），你需要提前部署诸如NFS-Client Provisioner、Ceph RBD等存储解决方案并创建对应的StorageClass。

责任声明：项目默认开启了PVC，这是为了数据安全。但如果你只是在测试，或者有其他的持久化方案（比如HostPath，但不推荐用于生产），你可以选择删除YAML中关于volumeClaimTemplates或volumes/volumeMounts的部分。这就是“please handle it yourself”的含义，项目提供了生产可用的基线配置，但最终如何调整以适应你的具体环境，需要你根据K8s知识自行判断。

3. 详细部署实操与核心环节

3.1 前置环境检查与准备

在动手敲命令之前，做好准备工作能避免很多后续的麻烦。

1. Kubernetes集群：确保你有一个正在运行的K8s集群，并且可以通过kubectl命令正常访问。用kubectl cluster-info和kubectl get nodes验证一下。
2. StorageClass确认：这是最重要的步骤。执行kubectl get storageclass。你需要看到至少一个StorageClass，并且其中有一个的DEFAULT列标记为“yes”。如果没有默认的，你需要记住一个可用的StorageClass名称，后续修改YAML会用到。

   kubectl get storageclass # 期望输出类似： # NAME PROVISIONER RECLAIMPOLICY VOLUMEBINDINGMODE ALLOWVOLUMEEXPANSION AGE # alicloud-disk-essd diskplugin.csi.alibabacloud.com Delete Immediate true 50d # standard (default) rancher.io/local-path Delete WaitForFirstConsumer false 100d

3. 镜像拉取策略：项目YAML中使用的Dify镜像（如langgenius/dify-api:1.9.2）默认从Docker Hub拉取。确保你的集群节点有网络权限能访问Docker Hub，或者你已经将这些镜像同步到了私有仓库，并相应修改了YAML中的镜像地址。
4. 资源规划：粗略估计一下你的Dify环境需要多少资源。默认配置可能只设置了较小的requests/limits。如果预期有较多用户或复杂工作流，建议提前调整YAML中Deployment的resources部分，为CPU和内存设置合适的值，避免Pod因资源不足被驱逐。

3.2 部署步骤详解

假设你已经从GitHub仓库（wyy-holding/dify-k8s）克隆或下载了项目文件，并找到了核心的dify-k8s.yaml（或类似名称的）文件。

第一步：定制化修改YAML（非必须，但强烈建议）

不要直接apply！先打开YAML文件，进行必要的审查和修改。

• 修改StorageClass：在文件中搜索storageClassName。你可能会在PersistentVolumeClaim或StatefulSet的volumeClaimTemplates里找到它。如果集群有默认StorageClass，你可以将storageClassName: xxx这一行直接删除（K8s会自动使用默认的）。如果没有默认的，则将xxx替换为你集群中已有的、合适的StorageClass名称。
• 修改访问方式：搜索type: NodePort（或LoadBalancer），这通常在前端（web）服务的Service定义里。NodePort会在每个节点上开放一个端口（如30000-32767范围）来访问服务。你可以修改nodePort字段指定一个固定端口（需在范围内且未被占用），或者改为type: LoadBalancer（如果云厂商支持，会自动创建外部负载均衡器）。对于内部测试，NodePort最简单。
• 检查配置：快速浏览一下关键环境变量，特别是数据库连接相关的（如POSTGRES_HOST、POSTGRES_PASSWORD），确保它们指向正确的K8s服务名（如postgres）并设置了强密码。

第二步：部署到Kubernetes

1. 为Dify创建一个独立的命名空间（Namespace），这是一个好习惯，便于资源管理。

   kubectl create namespace dify

2. 应用主YAML文件。使用-n参数指定命名空间。

   kubectl apply -f dify-k8s.yaml -n dify

3. 观察部署状态。这个命令会持续显示所有资源的状态，直到所有Pod都变成Running。

   kubectl get pods -n dify -w

   你也可以分别查看不同资源：

   kubectl get deployments,statefulsets,services,pvc -n dify

第三步：访问与验证

1. 获取访问地址：
   • 如果使用NodePort，需要获取任意一个集群节点的IP地址（kubectl get nodes -o wide）和Service暴露的NodePort端口（kubectl get svc -n dify，找到web服务对应的端口）。
   • 如果使用LoadBalancer，等待EXTERNAL-IP分配完成后，直接访问该IP。
   • 如果是本地集群（如Minikube），可以使用minikube service -n dify web --url获取地址。
2. 访问前端：在浏览器中打开上一步获取的地址（例如http://<节点IP>:<NodePort>）。你应该能看到Dify的登录界面。
3. 初始登录：首次访问，通常需要注册第一个管理员账号。按照页面提示操作即可。

注意：Pod启动需要时间，特别是首次拉取镜像时。如果前端页面无法打开，请耐心等待1-2分钟，并用kubectl logs -n dify <web-pod-name>查看前端Pod日志，用kubectl describe pod -n dify <api-pod-name>查看Pod启动失败的具体事件（如镜像拉取失败、健康检查不通过等），这是排查问题的关键。

3.3 核心配置解析：以连接外部数据库为例

项目说明中提到，如果你想连接外部数据库（如云上的RDS PostgreSQL）而不是使用YAML内嵌的数据库，该怎么做？这完美体现了项目“保留所有配置项”的设计。

假设你有一个外部的PostgreSQL实例，地址是myrds.example.com:5432，数据库名为dify，用户为difyuser，密码为securepassword123。

1. 定位配置：在dify-k8s.yaml中，找到api和worker这两个Deployment的定义部分。里面会有大量环境变量。
2. 修改环境变量：你需要修改或确认以下环境变量的值：

   # 在 api 和 worker 的 env 部分 - name: DB_HOST value: "myrds.example.com" # 改为你的外部数据库主机 - name: DB_PORT value: "5432" - name: DB_USER value: "difyuser" - name: DB_PASSWORD value: "securepassword123" # 强烈建议将此值改为从Secret读取！ - name: DB_DATABASE value: "dify" - name: DB_ENGINE value: "postgresql"

   重要安全提示：永远不要将明文密码写在YAML文件中。应该先创建一个K8s Secret：

   kubectl create secret generic dify-db-secret -n dify \ --from-literal=db-password='securepassword123'

   然后在YAML中这样引用：

   - name: DB_PASSWORD valueFrom: secretKeyRef: name: dify-db-secret key: db-password

3. 移除内部数据库服务：既然用了外部数据库，YAML中定义的PostgreSQL的Deployment和Service就不再需要了。你可以选择：
   • 注释或删除：在dify-k8s.yaml中，找到并注释掉（或删除）定义PostgreSQL Deployment和Service的整个YAML块。这是最干净的做法。
   • 保留但不启动：也可以保留，但通过调整副本数为0来禁用它，不过这会留下无用资源。
4. 重新部署：应用修改后的YAML。

   kubectl apply -f dify-k8s.yaml -n dify

   之后，api和workerPod会重启，并使用新的环境变量连接到你的外部数据库。

这个过程清晰地展示了如何利用项目的灵活性。你不需要改动项目代码，只需要遵循K8s和Dify的标准配置方式，就能实现深度定制。

4. 运维、升级与故障排查实录

4.1 版本升级操作指南

当Dify发布新版本（例如从1.9.2升级到1.10.0），或者dify-k8s项目本身更新了YAML配置时，你需要进行升级。项目文档给出了基本步骤，这里补充一些细节和上下文。

1. 修改YAML文件：获取最新的dify-k8s.yaml文件。升级通常涉及两方面：
   • 镜像版本：将文件中所有关于Dify镜像的标签（image: langgenius/dify-api:1.9.2）更新到新版本（如1.10.0）。务必检查api、worker、web等多个组件。
   • 配置变更：新版本Dify可能会新增或修改环境变量。对比新旧YAML，确保必要的配置都已添加。重要：不要直接用新文件覆盖你的旧文件，而是用diff工具对比，将你的自定义配置（如外部数据库连接信息、StorageClass名称、NodePort端口等）合并到新文件中。
2. 应用更新：执行kubectl apply -f dify-k8s.yaml -n dify。Kubernetes会计算当前状态与YAML描述的目标状态之间的差异，并逐步更新资源。对于Deployment，这会触发滚动更新，新Pod会逐个创建，旧Pod会逐个终止，保证服务不中断。
3. 重启有状态负载：文档中提到的kubectl rollout restart statefulset/deployment your-pod-name -n dify是一个更主动的操作。apply命令有时可能不会触发Pod重启（例如，仅环境变量值改变但引用的ConfigMap/Secret名称未变）。为了确保所有Pod都加载了新的镜像和配置，手动重启是更稳妥的做法。
   • 你可以重启所有相关Deployment：

     kubectl rollout restart deployment/api -n dify kubectl rollout restart deployment/worker -n dify kubectl rollout restart deployment/web -n dify

   • 使用kubectl get deployments -n dify查看所有Deployment名称。

实操心得：在生产环境升级前，务必在测试环境先演练一遍。升级后，立即检查前端页面是否正常、核心API功能（如创建应用、对话测试）是否可用。同时监控Pod日志几分钟，观察有无异常报错。对于数据库有重大变更的版本，官方通常会提供迁移脚本，你需要参考Dify官方的升级文档，在升级应用前或后执行相应的数据库迁移命令（通常可以通过kubectl exec进入apiPod执行）。

4.2 常见问题与排查技巧

在部署和运维过程中，你可能会遇到以下典型问题。这里提供一个排查思路的“检查清单”。

排查心法：当遇到问题时，遵循“从外到内，从表象到根源”的顺序：

1. 看整体状态：kubectl get all -n dify，快速了解所有资源是否正常。
2. 看Pod详情：kubectl describe pod，关注Events，这是K8s系统给你的第一手诊断信息。
3. 看应用日志：kubectl logs，这是应用内部的运行时信息，能定位到代码级别的错误。
4. 进入Pod内部：对于网络、配置等问题，可以用kubectl exec -it <pod-name> -n dify -- /bin/sh进入容器，手动执行ping、curl、env等命令进行调试。

4.3 监控、备份与日常维护建议

将Dify部署在K8s上，意味着你可以利用K8s生态的工具进行更好的运维。

• 监控：集成Prometheus和Grafana。可以为Dify的Deployment添加Prometheus注解（annotations），自动抓取应用指标。更简单的方式是使用Kubernetes Dashboard或云厂商提供的监控服务，关注Pod的CPU、内存使用率，以及节点磁盘空间。
• 日志集中管理：使用EFK（Elasticsearch, Fluentd, Kibana）或Loki+Granfana栈，将Dify所有Pod的日志集中收集、存储和查询，便于故障排查和审计。
• 数据备份：这是生命线！虽然PVC提供了持久化，但备份是另一回事。
  • 数据库备份：定期对PostgreSQL数据库执行pg_dump。可以创建一个CronJob资源，定时运行备份命令，并将备份文件上传到云存储。
  • 文件备份：如果你使用了OSS，云厂商通常提供跨区域复制或版本控制功能。如果是本地存储，需要定期备份PVC对应的实际存储卷。
  • 整体备份：可以考虑使用Velero这类工具，对整个dify命名空间进行定时备份和灾难恢复。
• 资源伸缩：在流量高峰时段，你可以手动或通过HPA（Horizontal Pod Autoscaler）自动扩展api和worker的Pod数量。在YAML中为Deployment配置好资源请求和HPA策略即可。

最后，关于调用应用外部API的端口问题，文档提示“不要忘记默认端口31234”。这指的是Dify后端API服务在K8s集群内暴露的端口。当你需要在Dify工作流中调用一个部署在同一K8s集群内的其他服务的API时，可以使用K8s的Service DNS名称，例如http://your-other-service.your-namespace.svc.cluster.local:31234/your-api。如果服务在集群外，则使用外部可达的地址和端口。这个提醒是为了避免开发者误以为API调用总是走80或443端口，在K8s内部网络，Service端口是需要显式指定的。