版本升级与迁移

私有部署的升级本身只有三条命令，但跨过某些版本区间时，光换镜像不够——向量存储位置和文本排序规则都需要手动补一步。这一页先给备份和常规升级，再按版本区间列出额外动作，最后是判断升级做没做干净的观测点。

前置条件

项目	要求
已知当前版本	左下角头像 →「系统设置」→ 左侧「关于」→ 系统版本
已定目标版本	交付 compose 用 `:latest`，要升到指定版本得把 `image` 标签写死成具体版本号
停服窗口	升级过程中服务不可用
已做备份	见下

先备份，这是能回滚的前提：

docker compose exec asktable-pg pg_dump -U asktable -d asktable -Fc -f /tmp/asktable.dump
docker compose cp asktable-pg:/tmp/asktable.dump ./backup-asktable.dump

启用了工作簿就再备一份，把 -d asktable 换成 -d asktable_workbook。./asktable_data 里是上传文件和日志，直接复制目录即可。

操作步骤

拉新镜像

docker compose pull

停服务并重建

docker compose down
docker compose up -d

容器启动时会先跑一遍数据库结构迁移，不需要手动执行 SQL。

确认版本和迁移结果

左下角头像 →「系统设置」→ 左侧「关于」→ 系统版本应显示目标版本；docker compose logs asktable 里不应出现迁移报错。

跨版本时补做手动迁移

对照下面按版本区间列出的项目，只做你跨过的那些。

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

这个区间里，字段向量从独立的 Qdrant 服务改存主库的 pgvector 扩展。从 v4.1.x 升到 v4.2.x 需要：

换 pgvector 镜像

官方 postgres 镜像不带 pgvector 扩展，必须换成带扩展的镜像（扩展本身由迁移脚本自动安装）：

docker-compose.yaml

asktable-pg:
  image: registry.cn-shanghai.aliyuncs.com/dminfra/pgvector:pg17   # 原来是 postgres:17

删掉 Qdrant

对照私有部署（Docker）的最新 compose，删掉 asktable_vdb 服务、VDB_ADDRESS 和 VDB_API_KEY 两个环境变量，以及 qdrant_storage、qdrant_snapshots 两个卷。

拉起

docker compose pull
docker compose down
docker compose up -d

启动时自动迁移并安装 pgvector 扩展。日志提示 asktable_workbook 库不存在时，按私有部署（Docker）补建。

重建 Embedding

老数据源的字段向量是空的。逐个进数据源页，点顶栏「设置」→「索引维护」→「重建 Embedding」，随后提示重建已开始、完成后语义检索自动生效。

collation 版本警告

只有换了 PostgreSQL 镜像、底层 glibc 版本跟着变时才会遇到。判据是 docker compose logs asktable-pg 或 docker compose logs asktable 里出现 collation version mismatch。

在原有 PostgreSQL 上自己装 pgvector 扩展、没换镜像 → 不触发，跳过本节。
把旧镜像（早期部署用的 postgres 镜像）换成 pgvector 镜像、且复用旧 postgres_data 卷 → 触发，按下面处理。

别只按提示刷版本号。glibc 版本不同会改变文本排序规则，旧文本索引与新排序规则对不上，查询会静默漏行。必须先重建索引，再刷版本号。

docker compose exec asktable-pg psql -U asktable -d asktable -c "REINDEX DATABASE asktable;"
docker compose exec asktable-pg psql -U asktable -d asktable -c "ALTER DATABASE asktable REFRESH COLLATION VERSION;"
docker compose exec asktable-pg psql -U asktable -d postgres -c "ALTER DATABASE template1 REFRESH COLLATION VERSION;"

启用了工作簿就对 asktable_workbook 做同样两步。数据可以丢弃时更省事：docker compose down -v 删卷重建，会清空全部数据，生产环境不要用。

关键约束

项目	值或默认	在哪里改
升级方式	换镜像后重建容器，数据库结构迁移在启动时自动执行	`docker compose pull` → `down` → `up -d`
镜像标签	`:latest`；发版同时推 `{version}` 和 `latest` 两个标签	`docker-compose.yaml` 的 `image`，要能回滚就写死版本号
主库镜像	`registry.cn-shanghai.aliyuncs.com/dminfra/pgvector:pg17`	`asktable-pg` 的 `image`
备份工具	`pg_dump` 在容器里可用（镜像装了 PostgreSQL 客户端）	`docker compose exec asktable-pg pg_dump ...`
回滚	把 `image` 标签改回上一个版本号，再重建容器	`docker-compose.yaml` 的 `image`
数据卷	`./postgres_data`、`./asktable_data`、`./redis_data`；`down -v` 会连卷一起删	`docker-compose.yaml` 的 `volumes`
collation 警告	只在换镜像且复用旧数据卷时出现	先 `REINDEX`，再 `REFRESH COLLATION VERSION`
字段向量	v4.2.x 起存主库 pgvector，不再用独立 Qdrant	数据源 →「设置」→「索引维护」→「重建 Embedding」

出问题怎么判断

现象	判定条件	处理
升级后版本号没变	「关于」里的系统版本还是旧值，且 `docker compose images` 里 `asktable` 的镜像 ID 没更新	`pull` 没拿到新镜像，检查出网放行和镜像标签
容器起不来	`docker compose logs asktable` 出现与 `vector` 扩展相关的报错	`asktable-pg` 还在用不带 pgvector 的镜像，换成 pgvector 镜像后重建
查询开始漏行	日志里出现过 `collation version mismatch`	按“collation 版本警告”先 `REINDEX` 再刷新版本号
工作簿报错	`docker compose logs asktable` 出现 `workbook PG ping failed`	补建 `asktable_workbook` 库，见私有部署（Docker）
升级后语义检索变差	数据源「设置」→「索引维护」里没执行过「重建 Embedding」	逐个数据源执行一次重建
想退回旧版	已按“前置条件”做过备份	把 `image` 标签改回旧版本号再重建；数据结构不兼容时用备份恢复
数据库起来但服务连不上	日志里是数据库认证失败	确认 `DATABASE_PASSWORD` 与 `POSTGRES_PASSWORD` 一致，两处不同步会在重建后暴露

下一步

私有部署（Docker） — 访问地址、升级命令与排障表
部署 AI 搜索（值索引） — 值索引与 Embedding 是两件事
数据源日常维护 — 重建索引、刷新元数据
部署总览 — 可选组件与上线顺序

部署与运维

选择接入方式

飞书机器人

网页嵌入

开发与自动化

定时分析报告

版本升级与迁移

前置条件

操作步骤

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

collation 版本警告

关键约束

出问题怎么判断

下一步

​前置条件

​操作步骤

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

​collation 版本警告

​关键约束

​出问题怎么判断

​下一步

前置条件

操作步骤

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

collation 版本警告

关键约束

出问题怎么判断

下一步