abrahamleal/ccloud-schema-exporter

Schema Exporter for Confluent Schema Registry

!Build Status !Quality Gate

镜像概述和主要用途

该工具通过REST API在Confluent Schema Registry之间导出模式，支持五种操作模式：batchExport、sync、getLocalCopy、fromLocalCopy和schemaLoad。可用于自托管Schema Registry之间的模式迁移，也支持本地备份与恢复操作。若需在本地部署与Confluent Cloud之间迁移模式，建议参考Confluent Replicator。

核心功能和特性

五种操作模式

• sync：持续同步新注册的模式到目标Registry
• batchExport：一次性迁移模式，完成后将目标Registry重置为READWRITE模式
• getLocalCopy：从源Registry获取模式并保存本地副本
• fromLocalCopy：将getLocalCopy获取的本地副本写入目标Registry
• schemaLoad：从本地目录加载模式到Registry

其他特性

• 支持通过环境变量或命令行参数配置认证信息（命令行参数优先级更高）
• 提供模式过滤功能（允许/禁止列表）
• 支持同步软删除和硬删除（需Confluent Cloud或Confluent Platform 6.1+）
• 可暴露Prometheus格式监控指标
• 支持自定义源和目标实现

使用场景和适用范围

• 自托管Schema Registry之间的模式迁移
• 模式的本地备份与灾难恢复
• 持续同步新注册的模式到目标环境
• 从本地文件系统加载模式到Schema Registry
• 需要监控模式同步状态的场景

使用方法和配置说明

环境变量

工具需要以下环境变量（根据模式不同可能不需要全部变量）：

注意：使用-getLocalCopy和-customDestination时不需要DST_*变量；使用-fromLocalCopy、-schemaLoad和-customSource时不需要SRC_*变量。

Docker运行示例

bash
docker run \
  -e SRC_SR_URL=$SRC_SR_URL \
  -e SRC_API_KEY=$SRC_API_KEY \
  -e SRC_API_SECRET=$SRC_API_SECRET \
  -e DST_SR_URL=$DST_SR_URL \
  -e DST_API_KEY=$DST_API_KEY \
  -e DST_API_SECRET=$DST_API_SECRET \
  abrahamleal/ccloud-schema-exporter:latest

注：Docker镜像默认处理-sync -syncDeletes -syncHardDeletes -withMetrics -noPrompt的持续同步模式。一次性导出建议使用发布二进制文件。如需传递自定义参数，可通过--entrypoint覆盖入口点，例如：--entrypoint "/ccloud-schema-exporter -batchExport"

不同模式的运行命令

批量导出

bash
./ccloud-schema-exporter -batchExport
# v1.1+支持同步软删除
./ccloud-schema-exporter -batchExport -syncDeletes

持续同步

bash
./ccloud-schema-exporter -sync

本地备份

bash
./ccloud-schema-exporter -getLocalCopy
# 默认备份目录：{当前路径}/SchemaRegistryBackup/

从本地备份恢复

bash
./ccloud-schema-exporter -fromLocalCopy
# 默认读取目录：{当前路径}/SchemaRegistryBackup/（递归查找）

从本地目录加载模式

bash
./ccloud-schema-exporter -schemaLoad AVRO -localPath /path/to/schemas

优先级：当指定多个模式时，优先级顺序为 sync -> batchExport -> getLocalCopy -> fromLocalCopy -> schemaLoad

命令行选项

bash
Usage of ./ccloud-schema-exporter:

  -allowList value
    	允许的模式主题列表，支持逗号分隔或文件路径
  -batchExport
    	执行一次性模式导出
  -customDestination string
    	自定义目标实现名称
  -customSource string
    	自定义源实现名称
  -deleteAllFromDestination
    	删除目标Registry中所有已写入的模式（忽略允许/禁止列表）
  -dest-sr-key string
    	目标Schema Registry的API密钥
  -dest-sr-secret string
    	目标Schema Registry的API密钥密码
  -dest-sr-url string
    	目标Schema Registry的URL
  -disallowList value
    	禁止的模式主题列表，支持逗号分隔或文件路径
  -fromLocalCopy
    	从本地备份注册模式（默认目录：SchemaRegistryBackup）
  -getLocalCopy
    	备份源Registry模式到本地（默认目录：SchemaRegistryBackup）
  -localPath string
    	本地操作的自定义路径（必须是已存在的目录）
  -noPrompt
    	禁用交互检查（需确保目标Registry模式和兼容性正确）
  -schemaLoad string
        加载的模式类型（当前支持：AVRO）
  -scrapeInterval int
    	同步检查间隔时间（秒，默认60）
  -src-sr-key string
    	源Schema Registry的API密钥
  -src-sr-secret string
    	源Schema Registry的API密钥密码
  -src-sr-url string
    	源Schema Registry的URL
  -sync
    	持续同步模式
  -syncDeletes
    	同步源集群的软删除到目标
  -syncHardDeletes
    	同步源集群的硬删除到目标
  -timeout int
    	REST调用超时时间（秒，默认60）
  -usage
    	打印工具使用说明
  -version
    	打印版本信息并退出
  -withMetrics
    	在:9020/metrics暴露Prometheus格式指标

示例用法

bash
export SRC_SR_URL=XXXX
export SRC_API_KEY=XXXX
export SRC_API_SECRET=XXXX
export DST_SR_URL=XXXX
export DST_API_KEY=XXXX
export DST_API_SECRET=XXXX
./ccloud-schema-exporter <-sync | -batchExport | -getLocalCopy | -fromLocalCopy>

过滤导出

所有模式（-sync/-batchExport/-getLocalCopy/-fromLocalCopy）均支持通过以下参数过滤主题：

• -allowList：允许的主题列表，支持逗号分隔字符串或文件路径（文件需有扩展名，如.txt）
• -disallowList：禁止的主题列表，格式同上

优先级：同时在允许和禁止列表中的主题将被禁止；-deleteAllFromDestination不尊重过滤列表

同步硬删除说明

v1.1版本起支持高效同步硬删除，需满足以下条件：

• 源和目标均为Confluent Cloud Schema Registry或Confluent Platform 6.1+

注意：-syncDeletes仅同步软删除，同样要求Confluent Cloud或Confluent Platform 6.1+环境；若环境不支持，工具将仅同步未来检测到的软删除。

非交互运行

工具默认包含以下检查，可通过-noPrompt禁用（Docker镜像默认启用）：

1. 目标Schema Registry处于IMPORT模式（必要条件）
2. 同步硬删除时，源和目标均为Confluent Cloud Schema Registry（必要条件）
3. 目标Schema Registry全局兼容性模式为NONE（建议设置，因无法确定每个主题的兼容性规则）

建议首次同步时将目标兼容性设为NONE，完成后恢复为源的兼容性级别。修改模式方法参考Schema Registry API文档。

可扩展性：自定义源和目标

工具支持通过实现CustomSource或CustomDestination接口扩展源和目标：

接口定义

go
type CustomSource interface {
	// 同步/批量导出前的初始化
	SetUp() error
	// 从源获取指定主题和版本的模式
	GetSchema(subject string, version int64) (id int64, stype string, schema string, references []SchemaReference, err error)
	// 获取源的状态（主题及版本列表）
	GetSourceState() (map[string][]int64, error)
	// 同步/批量导出后的清理
	TearDown() error
}

type CustomDestination interface {
	// 同步/批量导出前的初始化
	SetUp() error
	// 在目标注册模式
	RegisterSchema(record SchemaRecord) error
	// 在目标删除模式
	DeleteSchema(record SchemaRecord) error
	// 获取目标的状态（主题及版本列表）
	GetDestinationState() (map[string][]int64, error)
	// 同步/批量导出后的清理
	TearDown() error
}

注册自定义实现

需修改cmd/ccloud-schema-exporter/ccloud-schema-exporter.go中的工厂映射：

go
var sampleDestObject = client.NewSampleCustomDestination()
var customDestFactory = map[string]client.CustomDestination{
	"sampleCustomDestination": &sampleDestObject,
	// 添加自定义目标实现：名称 -> 实例
}
var apicurioObject = client.NewApicurioSource()
var customSrcFactory = map[string]client.CustomSource{
	"sampleCustomSourceApicurio": &apicurioObject,
	// 添加自定义源实现：名称 -> 实例
}

使用自定义实现

通过-customSource或-customDestination指定实现名称，例如：

bash
./ccloud-schema-exporter -customSource sampleCustomSourceApicurio -sync

示例：工具内置Apicurio源实现，默认连接http://localhost:8081，可通过环境变量APICURIO_OPTIONS覆盖（格式：apicurioUrl=http://url:port;header=value）

模式加载

-schemaLoad支持从本地目录加载AVRO模式（需指定-localPath），特性包括：

• 递归查找目录中的模式文件
• 支持模式引用（内联引用默认支持）
• 版本控制：按文件名 lex 顺序注册版本（如orders_v1先于orders_v2）
• 引用版本：引用仅使用最新版本

引用格式示例

json
{
   "type" : "record",
   "namespace" : "io.leal.abraham",
   "name" : "myRecord",
   "fields" : [
      { "name" : "Name" , "type" : ["null", "io.leal.abraham.anotherReference"], "default": null },
      { "name" : "Age" , "type" : "io.leal.abraham.singleReference" }
   ]
}

引用的全名（如io.leal.abraham.anotherReference）需对应目录中存在的模式文件。

监控

通过-withMetrics选项在:9020/metrics暴露Prometheus格式指标，samples目录提供Grafana仪表板示例。

功能请求/问题报告

通过GitHub Issues提交功能请求或问题报告，也可提交PR贡献代码。