设置名称和 TLS
你的 Excubius 服务器响应一个主要名称和任意数量的别名,并以六种模式之一提供 HTTPS,从 Let's Encrypt 证书到在其前端终止 TLS 的网关。安装程序中的回答设置初始值。之后你在控制台中更改它们,更改会在一分钟内生效,无需重启。本指南说明如何选择和更改这些设置。
开始之前
- 若要在控制台中更改名称和 TLS,你需要 Super admin(超级管理员)角色。
- 若要改为在服务器上操作,你需要 SSH 访问权限和
sudo,以便切换为服务账户(默认为excubius)。 - 先创建 DNS 记录。每个名称都必须能从用户使用 Excubius 的位置解析到服务器,或解析到服务器前端的网关。
三种名称
| 名称 | 说明 |
|---|---|
| Primary name | 公共地址中的主机名,例如 monitoring.ciguapa.example。Excubius 在 Slack 消息和 Jira 问题中发送的链接使用它。登录始终在这个名称上进行:打开别名的用户会被转到主要名称登录 |
| Aliases | 用户可以打开的其他名称,例如当客户的 DNS 区域无法访问时,你控制的域中的 monitoring.areito.example。服务器响应所有这些名称 |
| Names in the certificate | 为其申请证书的名称。默认包含所有名称,新增的别名会自动加入。取消勾选证书无法覆盖的名称,例如你无法控制其 DNS 的名称 |
一台服务器最多可以有 100 个名称。
为 Microsoft Entra ID 和 Google 登录注册的重定向地址以主要名称开头。更改主要名称时,请先更新这些地址;请参阅设置登录提供商。
选择模式
| 控制台中的模式 | 安装程序中的回答 | 适用情形 |
|---|---|---|
| Let's Encrypt over HTTP | letsencrypt | 证书中的每个名称都在公共 DNS 中指向这台服务器,并且 80 端口可从 Internet 访问,无论是直接访问还是通过 NAT 或网关转发 |
| Let's Encrypt over DNS | letsencrypt-dns | 你拥有这些名称所在 DNS 区域的 API 凭据。服务器不需要能从 Internet 访问,因此这是通过 VPN 访问的服务器的常用选择 |
| Self-signed | selfsigned | 任何地方。在用户的计算机和手机上信任该证书之前,浏览器会显示警告 |
| Your own certificate | custom | 你的组织自行颁发证书。你粘贴证书链和密钥,并在它们过期之前更换 |
| Gateway in front | gateway | 负载均衡器或反向代理(例如 Azure Application Gateway 或 Front Door)终止 TLS 并转发纯 HTTP。系统会遵从它的 X-Forwarded-Proto 标头 |
| Plain HTTP | later | 首次测试,或你完全信任的网络。任何内容都不加密 |
在控制台中更改名称或模式
- 打开 Settings 并选择 Server and certificates。你也可以从 Settings › Instance 通过 Server names and HTTPS 进入。
- 在 Names 下,检查 Primary name。若要添加别名,请输入它并选择 Add;若要删除别名,请选择它旁边的 Remove。
- 在 HTTPS 下,选择模式并填写它要求的内容。下面的各节分别说明每种模式。
- 在 Names in the certificate 下,取消勾选证书无法覆盖的名称。
- 选择 Apply。页面会显示 Saved. The certificate service is applying it.
在 Current certificate 下,你可以看到当前提供的证书:颁发者、名称、Valid until、Last attempt 及其结果,以及 Next check。如果尝试失败,What went wrong 会给出说明。
每次更改在保存之前都会经过检查,并写入审核日志。
通过 HTTP 使用 Let's Encrypt
输入 E-mail for the Let's Encrypt account。应用之前,请确保证书中的每个名称都在公共 DNS 中解析到服务器,并且 80 端口可从 Internet 访问。不可能公开的名称(例如 IP 地址,或以 .local、.internal、.corp 结尾的名称)会被拒绝:请取消勾选它,或改用自签名证书。
通过 DNS 使用 Let's Encrypt
-
输入 E-mail for the Let's Encrypt account。
-
选择这些名称所在区域的 DNS provider。如果你的提供商不在列表中,请选择 Other (acme.sh dnsapi id) 并输入它的 acme.sh
dnsapi标识符。 -
在 API credentials 下,输入提供商读取的值。控制台会列出每个提供商所需的值:
提供商 dnsapi标识符变量 Cloudflare dns_cfCF_Token,CF_Account_IDDreamHost dns_dreamhostDH_API_KEYAzure DNS dns_azureAZUREDNS_SUBSCRIPTIONID,AZUREDNS_TENANTID,AZUREDNS_APPID,AZUREDNS_CLIENTSECRETAmazon Route 53 dns_awsAWS_ACCESS_KEY_ID,AWS_SECRET_ACCESS_KEYGoDaddy dns_gdGD_Key,GD_SecretDigitalOcean dns_dgonDO_API_KEYGandi dns_gandi_livednsGANDI_LIVEDNS_TOKENHetzner dns_hetznercloudHETZNER_TOKENIONOS dns_ionosIONOS_PREFIX,IONOS_SECRETLinode (Akamai) dns_linode_v4LINODE_V4_API_KEYNamecheap dns_namecheapNAMECHEAP_USERNAME,NAMECHEAP_API_KEY,NAMECHEAP_SOURCEIPOVHcloud dns_ovhOVH_END_POINT,OVH_AK,OVH_AS,OVH_CKPorkbun dns_porkbunPORKBUN_API_KEY,PORKBUN_SECRET_API_KEY -
也可以将 Let's Encrypt server 设置为 Staging,以便在不触及 Let's Encrypt 速率限制的情况下进行演练。浏览器不信任 Staging 证书;一切正常后请切换回 Production。
凭据值是只写的:它们加密存储,之后不再显示。若要在编辑设置时保留已存储的值,请将对应字段留空。
自签名
无需输入任何内容。证书的有效期为 825 天,续订方式与其他证书相同。若要消除浏览器警告,请选择 Download the certificate,并将其作为受信任的证书安装到使用该服务器的计算机和手机上。
你自己的证书
以 PEM 格式粘贴 Certificate chain(服务器证书在前),并以 PEM 格式粘贴不带密码的 Private key。密钥必须是 2048 位或更长的 RSA,或者是 ECDSA。如果证书已过期、未覆盖服务器的名称,或密钥与证书不匹配,控制台会拒绝该证书。请在证书过期之前更换这两项;Excubius 不会为你续订。
前端网关
无需输入任何内容。请将网关配置为把纯 HTTP 转发到服务器的 80 端口,并发送 X-Forwarded-Proto 标头。
续订
Let's Encrypt 证书和自签名证书会自动续订。证书服务每天检查当前证书,并在剩余 30 天或更短时间时续订。无需在服务器上设置任何计时器。
- 失败的尝试绝不会删除可用的内容。系统会继续提供之前的证书或纯 HTTP;错误会连同下次重试时间一起显示在页面上,首次重试在 15 分钟后,之后间隔翻倍,最长为一天。
- 设置更改后会立即尝试。
- Renew now 会立即请求新证书。
- Use self-signed now 会切换到自签名证书,这是在 Let's Encrypt 暂时无法工作时快速启用 HTTPS 的办法。
只要请求通过 HTTPS 到达,会话 Cookie 就会标记为 Secure,因此更改模式无需重启。请将配置文件中的 COOKIE_SECURE 留空;它只会强制该行为固定为开或关。
地址 /healthz 和 /heartbeat 在所有模式下都通过纯 HTTP 响应,因此在你更改 TLS 期间,外部监视器仍能继续工作。
从服务器更改 TLS
当控制台无法访问时(例如证书已损坏,浏览器拒绝打开页面),请在服务器上更改相同的设置。该脚本与控制台使用相同的检查和相同的审核日志。
-
通过 SSH 连接并切换为服务账户:
sudo -iu excubius -
显示当前设置和证书:
/opt/excubius/current/scripts/enable-tls.sh --status -
更改你需要的内容。例如,切换到自签名证书:
/opt/excubius/current/scripts/enable-tls.sh --mode selfsigned或者通过 Cloudflare 使用 Let's Encrypt over DNS,包含两个名称,并且只为第二个名称申请证书。凭据从标准输入以
KEY=VALUE行的形式读取:/opt/excubius/current/scripts/enable-tls.sh --mode letsencrypt-dns \--email ops@areito.example --dns-provider dns_cf \--names "monitoring.ciguapa.example monitoring.areito.example" \--cert-names monitoring.areito.example < credentials.txt -
若要立即续订,请运行
enable-tls.sh --renew。
如果你选择了其他安装目录,请替换 /opt/excubius。运行 enable-tls.sh --help 可查看所有选项,包括 --staging 和 --production。你自己的证书只能从控制台上传。
使用安装程序更改回答
sudo ./install.sh --reconfigure 会再次询问所有问题。此时你给出的 TLS 回答会应用到正在运行的平台,效果与你在控制台中更改它们相同。