升级指南

把 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 是否失效以更新日志为准
  • 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 可能不同步,用模板新建的项目记得把核心包升级到最新
  • 多实例部署:升级时逐台滚动发布,避免所有实例同时重启导致服务中断