部署与运维
版本升级与迁移
备份数据、升级版本，并完成相应的迁移步骤。
常规升级通过更新镜像完成。跨越特定版本时，还需要迁移向量数据或调整文本排序规则。升级前应备份数据，并核对对应版本的迁移要求。
前置条件
| 项目 | 要求 |
|---|---|
| 已知当前版本 | 左下角头像 →「系统设置」→ 左侧「关于」→ 系统版本 |
| 已定目标版本 | 交付 compose 用 :latest，要升到指定版本得把 image 标签写死成具体版本号 |
| 停服窗口 | 升级过程中服务不可用 |
| 已做备份 | 见下 |
先停止应用写入再备份，这是能恢复到升级前状态的前提。下面按本页 Compose 服务名操作，保留 PostgreSQL 运行以完成备份：
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启用了工作簿，还需单独备份，并使用不同文件名：
docker compose exec -T asktable-pg pg_dump -U asktable -d asktable_workbook -Fc > backup-asktable-workbook.dump同时记录原镜像版本并妥善保存部署配置。确认备份可读取、已在副本验证恢复；不要把运行中的 PostgreSQL 数据目录复制当成数据库备份。升级要求应在启动新版本前完成。
操作步骤
确认跨版本要求
先阅读下面与你升级区间对应的章节，完成环境变量和数据库镜像等准备，再启动目标版本。
拉新镜像
docker compose pull停服务并重建
docker compose down
docker compose up -d容器启动时会先跑一遍数据库结构迁移，不需要手动执行 SQL。
确认版本和迁移结果
左下角头像 →「系统设置」→ 左侧「关于」→ 系统版本应显示目标版本；docker compose logs asktable 里不应出现迁移报错。
完成业务验收
按对应迁移章节检查登录、项目权限、历史内容和一次实际查询，再结束维护窗口。
升级到 Organization 版本
本节适用于从尚未引入组织的版本升级。私有部署会把现有有效用户和项目归入一个默认组织，由最早创建的系统管理员担任组织 Owner，其他用户成为 Member。公开和私密项目迁入组织范围；普通有效项目的 ID、API Key、对话和画卷继续保留。
迁移会清理没有有效负责人的项目及其关联资源、孤立的成员关系等无效历史数据，并删除旧的全局认证配置键。这些清理不能靠换回旧镜像恢复。升级前必须备份数据库和业务文件，并在备份副本上检查迁移结果。
检查管理员、项目负责人和备份
确认旧实例至少有一名系统管理员，并核对现有项目都有有效负责人。已有用户却没有系统管理员时，私有部署迁移会停止，不会随意选择组织 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 分别成对填写，见部署认证配置。旧的数据库认证配置键和强制手机号开关不再作为配置来源。
Local 原有企业微信/WPS 集成会迁入默认组织。已有企业配置不完整时迁移会报错，请先补齐原配置并保留备份。升级后由组织 Owner/Admin 在 个人资料 → 组织 → 企业集成 管理。
启动目标版本
确认镜像标签与环境配置后，网络部署拉取目标镜像并启动；离线部署使用同次发布的安装脚本和离线包，见私有部署（Docker）。
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 环境变量，详见部署认证配置。
升级到成员工作区版本
成员工作区和身份权限升级已包含在 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 的恢复流程自动修复；遇到这种情况请保留版本和现象反馈。
升级后验收
- 核对项目成员和角色。需要限制数据范围时，管理员必须给成员明确绑定数据角色，不能依赖旧聊天曾选过的角色。
- 用普通成员验证自己的 Agent/Skill 可编辑、分享来的 Agent 可使用但不可编辑；负责人和管理员仍可治理项目资源，个人 Key 仅本人管理。
- 核对历史内容与新执行：收紧角色后，新查询使用当前权限，已有消息和结果不会自动遮盖；撤销 Agent 使用权后可回看历史，不能继续调用它。失去项目权限后不可再访问项目历史。
- 验证旧看板恢复和一次数据表刷新；核对定时任务负责人、执行范围与通知，验证原 iframe 地址及来源限制。
- 接入方将无 Agent 查询改为带
data_agent_id的 Conversation API；旧/v1/integration/query已移除。个人配置管理改用有权成员的个人凭证，见OpenAPI。 - CLI 与服务端分别核对：
cli-v0.0.10的旧嵌套 schedule/embed 命令与当前独立管理接口不兼容，暂用网页入口，见CLI。
迁移会改写资源归属和权限关系。回退必须恢复升级前的数据库、业务文件、镜像与配置，不能只换回旧镜像。
v4.1.x → v4.2.x（Qdrant → pgvector）
这个区间里，字段向量从独立的 Qdrant 服务改存主库的 pgvector 扩展。从 v4.1.x 升到 v4.2.x 需要：
换 pgvector 镜像
官方 postgres 镜像不带 pgvector 扩展，必须换成带扩展的镜像（扩展本身由迁移脚本自动安装）：
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 做同样两步。不要为消除警告直接清空生产数据目录；本页 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） |
| 升级后语义检索变差 | 数据源「设置」→「索引维护」里没执行过「重建 Embedding」 | 逐个数据源执行一次重建 |
| 想退回旧版 | 已按“前置条件”做过备份 | 把 image 标签改回旧版本号再重建；数据结构不兼容时用备份恢复 |
| 数据库起来但服务连不上 | 日志里是数据库认证失败 | 确认 DATABASE_PASSWORD 与 POSTGRES_PASSWORD 一致，两处不同步会在重建后暴露 |
下一步
- 私有部署（Docker） — 访问地址、升级命令与排障表
- 部署 AI 搜索（值索引） — 值索引与 Embedding 是两件事
- 数据源日常维护 — 重建索引、刷新元数据
- 部署总览 — 可选组件与上线顺序