事後分析：在用戶登入時發生意外的 500 錯誤

總結#

2024 年 7 月 18 日，Logto Cloud 的認證服務出現 500 內部伺服器錯誤，引致服務中斷。

• 受影響用戶：所有嘗試進行認證的 Cloud 用戶
• 受影響地區：歐洲和美國
• 嚴重性：重大，影響用戶登入體驗

根本原因#

在最近的 Cloud 部署期間，數據庫架構的嚴重變更導致登入體驗 API 在過渡測試環境和生產環境時失敗。

時間線#

• 2024-07-18 08:57 (UTC)：更新部署至 Logto Cloud
• 2024-07-18 09:28 (UTC)：第一位用戶報告 500 錯誤
• 2024-07-18 09:31 (UTC)：開發團隊確認問題並開始調查
• 2024-07-18 09:32 (UTC)：問題自動解決
• 2024-07-18 09:40 (UTC)：確認問題根源

事件分析#

數據庫的嚴重變更是什麼，以及為什麼發生？#

我們目前正在開發一個名為「Bring your UI」的新功能，允許用戶透過自己的網頁自定義 Logto 的登入體驗。此功能需要在 sign-in-exp 表中新增一個欄位來存儲自定義 UI 設定。

由於開發過程中的一些需求變更，功能發布被延遲，但第一部分的架構變更早在幾週前便已部署至生產環境，儘管尚未使用。此拉請中引入了數據庫欄位的更新。

不幸的是，這一變更並不相容，導致來自舊程式碼的 API 請求在與新數據庫通訊時失敗。

我們如何部署新的 Logto Cloud 版本？#

在部署新的 Logto Cloud 版本時，我們首先將其部署至測試環境，然後交換測試環境和生產環境。 具體過程如下：

1. 運行數據庫更改腳本並更新數據庫。
2. 將新源代碼部署到測試伺服器。
3. 運行測試伺服器並進行測試。
4. 交換測試和生產伺服器，讓「測試」成為「生產」，允許用戶無中斷地使用新版本。

然而，兩個環境共用同一數據庫，整個過程需要時間。因此在從數據庫更新到環境交換的時間窗口內，線上用戶仍然處於生產環境中的舊代碼，但試圖與新數據庫通訊。

這是事件的根本原因，也是為什麼問題在 35 分鐘內自動解決的原因。

為什麼這在代碼審查過程中沒有被解決？#

我們確實有一個 CI 任務來檢查數據庫變更的向後兼容性。然而，先前並未要求在合併 PR 前通過 CI 檢查。這是因為大多數時候開發階段通常在幾次短衝刺中完成，架構變更的首部和第二部分通常會在同一發佈階段中包含。

這次，功能發布被延遲，將架構變更分布到兩個版本中。開發者認為 CI 錯誤是預期的，並告知審閱者這不應阻止 PR 合併。

交流的差距無疑存在，最終 PR 在未提供任何必要的向後兼容支持下合併。

學到的課題#

• 在進行數據庫架構的重大變更時，我們應該總是考慮舊版本源代碼的向後兼容性。
• 當更改數據庫欄位時，我們應該避免直接在架構中更改，而是使用棄用和遷移方法。
• 開發人員應更清楚發佈流程和時間表。

糾正和預防措施#

• ✅ 現在在合併包含架構變更的 PR 前，數據庫向後兼容性的 CI 檢查必須通過。
• ✅ 強調團隊內向後兼容性的重點。