SSD Nodes Learn Hosting plans →
指南 Matt Connor作者: Matt Connor

如何在 VPS 上用 Docker 自托管 Zitadel

Zitadel 本身约需 512MB 内存。本文介绍在一台 VPS 上配置 PostgreSQL、masterkey、TLS、SMTP 和备份,并说明升级会如何处理数据库。

在 VPS 上自行托管 Zitadel 的要求

要在 VPS 上自行托管 Zitadel,您需要 Docker 主机、指向该主机的公网 DNS 名称、PostgreSQL,以及足够运行这两者的 CPU 和 RAM。Zitadel 的生产指南指出,应用本身大约需要 512 MB RAM,CPU 使用量低于 1 个核心。资源增长主要来自数据库和密码哈希计算。Zitadel 是身份提供商。它通过 OIDC(OpenID Connect)和 SAML(security assertion markup language)签发令牌,使其他服务不再需要各自维护用户列表。安装由一个 curl 和一个 docker compose up 组成。决定实例能否稳定运行的部分包括主密钥、数据库用户、SMTP(simple mail transfer protocol)、备份,以及第一次升级。

以下内容假设您使用 Ubuntu 24.04、Docker Engine 24 或更高版本,并安装了 2.24.4 或更高版本的 Compose 插件,同时已有类似 auth.example.com 的名称解析到该服务器。TLS 覆盖配置使用 !override,因此需要满足上述 Compose 版本要求。

Zitadel 需要多大的 VPS?

Zitadel 文档中的 Compose 快速入门要求 2 GB 内存。这个数值针对的是快速入门环境。Zitadel 的生产指南给出了不同的数值。

图表Zitadel's own published sizing guidance, October 2026
此图表背后的数据
[
  {
    "config": "Zitadel itself, under 1 core",
    "cpu_cores": 0.5,
    "ram_gb": 0.5
  },
  {
    "config": "HA node, reduced setup",
    "cpu_cores": 4,
    "ram_gb": 8
  },
  {
    "config": "HA node, logs and metrics on",
    "cpu_cores": 4,
    "ram_gb": 16
  }
]

这些是文档公布的建议值,不是从正在运行的服务器上测得的数据。应将其理解为资源需求的构成。Zitadel 进程本身占用较少:指南给出的内存需求约为 0.5 GB,并说明它可以在不到 1 个 CPU 核心的环境中运行。CPU 核心主要用于密码哈希。密码哈希本来就需要较长时间,因此登录请求突增时会表现为 CPU 峰值。指南建议为此保留 4 个 CPU 核心。PostgreSQL 是另一项主要开销:同一份指南按每 100 个请求/秒约需 1 个 CPU 核心、每个核心配备 4 GB 内存进行估算。

下面两行较大的数值不是单机配置。对于最小的高可用部署,指南建议使用 3 个节点的集群,每个节点配备 4 个核心和 16 GB 内存。如果不启用日志收集和指标功能,则每个节点可减少到约 4 个核心和 8 GB 内存。指南没有给出单节点部署的配置建议。

因此,2 GB 的 VPS 可以启动这套服务,但当实际流量到来后,它远低于指南仅为数据库预留的资源。登录服务是其他所有服务依赖的组件。它停止运行时,所有信任该服务的应用都无法允许用户登录。若您认为为身份验证支付指南建议的数据库和密码哈希资源成本过高,现在做出这个决定是合理的;这也比迁移后再调整便宜得多。Keycloak、Authentik 和 Zitadel 的对比介绍了它们各自的内存成本和运维工作量,自托管 Authentik 服务器则通常适合资源较小的服务器。

获取堆栈并固定版本

mkdir zitadel-compose && cd zitadel-compose
curl -fsSLO https://raw.githubusercontent.com/zitadel/zitadel/main/deploy/compose/docker-compose.yml
curl -fsSLO https://raw.githubusercontent.com/zitadel/zitadel/main/deploy/compose/.env.example
cp .env.example .env
chmod 600 .env

该文件定义了您实际会运行的 4 个服务。Traefik 是反向代理:它按路径路由,并通过后文的覆盖配置终止 TLS(transport layer security)。zitadel-api 是监听 8080 端口的 Go 二进制程序。zitadel-login 是在 /ui/v2/login 提供的登录界面。postgres 保存全部数据。同一文件中还定义了 Redis 缓存和 OpenTelemetry collector,但它们位于 Compose profiles 后面,默认不会启动,只有在您主动启用时才会运行。

现在不要运行 docker compose up。第一次启动会创建实例,下面的多个设置之后无法直接修改,需要额外处理。

您复制的 .env 会固定自身的镜像标签:

ZITADEL_VERSION=v4.16.0
TRAEFIK_IMAGE=traefik:v3.7.7
POSTGRES_IMAGE=postgres:17.10-alpine

当前 v4 版本是 v4.20.3,于 13 November 2026 发布,比随附文件中的固定版本高 4 个次版本。v4.20.0 之前的版本 v4.19.5 于 15 October 2026 发布,是 Zitadel 技术公告 A-10018 首次涵盖的版本:受影响的 v1 和 v2 API 列表端点现在会应用默认限制和最大限制,因此客户端不带限制进行列表查询时不再获得全部结果,而必须分页;请求超过最大限制时会被拒绝。之后的每个版本,包括 v4.20.0,都包含此变更。将 ZITADEL_VERSION 设置为您计划运行的版本,并使用 v4 系列,不要跟踪最新版本。若您手动选择版本,请跳过 v4.18.0:该版本的发行说明称 setup 步骤会失败,并建议改用 v4.19.0。上面的 curl 会从 main 分支拉取 docker-compose.yml,而该分支没有固定到任何版本,因此请将这两个文件的副本都提交到 git 仓库。否则,下个月在新主机上执行相同命令时会得到不同的文件,而您无法知道发生了什么变化。

将 .env 中的 LOGIN_SESSION_COOKIE_SECRET 替换为使用 openssl rand -base64 32 生成的随机值。Login UI 使用该值签名会话 cookie,v4.19.5 的发行说明明确警告不要保留示例值。

为 Postgres 创建专用用户并设置真实密码

随附的 .env 使用超级用户连接 Zitadel 和 PostgreSQL,密码为 postgres:

POSTGRES_ADMIN_USER=postgres
POSTGRES_ADMIN_PASSWORD=postgres
ZITADEL_DATABASE_POSTGRES_DSN=postgresql://postgres:postgres@postgres:5432/zitadel?sslmode=disable

这里的加固步骤有一个陷阱。Zitadel 文档要求将 POSTGRES_ZITADEL_PASSWORD 追加到 .env,但基础 docker-compose.yml 从不读取该变量,因此设置它不会产生任何效果。单独修改 POSTGRES_ADMIN_PASSWORD 反而会导致连接失败,因为密码也以字面值写在 DSN(数据源名称)字符串中。DSN 决定了 Zitadel 的连接方式。

.env.example 中的注释已经明确说明了其余事项:配置 DSN 后,Zitadel 会直接使用其中的用户,不会为您创建非特权用户。因此,该角色必须在首次启动前存在。为该角色生成密码,在启动 Postgres 前将 POSTGRES_ADMIN_PASSWORD 设置为 .env 中的另一个随机密码,然后单独启动 Postgres 并创建该角色。Postgres 镜像只会在初始化空数据目录时应用管理员密码;之后修改 .env 不会轮换现有数据库密码。

tr -dc A-Za-z0-9 </dev/urandom | head -c 32; echo

docker compose --env-file .env -f docker-compose.yml up -d postgres

docker compose --env-file .env -f docker-compose.yml exec -T postgres \
  psql -U postgres -d postgres <<'SQL'
CREATE ROLE zitadel LOGIN PASSWORD 'the-password-you-generated';
ALTER DATABASE zitadel OWNER TO zitadel;
SQL

这些 psql 调用在容器内通过本地套接字执行。官方 Postgres 镜像信任此连接,因此不会提示输入密码。关键在于所有权。Zitadel 的初始化阶段会创建自己的架构(eventstore、projections、system)和表。数据库所有权会授予该角色创建权限,使其能够初始化这些架构。PostgreSQL 15 对 public 架构 CREATE 权限的变更是另一回事,并不意味着 Zitadel 的架构初始化会失败。

现在将 DSN 指向新角色,并保留在启动 Postgres 前设置的管理员密码:

POSTGRES_ADMIN_PASSWORD=a-32-character-random-string
ZITADEL_DATABASE_POSTGRES_DSN=postgresql://zitadel:the-password-you-generated@postgres:5432/zitadel?sslmode=disable

sslmode=disable 会让数据库连接在私有 Compose 网络上保持未加密状态;其端口从不发布到主机。Zitadel 的数据库指南建议在生产环境的数据库连接中使用 TLS。首次完整启动后,检查该角色是否确实拥有自己的数据:

docker compose exec -T postgres psql -U zitadel -d zitadel -c '\dn'

输出中应列出一个 eventstore 架构、一个 projections 架构和一个 system 架构。如果缺少这些架构,说明初始化阶段尚未执行到这里;API 容器日志会说明原因。

主密钥及其丢失代价

Zitadel 会在存储密钥前先加密这些机密信息:身份提供商凭据、SMTP 密码、一次性密码种子和机器密钥。主密钥用于解密全部这些数据。主密钥固定为 32 字节。文档明确说明,修改主密钥会导致无法访问已加密的数据。

生成一个主密钥,并替换 .env 中的占位行:

tr -dc A-Za-z0-9 </dev/urandom | head -c 32; echo

请编辑 ZITADEL_MASTERKEY=MasterkeyNeedsToHave32Characters 所在的行,不要再追加一行。Compose 会采用重复键的最后一个定义,因此追加一行确实有效,但文件中存在两行主密钥配置,会给下一个读取该文件的人造成风险。

现在考虑主密钥的存储位置。Compose 文件会通过以下方式启动 API 容器:

command: start-from-init --masterkey "${ZITADEL_MASTERKEY}"

因此,主密钥会出现在容器的命令行参数中,任何能够访问 Docker socket 的人都可以通过 docker inspect 查看它。在只有一名管理员的 VPS 上,这是可以接受的取舍;.env 的权限模式负责保护磁盘上的文件。如果无法接受这种方式,请将主密钥挂载为文件,并改用 --masterkeyFile /run/secrets/zitadel-masterkey,这样主密钥值不会出现在进程参数中。

首次启动前,将主密钥复制到密码管理器中。主密钥不会出现在数据库转储中,因此使用不同的主密钥恢复转储后,实例将无法读取自己的机密信息。请将主密钥存放在保存转储的归档之外,避免一份被窃取的备份同时包含加密数据及其解密密钥。

首次启动前设置外部域名

ZITADEL_DOMAIN 中的 .env 会传入容器内的 ZITADEL_EXTERNALDOMAIN,这就是用户输入的名称。Zitadel 会根据它生成 OIDC issuer、登录界面基础 URI、SAML 端点和首个管理员的登录名,因此它不是装饰性配置。

ZITADEL_DOMAIN=auth.example.com
ZITADEL_EXTERNALPORT=443
ZITADEL_EXTERNALSECURE=true

Zitadel 根据 Host 请求头判断您要访问哪个实例。如果该请求头与已知域名不匹配,每个请求都会返回相同的结果:

ID=QUERY-1kIjX Message=Instance not found

看到此错误时,请检查两点。其中一种情况是,ZITADEL_DOMAIN 不是您正在访问的名称;另一种情况是,前置代理将 Host 重写成了上游地址。使用服务器 IP 地址而不是域名访问时,也会出现此错误。

之后可以修改这些值。Zitadel 必须重新运行设置阶段才能应用更改,而且已经注册的每个应用仍会保留旧的重定向 URI。现在选择最终名称,比之后迁移名称的成本低得多。

使用 Let's Encrypt overlay 终止 TLS

对于公网域名,添加 Zitadel 的 Let's Encrypt overlay。它会将 Traefik 切换为 ACME(自动证书管理环境)HTTP challenge,并将发布端口替换为 80 和 443,因此该服务器上的其他程序不能占用这两个端口中的任何一个。

curl -fsSLO https://raw.githubusercontent.com/zitadel/zitadel/main/deploy/compose/docker-compose.mode-letsencrypt.yml
echo 'LETSENCRYPT_EMAIL=ops@example.com' >> .env

该 overlay 还会在 API 容器上设置 ZITADEL_EXTERNALPORT: 443 和 ZITADEL_EXTERNALSECURE: true,因此公网 URL 与 Zitadel 为自身生成的 URL 保持一致。启动前,A 记录必须已经解析,因为没有该记录时 HTTP challenge 会失败。

如果已经在 nginx 或负载均衡器上终止 TLS,请改用 docker-compose.mode-external-tls.yml,并将 TRAEFIK_TRUSTED_IPS 设置为代理发送请求时使用的地址范围。Traefik 只接受来自该列表中地址的 X-Forwarded-* header。该 overlay 会明确将 Zitadel 的外部 URL 和登录 URL 设置为 HTTPS。

上游代理有两项 Zitadel 严格要求的工作。代理必须通过 HTTP/2 与后端通信,因为 API 使用 gRPC。代理还必须原样透传 Host 和 X-Forwarded-Proto: https。对于此 Compose stack,nginx 配置结构如下:

server {
    listen 443 ssl;
    http2 on;
    ssl_certificate     /etc/certs/selfsigned.crt;
    ssl_certificate_key /etc/certs/selfsigned.key;
    location /ui/v2/login {
        proxy_pass http://YOUR_LOGIN_UPSTREAM:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto https;
    }
    location / {
        grpc_pass grpc://YOUR_API_UPSTREAM:8080;
        grpc_set_header Host $host;
        grpc_set_header X-Forwarded-Proto https;
    }
}

将 upstream 占位符替换为 nginx 可以访问的地址。如果通过 443 以外的端口提供 Zitadel,请使用 grpc_set_header Host $host:$server_port;,以便将端口一并写入 header。其余部分是普通的 virtual host,逐行解读 nginx reverse proxy 配置介绍了与 Zitadel 无关的部分。

第一个管理员及强制修改密码

首次启动会创建一个实例、一个组织和一个人工管理员。登录名由 zitadel-admin@、zitadel. 和您的外部域名组成,因此使用 ZITADEL_DOMAIN=auth.example.com 时,登录名为:

zitadel-admin@zitadel.auth.example.com

如果您未设置自定义密码,密码就是 Password1!。Zitadel 的上游默认设置是在首次登录时强制修改密码,而随附的 compose 文件会覆盖此默认设置:

ZITADEL_FIRSTINSTANCE_ORG_HUMAN_PASSWORDCHANGEREQUIRED: false

该行硬编码在 docker-compose.yml 中,而不是从 .env 读取,因此请将自定义值放在您自己的小型覆盖文件中。将其命名为 docker-compose.local.yml:

services:
  zitadel-api:
    environment:
      ZITADEL_FIRSTINSTANCE_ORG_HUMAN_EMAIL_ADDRESS: you@example.com
      ZITADEL_FIRSTINSTANCE_ORG_HUMAN_PASSWORD: "a-long-temporary-password"
      ZITADEL_FIRSTINSTANCE_ORG_HUMAN_PASSWORDCHANGEREQUIRED: "true"

只有在运行 Compose 时未使用 -f 标志,Compose 才会自动加载 docker-compose.override.yml;而 Zitadel 指南中的每条命令都会传入 -f,从而禁用这一行为。与其重复一组不断增长的标志,不如在 .env 中固定文件列表:

COMPOSE_FILE=docker-compose.yml:docker-compose.mode-letsencrypt.yml:docker-compose.local.yml

现在启动它:

docker compose pull
docker compose up -d --wait

--wait 会一直持有该命令,直到健康检查通过。如果 API 容器始终无法通过健康检查,Compose 会以 dependency failed to start: container zitadel-zitadel-api-1 is unhealthy 停止,而 docker compose logs zitadel-api 中会记录具体原因。容器名称取自项目名称,随附的 compose 文件通过顶层 name: zitadel 自行设置该名称,因此不会显示目录名称。首次启动时,原因通常是 masterkey 长度或数据库 DSN。

在 https://auth.example.com/ui/console 登录,修改密码,然后为该账户启用第二因素,再创建其他内容。每个 ZITADEL_FIRSTINSTANCE_* 值只在创建第一个实例期间生效。实例创建后,再编辑这些值不会产生任何作用。

密码重置为何要等 SMTP 正常后才会生效

无法发送邮件的身份提供商,其故障可能会隐蔽数周。Zitadel 会发送用户邀请、地址验证、密码重置链接、一次性代码和域名声明通知。未配置 SMTP 提供商时,Console 仍会报告操作已完成,但消息会进入通知处理流程,却没有可用的发送目标。v4.20.0 默认使用传统模式(LegacyEnabled: true),该模式会忽略并行工作线程的 MaxAttempts: 3 和 MaxTtl: 5m 设置。这些值不表示默认的通知重试行为。等待链接的用户不会收到任何提示。

在 Console 中配置它,位置是实例设置下的 https://auth.example.com/ui/console/settings。SMTP 提供商表单要求填写发件人电子邮件地址、发件人名称、主机和端口、用户、SMTP 密码,以及 TLS 开关。保存前使用表单中的测试按钮,因为它会发送真实邮件:邮件要么到达,要么不到达。激活提供商,使 Zitadel 使用它发送邮件。

对应的环境变量包括 ZITADEL_DEFAULTINSTANCE_SMTPCONFIGURATION_SMTP_HOST 及其同组变量。它们只在创建实例时生效。对于已经运行的堆栈,这些变量不起作用,因此现有实例应在 Console 中配置。

从 VPS 发送邮件时,有两点需要注意,因为问题通常出在这里。选择中继前,检查提供商的出站 SMTP 策略:DigitalOcean 默认会阻止 Droplets 使用 25、465 和 587 端口,因此 587 端口并不是通用的解决方案。请使用提供商允许的端口,并通过身份验证的中继发送邮件。还应为发件域名发布 SPF(sender policy framework,发件人策略框架)和 DKIM(domainkeys identified mail,域名密钥识别邮件)记录,否则重置链接会进入垃圾邮件。对用户而言,这与邮件根本没有发送完全一样。

在 v4.20.0 中,出站 SMTP TLS 连接会拒绝经过已受损 eMudhra 中间 CA 的证书链。受影响的中继需要更换证书。

邀请用户前先验证流程。创建一个临时用户,请求密码重置,然后监控邮件是否到达。如果邮件没有到达,docker compose logs -f zitadel-api 会指出 SMTP 故障。SMTP 密码会以加密形式存储在数据库中;masterkey 还负责保护这一项数据。

分别备份 Postgres 和主密钥

Zitadel 的所有数据都存储在 PostgreSQL 中。用于解密这些数据的是主密钥。请将两者备份到不同位置。

先创建转储:

sudo install -d -m 700 /srv/zitadel-backups
docker compose exec -T postgres \
  pg_dump -U postgres -Fc zitadel > "/srv/zitadel-backups/zitadel-$(date +%F).dump"

-Fc 是自定义格式,导出时会压缩,pg_restore 可以按需读取其中的数据。exec -T 会退出终端模式,这一点很重要,因为该命令由 cron 执行,且没有附加终端。

然后使用 restic 将该目录推送到异地。restic 会加密数据并执行去重:

export RESTIC_REPOSITORY="sftp:backup@backup.example.com:/srv/restic/zitadel"
export RESTIC_PASSWORD_FILE=/root/.restic-password
restic init
restic backup /srv/zitadel-backups
restic forget --keep-daily 7 --keep-weekly 4 --keep-monthly 6 --prune

restic init 只在第一天运行一次。将转储和后面的两个命令放入 /usr/local/bin/zitadel-backup.sh,然后每天夜间运行:

0 3 * * * /usr/local/bin/zitadel-backup.sh

将 .env 以及使用的每个 Compose 文件都备份到 git 中。主密钥是唯一的例外。应将它存储在密码管理器中,并另存到不属于此 restic 仓库的第二个位置,因为如果数据库及其解密密钥位于同一个归档中,那么这个归档就不再是加密系统的备份。

未执行过恢复的备份只是猜测。请在同一台服务器上的临时数据库中执行恢复并检查内容:

docker compose exec -T postgres createdb -U postgres zitadel_restore_test
docker compose exec -T postgres pg_restore -U postgres -d zitadel_restore_test \
  < /srv/zitadel-backups/zitadel-2026-08-21.dump
docker compose exec -T postgres psql -U postgres -d zitadel_restore_test -c '\dt eventstore.*'
docker compose exec -T postgres dropdb -U postgres zitadel_restore_test

如果能列出 eventstore 架构中的表,说明转储有效。如果报错称该架构不存在,则说明转储无效;而且你能在不造成损失的情况下发现这个问题。备份和升级 Compose 堆栈的通用模式在这里几乎可以直接套用,只有将主密钥排除在同一归档之外是 Zitadel 特有的要求。

升级 Zitadel 且不丢失实例

升级是在 .env 中提升版本,然后执行 2 个命令:

docker compose pull
docker compose up -d --wait

在对供用户登录的实例运行这些命令前,请先了解第二个命令的作用。容器的命令是 start-from-init,它会在开始提供服务前运行 init 和 setup 阶段,而 setup 阶段负责执行数据库迁移。因此,版本提升会在容器启动时对生产数据库执行架构迁移,整个过程无人值守,同时 --wait 会等待健康检查通过。这正是上文的恢复测试不可省略的原因。

在升级前立即创建一次新的转储。昨晚的转储不是同一份备份。

对于 v4.20.3,正在进行的外部身份提供商登录必须重新开始,未兑换的 Login V1 授权码会被拒绝一次。自定义登录 UI 需要 session.link 权限才能完成 OIDC 或 SAML 请求;请在升级前向其服务用户授予 IAM_LOGIN_CLIENT。随附的 Login V2 服务用户已经拥有该角色。Session API 的密码检查现在会强制执行用户所属组织的登录策略,因此禁用用户名/密码登录的组织必须将用户转到其身份提供商。

不要跨越主版本升级。从 v3 升级到 v4 前,先升级到 v3.4.1 或更高版本。v4 要求必须启用 OIDC web keys,并移除了旧版签名路径。因此,如果您的 v3 实例从未启用 web keys,升级后使用旧版密钥签名的令牌将无法再验证。Zitadel 技术公告 A-10017 指出,现有的 JWT access tokens 和 ID tokens 可能立即失效,用户可能需要重新登录。其修复方法是先升级到 v3.4.1 或更高版本,并在升级前等待使用旧版密钥签名的令牌和会话过期;或者接受一个计划中的重新登录窗口。如果您已经运行 v3.4.1 或更高版本,并且在启用 web keys 后已经等待了足够时间,公告称无需采取措施。

使用 docker compose logs -f zitadel-api 监控 setup 阶段。大型 eventstore 的迁移可能需要数分钟,Traefik 在健康检查通过前不会将请求路由到 API,因此站点会在此期间中断。请提前规划,不要等到中断发生后才发现这一点。

回滚不是重新设置旧标签那么简单。迁移执行后,旧版二进制程序无法理解发现的数据库架构,因此回滚意味着恢复转储。当实例已经包含真实用户后,请迁移到 docker-compose.prodlike.yml;该覆盖配置会将 init 和 setup 作为独立于 start 的步骤运行,使迁移成为您主动触发并监控的操作,而不是容器重启的副作用。

应指向新的身份提供商的配置

在 Console 中创建一个项目,然后在其中创建一个应用。对于现代应用,选择 OIDC;Zitadel 会提供 client ID、client secret 和位于 https://auth.example.com/.well-known/openid-configuration 的 discovery document。大多数支持单点登录的自托管软件都需要这些信息。

许多软件不支持单点登录,或者只在付费层级中提供支持。对于前一种情况,在应用前部署 oauth2-proxy,即可让 Zitadel 保护任何 HTTP 服务。对于后一种情况,如果某项功能尚未付费,计划围绕该功能迁移前,建议阅读 自托管应用中的 SSO 费用门槛。

FAQ

自托管 Zitadel 需要多少 RAM 和 CPU?

Zitadel 的生产环境指南称,Zitadel 本身需要约 0.5 GB RAM,使用不到 1 个 CPU 核心也可以运行;同时建议为密码哈希保留 4 个核心。PostgreSQL 的资源需求需单独计算:大约每 100 个请求/秒需要 1 个核心,每个核心需要 4 GB RAM。指南中较大的数值是三节点高可用集群中每个节点的需求:每个节点需要 4 个核心和 16 GB RAM;如果不收集日志和指标,则约需 4 个核心和 8 GB RAM。Compose 快速入门要求至少 2 GB,这足以进行试用,但留给数据库的空间很少,而系统中的其他服务也可能依赖该数据库。

如果丢失 Zitadel masterkey,会发生什么?

使用该密钥加密的所有内容仍会保持加密状态。身份提供商凭据、SMTP 密码和一次性密码种子都无法解密,而且事后无法更换该密钥。仅有数据库转储无法恢复可用实例,因为转储中只有密文,没有密钥。请将 masterkey 存储在密码管理器中,并与保存数据库转储的备份分开存放。如果两者都丢失,只能从头重建实例。

为什么 Zitadel 的密码重置邮件始终收不到?

因为未配置 SMTP 提供商,或者已配置的提供商无法投递邮件。Zitadel v4.20.0 默认使用旧版通知处理方式,因此并行工作进程的 3 次尝试和 5 分钟设置不会生效。请在实例设置中配置 SMTP 提供商,并使用该表单中的测试按钮;该按钮会发送真实邮件。启用该提供商,使用 VPS 提供商允许的端口上的经过身份验证的中继,并为发信域名发布 SPF 和 DKIM 记录,避免邮件被过滤为垃圾邮件。

安装后可以更改 Zitadel 的外部域名吗?

可以,但不能只编辑 .env。请修改 ZITADEL_EXTERNALDOMAIN、ZITADEL_EXTERNALPORT 和 ZITADEL_EXTERNALSECURE,然后让 Zitadel 重新运行设置阶段,以应用这些更改。已注册的应用会保留旧的重定向 URI,必须手动更新;任何 Host 请求头与 Zitadel 已知域名不匹配的请求,都会收到 Instance not found。在首次启动前确定最终名称,可以避免这些问题。

这篇文章对您有帮助吗?