Helm Chart value.yaml 重要参数的完整指南 - 确定所需更改、按环境调整和维护默认值的标准
在 Kubernetes 上部署 Dify Enterprise 时，values.yaml 是最重要的文件，决定了部署的整体情况。正如官方安装命令helm upgrade -i dify -f values.yaml dify/dify所示，所有生产环境配置差异都被合并到该文件中。
参数有很多，但您不需要全部了解。重要的是将参数分为三层：“必须更改的参数”、“需要针对每个环境调整的参数”和“可以保留为默认的参数”，并对其进行优先级管理。
另外，公式中提供了dify-ee-helm-chart-values-generator来处理数值的复杂性，可用于生成初始配置。
1.values.yaml整体结构
helm show values dify/dify输出的主要部分如下。
values.yaml
├── global # グローバル設定（イメージレジストリ、プルシークレット等）
├── api # API サーバー設定
├── worker # Worker サーバー設定
├── web # Web フロントエンド設定
├── sandbox # コード実行 Sandbox 設定
├── enterprise # Enterprise 固有設定（License 等）
├── ingress # Ingress / ドメイン設定
├── persistence # 永続化設定
├── externalPostgres # 外部 PostgreSQL 接続
├── externalRedis # 外部 Redis 接続
├── externalS3 # 外部オブジェクトストレージ接続
├── postgresql # 内蔵 PostgreSQL（検証用）
├── redis # 内蔵 Redis（検証用）
└── pluginDaemon # プラグイン Daemon 設定
2.必须改变的参数（Must Change）
以下参数不应在生产中使用其默认值。
2.1 域和入口
ingress:
enabled: true
className: "nginx" # 環境に応じて alb, traefik 等
annotations:
cert-manager.io/cluster-issuer: "letsencrypt-prod"
nginx.ingress.kubernetes.io/proxy-body-size: "50m"
tls:
- secretName: dify-tls-cert
hosts:
- console.dify.example.co.jp
- api.dify.example.co.jp
- app.dify.example.co.jp
- upload.dify.example.co.jp
- enterprise.dify.example.co.jp
hosts:
console:
host: console.dify.example.co.jp
api:
host: api.dify.example.co.jp
app:
host: app.dify.example.co.jp
upload:
host: upload.dify.example.co.jp
enterprise:
host: enterprise.dify.example.co.jp
注意：Dify Enterprise 有多个端点：控制台/api/应用程序/上传/企业/触发器。提前设计您的 DNS 和通配符证书。
2.2 秘密/内部通信密钥
api:
secretKey: "" # 必ず強ランダム値に変更
innerApiKey: "" # 必ず強ランダム値に変更
生成示例：
# 32 バイトの hex 文字列を生成
openssl rand -hex 32
**在生产中，我们建议使用 existingSecret，而不是在 value.yaml 中以纯文本形式编写。 **
api:
existingSecret: "dify-api-secrets"
existingSecretKeys:
secretKey: "SECRET_KEY"
innerApiKey: "INNER_API_KEY"
2.3 企业许可模式
enterprise:
enabled: true
licenseMode: "online" # オフライン環境では "offline" に変更
对于离线模式，请参考官方License激活文档，了解如何放置License文件。
2.4 外部数据库连接
在生产中，禁用内置 PostgreSQL 并使用外部托管数据库。
# 内蔵 PostgreSQL を無効化
postgresql:
enabled: false
# 外部 PostgreSQL を有効化
externalPostgres:
enabled: true
host: "dify-prod.cluster-xxxx.ap-northeast-1.rds.amazonaws.com"
port: 5432
username: "dify_app"
database: "dify_production"
existingSecret: "dify-postgres-secret"
existingSecretPasswordKey: "password"
sslMode: "require" # 本番では SSL 必須
2.5 外部Redis连接
redis:
enabled: false
externalRedis:
enabled: true
host: "dify-prod.xxxxx.apne1.cache.amazonaws.com"
port: 6379
existingSecret: "dify-redis-secret"
existingSecretPasswordKey: "password"
useSsl: true
2.6 外部对象存储
externalS3:
enabled: true
bucket: "dify-enterprise-prod"
region: "ap-northeast-1"
endpoint: "" # AWS S3 の場合は空、MinIO の場合は URL を指定
existingSecret: "dify-s3-secret"
existingSecretKeys:
accessKey: "AWS_ACCESS_KEY_ID"
secretKey: "AWS_SECRET_ACCESS_KEY"
3.每个环境需要调整的参数（Per-Environment）
3.1 副本数量
| 组件 | 验证 | 分期 | 生产 |
|---|---|---|---|
| api.replicas | 1 | 2 | 3+ |
| 工人.replicas | 1 | 2 | 3+ |
| 网络副本 | 1 | 1 | 2+ |
| 沙盒.replicas | 1 | 1 | 2+ |
| 企业.副本 | 1 | 1 | 2 |
3.2 资源限制
# 本番向け -- 各コンポーネントに明示的に定義
api:
resources:
requests:
cpu: "2"
memory: "4Gi"
limits:
cpu: "4"
memory: "8Gi"
worker:
resources:
requests:
cpu: "2"
memory: "4Gi"
limits:
cpu: "4"
memory: "8Gi"
web:
resources:
requests:
cpu: "500m"
memory: "512Mi"
limits:
cpu: "1"
memory: "1Gi"
sandbox:
resources:
requests:
cpu: "500m"
memory: "512Mi"
limits:
cpu: "1"
memory: "1Gi"
3.3 日志级别
# 検証環境
api:
env:
LOG_LEVEL: "DEBUG"
# 本番環境
api:
env:
LOG_LEVEL: "WARNING"
3.4 SMTP设置（邮件通知）
api:
env:
MAIL_TYPE: "smtp"
SMTP_SERVER: "smtp.example.co.jp"
SMTP_PORT: "587"
SMTP_USE_TLS: "true"
SMTP_USERNAME: "dify-noreply@example.co.jp"
MAIL_DEFAULT_SEND_FROM: "Dify Enterprise <dify-noreply@example.co.jp>"
existingSecret: "dify-smtp-secret"
3.5 SSO/SAML 集成
在企业版中，可以使用 SAML/OIDC 进行 SSO。与 Azure AD 或 Okta 链接时，请设置以下内容。
enterprise:
sso:
enabled: true
protocol: "saml"
# 具体的な IdP 設定は管理コンソールから行う
3.6 沙盒网络限制
sandbox:
env:
ALLOWED_SYSCALLS: "" # 許可するシステムコールを限定
networkPolicy:
enabled: true
# 許可する通信先を明示的に指定
4. 可以保留默认的参数（Keep Default）
除非有特殊要求，以下内容无需更改。
| 参数类别 | 原因 |
|---|---|
| 实验性功能标志 | 稳定版就可以不用开启 |
| 未使用的插件设置 | 不要触动未使用插件的设置 |
| 未使用的云提供商的连接设置 | 使用 AWS 时，忽略 GCP/Azure 特定项目 |
| 图像标签（如果包含在 Helm Chart 版本中） | 无需指定单独的标签，因为它们由图表版本管理 |
| 内部端口号 | 除非有特殊要求，否则使用默认端口 |
5.参数分类汇总表
| 分类 | 参数示例 | 更改时间 |
|---|---|---|
| 必须改变 | ingress.hosts、secretKey、innerApiKey、externalPostgres、externalRedis、externalS3、enterprise.licenseMode | 首次部署之前 |
| 每个环境 | 副本、资源、LOG_LEVEL、SMTP、SSO、网络策略 | 搭建环境时 |
| 保持默认 | 实验标志、未使用的插件、内部端口 | 仅在需要时 |
6.values.yaml 的版本控制
6.1 使用 Git 存储库进行管理
value.yaml 是基础设施代码本身，由 Git 管理。
infra-repo/
├── helm/
│ └── dify/
│ ├── base-values.yaml # 全環境共通
│ ├── testing-values.yaml # 検証環境上書き
│ ├── staging-values.yaml # ステージング上書き
│ └── production-values.yaml # 本番環境上書き
├── secrets/
│ └── README.md # Secret の管理方針を記載
└── scripts/
└── deploy.sh # デプロイスクリプト
6.2 部署命令示例
# 本番デプロイ（base + 環境別の values を重ねて適用）
helm upgrade -i dify dify/dify \
-n dify-production \
-f helm/dify/base-values.yaml \
-f helm/dify/production-values.yaml \
--wait --timeout 10m
养成在部署之前使用 helm diff 插件检查更改的习惯。
7. 故障排除
价值观引起的常见问题
| 症状 | 原因 | 治疗 |
|---|---|---|
| Pod 发生 CrashLoopBackOff | 错误的数据库连接信息 | 检查 externalPostgres 的主机/端口/凭据 |
| 502 入口 | 服务名称或端口不匹配 | 使用 kubectl get svc 检查实际服务 |
| 许可证认证错误 | 许可证模式不匹配 | 检查在线/离线设置并重启企业pod |
| 文件上传失败 | S3 凭证不正确 | 检查外部S3凭证和存储桶策略 |
| 发送邮件失败 | SMTP 设置不正确 | SMTP_SERVER / PORT / TLS / 检查身份验证信息 |
| OOM 杀死 | 资源限制缺失 | 检查 kubectl describe pod 上的事件并增加限制 |
9. 总结
Helm Chart 的 value.yaml 是 Dify Enterprise 部署的“蓝图”。虽然没有必要破译所有参数，但建议按照以下优先顺序进行处理。
- 首日支持：Domain/Secret/External DB/Redis/S3/License模式
- 搭建环境时支持：副本数量、资源限制、日志级别、SMTP、SSO
- 运行开始后实施：根据需要添加实验性功能和插件设置
使用Git管理values.yaml，针对每个环境将其分开，并在部署前使用helm diff检查差异。养成这三个习惯是Dify Enterprise稳定运营的基础。