升级 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以查看其他人是否遇到过类似问题

大多数升级问题可以通过确保你有最近的备份并仔细遵循发布说明来解决。