文档

简体中文

English

简体中文

English

切换主题

社区版开源 Web · 0.2.27 发行文档 · 0.2.27内容核对：2026-11-05查看 Markdown

5.2 备份、恢复与升级 ​

完整备份包含 PostgreSQL、DSH 会话与配置、工作文件以及数据库口令，不含密钥与连接授权。先判断当前是 npm 原生安装还是 Compose 安装，再按对应流程在原安装目录执行，并使用新的备份目录。

0.2.27 的数据边界 ​

本版数据版本为 18，直接兼容的数据版本仅为 18。从受支持的旧版本升级时，由正常升级流程先备份再迁移；这不表示旧程序可以读取升级后的数据。继续使用原 --home、安装身份、数据库与工作目录，不重新初始化，不删除原库或持久卷。

若升级报告尚有同一操作待恢复，先保留错误和备份，核对原目标后使用同版命令包执行 teloa upgrade --to 0.2.27 --resume。不要另开一次升级、覆盖程序目录或用 up 绕过维护状态。回退仍需匹配的旧程序和升级前备份。

npm 安装 ​

把 0.2.27 命令包安装到新的命令目录，用其中的 teloa 操作：

sh
npm install --prefix ./teloa-command-027 --ignore-scripts https://github.com/teloa-ai/teloa/releases/download/v0.2.27/teloa-cli-0.2.27.tgz
./teloa-command-027/node_modules/.bin/teloa stop
./teloa-command-027/node_modules/.bin/teloa backup --output "/absolute/path/new-backup"
./teloa-command-027/node_modules/.bin/teloa upgrade --to 0.2.27
./teloa-command-027/node_modules/.bin/teloa status

自定义安装继续传入原 --home。

--to 等于该命令包版本时以其为候选，其他版本从 npm 注册表取得，见安装指南。升级也会自动备份，核对候选就绪后切换，成功后自动启动，不需要再运行 up。升级失败时安装停在维护状态，up 与 restart 会拒绝；自动备份在 <home>.backups/before-<版本>-…，路径记在 instances/default/upgrade.json。npm 备份包括数据库、会话与配置，不包含模型凭据或工作目录中的文件。备份本身未加密，应妥善保护；另行保存工作目录，继续工作前核对两者。恢复时使用新的安装目录：teloa restore --from "/absolute/path/new-backup" --home "/absolute/path/new-home"，之后重新配置凭据。恢复必须使用与备份完全相同版本的命令包（升级前的自动备份属于旧版本，用旧版命令包恢复），并先把原工作目录放回原路径。仅更新 npm 命令包不会升级运行中的应用。Compose 安装的备份命令见下一节。

1. 停止写入并备份 ​

先处理正在执行的工作。下面是 macOS / Linux shell 命令：

sh
umask 077
mkdir backup
docker compose stop app
docker compose exec -T db pg_dump -U teloa -d teloa -Fc > backup/database.dump
docker compose run -T --rm --no-deps --entrypoint tar app -C /data --anchored --exclude=dsh/.env --exclude='dsh/.credentials.*' --exclude=teloa/mcp/credentials -czf - dsh teloa > backup/app.tar.gz
docker compose run -T --rm --no-deps --entrypoint cat app /run/teloa-secrets/postgres-password > backup/postgres-password
docker compose start app

每条导出命令应成功结束；文件存在不代表有效，失败可能留下空文件。备份包含数据库口令和工作资料，应保存到受控的加密存储。

与 teloa backup 一致，打包时排除密钥与授权：DSH 目录下的 .env（可能含明文密钥）、.credentials.*（加密保存的密钥与授权令牌及其元数据、隔离的明文副本）和受管 MCP 旧密钥目录 teloa/mcp/credentials。密钥存储的主密钥在单独的 credentials-secret 卷里，也不在备份内。恢复后请在设置中重新录入模型密钥、连接授权与 IM 通道密钥；.env 里需要保留的设置请自行另存到受保护的位置。

2. 在独立副本恢复 ​

使用相同版本源码和镜像。确认新项目名 teloa-restore 和端口 3107 尚未使用；以下流程不能用于覆盖已有工作库。

恢复副本可能带有启用的自动化。启动应用前确认不会重复执行真实业务，先在受控网络或停用计划的副本验证。

先恢复口令，再启动空数据库：

sh
docker compose -p teloa-restore run -T --rm --no-deps --entrypoint sh init -c 'cat > /data/secrets/postgres-password && chmod 440 /data/secrets/postgres-password' < backup/postgres-password
docker compose -p teloa-restore up -d db
docker compose -p teloa-restore ps

等待数据库健康，再恢复数据和工作文件：

--no-acl 不能省略。备份的 ACL 段会把看板只读权限授给应用首次启动时才创建的角色（如 teloa_business_reader_<hash>），全新恢复库里没有这个角色；带上 --no-acl 跳过 ACL 重放即可完成恢复，首次启动应用后会重建角色与只读授权。这也与 teloa restore 的 --no-owner --no-acl 一致。

sh
docker compose -p teloa-restore exec -T db pg_restore --exit-on-error --no-owner --no-acl -U teloa -d teloa < backup/database.dump
docker compose -p teloa-restore run -T --rm --no-deps --entrypoint tar app -C /data -xzf - < backup/app.tar.gz
TELOA_PORT=3107 docker compose -p teloa-restore up -d --no-build

使用副本的新认证链接进入，核对员工、群、任务、资料和一份工作文件的身份与内容，不只看首页能否打开。验证后停止副本。

升级和回退 ​

继续使用原安装目录、Compose 项目名和 .env。不要运行新安装准备脚本，不重新生成项目名；否则会接入另一组数据卷。旧版默认项目名通常为 teloa，但应核对实际配置，不能猜测。若换用新的下载配置，先保留原项目名到 COMPOSE_PROJECT_NAME，不要覆盖其他配置。

记录程序版本、镜像校验值和项目名，先在隔离副本检查目标版本。正式升级前完成备份。Hub 安装先将 Compose 中 app 与 init 的镜像改为同一精确版本，再执行 docker compose pull 与 docker compose up -d --no-build；源码构建使用 docker compose up -d --build。

数据库或会话格式变化后，旧镜像不一定能读取新数据。回退需要旧版本和升级前完整备份配套，不能只改镜像标签或 --to 版本号。

Compose 回退（先保留新数据）： 停止原项目的 app，保留当前数据卷、升级后的 Compose 文件和 .env；不要覆盖它们。使用升级前的精确版本源码与镜像，以及升级前完整备份，按上节「在独立副本恢复」流程操作：将其中所有项目名改为尚未使用的 teloa-restore-old，端口改为另一个未使用的端口。新项目只先启动数据库，恢复数据库和工作文件后，最后才启动旧版本 app。先在受控网络或禁用计划的副本中核对员工、会话、任务和文件，再决定是否切换入口；保留原项目以供核对。没有匹配备份时不要启动旧镜像。

npm 原生回退： 保留升级后的 home；安装升级前的命令包，用 teloa restore --from "/absolute/path/pre-upgrade-backup" --home "/absolute/path/restored-home" 恢复到新目录，用旧命令包启动并核对。确认前不要删除升级后的 home，也不要对原 home 直接执行恢复。

源码模式的数据位置见配置与数据位置。直接复制运行中的 PostgreSQL 数据目录不能替代一致备份。

升级前保留与核对的内容 ​

0.2.27 使用 DSH 0.2.1-rc.2。已有安装升级前保留原版本和完整备份，先在独立数据库、配置目录、工作目录与端口检查目标版本。

  • 依赖使用发行包锁定的 DSH 版本，不单独更新某个官方包，也不使用浮动版本标签。保留平台 optional dependencies，避免语音、浏览器或电脑驱动缺失。
  • 完整保存 DSH 配置、会话与附件、扩展启用选择、市场待处理安装记录和工作文件。准备可选包时保持已有启用/停用选择；Browser 和 Computer 默认关闭。
  • 在副本核对旧会话读取与续接、员工及业务身份、附件原文、一次文件预览和一次任务停止。旧子会话沿官方恢复路径保留，不转换成虚构的 Team 记录。
  • 安排重启前收口在途工作。后台本地进程与内存中的改动审阅不能靠复制会话记录恢复；重启后核对中断，不自动重放可能已执行的外部操作。
  • 正式切换应在候选验收和回退方案确认后单独执行。若会话或数据库格式已改变，回退使用升级前副本，不能让旧版本直接改写新数据。

候选各能力的入口与限制见原生运行能力。扩展显示“已启用”不等于实际浏览器、桌面、语音或 SSH 链路均已验证。