Certificate Management Service：在Jetty伺服器安裝SSL認證（Linux）

適用範圍

開始配置前，確保滿足以下條件：

步驟一：下載SSL認證

1. 進入SSL認證管理頁面，在目標認證操作列單擊更多進入認證詳情頁面，然後在下載頁簽中下載伺服器類型為JKS的認證。

   說明

   JKS是Java專用的密鑰庫格式，適合主要在Java環境下使用。

2. 解壓後的檔案包含認證檔案（.jks尾碼，且含完整憑證鏈結）和認證密碼檔案（jks-password.txt）。

步驟三：配置系統與網路環境

此步驟確保應用有權監聽指定連接埠，並且安全性群組和防火牆允許外部流量訪問。

1. 在伺服器終端執行以下命令，檢測443連接埠的開放情況：

   RHEL/CentOS

   command -v nc > /dev/null 2>&1 || sudo yum install -y nc
   # 請將以下的 <當前伺服器的公網 IP> 替換為當前伺服器的公網 IP
   sudo ss -tlnp | grep -q ':443 ' || sudo nc -l 443 & sleep 1; nc -w 3 -vz <當前伺服器的公網 IP> 443

   如果輸出 Ncat: Connected to <當前伺服器公網 IP>:443，則表明443連接埠已開放。否則需在安全性群組和防火牆中開放443連接埠。

   Debian/Ubuntu

   command -v nc > /dev/null 2>&1 || sudo apt-get install -y netcat
   # 請將以下的 <當前伺服器的公網 IP> 替換為當前伺服器的公網 IP
   sudo ss -tlnp | grep -q ':443 ' || sudo nc -l -p 443 & sleep 1; nc -w 3 -vz <當前伺服器的公網 IP> 443

   若輸出 Connection to <當前伺服器公網 IP> port [tcp/https] succeeded! 或 [<當前伺服器公網 IP>] 443 (https) open，則表明443連接埠已開放。否則需在安全性群組和防火牆中開放443連接埠。

2. 在安全性群組配置開放443連接埠。

   重要

   若您的伺服器部署在雲平台，請確保其安全性群組已開放 443 連接埠 (TCP)，否則外部無法訪問服務。以下操作以阿里雲 ECS 為例，其他雲平台請參考其官方文檔。

   進入Elastic Compute Service執行個體，單擊目標執行個體名稱進入執行個體詳情頁面，請參考添加安全性群組規則，在安全性群組中添加一條授權策略為允許、協議類型為 TCP、目的連接埠範圍為 HTTPS(443)、授權對象為任何位置(0.0.0.0/0)的規則。

3. 在防火牆中開放443連接埠。

   執行以下命令，識別系統當前的防火牆服務類型：

   if command -v systemctl >/dev/null 2>&1 && systemctl is-active --quiet firewalld; then
       echo "firewalld"
   elif command -v ufw >/dev/null 2>&1 && sudo ufw status | grep -qw active; then
       echo "ufw"
   elif command -v nft >/dev/null 2>&1 && sudo nft list ruleset 2>/dev/null | grep -q 'table'; then
       echo "nftables"
   elif command -v systemctl >/dev/null 2>&1 && systemctl is-active --quiet iptables; then
       echo "iptables"
   elif command -v iptables >/dev/null 2>&1 && sudo iptables -L 2>/dev/null | grep -qE 'REJECT|DROP|ACCEPT'; then
       echo "iptables"
   else
       echo "none"
   fi

   若輸出為 none，則無需進一步操作。否則，請根據輸出的類型（firewalld、ufw、nftables、iptables），執行以下命令開放 443 連接埠：

   firewalld

   sudo firewall-cmd --permanent --add-port=443/tcp && sudo firewall-cmd --reload

   ufw

   sudo ufw allow 443/tcp

   nftables

   sudo nft add table inet filter 2>/dev/null
   sudo nft add chain inet filter input '{ type filter hook input priority 0; }' 2>/dev/null
   sudo nft add rule inet filter input tcp dport 443 counter accept 2>/dev/null

   iptables

   sudo iptables -A INPUT -p tcp --dport 443 -j ACCEPT

   為避免 iptables 規則在系統重啟後失效，請執行以下命令持久化 iptables 規則：

   RHEL/CentOS

   sudo yum install -y iptables-services
   sudo service iptables save

   Debian/Ubuntu

   sudo apt-get install -y iptables-persistent
   sudo iptables-save | sudo tee /etc/iptables/rules.v4 >/dev/null

步驟三：在Jetty伺服器安裝SSL認證

1. 建立並進入 Jetty 的工作目錄（$JETTY_BASE），在Jetty的工作目錄下建立一個用於存放認證的cert目錄。

   重要

   將 Jetty 的安裝目錄（$JETTY_HOME）與工作目錄（$JETTY_BASE）分離，便於日後升級和維護。

   # 樣本：假設 Jetty 安裝在 /usr/local/jetty，應用和配置放在 /var/www/my-app
   export JETTY_HOME=/usr/local/jetty
   export JETTY_BASE=/var/www/my-app
   
   # 建立必要的目錄結構，用於存放認證檔案、網站代碼資源等。
   mkdir -p $JETTY_BASE/cert
   mkdir -p $JETTY_BASE/webapps
   
   # 後續操作建議在 $JETTY_BASE 目錄中進行
   cd $JETTY_BASE

2. 將認證檔案上傳至建立完成的cert目錄。

   說明

   您可以使用遠程登入工具的本地檔案上傳功能來上傳檔案。例如PuTTY、Xshell或WinSCP等工具。如果您使用的是阿里雲Elastic Compute Service，關於上傳檔案的具體操作，請參見上傳或下載檔案。

3. 啟用 Jetty 的 ssl 模組，並指定認證資訊。

   1. 在 $JETTY_BASE 目錄下，執行以下命令初始化 ssl 模組。

      # 該命令會在 $JETTY_BASE/start.d/ 目錄下產生 ssl.ini 和 https.ini 設定檔。
      java -jar $JETTY_HOME/start.jar --add-to-start=ssl

   2. 編輯 $JETTY_BASE/start.d/ssl.ini 檔案，填入憑證路徑和密碼。

      # 執行一下命令進入編輯模式，準備填寫認證的相關配置資訊
      vim $JETTY_BASE/start.d/ssl.ini

   3. 找到並修改以下參數，確保它們沒有被 # 注釋。對於從阿里雲下載的 JKS 認證，keyStorePassword 和 keyManagerPassword 使用相同的密碼。

      # ---------------------------------------
      # SSL Context Factory KeyStore Configuration
      # ---------------------------------------
      # jetty.ssl.keystore.path 已廢棄，請使用 jetty.ssl.keyStorePath
      jetty.ssl.keyStorePath=cert/your_domain.jks
      
      # jetty.ssl.keystore.password 已廢棄，請使用 jetty.ssl.keyStorePassword
      jetty.ssl.keyStorePassword=[jks-password.txt檔案中的密碼]
      
      # jetty.ssl.keymanager.password 已廢棄，請使用 jetty.ssl.keyManagerPassword
      jetty.ssl.keyManagerPassword=[jks-password.txt檔案中的密碼]

步驟四：重新啟動Jetty服務

在 $JETTY_BASE 目錄下，啟動 Jetty 伺服器。

# 進入Jetty工作目錄。
cd $JETTY_BASE

# 重啟服務。
sudo java -jar $JETTY_HOME/start.jar

步驟五：驗證SSL是否安裝成功

安裝或更新認證後，認證未生效或 HTTPS 無法訪問

常見原因如下：

• 伺服器安全性群組或防火牆未開放 443 連接埠。請參見配置系統與網路環境。

• 認證的綁定網域名稱未包含當前訪問的網域名稱。請參見網域名稱匹配。

• 修改 Jetty 設定檔後，未重啟Jetty服務。具體操作可參見重新啟動Jetty服務。

• 認證檔案未正確替換，或 Jetty 配置未正確指定憑證路徑。請檢查 Jetty 設定檔和所用認證檔案是否為最新且有效。

• 網域名稱已接入 CDN、SLB 或 WAF 等雲產品，但未在相應產品中安裝認證。請參閱流量經過多個雲產品時認證的部署位置完成相關操作。

• 當前網域名稱的 DNS 解析指向多台伺服器，但認證僅在部分伺服器上安裝。需分別在每個伺服器中安裝認證。

如何更新（替換）Jetty 中已安裝的 SSL 憑證

請先備份伺服器上原有的認證檔案（.jks，以及.txt檔案），然後登入數位憑證管理服務控制台，下載新的認證檔案，並上傳到目標伺服器覆蓋原有檔案（確保路徑和檔案名稱一致）。最後，重啟Jetty服務，使新認證生效。

啟動時報錯：“Address already in use”或“連接埠已被佔用”？

這表示 443 連接埠已被其他程式監聽。使用 sudo ss -tlnp | grep :443 或 sudo lsof -i:443 命令尋找佔用連接埠的進程，並將其停止。常見的佔用程式有 Nginx、Apache 或之前未正常關閉的測試命令。

啟動時報錯：“Permission denied”？

在 Linux 系統中，綁定 1024 以下的連接埠需要 root 許可權。確認已使用 sudo 來啟動 Jetty。在生產環境中，不推薦直接使用 root 使用者運行服務，更安全的做法是使用 setcap 授予 Java 程式綁定低位連接埠的許可權（例如：sudo setcap 'cap_net_bind_service=+ep' /path/to/your/java），或將 Jetty 置於反向 Proxy（如 Nginx）之後。