> ## Documentation Index
> Fetch the complete documentation index at: https://help.teable.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 版本更新

本文档介绍如何更新您的 Teable 私有化部署版本。

## 发布通道与版本号

Teable 应用以**日期型 release tag** 发布，形如
`release.<时间戳>.<构建号>`(例如 `release.2026-07-14T12-24-39Z.2228`),
另有两个浮动通道：

| Tag | 含义 |
| - | - |
| `latest` | **稳定**通道 —— 始终指向最新的稳定版本 |
| `beta` | 滚动通道 —— 最新构建，先于稳定版 |
| `release.<时间戳>.<构建号>` | 不可变的具体版本 |

发布频率较高（常常一周多个版本），何时升级由您自主决定。
全部版本可在 [GitHub Packages](https://github.com/teableio/teable/pkgs/container/teable) 查看。

<Note>
  在进行任何更新操作之前，强烈建议先备份您的数据。
</Note>

## 日常更新：跟着更新日志走

新功能与修复都发布在[更新日志](/zh/changelog)里，而 Teable 的每个 release tag
自带构建日期 —— 所以「我有没有这个功能」就是一次日期比较。想用上日志里提到的
某项更新，把 Teable 镜像升到该条目日期之后（含当日）的任一版本即可：

* **Docker 部署**直接跟 `latest` 通道就行：

  ```bash theme={null}
  cd teable          # 您的部署目录
  docker compose pull
  docker compose up -d
  ```

  容器基于新镜像重建；数据存储在 Docker 卷（或外部数据库）中，不受影响。

* **Kubernetes 部署**不要跑浮动 tag：保持 Teable 镜像钉版，**每次更新时主动
  上调钉定的版本号**。部署仓库自带的 `pin-image.sh` 可解析 `latest` 当前
  对应的具体版本。

## 最佳方式：整个平台一起升

全功能部署有两条版本线 —— Teable 应用与平台本身(见[架构](/zh/deploy/architecture))。
最可靠的节奏是把两条线绑在一起，以
[`VERSIONS.md`](https://github.com/teableio/teable-deployment/blob/main/VERSIONS.md)
为升级清单，每轮：

1. 把运行平面升到**最新平台版本**(`v<年>.<月>.<序号>`)：每个 git tag 都是
   全部运行面组件的已验证快照，对应的
   [`CHANGELOG.md`](https://github.com/teableio/teable-deployment/blob/main/CHANGELOG.md)
   条目写明变了什么、你需要做什么（多数版本可热切换）。操作时从 checkout 到
   该 tag 的仓库副本进行；
2. 把 Teable 应用钉到 **`latest` 当前对应的具体版本号**(`pin-image.sh`
   可解析)—— 用钉定的已验证组合替代浮动通道；
3. 跑自带的 **doctor** —— 检查健康状态，并把实际运行的组合与平台版本清单
   比对（兼容 / 需升级 Teable 应用 / 未知组合）。

## 必填密钥

Teable 不再回退到内置的默认密钥。此前依赖这些默认值的部署，升级后第一次启动会中止，并列出需要配置的环境变量，以及一段可直接复制的配置块，它能让现有会话、令牌和已加密数据继续可用。补齐后重启，再安排一次轮换。详见[密钥与轮换](/zh/deploy/env#密钥与轮换)。

## 数据库迁移

Teable 启动时自动执行数据库迁移，无需人工干预。如升级后出现异常，先查日志：

```bash theme={null}
docker compose logs teable | grep -i migration
```

## 回滚

如果升级后遇到问题：

1. 将 `docker-compose.yaml` 中的镜像 tag 改回上一个版本号
   (这正是钉版优于 `latest` 的原因：上一个版本是白纸黑字记着的);
2. `docker compose up -d`

<Warning>
  若某次升级执行过数据库结构迁移，直接回滚可能不安全 —— 此时应从升级前的备份恢复。
  这也是上文强烈建议备份的主要原因。
</Warning>

## 常见问题

<Accordion title="更新后会丢失数据吗？">
  不会。您的数据存储在 Docker 卷或外部数据库中，更新容器不会影响数据。但仍建议在更新前备份。
</Accordion>

<Accordion title="更新后 Instance ID 会变化吗？">
  不会。应用更新期间 Instance ID 保持不变，它是您私有化安装的永久标识。
</Accordion>

<Accordion title="更新需要多长时间？">
  通常拉取新镜像需要几分钟（取决于网速），容器重启只需几秒。整个过程一般在 5-10 分钟内完成。
</Accordion>

<Accordion title="更新期间服务会中断吗？">
  使用 `docker compose up -d` 会有短暂的服务中断（通常几秒到几十秒）。
</Accordion>

<Accordion title="如何查看当前运行的版本？">
  您可以通过以下方式查看当前版本：

  * 查看 Teable 界面左下角的版本号
  * 使用管理员账号访问管理面板
  * 运行 `docker inspect <容器名> --format='{{.Config.Image}}'` 查看镜像版本。若您运行的是 `latest` 通道，全功能部署自带 `pin-image.sh` 工具可解析 `latest` 当前对应的具体版本。
</Accordion>

<Accordion title="更新失败怎么办？">
  1. 先查看容器日志排查：`docker compose logs teable`
  2. 如果是数据库迁移问题，尝试从备份恢复
  3. 问题持续存在时，回滚到上一版本
  4. 联系支持：[support@teable.ai](mailto:support@teable.ai)
</Accordion>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.