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

# 5.2 备份、恢复与升级

完整备份包含 PostgreSQL、DSH 会话与配置、工作文件以及数据库口令，不含密钥与连接授权。以下命令针对 Compose 安装，在原安装目录执行，使用一个新的备份目录。

## npm 安装

把 `0.2.4` 命令包安装到新的命令目录，用其中的 `teloa` 操作。自定义安装继续传入原 `--home`；先处理运行中的工作，再停止并备份到新目录，然后升级：

```sh
teloa stop
teloa backup --output "/absolute/path/new-backup"
teloa upgrade --to 0.2.4
teloa status
```

`--to` 等于该命令包版本时以其为候选，其他版本从 npm 注册表取得，见[安装指南](https://docs.teloa.ai/v/0.2.4/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 命令包不会升级运行中的应用。下方 shell 命令针对 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
```

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

```sh
docker compose -p teloa-restore exec -T db pg_restore --exit-on-error --no-owner -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
```

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

## 升级和回退

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

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

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

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

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

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

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