配置 TeamCity 服务器的 HTTPS 访问
HTTPS 协议使用加密来确保计算机网络上的服务器 - 客户端通信的安全性。 如果您的 TeamCity 服务器可以通过公共网络地址访问,我们强烈建议您配置 HTTPS 连接,以大幅提升安全性。
为了配置安全的 HTTPS 访问,您需要一个证书。 您可以手动获取并加载它,或者让 TeamCity 通过 Let's Encrypt 自动发放有效证书。
warning
Let's Encrypt是一个非盈利的证书颁发机构(CA),它提供被所有现代浏览器信任的TLS证书。 TeamCity 可以联系此 CA,以自动为您的 TeamCity 服务器域和(如果已配置)artifacts isolation domain颁发证书。
请参考此文章以了解 Let's Encrypt 如何验证您的域名所有权并发放证书:工作原理。
note
这个选项对 多节点设置 不可用。 反而在代理端配置证书。 请参阅您的代理服务器文档以获取更多信息。
证书类型: 单域名或多域名 SAN 证书
证书有效期: 90 天
自动续订: 到期前 30 天
验证类型: HTTP-01
导航至 Administration | HTTPS Settings,然后选择 从 Let's Encrypt 获取 选项。 由于 Let's Encrypt 需要访问特定的端点以验证您拥有服务器和工件隔离域,因此这些域必须可以通过互联网访问。 如果您的 server URL 指向一个 "localhost" 地址,您将会看到相应的错误信息。
点击相应的链接阅读 Let's Encrypt 服务条款,然后点击 同意并获取。
在 CA 验证您的身份后,有效的证书将自动颁发和安装。
选择所需的 redirect mode。
在 TeamCity 设置中,将您的 artifacts isolation URL 和 server URL 从 "http://..." 更新为 "https://..."。 TeamCity 显示 "域隔离工件 URL 使用 HTTP" 和 "服务器根 URL 使用 HTTP" 健康报告 作为此步骤的提醒。
Let's Encrypt 预计在 http://<your_domain>:80/.well-known/acme-challenge
位置找到挑战文件。 为了提供这些文件,TeamCity 需要访问 80 端口。
如果您的服务器运行在不同的端口(例如,8111),TeamCity 会尝试在端口80上打开一个自定义套接字。 此插槽在挑战验证结束后关闭(无论结果如何)。
如果您的服务器运行在 80 端口上,TeamCity 会尝试直接提供挑战文件。 您无需停止或重新配置您的 TeamCity 服务器。
由于 TeamCity 通过启动服务器的同一用户来应对挑战并打开套接字,如果该用户无法访问端口 80,这两种方法可能都会失败。
如果 Let's Encrypt 无法验证域名所有权并颁发证书,TeamCity 会暂停此过程,并显示文本文件内容和路径。

为了发放证书,请尝试以下操作:
点击 Cancel,确保端口80对当前用户可用且可访问,然后重试 automatic fetch。
请不要点击 Cancel,而应手动将所需的挑战文件放置在给定的位置下。 当完成后,返回至 Administration | HTTPS Settings 页面,然后点击 继续。
Let's Encrypt 发布的证书有效期为90天。 TeamCity 尝试在证书过期前 30 天自动更新证书。 您可以通过 teamcity.https.close.expiration.threshold.<units>=value
internal property 设置不同的阈值:
teamcity.https.close.expiration.threshold.minutes=60
teamcity.https.close.expiration.threshold.days=40
如果 TeamCity 无法重新发出证书,那么 健康报告 中将显示相应的消息。 如果 TeamCity 无法自动完成,您需要手动更新证书。
如果您不希望让 TeamCity 从 Let's Encrypt 请求证书,那么请获取并手动上传 SSL 证书和私有 RSA 或 ECC 密钥。
证书必须是一个
.pem
文件。私钥必须采用
PKCS#1
(仅适用于 RSA 密钥)或PKCS#8
(RSA 和 ECC 密钥)格式,并且不能被加密。tip
如果您的密钥有密码,您可以利用 OpenSSL 来删除它:
openssl pkcs8 -topk8 -nocrypt -in [original.key] -out [new.key]
以下示例说明了如何使用 OpenSSL 终端命令生成以下文件:
私有椭圆曲线 (EC) 密钥,以 PKCS#8 格式表示
PEM 格式的公钥
预定义过期日期的自签名证书
# Generate a private EC key
openssl ecparam -name prime256v1 -genkey -noout -out private-eckey.pem
# Generate a corresponding public key
openssl ec -in private-eckey.pem -pubout -out public-key.pem
# Create a self-signed certificate
openssl req -new -x509 -key private-eckey.pem -out cert.pem -days 360
# Convert your EC private key to the PKCS#8 format
openssl pkcs8 -topk8 -nocrypt -in private-eckey.pem -out private-ec-pkcs8.key
一旦您获得了证书和私钥:
前往 Administration | HTTPS Settings。
选择 Upload 选项。
上传这两个文件。
选择 HTTPS 连接的端口。 默认情况下,TeamCity 建议使用 443 端口。 您可能需要更改端口号。
tip
确保指定的端口未被占用,且 TeamCity 服务器进程可以访问它。 例如,如果您出于安全原因在 Unix 下用一个非特权帐户运行 TeamCity 服务器,Unix 仅允许 root 用户访问 1024 以下的端口。
点击 应用文件,让 TeamCity 检查服务器 URL 是否可访问。 如果访问被拒绝,TeamCity 会显示一个错误并忽略无效的设置。
保存您的设置。
选择所需的 redirect mode。
note
在多节点服务器配置中,每个节点的设置都是独立的。 将证书分别上传到每个节点中。
TeamCity 会跟踪您的证书的有效性,并在过期日期前 30 天开始显示警告。 在证书过期后,将会显示一个错误。
您也可以使用脚本来自动配置 HTTPS 设置,脚本应包含以下内容:
curl '<TeamCity_URL>/app/https/settings/uploadCertificate' -X POST -H 'Accept: application/json' -H 'Authorization: Bearer TOKEN' -F certificate=@PATH_CERT -F key=@PATH_KEY -F port=XXXX'`
例如:
curl -X POST '
http://localhost:8111/app/https/settings/uploadCertificate' -H '
Accept:application/json' -H '
Authorization: Bearer aBcDeF.gHiGKLm.NOpQRsTUvWXyZ' -F "
certificate=@./cert.pem" -F "
key=@./private-15-days.key" -F "
port=6942"
这里的 TOKEN
是您的 个人令牌,它具有 更改 HTTPS 设置
权限。
如果您的 TeamCity 服务器在一个 Linux 容器中运行,请在 docker run
/ podman run
命令中添加 -p 443:8443
参数。 这个参数允许 TeamCity 将容器内的非特权端口 8443 映射到默认的 HTTPS 端口 443。 因此,TeamCity 将可以在不以 root 用户(否则需要访问特权端口 443)运行服务器的情况下访问。
在您正确配置了 HTTPS 访问之后,TeamCity 允许您选择以下重定向选项之一:

禁用(默认)。 所有客户端都可以使用 HTTP 和 HTTPS 请求。 这是最不安全的选项。
仅浏览器请求。 所有通过浏览器连接的用户必须使用 HTTPS。 代理和自定义脚本的请求可以使用 HTTP。
如果您拥有安全的、独立的基础设施,或者只有本地代理连接到 TeamCity 服务器,那么这个选项可能适合您。
在过渡期也很有帮助,您可以配置您的代理通过 HTTPS 连接到 TeamCity。
启用所有请求。 所有 TeamCity 客户端都被重定向到 HTTPS。
tip
在启用此选项之前,请确保您已在所有代理上将 URL 更新为 HTTPS。 否则,使用 HTTP 的代理可能无法连接到服务器。
您可以在 Agents | Overview | Parameters Report 页面使用
teamcity.serverUrl
进行过滤,查看代理用于连接到 TeamCity 服务器的 URL。warning
这个选项可能会导致在您删除上传的证书后,无法完全访问您的 TeamCity 服务器。
TeamCity 默认使用的与客户端通信的协议是 TLS 版本 1.2。
为了设置一份可用协议的列表,或者强制 TeamCity 使用一种特定的协议,添加 teamcity.https.use.protocols
内部属性 并使用常见的 Tomcat 语法将其设置为所需值。 查看此页面的 "protocols" 属性描述以查看可用值:The HTTP Connector。
teamcity.https.use.protocols=TLSv1.3
在您修改此属性后,请重启您的 TeamCity 服务器以使更改生效。

如果您错误地配置了 HTTPS,可能无法登录或遇到其他阻止您回滚这些更改的问题。 在这种情况下,您可以手动编辑位于服务器 / 节点机器的 https-settings.xml 配置文件,该文件位于 data_directory/config/_https
文件夹下。
如果启用了 HTTPS 访问,TeamCity 将添加带有一年有效期的 Strict Transport Security(HSTS)头。 因此,您的浏览器开始实施 HTTPS 协议,并阻止您访问同一域名上托管的 HTTP 资源。
这种行为是有意为之且无法被禁用。 如果您需要通过 HTTP URL 访问内部资源,可以考虑将这些资源放在代理服务器后面,并为它们配置 HTTPS 访问。 作为一种应对方法,当您需要访问 HTTP URL 时,您也可以手动在浏览器中删除 HSTS 设置。
感谢您的反馈!