企业官网建设流程全解析

• 后端
• 认证鉴权
• 单点登录

本指南以 Apereo CAS 官方文档 Kubernetes-Helm-Deployment 为主体，系统讲解如何借助 CAS WAR Overlay Initializr 生成的 Helm Chart，在本地 Kubernetes 集群（以 K3S 为主）上完成 CAS 单点登录服务的安装、配置、排障与访问验证。读完本文，你将掌握 Helm 的核心概念、CAS Helm Chart 的架构组成、从环境准备到helm upgrade --install落地的完整命令行流程，以及借助kubectl进行日常运维与问题定位的实用技巧。

前置准备：Helm Chart 从哪里来

CAS 的 Helm Chart 并不是随本仓库（Apereo CAS 服务器源码）直接分发的独立产物，而是内置于 CAS WAR Overlay Initializr 生成的 overlay 工程中。该 Initializr 基于 Spring Initializr 框架构建，允许部署者通过 curl 友好的 API 快速生成包含所需模块与依赖的 CAS WAR Overlay 工程，例如：

function getcas() { url="https://getcas.apereo.org/starter.tgz" ... cmd="curl ${url} -d type=${projectType} -d baseDir=${directory} ${dependencies} ${casVersion} ${bootVersion} | tar -xzvf -" eval "${cmd}" } getcas --modules duo,oidc

生成出来的 overlay 工程同时包含两样关键资产：

• CAS 容器镜像构建脚本：后续需要用./gradlew clean build jibBuildTar构建 CAS Docker 镜像；
• Helm Chart（helm/目录）：其中包含templates/模板目录、values.yaml默认值文件，以及若干用于生成证书与信任库的辅助脚本。

文档特别提醒：当前 Helm Chart 尚属较新阶段，官方提示在稳定之前可能不会发布到公开 Helm 仓库，因此更适用于具备 CAS 与 Kubernetes 经验的部署者，作为自托管部署方案来使用。本指南默认你已通过 Initializr 创建好 overlay 工程。

若你希望由 Kubernetes 直接管理 CAS 的配置（而非用 ConfigMap 手工下发），可同时参考官方文档 Spring Cloud 配置中心 - Kubernetes 支持，其对应的仓库模块为 cas-server-support-configuration-cloud-kubernetes，通过spring.cloud.kubernetes.secrets、spring.cloud.kubernetes.config相关属性即可从ConfigMap与Secret中加载配置。

什么是 Helm

Helm 是 Kubernetes 的包管理工具，其核心单位是Chart。一个 Helm Chart 是一组模板，模板与“部署环境相关的 values 值”组合后，即可生成最终的 Kubernetes 配置 YAML。理解 Helm 的工作方式有助于后续排错：

• Chart 作者定义模板与默认值；
• 部署者编写自己的 values 文件，覆盖Chart 定义的任何默认值；
• 部署者无需修改模板即可完成安装；
• 若发现模板本身需要变更，这类改动是回馈给 Chart 上游的候选，能让 Chart 在后续迭代中变得更加可定制、支持更多部署选项。

CAS Helm Chart 概览

当前 CAS Helm Chart 的部署形态与设计要点如下：

此外，Chart 中 CAS 与 Spring Boot Admin 之间的服务发现方式，官方建议未来可迁移至 “cloud” 模式发现；Boot Admin 拥有独立 Ingress，因为它定位为内部可访问，而 CAS 通常对外暴露——两者也可同时设为内网或同时对外。

在本地 Kubernetes 上安装 CAS

安装 Helm 与 Kubectl

Helm v3 与 Kubectl 都是单一二进制程序，Kubectl 可能随 Kubernetes 安装自带，但两者都应下载并放入PATH：

• 安装 Helm：参考 Helm 官方安装文档
• 安装 Kubectl：参考 Kubernetes 官方安装文档

安装 Kubernetes

Mac、Windows、Linux 上有多种本地 Kubernetes 集群方案，但它们都要求 Linux 作为 VM 或宿主操作系统。CAS Helm Chart 在 CAS Initializr 的 CI 脚本中基于K3S安装并测试，因此 K3S 方式“始终可用”；Windows 与 Mac 用户则需要先安装 Linux 虚拟机（例如运行 Ubuntu）。

K3S Kubernetes

k3s 运行于 Linux，非常轻量、易于安装，适合开发场景，且不强制安装 Docker。以下为完整安装链路：

# 安装 k3s，禁用 traefik ingress controller（后续使用 ingress-nginx） curl -sfL https://get.k3s.io | INSTALL_K3S_EXEC="server --disable traefik" sh # helm 需要此环境变量，建议写入 profile export KUBECONFIG=/etc/rancher/k3s/k3s.yaml # 用 Initializr 生成的 overlay 构建 CAS 镜像 ./gradlew clean build jibBuildTar --refresh-dependencies # 导入镜像到 k3s（k3s 能从 registry 拉取镜像，但看不到本地 Docker 镜像） k3s ctr images import build/jib-image.tar # 验证镜像已加载 k3s ctr images ls | grep cas # 进入 helm chart 目录 cd helm # 为 Tomcat 创建 keystore secret ./create-cas-server-keystore-secret.sh # 为 ingress controller 创建 TLS secret（未创建时 nginx-ingress 会使用默认值） ./create-ingress-tls.sh # 创建包含 SSL 信任库的 configmap ./create-truststore.sh # 安装 cas-server helm chart helm upgrade --install cas-server ./cas-server

镜像导入的关键点：jibBuildTar产出的是build/jib-image.tar文件，K3S 无法直接读取 Docker 守护进程中的本地镜像，必须通过k3s ctr images import显式导入；这也是官方脚本刻意采用“构建 tar → 导入”两步的原因。

其他本地集群选项

• Docker Desktop：安装后到 Settings 中启用 Kubernetes；在 bash 终端（Windows 上可用 Git Bash、Cygwin 或 Msys2）确保 Helm 与 Kubectl 在 PATH 中；运行helm/子目录中的证书与信任库脚本；构建镜像./gradlew clean build jibBuildTar --refresh-dependencies；本地加载docker load < build/jib-image.tar；再安装 Ingress Controller 并安装 CAS Helm Chart。
• Minikube：参考 Minikube 官方文档，其流程包括安装 kubectl 与 minikube、启动集群、minikube mount挂载配置目录到/etc/cas/、加载镜像后创建casService 并应用 deployment.yaml，最后通过kubectl port-forward svc/cas 8443:8443与curl -k https://localhost:8443/cas/login验证登录页可访问——可以作为本地快速验证 CAS+Kubernetes 组合的参考实现。

安装 Ingress Controller

CAS Helm Chart仅针对 Kubernetes ingress-nginx 测试过，欢迎为其他 ingress controller 增加支持。使用 Helm 安装ingress-nginx：

helm repo add ingress-nginx https://kubernetes.github.io/ingress-nginx kubectl create namespace ingress-nginx helm install --namespace ingress-nginx ingress-nginx ingress-nginx/ingress-nginx kubectl wait --namespace ingress-nginx \ --for=condition=ready pod \ --selector=app.kubernetes.io/component=controller \ --timeout=120s

Ingress Controller 安装指南可参考 Kubernetes Nginx Ingress 官方部署文档。

安装 CAS Server Helm Chart

Helm Chart 由模板与一个或多个 values 文件（外加命令行 set 参数）组合生成 Kubernetes YAML。Chart 目录（包含templates/子目录）内置默认values.yaml，额外 values 文件应在命令行显式指定以按需覆盖默认值。

以下命令默认使用default命名空间；若希望 CAS 位于独立命名空间，可为任意helm命令追加--namespace cas（需先创建命名空间，如kubectl create namespace cas）：

# 删除 cas-server chart 安装 helm delete cas-server # 安装 cas-server chart helm install cas-server ./cas-server # 安装或更新 cas-server helm upgrade --install cas-server ./cas-server # 使用本地 values 文件覆盖默认值 helm upgrade --install cas-server --values values-local.yaml ./cas-server # 只渲染 Kubernetes YAML，不实际安装（用于检查） helm upgrade --install cas-server --values values-local.yaml ./cas-server --dry-run --debug # 当 dry-run 因 YAML 无法转 JSON 而失败时，改用 template 定位问题 helm template cas-server --values values-local.yaml ./cas-server --debug

排错提示：--dry-run --debug偶尔会因渲染出的 YAML 无法转换为 JSON 而失败，此时helm template ... --debug是更直接的“只渲染不安装”手段，便于快速定位模板或 values 语法问题。

常用kubectl命令

若使用非默认命名空间，别忘了追加-n或--namespace：

# 查看 pod 状态 kubectl get pods # 描述 CAS pod，排查启动失败原因 kubectl describe pod cas-server-0 # 跟踪控制台日志 kubectl logs cas-server-0 -f # 进入容器 kubectl exec -it cas-server-0 sh # 重启 CAS pod（删除后由 StatefulSet 自动重建） kubectl delete pod cas-server-0

浏览访问 CAS

确保 values 文件中配置的主机已写入 hosts 文件。以如下 ingress 配置为例：

ingress: hosts: - host: cas.example.org paths: - "/cas" tls: - secretName: cas-server-ingress-tls hosts: - cas.example.org

对应的本机 hosts 条目：

127.0.0.1 cas.example.org

当 CAS pod 运行正常后，浏览器访问https://cas.example.org/cas/login即可打开登录页。此外，CAS Spring Boot Admin 服务器也有独立 ingress，使用 Boot Admin ingress 中配置的主机名即可访问（Boot Admin 定位为内部服务，而 CAS 通常对外，两者可根据需要调整内外网策略）。

结语

从本指南可以看到，基于 CAS WAR Overlay Initializr 的 Helm Chart 为本地乃至生产环境提供了一条可复制的 CAS 部署路径：K3S 负责轻量集群，ingress-nginx 负责流量入口，jibBuildTar负责镜像构建，create-*.sh系列脚本负责证书与信任库，helm upgrade --install负责声明式交付。部署完成后，善用kubectl describe/logs/exec即可完成日常巡检与问题定位。由于 Chart 仍处于演进阶段（如 SSL 策略、StatefulSet使用方式、服务发现模式等均可能调整），建议持续关注 CAS Initializr 工程中 Helm Chart 的更新，并将任何模板改进贡献回上游，推动其走向更通用的发布形态。

• 后端
• 认证鉴权
• 单点登录