teableio/teable-db-migrate

Teable应用自动迁移镜像

镜像概述

Teable应用自动迁移镜像是一款专为Teable协作表格工具设计的数据迁移工具，通过自动化流程实现Teable实例间的表结构同步与数据迁移，减少手动操作成本，确保迁移过程的准确性和高效性，适用于应用升级、环境迁移等场景。

核心功能与特性

• 表结构自动迁移：智能识别源Teable实例中的表格结构（字段类型、约束、视图配置等），自动在目标实例中创建或更新对应结构，支持字段映射自定义。
• 全量/增量数据同步：支持全量数据迁移（首次迁移）与增量数据同步（后续更新），增量模式基于updated_at字段追踪变更，减少重复传输。
• 跨版本兼容性：适配Teable v1.x至最新版本，自动处理不同版本间的结构差异，无需手动适配版本特性。
• 迁移过程可视化：实时输出迁移进度日志（包含结构检测、数据传输、校验结果），支持debug级别日志用于问题排查。
• 灵活配置能力：通过环境变量或配置文件自定义迁移规则，如字段过滤、数据转换规则、迁移超时时间等。

使用场景与适用范围

• Teable版本升级：从低版本Teable迁移至新版本时，自动处理表结构变更与历史数据迁移。
• 跨环境数据同步：开发/测试环境与生产环境间的Teable数据同步，确保测试环境数据与生产一致。
• 多实例数据整合：合并多个Teable工作空间的表格数据，或向新实例迁移指定表格。
• 灾备与数据备份：定期将生产环境Teable数据迁移至备份实例，保障数据安全性。

使用方法与配置说明

基础使用（Docker Run命令）

bash
docker run -d \
  --name teable-migrate \
  -e SOURCE_TYPE="teable" \
  -e SOURCE_URL="https://source-teable.example.com/api" \
  -e SOURCE_API_KEY="sk_source_xxxxxx" \
  -e TARGET_TYPE="teable" \
  -e TARGET_URL="https://target-teable.example.com/api" \
  -e TARGET_API_KEY="sk_target_xxxxxx" \
  -e MIGRATE_MODE="full" \
  teable/auto-migrate:latest

核心环境变量配置

迁移流程说明

1. 连接验证：容器启动后，通过SOURCE_URL和SOURCE_API_KEY验证源Teable实例访问权限，同理验证目标实例。
2. 结构检测：扫描源实例中符合TABLE_FILTER的表格，提取结构信息（字段、视图、权限等），与目标实例对比生成差异报告。
3. 结构同步：根据差异报告，在目标实例中创建新表格、新增/修改字段（如需删除操作，需设置ALLOW_DELETE=true）。
4. 数据迁移：
   • 全量模式：迁移源表格所有数据至目标实例。
   • 增量模式：仅迁移源实例中updated_at字段晚于上次迁移时间的数据（首次执行等同于全量）。
5. 结果校验：迁移完成后，自动对比源与目标数据条数及关键字段值，输出校验结果日志（info级别）。

注意事项

• 迁移前需确保源/目标Teable实例已在「设置-API访问」中开启API权限，并生成有效API密钥。
• 增量迁移依赖源表格的updated_at字段，需确保源表格已启用该字段记录更新时间。
• 大规模数据迁移建议在业务低峰期执行，并通过LOG_LEVEL=debug开启详细日志以便问题排查。
• 生产环境迁移前建议先通过测试环境验证迁移规则，避免数据异常。