[Bug]: Upgrade path missing column `tenant.tenant_ocr_id` – all tenant DB queries silently fail as “Tenant not found”

快速结论：该报错通常出现在 RAGFlow 从旧版本（如 v0.26.x）原地升级到 v0.27.0 并复用已有 PostgreSQL 元数据库的场景。根本原因是升级迁移漏加了 tenant.tenant_ocr_id 列，导致所有 Tenant 查询静默失败；优先排查元数据库的 tenant 表结构，而不是 API 序列化本身。

适用环境：Issue 中已确认：RAGFlow v0.27.0（代码提交 ec9c08d，镜像 v0.27.0）；元数据库为外部 PostgreSQL 17（DB_TYPE=postgres）；部署于 Kubernetes，后端为 python 模式（API_PROXY_SCHEME=python）；由 v0.26.4 原地升级，非全新安装。

最快修复方案：已在 Issue 中验证的手动补列方案：在元数据库中执行 ALTER TABLE tenant ADD COLUMN tenant_ocr_id varchar(32);。若旧库同样缺少 ocr_id，可一并执行 ALTER TABLE tenant ADD COLUMN ocr_id varchar(128);。

注意事项：该 SQL 仅为绕过升级路径缺列问题，属于临时方案；正式修复是上游在 migrate_db() 中补上对应 alter_db_add_column 调用。补列后 tenant_ocr_id 的外键值可能仍为空，需要后续迁移逻辑（如 tenant_model_id_migration）填充。执行前请备份元数据库。全新安装不受影响，只有升级路径存在该问题。

问题场景

用户将已有的 RAGFlow v0.26.4 部署原地升级到 v0.27.0 镜像，复用由更早版本创建、并经过多次升级的 PostgreSQL 元数据库，并让启动迁移自动运行。升级后调用任何需要解析 Tenant 的 API（例如使用有效 API Key 调用 POST /api/v1/datasets）即失败，数据集创建、解析、检索等流程均受影响。

报错原文

[Bug]: Upgrade path missing column `tenant.tenant_ocr_id` - all tenant DB queries silently fail as "Tenant not found"

{"code":101,"message":"Unable to serialize unknown type: "}

ERROR Tenant not found.

Failed to create index on tenant (tenant_ocr_id): column "tenant_ocr_id" does not exist

ProgrammingError: column t1.tenant_ocr_id does not exist

原因分析

v0.27.0 的 Tenant 模型在 api/db/db_models.py（约第 1148 行）声明了 tenant_ocr_id = CharField(max_length=32, null=True, index=True)，但升级用的增量列列表（db_models.py 中约 2373–2452 行的 alter_db_add_column 调用）只包含旧列 "tenant", "ocr_id"，没有 "tenant", "tenant_ocr_id"。

因此升级后的数据库中缺少该列：启动时创建索引失败，peewee 对该模型的所有 SELECT 都会抛出 ProgrammingError: column t1.tenant_ocr_id does not exist。TenantService.get_by_id() 捕获并吞掉了这个异常，返回 (False, None)，对外表现为 “Tenant not found”；服务层随后把 Response 对象交给 JSON 序列化器，才产生看似无关的 Unable to serialize 报错。

全新安装不会触发，因为 create_tables 会按完整模型建表，只有升级路径遗漏了该列。Issue 中提到，同源的升级路径 schema 漂移还涉及其他问题（如 tenant_model.model_type 字段类型、tenant_*_id 字段类型），说明旧库结构与新模型之间存在多处不一致。

环境排查

确认 RAGFlow 版本与部署方式：是否由旧版本原地升级而来（而非全新安装），镜像/代码版本是否为 v0.27.0（提交 ec9c08d）。
确认元数据库类型与版本：Issue 中为外部 PostgreSQL 17，DB_TYPE=postgres；MySQL 等其他数据库的升级路径需另行核对，Issue 未覆盖。
检查 tenant 表实际列：是否存在 tenant_ocr_id、ocr_id，以及两者长度是否与模型声明一致（tenant_ocr_id 为 varchar(32)，ocr_id 为 varchar(128)）。
查看 RAGFlow 启动日志中是否有 Failed to create index on tenant (tenant_ocr_id): column "tenant_ocr_id" does not exist 一类迁移告警。
确认后端运行模式与代理配置（Issue 中为 API_PROXY_SCHEME=python），以便对照日志中的 ERROR Tenant not found.。

解决步骤

先按“环境排查”确认 tenant 表缺少 tenant_ocr_id 列，再动手修改，避免误判为 API 序列化问题。
备份元数据库（尤其是 tenant 表），因为后续步骤是直接改表结构。
在元数据库中执行 Issue 中验证有效的补列语句：ALTER TABLE tenant ADD COLUMN tenant_ocr_id varchar(32);
如果旧库中没有 ocr_id 列，按评论建议一并补为 ALTER TABLE tenant ADD COLUMN ocr_id varchar(128);（可优先尝试，取决于旧库实际结构）。
重启 RAGFlow 服务，让启动迁移重新执行，并检查启动日志中不再出现创建 tenant_ocr_id 索引失败的报错。
如需彻底修复而非临时绕过，可关注上游是否已在 migrate_db() 中加入 alter_db_add_column(migrator, "tenant", "tenant_ocr_id", CharField(max_length=32, null=True, index=True))，并升级到包含该修复的构建；评论指出该修复已进入 main，但当时尚不确定是否已进入正式 Docker 镜像。

验证方法

使用有效 API Key 重新调用 POST /api/v1/datasets，应正常创建数据集，而不再返回 {"code":101,"message":"Unable to serialize unknown type: ..."}；服务器日志中不再出现 ERROR Tenant not found. 与 column "tenant_ocr_id" does not exist。Issue 作者报告补列后数据集创建、解析、检索均通过。若配置了 RAGFlow 的其他租户相关接口，也可一并调用确认 Tenant 能正常解析。