1. 项目概述与核心价值最近在折腾AI应用开发平台发现Dify这个工具确实挺有意思它把大模型应用开发的门槛降得很低。不过官方主要提供了Docker Compose的部署方式对于已经将生产环境全面容器化、并且用上了Kubernetes的团队来说直接在K8s里跑Dify显然更符合技术栈的统一管理。网上虽然有一些零散的部署经验但要么配置不全要么版本老旧踩坑无数之后我决定基于官方的docker-compose.yaml从头到尾构建一套完整、可配置的Kify K8s部署方案也就是这个dify-k8s项目。简单来说这个项目就是把Dify官方Docker Compose的所有服务包括Web前端、API后端、Celery Worker、Redis、PostgreSQL等全部“翻译”成了Kubernetes的YAML资源定义文件。它的核心价值在于你无需再手动去拆解Compose文件、处理服务依赖和网络配置直接使用这套YAML就能在K8s集群里一键拉起一个功能完整、配置灵活的Dify环境。无论是想快速搭建一个内部使用的AI应用开发平台还是为团队提供标准化的模型服务底座这套方案都能帮你省下大量前期研究和调试的时间。2. 方案设计思路与架构解析2.1 从Docker Compose到Kubernetes的映射逻辑官方Docker Compose文件是单机环境下的服务编排标准而Kubernetes是分布式环境下的容器编排平台两者的设计哲学和资源模型不同。我的设计思路不是简单粗暴地“一键转换”而是基于对Dify架构的理解进行针对性的适配。首先我分析了docker-compose.yaml中的每一个服务。Dify的核心服务包括api 提供RESTful API的后端服务是核心业务逻辑所在。worker 处理异步任务如知识库文档处理、对话生成的Celery Worker。web 基于Nginx的静态前端文件服务。redis 用作Celery的消息代理和结果后端也用于缓存。db PostgreSQL数据库存储应用、对话、知识库等核心数据。在K8s中这些服务被映射为不同的资源类型无状态服务Deploymentapi、worker、web。这些服务可以水平扩展多个副本间没有状态依赖。因此我为它们创建了Deployment资源并配置了相应的副本数、资源请求与限制。有状态服务StatefulSetdbPostgreSQL。数据库是有状态的需要稳定的网络标识和持久化存储。使用StatefulSet可以确保Pod在重新调度后依然能挂载到原来的持久卷PV并且主机名稳定这对于数据库主从配置虽然当前是单机和连接至关重要。缓存/消息中间件Deployment Serviceredis。虽然Redis也可以是有状态的但在Dify的默认配置中它主要用作缓存和消息队列数据可丢失或重建。因此我选择了Deployment来部署并通过PVC为其提供持久化存储以防容器重启导致缓存热点数据丢失。如果追求更高可用性未来可以考虑部署Redis哨兵或集群模式。配置与网络 将Compose中的环境变量翻译为K8s的ConfigMap和Secret将服务发现和端口暴露通过Service资源实现。2.2 配置灵活性与可扩展性设计官方Dify的很多高级功能如使用外部OSS存储文件、切换向量数据库从PGVector到Milvus/Qdrant等都是通过环境变量配置的。为了保留这份灵活性我的方案采取了以下设计环境变量集中管理 所有从docker-compose.yaml中提取的环境变量都被分类整理到K8s的ConfigMap中。例如数据库连接字符串、Redis地址、应用密钥等放在一个ConfigMap而OSS配置、向量数据库连接信息等可能包含敏感数据或需要频繁变动的配置则被单独列出方便用户按需修改和挂载。存储抽象化 方案默认使用了Kubernetes的PersistentVolumeClaimPVC来为数据库、Redis和上传文件目录如果使用本地存储提供持久化存储。这是K8s的最佳实践。我在YAML中为这些PVC指定了storageClassName字段。这是关键一步用户必须根据自己集群的实际情况修改这个storageClassName指向集群中已存在的StorageClass或者如果不需要持久化仅用于测试可以修改为使用emptyDir临时卷。服务暴露方式 前端web服务通过NodePort类型的Service暴露方便在集群外通过节点IP和端口如节点IP:31234访问。对于生产环境用户完全可以按需修改为LoadBalancer类型并配合云厂商的负载均衡器或者通过Ingress控制器来提供域名访问。资源预留与限制 在每个Deployment的Pod模板中我都预定义了resources.requests和resources.limits。这是保障应用稳定性和集群公平性的重要措施。请求值requests是调度依据限制值limits防止单个Pod耗尽节点资源。用户需要根据自身业务负载和节点配置调整这些CPU和内存值。3. 详细部署步骤与实操要点3.1 前置环境准备在开始部署dify-k8s之前你需要一个正常运行的Kubernetes集群。无论是本地的Minikube、Kind还是云上的EKS、ACK、TKE等托管集群都可以。这里以大多数环境为例进行说明。首先确保你的kubectl命令行工具已经正确配置可以连接到目标集群。kubectl cluster-info这个命令应该能正确显示集群的控制平面地址和核心服务状态。接下来最关键的一步是确认集群的StorageClass。StorageClass是K8s中动态供给持久卷的抽象。我们的YAML文件里指定了名为standard的StorageClass如果你的集群里不是这个名字例如在阿里云ACK上可能是alicloud-disk-ssd在AWS EKS上可能是gp2部署就会因为找不到存储类而卡住。列出集群中的所有StorageClasskubectl get storageclass查看哪个StorageClass被标记为defaultkubectl get storageclass -ojsonpath{range .items[*]}{.metadata.name}{\t}{.provisioner}{\t}{.metadata.annotations.storageclass\.kubernetes\.io/is-default-class}{\n}{end}如果已有默认的StorageClass输出中会显示true。如果没有默认的或者你想使用特定的StorageClass你有两个选择修改YAML文件 将dify-k8s.yaml中所有storageClassName: standard替换为你集群中存在的StorageClass名称。设置默认StorageClass 为你选择的StorageClass打上默认标签。kubectl patch storageclass 你的storageclass名称 -p {metadata: {annotations:{storageclass.kubernetes.io/is-default-class:true}}}实操心得 很多部署失败都卡在PVC无法绑定PV这一步。务必提前处理好StorageClass。对于本地测试集群如Minikube通常已经配置好了名为standard的StorageClass。对于云上集群务必使用云盘对应的StorageClass否则无法自动创建云盘。3.2 部署Dify应用到Kubernetes集群环境准备好后部署过程就非常标准化了。创建独立的命名空间 为Dify应用创建一个独立的命名空间是个好习惯便于资源管理和隔离。kubectl create namespace dify应用主配置文件 进入dify-k8s项目目录执行以下命令。-n dify参数指定了资源部署到我们刚创建的命名空间。kubectl apply -f dify-k8s.yaml -n dify这条命令会依次创建ConfigMap、Secret如果有、Service、PersistentVolumeClaim、Deployment、StatefulSet等所有资源。监控部署状态 应用YAML文件后K8s需要一些时间来拉取镜像、创建容器、调度Pod。你可以使用以下命令观察部署进度# 查看命名空间下所有Pod的状态 kubectl get pods -n dify -w当所有Pod的STATUS都变为Running并且READY列显示为1/1或2/2取决于容器数量时表示部署成功。# 查看所有创建的Service注意前端服务的NodePort端口 kubectl get svc -n dify你会看到一个名为dify-web的Service其PORT(S)列类似80:31234/TCP这意味着集群外可以通过任意节点的IP地址和31234端口访问Dify前端。3.3 访问与初始化验证部署完成后你可以通过两种方式访问DifyNodePort方式 在浏览器中输入http://你的K8s节点IP:31234。节点IP可以是Master或Worker节点的公网IP或内网IP确保防火墙规则允许该端口访问。端口转发临时测试 如果集群在本地或网络不通可以使用kubectl port-forward临时将服务端口映射到本地。kubectl port-forward svc/dify-web -n dify 8080:80然后在浏览器访问http://localhost:8080。首次访问你应该能看到Dify的初始化界面按照提示完成管理员账号注册即可。这同时验证了前端web、后端api和数据库db之间的连接是正常的。注意事项 如果访问时出现“502 Bad Gateway”或连接超时不要慌。首先检查dify-api这个Pod的日志它很可能还在启动或初始化数据库中。kubectl logs -f deployment/dify-api -n dify常见的启动错误包括数据库连接失败检查db Pod状态和数据库环境变量、Redis连接失败等。通过日志可以快速定位问题。4. 核心配置解析与自定义指南4.1 环境变量配置详解dify-k8s.yaml中的ConfigMapdify-env包含了大部分配置。理解关键配置项能帮你更好地定制自己的Dify环境。数据库配置(DB_*) 指向的是K8s内部Servicedify-db的DNS名称dify-db.dify.svc.cluster.local。这是K8s内置的DNS服务发现的优势无需知道Pod的具体IP。请确保这里的数据库名、用户名、密码与PostgreSQL StatefulSet中初始化脚本设置的一致。Redis配置(REDIS_HOST) 同样指向内部Servicedify-redis。这保证了应用内通信的隔离和稳定性。外部访问地址(CONSOLE_API_URL,APP_API_URL,CONSOLE_WEB_URL) 这些URL用于前端向后端发起API请求。在默认的NodePort部署下它们被设置为http://节点IP:31234。如果你使用了Ingress或LoadBalancer并通过域名访问必须将这些配置修改为你的公网域名否则前端会向错误的地址发起请求。文件存储 默认配置可能使用本地存储。如果你需要将用户上传的文件、应用图标等存储到阿里云OSS、AWS S3等对象存储需要配置STORAGE_TYPE、OSS或S3相关的一系列环境变量。这些配置通常涉及AccessKey等敏感信息强烈建议将其放入K8s Secret中而非明文写在ConfigMap。你可以在YAML中创建额外的Secret资源然后通过env.valueFrom.secretKeyRef的方式挂载到api和worker的容器环境中。4.2 存储与持久化配置持久化是生产部署的基石。我们的YAML为三个组件声明了PVCdify-db-pvc 供PostgreSQL StatefulSet使用存储数据库文件。dify-redis-pvc 供Redis Deployment使用存储RDB/AOF持久化文件。dify-uploads-pvc 供api和workerDeployment使用挂载到容器内的上传文件目录如/app/storage。仅在STORAGE_TYPE为local时生效。如果使用了OSS/S3这个卷可以移除或保留用于临时文件。自定义存储修改StorageClass 如前所述根据集群环境修改storageClassName。调整存储大小 PVC中resources.requests.storage字段定义了申请空间的大小如10Gi。请根据数据量预估进行调整。使用已有存储 如果你已经有现成的PV例如云盘快照恢复的数据可以修改PVC的spec添加volumeName字段直接绑定特定PV并可能需要调整accessModes和storageClassName。4.3 网络与服务暴露进阶默认的NodePort方式简单但端口范围有限30000-32767且缺乏负载均衡和域名管理。生产环境建议升级LoadBalancer 将dify-webService的类型改为LoadBalancer。在云环境下这会自动创建一个云负载均衡器并分配一个公网IP。你需要将前面提到的CONSOLE_WEB_URL等地址改为这个负载均衡器的IP或域名。Ingress 这是更优雅的方式。你需要先为集群安装Ingress Controller如Nginx Ingress Controller。然后创建一个Ingress资源将你的域名例如dify.yourcompany.com路由到dify-web服务的80端口。同时配置TLS证书以实现HTTPS访问。这样外部访问地址就变成了https://dify.yourcompany.com所有环境变量中的URL也需要相应更新。5. 运维、升级与故障排查实录5.1 应用升级流程当Dify发布新版本例如从v1.9.2升级到v1.10.0你需要升级集群中的部署。我们的方案升级非常清晰修改镜像版本 打开dify-k8s.yaml文件找到所有image字段主要存在于api、worker、web的Deployment中。将镜像标签tag从当前的v1.9.2修改为目标版本如v1.10.0。重要提示 务必在Dify官方发布公告或镜像仓库中确认新版本镜像可用。不同版本间数据库结构可能有变更官方通常会在Release Notes中说明是否需要执行数据库迁移脚本。我们的YAML中api容器的启动命令包含了数据库迁移步骤通常能自动处理。应用配置更新 执行kubectl apply命令K8s会按照“滚动更新”的策略逐步用新版本的Pod替换旧版本的Pod。kubectl apply -f dify-k8s.yaml -n dify监控更新状态 使用kubectl rollout status命令跟踪Deployment的更新进度。kubectl rollout status deployment/dify-api -n dify kubectl rollout status deployment/dify-worker -n dify kubectl rollout status deployment/dify-web -n dify直到所有新Pod都变为Ready状态。重启有状态服务如需 对于StatefulSet如dify-db和需要同步更新的配置如果新版本有要求可能需要手动重启。但数据库升级需极其谨慎建议先备份。kubectl rollout restart statefulset dify-db -n dify5.2 常见问题与排查技巧在实际部署和运维中你可能会遇到以下问题。这里提供一套排查思路问题一Pod一直处于Pending状态。排查kubectl describe pod pod-name -n dify。查看Events部分。可能原因及解决资源不足 节点没有足够的CPU或内存满足Pod的requests。可以适当降低resources.requests的值或为集群添加节点。PVC无法绑定 最常见的原因。事件中会出现Failed to provision volume with StorageClass standard...。确认StorageClass名称是否正确或云盘配额是否已满。问题二Pod处于CrashLoopBackOff或Error状态。排查kubectl logs pod-name -n dify查看容器日志。可能原因及解决数据库连接失败 日志中会出现psycopg2.OperationalError或connection refused。检查dify-dbPod是否运行正常以及ConfigMap中的DB_HOST、DB_PASSWORD是否正确。镜像拉取失败 事件中会出现ErrImagePull。检查镜像名称和标签是否正确以及节点网络是否能访问Docker Hub或你的私有镜像仓库。应用启动错误 例如缺少某个环境变量或环境变量值格式错误。仔细核对ConfigMap中的配置特别是包含特殊字符或长字符串的配置项。问题三前端能访问但登录或操作时报API错误如500、502。排查 这通常是后端服务dify-api或dify-worker的问题。首先检查dify-apiPod的日志kubectl logs -f deployment/dify-api -n dify。查看是否有未处理的异常、数据库迁移失败、或第三方服务如OpenAI API调用失败。检查dify-worker的日志看异步任务处理是否正常kubectl logs -f deployment/dify-worker -n dify。问题四如何调用部署在K8s内的Dify应用的API内部调用 在集群内其他Pod中可以通过Service的DNS名称调用例如http://dify-api.dify.svc.cluster.local/v1/...。外部调用 如果你需要从集群外部如自己的业务服务器调用Dify的API你需要通过dify-webService暴露的端口。假设节点IP是192.168.1.100NodePort是31234那么API基础地址就是http://192.168.1.100:31234。在Dify前端页面的“API访问”页面获取密钥后调用时需携带此密钥并注意端口。例如使用curl测试curl -X GET http://192.168.1.100:31234/v1/models -H Authorization: Bearer your-app-api-key注意 生产环境强烈建议通过Ingress配置HTTPS和域名并使用域名进行访问这样更安全、更规范。问题五如何备份和恢复数据数据安全无小事。主要备份两个部分数据库备份 进入dify-dbPod执行pg_dump。kubectl exec -it dify-db-0 -n dify -- pg_dump -U dify -d dify dify_backup_$(date %Y%m%d).sql上传文件备份 如果使用本地存储需要备份dify-uploads-pvc对应的PV数据。具体方法取决于你的存储类型如云盘快照、文件系统备份工具。恢复 创建新的PVC/PV将备份文件导入然后修改Deployment的挂载指向新的卷。对于数据库可以在初始化新Pod时将备份SQL文件挂载为初始化脚本。这套dify-k8s方案是我在多次实践和踩坑后总结出来的它最大程度地保留了Dify的原有功能同时融入了Kubernetes生态的最佳实践如声明式配置、服务发现、资源管理和滚动更新。它可能不是最完美的但一定是一个坚实可靠的起点。你可以以此为基础根据自己团队的CI/CD流程、监控告警体系、安全策略进行进一步的定制和加固构建出更加强大的内部AI生产力平台。