> ## Documentation Index
> Fetch the complete documentation index at: https://docs.asktable.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 迁移

> 私有部署的版本迁移：常规升级，以及按版本号列出需要额外手动操作的迁移（如 v4.1.x → v4.2.x 的 Qdrant→pgvector）。

## 常规升级

```bash theme={null}
docker compose pull && docker compose down && docker compose up -d
```

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

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

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

<Steps>
  <Step title="换 pgvector 镜像">
    官方 `postgres` 镜像不带 pgvector 扩展，必须换（扩展由迁移脚本自动安装）：

    ```yaml docker-compose.yaml theme={null}
    asktable-pg:
      image: registry.cn-shanghai.aliyuncs.com/dminfra/pgvector:pg17   # 原来是 postgres:17
    ```
  </Step>

  <Step title="删掉 Qdrant">
    对照 [私有部署](/deploy/docker) 最新 compose，删除 `asktable_vdb` 服务、`VDB_ADDRESS`/`VDB_API_KEY` 环境变量、`qdrant_storage`/`qdrant_snapshots` 卷。
  </Step>

  <Step title="拉起">
    ```bash theme={null}
    docker compose pull && docker compose down && docker compose up -d
    ```

    自动迁移并安装 pgvector 扩展。缺 `asktable_workbook` 库时按 [私有部署](/deploy/docker) 补建。
  </Step>

  <Step title="重建 Embedding">
    老数据源向量为空，进每个数据源页点 **重建 Embedding** 回填。
  </Step>
</Steps>

### collation 版本警告

只有**换了 PostgreSQL 镜像、底层 glibc 版本变化**时才会遇到，判据是启动日志出现 `collation version mismatch`。

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

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

```bash theme={null}
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;"
```

启用了 Workbook 就对 `asktable_workbook` 库做同样两步。数据可弃时更省事：`docker compose down -v` 删卷重建（**生产勿用，会清空数据**）。