企业官网建设流程全解析

本指南以当前仓库中 stable/distribution/README.md 为核心，系统讲解如何在 Kubernetes 上通过 Helm 部署 JFrog Distribution（包含 distribution 与 distributor 两个核心组件及其依赖的 MongoDB、Redis），并深入剖析 values.yaml 中的全部配置参数、外部数据库接入方式、Master Key 唯一化以及 Ingress/TLS 配置。读者读完本文，将能够独立完成该 Chart 的安装、升级、参数定制与问题排查，并理解其底层模板实现（templates 目录）的运作原理。

注意：本 Chart 已在仓库中被标记为DEPRECATED（详见 Chart.yaml 中的deprecated: true与注释说明），新版本由 jfrog/charts 项目维护。若用于新环境，建议优先使用上游新 Chart；本文所述内容以当前仓库中 0.4.3 版本的实现为准，仍可作为理解 JFrog Distribution 在 Kubernetes 上部署架构与配置原理的参考资料。

Chart 组件架构：一次部署四个核心组件

依据 Chart Details 一节 的定义，本 Chart 在helm install后会在集群内完成以下四类组件的部署：

1. MongoDB 数据库：由子 Chart 提供，用于存储 Distribution 的业务数据；
2. Redis：由子 Chart 提供，作为缓存与任务队列存储；
3. distributor：负责将制品从源 Artifactory 分发到目标边缘节点（Edge）；
4. distribution：JFrog Distribution 主服务，对外提供分发任务的编排与管理 API。

这四个组件通过 requirements.yaml 以依赖方式引入子 Chart：

dependencies: - name: mongodb version: 2.0.5 repository: https://kubernetes-charts.storage.googleapis.com/ condition: mongodb.enabled - name: redis version: 1.1.21 repository: https://kubernetes-charts.storage.googleapis.com/ condition: redis.enabled

注意其中的condition: mongodb.enabled与condition: redis.enabled：这正是 README 中"外部数据库"章节能够通过--set mongodb.enabled=false或--set redis.enabled=false关闭内置子 Chart 的底层机制——Helm 会根据该 condition 判断是否渲染对应的依赖 Chart。

从模板实现看（distribution-statefulset.yaml、distributor-statefulset.yaml），distribution 与 distributor 均以StatefulSet方式部署（apiVersion: apps/v1beta2，updateStrategy: RollingUpdate，默认replicas: 1），并各自挂载独立的数据卷。主服务通过 Service 暴露（distribution-svc.yaml），默认端口映射为外部 80 → 内部 8080。

前置条件（Prerequisites）

根据 README 的 Prerequisites Details 与 Requirements 章节，部署前需满足：

• Kubernetes 1.8+；
• 一个正在运行的 Kubernetes 集群；
• 已启用动态存储供给（Dynamic storage provisioning），且已设置默认 StorageClass，以便服务能够通过默认 StorageClass 申请持久化存储；
• 一个正在运行的Artifactory Enterprise Plus实例（Distribution 依赖 Artifactory 作为制品源）；
• 已安装并配置好可访问集群的kubectl；
• 已安装并配置好helm（对应用户需先执行helm init）。

安装 Chart

以 release 名称distribution安装：

helm install --name distribution stable/distribution

访问 Distribution

安装完成后，Distribution 的对外 IP 可能需要在几分钟后才可用，节点完成初始化也需要一定时间。请根据安装命令输出的指引获取 Distribution 的 IP 与访问 URL。

实际模板在 NOTES.txt 中会根据distribution.service.type的取值输出三种不同的访问方式：

• LoadBalancer：kubectl get svc -w <release>观察 Service 状态，然后通过SERVICE_IP访问http://$SERVICE_IP:80/；
• NodePort：通过NODE_IP:NODE_PORT访问；
• ClusterIP：使用kubectl port-forward将本地端口转发到 Pod 后访问。

模板中的默认凭据为：用户名admin，密码password（仅适用于初始登录，生产环境务必修改）。

升级 Distribution

当获取到新的 Chart 版本后，可通过以下命令升级已有部署：

helm upgrade distribution stable/distribution

生成唯一 Master Key

JFrog Distribution 要求集群内所有微服务共享同一个Master Key。Chart 默认在 values.yaml 中内置了一个用于演示的 Key（distribution.masterKey字段，值为一串B字符占位）：

该 Key 仅用于演示，严禁在生产环境使用！

建议在安装/升级时生成唯一 Key 并通过--set传入：

# 生成 256 位（64 个十六进制字符）随机 Key $ export MASTER_KEY=$(openssl rand -hex 32) $ echo ${MASTER_KEY} # 将生成的 Key 传给 Helm $ helm install --set distribution.masterKey=${MASTER_KEY} -n distribution stable/distribution

注意：后续所有helm install与helm upgrade调用都必须携带相同的--set distribution.masterKey=${MASTER_KEY}，否则会导致各微服务之间密钥不一致而无法通信。

从源码看，Master Key 的注入发生在 distribution-statefulset.yaml 的DEFAULT_JAVA_OPTS环境变量中，模板会渲染出-Djfrog.master.key=<masterKey>的 JVM 参数；该文件同时渲染-Ddistribution.home=<mountPath>、-Duser.timezone=UTC与-Dspring.profiles.active=production等生产环境参数，并支持通过distribution.javaOpts.xms/distribution.javaOpts.xmx注入-Xms/-Xmx堆内存配置（注意注释中的提醒：xmx不应高于resources.limits.memory）。

使用外部数据库（External Databases）

Chart 支持为 Distribution 接入外部 MongoDB 或 PostgreSQL（经由连接 URL 语义），也支持接入外部 Redis。核心思路是：关闭内置子 Chart，并传入对应的连接 URL。

外部 MongoDB

使用外部 MongoDB 时，需要关闭内置 MongoDB 子 Chart，并通过global.mongoUrl与global.mongoAuditUrl传入业务库与审计库两个连接串：

参数：mongodb.enabled=false,global.mongoUrl=${DISTRIBUTION_MONGODB_CONN_URL},global.mongoAuditUrl=${DISTRIBUTION_MONGODB_AUDIT_URL}

重要：在部署 Distribution 服务之前，请确保外部数据库已提前创建完成。

# 为 Distribution 传入自定义 MongoDB # 示例 # MongoDB 主机: custom-mongodb.local # MongoDB 端口: 27017 # MongoDB 用户: distribution # MongoDB 密码: password1_X $ export DISTRIBUTION_MONGODB_CONN_URL='mongodb://${MONGODB_USER}:${MONGODB_PASSWORD}@custom-mongodb.local:27017/${MONGODB_DATABSE}' $ export DISTRIBUTION_MONGODB_AUDIT_URL='mongodb://${MONGODB_USER}:${MONGODB_PASSWORD}@custom-mongodb.local:27017/audit?maxpoolsize=500' $ helm install -n distribution --set global.mongoUrl=${DISTRIBUTION_MONGODB_CONN_URL},global.mongoAuditUrl=${DISTRIBUTION_MONGODB_AUDIT_URL} stable/distribution

（注意：示例中的${MONGODB_USER}、${MONGODB_PASSWORD}、${MONGODB_DATABSE}为占位符，实际使用时请替换为真实值。）

从模板实现看，连接串并非直接注入环境变量，而是先由 _helpers.tpl 中的mongodb.url/mongodb.audit.url两个模板函数计算最终 URL（优先取global.mongoUrl/global.mongoAuditUrl，否则基于内置 MongoDB 的用户名密码拼装），再经 mongo-connection-secret.yaml 以Opaque Secret的mongo_connectionString/audit_mongo_connectionString两个 key 存储，最终由 distribution 的 StatefulSet 通过secretKeyRef挂载为mongo_connectionString与audit_mongo_connectionString环境变量。

外部 Redis

使用外部 Redis 时，需要禁用内置 Redis 子 Chart，并通过global.redisUrl传入连接串：

参数：redis.enabled=false与global.redisUrl=${DISTRIBUTION_REDIS_CONN_URL}

重要：部署前请确保外部数据库已提前创建完成。

# 为 Distribution 传入自定义 Redis # 示例 # Redis 主机: custom-redis.local # Redis 端口: 6379 # Redis 密码: password2_X $ export DISTRIBUTION_REDIS_CONN_URL='redis://:${REDIS_PASSWORD}@custom-redis.local:6379' $ helm install -n distribution --set redis.enabled=false,global.redisUrl=${DISTRIBUTION_REDIS_CONN_URL} stable/distribution

Redis 连接串的生成逻辑同样位于 _helpers.tpl 的redis.url模板函数中（优先global.redisUrl，否则使用内置 Redis 的密码与端口拼装），并经 redis-connection-secret.yaml 以 Secret 的redis_connectionString注入到 distribution 与 distributor 两个组件的redis_connectionString环境变量。

关于内置子 Chart 的密码约束

若使用内置 MongoDB/Redis（即不设置global.mongoUrl等），_helpers.tpl中的mongodb.url、mongodb.audit.url、redis.url模板函数会通过required强制要求提供密码：

• .Values.mongodb.mongodbPassword必填（否则渲染时报A valid .Values.mongodb.mongodbPassword entry required!）；
• .Values.redis.redisPassword必填（否则报A valid .Values.redis.redisPassword entry required!）。

因此使用内置数据库时，务必通过--set mongodb.mongodbPassword=... --set redis.redisPassword=...或自定义 values.yaml 提供密码。仓库中 ci/test-values.yaml 给出了 CI 验证用的最小取值示例：

mongodb: mongodbRootPassword: password mongodbPassword: password redis: redisPassword: "password" distributor: token: "<JWT token 示例>"

完整配置参数表

README 的 Configuration 章节 给出了核心参数表。以下在完整继承该表的基础上，补充 values.yaml 中实际存在但 README 未列出的参数（以「(values.yaml 补充)」标注）。所有参数均可通过--set key=value[,key=value]传递给helm install。

参数说明补充

• storageClass 语义（源码见 distribution-statefulset.yaml 与 distributor-statefulset.yaml）：若设置storageClass: "-"，模板会渲染storageClassName: ""以禁用动态供给；若未定义或为nil，则不带storageClassName字段，交由集群默认 provisioner（AWS 上通常为 gp2，GKE 为 standard）。
• MongoDB 的 wiredTiger 缓存：values.yaml 注释明确提醒，--wiredTigerCacheSizeGB不应超过内存限制（limits）的一半，否则可能被 Kubernetes 因 OOMKill 杀死。
• 资源与堆内存：distribution 与 distributor 均支持resources与javaOpts配置；模板会在DEFAULT_JAVA_OPTS中拼接-Xms/-Xmx，务必将xmx控制在resources.limits.memory以内。
• 探针：distribution 的 readiness 探针访问/api/v1/system/ping（初始延迟 60s、周期 10s、失败阈值 10），liveness 探针同为该路径（初始延迟 180s、周期 10s）——这是判断 Distribution 是否健康就绪的官方探测路径。

配置 Ingress 与 TLS

启用 Ingress

要创建带主机名的 Ingress 对象，可向 Helm 命令添加以下参数：

helm install --name distribution \ --set ingress.enabled=true \ --set ingress.hosts[0]="distribution.company.com" \ --set distribution.service.type=NodePort \ stable/distribution

若集群支持自动创建/获取 TLS 证书（例如基于 cert-manager 的机制），可参照对应机制的文档配置自动 TLS。

手动配置 TLS

如需手动配置 TLS，首先为需要保护的主机名创建/获取密钥与证书对，然后在命名空间中创建 TLS Secret：

kubectl create secret tls distribution-tls --cert=path/to/tls.cert --key=path/to/tls.key

然后将 Secret 名称与目标主机名写入自定义values.yaml的 Ingress TLS 段：

ingress: ## 为 true 时创建 Distribution Ingress ## enabled: true ## Distribution Ingress 主机名 ## 启用 Ingress 时必须提供 ## hosts: - distribution.domain.com annotations: kubernetes.io/tls-acme: "true" ## Distribution Ingress TLS 配置 ## Secret 必须提前在命名空间中手动创建 ## tls: - secretName: distribution-tls hosts: - distribution.domain.com

对应的 ingress.yaml 模板实现如下：当ingress.enabled=true时渲染extensions/v1beta1的 Ingress 对象，默认backend指向 distribution 服务（servicePort取distribution.externalPort）；当提供ingress.hosts时为每个主机生成rules规则；当提供ingress.tls时将配置原样toYaml渲染到tls段。

部署机制源码解读：模板如何协作

为了让读者深入理解"一次部署四组件"的实现，这里梳理 templates 目录下各模板文件的职责：

• _helpers.tpl：定义全部命名模板，包括distribution.name/distribution.fullname（遵循 DNS 规范的 63 字符截断）、distributor.fullname、mongodb.url/mongodb.audit.url/redis.url（连接串拼装与 base64 编码）、distribution.serviceAccountName、distribution.chart（chart 名与版本标签）等；
• distribution-statefulset.yaml：distribution 主服务 StatefulSet。其init 容器（init-data，基于initContainerImage）会循环等待mongodb:27017与redis:6379端口可达后才启动主容器；主容器通过secretKeyRef从两个连接 Secret 读取 MongoDB/Redis 连接串，并注入BT_ARTIFACTORY_URL、BT_SERVER_URL以及可选的artifactory_edge_*、artifactory_ci_*环境变量；
• distributor-statefulset.yaml：distributor StatefulSet。其 init 容器（prepare-data）等待 Redis 就绪，并在配置了distributor.token时将 token 复制到挂载路径下的etc/security/token（权限400）并chown 1020:1020；主容器的BT_SERVER_URL自动指向同 release 的 distribution 服务（http://<distribution-fullname>:80）；
• distributor-token.yaml：当distributor.token非空时生成一个 ConfigMap，用于承载 distributor 的认证 token；
• mongo-connection-secret.yaml 与 redis-connection-secret.yaml：分别生成承载 MongoDB（含审计库）与 Redis 连接串的 Opaque Secret；
• distribution-pvc.yaml / distributor-pvc.yaml：PVC 资源（配合 StatefulSet 的volumeClaimTemplates逻辑）；
• distribution-serviceaccount.yaml、distribution-role.yaml、distribution-rolebinding.yaml：ServiceAccount 与 RBAC 资源（values.yaml 默认授予 services/endpoints/pods 的 get/watch/list 权限）；
• distribution-svc.yaml：Distribution 对外 Service，port取externalPort、targetPort取internalPort；
• ingress.yaml：条件渲染的 Ingress 资源；
• NOTES.txt：安装成功后输出的访问指引与默认凭据（admin / password）。

废弃状态与迁移建议

该 Chart 已在 Chart.yaml 中被标记为deprecated: true，版本为0.4.3，appVersion为1.1.0，注释明确指出 Chart 现已迁移至 jfrog/charts 项目维护。因此：

• 存量部署可参考本文档完成日常升级与配置调整；
• 新建环境建议迁移到上游新 Chart，避免继续使用本仓库中已废弃的版本；
• 迁移前请先梳理本文档列出的关键参数（Master Key、MongoDB/Redis 连接、Ingress/TLS、持久化卷），确保新环境配置一致，尤其是Master Key 必须在同一集群的所有微服务间保持一致。

结语

通过本文，读者应已掌握：Distribution Chart 的四组件部署拓扑、安装/升级/访问流程、Master Key 唯一化方法、内置 vs 外部数据库（MongoDB/Redis）的切换方式、完整的参数清单与存储/资源/探针配置要点，以及 Ingress/TLS 的手动配置路径。如需进一步深入，可结合仓库中 values.yaml、requirements.yaml 以及 templates 目录下的模板源码逐一验证本文引用的实现细节。