升級 Paideia LMS

本指南涵蓋了如何更新你的 Paideia LMS 版本、如何了解從一個版本到下一個版本發生了什麼變化，以及如何理解 Paideia 的版本系統和相應的文檔更新。

有什麼變化？

Paideia LMS 的最新版本是 v0.6.0。

你可以在 GitHub 和文檔中的 Paideia 變更日誌 中找到所有變化的詳盡列表。升級到每個新主要版本的重要說明都記錄在發布說明中。

升級 Paideia LMS

由於 Paideia LMS 以單一二進制檔案分發，升級很簡單：只需下載新的二進制版本並替換舊的即可。

下載最新版本

1. 下載二進制檔案：從 Paideia 發布頁面 下載適合你平台的二進制檔案（macOS ARM64、Linux ARM64 或 Linux x64）
2. 停止目前的 Paideia 實例（如果作為服務執行）
3. 替換二進制檔案為新版本
4. 重啟 Paideia LMS

資料庫遷移

當你使用新版本啟動 Paideia LMS 時，資料庫遷移會在啟動期間自動應用。這些遷移設計為：

• 向後相容：遷移結構旨在保持與現有資料的相容性
• 非破壞性：資料庫模式更改以保留現有資料的方式應用
• 安全：遷移系統確保整個升級過程中的資料完整性

如果你在遷移過程中遇到任何問題，該過程會自動回滾，你的資料庫將保持其先前狀態。

升級前

我們強烈建議在升級前採取以下預防措施：

1. 每日備份：確保你有 PostgreSQL 資料庫的最近備份
2. 資料庫轉儲：使用 Paideia 的內建資料庫轉儲功能在升級前建立備份
3. 查看發布說明：檢查發布說明中是否有任何破壞性更改或特殊升級說明

# 範例：在升級前建立資料庫轉儲
# 使用 Paideia 的內建轉儲功能
./paideia dump --output backup-$(date +%Y%m%d).sql

# 或直接使用 PostgreSQL 的 pg_dump
pg_dump -h localhost -U postgres paideia_db > backup-$(date +%Y%m%d).sql

零停機升級（滾動升級）

如果你需要完全避免停機，可以執行滾動升級：

1. 部署新二進制檔案到新實例，同時保持舊實例執行
2. 將新實例指向相同的 PostgreSQL 資料庫和 S3 儲存
3. 更新負載平衡器以將流量路由到新實例
4. 驗證新實例是否正常運作
5. 停用舊實例（確認後）

由於 Paideia LMS 是無狀態的（所有資料都儲存在 PostgreSQL 和 S3 中），多個實例可以在升級過程中同時針對同一資料庫執行。

語義化版本控制

Paideia LMS 遵循語義化版本控制，它使用可預測的模式來告知用戶從一個版本到下一個版本可以預期的變化類型。

語義化版本控制遵循軟體版本號的 X.Y.Z 模式。這些值代表主要 (X)、次要 (Y) 和修補 (Z) 更新。

修補更改

修補更改是影響最小的更改。它們不會改變你使用 Paideia LMS 的方式，更新時不需要更改配置或資料。

當 Paideia 發布”修補”版本時，最後一個數字會增加。（例如 paideia@1.2.3 -> paideia@1.2.4）

修補可能因以下原因發布：

• 不影響功能的錯誤修復
• 不改變行為的內部改進
• 效能優化
• 安全修補
• 日誌和錯誤訊息的改進

修補更改還包括大多數錯誤修復，即使是在用戶利用現有非預期行為的情況下。

次要更改

次要版本主要引入你可能希望使用的新功能和改進，但不需要更改配置或資料。某些現有功能也可能在次要版本中被棄用（標記為在未來的版本中刪除，同時繼續執行），讓你有機會為它們最終的刪除做準備。

次要版本包括以下更改：

• 棄用現有功能/選項，並警告它們將在即將到來的主要版本中刪除
• 引入新功能
• 引入新的配置選項
• 效能改進
• 新的整合或功能

次要版本可能同時包含較小的修補更改。

主要更改

主要版本將包含對至少一些現有程式碼或配置的破壞性更改。這些破壞性更改總是記錄在發布說明中。

主要版本允許 Paideia 不僅對內部邏輯，而且對預期行為和使用方式進行重大更改。文檔將僅更新以反映最新版本。

主要版本包括以下更改：

• 刪除以前已棄用的功能
• 對現有功能的更改
• 需要更新的配置選項更改
• 重大架構更改
• 可能需要手動干預的資料庫模式更改（罕見）

主要版本也可能包含一些非破壞性更改和改進，這些更改和改進通常會單獨在次要或修補版本中發布。

破壞性更改和資料丟失：如果主要版本包含破壞性更改或資料丟失遷移，這些將在發布說明中明確指定。此類更改不太可能發生，但當它們發生時，將詳細記錄遷移說明。

例外

• 文檔的改進：文檔更新是從原始碼構建的，可以獨立於二進制版本進行更新。

發布說明

每個版本都包含詳細的發布說明，記錄：

• 新功能和能力
• 錯誤修復
• 效能改進
• 破壞性更改（如果有）
• 遷移說明（如果需要）
• 棄用和未來更改

升級前務必查看發布說明，以了解已更改的內容以及是否需要採取任何操作。

備份建議

為確保安全的升級過程，我們建議：

1. 每日自動備份：設置 PostgreSQL 資料庫的每日自動備份
2. 升級前備份：在升級到新的主要版本之前，始終建立資料庫轉儲
3. 測試備份：定期驗證你的備份是否可以成功恢復
4. 備份儲存：將備份儲存在與生產資料庫不同的位置

有關備份的更多信息，請參閱安裝和設定指南。

故障排除升級

如果你在升級期間或之後遇到問題：

1. 查看發布說明以了解任何已知問題或特殊說明
2. 查看日誌以查找可能指示問題的錯誤訊息
3. 如有必要，從備份恢復並聯繫支援
4. 查看 GitHub issues以查看其他人是否遇到過類似問題

大多數升級問題可以通過確保你有最近的備份並仔細遵循發布說明來解決。