升级指南

本文说明如何把 EasyAdminBlazor 项目升级到新版本。升级前先看更新日志，重点确认有没有破坏性变更。

1. 升级前准备

• 备份数据库：升级可能涉及表结构变更，先备份
• 在测试环境升级验证：不要直接在生产库上做
• 阅读更新日志，确认本次升级的依赖升级、安全修复和配置变化

2. 升级 NuGet 包

先查看当前引用的版本：

dotnet list package

升级核心包和扩展包：

# 核心包升级到最新
dotnet add package EasyAdminBlazor

# 用到的扩展包同步升级
dotnet add package EasyAdminBlazor.Mail
dotnet add package EasyAdminBlazor.Redis
dotnet add package EasyAdminBlazor.Scheduler
# ...按实际使用安装/升级

也可以在 Visual Studio 的「管理 NuGet 程序包」界面里升级。建议核心包与扩展包保持同一版本。

3. 更新模板包

模板包需要单独更新，重新执行安装命令即可覆盖为最新版：

dotnet new install EasyAdminBlazor.Templates

已创建的项目不受影响；之后新建项目会使用最新模板。

4. 升级后验证步骤

1. 清理 bin、obj 目录（旧的编译产物可能干扰升级）
2. 重新编译：dotnet build
3. 在开发环境启动，开启 UseAutoSyncStructure(true)，确认新增的表/字段已同步
4. 按更新日志检查破坏性变更（配置项改名、API 调整、默认行为变化）
5. 走一遍关键功能：登录、用户/角色/菜单、操作日志、文件上传、代码生成器
6. 验证通过后再部署生产（见部署上线）

5. 常见注意点

• 数据库结构：升级可能新增表或字段。开发环境同步没问题后，生产环境再执行同步（或按部署文档关闭自动同步、手动执行变更脚本）
• 缓存：升级后重启进程；如果用了 Redis，必要时清理旧缓存 key
• AesKey / AdminRouteSecret：除非更新日志明确要求，升级时不需要修改；已登录用户 Cookie 是否失效以更新日志为准
• 模板版本落后于核心包：EasyAdminBlazor.Templates 与 EasyAdminBlazor 可能不同步，用模板新建的项目记得把核心包升级到最新
• 多实例部署：升级时逐台滚动发布，避免所有实例同时重启导致服务中断