#Release 2.2.1

#发布日期

2026年5月12日

#发布信息

• 更新范围：从 2.2.1 版本文档对应提交 97a4db8ef81ce52498aa52859604c1f4a911f4ec 之后，到当前提交 bb5e43403df45c36d8c0d03c421ba324e632ce79
• 版本更新提交：97a4db8ef81ce52498aa52859604c1f4a911f4ec

#更新内容

#新功能

• 新增物理 Schema Excel 导出能力。建模导出面板现在支持按当前空间导出物理 Schema 清单，便于在建模评审、数仓对齐和线下交付场景中快速查看 Schema、字段和排序信息。
• 建模导出新增测试用例可选项，支持在迁移包中按需包含 yiask_alisa_testcase 相关数据，方便跨环境同步建模验证样例与回归数据。
• 角色权限管理新增指标权限支持。角色同步与权限写入逻辑现在可以处理指标维度的权限配置，便于将指标可见范围、数据行权限与现有 Schema 权限一起管理。
• 生成文件预览补充图片类型支持，报表、附件和聊天中的图片类文件现在可以直接在预览页中打开查看。
• 数据源密码链路补充“只写不读”能力。yiask_datasource.password 支持前端可编辑但不回显，列表和详情接口不再返回明文密码，同时测试连接会优先使用当前表单值，在密码未改动时自动回退到数据库中的已有密码。

#优化与重构

• 优化建模导出链路，支持按类型与集合精细选择导出内容，并补充空记录处理，减少跨环境导出时因空数据集合导致的歧义。
• 优化 Docker 构建与部署说明，移除对历史 storage/plugins/@nocobase 清理流程的依赖，降低镜像构建脚本和运行时插件目录的不一致风险。
• 优化技能工作区的标题读取与默认选中逻辑，减少首次进入工作区或切换技能时标题显示异常、默认态错位的问题。
• 优化密码与连接测试相关的服务端处理逻辑，补齐 MySQL 直连测试分支和写入型字段中间件的测试覆盖，提升数据源配置链路的可维护性。

#缺陷修复

• 修复普通建模导出的 ZIP 包无法再次导入的问题。此前仅包含 data.json 的 YiAsk 导出包会被误判为 skills ZIP，导致界面提示导入成功但实际没有写入任何建模数据；现在会按建模数据正确识别导入，并在 ZIP 不含可导入数据时直接报错。
• 修复插件上传文件扩展名校验缺失的问题，避免在插件管理界面上传不受支持的文件类型。
• 修复生成文件预览链路中的若干图片与链接处理问题，避免图片预览地址构造错误或预览页展示异常。
• 修复角色权限同步中的指标权限写入与查询逻辑问题，避免角色批量更新时丢失指标侧授权信息。
• 修复数据源密码字段在接口返回、编辑保存和测试连接场景中的行为不一致问题，避免列表泄露密码、未修改密码时被误清空，或测试连接未正确使用已有密码。

#迁移文件

如需同步本版本元数据调整，请下载迁移文件：migration-1778543014068.nbdata

使用指南见：版本更新指南

#升级流程

1. 上传迁移文件 migration-1778543014068.nbdata，等待迁移执行完成。
2. 更新部署版本到 2.2.1。
3. 进入应用 container，执行 rm -rf storage/plugins/@nocobase，然后执行 pm2 reload all，再执行 yarn nocobase upgrade。
4. 必要时重启 container，并确认服务恢复正常。

#出现错误时

1. 【出现 invalid SQL 报错时】进入应用 container，重新执行 yarn nocobase upgrade。
2. 如果数据源、建模映射或字段元数据未刷新，重启应用并重新检查相关 collection 的字段状态。