CAS单点登录（第7版）3.安装

如有疑问，请看视频：CAS单点登录（第7版）

安装
1. 要求
  1. 安装要求

根据配置组件的选择，可能还有其他要求，例如 LDAP 目录、数据库和缓存基础结构。但是，在大多数情况下，对于选择具有明确硬件和软件依赖关系的组件的部署人员来说，需求应该是不言而喻的。在任何附加要求不明显的情况下，对组件配置的讨论都应该提到系统、软件、硬件和其他要求。

1. 1. Java

CAS 的核心是基于 Java 的 Web 应用程序。在部署之前，您需要安装 JDK 21。JDK 要求是全局性的，适用于所有 CAS 模块和功能。所需的 Java 版本必须在编译时（当您构建和打包 CAS 时）以及当然在运行时（当您部署 CAS Web 应用程序时）可用。

发布政策

Java 平台要求通常仅在发布 CAS 主要版本时发生变化，并且需要更新的版本。对于所有其他功能、次要、补丁或维护版本，这些要求将普遍保持不变。此外，我们无法确定 CAS 能否在高于所需基准的较新 JDK 版本中正确运行。YMMV。

所有兼容的发行版（如 Amazon Corretto、Zulu、Eclipse Temurin 等）都应该可以工作并受到隐式支持。无论您使用哪种 Java 发行版，请确保在下载和使用软件包之前已仔细阅读许可协议。

Java Software | Oracle

JAVA_HOME=C:\Program Files\Java\jdk-21

%JAVA_HOME%\bin

java -version

1. 1. Servlet 容器

CAS 没有官方支持的 servlet 容器，但 Apache Tomcat 是最常用的。对特定 servlet 容器的支持取决于社区成员的专业知识。

有关更多信息，请参阅本指南。

https://tomcat.apache.org/download-10.cgi

http://localhost:8080/

1. 1. 构建工具

提供 WAR 覆盖以实现简单而灵活的部署解决方案。虽然它不可否认需要高昂的学习前期成本，但从长远来看，它会获得许多好处。

少做事

您不需要在安装之前安装 Gradle。它会自动提供给您。

1. 1. git（可选）

虽然并非严格要求，但强烈建议您为 CAS 部署安装 Git，并在源代码控制存储库中管理所有 CAS 构件、配置文件、构建脚本和设置。

Git

TortoiseGit – Windows Shell Interface to Git

1. 1. OS

对操作系统没有特别的偏好，尽管基于 Linux 的安装通常比 Windows 更常见。

1. 1. Internet 连接

任何基于 Maven/Gradle 的项目的构建阶段通常需要 Internet 连接，包括用于安装 CAS 的推荐 WAR 覆盖。构建过程通过搜索包含本地下载和安装的工件（大多数情况下为 jar 文件）的在线存储库来解决依赖关系。

1. 1. 硬件

社区轶事证据似乎表明，CAS 部署在至少具有 4GB 内存的双核 3.00Ghz 处理器上表现良好。如果日志保存在服务器本身上，则还需要足够的磁盘空间（最好是 SSD）来存储 CAS 生成的日志。

请记住，上述要求是建议。或多或少，您可能会完全满意，具体取决于您的部署和请求量。从最低限度开始，并准备好根据需要调整和增强容量。

1. WAR Overlay
  1. 概述
    1. 安装

CAS 安装基本上是一个面向源代码的过程，我们建议使用 WAR 覆盖（1）项目来组织自定义，例如组件配置和 UI 设计。WAR 覆盖构建的输出是一个 cas.war 文件，可以部署到 Apache Tomcat 等 servlet 容器。

1. 1. 1. 要求

请参阅本指南以了解更多信息。

1. 1. 1. 什么是 WAR Overlay？

覆盖是一种对抗重复代码和/或资源的策略。覆盖允许您下载项目本身提供的预构建 CAS Web 应用程序服务器，并覆盖/插入特定行为，而不是下载 CAS 代码库并从源代码构建。在构建时，构建安装过程将首先尝试下载提供的二进制工件。然后，该工具将找到同一项目目录中可用的配置文件和设置，并将它们合并到下载的工件中，以生成一个有益健康的存档（即 cas.war）。被覆盖的项目可能包括资源、java 类、图像、CSS 和 javascript 文件。为了使 mergeprocess 成功执行，本地被覆盖的工件的位置和名称必须与原始下载的存档中的项目提供的位置和名称完全匹配。覆盖项目的 src/main/java 文件夹中的 Java 代码和 src/main/resources 中的资源将最终位于 cas.war 的 WEB-INF\classes 文件夹中，并且它们将由类加载器加载，而不是由 WEB-INF\lib 内的 jar 文件中具有相同名称的资源加载。

毋庸置疑，虽然前期启动时间可能略有复杂，但这种方法具有显著的优势：

无需从源下载/构建。
在大多数情况下，通过调整构建脚本以下载较新的 CAS 版本，升级会变得非常容易。
作为部署程序，您只需保留自己的本地自定义项，而不是托管整个软件源代码，这使得更改跟踪变得更加容易。
跟踪源代码控制存储库中的更改非常轻量级，因为仅管理相关更改（而不是整个软件）。
1. 1. 1. 1. 管理Overlay

CAS 的大多数（如果不是全部）方面都可以通过在覆盖中添加、删除或修改文件来控制;通过添加将 CAS API 实现为 Java 源文件或依赖项引用的第三方组件来自定义 CAS 的行为也是可能的，而且确实很常见。

使用覆盖的过程可以总结为以下步骤：

从提供的基本 vanilla build/deployment 开始并构建。
确定生成的版本中需要更改的工件。这些工件通常由 Gradle build 目录中的 build 生成。
将已识别的工件从上述已识别的目录复制到 src/main/resources 目录。

创建 src/main/resources 目录（如果尚不存在）。
复制的路径和文件名必须与它们的构建对应项完全匹配，否则更改不会生效。

更改后，请尽可能多次重新生成并重复该过程。
仔细检查您在构建的二进制构件中的更改，以确保覆盖过程正常工作。

精确

不要复制生成生成的所有内容。尝试将更改和自定义保持在最低限度，只获取您实际需要的内容。确保部署环境保持干净和精确，否则您将面临可怕的升级问题和痛苦的头痛风险。

1. 1. 1. CAS Overlay 初始化器

Apereo CAS Initializr 是 Apereo CAS 项目提供的一项服务，允许您作为部署者即时生成 CAS WAR Overlay 项目，并提供快速启动所需的资源。

要了解有关 initializr 的更多信息，请查看本指南。

1. 1. 1. Docker 化部署

有关更多信息，请参阅本指南。

1. 1. 1. Servlet 容器

CAS 可以部署到许多 servlet 容器中。有关更多信息，请参阅本指南。

1. 1. 1. 依赖关系管理

每个 CAS 版本都提供了它支持的依赖项的精选列表。实际上，您无需在构建配置中为这些依赖项中的任何一个提供版本，因为 CAS 发行版会为您管理这些依赖项。当您升级 CAS 本身时，这些依赖项也将以一致的方式升级。

精选的依赖项列表包含第三方库的精炼列表。该列表可作为标准物料清单（BOM）使用。不是每个人都喜欢从 BOM 中继承。您可能有自己的 corporate standard parent 需要使用，或者您可能只是喜欢显式声明所有配置。

要利用 CAS BOM，请参阅本指南。

WAR 覆盖
1. 1. Bill of Materials物料清单
    1. CAS Bill of Materials (BOM)

每个 CAS 版本都提供了它支持的依赖项的精选列表。实际上，您无需在构建配置中为这些依赖项中的任何一个提供版本，因为 CAS 分配会为您管理这些依赖项。当您升级 CAS 本身时，这些依赖项也将以一致的方式升级。

通过在 WAR 覆盖中包含以下依赖项来启用对 BOM 的支持：

Apache Maven

1	<dependency> <groupId>org.apereo.cas</groupId> <artifactId>cas-server-support-bom</artifactId> <version>${cas.version}</version> </dependency>

Gradle

1	implementation enforcedPlatform("org.apereo.cas:cas-server-support-bom:${project.'cas.version'}")

Resources

请注意，CAS Initializr 已预配置为使用 CAS BOM。

1. 1. 依赖项版本

CAS 使用以下库和模块：

Show entries

搜索：

群	名字	版本
ch.qos.logback	logback-access	1.5.16
ch.qos.logback	logback-classic	1.5.16
ch.qos.logback	logback-core	1.5.16
co.elastic.apm	apm-agent-api	1.52.1
co.elastic.apm	apm-agent-attach	1.52.1

显示 1 到 5 的 461 个条目

您可能无法立即在 deployment中看到所有列出的工件和库。根据最终构建中包含的 CAS 功能模块，上述库和依赖项将被拉取到最终的 Web 应用程序工件中。

所有权

请注意，上面列出的依赖项通常是 CAS 软件明确请求、拥有和控制的依赖项。当然，还有许多其他模块和依赖项将被传递拉入，其具体细节和版本不受 CAS 的直接控制。在这种情况下，特定功能模块或库本身负责将其自己的依赖项正确拉取到 build 中。上面列出的内容主要用作有用的指南，而不是全面的参考。

1. 1. CAS初始化
    1. WAR Overlay Initializr

CAS Initializr

Apereo CAS Initializr 是 Apereo CAS 生态系统中的一个组件，它允许作为部署者，使用快速启动所需的资源即时生成 CAS WAR Overlay 项目。

要开始 CAS 部署，采用者通常从基于 Gradle 的简单覆盖项目开始，并将其用作未来修改的基准。虽然这是多年来的传统和推荐方法，但对于生态系统的新手用户来说，下载、修改和准备覆盖项目以包含所有必需的自定义内容也可能相当具有挑战性。鉴于覆盖项目的静态性质，项目所有者和维护者在不影响基线模板的情况下使其保持最新或提供额外的增强功能和自动化也可能是一项挑战。

为了解决此类情况，CAS WAR Overlay Initializr 提供了一种快速方法来提取 CAS 部署所需的所有依赖项和模块，并提供友好且编程友好的 curl API 来生成覆盖结构和所需的构建文件。

处理项目生成任务的底层框架基于 Spring Initializr。

1. 1. 1. 概述

CAS Initializr 可以根据部署所需的请求模块和依赖项动态生成起始项目。此行为可以根据该输入和随后的条件根据用户体验进行定制，以在同一项目中生成其他引用、文件、startingtemplates 等，以使部署过程更加舒适。

管理和维护单独的覆盖项目并使其与各种 CAS 版本保持同步可能是一项成本高昂的维护任务。CAS Initializr 允许项目开发人员自动执行维护任务，将所有内容保存在同一个存储库中，以便更快、更准确地进行升级。

CAS Initializr 由 CAS 项目本身在内部以一种非常 Eat What You Kill 的方式用于动态生成覆盖项目。这些生成的项目用作发布到 Docker Hub 的 CAS 基础 Docker 映像，并用作 CAS CI 针对每个相关功能运行的浏览器/UI 测试的基准。CAS Initializr 使用自身来测试自身！

要正确初始化和生成 CAS 覆盖，您可能需要确保已安装 curl、http 和/或 jq。

1. 1. 1. 项目类型

可以使用 curl 调用 CAS Initializr 来生成不同类型的覆盖项目。项目选择使用 type 参数表示。支持以下类型：

类型	描述	模板存储库
cas-overlay	Default;生成 CAS WAR 覆盖层。	请参阅此存储库。
cas-config-server-overlay	Spring Cloud 配置服务器的 WAR 覆盖。	请参阅此存储库。

1. 1. 1. 项目版本

可以指示 CAS Initializr 为特定版本准备覆盖项目。以下请求参数控制版本选择：

类型	描述
casVersion	指定覆盖的 CAS 版本。
bootVersion	（可选）指定覆盖的 Spring Boot 版本。

请注意，混合和匹配不同的版本通常会导致项目构建不稳定。这样做的风险由您自己承担！项目生成请求中的版本号规范是不必要的，并且 CAS Initializr 将始终使用可信默认值来处理生成任务。

记得

您可能需要指定的唯一版本是 CAS 服务器版本。覆盖构建或组件版本（如 Spring Boot）的其他方面通常会导致构建和部署环境不稳定。

要查看 Heroku 上 CAS Initializr 的支持版本列表，您可以使用：

1	curl <cas-initializr-url>/actuator/supportedVersions \| jq

1. 1. 1. 源代码

CAS Initializr 可从以下网址获得：

源存储库	位置
https://github.com/apereo/cas-initializr	链接

1. 1. 1. 项目生成

可以使用 curl 调用 CAS Initializr 来生成覆盖项目。要访问 CAS Initializr，可以使用以下策略。

1. 1. 1. 1. Heroku

CAS 项目在 Heroku 上提供了 CAS Initializr 的公共实例，由 Apereo CAS 支持订户支付费用。要开始使用此实例，一种简单的方法可能是在 bash 配置文件中包含以下函数：

function getcas() {

url="https://getcas.apereo.org/starter.tgz"

projectType="cas-overlay"

dependencies=""

directory="overlay"

for arg in $@; do

case "$arg" in

--url|-u)

url=$2

shift 1

;;

--type|-t)

projectType=$2

shift 1

;;

--directory|--dir|-d)

directory=$2

shift 1

;;

--casVersion|--cas)

casVersion="-d casVersion=$2"

shift 1

;;

--bootVersion|--springBootVersion|--boot)

bootVersion="-d bootVersion=$2"

shift 1

;;

--modules|--dependencies|--extensions|-m)

dependencies="-d dependencies=$2"

shift 1

;;

shift

;;

esac

done

rm -Rf ./${directory}

echo -e "Generating project ${projectType} with dependencies ${dependencies}..."

cmd="curl ${url} -d type=${projectType} -d baseDir=${directory} ${dependencies} ${casVersion} ${bootVersion} | tar -xzvf -"

echo -e "${cmd}"

eval "${cmd}"

ls}

注意

如果您愿意，可以调用 /starter.zip 端点来取回 ZIP 文件。

这允许您使用以下方法在 overlay 目录中生成 CAS 覆盖项目：

1	getcas --modules duo,oidc

…生成一个 CAS 覆盖项目，该项目使用 Duo Security 的多因素身份验证准备，并支持 OpenID Connect。

注意

为了帮助降低部署成本，Heroku 实例已开启对速率限制请求的支持。请注意，频繁请求的访问可能会受到限制。

1. 1. 1. 1. Docker

如果 Initializr 在 Heroku 上不可用，您还可以通过 Docker 运行自己的 Initializr 实例：

1	docker run --rm -p 8080:8080 apereo/cas-initializr:${tag}

CAS Initializr 应在 http://localhost:8080 上可用，并将使用 curl 响应 API请求。可在此处找到 CAS Initializr 的已发布图像和标签。

1. 1. 1. CAS 模块

可以请求的 CAS 项目模块和依赖项必须由其标识符指定。要查看此服务支持和可用的所有依赖项的完整列表，您可以调用以下命令：

1	curl <cas-initializr-url>/dependencies

通常，依赖项标识符与不带 cas-server- 前缀的 CAS 服务器依赖项/模块工件名称匹配。此外，某些依赖项被分配了别名作为快捷方式以简化请求。要查看依赖项及其别名的完整列表，您可以使用：

1	curl <cas-initializr-url>/actuator/info \| jq

此外，CAS Initializr 还发布了有关其功能的元数据，即所有请求参数（依赖项、类型等）的可用选项。thisservice 的客户端可以使用此信息来初始化 select 选项和可用依赖项的范围。

您可以使用相应的 Accept 标头获取根终端节点上的元数据：

1	curl -H 'Accept: application/json' <cas-initializr-url> \| jq

或者使用 HTTPie：

1	http <cas-initializr-url> Accept:application/json \| jq

1. 1. 1. 1. 依赖关系管理

CAS Initializr 设置为使用 CAS BOM 进行依赖关系管理。

1. 1. 升级配方
    1. OpenRewrite 升级配方

OpenRewrite 是 CAS 使用的一种工具和平台，允许项目将就地安装从一个版本升级到下一个版本。它的工作原理是更改表示 CAS Overlay 构建的项目结构，并打印回修改后的文件。修改指令以升级脚本的形式打包在一起，这些脚本称为 Recipes，由 CAS 项目生成，然后在 CAS 覆盖中引用和发现。

通过在 WAR 覆盖中包含以下依赖项来启用支持：

Apache Maven

Gradle

BOM - Spring

BOM - Gradle

资源

dependencies {

The following platform references should be included automatically and are listed here for reference only.

implementation enforcedPlatform("org.apereo.cas:cas-server-support-bom:${project.'cas.version'}")

implementation platform(org.springframework.boot.gradle.plugin.SpringBootPlugin.BOM_COORDINATES)

implementation "org.apereo.cas:cas-server-support-openrewrite"}

YAGNI

您无需在配置和覆盖中显式包含此组件。这只是为了告诉你它存在，如果你需要它。

CAS 生成的 OpenRewrite 配方本质上是 YAML 文件，它们对 CAS 构建进行微创更改，使您可以毫不费力地从一个版本升级到下一个版本。该配方几乎包含 CAS 构建系统从一个版本导航到另一个版本所需的一切，并自动进行升级的繁琐方面，例如查找正确的 CAS 版本、相关库和插件，以及对 CAS 构建的任何可能的结构更改。

请参阅 CAS 覆盖项目中生成的说明，了解有关如何应用升级配方的更多信息。在较现代和最新版本的 CAS 中，说明通常位于 CAS 覆盖项目的 README 文件中。

使用警告！

虽然升级配方会随着时间的推移而变得越来越聪明和更好，但您应该知道他们的技术实力和能力只能到此为止。升级的某些方面可能根本无法自动化，尤其是在您对 CAS 版本进行了重大修改的情况下。对 CAS 构建的较少更改通常会带来更顺畅、更便宜且痛苦更少的未来升级，因此在踏入兔子洞之前请三思而后行。

1. 命令行 Shell

CAS 命令行 shell 提供了查询 CAS 服务器以获取有关可用设置/模块和各种其他实用程序功能的帮助的功能。

要调用和使用该实用程序，请执行：

1	java -jar /path/to/cas-server-support-shell-$casVersion.jar

…其中$casVersion不用说的是部署的 CAS 版本。

接下来介绍的界面将指导您了解可用的参数和查询方法。您将学习如何启动交互式 shell 并动态查询 CAS 引擎。

JCE 要求

确保在 CAS 使用的 Java 环境中安装了正确的 JCE 捆绑包，尤其是在需要使用特定的签名/加密算法和方法时。请务必为您的 Java 版本选择正确的 JCE 版本。可以通过 java -version 命令检测 Java 版本。

请注意，WAR Overlay 部署策略应该已经配备了此功能。您不必执行任何特殊和额外的操作来与 shell 交互。有关如何调用和使用 shell 的更多信息，请参阅 relevantoverlay 文档。

1. 1. Shell 命令

以下命令由 CAS 命令行 shell 提供和公开。

1. 1. 1. 生成密钥

为 CAS 设置生成签名/加密加密密钥

Show entries

搜索：

名字	描述	Default
key-size,--key-size	Key size	256

显示 1 到 1 的 1 个条目

1. 1. 1. 解密文本，解码文本

使用密钥解密和验证文本数据

Show entries

搜索：

名字	描述	Default
enable-encryption,--enable-encryption	Whether value should be encrypted	true
enable-signing,--enable-signing	Whether value should be signed	true
encryption-alg,--encryption-alg	Encryption alg	A256CBC-HS512
encryption-key,--encryption-key	Encryption key	__NULL__
encryption-key-size,--encryption-key-size	Encryption key size	512

显示 1 到 5 的 8 个条目

1. 1. 1. 密文，编码文本

使用密钥对文本数据进行签名和加密

Show entries

搜索：

名字	描述	Default
enable-encryption,--enable-encryption	Whether value should be encrypted	true
enable-signing,--enable-signing	Whether value should be signed	true
encryption-alg,--encryption-alg	Encryption alg	A256CBC-HS512
encryption-key,--encryption-key	Encryption key	__NULL__
encryption-key-size,--encryption-key-size	Encryption key size	512

显示 1 到 5 的 8 个条目

1. 1. 1. 生成 DDL

生成数据库 DDL 脚本

Show entries

搜索：

名字	描述	Default
createSchema,--createSchema	Generate DROP SQL statements in the DDL	false
delimiter,--delimiter	Delimiter to use for separation of statements when generating SQL	;
dialect,--dialect	Database dialect class	HSQL
dropSchema,--dropSchema	Generate DROP SQL statements in the DDL	false
file,--file	DDL file to contain to generated script	/etc/cas/config/cas-db-schema.sql

显示 1 到 5 的 8 个条目

1. 1. 1. 解密值

通过 Jasypt 解密 CAS 属性值/设置

Show entries

搜索：

名字	描述	Default
alg,--alg	Algorithm to use to decrypt	__NULL__
initvector,--initvector,iv,--iv	Use initialization vector to encrypt	false
iterations,--iterations	Key obtention iterations to decrypt, default 1000	__NULL__
password,--password	Password (encryption key) to decrypt	__NONE__
provider,--provider	Security provider to use to decrypt	__NULL__

显示 1 到 5 的 6 个条目

1. 1. 1. 加密值

通过 Jasypt 加密 CAS 属性值/设置

Show entries

搜索：

名字	描述	Default
alg,--alg	Algorithm to use to encrypt	__NULL__
file,--file	File to encrypt	__NULL__
initvector,--initvector,iv,--iv	Use initialization vector to encrypt	false
iterations,--iterations	Key obtention iterations to encrypt, default 1000	__NULL__
password,--password	Password (encryption key) to encrypt	__NONE__

显示 1 到 5 的 7 个条目

1. 1. 1. jasypt-list-算法

列出可与 Jasypt 一起用于属性加密的方法

Show entries

搜索：

名字	描述	Default
includeBC,--includeBC	Include Bouncy Castle provider	false

显示 1 到 1 的 1 个条目

1. 1. 1. jasypt-list-providers

列出可与 Jasypt 一起使用的具有 PBE 密码的加密提供程序

Show entries

搜索：

名字	描述	Default
includeBC,--includeBC	Include Bouncy Castle provider	false

显示 1 到 1 的 1 个条目

jasypt-test-algorithms

测试可与 Jasypt 一起使用的加密算法，以确保加密和解密都有效

Show entries

搜索：

名字	描述	Default
表中无可用数据

显示 0 到 0 个条目中的 0 个

1. 1. 1. 生成-完整-JWT

生成 JWT 并使用给定的密钥库对其进行签名

Show entries

搜索：

名字	描述	Default
aud,--aud	Audience	CAS
claims,--claims	JWT claims as JSON	{}
exp,--exp	Expiration in seconds	300
iss,--iss	Issuer	https://localhost:8443/cas/oidc
jwks,--jwks	Path to the JWKS file used to sign the token

显示 1 到 5 的 6 个条目

1. 1. 1. 生成 JWT

生成具有给定大小和算法的 JWT 以进行签名和加密。

Show entries

搜索：

名字	描述	Default
encryptionAlgorithm,--encryptionAlgorithm	Algorithm to use for encryption	dir
encryptionMethod,--encryptionMethod	Method to use for encryption	A192CBC-HS384
encryptionSecretSize,--encryptionSecretSize	Size of the encryption secret	48
signingAlgorithm,--signingAlgorithm	Algorithm to use for signing	HS256
signingSecretSize,--signingSecretSize	Size of the signing secret	256

显示 1 到 5 的 6 个条目

1. 1. 1. 生成 OIDC-JWKS

生成 OIDC JSON Web 密钥库

Show entries

搜索：

名字	描述	Default
jwksFile,--jwksFile	Location of the JSON web keystore file.	/etc/cas/config/keystore.jwks
jwksKeyId,--jwksKeyId	The key identifier to set for the generated key in the keystore.	cas
jwksKeySize,--jwksKeySize	The key size (an algorithm-specific) for the generated jwks.	2048
jwksKeyType,--jwksKeyType	The type of the JWKS used to handle signing/encryption of authentication tokens.	RSA

显示 1 到 4 的 4 个条目

1. 1. 1. 添加属性

将与 CAS 组/模块关联的属性添加到 Properties/Yaml 配置文件中。

Show entries

搜索：

名字	描述	Default
file,--file	Path to the CAS configuration file	/etc/cas/config/cas.properties
group,--group	Group/module whose associated settings should be added to the CAS configuration file	__NONE__

显示 1 到 2 的 2 个条目

1. 1. 1. convert-props

将 CAS 属性转换为同一位置的 YAML 文件。

Show entries

搜索：

名字	描述	Default
properties,--properties	Path to a properties file that contains CAS settings	/etc/cas/config/cas.properties

显示 1 到 1 的 1 个条目

1. 1. 1. 导出属性

从配置元数据中导出 CAS 属性和设置。

Show entries

搜索：

名字	描述	Default
dir,--dir	Path to a directory where reference configuration files would be exported.	./etc/cas/config

显示 1 到 1 的 1 个条目

1. 1. 1. 找到

查找与 CAS 组/模块关联的属性。

Show entries

搜索：

名字	描述	Default
name,--name	Property name regex pattern	.+
strict-match,--strict-match	Whether pattern should be done in strict-mode which means the matching engine tries to match the entire region for the query.	__NONE__
summary,--summary	Whether results should be presented in summarized mode	__NONE__

显示 1 到 3 个条目中的 3 个

1. 1. 1. 生成 idp 元数据

生成 SAML2 IdP 元数据

Show entries

搜索：

名字	描述	Default
entityId,--entityId	Entity ID to use for the generated metadata	cas.example.org
force,--force	Force metadata generation (XML only, not certs), overwriting anything at the specified location	__NONE__
hostName,--hostName	CAS server prefix to be used at the IdP host name when generating metadata	https://cas.example.org/cas
metadataLocation,--metadataLocation	Directory location to hold metadata and relevant keys/certificates	/etc/cas/saml
scope,--scope	Scope to use when generating metadata	example.org

显示 1 到 5 的 6 个条目

1. 1. 1. 生成匿名用户

生成匿名（永久）用户名标识符

Show entries

搜索：

名字	描述	Default
salt,--salt	Salt used to generate and encode the anonymous identifier	__NONE__
service,--service	Service application URL for which CAS may generate the identifier	__NONE__
username,--username	Authenticated username	__NONE__

显示 1 到 3 个条目中的 3 个

1. 1. 1. 生成 YAML

生成 YAML 注册的服务定义

Show entries

搜索：

名字	描述	Default
destination,--destination	Path to the destination YAML service definition file	__NONE__
file,--file	Path to the JSON service definition file	__NONE__

显示 1 到 2 的 2 个条目

1. 1. 1. 验证服务

按路径或目录验证给定的 JSON/YAML 服务定义

Show entries

搜索：

名字	描述	Default
directory,--directory	Path to the JSON/YAML service definitions directory
file,--file	Path to the JSON/YAML service definition file

显示 1 到 2 的 2 个条目

1. 1. 1. validate-endpoint

测试与终端节点的连接以验证连接、SSL 等

Show entries

搜索：

名字	描述	Default
proxy,--proxy	Proxy address to use when testing the endpoint url
timeout,--timeout	Timeout to use in milliseconds when testing the url	5000
url,--url	Endpoint URL to test	__NONE__

显示 1 到 3 个条目中的 3 个

1. 1. 1. 验证-LDAP

测试与 LDAP 服务器的连接以验证连接、SSL 等

Show entries

搜索：

名字	描述	Default
baseDn,--baseDn	baseDn to use when testing the LDAP server, searching for accounts (i.e. OU=some,DC=org,DC=edu)	__NONE__
bindCredential,--bindCredential	bindCredential to use when testing the LDAP server	__NONE__
bindDn,--bindDn	bindDn to use when testing the LDAP server	__NONE__
searchFilter,--searchFilter	Filter to use when searching for accounts (i.e. (&(objectClass=*) (sAMAccountName=user)))
url,--url	LDAP URL to test, comma-separated.	__NONE__

显示 1 到 5 的 7 个条目

1. Docker 部署
  1. Docker官方文档

Docker: Accelerated Container Application Development

https://docs.docker.com/desktop/setup/install/windows-install/

1. 1. 1. 在Windows上安装Docker桌面

Docker 桌面术语

Docker Desktop 在大型企业（超过 250 名员工或年收入超过 1000 万美元）的商业使用需要付费订阅。

此页面包含下载 URL、有关系统要求的信息以及有关如何安装适用于 Windows 的 Docker Desktop 的说明。

适用于 Windows 的 Docker 桌面 - x86_64
适用于 Windows 的 Docker 桌面 - Arm（测试版）

有关校验和，请参阅发行说明

Windows 系统，通过命令提示符：

wmic cpu get architecture

输出 9 表示是 AMD64。

输出 12 表示是 ARM64。

1. 1. 1. 1. 系统要求

提示

我应该使用 Hyper-V 还是 WSL？

Docker Desktop 的功能在 WSL 和 Hyper-V 上保持一致，没有对任何一种架构的偏好。 Hyper-V 和 WSL 各有优缺点，具体取决于您的具体设置和计划的用例。

1. 1. 1. 1. WSL 2 后端，x86_64

WSL 版本 1.1.3.0 或更高版本。
Windows 11 64位：Home或Pro版本22H2或更高版本，或企业或教育版本22H2或更高版本。
Windows 10 64位：所需的最低是家庭或Pro 22H2（建造19045）或更高的企业或教育22H2（构建19045）或更高。
打开Windows上的WSL 2功能。有关详细说明，请参阅 Microsoft文档。

Install WSL | Microsoft Learn

先决条件

您必须运行 Windows 10 版本 2004 及更高版本（Build 19041 及更高版本）或 Windows 11 才能使用以下命令。如果您使用的是早期版本，请参阅手动安装页面。

安装WSL命令

现在，您可以使用单个命令安装运行 WSL 所需的所有内容。右键单击并选择“以管理员身份运行”，以管理员模式打开 PowerShell 或 Windows 命令提示符，输入 wsl --install 命令，然后重新启动计算机。

wsl --install

此命令将启用运行 WSL 和安装 Linux 的 Ubuntu 发行版所需的功能。（可以更改此默认分配）。

需要以下硬件先决条件才能在Windows 10或Windows 11上成功运行WSL 2：

具有第二级地址翻译（SLAT）的64位处理器
4GB系统RAM
在BIOS中启用硬件虚拟化。有关更多信息，请参见虚拟化。

https://support.lenovo.com/us/zc/solutions/ht500006

1. 1. 1. 1. Hyper-V 后端，x86_64
Windows 11 64 位：企业版、专业版或教育版 22H2 或更高版本。
Windows 10 64 位：企业版、专业版或教育版 22H2（内部版本 19045）或更高版本。
打开 Hyper-V 和容器 Windows 功能。
要在 Windows 10 上成功运行客户端 Hyper-V，需要满足以下硬件先决条件：

具有二级地址转换 (SLAT) 功能的 64 位处理器
4GB系统内存
在 BIOS 设置中打开 BIOS 级硬件虚拟化支持。有关详细信息，请参阅虚拟化
1. 1. 1. 1. WSL 2 后端，Arm（测试版）

有关使用Docker Desktop设置WSL 2的更多信息，请参见 WSL。

笔记

Docker仅支持Windows上的Docker桌面，用于仍在 Microsoft服务时间表中的Windows版本。 Docker Desktop在Windows的服务器版本（例如Windows Server 2019或Windows Server 2022）上不支持。有关如何在Windows Server上运行容器的更多信息，请参见 Microsoft的官方文档。

重要的

要运行Windows容器，您需要Windows 10或Windows 11专业版或企业版。 Windows Home或Education版本仅允许您运行Linux容器。

使用 Docker Desktop 创建的容器和映像在安装它的计算机上的所有用户帐户之间共享。这是因为所有 Windows 帐户都使用相同的 VM 来构建和运行容器。请注意，使用 Docker Desktop WSL 2 后端时无法在用户帐户之间共享容器和映像。

Docker Business 客户支持在 VMware ESXi 或 Azure VM 内运行 Docker Desktop。它需要首先在虚拟机管理程序上启用嵌套虚拟化。有关更多信息，请参阅在 VM 或 VDI 环境中运行 Docker Desktop。

如何在 Windows 和 Linux 容器之间切换？

1. 1. 1. 1. 在Windows上安装Docker桌面

提示

请参阅有关如何在无需管理员权限的情况下安装和运行 Docker Desktop 的常见问题解答。

1. 1. 1. 1. 交互式安装

使用页面顶部的下载按钮或从发行说明下载安装程序。

双击Docker Desktop Installer.exe运行安装程序。默认情况下，Docker Desktop 安装在C:\Program Files\Docker\Docker.

出现提示时，请确保选择或不选择“配置”页面上的“使用 WSL 2 而不是 Hyper-V”选项，具体取决于您选择的后端。如果您的系统仅支持这两个选项之一，您将无法选择使用哪个后端。

按照安装向导上的说明授权安装程序并继续安装。

安装成功后，选择关闭以完成安装过程。

启动 Docker 桌面。

如果您的管理员帐户与您的用户帐户不同，则必须将该用户添加到docker-users组：

以管理员身份运行计算机管理。
导航到本地用户和组>组> docker-users。
右键单击将用户添加到组中。
注销并重新登录以使更改生效。
1. 1. 1. 1. 从命令行安装

下载后Docker Desktop Installer.exe，在终端中运行以下命令来安装 Docker Desktop：

$ "Docker Desktop Installer.exe" install

如果您使用 PowerShell，则应将其运行为：

Start-Process 'Docker Desktop Installer.exe' -Wait install

如果使用 Windows 命令提示符：

start /w "" "Docker Desktop Installer.exe" install

默认情况下，Docker Desktop 安装在C:\Program Files\Docker\Docker.

该install命令接受以下标志：

--quiet：在运行安装程序时抑制信息输出

--accept-license：立即接受 Docker订阅服务协议，而不是在申请首次运行时要求接受该协议

--no-windows-containers：禁用Windows容器集成

--allowed-org=<org name>：要求用户在运行应用程序时登录并成为指定的Docker Hub组织的一部分

--backend=<backend name>：选择用于Docker桌面的默认后端，hyper-v或windows（wsl-2默认）

--installation-dir=<path>：更改默认安装位置（C:\Program Files\Docker\Docker）

--admin-settings：自动创建一个admin-settings.json由管理员使用的文件，以控制其组织内客户端计算机上的某些Docker桌面设置。有关更多信息，请参见设置管理。

它必须与标志一起使用--allowed-org=<org name>。
例如：--allowed-org=<org name> --admin-settings="{'configurationFileVersion': 2, 'enhancedContainerIsolation': {'value': true, 'locked': false}}"

--proxy-http-mode=<mode>：设置 HTTP 代理模式，system（默认）或manual

--override-proxy-http=<URL>：设置传出HTTP请求必须使用的HTTP代理的URL，要求--proxy-http-mode是manual

--override-proxy-https=<URL>：设置用于传出 HTTPS 请求的 HTTP 代理的 URL，--proxy-http-mode需要manual

--override-proxy-exclude=<hosts/domains>：绕过主机和域的代理设置。使用逗号分隔的列表。

--proxy-enable-kerberosntlm：启用 Kerberos 和 NTLM 代理身份验证。如果您要启用此功能，请确保您的代理服务器已正确配置为 Kerberos/NTLM 身份验证。适用于 Docker Desktop 4.32 及更高版本。

--hyper-v-default-data-root=<path>：指定 Hyper-V VM 磁盘的默认位置。

--windows-containers-default-data-root=<path>：指定 Windows 容器的默认位置。

--wsl-default-data-root=<path>：指定 WSL 分发磁盘的默认位置。

--always-run-service：安装完成后，启动com.docker.service并将服务启动类型设置为自动。这规定了对管理员特权的需求，否则这是开始的必要条件com.docker.service。com.docker.serviceWindows容器和Hyper-V后端需要。

笔记

如果您使用的是PowerShell，则需要ArgumentList在任何标志之前使用参数。例如：

Start-Process 'Docker Desktop Installer.exe' -Wait -ArgumentList 'install', '--accept-license'

如果您的管理员帐户与您的用户帐户不同，则必须将用户添加到Docker-users组：

$ net localgroup docker-users <user> /add

1. 1. 1. 1. 启动Docker桌面

安装后，Docker Desktop不会自动启动。启动Docker桌面：

搜索Docker，然后在搜索结果中选择Docker桌面。
Docker菜单（
）显示Docker订阅服务协议。

以下是要点总结：

Docker Desktop 对于小型企业（员工少于 250 名且年收入少于 1000 万美元）、个人使用、教育和非商业开源项目免费。
否则，需要付费订阅才能用于专业用途。
政府实体也需要付费订阅。
Docker Pro、Team 和 Business 订阅包括 Docker Desktop 的商业用途。

选择接受继续。 Docker Desktop 在您接受条款后启动。

请注意，如果您不同意这些条款，Docker Desktop 将不会运行。您可以选择稍后打开 Docker Desktop 接受这些条款。

更多信息请参见 Docker Desktop 订阅服务协议。建议您阅读常见问题解答。

1. 1. Docker安装

在 CAS 软件的每个版本发布时，docker 镜像都会被标记并推送到 Docker Hub 上的 Apereo CAS 存储库。可以通过以下命令下拉图像：

1	docker pull apereo/cas

…其中 [A.B.C] 表示映射到 CAS 服务器版本的映像标签。

然后：

docker run --rm \

-e SERVER_SSL_ENABLED=false -e SERVER_PORT=8080 \

-p 8080:8080 --name casserver apereo/cas

CAS 应在 http://localhost:8080/cas 上运行。

注意：

如果报错Error response from daemon: failed to resolve reference "docker.io/apereo/cas:latest": failed to do request: Head "https://registry-1.docker.io/v2/apereo/cas/manifests/latest": dialing registry-1.docker.io:443 container via direct connection because static system has no HTTPS proxy: connecting to registry-1.docker.io:443: dial tcp 185.45.7.97:443: connectex: A connection attempt failed because the connected party did not properly respond after a period of time, or established connection failed because connected host has failed to respond，请在Docker Engine中增加以下镜像配置：

{

"builder": {

"gc": {

"defaultKeepStorage": "20GB",

"enabled": true

}

"experimental": false,

"registry-mirrors": [

"https://registry.docker-cn.com",

"https://docker.mirrors.ustc.edu.cn",

"http://hub-mirror.c.163.com",

"http://docker.1ms.run",

"http://hub.rat.div",

"http://docker.1panel.live"

]

}

如果报错Caused by: java.io.FileNotFoundException: /etc/cas/thekeystore (No such file or directory)，请使用以下Shell命令生成密钥：

keytool -genkey -alias casuser -keypass changeit -keyalg RSA -keystore the.keystore -storepass changeit

1. 1. Docker概述

Docker 化 CAS 部署是由 Docker 包装的现有 CAS 覆盖项目。覆盖项目已经包括一个嵌入式容器来处理 CAS 的部署。覆盖项目还包括一个嵌入式构建工具，因此 CAS 的构建和部署不需要单独的步骤来下载和配置选项。

Docker Hub 上托管的 Docker 映像主要用作快速入门和演示。您还可以将它们用作基本映像，以将您的自定义项添加到映像中。该映像基于现有的 CAS WAR Overlay 构建而成。

使用 CAS Initializr 生成 CAS WAR 覆盖项目时，请参阅 README.md文件中提供的说明，以查看构建 CAS Docker 映像的选项。

1. 1. Kubernetes 和 Helm

要了解如何使用 CAS Helm Chart 在 Kubernetes 集群上部署 CAS，请参阅此处。

1. Graal VM 本机映像
  1. Graal VM Native Image 安装

Graal VM Native Images 是独立的可执行文件，可以通过提前处理编译的 Java 应用程序来生成。原生映像通常具有较小的内存占用，并且比 JVM 映像启动速度更快。

可以调整 CAS 服务器安装和部署过程，以便在专用native配置文件下作为 Graal VM 本机映像构建和运行。与 Java 虚拟机相比，CAS 服务器本机映像可以以更小的内存占用和更快的启动时间运行。CAS Graal VM Native Image 是一个完整的、特定于平台的可执行文件。您无需提供 Java 虚拟机即可运行 CAS 本机映像。它需要并使用预先（AOT）处理来创建可执行文件。这种预先处理涉及从主入口点对 CAS 应用程序代码进行静态分析。

使用警告！

此功能是一项正在进行的工作，需要大量的试验和错误，并且在这一点上是高度实验性的。我们鼓励您开始使用此功能试验和测试 CAS 部署，并贡献修复程序。

本机 CAS 部署和基于 JVM 的 CAS 部署之间存在一些关键差异。主要区别在于：

CAS 服务器的静态分析是在构建时从主入口点执行的。

创建本机映像时无法访问的代码将被删除，并且不会成为可执行文件的一部分。

Graal VM 无法直接识别 CAS 代码中的动态元素，必须了解反射、资源、序列化和动态代理。

CAS 服务器应用程序 Classpath 在构建时是固定的，无法更改。

没有延迟类加载，最终可执行文件中附带的所有内容都将在启动时加载到内存中。

在 AOT 处理阶段，CAS Web 应用程序将启动，直到 Bean 定义可用为止。在 AOT 处理阶段不会创建 Bean 实例。

直接集成到 CAS 版本中的 AOT 流程通常会生成：

build/generated/aotSources 下的 Java 源代码

build/generated/aotClasses 下的字节码（用于动态代理等）

Graal VM JSON 提示文件

资源提示（resource-config.json）

反射提示（reflect-config.json）

序列化提示（serialization-config.json）

Java 代理提示（proxy-config.json）

JNI 提示（jni-config.json）

请注意，Graal VM 本机映像工具会自动选取放在 src/main/resources/META-INF/native-image 下的提示文件。生成的提示文件可以在 build/generated/aotResources 中找到。

1. 1. 系统要求

构建计算机上必须存在与 CAS 要求兼容的 Graal VM 发行版，并将其激活为正在运行的 Java 运行时。目前，您至少需要安装 Graal VM 并准备好本机映像工具，以防您的 Graal VMdistribution 默认不提供和打包它。

毋庸置疑，使用 Graal VM 原生映像的能力现在和将来仅在使用嵌入式服务器容器运行的 CAS 部署中可用。在构建 CAS Graal VM 本机映像时，将自动提供嵌入式服务器容器。

最终生成 CAS Graal VM 本机映像的构建计算机最好运行至少具有 32GB 内存和 4 个 CPU 内核的 Linux。

LLVM 工具链

您可能会遇到有关 ld64 限制的构建错误，尤其是在 ARM 计算机上构建本机映像时。构建过程可能会要求您通过 gu install llvm-toolchain 使用 ld64.lld。

1. 1. 安装

构建 Graal VM 原生映像的功能直接内置于 CAS 安装过程中。可以使用 CAS Initializr 下载和准备安装脚本。生成的项目将包含一个 README 文件，其中包含有关如何构建和运行 CAS 本机映像的说明。

构建时间

构建 CAS Graal VM 本机映像可能非常耗费资源且耗时。根据构建中包含的模块数量、CAS 配置选项以及构建机器的马力和可用内存，构建时间可能会有很大差异，通常在 10~20 分钟左右，甚至更长。

由于在 AOT 和本机模式下，正在处理配置并在构建时优化上下文，因此任何会影响 bean 创建的属性（例如在 bootstrap 上下文中使用的属性）都应在构建时和运行时设置为相同的值，以避免意外行为。在构建包含 Spring Cloud Config Client 的 CAS 部署时，必须确保它连接到的配置数据源在构建时可用。例如，如果从 Spring Cloud Config Server 检索配置数据，请确保其实例正在运行并在 Config Client 设置中指示的端口上可用。

1. 1. 已知限制

CAS Graal VM 原生映像是一项不断发展的技术。并非 CAS 使用的所有库以及 CAS 提供的所有模块都支持本机映像。此外，以下方案不受支持，或者确实需要大量技巧和操作才能运行：

Apache Log4j 不支持本机映像;默认情况下，改用 Logback。

加载、解析和执行 Apache Groovy 脚本或加载动态代码结构的所有功能和特性。

用 Groovy 或其他动态语言编写的库和依赖项将极具挑战性。

从 Spring Cloud 支持的外部源加载 CAS 配置属性的所有功能和特性。

CAS 本机映像不支持刷新范围和动态刷新应用程序上下文。

如果您发现一个库不适用于 Graal VM，请在可访问性元数据项目中讨论该问题。

请注意，虽然启动时间比传统 JVM 快几个数量级，但本机映像上的实际延迟和吞吐量可能会更差 - 没有 JIT 编译器在运行时优化代码执行路径。理想情况下，您应该运行性能测试，以了解 CAS 作为本机映像与传统 JVM 应用程序的行为方式。

1. 1. 1. Upche Groovy

鉴于 Apache Groovy 编程语言及其元编程模型的动态特性，您将发现 CAS 中几乎所有加载、解析和执行任何形式的 Groovy 脚本或在 Groovy 代码片段中加载动态代码结构的能力和特性要么根本不起作用，要么必须重写，以便它们可能是静态的由 Groovy 解析器编译。在本机映像模式下，CAS 将强制自动切换 Groovy 编译器配置以使用 Groovy 的静态编译功能，该功能在某些情况下似乎有助于本机映像编译。

记得

同样，这仅适用于某些情况，并且肯定不会是一个万无一失的解决方案。这方面的修复和增强肯定会改变 Apache Groovy 和/或 Graal VM 的原生镜像编译器和 AOT 处理本身，这些都在这里没有任何意义或范围。

要了解有关 CAS 中 Apache Groovy 的更多信息，请参阅本指南。

1. 1. 本机映像提示

如果需要为反射、资源、序列化、代理使用等提供自己的提示，可以定义自己的类来实现 CasRuntimeHintsRegistrar API，大纲如下：

package org.example;

public class MyRuntimeHints implements CasRuntimeHintsRegistrar {

@Override

public void registerHints(RuntimeHints hints,

ClassLoader classLoader) {

// Register your own hints...

}}

然后，您可以在任何 @AutoConfiguration 类上使用 @ImportRuntimeHints 来激活此类提示。或者，您可以创建文件 src/main/resources/META-INF/spring/aot.factories，其中包含以下内容：

1	org.springframework.aot.hint.RuntimeHintsRegistrar=org.example.MyRuntimeHints

CAS 本身将为代码库中的许多模块提供大量本机映像提示。此过程和本机 imagesupport 覆盖范围并不详尽，系统可能会要求您为 CAS 提供的提示中不存在的组件、API 和进程注册自己的提示。如果您确实遇到此类情况，请考虑将这些提示直接贡献给 CAS 项目（如果提示属于或影响 CAS 拥有的组件），或者与可访问性元数据项目讨论该问题。

1. Kubernetes Helm 部署
  1. Kubernetes Helm 安装

CAS WAR Overlay Initializr 包括一个 CAS Helm 图表，可用于在 Kubernetes 集群上部署 CAS。本文档不会讨论如何设置 productionKubernetes 集群，但会介绍如何在本地 Kubernetes 集群上使用 Helm Chart 设置 CAS。本文档假定 CAS Initializr 已用于创建覆盖，因为该 Initializr 项目包含 Helm 图表，并且构建 CAS 容器映像需要 initializr 生成的覆盖。

注意

此 Helm Chart 是新的，一旦稳定下来，就可以将其发布到 Helm 存储库。目前，对于具有 CAS 和 Kubernetes 经验的部署人员来说，最好将其视为部署选项。

您可能还对通过 Kubernetes 管理 CAS 配置感兴趣。

1. 1. 什么是 Helm？

Helm Chart 是一组模板，这些模板与部署特定值相结合，以生成 Kubernetes 配置 yaml。Helm Chart 的部署者应该能够创建自己的值文件，以覆盖 Chart 定义的任何默认值并安装应用程序，而无需更改模板。如果模板需要更改，这些更改是回馈 Helm Chart 的候选项，因此随着时间的推移，它将变得更加可自定义并支持更多部署选项。

1. 1. CAS Helm Chart 概述

图表支持任意交易量的映射，并且可以在 values 文件中指定 cas config。配置可以在 cloud config 而不是 kubernetes 配置映射中，服务注册表可以在数据库、git 或 kubernetes 持久卷中的简单 json 注册表中。票据注册表可以使用 redis、postgresql 或 mongo 等的标准 helm 图表。目前，该图表在 Ingress Controller 与 CAS 和 Boot Admin 服务器之间使用 SSL。这可能有点矫枉过正，并且涉及到SSL带来的所有痛苦（例如信任和主机名验证）。此图表使用 StatefulSet 作为 CAS 而不是 Deployment，但这在未来可能会发生变化或变得可配置。

Spring Boot Admin CAS 服务器发现方法最终可能应该更改为“云”发现。

1. 1. 在本地 Kubernetes 安装上安装 CAS

以下部分概述了安装 Helm 和 Kubernetes 以及在本地安装和运行 CAS Helm Chart 的步骤。

1. 1. 1. 安装 Helm 和 Kubectl

Helm v3 和 Kubectl 只是单个二进制程序。Kubectl 可能随 kubernetesinstallation 一起提供，但两者都应该下载并放在 PATH 中。

安装 Helm

安装 Kubectl

1. 1. 1. 安装 Kubernetes

在 Mac、Windows 或 Linux 上运行 Kubernetes 集群有多种选择，但它们都需要将 Linux 作为 VM 或主机操作系统。CAS Helm Chart 作为 CAS Initializr 的持续集成脚本的一部分，在 K3S Kubernetes 安装上安装和测试，因此该方法应该始终有效，但它确实需要 Windows 和 Mac 用户安装 Linux 虚拟机（例如运行 Ubuntu）。

1. 1. 1. K3S Kubernetes

k3s 可以在 Linux 上运行，非常轻量级且易于安装以进行开发。不需要安装 Docker。

# install k3s, without traefik ingress controller

curl -sfL https://get.k3s.io | INSTALL_K3S_EXEC="server --disable traefik" sh# the following export is needed for helm, put in profileexport KUBECONFIG=/etc/rancher/k3s/k3s.yaml# build a CAS image from the overlay generated from Initializr

./gradlew clean build jibBuildTar --refresh-dependencies# import the image to k3s (k3s can pull images from registries but can't see local docker images)

k3s ctr images import build/jib-image.tar# verify the image is loaded

k3s ctr images ls | grep cas# Go to folder with helm chartcd helm # create secret for tomcat

./create-cas-server-keystore-secret.sh# create secret for ingress controller to use with CAS ingress (nginx-ingress will use default if not created)

./create-ingress-tls.sh# create configmap containing SSL trust store

./create-truststore.sh# install cas-server helm chart

helm upgrade --install cas-server ./cas-server

1. 1. 1. 1. 其他选项

Docker 桌面

安装 Docker Desktop

在“设置”中启用 Kubernetes

需要安装 Helm 和 Kubectl 并添加到 bash 终端的路径中（在 Windows 上使用 Git Bash 或 Cygwin 或 Msys2）

运行 shell 脚本以安装证书和信任存储（在 helm 子目录中）

通过 ./gradlew clean build jibBuildTar --refresh-dependencies 构建 CAS 镜像

将 CAS 映像本地加载到 Docker docker load < build/jib-image.tar

安装 Ingress Controller

安装 CAS Helm Chart

Minikube

1. 1. 1. 安装 Ingress Controller

CAS Helm Chart 仅使用 Kubernetes ingress-nginx 进行了测试，请随意添加对其他 Ingress 控制器的支持。Kubernetes Nginx Ingress 安装指南可在此处找到。

要使用 Helm 和 ingress-nginx Helm Chart 安装 Ingress 控制器：

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

1. 1. 1. 安装 CAS 服务器 Helm Chart

Helm 图表由模板组成，这些模板与来自一个或多个值文件（和命令行集参数）的值组合以生成 kubernetes yaml。chart 文件夹（包含 templates 目录）包含默认使用的 default values.yaml，但应在命令行上指定其他值文件以根据需要覆盖默认值。以下示例使用default命名空间，但可以将 --namespace cas 添加到以下任何 helm 命令中，以将 CAS 放在其自己的 kubernetes 命名空间中（需要先创建命名空间，例如 kubectl create namespace cas）

# delete cas-server helm chart install

helm delete cas-server# install cas-server chart

helm install cas-server ./cas-server# install or update cas-server

helm upgrade --install cas-server ./cas-server# use local values file to override defaults

helm upgrade --install cas-server --values values-local.yaml ./cas-server# see kubernetes yaml without installing

helm upgrade --install cas-server --values values-local.yaml ./cas-server --dry-run --debug# sometimes dry-run fails b/c yaml can't convert to json so use template instead to see problem

helm template cas-server --values values-local.yaml ./cas-server --debug

1. 1. 1. 有用的 kubectl 命令

如果使用非默认命名空间，请不要忘记添加 -n 或 --namespace。

# Look at the pods to see the status

kubectl get pods # Describe the CAS pod to see why it isn't starting

kubectl describe pod cas-server-0# tail the console logs

kubectl logs cas-server-0 -f# exec into container

kubectl exec -it cas-server-0 sh# bounce CAS pod

kubectl delete pod cas-server-0

1. 1. 1. 浏览至 CAS

确保此条目的 values file 中列出的任何主机都存在 host file 条目：

ingress:

hosts:

- host: cas.example.org

paths:

- "/cas"

tls:

- secretName: cas-server-ingress-tls

hosts:

- cas.example.org

1 2	# host entry 127.0.0.1 cas.example.org

CAS Spring Boot Admin 服务器有自己的入口，因为它是内部可访问的，而 CAS 可能是外部的，但两者都可以是内部的或外部的。

1. Servlet 容器
  1. 概述
    1. Servlet 容器配置

有许多容器选项可用于部署 CAS。WAR Overlay 指南介绍了如何构建和部署 CAS。

1. 1. 1. 我该如何选择？

菜单上有各种各样的 servlet 容器和服务器。选择标准概述如下：

选择您最熟悉的技术，并具备排除故障、调整和扩展的技能和耐心，以取得成功。

选择一种不会强制将 CAS 配置绑定到集群中任何单个服务器/节点的技术，因为这将带来自动扩展问题和手动操作。

选择一种与您的网络和防火墙配置配合良好且性能足够高且可靠的技术，具体取决于您的网络拓扑。

选择一种在预期负载下显示有希望的结果的技术，并运行性能和压力测试。

选择一种尽可能不依赖外部流程、系统和人工工作、自力更生且自给自足的技术。

1. 1. 1. 生产质量

这里介绍的所有 servlet 容器，无论是嵌入式的还是其他的，都旨在为生产做好准备。这意味着 CAS 附带了开箱即用的有用默认值，如有必要，可以覆盖这些默认值，默认情况下，CAS 会为您配置当今平台中从开发到生产的所有内容。就其生产质量而言，使用嵌入式容器与使用外部容器几乎没有区别。

除非有具体的、技术性的和合理的反对意见，否则选择嵌入式 servlet 容器几乎总是更好的选择。

1. 1. 1. 执行器端点

提供了以下终端节点：

POST	/cas/actuator/shutdown

通过“POST”关闭应用程序。默认情况下处于禁用状态。

POST	/cas/actuator/restart

POST	/cas/actuator/pause

POST	/cas/actuator/resume

1. 1. 1. 嵌入式

请参阅本指南。

1. 1. 1. 外部

请参阅本指南

1. 1. 1. Docker

您可能还对通过 Docker 部署 CAS 感兴趣。有关更多信息，请参阅本指南。

1. 1. 1. 系统服务

可以使用 init.d 或 systemd 轻松地将 CAS 作为 Unix/Linux 服务启动。要了解更多信息，请访问本指南。

1. 1. 选项
    1. 嵌入式
      1. 概述
        嵌入式 Servlet 容器

请注意，CAS 本身附带了许多嵌入式容器，这些容器允许平台尽可能自包含。这些嵌入式容器是 CAS 软件不可或缺的一部分，通常每个版本都会进行维护和更新，并且肯定用于生产部署。您不需要配置并部署到外部配置的容器，但如果需要，可以配置并部署到外部配置的容器。

1. 1. 1. 1. 配置

CAS 配置目录中提供了以下设置和属性：

第三方

笔记

下面列出的配置设置在 CAS 配置元数据中标记为 Third Party（第三方）。此标志表示配置设置不受 CAS 生态系统的控制、拥有或管理，并且会影响第三方库（如 Spring Boot 或 Spring Cloud to CAS）提供的功能。有关更多信息，您可能必须访问第三方来源以查找更多详细信息。

Show entries

搜索：

· server.servlet.application-display-name=application

应用程序的显示名称。

org.springframework.boot.autoconfigure.web.ServerProperties$Servlet.

如何配置此属性？

· server.servlet.context-parameters=

Servlet 上下文 init 参数。

org.springframework.boot.autoconfigure.web.ServerProperties$Servlet.

如何配置此属性？

· server.servlet.context-path=

应用程序的上下文路径。

org.springframework.boot.autoconfigure.web.ServerProperties$Servlet.

如何配置此属性？

· server.servlet.encoding.charset=UTF-8

HTTP 请求和响应的字符集。如果未明确设置，则添加到 “Content-Type” 标头中。

org.springframework.boot.web.servlet.server.Encoding.

如何配置此属性？

· server.servlet.encoding.enabled=true

是否启用 http 编码支持。

如何配置此属性？

显示 1 到 5 的 48 个条目

1. 1. 1. 1. 执行

CAS Web 应用程序构建后，可以通过以下命令与嵌入式容器一起部署到位：

1	java -jar /path/to/cas.war

此外，还可以将 CAS 作为完全可执行的 Web 应用程序运行：

1 2	# chmod +x /path/to/cas.war /path/to/cas.war

这是通过部署覆盖的构建过程实现的，其中启动脚本插入到 Web 应用程序构件的开头。如果要查看和检查脚本，请运行以下命令：

1 2	# X is the number of lines from the beginning of the file head -n X /path/to.cas.war

请注意，大多数 Linux 和 OS X 发行版都支持将 CAS 作为独立且完全可执行的 Web 应用程序运行。其他平台（如 Windows）可能需要自定义配置。

可以使用以下嵌入式 servlet 容器：

选择	参考
Apache Tomcat	请参阅本指南。
Jetty	请参阅本指南。
Undertow	请参阅本指南。

1. 1. 1. 1. Apache Tomcat
        概述
        Apache Tomcat - 嵌入式 Servlet 容器配置

请注意，默认情况下，嵌入式容器会尝试启用 HTTP2 协议。

Apache Maven

Gradle

BOM - Spring

BOM - Gradle

资源

dependencies {

The following platform references should be included automatically and are listed here for reference only.

implementation enforcedPlatform("org.apereo.cas:cas-server-support-bom:${project.'cas.version'}")

implementation platform(org.springframework.boot.gradle.plugin.SpringBootPlugin.BOM_COORDINATES)

Including this module in the CAS WAR overlay is optional and unnecessary. This module is automatically included

and bundled with the CAS server distribution and there are alternative options baked in to allow one to replace

this module with another. The entry below is listed for reference only.

implementation "org.apereo.cas:cas-server-webapp-tomcat"

}

1. 1. 1. 1. 配置

CAS 配置目录中提供了以下设置和属性：

第三方

笔记

Show entries

搜索：

· server.tomcat.accept-count=100

当所有可能的请求处理线程都在使用中时，传入连接请求的最大队列长度。

org.springframework.boot.autoconfigure.web.ServerProperties$Tomcat.

如何配置此属性？

· server.tomcat.accesslog.buffered=true

是否缓冲 output 以便仅定期刷新它。

org.springframework.boot.autoconfigure.web.ServerProperties$Tomcat$Accesslog.

如何配置此属性？

· server.tomcat.accesslog.check-exists=false

是否检查日志文件是否存在，以便在外部进程重命名日志文件时可以重新创建日志文件。

org.springframework.boot.autoconfigure.web.ServerProperties$Tomcat$Accesslog.

如何配置此属性？

· server.tomcat.accesslog.condition-if=

是否仅在 “ServletRequest.getAttribute（conditionIf）” 不产生 null 时启用请求的日志记录。

org.springframework.boot.autoconfigure.web.ServerProperties$Tomcat$Accesslog.

如何配置此属性？

· server.tomcat.accesslog.condition-unless=

是否仅在 “ServletRequest.getAttribute（conditionUnless）” 生成 null 时启用请求日志记录。

org.springframework.boot.autoconfigure.web.ServerProperties$Tomcat$Accesslog.

如何配置此属性？

显示 1 到 5 的 49 个条目

1. 1. 1. 1. IPv4 配置

要强制 Apache Tomcat 使用 IPv4，请将以下内容配置为 run 命令的系统属性：

1	-Djava.net.preferIPv4Stack=true

对于外部容器，需要将相同类型的配置应用于 $CATALINA_OPTS环境变量。

1. 1. 1. 1. HTTP和代理
        Apache Tomcat - 嵌入式 Servlet 容器代理

CAS 配置目录中提供了以下设置和属性：

必填

自选

笔记

下面列出的配置设置在 CAS 配置元数据中标记为 Required。此标志表示可能需要该设置的存在才能激活或影响 CAS 功能的行为，并且通常应进行审查、可能拥有和调整。如果为该设置分配了默认值，则无需严格将该设置放在配置副本中，但仍应对其进行检查以确保它符合您的部署预期。

Show entries

搜索：

· cas.server.tomcat.http-proxy.enabled=false

启用以代理模式运行的容器。

org.apereo.cas.configuration.model.core.web.tomcat.CasEmbeddedApacheTomcatHttpProxyProperties.

如何配置此属性？

· cas.server.tomcat.http[0].enabled=

为嵌入式容器启用单独的端口以进行 HTTP 访问。

org.apereo.cas.configuration.model.core.web.tomcat.CasEmbeddedApacheTomcatHttpProperties.

如何配置此属性？

显示 1 到 2 的 2 个条目

1. 1. 1. 1. 访问日志
        Apache Tomcat - 嵌入式 Servlet 容器访问日志

CAS 配置目录中提供了以下设置和属性：

必填

自选

笔记

Show entries

搜索：

· cas.server.tomcat.ext-access-log.enabled=false

用于指示是否启用扩展日志工具的标志。

org.apereo.cas.configuration.model.core.web.tomcat.CasEmbeddedApacheTomcatExtendedAccessLogProperties.

如何配置此属性？

显示 1 到 1 的 1 个条目

1. 1. 1. 1. 重写Value
        Apache Tomcat - 嵌入式 Servlet 容器重写Value

CAS 配置目录中提供了以下设置和属性：

必填

笔记

Show entries

搜索：

· cas.server.tomcat.rewrite-valve.location=

由 Apache Tomcat 专门提供的重写阀的位置，用于激活 URL 重写。

org.apereo.cas.configuration.model.core.web.tomcat.CasEmbeddedApacheTomcatRewriteValveProperties.

如何配置此属性？

显示 1 到 1 的 1 个条目

1. 1. 1. 1. AJP
        Apache Tomcat - 嵌入式 Servlet 容器 AJP

CAS 配置目录中提供了以下设置和属性：

必填

自选

笔记

Show entries

搜索：

· cas.server.tomcat.ajp.enabled=false

在 CAS 中为嵌入式 Apache Tomcat 容器启用 AJP 支持。

org.apereo.cas.configuration.model.core.web.tomcat.CasEmbeddedApacheTomcatAjpProperties.

如何配置此属性？

显示 1 到 1 的 1 个条目

1. 1. 1. 1. APR
        Apache Tomcat - 嵌入式 Servlet 容器 APR

Apache Tomcat 可以使用 Apache Portable Runtime 来提供卓越的可扩展性、性能，并与本机服务器技术更好地集成。

启用 APR 需要以下 JVM 系统属性，该属性指示 APR 库二进制文件的位置（即 usr/local/opt/tomcat-native/lib）：

1	-Djava.library.path=/path/to/tomcat-native/lib

1. 1. 1. 1. 基本身份验证
        Apache Tomcat - 嵌入式 Servlet 容器基本身份验证

CAS 配置目录中提供了以下设置和属性：

必填

自选

笔记

Show entries

搜索：

· cas.server.tomcat.basic-authn.enabled=false

为 Tomcat 启用 Basic authentication。

org.apereo.cas.configuration.model.core.web.tomcat.CasEmbeddedApacheTomcatBasicAuthenticationProperties.

如何配置此属性？

显示 1 到 1 的 1 个条目

1. 1. 1. 1. 集群和复制
        Apache Tomcat - 嵌入式 Servlet 容器集群

启用内存中会话复制以复制 Web 应用程序会话增量。

聚类类型	描述
DEFAULT	通过多播发现集群成员，以及（可选）通过使用 clusterMembers 静态定义的集群成员来发现集群成员。带有 McastService 的 SimpleTcpCluster
CLOUD	用于 Kubernetes，其中成员是通过访问 Kubernetes API 或对 Kubernetes 服务的成员进行 DNS 查找来发现的。文档目前比较简单，详见代码。

成员资格提供商	描述
kubernetes	使用 Kubernetes API 查找部署中的其他 Pod。API 是通过容器中设置的环境变量中的信息发现和访问的。KUBERNETES_NAMESPACE 环境变量用于查询命名空间中的 Pod，它会将该命名空间中的其他 Pod 视为潜在的集群成员，但可以使用 KUBERNETES_LABELS 环境变量（用作标签选择器）对其进行过滤。
dns	使用 DNS 查找查找环境变量指定的 DNS 名称后面DNS_MEMBERSHIP_SERVICE_NAME集群成员的地址。在 Kubernetes 中运行，但不依赖 Kubernetes。
MembershipProvider 类	使用您选择的成员资格提供程序实现。

大多数设置都适用于 DEFAULT 集群类型，如果多播发现不起作用，则要求通过 clusterMembers 定义成员。cloudMembershipProvider 设置适用于 CLOUD 类型。

CAS 配置目录中提供了以下设置和属性：

必填

自选

笔记

Show entries

搜索：

· cas.server.tomcat.clustering.enabled=false

启用 tomcat 会话集群。

org.apereo.cas.configuration.model.core.web.tomcat.CasEmbeddedApacheTomcatClusteringProperties.

如何配置此属性？

显示 1 到 1 的 1 个条目

1. 1. 1. 1. 连接
        Apache Tomcat - 嵌入式 Servlet 容器连接器

CAS 配置目录中提供了以下设置和属性：

自选

笔记

下面列出的配置设置在 CAS 配置元数据中标记为 Optional（可选）。This标志表示在最终用户 CAS 配置中不需要立即存在该设置，因为分配了默认值，或者该功能的激活不受设置值有条件地控制。换句话说，仅当需要修改默认值或需要打开由设置控制的功能时，才应在配置中包含此字段。

Show entries

搜索：

· cas.server.tomcat.socket.app-read-buf-size=0

在 Tomcat 中打开的每个连接都与一个读取的 ByteBuffer 相关联。此属性控制此缓冲区的大小。默认情况下，此读取缓冲区的大小为 8192 字节。对于较低的并发性，您可以增加此值以缓冲更多数据。对于极数量的 Keep Alive 连接，请减少此数量或增加堆大小。

org.apereo.cas.configuration.model.core.web.tomcat.CasEmbeddedApacheTomcatSocketProperties.

如何配置此属性？

· cas.server.tomcat.socket.app-write-buf-size=0

在 Tomcat 中打开的每个连接都与一个写入 ByteBuffer 相关联。此属性控制此缓冲区的大小。默认情况下，此写入缓冲区的大小为 8192 字节。对于低并发性，您可以增加此值以缓冲更多响应数据。对于极数量的 Keep Alive 连接，请减少此数量或增加堆大小。这里的默认值非常低，如果您不处理数以万计的并发连接，则应提高该值。

org.apereo.cas.configuration.model.core.web.tomcat.CasEmbeddedApacheTomcatSocketProperties.

如何配置此属性？

· cas.server.tomcat.socket.buffer-pool=0

NIO 连接器使用一个名为 NioChannel 的类，该类包含链接到套接字的元素。为了减少垃圾回收，NIO 连接器缓存了这些 channel 对象。此值指定此缓存的大小。默认值为 500，表示缓存将容纳 500 个 NioChannel 对象。其他值为 -1 表示无限缓存，0 表示无缓存。

org.apereo.cas.configuration.model.core.web.tomcat.CasEmbeddedApacheTomcatSocketProperties.

如何配置此属性？

· cas.server.tomcat.socket.performance-bandwidth=-1

表示高带宽的相对重要性的 int 。性能首选项由三个整数描述，这些整数的值表示短连接时间、低延迟和高带宽的相对重要性。整数的绝对值无关紧要;为了选择协议，将比较这些值，值越大表示偏好越强。负值将禁用该设置。例如，如果应用程序更喜欢较短的连接时间，而不是低延迟和高带宽，则它可以使用值（1， 0， 0）调用此方法。如果应用程序更喜欢高带宽而不是低延迟，以及低延迟而不是短连接时间，那么它可以使用值（0， 1， 2）调用此方法。

org.apereo.cas.configuration.model.core.web.tomcat.CasEmbeddedApacheTomcatSocketProperties.

如何配置此属性？

· cas.server.tomcat.socket.performance-connection-time=-1

一个 int，表示短连接时间的相对重要性。性能首选项由三个整数描述，这些整数的值表示短连接时间、低延迟和高带宽的相对重要性。整数的绝对值无关紧要;为了选择协议，将比较这些值，值越大表示偏好越强。负值将禁用该设置。例如，如果应用程序更喜欢较短的连接时间，而不是低延迟和高带宽，则它可以使用值（1， 0， 0）调用此方法。如果应用程序更喜欢高带宽而不是低延迟，以及低延迟而不是短连接时间，那么它可以使用值（0， 1， 2）调用此方法。

org.apereo.cas.configuration.model.core.web.tomcat.CasEmbeddedApacheTomcatSocketProperties.

如何配置此属性？

显示 1 到 5 的 6 个条目

1. 1. 1. 1. Logging
        Apache Tomcat - 嵌入式 Servlet 容器日志记录

嵌入式 Apache Tomcat 容器目前无法在 INFO 下显示任何日志消息，即使您的 CAS 日志配置明确要求 DEBUG 或 TRACE 级别数据也是如此。请参阅此 bug 报告以了解更多信息。

虽然将来可能会提供解决方法和修复，但目前，您可以执行以下更改，以从嵌入式 Apache Tomcat 获取 DEBUG 级别的日志数据。如果要对 Tomcat 内部组件（如阀门等）的行为进行故障排除，这将特别有用。

设计一个 logging.properties 文件，如下所示：

handlers = java.util.logging.ConsoleHandler.level = ALLjava.util.logging.ConsoleHandler.level = FINERjava.util.logging.ConsoleHandler.formatter = java.util.logging.SimpleFormatter

将java.util.logging.config.file 设置设计为系统/环境变量或命令行参数，其值设置为 logging.properties 路径。在启动和部署 CAS 时使用该设置。

例如：

1	java -jar /path/to/cas.war -Djava.util.logging.config.file=/path/to/logging.properties

1. 1. 1. 1. 移除用户阀
        Apache Tomcat - 嵌入式 Servlet 容器远程用户

CAS 配置目录中提供了以下设置和属性：

必填

自选

笔记

Show entries

搜索：

· cas.server.tomcat.remote-user-valve.remote-user-header=

应传递到 http servlet 请求的 remote-user 标头的名称。将此设置留空或未定义将完全停用 valve。标头通常通过代理、负载均衡器等传递给 tomcat。

org.apereo.cas.configuration.model.core.web.tomcat.CasEmbeddedApacheTomcatRemoteUserValveProperties.

如何配置此属性？

显示 1 到 1 的 1 个条目

1. 1. 1. 1. 会话初始化
        Apache Tomcat - 嵌入式 Servlet 容器会话初始化

CAS 配置目录中提供了以下设置和属性：

必填

笔记

Show entries

搜索：

· cas.server.tomcat.session-initialization.enabled=false

启用筛选器。

org.apereo.cas.configuration.model.core.web.tomcat.CasEmbeddedApacheTomcatSessionInitializationProperties.

如何配置此属性？

显示 1 到 1 的 1 个条目

1. 1. 1. 1. SSL Valve
        Apache Tomcat - 嵌入式 Servlet 容器 SSL Valve

Apache Tomcat SSLValve 是一种通过 HTTP 标头从运行在 Tomcat 前面的 SSL 代理（例如 HAProxy 或 BigIP F5）获取客户端证书的方法。如果启用此功能，请确保您的代理确保此标头不是源自客户端（例如浏览器）。

CAS 配置目录中提供了以下设置和属性：

必填

自选

笔记

Show entries

搜索：

· cas.server.tomcat.ssl-valve.enabled=false

为 apache tomcat 启用 SSL Valve。

org.apereo.cas.configuration.model.core.web.tomcat.CasEmbeddedApacheTomcatSslValveProperties.

如何配置此属性？

显示 1 到 1 的 1 个条目

HAProxy 配置示例（代码段）：使用 cert optional配置 SSL 前端，重定向到 cas，如果提供了 cert，则将其放在标头上。

frontend web-vip

bind 192.168.2.10:443 ssl crt /var/lib/haproxy/certs/www.example.com.pem ca-file /var/lib/haproxy/certs/ca.pem verify optional

mode http

acl www-cert ssl_fc_sni if { www.example.com }

acl empty-path path /

http-request redirect location /cas/ if empty-path www-cert

http-request del-header ssl_client_cert unless { ssl_fc_has_crt }

http-request set-header ssl_client_cert -----BEGIN\ CERTIFICATE-----\ %[ssl_c_der,base64]\ -----END\ CERTIFICATE-----\ if { ssl_fc_has_crt }

acl cas-path path_beg -i /cas

reqadd X-Forwarded-Proto:\ https

use_backend cas-pool if cas-path

backend cas-pool

option httpclose

option forwardfor

cookie SERVERID-cas insert indirect nocache

server cas-1 192.168.2.10:8080 check cookie cas-1

1. 1. 1. 1. Jetty
        Jetty - 嵌入式 Servlet 容器配置

Apache Maven

Gradle

BOM - Spring

BOM - Gradle

资源

dependencies {

The following platform references should be included automatically and are listed here for reference only.

implementation enforcedPlatform("org.apereo.cas:cas-server-support-bom:${project.'cas.version'}")

implementation platform(org.springframework.boot.gradle.plugin.SpringBootPlugin.BOM_COORDINATES)

Including this module in the CAS WAR overlay is optional and unnecessary. This module is automatically included

and bundled with the CAS server distribution and there are alternative options baked in to allow one to replace

this module with another. The entry below is listed for reference only.

implementation "org.apereo.cas:cas-server-webapp-jetty"}

1. 1. 1. 1. 嵌入式 Jetty 集装箱

CAS 配置目录中提供了以下设置和属性：

自选

第三方

笔记

Show entries

搜索：

· cas.server.jetty.sni-host-check=true

服务器名称指示是传输层安全性（TLS）协议的扩展，它允许客户端在握手过程开始时指示它尝试连接到的主机名。当服务器在单个 IP 地址上托管具有不同 SSL 证书的多个域时，这尤其有用。将此设置设置为 false 意味着 Jetty 服务器不会严格要求客户端在 SSL/TLS 握手期间发送 SNI 扩展，并在 SSL/TLS 握手期间禁用服务器名称指示（SNI）的主机名检查。

org.apereo.cas.configuration.model.core.web.jetty.CasEmbeddedJettyProperties.

如何配置此属性？

显示 1 到 1 的 1 个条目

1. 1. 1. 1. Undertow
        Undertow - 嵌入式 Servlet 容器配置

Apache Maven

Gradle

BOM - Spring

BOM - Gradle

资源

dependencies {

The following platform references should be included automatically and are listed here for reference only.

implementation enforcedPlatform("org.apereo.cas:cas-server-support-bom:${project.'cas.version'}")

implementation platform(org.springframework.boot.gradle.plugin.SpringBootPlugin.BOM_COORDINATES)

Including this module in the CAS WAR overlay is optional and unnecessary. This module is automatically included

and bundled with the CAS server distribution and there are alternative options baked in to allow one to replace

this module with another. The entry below is listed for reference only.

implementation "org.apereo.cas:cas-server-webapp-undertow"}

CAS 配置目录中提供了以下设置和属性：

第三方

笔记

Show entries

搜索：

· server.undertow.accesslog.dir=

Undertow 访问日志目录。

org.springframework.boot.autoconfigure.web.ServerProperties$Undertow$Accesslog.

如何配置此属性？

· server.undertow.accesslog.enabled=false

是否开启访问日志。

org.springframework.boot.autoconfigure.web.ServerProperties$Undertow$Accesslog.

如何配置此属性？

· server.undertow.accesslog.pattern=common

访问日志的格式模式。

org.springframework.boot.autoconfigure.web.ServerProperties$Undertow$Accesslog.

如何配置此属性？

· server.undertow.accesslog.prefix=access_log.

日志文件名前缀。

org.springframework.boot.autoconfigure.web.ServerProperties$Undertow$Accesslog.

如何配置此属性？

· server.undertow.accesslog.rotate=true

是否开启访问日志轮换。

org.springframework.boot.autoconfigure.web.ServerProperties$Undertow$Accesslog.

如何配置此属性？

显示 1 到 5 的 25 个条目

1. 1. 1. 外部
      1. 外部 Servlet 容器配置

CAS 部署可以部署到任意数量的外部 servlet 容器。容器必须至少支持 servlet 规范 6.0.0。在这些情况下，可以在 WAR Overlay 中使用以下普通 CAS Web 应用程序：

Apache Maven

Gradle

BOM - Spring

BOM - Gradle

资源

dependencies {

The following platform references should be included automatically and are listed here for reference only.

implementation enforcedPlatform("org.apereo.cas:cas-server-support-bom:${project.'cas.version'}")

implementation platform(org.springframework.boot.gradle.plugin.SpringBootPlugin.BOM_COORDINATES)

Including this module in the CAS WAR overlay is optional and unnecessary. This module is automatically included

and bundled with the CAS server distribution and there are alternative options baked in to allow one to replace

this module with another. The entry below is listed for reference only.

implementation "org.apereo.cas:cas-server-webapp"}

虽然没有官方项目支持，但以下容器应与 CAS 部署兼容：

Apache Tomcat（至少需要 Apache Tomcat 10）

JBoss

Wildfly

Undertow

Jetty（至少需要 Jetty 12）

GlassFish

WebSphere

请记住，CAS 绝不会以任何方式自动进行外部容器的配置，这意味着您负责升级、维护和所有其他配置方式，例如日志记录、SSL 等。CAS 不为外部容器的配置或问题提供官方支持和故障排除指南等。有关更多信息，请参阅 Servlet 容器自己的文档。

注意：对于 JBoss、Wildfly 和 EAP，你可能需要在 overlay 的 src/main/webapp/WEB-INF 中添加一个 jboss-deloyment-structure.xml 文件，以便 CAS 正确启动。

<jboss-deployment-structure>

</dependencies>

</deployment></jboss-deployment-structure>

1. 1. 1. 1. 配置

通过在覆盖中包含以下模块来启用对外部容器的支持：

Apache Maven

Gradle

BOM - Spring

BOM - Gradle

资源

dependencies {

The following platform references should be included automatically and are listed here for reference only.

implementation enforcedPlatform("org.apereo.cas:cas-server-support-bom:${project.'cas.version'}")

implementation platform(org.springframework.boot.gradle.plugin.SpringBootPlugin.BOM_COORDINATES)

implementation "org.apereo.cas:cas-server-webapp"}

1. 1. 1. 1. 异步支持

文件（例如，对于 Apache Tomcat，则为 $CATALINA_HOME/conf/web.xml）。

1. 1. 1. 1. Logging

使用外部容器时，您可能需要确保 CAS 默认附带的日志记录配置文件处于禁用状态，并特别如果通过 CAS 设置控制日志配置和位置，则将其转换为无操作。这是必需的，因为在外部 servlet 容器内初始化 CAS Web 应用程序上下文往往会在 CAS 本身有机会通过设置控制日志记录之前过早地从 Classpath 初始化日志配置。

要禁用 CAS 自己的日志记录，请在 src/main/resources 下定义log4j2.xml，并在其中放入以下内容：

<?xml version="1.0" encoding="UTF-8" ?><Configuration>

</Console>

</Appenders>

</AsyncRoot>

</Loggers></Configuration>

上述配置将使日志记录初始化变得毫无意义，从而允许通过 CAS 设置定义日志的位置和配置。

1. 1. 1. 1. 异步日志记录

CAS 日志记录会自动将自身插入到运行时应用程序上下文中，并在指示容器关闭后清理日志记录上下文。但是，Apache Tomcat 似乎在默认情况下会忽略所有名为 log4j*.jar 的 JAR 文件，这会阻止此功能正常工作。您可能需要更改 catalina.properties 并从 jarsToSkip 属性中删除 log4j*.jar。否则，将阻止容器正常关闭，并导致 Logger 上下文线程挂起。

如果其他容器跳过扫描 Log4j JAR 文件，则可能需要在其他容器上执行类似的操作。

1. 操作系统服务
  1. OS 服务部署

可以使用 init.d 或 systemd 轻松地将 CAS 作为 Unix/Linux 服务启动。Windows 支持也通过外部守护程序提供。请注意，以下大多数（如果不是全部）策略都尝试通过 embeddedservlet 容器运行 CAS，此处解释了该容器的配置。

HEAT.D 服务

SYSTEM.D 服务

UPSTART

WINDOWS 服务

如果 CAS 是作为完全可执行的 Web 应用程序构建和运行的，那么它可以用作 init.d 服务。将 Web 应用程序文件symlink init.d以支持标准的 start、stop、restart 和 status 命令。

CAS 中内置的配置允许它与操作系统系统配置进行交互，如下所示：

要将 CAS 安装为 init.d 服务，请创建一个符号链接：

1 2	sudo ln -s /path/to/cas.war /etc/init.d/cas service cas start

您还可以使用标准操作系统工具将应用程序标记为自动启动。例如，在 Debian 上：

1	update-rc.d myapp defaults <priority>

1. 1. 安全

当以 root 身份执行时，就像使用 root 启动 init.d 服务时一样，CAS defaultexecutable 脚本将以拥有 Web 应用程序文件的用户身份运行 Web 应用程序。您永远不应该以 root 身份运行 CAS，因此 Web 应用程序文件永远不应归 root 所有。相反，请创建一个特定用户来运行 CAS 并使用 chown 使其成为文件的所有者。例如：

1	chown bootapp:bootapp /path/to/cas.war

您还可以采取措施来防止修改 CAS Web 应用程序文件。首先，配置其权限，使其不能被写入，只能由其所有者读取或执行：

1	chmod 500 /path/to/cas.war

此外，您还应该采取措施来限制 CAS Web 应用程序或运行它的账户被盗用时的损害。如果攻击者确实获得了访问权限，他们可以使 Web 应用程序文件可写并更改其内容。防止这种情况的一种方法是使用 chattr 使其不可变：

1	sudo chattr +i /path/to/cas.war

这将阻止任何用户（包括 root）修改文件。

1. 故障排除指南

此处收集了许多常见问题和解答。请留意更新，因为随着时间/开发的进展，这可能会增加。

1. 1. 查看日志

CAS 服务器日志是确定问题根本原因的最佳资源，前提是您已配置适当的日志级别。具体来说，您需要确保在日志配置中的 org.apereo 包上开启了 DEBUG 级别：

应用更改后，重新启动服务器环境并观察日志文件，以更好地了解 CAS 行为。有关更多信息，请查看本指南，了解如何使用 CAS 配置日志。

请注意，上述配置块仅解决 CAS 组件的日志记录行为;而不是 CAS 所依赖的那些。查阅 log4j 配置并为每个相关组件打开适当的 DEBUG 日志。这些通常是诊断和故障排除的最佳数据源。

如果您选择的容器是 Apache Tomcat，您可能还需要查看 catalina.out 和 localhost-X-Y-Z.log 日志文件，以了解有关问题来源的更多信息。

1. 1. 部署问题;配置问题 X.您能帮忙吗？

是的。研究这个。

1. 1. 如何优化/扩展 MongoDb、MySQL、Hazelcast、Docker 等？

如果您对 CAS 使用的外部组件的调整和配置有疑问，并且您需要实现 CAS 默认提供的更高级的使用案例，则您的问题最好由负责该组件开发和支持的社区来解决。作为一般规则，您应该始终选择您最熟悉的技术，否则，请向 Spring Webflow、MongoDb、Hazelcast、Redis 等论坛提出问题，让专家审查和推荐想法。

此类别中最好在其他地方回答的典型问题是：

如何将 TLS 版本从 A 更改为 B？

为什么 Azure/AWS/GCP 以这种方式工作？

如何为 Apache Tomcat、Jetty、Active Directory 等配置 SSL？

如何在 Spring webflow 中将变量从一个流传递到下一个流？

如何优化 hazelcast 集群？

您能解释一下配置 Redis Sentinel 所需的步骤吗？

使 MongoDb 高可用性的推荐策略是什么？

1. 1. 试用最新补丁版本

您尝试解决的问题很可能已在下一个补丁版本中得到解决。补丁版本是一种保守的增量改进，包括错误修复和小的增强功能，并且与同一 MINOR 版本的先前 PATCH 版本绝对向后兼容。例如，如果您当前使用的是 CAS 版本 6.5.1 并遇到了可能的问题，则应考虑升级到 6.5.2 和 6.5.3 等，以进一步调查，前提是版本当然可用并已发布。

项目发布时间表可在此处获得，您可以随时查看已发布的版本。

1. 1. 使用 SNAPSHOT 版本

在某些情况下，您可能会了解到与您的 CAS 部署相关的缺陷或行为有可用的修复程序，并且系统可能会建议您升级到当前可用的 SNAPSHOT 版本。根据您选择的安装，您需要在部署配置和构建脚本中找到描述当前 CAS 版本的设置，并将其升级到下一个 SNAPSHOT。构建脚本还应包含有关如何在 README 文件等中获取和构建 SNAPSHOT 版本的其他说明。

要了解适用于您的部署的 SNAPSHOT 版本，您可以查看发布计划或 CAS 代码库的相应分支。例如，如果您已部署 CAS 2.0.4，并且发布计划显示下一个版本的目标是 2.0.5，则可用的 SNAPSHOT 版本将为 2.0.5-SNAPSHOT。您还可以查看分配给议题/拉取请求的里程碑设置并确定 SNAPSHOT 版本。SNAPSHOT 版本始终以 -SNAPSHOT 为后缀。如果分配给问题的里程碑是例如 1.2.5-RC1，则 SNAPSHOT 版本将为 1.2.5-RC1-SNAPSHOT。

1. 1. 配置 SSL Behind Load Balancer/Proxy

您可能正在 servlet 容器（如 Apache Tomcat）中运行 CAS，该容器位于某种代理（如 haproxy、Apache httpd 等）后面，其中代理正在处理 SSL 终止。与用户的连接通过 https 进行保护，但代理和 CAS 服务之间的连接只是 http。

通过此设置，CAS 登录屏幕可能仍会警告您连接不安全。CAS 中没有允许您控制/调整此设置的设置，因为这完全由容器本身控制。CAS 只关心传入连接请求是否将自身标识为安全连接。因此，要删除警告，您需要查看容器的配置和文档，了解如何保护代理和 CAS 之间的连接。

对于 Apache Tomcat，您可以使用 secure=true 属性调整与代理通信的连接器。

1. 1. 应用程序 X“重定向您太多次”

“Too many redirect” 错误通常是由服务票证验证失败事件引起的，通常是由应用程序配置错误引起的。票证验证失败可能是由过期或无法识别的票证、与 SSL 相关的问题等引起的。检查您的 CAS 日志，您将找到原因。

1. 1. 未接收属性

如果您的客户端应用程序未接收属性，则需要确保：

客户端正在使用能够释放属性的 CAS 协议版本。

基于 #1 的客户端正在点击相应的服务票证验证终端节点（即 /p3/serviceValidate）。

CAS 服务器本身正在正确解析和检索属性。

CAS 服务器有权在其服务注册表中释放该特定客户端应用程序的属性。

请查看本指南以更好地了解 CAS 服务注册表。

1. 1. 应用程序未授权

当在 CAS 服务注册表中找不到请求应用程序/服务 URL 时，您可能会遇到此错误。当身份验证请求提交到 CAS login端点时，目标应用程序将指示为 url 参数，该参数将根据 CAS 服务注册表进行检查，以确定是否允许该应用程序使用 CAS。如果未找到 URL，则将重新显示此消息。由于注册表中的服务定义能够由 url 模式定义，因此完全有可能注册表中服务定义的模式配置错误，并且不会为请求的应用程序 url 生成成功匹配。

请查看本指南以更好地了解 CAS 服务注册表。

1. 1. 无效/过期的 CAS 票证

尝试使用 CAS 票证时INVAILD_TICKET相关错误，该票证的过期策略指示该票证已过期。CAS 日志应进一步更详细地说明票证是否被视为过期，但出于诊断目的，您可能需要调整票证过期策略配置以删除和排查此错误。

此外，如果无法在 CAS 票证注册表中找到票证本身，则该票证也被视为无效。您需要观察使用的票证，并将其与票证注册表中存在的值进行比较，以确保提供的票证 ID 有效。

1. 1. Out of Heap Memory 错误

java.lang.OutOfMemoryError: GC overhead limit exceeded

at java.util.Arrays.copyOfRange(Arrays.java:3658)

at java.lang.StringBuffer.toString(StringBuffer.java:671)

您可能会遇到此错误，因为很可能使用了基于缓存的票证注册表（如 Hazelcast），其驱逐策略未正确配置。对象和票据缓存在注册表存储后端中，其存在时间往往比应有的时间长，或者驱逐策略没有做好清理可能被 CAS 标记为过期的未使用票据的工作。

要进行故障排除，您可以将 JVM 配置为在退出之前执行堆转储，您应该立即进行设置，以便在下次发生时获得一些其他信息。以下系统属性应该可以解决问题：

1	-XX:+HeapDumpOnOutOfMemoryError -XX:HeapDumpPath="/path/to/jvm-dump.hprof"

此外，请确保您的容器配置为具有足够的可用内存。对于 Apache Tomcat，可以将以下设置配置为环境变量。

1	CATALINA_OPTS=-Xms1000m -Xmx2000m

您将需要使用类似 JVisualVM 的内容来分析您的服务器。这将帮助您了解内存的实际情况。

您还可以考虑使用 JMap 工具或 YourKit Java 分析器进行定期堆转储，并使用某些分析工具进行离线分析。

最后，查看票据注册表的驱逐策略，并确保确定对象生命周期的值适合您的环境。

1. 1. SSL & 证书
    1. PKIX 路径构建失败

Sep 28, 2009 4:13:26 PM org.apereo.cas.client.validation.AbstractCasProtocolUrlBasedTicketValidator retrieveResponseFromServer

SEVERE: javax.net.ssl.SSLHandshakeException:

sun.security.validator.ValidatorException: PKIX path building failed:

sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target

javax.net.ssl.SSLHandshakeException:

sun.security.validator.ValidatorException: PKIX path building failed:

sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target

at com.sun.net.ssl.internal.ssl.Alerts.getSSLException(Unknown Source)

at com.sun.net.ssl.internal.ssl.SSLSocketImpl.fatal(Unknown Source)

at com.sun.net.ssl.internal.ssl.Handshaker.fatalSE(Unknown Source)

at com.sun.net.ssl.internal.ssl.ClientHandshaker.serverCertificate(Unknown Source)

PKIX 路径构建错误是最常见的 SSL 错误。此处的问题是 CAS 客户端不信任 CAS 服务器提供的证书;大多数情况下，发生这种情况是由于在 CAS 服务器上使用自签名证书。要解决此错误，请将 CAS 服务器证书导入 CAS 客户端的系统信任库。如果证书是由您自己的 PKI 颁发的，则最好将 PKI 的根证书导入到 CAS 客户端信任库中。

默认情况下，Java 系统信任库位于 $JAVA_HOME/jre/lib/security/cacerts。要导入的证书必须是 DER 编码的文件。如果证书文件的内容是二进制的，则可能是 DER 编码的;如果文件以文本 ---BEGIN CERTIFICATE------ 开头，则它是 PEM 编码的，需要转换为 DER 编码。

1	keytool -import -keystore $JAVA_HOME/jre/lib/security/cacerts -file tmp/cert.der -alias certName

如果您的计算机上安装了多个 java 版本，请确保应用程序/Web 服务器指向正确的 JDK/JRE 版本（证书已正确导出到的版本）生成自我验证证书时发生的一个常见错误是JAVA_HOME可能与服务器使用的证书不同。

1. 1. 1. 无使用者可选名称

1	javax.net.ssl.SSLHandshakeException: java.security.cert.CertificateException: No subject alternative names present

这是主机名/SSL 证书 CN 不匹配。当颁发给 localhost 的自签名证书放置在通过 IP 地址访问的计算机上时，通常会发生这种情况。应该注意的是，生成带有通用名称 IP 地址的证书，例如 CN=192.168.1.1,OU=Middleware,dc=vt,dc=edu，在建立连接的客户端是 Java 的大多数情况下是行不通的。

1. 1. 1. HTTPS 主机名错误

java.lang.RuntimeException: java.io.IOException: HTTPS hostname wrong: should be <eiger.iad.vt.edu>

org.apereo.cas.client.validation.Saml11TicketValidator.retrieveResponseFromServer(Saml11TicketValidator.java:203)

org.apereo.cas.client.validation.AbstractUrlBasedTicketValidator.validate(AbstractUrlBasedTicketValidator.java:185)

org.apereo.cas.client.validation.AbstractTicketValidationFilter.doFilter

当 CAS 客户端票证验证程序尝试联系 CAS 服务器，并收到其 CN 与 CAS 服务器的完全限定主机名不匹配的证书时，最常发生上述错误。这种不匹配有几个常见的根本原因：

CAS 客户端配置错误

复杂的多层服务器环境（例如群集 CAS 服务器）

主机名对于通配符证书的范围来说太宽泛

此外，还有必要检查您的 CAS 服务器用于 SSL 加密的证书是否与客户端正在检查的证书匹配。

1. 1. 1. 未找到与 X 匹配的名称

Caused by: java.security.cert.CertificateException: No name matching cas.server found

at sun.security.util.HostnameChecker.matchDNS(Unknown Source) ~[?:1.8.0_77]

at sun.security.util.HostnameChecker

同上。

1. 1. 1. 通配符证书

对通配符证书的 Java 支持仅限于与通配符严格位于同一域中的主机。例如，CN=.vt.edu 的证书与主机 a.vt.edu 和 b.vt.edu 匹配，但与主机 a.b.vt.edu 不匹配。

1. 1. 1. 无法识别的名称错误

1	javax.net.ssl.SSLProtocolException: handshake alert: unrecognized_name

上述错误主要发生在 Oracle JDK CAS Server 安装中。在 JDK 中，SNI（服务器名称指示）默认处于启用状态。当 HTTPD 服务器未发回正确的服务器名称时，JDK HTTP 连接将拒绝连接并引发上述异常。

您必须确保您的 HTTPD 服务器发回正确的主机名。例如，在 Apache HTTPD 中，您必须在 SSL 虚拟主机中设置 ServerAlias：

1 2	ServerName your.ssl-server.name ServerAlias your.ssl-server.name

或者，您可以通过将此标志添加到 CAS 服务器的应用程序服务器配置的 Java 选项中，在 JDK 中禁用 SNI 检测：

1	-Djsse.enableSNIExtension=false

1. 1. 1. 当所有其他方法都失败时

如果您已经阅读、理解并尝试了此页面上的所有故障排除提示，但仍然遇到问题，请执行 SSL 跟踪并将其附加到 CAS 邮件列表的帖子中。当设置了以下系统属性 javax.net.debug=ssl 时，会将 SSL 跟踪写入 STDOUT。下面是一个示例，说明如何在 Tomcat servlet 容器中执行此操作。

Tomcat 脚本setenv.sh 如下：

# Uncomment the next 4 lines for custom SSL keystore# used by all deployed applications# KEYSTORE="$HOME/path/to/custom.keystore"# CATALINA_OPTS=$CATALINA_OPTS" -Djavax.net.ssl.keyStore=$KEYSTORE"# CATALINA_OPTS=$CATALINA_OPTS" -Djavax.net.ssl.keyStoreType=BKS"# CATALINA_OPTS=$CATALINA_OPTS" -Djavax.net.ssl.keyStorePassword=changeit"

# Uncomment the next 4 lines to allow custom SSL trust store# used by all deployed applications# TRUSTSTORE="$HOME/path/to/custom.truststore"# CATALINA_OPTS=$CATALINA_OPTS" -Djavax.net.ssl.trustStore=$TRUSTSTORE"# CATALINA_OPTS=$CATALINA_OPTS" -Djavax.net.ssl.trustStoreType=BKS"# CATALINA_OPTS=$CATALINA_OPTS" -Djavax.net.ssl.trustStorePassword=changeit"

# Uncomment the next line to print SSL debug trace in catalina.out# CATALINA_OPTS=$CATALINA_OPTS" -Djavax.net.debug=ssl"

export CATALINA_OPTS