---
title: 备份、恢复与升级
description: 同时保护数据库、会话、工作文件和容器身份。
lastVerified: 2026-11-06
---

# 5.2 备份、恢复与升级

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

## 0.2.31 的数据边界

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

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

## npm 安装

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

```sh
npm install --prefix ./teloa-command-027 --ignore-scripts https://github.com/teloa-ai/teloa/releases/download/v0.2.31/teloa-cli-0.2.31.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.31
./teloa-command-027/node_modules/.bin/teloa status
```

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

`--to` 等于该命令包版本时以其为候选，其他版本从 npm 注册表取得，见[安装指南](https://docs.teloa.ai/v/0.2.31/markdown/start/quickstart.md)。升级也会自动备份，核对候选就绪后切换，成功后自动启动，不需要再运行 `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 直接执行恢复。

源码模式的数据位置见[配置与数据位置](https://docs.teloa.ai/v/0.2.31/markdown/deploy/configuration.md)。直接复制运行中的 PostgreSQL 数据目录不能替代一致备份。

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

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

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

候选各能力的入口与限制见[原生运行能力](https://docs.teloa.ai/v/0.2.31/markdown/guides/native-capabilities.md)。扩展显示“已启用”不等于实际浏览器、桌面、语音或 SSH 链路均已验证。