ZITADEL v4.19.5 介绍与选型指南

ZITADEL v4.19.5 介绍与选型指南：基于官方 GitHub 与文档站（查询日期 2026-10-18）梳理定位、事件溯源架构、多租户模型与功能全景，附与 Keycloak/Authelia/Authentik/Ory Kratos 的社区活跃度、版本节奏与协议支持量化对比及选型建议。认知篇不本地实测，部署实测见配套篇。

ZITADELZITADELIAMOIDC2026/10/18

ZITADEL v4.19.5 介绍与选型指南

目标：面向正在为自托管环境挑选身份与访问管理（IAM）平台的架构师与运维工程师，系统介绍 ZITADEL v4.19.5 的定位、架构、功能与同类竞品量化对比，并给出可落地的选型建议。本文为认知篇，全部内容基于官方 GitHub 仓库与官方文档站溯源编写，关键数据均标注来源与查询日期（2026-10-18），不做本地安装实测；部署实测见《ZITADEL Docker Compose 部署指南》。

一、环境信息

本篇为 A1 认知篇，不依赖本地环境实测，以下为本文全部信息的信息基准，读者可按此清单复核每个论断：

  • 信息查询日期：2026-10-18（所有版本号、社区数据、发布节奏均以当日实查为准）
  • 版本依据：GitHub Releases 页 https://github.com/zitadel/zitadel/releases/latest 于查询日 302 重定向至 releases/tag/v4.19.5，即 v4.19.5 为当前最新稳定版；该版本发布时间为 2026-10-15（来源：Releases Atom 订阅 https://github.com/zitadel/zitadel/releases.atom，条目 <updated>2026-10-15</updated>）
  • 官方来源清单：
    • GitHub 仓库：https://github.com/zitadel/zitadel（README、LICENSE、Releases）
    • 官方文档站：https://zitadel.com/docs/（本篇引用：Docker Compose 部署页、Database 页、APIs 概览页）
    • OpenID 认证名录：https://openid.net/certification/#OPs（README 徽章指向）
    • 竞品数据：github.com/keycloak/keycloak、github.com/authelia/authelia、github.com/goauthentik/authentik、github.com/ory/kratos（仓库页 stargazerCount 实查 + releases.atom 实查）
  • 软件身份：ZITADEL，开源身份与访问管理平台（Identity and Access Management），由 Caos AG（瑞士）主导开发并商业化，Go 语言编写，AGPL-3.0 许可（特定目录含 Apache 2.0 / MIT 例外，见仓库 LICENSING.md，查询日实查）

二、软件概述

ZITADEL（读作 "zitadel"）是一个开源的身份与访问管理平台，官方自我定位为 "The Identity Infrastructure for Developers"（开发者的身份基础设施）。它把登录认证（SSO）、多因素认证（MFA）、通行密钥（Passkeys）、协议对接（OIDC/SAML）、用户目录同步（SCIM）与多租户管理（B2B 组织）打包成一个单一 Go 二进制 + 一个 PostgreSQL 数据库的服务，可直接替代 Auth0/Okta 的自建方案。

v4.19.5 版本（2026-10-15 发布）的核心特征如下（来源：README 与 v4.19.5 源码树，查询日实查）：

维度值（v4.19.5 实查）
开发语言Go（单二进制，zitadel --version 输出 zitadel version v4.19.5）
许可证AGPL-3.0（apps/ 文档等目录为 Apache 2.0 / MIT 例外）
数据库PostgreSQL 14–18（官方 Database 文档："Currently, versions 14 to 18 are supported"）
支持协议OIDC（通过 OpenID 认证）、SAML 2.0、SCIM 2.0、LDAP（身份代理）
API 形态gRPC + connectRPC + REST（每个资源三类接口同源可用）
登录界面Login V2（Next.js 独立服务，端口 3000）+ 管理控制台 Console（内置于 API）
部署形态单机二进制、Docker Compose、Kubernetes（官方 Helm Chart）
云端/自托管ZITADEL Cloud 与自托管运行同一份代码库（README 明示）

💡 说明：ZITADEL 的命名来自瑞士联邦议会大厦（Bundeshaus "Zitadel"），项目起家于瑞士，因此对 GDPR/数据主权场景有天然的叙事优势——所有数据可完全落在自有 PostgreSQL 内。

三、核心架构

ZITADEL 的架构可以概括为「一个 API 进程 + 一个登录 UI 进程 + 一个 PostgreSQL」，理解它的关键在于三点：事件溯源内核、多租户层级、API-First 设计。

3.1 部署拓扑

官方 Docker Compose 部署（详见《ZITADEL Docker Compose 部署指南》）的组件拓扑如下：

用户/应用
   │  HTTP/HTTPS
   ▼
反向代理（Traefik，官方 compose 默认，80/443）
   │  h2c（gRPC/HTTP2 直通）
   ▼
┌─────────────────────────────┐
│ ZITADEL API（Go，端口 8080） │ ←→ 管理控制台 /ui/console（内置）
│  · OIDC/SAML/SCIM 端点      │ ←→ gRPC/REST 管理 API
│  · Session API              │
└─────────────────────────────┘
   │  SQL（事件追加 + 投影读模型）
   ▼
PostgreSQL 14–18（schemas：eventstore / projections / system）
   ▲
┌─────────────────────────────┐
│ ZITADEL Login（Next.js，3000）│ ←→ /ui/v2/login 登录界面
└─────────────────────────────┘

要点解读：

  • API 进程是单体：认证协议端点、管理 API、控制台静态资源都由同一个 8080 端口的 Go 进程提供，内部无微服务拆分，运维面非常小。
  • Login V2 是独立进程：v4 起默认登录界面是独立的 Next.js 应用（镜像 ghcr.io/zitadel/zitadel-login），通过一个专用的 login-client 机器账号 PAT 与 API 通信；它无状态，可水平扩展。
  • PostgreSQL 是唯一状态：官方 compose 里除 Redis 可选缓存外全部状态在 PostgreSQL，备份恢复即备份这一个数据库。

3.2 事件溯源内核

ZITADEL 的存储内核是事件溯源（Event Sourcing）：每一次用户创建、密码修改、策略变更都作为不可变事件追加写入 eventstore.events 表，再由投影（Projections）机制异步物化成查询友好的读模型表（projections.*）。

💡 技术拓展：应用状态持久化不止「事件溯源」一种。常见方案对比——

方案原理/特点适用场景
CRUD 直写直接更新当前状态行，历史靠审计日志另行记录常规业务系统，简单直接
状态快照 + 变更日志定期落快照，增量记 binlog 类日志需要增量同步/CDC 的系统
事件溯源 Event Sourcing只追加不可变事件，状态由事件回放/投影得出强审计、可回溯、可重放的业务内核
CQRS（命令查询职责分离）写模型与读模型分离，常与事件溯源组合读写负载差异大、读模型多样

ZITADEL 实际采用「事件溯源 + CQRS 投影」组合：事件表天然构成完整审计流（README 称之为 "comprehensive event stream"，可通过 Webhook 外流至 SOC/SIEM），而投影表保证了 Console 与 API 的查询性能。代价是 schema 复杂度与投影重建运维成本。

3.3 多租户层级

ZITADEL 的多租户是基础设施级的，自上而下三层（官方 Concepts：Structure → Instance / Organization / Project）：

  1. Instance（实例）：一个 ZITADEL 进程可托管多个逻辑实例，实例间数据完全隔离（域名区分），SaaS 运营方可按客户维度分发实例；
  2. Organization（组织）：B2B 场景的一等公民，每个组织有独立域名、品牌、策略（密码复杂度、MFA 强制等）与自助入口；
  3. Project（项目）+ 应用 + 角色：OIDC/SAML 应用挂在项目下，角色授权（RBAC）以「用户授予（User Grant）」跨组织委派。

这一层级是 ZITADEL 与 Keycloak（Realm 概念，官方对比称存在 "Scaling limits"）在 B2B 场景的核心差异点，也是官方 README 对比表中列出的首条优势（"Infrastructure-level tenants — Instances (High scale)"）。

3.4 API 与端点版图

v4.19 的对外端点分四族（来源：官方 APIs 概览页，查询日实查）：

端点族REST 前缀职责
OIDC/OAuth 标准端点/oauth/v2/*、/oidc/v1/*authorize、token、introspect、userinfo、revocation、end_session、jwks
v2 资源 API（推荐）/v2/*Users、Sessions、Organizations、Projects、Applications、Actions 等资源化接口
v1 传统 API（维护态）/management/v1/*、/admin/v1/*、/auth/v1/*组织级管理 / 实例级管理 / 当前用户自助
System API/system/v1/*多实例（Instance）生命周期管理（SaaS 运营用）

每个 gRPC 服务同时暴露 connectRPC 与 REST（grpc-gateway）两种形态，例如 POST /v2/sessions 即 zitadel.session.v2.SessionService/CreateSession 的 REST 映射。API 全景实测见《ZITADEL v4.19.5 API 使用详解》。

四、功能特性

以下功能清单来自官方 README（v4.19.5，查询日实查），按四大类归纳：

认证（Authentication）

  • 单点登录（SSO）：用户名/密码、通行密钥（FIDO2/WebAuthn）、企业与社会身份源（Google、Azure AD、GitHub 等预置模板 + LDAP）
  • MFA：TOTP、U2F、OTP Email、OTP SMS
  • 协议：OIDC（OpenID 认证名录在列）、SAML 2.0、OAuth 2.0 设备授权流
  • 机器对机器（M2M）：JWT Profile、个人访问令牌（PAT）、Client Credentials 三种服务账号认证
  • 令牌交换（Token Exchange）与身份模拟（Impersonation）
  • 自定义会话流（Session API，可用于自建登录 UI）
  • Hosted Login V2（可完全定制的登录体验）

多租户（Multi-Tenancy）

  • 身份代理（Identity Brokering）与预置 IdP 模板
  • B2B 自助入驻流程（可定制 onboarding）
  • 第三方委派角色管理（把项目的角色管理权交给客户组织）
  • 域名发现（Domain Discovery，用户输入邮箱自动路由到正确组织）

集成（Integration）

  • 每个资源均有 gRPC、connectRPC、REST 三种 API
  • Actions：Webhook、自定义代码、令牌增强（v2 Actions）
  • RBAC 与 SCIM 2.0 Server（用户目录同步）
  • 审计日志与 SOC/SIEM 外流集成
  • 多语言官方 SDK 与示例应用

自助与管理（Self-Service & Admin）

  • 自助注册（邮箱/手机验证）
  • 管理控制台（Console）：组织、项目、应用、用户全量管理
  • 按组织的自定义品牌（Logo、配色、CSS）

部署（Deployment）

  • PostgreSQL ≥ 14（14–18），零停机版本升级（Zero-downtime updates）
  • 无外部会话存储的水平扩展（README："horizontal scalability without external session stores"）
  • Kubernetes 官方 Helm Chart

五、快速上手（引自官方，未本地实测）

本篇为认知篇，以下为官方文档给出的最小上手路径，仅转述并标注来源；逐条命令的实测回显见《ZITADEL Docker Compose 部署指南》。

官方 README 与 compose 文档页（https://zitadel.com/docs/self-hosting/deploy/compose，查询日实查）给出的三分钟启动方式：

mkdir zitadel-compose && cd zitadel-compose
# 下载 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
# 复制为 .env 并启动
cp .env.example .env
docker compose up -d --wait

官方说明：启动后访问 http://localhost:8080 打开登录页；控制台入口 http://localhost:8080/ui/console?login_hint=zitadel-admin@zitadel.localhost，初始密码 Password1!。基础栈的组成为「Traefik（反向代理）→ ZITADEL API（Go）+ ZITADEL Login（Next.js）→ PostgreSQL」，gRPC over HTTP/2 的路由由 Traefik 自动处理。

⚠️ 注意：官方 .env.example 随版本更新会滞后于最新 Release（查询日 .env.example 主分支默认 ZITADEL_VERSION=v4.16.0），生产部署建议显式将其改写为当前最新稳定版。本地 HTTP 实测还必须显式关闭 TLS 相关配置（ZITADEL_TLS_ENABLED=false 等）——ZITADEL 默认 ExternalSecure: true 且 TLS.Enabled: true（v4.19.5 cmd/defaults.yaml 实查），这些差异在部署篇中有完整实测。

六、适用场景与限制

6.1 典型适用场景

  1. B2B SaaS 的租户身份底座：每个客户一个 Organization，客户管理员自助管理本组织用户，SaaS 方持有 Instance/System API 层。ZITADEL 的三层租户模型为此场景原生设计。
  2. 替代 Auth0/Okta 的自托管统一认证：OIDC/SAML 全覆盖 + 自托管数据主权 + 无按 MAU 计费。
  3. 强审计合规场景：事件溯源内核使「谁在何时做了什么」全部落库，可直接外流 SIEM。
  4. 机器身份密集的平台：服务账号三种认证方式（PAT / JWT Profile / Client Credentials）+ 令牌交换，适合 CI/CD、微服务间调用场景。

6.2 已知限制（查询日实查）

  • 数据库仅支持 PostgreSQL：v4.19.5 的配置默认文件 cmd/defaults.yaml 中 Database 段仅含 postgres 一个子段；历史上支持 CockroachDB，当前官方文档与配置均已回归 PostgreSQL 为唯一选项。
  • AGPL-3.0 许可：对「修改后作为网络服务分发」要求开放源码（网络条款），商用产品若深度魔改需评估合规；官方另有商业许可接触面（zitadel.com/contact）。
  • Login V2 依赖独立进程：compose 里的 zitadel-login（Next.js）需要一并运维；只跑 API 不跑 Login UI 时，v4 默认 LOGINV2_REQUIRED=true 会使标准 OIDC 跳转登录不可用，需自行调整实例特性开关。
  • 本地 HTTP 部署需显式降级 TLS 策略：默认配置按 HTTPS 域名设计（ExternalSecure: true），内网 HTTP 试用必须改 ZITADEL_EXTERNALSECURE=false、ZITADEL_TLS_ENABLED=false，并保证 ExternalDomain/ExternalPort 与真实访问入口一致，否则出现 "Instance not found"（官方 compose 文档明确点名这是最常见部署问题）。

七、同类选型对比

数据来源与查询日期：各项目 GitHub 仓库页 stargazerCount/License 徽章、releases.atom 订阅、各自官方 README/文档站，均为 2026-10-18 实查。对比对象：Keycloak、Authelia、Authentik、Ory Kratos（Ory Hydra 属配套产品，见 7.4 说明）。

7.1 社区活跃度与版本节奏（量化）

项目Star 数最新稳定版（查询日）版本发布节奏（近 90 天实查）许可证技术栈
ZITADEL15,341v4.19.5（2026-10-15）10 次（2026-08-14 v4.17.1 → 2026-10-15 v4.19.5，月度 minor + 周度 patch）AGPL-3.0Go
Keycloak37,42026.8.1（2026-10-13）5 次（26.7.4 → 26.8.1，月度 minor + patch）Apache-2.0Java（Quarkus）
Authelia29,297v4.39.28（2026-09-17）5+ 次（4.39.24–28 密集 patch）Apache-2.0Go
Authentik25,9932026.8.4（2026-10-14）5 次（2026.8.2–4 等，年.月版本制，约 3 minor/年）MIT（企业目录另立条款）Python（Django）
Ory Kratos13,923v26.2.0（2026-03-20）1 次（节奏明显放缓，上一版 v25.4.0 为 2025-11）Apache-2.0Go

解读（关键差异与如何读这张表）：

  • 社区声量（Star）与工程节奏并不正相关：Keycloak 星数第一（Red Hat 背书的传统生态），但 ZITADEL 在近 90 天的发布次数（10 次）是五者中最高的，patch 响应速度快（v4.19.2→v4.19.5 五天内四连发），体现了活跃的问题修复流。
  • 版本节奏可用性提示：Authentik 采用年.月版本制（2026.2 / 2026.5 / 2026.8），升级语义是「跟随版本列车」；Ory Kratos 2026 年只发了一版，选它需要接受较慢的迭代节奏与更依赖 Ory 商业生态（Network/Console/Enterprise）的整体方案。
  • 许可证差异是硬约束：Apache-2.0（Keycloak/Authelia/Kratos）对闭源集成最宽松；ZITADEL 的 AGPL-3.0 要求网络服务场景下开放修改源码；Authentik 主代码 MIT 但企业目录（authentik/enterprise/）为商业许可（两仓库 LICENSE 文件查询日实查）。

7.2 协议与能力支持矩阵

能力ZITADEL v4.19Keycloak 26.8Authelia 4.39Authentik 2026.8Ory Kratos v26.2
OIDC Provider✅（OpenID 认证名录在列）✅（认证名录在列）✅（4.38+，持续完善）✅❌（由 Ory Hydra 承担）
OAuth 2.0✅✅✅（OP 范畴）✅❌（同上）
SAML 2.0✅✅❌✅❌
SCIM 2.0✅（内置 Server）🟡（需第三方扩展包）❌✅（企业版 Outpost）❌（付费套件含）
LDAP 目录对接🟡（作为 IdP 代理对接上游 LDAP）✅（原生 User Federation）🟡（可作为认证后端对接）✅（LDAP Provider/Outpost）❌
Passkeys/WebAuthn✅✅✅✅✅
MFA（TOTP/SMS/Email）✅（含 OTP Email/SMS）✅✅（TOTP/WebAuthn 为主）✅🟡（需搭配 Ory 全家桶）
多租户/B2B 组织✅（Instance→Org→Project 三层）🟡（Realm，官方对比称存在扩展性限制）❌（单租户定位）✅（Brands/Tenants + 企业特性）🟡（企业套件含 Organizations）
管理 API✅（gRPC+REST 全量）✅（REST Admin API）🟡（配置即代码 YAML + 有限 API）✅（REST API）✅（REST/gRPC）
事件审计外流✅（事件流 + Webhook/Actions）🟡（事件表 + SPI 扩展）❌（日志为主）✅（事件 + Webhook）✅（Webhook）
自带登录 UI✅（Login V2 + Console）✅✅（门户式登录页）✅（Flow 可视化编排）❌（Headless，UI 自建）

解读（如何选型）：

  • 这张矩阵的分水岭是 SAML 与多租户：两者都要 → ZITADEL / Keycloak / Authentik 三选一；只要 OIDC 且追求轻量反向代理认证 → Authelia；纯 Headless 自建体验、接受 Ory 全家桶 → Kratos。
  • ZITADEL 与 Authentik 的能力面最接近（都是现代自托管 IAM），差异在：ZITADEL 单二进制 + PostgreSQL 单存储 + gRPC 全量 API + 事件流审计；Authentik 用 PostgreSQL + Redis + Python，强在 Flow 可视化编排与 Outpost 代理（LDAP Provider/RADIUS/反向代理）。
  • Keycloak 的不可替代项是Java 生态与政企背书（且 Apache-2.0 无许可顾虑），代价是 JVM 资源占用与 Realm 规模化调优成本。

7.3 功能定位一句话卡

项目一句话定位
ZITADELAPI-first、事件溯源内核、多租户原生的「身份基础设施」，云与自托管同代码
Keycloak老牌 Java 系 IAM 事实标准，Red Hat 维护，生态最全
Authelia反向代理认证门户 + 轻量 OIDC OP，homelab/中小站首选
AuthentikPython 系全功能 IAM，Flow 编排灵活，Outpost 生态独特
Ory KratosHeadless 身份服务（无 UI），需与 Hydra（OAuth2/OIDC）等 Ory 组件组合

7.4 选型建议（「如果…则…」）

  • 如果你在做 B2B SaaS、需要每客户独立组织/品牌/策略，且看重 API 自动化（IaC 全量管理身份资源）→ 首选 ZITADEL。
  • 如果你的采购约束是 Apache-2.0/MIT 宽松许可，或团队是 Java 栈、需要与 RH 生态（SSSD/FreeIPA）深度集成 → Keycloak。
  • 如果场景是给内网 Nginx/Traefik 后面的几十个自托管应用加统一登录，不经营对外 SaaS，用户量数百以内 → Authelia 最省心（同场景《Authelia》有专门实测篇）。
  • 如果需要 LDAP/RADIUS 反向代理等「协议出口」（把 ZITADEL/上游 IdP 的身份转成 LDAP 供给老设备）→ Authentik（Outpost） 或 Keycloak 扩展。
  • 如果你在构建完全自定义体验的 Headless 身份平台（自有 App 是唯一交互面），能接受多组件组合 → Ory Kratos + Hydra；若还想要多租户与 gRPC，则回到 ZITADEL 的 Session API + 全量 v2 API 路线（实测见《ZITADEL v4.19.5 API 使用详解》）。

💡 说明：以上对比只覆盖「可自托管的开源 IAM」主航道。若评估面扩大到商用 SaaS（Auth0/Okta/Cognito），维度还需加入计费模型与数据出境合规，超出本篇范围。

八、参考链接