在Spring Boot應用安裝SSL認證（Linux） - Certificate Management Service

本文介紹如何在 Spring Boot 應用中直接配置 SSL 憑證以啟用 HTTPS。

適用範圍

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

認證狀態：已擁有由權威機構簽發的 SSL 憑證。若認證即將到期或已到期，請先續約SSL認證。
網域名稱匹配：確保認證能夠匹配所有需保護的網域名稱。如需添加或修改，請參見追加和更換網域名稱。
- 精確網域名稱：僅對指定網域名稱生效。
  - example.com 僅對 example.com 生效。
  - www.example.com 僅對 www.example.com 生效。
- 萬用字元網域名稱：僅對其一級子網域名稱生效。
  - *.example.com 對 www.example.com、a.example.com 等一級子網域名稱生效。
  - *.example.com 對根網域名稱 example.com 和多級子網域名稱 a.b.example.com 不生效。
說明
如需匹配多級子網域名稱，綁定網域名稱中需包含該網域名稱（如 a.b.example.com），或包含相應的萬用字元網域名稱（如 *.b.example.com）。
伺服器許可權：需要使用 root 賬戶或一個具有 sudo 許可權的賬戶。
網域名稱解析：網域名稱已配置解析記錄並解析至伺服器的公網 IP。
環境依賴：伺服器已安裝 Java 8 或更高版本。

操作步驟

步驟一：準備認證檔案

進入SSL認證管理頁面，在目標認證操作列單擊更多進入認證詳情頁面，然後在下載頁簽中下載伺服器類型為JKS的認證。
說明
Spring Boot支援JKS和PKCS12（.pfx）格式。本文以JKS為例。解壓後將得到一個認證檔案（如 domain.jks）和一個密碼檔案（jks-password.txt）。
將解壓後的認證檔案（.pfx或.jks）和密碼檔案（.txt）上傳至伺服器，並存放在一個安全的外部目錄（/etc/ssl/myapp）。
重要
嚴禁將認證或私密金鑰檔案放置在 src/main/resources 目錄下。這樣做會將敏感密鑰打包到應用交付物（如 JAR/WAR 檔案）中，極易導緻密鑰泄露。
您可以使用遠程登入工具的本地檔案上傳功能來上傳檔案。例如PuTTY、Xshell或WinSCP等工具。如果您使用的是阿里雲Elastic Compute Service，關於上傳檔案的具體操作，請參見上傳或下載檔案。

步驟二：配置Spring Boot應用

說明

將認證密碼等敏感資訊寫入程式碼在代碼或設定檔中是危險的。應通過環境變數或外部安全檔案進行管理。

通過export命令設定環境變數。

# 從之前下載的密碼檔案中擷取密碼
export SSL_KEYSTORE_PASSWORD='your_secure_password'
# 如果私密金鑰密碼不同，同樣設定
export SSL_KEY_PASSWORD='your_key_password'

按照以下樣本和說明配置application.properties或application.yml檔案。

說明

本文以Spring Boot 3.4.10版本為例。

application.properties

# 監聽443連接埠
server.port=443

# --- SSL配置 ---
# 認證檔案路徑，使用'file:'首碼指定外部絕對路徑
server.ssl.key-store=file:/etc/myapp/ssl/keystore.p12
# 認證密鑰庫類型
server.ssl.key-store-type=PKCS12
# 認證別名，通常在產生JKS/P12檔案時指定
server.ssl.key-alias=mycert

# --- 安全配置：密碼管理 ---
# 從環境變數讀取密碼，避免寫入程式碼在設定檔中
server.ssl.key-store-password=${SSL_KEYSTORE_PASSWORD}
# 如果私密金鑰密碼與密鑰庫密碼不同，也從環境變數讀取
server.ssl.key-password=${SSL_KEY_PASSWORD}

# --- 安全配置：TLS協議與加密套件 ---
# 啟用安全的TLS協議版本
server.ssl.enabled-protocols=TLSv1.2,TLSv1.3
# 配置推薦的強加密套件
server.ssl.ciphers=TLS_AES_256_GCM_SHA384,TLS_CHACHA20_POLY1305_SHA256,TLS_AES_128_GCM_SHA256,ECDHE-RSA-AES256-GCM-SHA384,ECDHE-RSA-AES128-GCM-SHA256

# 啟用HTTP/2以提升效能
server.http2.enabled=true

application.yml

server:
  port: 443 # 監聽443連接埠

  ssl:
    # --- SSL配置 ---
    # 認證檔案路徑，使用'file:'首碼指定外部絕對路徑
    key-store: file:/etc/myapp/ssl/keystore.p12
    # 認證密鑰庫類型
    key-store-type: PKCS12
    # 認證別名，通常在產生JKS/P12檔案時指定
    key-alias: mycert

    # --- 安全配置：密碼管理 ---
    # 從環境變數讀取密碼，避免寫入程式碼在設定檔中
    key-store-password: ${SSL_KEYSTORE_PASSWORD}
    # 如果私密金鑰密碼與密鑰庫密碼不同，也從環境變數讀取
    key-password: ${SSL_KEY_PASSWORD}

    # --- 安全配置：TLS協議與加密套件 ---
    # 啟用安全的TLS協議版本
    enabled-protocols: TLSv1.2,TLSv1.3
    # 配置推薦的強加密套件
    ciphers:
      - TLS_AES_256_GCM_SHA384
      - TLS_CHACHA20_POLY1305_SHA256
      - TLS_AES_128_GCM_SHA256
      - ECDHE-RSA-AES256-GCM-SHA384
      - ECDHE-RSA-AES128-GCM-SHA256

  # 啟用HTTP/2以提升效能
  http2:
    enabled: true

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

確保安全性群組和防火牆允許外部流量訪問。

在伺服器終端執行以下命令，檢測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連接埠。

在安全性群組配置開放443連接埠。
重要
若您的伺服器部署在雲平台，請確保其安全性群組已開放 443 連接埠 (TCP)，否則外部無法訪問服務。以下操作以阿里雲 ECS 為例，其他雲平台請參考其官方文檔。
進入Elastic Compute Service執行個體，單擊目標執行個體名稱進入執行個體詳情頁面，請參考添加安全性群組規則，在安全性群組中添加一條授權策略為允許、協議類型為 TCP、目的連接埠範圍為 HTTPS(443)、授權對象為任何位置(0.0.0.0/0)的規則。

在防火牆中開放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

步驟四：啟動應用

進入Spring Boot專案根目錄，請根據構建工具，在專案根目錄下執行相應命令以重啟應用。

開發/測試環境 (使用構建外掛程式)

Maven
```
mvn spring-boot:run
```
Gradle
```
gradle bootRun
```

生產環境（作為獨立JAR包運行）

生產環境通常將應用打包為.jar檔案運行。您需要先停止舊的進程，然後使用java -jar命令重新啟動。

# 1. 找到並停止正在啟動並執行應用進程 (PID)
# ps -ef | grep your-app-name.jar
# kill <PID>
#
# 2. 重新啟動應用，若需增加相關 JVM 參數，請在&之前繼續補充。
nohup java -jar /path/to/your-app-name.jar &

說明

重啟後，請檢查應用日誌，確保SSL認證已成功載入且服務在HTTPS連接埠正常啟動。

步驟五：驗證部署結果

請通過 HTTPS 訪問您已綁定認證的網域名稱（如 https://yourdomain.com，yourdomain.com 需替換為實際網域名稱）。
若瀏覽器地址欄顯示安全鎖表徵圖，說明認證已成功部署。如訪問異常或未顯示安全鎖，請先清除瀏覽器緩衝或使用無痕（隱私）模式重試。
Chrome 瀏覽器自 117 版本起，地址欄中的已被新的替代，需單擊該表徵圖後查看安全鎖資訊。

說明

如仍有問題，請參考常見問題進行排查。

應用於生產環境

在生產環境部署時，遵循以下最佳實務可提升安全性、穩定性和可維護性：

使用非管理員權限使用者運行：
為應用建立專用的、低許可權的系統使用者，切勿使用擁有管理員權限的賬戶運行應用。
說明
建議使用網關層配置 SSL的方案，即將認證部署在Server Load Balancer或Nginx等反向 Proxy上，由其終結 HTTPS 流量，再將解密後的 HTTP 流量轉寄到後端應用。
憑證外部化管理：
切勿將密碼等敏感資訊寫入程式碼在代碼或設定檔中。使用環境變數、Vault 或雲端服務商提供的Key Management Service來注入憑證。
啟用 HTTP 到 HTTPS 強制跳轉：
確保所有通過 HTTP 訪問的流量都被自動重新導向到 HTTPS，防止中間人攻擊。
配置現代 TLS 協議：
在伺服器配置中禁用老舊且不安全的協議（如 SSLv3, TLSv1.0, TLSv1.1），僅啟用 TLSv1.2 和 TLSv1.3。
認證監控與自動續期：
建議在認證部署完成後，為網域名稱開啟網域名稱監控功能。阿里雲將自動檢測認證有效期間，並在認證到期前發送提醒，協助您及時續期，避免服務中斷。具體操作請參見購買並開啟公網網域名稱監控。

常見問題

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

常見原因如下：

伺服器安全性群組或防火牆未開放 443 連接埠。請參見配置系統與網路環境。
認證的綁定網域名稱未包含當前訪問的網域名稱。請參見網域名稱匹配。
修改 Spring Boot 設定檔後，未重啟Spring Boot服務。具體操作可參見步驟四：啟動應用。
認證檔案未正確替換，或 Spring Boot 配置未正確指定憑證路徑。請檢查 Spring Boot 設定檔和所用認證檔案是否為最新且有效。
網域名稱已接入 CDN、SLB 或 WAF 等雲產品，但未在相應產品中安裝認證。請參閱流量經過多個雲產品時認證的部署位置完成相關操作。
當前網域名稱的 DNS 解析指向多台伺服器，但認證僅在部分伺服器上安裝。需分別在每個伺服器中安裝認證。

說明

如需進一步排查，請參考：根據瀏覽器錯誤提示解決認證部署問題和 SSL認證部署故障自助排查指南。

如何更新（替換）Spring Boot 應用中已安裝的 SSL 憑證

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