Skip to main content

​
常规升级

启动时后端自动跑数据库迁移。下面按版本号列出需要额外手动操作的迁移——只做你跨过的版本。

​
升级到 Organization 版本

这个版本把全部用户和项目放入唯一的 default org。首个 SYS_ADMIN 成为组织 Owner，其他用户成为 Member；原公开/私密项目会映射为组织内公开/私密类别。现有项目、API Key、对话和 Dashboard 保留原 ID 与内容。
升级前必须备份 PostgreSQL 数据库和 asktable_data。如果当前实例没有 SYS_ADMIN，迁移会主动失败，不会任意选择 Owner；请先在旧版本中恢复一个系统管理员。
1

备份并停止服务

2

固定 Region

在 asktable 的环境变量中设置 AT_REGION: cn 或 AT_REGION: global。默认是 cn；它是部署级静态配置，后续变更需要身份数据迁移。Local 登录身份始终以邮箱为主，不因 Region 改变。
3

迁移部署级登录配置

Google、GitHub、微信、邮箱登录、SMTP 与 SMS 不再从系统设置或数据库读取，旧的强制手机号开关也会删除。启动新版本前，把仍需使用的配置写入环境变量；OAuth 的 ID 与 Secret、SMS 的 URL 与 Key 必须分别成对填写。国内云生产必须完整配置微信与 SMS。变量清单与示例见 部署认证配置。企业微信/WPS 会迁入 default org，升级后在 个人设置 → 组织 → 登录集成 中维护。迁移会删除旧认证配置键，回滚依赖本步骤之前的数据库备份。
4

拉取并启动新版本

后端会先执行 Organization 数据库迁移，再启动应用。迁移失败时不要反复重启或跳过迁移，应保留日志并从备份恢复。
5

验证

使用原管理员登录，确认组织名称、成员、项目、API Key、对话和 Dashboard 正常；每个项目应只有一名项目负责人，原 is_public 值应正确映射为公开或私密项目，且不再出现 VIEWER 或匿名项目访问。
全新私有部署会在 setup 向导中要求填写组织名称。升级实例使用迁移生成的 default org 名称，Owner 可以在个人设置的组织设置中修改。升级后，项目和用户在个人设置的“组织”分组下治理；系统设置不再提供全局项目或用户入口。
Cloud 的组织订阅、余额与订单迁移需要在生产快照副本上先跑预检和对账断言，并在暂停 web/worker 的发布窗口一次完成。若预检输出 cloud_legacy_enterprise_credentials 或 cloud_legacy_enterprise_config，必须停止升级、导出相关数据并交由迁移负责人决定归属；migration 不会自动删除这些 Cloud 数据或猜测目标组织。值为空的历史企微/WPS 配置占位键不计入该 blocker。这不是普通私有部署的操作路径。

​
v4.1.x → v4.2.x（Qdrant → pgvector）

此区间字段向量从独立 Qdrant 改存主库 pgvector。从 v4.1.x 升级到 v4.2.x 需要：
1

换 pgvector 镜像

官方 postgres 镜像不带 pgvector 扩展，必须换（扩展由迁移脚本自动安装）：
docker-compose.yaml
2

删掉 Qdrant

对照 私有部署 最新 compose，删除 asktable_vdb 服务、VDB_ADDRESS/VDB_API_KEY 环境变量、qdrant_storage/qdrant_snapshots 卷。
3

拉起

自动迁移并安装 pgvector 扩展。缺 asktable_workbook 库时按 私有部署 补建。
4

重建 Embedding

老数据源向量为空，进每个数据源页点 重建 Embedding 回填。

​
collation 版本警告

只有换了 PostgreSQL 镜像、底层 glibc 版本变化时才会遇到，判据是启动日志出现 collation version mismatch。
  • 在原有 PostgreSQL 上自己装 pgvector 扩展、没换镜像 → 不触发，跳过本节。
  • 把旧镜像（如早期部署用的 postgres 镜像）换成 pgvector 镜像、且复用旧 postgres_data 卷 → 触发，按下面处理。
别只按提示刷版本号。glibc 版本不同会改变文本排序规则，旧文本索引与数据对不上，查询会静默漏行。必须先重建索引，再刷版本号。
启用了 Workbook 就对 asktable_workbook 库做同样两步。数据可弃时更省事：docker compose down -v 删卷重建（生产勿用，会清空数据）。