如何将云CockroachDB集群复制到本地Docker容器单节点集群

核心问题分析 #

你在本地执行SHOW BACKUPS IN '{S3_URI}'无结果，本质是本地Docker容器里的CockroachDB实例没有正确配置S3访问权限或网络权限，导致无法读取S3桶里的备份元数据。不用逐个导CSV，直接用官方的RESTORE命令就能批量恢复，步骤如下：

步骤1：给本地Docker容器配置S3访问权限 #

启动本地单节点集群时，必须把S3的访问凭证传递给容器，否则集群连不上S3。两种方式：

方式A：启动时直接传入环境变量 #

docker run -d \
  --name roach-local \
  -p 26257:26257 \
  -p 8080:8080 \
  -e AWS_ACCESS_KEY_ID=你的S3访问密钥ID \
  -e AWS_SECRET_ACCESS_KEY=你的S3私有访问密钥 \
  cockroachdb/cockroach:latest start-single-node --insecure

方式B：挂载本地AWS凭证文件 #

如果本地已经有~/.aws/credentials文件，直接挂载到容器里：

docker run -d \
  --name roach-local \
  -p 26257:26257 \
  -p 8080:8080 \
  -v ~/.aws/credentials:/root/.aws/credentials \
  cockroachdb/cockroach:latest start-single-node --insecure

步骤2：直接执行RESTORE命令恢复数据 #

不用依赖SHOW BACKUPS，直接连接本地集群执行恢复命令更可靠：

1. 连接本地集群：

cockroach sql --insecure --host=localhost:26257

2. 执行恢复命令（替换成你的S3 URI）：

-- 恢复整个集群的备份
RESTORE FROM 's3://你的桶名/备份路径' WITH aws_access_key_id='你的密钥ID', aws_secret_access_key='你的私有密钥';

-- 如果是指定数据库的备份，用这个
RESTORE DATABASE 你的数据库名 FROM 's3://你的桶名/备份路径/数据库备份子路径' WITH aws_access_key_id='你的密钥ID', aws_secret_access_key='你的私有密钥';

排查SHOW BACKUPS无结果的额外要点 #

如果一定要让SHOW BACKUPS生效，检查这几点：

• S3 URI完全一致：桶名、路径、大小写都要和CockroachLabs上用的一模一样
• 容器网络：确保Docker容器能访问外网（可以进入容器docker exec -it roach-local bash，然后用curl https://s3.amazonaws.com/你的桶名测试）
• 权限：S3凭证必须有s3:ListBucket（列出桶内容）和s3:GetObject（读取备份文件）的权限

替代方案：如果S3权限无法配置 #

如果暂时搞不定S3权限，用cockroach export/import批量操作，比逐个导CSV高效：

1. 从CockroachLabs集群导出整个数据库到本地：

cockroach export --insecure --host=你的CockroachLabs集群地址 --database=你的数据库名 --format=csv --output-dir=./local-backup

2. 把导出的文件复制到Docker容器：

docker cp ./local-backup roach-local:/local-backup

3. 本地集群执行导入：

IMPORT TABLE * FROM CSV '/local-backup/*.csv' WITH delimiter=',', header=true;

注意事项 #

• 本地CockroachDB版本必须和CockroachLabs集群版本完全一致，版本不兼容会导致恢复失败
• 确保本地Docker容器有足够的磁盘空间存储恢复的数据
• 如果备份是加密的，需要在RESTORE命令里加上encryption_passphrase='你的加密密钥'参数

内容的提问来源于stack exchange，提问作者Solstice