Nextcloud 23.0.0升级至23.0.5后出现LDAP UUID无效报错

该故障的核心原因是Nextcloud 23.0.2及以上小版本调整了LDAP UUID的存储校验规则，老版本升级后大概率遇到两类问题：一是数据库映射表字段长度不满足新版本要求，导致UUID更新写入失败；二是本地残留了LDAP服务端已删除的用户/组映射记录。
修复按以下优先级操作即可：

前置操作 #

• 确认升级前的整机备份可用，所有数据库操作前额外单独备份Nextcloud业务库
• 切到Nextcloud根目录：cd /var/www/nextcloud
• 开启维护模式避免操作过程中出现数据写入冲突：sudo -u www-data php occ maintenance:mode --on

方案1：修复数据库字段约束（90%场景可解决） #

1. 登录Nextcloud使用的数据库，以最常用的MariaDB/MySQL为例：

   mysql -u 你的数据库账号 -p 你的Nextcloud库名
   

2. 检查LDAP映射表的UUID字段属性：

   DESCRIBE ldap_user_mapping ldap_uuid;
   DESCRIBE ldap_group_mapping ldap_uuid;
   

   23.0.5版本要求两个表的ldap_uuid字段类型为varchar(128)，如果查询结果显示字段长度小于128，执行以下SQL修正：

   ALTER TABLE ldap_user_mapping MODIFY COLUMN ldap_uuid varchar(128) NOT NULL DEFAULT '';
   ALTER TABLE ldap_group_mapping MODIFY COLUMN ldap_uuid varchar(128) NOT NULL DEFAULT '';
   

3. 退出数据库控制台，重新执行UUID更新命令：

   sudo -u www-data php occ ldap:update-uuid
   

   正常执行后会显示所有记录更新完成，无写入失败提示。
4. 清理缓存和旧告警标记，关闭维护模式：

   sudo -u www-data php occ config:app:delete ldap invalid_uuids
   sudo -u www-data php occ cache:clear
   sudo -u www-data php occ maintenance:mode --off
   

   回到管理概览页刷新，告警即可消失。

方案2：清理残留失效映射记录 #

如果修正字段后仍然报错，说明8条写入失败的记录对应LDAP服务端已删除的用户/组，属于本地残留脏数据，直接清理即可：

1. 查询所有残留的失效LDAP记录：

   sudo -u www-data php occ ldap:show-remnants
   

   命令会列出所有本地有映射、但LDAP服务端已不存在的用户、组条目。
2. 批量删除残留用户记录：

   sudo -u www-data php occ ldap:show-remnants | cut -f2 -d'|' | tail -n +3 | grep -v '^$' | while read dn; do sudo -u www-data php occ user:delete "$dn"; done
   

3. 对列出的残留组，手动执行删除命令：

   sudo -u www-data php occ group:delete 残留组标识
   

4. 重新执行UUID更新命令，确认无报错后按方案1的步骤清理缓存、关闭维护模式。

方案3：强制更新UUID（适用于LDAP服务端UUID变更场景） #

如果是LDAP服务端迁移、重建导致所有用户/组UUID发生变更，不需要手动逐个提取替换：

1. 进入Nextcloud后台LDAP配置的「专家模块」，开启「覆盖UUID检测」选项
2. 执行带强制参数的更新命令：

   sudo -u www-data php occ ldap:update-uuid --force
   

3. 更新完成后清理缓存、关闭维护模式即可。

内容的提问来源于stack exchange，提问作者Trovão