跳到主要内容
版本:0.4 · 当前版

设置名称和 TLS

操作指南审阅日期:2026年10月11日
适用于:Excubius 0.4角色: 安装人员(Linux 管理员), 超级管理员
计划Free · Core · Pro · Enterprise部署自托管

你的 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 HTTPletsencrypt证书中的每个名称都在公共 DNS 中指向这台服务器,并且 80 端口可从 Internet 访问,无论是直接访问还是通过 NAT 或网关转发
Let's Encrypt over DNSletsencrypt-dns你拥有这些名称所在 DNS 区域的 API 凭据。服务器不需要能从 Internet 访问,因此这是通过 VPN 访问的服务器的常用选择
Self-signedselfsigned任何地方。在用户的计算机和手机上信任该证书之前,浏览器会显示警告
Your own certificatecustom你的组织自行颁发证书。你粘贴证书链和密钥,并在它们过期之前更换
Gateway in frontgateway负载均衡器或反向代理(例如 Azure Application Gateway 或 Front Door)终止 TLS 并转发纯 HTTP。系统会遵从它的 X-Forwarded-Proto 标头
Plain HTTPlater首次测试,或你完全信任的网络。任何内容都不加密

在控制台中更改名称或模式​

  1. 打开 Settings 并选择 Server and certificates。你也可以从 Settings › Instance 通过 Server names and HTTPS 进入。
  2. 在 Names 下,检查 Primary name。若要添加别名,请输入它并选择 Add;若要删除别名,请选择它旁边的 Remove。
  3. 在 HTTPS 下,选择模式并填写它要求的内容。下面的各节分别说明每种模式。
  4. 在 Names in the certificate 下,取消勾选证书无法覆盖的名称。
  5. 选择 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​

  1. 输入 E-mail for the Let's Encrypt account。

  2. 选择这些名称所在区域的 DNS provider。如果你的提供商不在列表中,请选择 Other (acme.sh dnsapi id) 并输入它的 acme.sh dnsapi 标识符。

  3. 在 API credentials 下,输入提供商读取的值。控制台会列出每个提供商所需的值:

    提供商dnsapi 标识符变量
    Cloudflaredns_cfCF_Token, CF_Account_ID
    DreamHostdns_dreamhostDH_API_KEY
    Azure DNSdns_azureAZUREDNS_SUBSCRIPTIONID, AZUREDNS_TENANTID, AZUREDNS_APPID, AZUREDNS_CLIENTSECRET
    Amazon Route 53dns_awsAWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY
    GoDaddydns_gdGD_Key, GD_Secret
    DigitalOceandns_dgonDO_API_KEY
    Gandidns_gandi_livednsGANDI_LIVEDNS_TOKEN
    Hetznerdns_hetznercloudHETZNER_TOKEN
    IONOSdns_ionosIONOS_PREFIX, IONOS_SECRET
    Linode (Akamai)dns_linode_v4LINODE_V4_API_KEY
    Namecheapdns_namecheapNAMECHEAP_USERNAME, NAMECHEAP_API_KEY, NAMECHEAP_SOURCEIP
    OVHclouddns_ovhOVH_END_POINT, OVH_AK, OVH_AS, OVH_CK
    Porkbundns_porkbunPORKBUN_API_KEY, PORKBUN_SECRET_API_KEY
  4. 也可以将 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​

当控制台无法访问时(例如证书已损坏,浏览器拒绝打开页面),请在服务器上更改相同的设置。该脚本与控制台使用相同的检查和相同的审核日志。

  1. 通过 SSH 连接并切换为服务账户:

    sudo -iu excubius
  2. 显示当前设置和证书:

    /opt/excubius/current/scripts/enable-tls.sh --status
  3. 更改你需要的内容。例如,切换到自签名证书:

    /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
  4. 若要立即续订,请运行 enable-tls.sh --renew。

如果你选择了其他安装目录,请替换 /opt/excubius。运行 enable-tls.sh --help 可查看所有选项,包括 --staging 和 --production。你自己的证书只能从控制台上传。

使用安装程序更改回答​

sudo ./install.sh --reconfigure 会再次询问所有问题。此时你给出的 TLS 回答会应用到正在运行的平台,效果与你在控制台中更改它们相同。