由于 Zitadel 团队决定将数据库从 CockroachDB 迁移到 PostgreSQL(参考https://zitadel.com/blog/move-to-postgresql,我阅读时版本为:Last updated on Jun 5, 2025 by Silvan),并且从 V3 版本开始进行断崖式兼容…这个操作几乎会让所有需要将 zitadel 从 v2 更新到 v3 的人踩坑。而我,正好是在 V2 选择了 CockroachDB 的人之一,所以理所当然的折腾了一段时间。
由于笔记具有时效性,我也不能市场维护每一篇笔记,所以可能存在时间推移部分问题有了新的变化的情况。在阅读此笔记之前请先阅读官方文档~
操作背景
由于我的 Zitadel 使用 Docker Compose 部署,所以操作起来相对地容器化,也有着更小的试错成本。而我的 Zitadel、数据库 均部署在一个 Compose 中,这个形式的部署使各种数据备份与回滚都更为容易。
#第一步,备份
这里分享一个部署技巧,在使用 Docker Compose 部署服务的时候,我建议的目录结构如下:
1/zitadel2 /data3 ... # 里面存放各种数据4 /config5 ... # 里面存放各种配置6 .env # 这个文件放置环境配置,若配置不复杂我还是会选择写进 compose 文件中而不是独立一个文件7 compose.yml # Docker compose 文件 而一些需要持久化存储的数据,就可以放在 data 目录下了。Docker Compose 中可以使用 volumes 属性自定义这个路径。例如我会写:
1...zitadel2 volumes:3 - ./services/zitadel/config.yaml:/config.yaml4 - ./services/zitadel/init-steps.yaml:/init-steps.yaml5...postgres6 volumes:
7 - ./data/postgres:/var/lib/postgresql/data好了,在这个情况下,如需针对所有配置文件以及数据进行备份,可以备份整个 /zitadel 文件夹,而若仅需备份数据,则备份 /zitadel/data 即可。回滚数据、迁移数据同理。
在对整个文件夹进行备份后,我将进行下一步操作。
备份后由于后续需要使用 zitadel cli 对数据库进行迁移,我们需要保持原有 Zitadel 服务的开放(但此时最好在 WAF 或者出口关闭外部对 Zitadel 的访问,以减少 Zitadel 持续往数据库写入新的数据的频率。
第二步,环境
迁移过程中可能会遇到许多乱七八糟的 bug,而且很多迁移 bug 仍然在被持续修复中,所以建议在执行迁移前将你的 Zitadel 更新到最新的 2.X.X 版本。(2.X.X 的最新版,3.X.X 放弃了对 CockroachDB 的支持,会导致实例无法启动从而无法迁移)最新版本可以从这里翻一下:https://github.com/zitadel/zitadel/tags
目前 2025 年 6 月 我能看到的最新是 v2.71.12:
正在加载图片...
在 Docker Compose 的 image 指定版本后,拉取镜像并重启容器即可。
1docker compose pull && docker compose down && docker compose up我建议是在执行此类更新后,docker compose up 不加 -d 以让实例在台前运行,以方便查看实例是否正常工作。若能正常工作,可以使用 Ctrl + C 关闭实例。
第三步,创建新数据
我的原有 Docker Compose 文件如下:
1services:2 zitadel:
3 restart: 'always'
4 networks:
5 - 'zitadel'
6 image: 'ghcr.io/zitadel/zitadel:v2.71.12'
7 command: 'start-from-init --config /config.yaml --steps /init-steps.yaml --masterkey "${ZITADEL_MASTERKEY}" --tlsMode external'
8 environment:
9 - 'ZITADEL_DATABASE_COCKROACH_HOST=crdb'
10 - 'ZITADEL_EXTERNALSECURE=false'
11 depends_on:
12 crdb:
13 condition: 'service_healthy'
14 ports:
15 - '8080:8080'
16 hostname: zitadel
17 container_name: zitadel
18 volumes:
19 - ./config/zitadel/config.yaml:/config.yaml
20 - ./config/zitadel/init-steps.yaml:/init-steps.yaml21 22 crdb:
23 restart: 'always'
24 networks:
25 - 'zitadel'
26 image: 'cockroachdb/cockroach:latest-v24.2'
27 command: 'start-single-node --insecure'
28 healthcheck:
29 test: ["CMD", "curl", "-f", "http://localhost:8080/health?ready=1"]
30 interval: '10s'
31 timeout: '30s'
32 retries: 5
33 start_period: '20s'
34 container_name: cockroachdb
35 volumes:
36 - ./data/cockroachdb:/cockroach/cockroach-data:rw
37 ports:
38 - '9090:8080'
39 - '26257:26257'40
41networks:
42 zitadel:官方文档中介绍需要先启动目标数据库,但其实按照官方指引重新拉一个 docker-compose 会导致当前 zitadel 与新的数据库环境网络不互通的问题。所以在此,我在我的原有 Docker Compose 加上了新的数据库配置文件:
1 db:
2 restart: 'always'
3 image: postgres:17-alpine
4 environment:
5 PGUSER: postgres
6 POSTGRES_PASSWORD: postgres
7 networks:
8 - 'zitadel'
9 healthcheck:
10 test: ["CMD-SHELL", "pg_isready", "-d", "zitadel", "-U", "postgres"]
11 interval: '10s'
12 timeout: '30s'
13 retries: 5
14 start_period: '20s'这样可以保证新的数据库与原有 Zitadel 服务处于同一个网络,不用去配置网络环境啦。此外,这里的 POSTGRES_PASSWORD 根据所需情况进行修改,如果你没有将这个服务映射到容器之外,可以考虑不修改密码。
#第四步,研究配置文件
根据仔细研究,配置文件其实分为了三份:
- 当前 zitadel 的 config,我命名为
config.yaml - 迁移后的 zitadel config,我命名为
config-new.yaml - 迁移 config,我命名为
config-mirror.yaml
这三个 config 我都放在了 <zitadel 目录>/config/zitadel/*.yaml
正在加载图片...
这三个 config 分别用在:
config.yaml当前 zitadel 的启动config-new.yaml新环境初始化(迁移后的 config)config-mirror.yaml新旧数据库迁移配置(迁移 config)
config.yaml
其实在整个迁移过程中不会使用到这个文件,仅用于当前(旧实例)启动使用。
#config-new.yaml
这个是新实例的配置,后面会用到此文件用于初始化。
我的配置使用了默认配置,注意这个配置文件里的 Database 部分需要填写新的数据库信息。
当然也可以拷贝旧的 config 并修改数据库为新的数据库信息,并保存为新的 config。
#config-mirror.yaml
这个配置是描述了将旧的数据库迁移到新数据库的配置信息,仅在迁移时使用。默认配置参考官方文档:https://zitadel.com/docs/self-hosting/manage/cli/mirror#configuration。
官方默认配置介绍中 Source 同时包含了 cockroach 和 postgres,因为这个迁移不但可以从 cockroach 迁移数据到 postgres,也可以将 postgres 中的 zitadel 数据迁移到另外一个 postgres 实例。但本次我们需要将数据从 cockroach 迁出,所以我们应该删除 Source 中 postgres 的部分。
接下来需要在 Source 的 cockroach 填入原数据库的连接信息,并在 Destination 的 postgres 填入目标数据库的连接信息。
#第五步,开始迁移
#迁移前检查
迁移中我们需要使用 Zitadel Cli,而 Zitadel Cli 存在于 Zitadel 实例中,也就是说 Zitadel 需要:
- 正常运行。由于我们只对实例进行更新,所以他是正常运行的。
- 可以同时连接新、旧数据库。
- 能够够得着我们刚才建的配置文件(config)
由于我们只对实例进行更新,所以他是正常运行的,问题 1 解决;由于新、旧数据库均通过同一个 Compose 挂载在统一网络,所以没问题,问题 2 解决;接下来我们看问题 3:
由于我们的文件存储在<zitadel 目录>/config/zitadel/*.yaml,我们可以通过映射的方式将问题映射到 Zitadel 运行目录内。我们来修改 compose 文件:
1services:2 zitadel:3 ...原有配置保持4 volumes:5 - ./config/zitadel/config.yaml:/config.yaml6 - ./config/zitadel/config-new.yaml:/home/config-new.yaml7 - ./config/zitadel/config-mirror.yaml:/home/config-mirror.yaml8 - ./config/zitadel/init-steps.yaml:/init-steps.yaml我新增了第 6 行、第 7 行。将两份配置文件映射到 Zitadel 的 /home/ 中。这样 Zitadel 实例就能很方便的够得着新的配置文件了。
#开始迁移
此时我们启动实例:docker compose up -d
接下来有个问题:Zitadel Cli 如何调用呢?
我尝试过 docker exec -it zitadel sh、docker exec -it zitadel bash、docker exec -it zitadel /bin/sh、docker exec -it zitadel /bin/ash 均不奏效,最后发现…需要使用docker exec -it zitadel /app/zitadel
也就是说,官方推荐的 zitadel init、zitadel setup 等指令在 Docker 的用法应该是docker exec -it zitadel /app/zitadel init、docker exec -it zitadel /app/zitadel setup
接下来的每一步都需要留意,检查日志是否有警告、报错等信息
需要注意的点:
- config 是否出现 内容读取异常、config 文件读取失败、文件不存在问题
- 是否出现数据库连接失败、密码错误问题
以上问题我都遇到过,不过这大抵是密码填错了、网络不通、路径写错的问题,并不是一个很困难的无解 bug。
初始化目标
首先我们来初始化目标,需要用到如下两个指令:
1docker exec -it zitadel /app/zitadel init --config /home/config-new.yaml
2docker exec -it zitadel /app/zitadel setup --for-mirror --config /home/config-new.yaml --masterkey <这里需要填写你原有实例的 master key>如果你的 config 映射在了其它地方,可以自行修改路径。
#数据迁移
1docker exec -it zitadel /app/zitadel mirror --system --config /home/config-mirror.yaml --masterkey <这里需要填写你原有实例的 master key>如果显示数据冲突,例如以下日志:
1[root@jimmy-pv-env-4d452f zitadel-mg]# docker exec -it zitadel /app/zitadel mirror --system --config /home/config-mirror.yaml
2INFO[0000] starting to copy assets caller="/home/runner/work/zitadel/zitadel/cmd/mirror/system.go:49"
3FATA[0000] unable to copy assets to destination caller="/home/runner/work/zitadel/zitadel/cmd/mirror/system.go:90" error="ERROR: duplicate key value violates unique constraint "assets_pkey" (SQLSTATE 23505)"可以检查数据库内容是否有冲突。我找到的解决方案是在数据迁移指令后加上--replace以强制覆盖重复项,但这可能会造成数据异常或丢失。迁移后请检查数据完整性以及系统运行稳定性。
迁移检查
1docker exec -it zitadel /app/zitadel mirror verify --system --config /home/config-mirror.yaml --masterkey <这里需要填写你原有实例的 master key>接下来,你的迁移工作就完成了,但此时还不能运行。
#第六步,收尾工作
由于数据库已经迁移,我们需要将旧实例停止并将数据库指向新迁移的数据库,所以需要做如下工作:
#停止当前 compose 下的所有实例
进入 Zitadel 文件夹,运行docker compose down
更新配置文件
在更新配置文件之前,我建议对当前状态再进行一个备份,作为“迁移后备份”
- 将旧的
config.yaml移除,将新的config-new.yaml改名为config.yaml - 移除不再使用的
config-mirror.yaml - 从 docker compose 中移除旧的数据库实例
- 检查
.env、compose.yaml、config.yaml是否仍然存在指向旧的数据库配置,如有将其指向新的数据库
运行新实例
在 Zitadel 文件夹中运行 docker compose up ,检查后台是否出现需要解决的错误,检查所有功能是否正常。
清理残留
可以根据需求自行选择是否清理:
- 旧的数据库 image
- 可能存在的 zitadel 旧镜像
- 旧数据库的文件内容
擦掉瑕疵
postgres 可能会出现报错 FATAL: role "root" does not exist,根据观察这大概是 10s 报一次,非常的烦。
不过 Zitadel Maintainer 表示这不是它们的锅:https://github.com/zitadel/zitadel/discussions/7832
根据解决方法,在 postgres 中的 env 加上 PGUSER=postgres 这个配置确实可行。