# 版本升级与迁移

备份数据、升级版本，并完成相应的迁移步骤。

部署说明 · 模块: deploy · 管理人员 · 部署形态：Cloud / 私有部署 · 已确认产品版本：资料未说明 · 来源：编辑整理 · 变更章节按产品 4.2.48-1026 核对（CLI 命令另按 0.0.10）；不代表所有实例已升级，也不是完整历史支持矩阵。

常规升级通过更新镜像完成。跨越特定版本时，还需要迁移向量数据或调整文本排序规则。升级前应备份数据，并核对对应版本的迁移要求。

## 前置条件

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

**先停止应用写入再备份**，这是能恢复到升级前状态的前提。下面按本页 Compose 服务名操作，保留 PostgreSQL 运行以完成备份：

```bash
docker compose stop asktable
docker compose exec -T asktable-pg pg_dump -U asktable -d asktable -Fc > backup-asktable.dump
tar -czf backup-asktable-data.tar.gz asktable_data
```

启用了工作簿，还需单独备份，并使用不同文件名：

```bash
docker compose exec -T asktable-pg pg_dump -U asktable -d asktable_workbook -Fc > backup-asktable-workbook.dump
```

同时记录原镜像版本并妥善保存部署配置。确认备份可读取、已在副本验证恢复；不要把运行中的 PostgreSQL 数据目录复制当成数据库备份。升级要求应在启动新版本前完成。

## 操作步骤

**确认跨版本要求**

先阅读下面与你升级区间对应的章节，完成环境变量和数据库镜像等准备，再启动目标版本。

**拉新镜像**

```bash
docker compose pull
```

**停服务并重建**

```bash
docker compose down
docker compose up -d
```

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

**确认版本和迁移结果**

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

**完成业务验收**

按对应迁移章节检查登录、项目权限、历史内容和一次实际查询，再结束维护窗口。

## 升级到 Organization 版本

本节适用于从尚未引入组织的版本升级。**私有部署**会把现有有效用户和项目归入一个默认组织，由最早创建的系统管理员担任组织 Owner，其他用户成为 Member。公开和私密项目迁入组织范围；普通有效项目的 ID、API Key、对话和画卷继续保留。

**Warning**

迁移会清理没有有效负责人的项目及其关联资源、孤立的成员关系等无效历史数据，并删除旧的全局认证配置键。这些清理不能靠换回旧镜像恢复。升级前必须备份数据库和业务文件，并在备份副本上检查迁移结果。

**检查管理员、项目负责人和备份**

确认旧实例至少有一名系统管理员，并核对现有项目都有有效负责人。已有用户却没有系统管理员时，私有部署迁移会停止，不会随意选择组织 Owner。请先在旧版本恢复正确的管理身份。

按本页备份步骤停止应用写入，备份主库、启用的工作簿库和 `asktable_data`，记录原镜像版本。无负责人项目会被迁移清理；需要保留时，应在升级前修复负责人关系。

**固定部署模式和 Region**

私有部署保持 `AT_DEPLOY_MODE=local`，并在主服务环境中明确设置 `AT_REGION: cn` 或 `AT_REGION: global`。Region 默认为 cn，后续改变需要身份数据迁移；Local 始终以邮箱作为账号标识。

**迁移登录和邮件配置**

将旧版本仍需使用的 Google、GitHub、微信、邮箱登录、SMTP 与 SMS 配置转为环境变量。OAuth 的 ID/Secret、SMS 的 URL/Key 分别成对填写，见[部署认证配置](https://docs.asktable.com/deploy/authentication)。旧的数据库认证配置键和强制手机号开关不再作为配置来源。

Local 原有企业微信/WPS 集成会迁入默认组织。已有企业配置不完整时迁移会报错，请先补齐原配置并保留备份。升级后由组织 Owner/Admin 在 **个人资料 → 组织 → 企业集成** 管理。

**启动目标版本**

确认镜像标签与环境配置后，网络部署拉取目标镜像并启动；离线部署使用同次发布的安装脚本和离线包，见[私有部署（Docker）](https://docs.asktable.com/deploy/docker)。

```bash
docker compose pull
docker compose up -d
docker compose logs --since=10m asktable
```

应用启动前会执行数据库迁移。失败时先保存错误日志并定位原因，不要跳过迁移直接开放服务。

**验收组织和登录**

用原管理员登录，确认默认组织、成员和项目归属。新装实例在初始化时填写组织名称，升级实例可在组织设置中修改迁移生成的名称。

核对每个项目只有一名负责人、公开/私密类别正确、默认权限与显式角色符合预期；抽查 API Key、历史对话、画卷和工作簿。用一名已导入的企业成员验证完整登录地址与组织归属，再验证邮件发送和业务查询。

组织成员、角色和企业集成从个人设置中的组织分组管理。系统管理员仍保留全局用户与项目目录，私有部署的项目目录不会自动授予项目内容访问权。

**Cloud 发布补充：不是普通私有部署操作**

Cloud 会按原用户和项目负责人建立组织归属，不会把全站合为一个默认组织。组织订阅、余额、订单和兑换记录的迁移，应先在生产快照副本上完成预检及对账，再在暂停 Web/Worker 写入的窗口执行。

预检出现 `cloud_legacy_enterprise_credentials` 或 `cloud_legacy_enterprise_config` 时，应停止升级，导出受影响数据并由迁移负责人确定归属；迁移不会猜测其目标组织。空的历史企业微信/WPS 配置占位键不构成此项阻断。

国内 Cloud 生产还必须配置完整的微信和 SMS 环境变量，详见[部署认证配置](https://docs.asktable.com/deploy/authentication)。

## 升级到成员工作区版本

成员工作区和身份权限升级已包含在 `4.2.43-1025`；以下迁移及恢复规则按 `4.2.48-1026` 核对。Cloud 的实际启用时间以服务通知为准，私有部署需先在备份副本中验收。后续修复也会影响旧看板和数据表的恢复，不能仅凭 `4.2.43` 的入口变化判断升级完成。

| 已有内容               | 升级后的处理                                                       |
| ------------------ | ------------------------------------------------------------ |
| 项目与成员              | 保留原可见性和显式成员；旧可见项目的有效默认访问者补为正式成员，保留原有效项目角色。新成员须申请获批、受邀或由管理员添加 |
| Agent 和 Skill      | 保留内容、ID 和引用，统一归项目负责人；旧 Agent 默认项目全员可用。新建 Agent 默认仅自己         |
| 成员数据角色             | 不从历史聊天推断或自动绑定；未绑定仍是“全部数据”，受 Agent 数据源范围限制                    |
| 旧无 Agent 普通对话      | 历史只读；继续分析需选择 Agent 开启新对话                                     |
| 旧无 Agent 看板        | 编辑分析前选择覆盖全部元素数据源的 Agent；保存时恢复原会话并保留历史。缺少数据源时页面会列出不匹配项        |
| 数据表刷新              | 有执行用户的表按其当前数据角色刷新，无需补选 Agent；缺少执行用户的旧表需先显式建立执行身份             |
| 定时任务               | 改为独立入口，统一归项目负责人，保留时间、指令、通知和运行历史；按负责人的当前权限执行                  |
| 嵌入应用               | 保留原 ID、iframe 地址、角色、来源限制、启停状态和历史会话；在独立入口管理                   |
| 旧项目 API Key / 访问令牌 | 保留凭证并更名系统集成凭证；查询必须指定 Agent，不继承创建人的数据角色，也不能读写个人配置             |
| 邀请链接               | 保留地址、角色和启停状态；未配置数据角色的旧链接仍是“全部数据”                             |

对话与看板现在从同一工作区打开。已绑定看板但原会话此前未同步的存量情况，不会由本次选择 Agent 的恢复流程自动修复；遇到这种情况请保留版本和现象反馈。

### 升级后验收

1. 核对项目成员和角色。需要限制数据范围时，管理员必须给成员明确绑定数据角色，不能依赖旧聊天曾选过的角色。
2. 用普通成员验证自己的 Agent/Skill 可编辑、分享来的 Agent 可使用但不可编辑；负责人和管理员仍可治理项目资源，个人 Key 仅本人管理。
3. 核对历史内容与新执行：收紧角色后，新查询使用当前权限，已有消息和结果不会自动遮盖；撤销 Agent 使用权后可回看历史，不能继续调用它。失去项目权限后不可再访问项目历史。
4. 验证旧看板恢复和一次数据表刷新；核对定时任务负责人、执行范围与通知，验证原 iframe 地址及来源限制。
5. 接入方将无 Agent 查询改为带 `data_agent_id` 的 Conversation API；旧 `/v1/integration/query` 已移除。个人配置管理改用有权成员的个人凭证，见[OpenAPI](https://docs.asktable.com/integrations/openapi)。
6. CLI 与服务端分别核对：`cli-v0.0.10` 的旧嵌套 schedule/embed 命令与当前独立管理接口不兼容，暂用网页入口，见[CLI](https://docs.asktable.com/integrations/cli)。

迁移会改写资源归属和权限关系。回退必须恢复升级前的数据库、业务文件、镜像与配置，不能只换回旧镜像。

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

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

**换 pgvector 镜像**

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

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

**删掉 Qdrant**

对照 [私有部署（Docker）](https://docs.asktable.com/deploy/docker) 的最新 compose，删掉 `asktable_vdb` 服务、`VDB_ADDRESS` 和 `VDB_API_KEY` 两个环境变量，以及 `qdrant_storage`、`qdrant_snapshots` 两个卷。

**拉起**

```bash
docker compose pull
docker compose down
docker compose up -d
```

启动时自动迁移并安装 pgvector 扩展。日志提示 `asktable_workbook` 库不存在时，按 [私有部署（Docker）](https://docs.asktable.com/deploy/docker) 补建。

**重建 Embedding**

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

### collation 版本警告

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

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

**Warning**

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

```bash
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` 做同样两步。不要为消除警告直接清空生产数据目录；本页 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 ...` |
| 回滚           | 先确认数据库兼容性；不兼容或迁移删除数据时，恢复升级前数据库、业务文件及对应旧镜像和配置                                      | 使用经过验证的升级前备份                                  |
| 数据目录         | 示例使用宿主机绑定目录 `./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）](https://docs.asktable.com/deploy/docker) |
| 升级后语义检索变差   | 数据源「设置」→「索引维护」里没执行过「重建 Embedding」                                | 逐个数据源执行一次重建                                                                        |
| 想退回旧版       | 已按“前置条件”做过备份                                                     | 把 `image` 标签改回旧版本号再重建；数据结构不兼容时用备份恢复                                                |
| 数据库起来但服务连不上 | 日志里是数据库认证失败                                                      | 确认 `DATABASE_PASSWORD` 与 `POSTGRES_PASSWORD` 一致，两处不同步会在重建后暴露                       |

## 下一步

- [私有部署（Docker）](https://docs.asktable.com/deploy/docker) — 访问地址、升级命令与排障表
- [部署 AI 搜索（值索引）](https://docs.asktable.com/deploy/ai-search) — 值索引与 Embedding 是两件事
- [数据源日常维护](https://docs.asktable.com/data/manage) — 重建索引、刷新元数据
- [部署总览](https://docs.asktable.com/deploy/overview) — 可选组件与上线顺序