跳至主要内容
版本: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 可從互聯網存取,無論是直接存取,還是經 NAT 或閘道轉發
Let's Encrypt over DNSletsencrypt-dns你有這些名稱所屬 DNS 區域的 API 憑證。伺服器不需要能從互聯網存取,因此這是透過 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。套用之前,請確保證書中的每個名稱都能公開解析到伺服器,並且連接埠 80 可從互聯網存取。無法公開的名稱(例如 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 答案會套用到運行中的平台,效果與你在控制台中變更相同。