企业官网建设流程全解析

JasperReports Server 是一款可独立运行或嵌入式使用的开源报表与 BI（商业智能）服务器，提供基于 Web 的报表、分析工具、可视化以及将多个自定义视图聚合到同一面板的 Dashboard 能力。本文以当前仓库stable/jasperreportsHelm Chart 为骨架，完整讲解其安装、卸载、全量配置参数、持久化、Ingress/TLS、升级注意事项以及 Chart 弃用后的迁移路径，并结合 deployment.yaml 等模板源码说明参数到容器环境变量的映射关系。读完本文，你将能够独立在 Kubernetes 集群中部署 JasperReports、按需选择内置 MariaDB 或外部数据库、配置 SMTP 邮件与 Ingress，并安全完成版本升级与仓库迁移。

一、Chart 定位与组件组成

该 Chart 通过 Helm 包管理器在 Kubernetes 集群上引导（bootstrap）一个 JasperReports 部署，其核心组件包括：

• JasperReports 应用容器：默认使用 Bitnami 维护的bitnami/jasperreports镜像（本仓库 Chart 固定版本为7.2.0-debian-10-r24，见 values.yaml）；
• 数据库依赖：Chart 打包了 Bitnami MariaDB Chart（依赖声明见 requirements.yaml，条件mariadb.enabled），默认随应用一起部署一套 MariaDB；也可以关闭内置数据库，改为连接外部数据库；
• Kubernetes 资源：Deployment、Service、Secret、PVC、Ingress 等模板位于 stable/jasperreports/templates 目录下。

从 Chart.yaml 可以看到该 Chart 版本为7.0.11，对应appVersion: 7.2.0，并已标记deprecated: true——这一点会在本文末尾专门说明。

该 Chart 同时可配合 Kubeapps 进行图表部署与管理，并已在 BKPR（Bitnami Kubernetes Production Runtime）之上与 NGINX Ingress、cert-manager、fluentd、Prometheus 一起验证过运行。

二、部署前提条件（Prerequisites）

在安装之前，请确认集群与基础设施满足以下条件（以当前 Chart 的实际声明为准）：

• Kubernetes 1.12+：Deployment 的apiVersion会根据集群版本自动选择（低于 1.14 使用extensions/v1beta1，否则使用apps/v1），见 _helpers.tpl；
• Helm 2.11+ 或 Helm 3.0-beta3+：_helpers.tpl中的镜像与 pullSecrets 逻辑针对 Helm 2.11 的变量作用域行为编写，旧版本可能无法正确渲染；
• 底层基础设施支持 PV（Persistent Volume）供应：JasperReports 与 MariaDB 默认开启持久化，需要集群具备动态或静态存储供应能力；
• 多副本场景需要 ReadWriteMany 卷：如果对 Deployment 进行水平扩容，JasperReports 的数据卷需要支持多节点同时读写。

三、快速安装与卸载

3.1 一条命令完成安装（TL;DR）

$ helm install my-release stable/jasperreports

该命令会以默认配置在集群中部署 JasperReports，同时部署其依赖的内置 MariaDB。

3.2 指定 release 名称安装

$ helm install my-release stable/jasperreports

部署完成后可用helm list查看所有 release。

3.3 卸载

$ helm delete my-release

该命令会删除与该 Chart 关联的所有 Kubernetes 组件并清理 release。

3.4 获取访问地址与登录凭据

安装后 Chart 的 NOTES.txt 会根据service.type与ingress.enabled输出访问指引，以下为不同场景下的核心命令（按模板源码整理）：

• LoadBalancer 模式：等待kubectl get svc --namespace <ns> -w <release名>中出现外部 IP 后执行：

export SERVICE_IP=$(kubectl get svc --namespace default <release名> --template "{{"{{ range (index .status.loadBalancer.ingress 0) }}{{.}}{{ end }}"}}") echo "JasperReports URL: http://$SERVICE_IP/jasperserver/"

• NodePort 模式：

export NODE_PORT=$(kubectl get --namespace default -o jsonpath="{.spec.ports[0].nodePort}" services <release名>) export NODE_IP=$(kubectl get nodes --namespace default -o jsonpath="{.items[0].status.addresses[0].address}") echo "JasperReports URL: http://$NODE_IP:$NODE_PORT/"

• ClusterIP 模式（本地端口转发）：

echo "JasperReports URL: http://127.0.0.1:8080/jasperserver/" kubectl port-forward --namespace default svc/<release名> 8080:80

• 登录凭据：用户名为jasperreportsUsername（默认user），密码自动生成并存储在 Secret 中，可用以下命令解码获取：

echo Username: user echo Password: $(kubectl get secret --namespace default <release名> -o jsonpath="{.data.jasperreports-password}" | base64 --decode)

若既未启用内置 MariaDB 又未提供外部数据库主机，NOTES.txt 会输出 ERROR 提示，并要求通过helm upgrade <release名> --set service.type=...,mariadb.enabled=false,externalDatabase.host=YOUR_EXTERNAL_DATABASE_HOST stable/jasperreports补齐配置。

四、全量配置参数参考（Parameters）

以下是该 Chart 的全部可配置参数及默认值。为便于检索，这里按模块分组整理（内容完整继承自 README，并依据 values.yaml 与各模板源码校正默认值）。

4.1 全局与镜像参数

源码佐证：image.registry、global.imageRegistry与image.tag的组合渲染逻辑见 _helpers.tpl；global.imagePullSecrets与image.pullSecrets的优先级合并逻辑见 _helpers.tpl。

4.2 应用账号与 SMTP 参数

源码佐证：未显式设置jasperreportsPassword时，secrets.yaml 会通过randAlphaNum 10生成随机密码并写入 Secret 的jasperreports-password键；smtpPassword同样被写入 Secret，容器内通过secretKeyRef引用（见 deployment.yaml）。

4.3 数据库参数（内置 MariaDB / 外部数据库）

源码佐证：当mariadb.enabled=true时，容器通过secretKeyRef从 MariaDB 的mariadb-password键读取数据库密码；当关闭内置 MariaDB 时，改为读取${release名}-externaldbSecret 中的db-password键，该 Secret 由 externaldb-secrets.yaml 按externalDatabase.password渲染（空值默认""）。完整分支逻辑见 deployment.yaml。

4.4 Service 与 Ingress 参数

源码佐证：Service 的externalTrafficPolicy仅在类型为LoadBalancer或NodePort时注入，nodePort仅在类型为NodePort且显式指定时写入（见 svc.yaml）；Ingress 的 TLS 配置由 ingress.yaml 遍历ingress.hosts渲染，后端指向servicePort: http。

4.5 持久化、资源与调度参数

源码佐证：PVC 由 pvc.yaml 渲染；storageClass的取值语义（-表示禁用动态供应并写入空storageClassName，nil表示不写该字段从而使用默认供应器，如 AWS 的 gp2、GKE 的 standard）在 _helpers.tpl 中实现；affinity与resources分别注入到 Deployment 的spec.affinity与容器resources字段。

五、配置方式：--set与values.yaml

所有参数都可通过helm install的--set key=value[,key=value]参数指定。例如：

$ helm install my-release \ --set jasperreportsUsername=admin,jasperreportsPassword=password,mariadb.rootUser.password=secretpassword \ stable/jasperreports

该命令将 JasperReports 管理员账号的用户名与密码分别设置为admin和password，同时将 MariaDBroot用户的密码设置为secretpassword。

说明：README 示例中的--set ...mariadb.mariadbRootPassword=secretpassword在 values.yaml 中对应的实际键为mariadb.rootUser.password，配置时以后者为准。

此外，也可以编写 YAML 文件并通过-f传入：

$ helm install my-release -f values.yaml stable/jasperreports

默认的 values.yaml 即为完整的配置模板，所有参数均带有注释说明，可复制后按需修改。

六、源码视角：参数到容器环境变量的映射

透过 deployment.yaml 可以清楚看到每个参数最终如何进入容器：

• 数据库连接：MARIADB_HOST、MARIADB_PORT_NUMBER、JASPERREPORTS_DATABASE_NAME、JASPERREPORTS_DATABASE_USER直接取自对应 values；JASPERREPORTS_DATABASE_PASSWORD一律通过secretKeyRef从 Secret 注入，避免明文出现在 Pod Spec 中；
• 应用账号：JASPERREPORTS_USERNAME直接取值，JASPERREPORTS_PASSWORD从 release Secret 的jasperreports-password键读取；
• 邮件配置：SMTP_HOST、SMTP_PORT、SMTP_EMAIL、SMTP_USER、SMTP_PROTOCOL仅在对应 values 非空时注入，SMTP_PASSWORD则从 Secret 的smtp-password键读取；
• 健康检查：容器监听8080端口（containerPort: http）；liveness 探针探测/jasperserver/login.html，initialDelaySeconds: 300、timeoutSeconds: 5、failureThreshold: 6；readiness 探针同样探测登录页，initialDelaySeconds: 30、timeoutSeconds: 3、periodSeconds: 5。这些阈值意味着应用启动较慢时探针不会误杀 Pod；
• 数据卷：/bitnami/jasperreports目录挂载jasperreports-data卷；persistence.enabled=true时挂载 PVC，否则退化为emptyDir（数据不持久）。

这些环境变量名与 values.yaml 中注释指向的 Bitnami JasperReports 容器镜像文档保持对应。

七、持久化存储详解

Bitnami JasperReports 镜像将报表数据与配置保存在容器内的/bitnami/jasperreports路径下，因此 Chart 使用 Persistent Volume Claims 保证数据在 Deployment 重建后不丢失。

• 该方案已在GCE、AWS 与 minikube上验证可用；
• 默认 PVC 大小8Gi、访问模式ReadWriteOnce，详见 values.yaml；
• persistence.storageClass的三种语义需特别注意：设为具体类名则写入storageClassName；设为"-"则写入空字符串从而禁用动态供应；留空/null则不写该字段，交由集群默认供应器（AWS 的 gp2、GKE/AWS/OpenStack 的 standard）处理；
• 内置 MariaDB 同样默认开启持久化（mariadb.master.persistence.enabled: true、8Gi、ReadWriteOnce）；
• 若彻底不需要持久化，可将persistence.enabled与mariadb.master.persistence.enabled置为false。

八、Ingress 与 TLS 集成

将ingress.enabled设为true后，Chart 会生成 Ingress 资源，默认主机名为jasperreports.local，路径/转发到 Service 的http端口：

• 多主机：ingress.hosts为数组，可同时覆盖多个主机名；
• TLS：将某个 host 的tls置为true，并指定tlsSecret（默认jasperreports.local-tls-secret）；tlsHosts可用于声明与主机名不同的 TLS 主机列表（例如配合支持 www 跳转的 Ingress 控制器）；
• cert-manager：将ingress.certManager置为true，模板会自动注入kubernetes.io/tls-acme: "true"注解（见 ingress.yaml），由 cert-manager 自动签发并创建证书 Secret；
• 自带证书：可在ingress.secrets数组中提供name、certificate、key，内容需以-----BEGIN CERTIFICATE-----或-----BEGIN RSA PRIVATE KEY-----开头；若使用 cert-manager，则无需手动提供 Secret；
• 自定义注解：通过ingress.annotations传入任意 key:value 注解，例如kubernetes.io/ingress.class: nginx。

九、镜像 Tag 策略：Rolling 与 Immutable 的区别

生产环境强烈建议使用不可变（immutable）Tag，避免同名的滚动 Tag 被上游更新后，集群在拉取时静默切换到内容不同的镜像，导致无法预期的行为变更。如果镜像 Tag 形如7.2.0-debian-10-r24（带-r<数字>后缀），即为不可变 Tag。

NOTES.txt 还会自动检测：当image.repository包含bitnami/且 Tag 不是-r\d+$结尾或 sha256 摘要时，会输出 "Rolling tag detected" 的警告。Bitnami 会在主容器发布新版本、出现重大变更或存在关键漏洞时发布新版 Chart 并更新容器。

十、升级注意事项（Upgrading）

10.1 升级到 7.0.0：Deployment apiVersion 变更

Helm 会依据资源的 GroupVersionKind（GVK，即 group=apps、version=v1、kind=Deployment）执行对象查找。7.0.0 版本将该 Chart 的 DeploymentapiVersion更新为apps/v1（与旧 API 弃用节奏保持一致），而 GVK 变更在 Kubernetes 视角下属于兼容性破坏，无法原地"升级"旧对象。因此从更早版本升级到 7.0.0 时，需要按 Helm 的处理方式重新创建相关 Deployment 资源。

实现佐证：当前 deployment.yaml 的 apiVersion 由_helpers.tpl中的jasperreports.deployment.apiVersion模板决定，Kubernetes 1.14 及以上使用apps/v1。

10.2 升级到 3.0.0：Selector 标签变更

3.0.0 之前版本的 Chart 在 Deployment 的spec.selector.matchLabels中带有chart标签，新版本移除了该标签，因此向后兼容性不再保证，需要先手工调整旧资源后再升级。以下示例假设 release 名为jasperreports：

$ kubectl patch deployment jasperreports-jasperreports --type=json -p='[{"op": "remove", "path": "/spec/selector/matchLabels/chart"}]' $ kubectl delete statefulset jasperreports-mariadb --cascade=false

执行后，再使用新版本 Chart 重新升级 release，即可让新 Deployment 的 selector 接管现有 Pod。

十一、Chart 弃用声明与迁移到 Bitnami 仓库

由于 Helmstable仓库进入弃用时间线，本 Chart（含 Chart.yaml 中的deprecated: true标记与 NOTES.txt 开头的弃用说明）已停止维护，JasperReports 的 Bitnami 维护版 Chart 迁移至bitnami/charts仓库，Bitnami 仓库已纳入 Helm Hub，后续更新、支持节奏保持不变。安装方式非常相似，只需添加bitnami仓库并在安装时使用bitnami/<chart>替代stable/<chart>：

$ helm repo add bitnami https://charts.bitnami.com/bitnami $ helm install my-release bitnami/<chart> # Helm 3 $ helm install --name my-release bitnami/<chart> # Helm 2

将已有的stable部署升级到 Bitnami 仓库中的 Chart：

$ helm repo add bitnami https://charts.bitnami.com/bitnami $ helm upgrade my-release bitnami/<chart>

关于 Chart 本身的 Issue 与 PR 会被转交至bitnami/chartsGitHub 仓库；与本次迁移过程相关的疑问集中在helm/charts仓库的迁移讨论 Issue 中统一答复。对于正在使用本仓库 Chart 的读者，建议评估后尽快迁移，以获得持续的漏洞修复与版本更新。