升级指南
把 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. 升级后验证步骤
- 清理
bin、obj目录(旧的编译产物可能干扰升级) - 重新编译:
dotnet build - 在开发环境启动,开启
UseAutoSyncStructure(true),确认新增的表/字段已同步 - 按更新日志检查破坏性变更(配置项改名、API 调整、默认行为变化)
- 走一遍关键功能:登录、用户/角色/菜单、操作日志、文件上传、代码生成器
- 验证通过后再部署生产(见部署上线)
5. 常见注意点
- 数据库结构:升级可能新增表或字段。开发环境同步没问题后,生产环境再执行同步(或按部署文档关闭自动同步、手动执行变更脚本)
- 缓存:升级后重启进程;如果用了 Redis,必要时清理旧缓存 key
- AesKey / AdminRouteSecret:除非更新日志明确要求,升级时不需要修改;已登录用户 Cookie 是否失效以更新日志为准
- v2.3.2 登录票据升级:票据升级为 v2,旧 v1 票据会被当作未登录处理,升级后所有用户需要重新登录一次(AesKey 同时已真正接入 Data Protection 应用名派生)
- v2.3.2 多租户 Host 白名单:启用多租户时建议立即配置
Security:AllowedHosts(后台域名列表),留空保持历史行为(不限制) - v2.3.2 操作日志新增两列:
SysOperationLog增加EntityType、EntityKey与索引idx_operationlog_entity(用于“修改历史”)。用UseAutoSyncStructure(true)会自动加;生产环境若关闭了自动同步,需要手动执行等价的ALTER TABLE ... ADD COLUMN ...与CREATE INDEX ... - v2.6.0 移除私有文件受控下载(破坏性变更):
/api/files/{id}接口与FileService.OpenPrivateFileAsync方法一并移除,文件一律走静态地址。若自己的代码引用了这些成员,需要改为使用SysFile.AccessUrl(文件记录上的访问地址)。框架内置的所有扩展包均无引用,已逐一核对。SysFile.IsPublic字段仍保留在实体上,但不再参与任何业务判断——保留它是为了让历史数据库的表结构保持原样,老项目升级后不需要改动数据库 - v2.6.0 审批记录新增一列:
SysApprovalRecord增加TotalLevels(INT NULL,记录提交时该轮流程的级数)。运行中的单据以它为准,流程配置后来被加级/减级都不会再改变在途单据的节点数量(在途单据不再因为改了流程就卡在“审批中”)。启动时框架会执行CodeFirst.SyncStructure<SysApprovalRecord>()自动补列;生产环境若关闭了自动同步,需要手动执行ALTER TABLE sys_approval_record ADD COLUMN TotalLevels INT NULL;。历史数据该列为空时会退回“按快照级次 → 流程配置”推断,行为与升级前一致 - v2.6.0 图片像素上限:新增
FileSettings:MaxImagePixels配置,默认 4000 万像素(约 160MB 解码缓冲)。它挡住的是"磁盘上几百 KB、解码后吃掉 2GB 内存"的构造图片;代价是 4800 万像素以上的手机原图会被拒绝上传,需要的话把该值调大(设为0表示不限制) - v2.6.0 大字段标记属性:用了"大字段标记"(
Is{列名}/{列名}Length)的话,标记属性必须带[Column(IsIgnore = true)]—— 否则它会被当成真实列写库,还会把同名真实列的值覆盖掉。老项目里已经加过标记属性的,检查一下有没有漏这个特性 - 模板版本落后于核心包:
EasyAdminBlazor.Templates与EasyAdminBlazor可能不同步,用模板新建的项目记得把核心包升级到最新 - 多实例部署:升级时逐台滚动发布,避免所有实例同时重启导致服务中断