ZITADEL 开源身份基础设施Docker Compose 自托管部署、冷启动架构与 V2 API 集成指南【免费下载链接】zitadelZITADEL - Identity infrastructure, simplified for you.项目地址: https://gitcode.com/GitHub_Trending/zi/zitadelZITADEL 是一个开源的身份与访问管理IAM平台为 SaaS 产品、B2B 平台和自托管生产环境提供 SSO、MFA、Passkeys、OIDC、SAML、SCIM 以及多租户能力。本文基于仓库根目录的 README.md 展开结合 deploy/compose/docker-compose.yml 部署编排、cmd/start/start_from_init.go 冷启动命令实现与 go.mod 依赖清单等源码证据讲解如何在 3 分钟内用 Docker Compose 跑起一套完整的 ZITADEL理解其 API 路由与事件驱动架构并学会通过 V2 REST API 管理用户资源。ZITADEL 是什么按照 README.md 的定义ZITADEL 是一个面向需要基础认证以上能力的团队的开源 IAM 平台开箱即用的核心能力包括单点登录SSO、用户名/密码、PasskeysFIDO2 / WebAuthn多因素认证MFAOTP、U2F、OTP Email、OTP SMS协议支持OpenID Connect官方认证过 OP 认证、SAML 2.0、SCIM 2.0 Server、设备授权Device Authorization、机器对机器认证JWT Profile、PAT、Client Credentials身份源集成LDAP、企业 IdP 与社交登录多租户身份代理Identity Brokering、可自定义的 B2B 自助注册、委托角色管理、域名发现扩展机制Actionswebhook、自定义代码、token enrichment、RBAC、审计日志对接 SOC/SIEM管理与自助自助注册邮箱/手机验证、Admin Console、按组织的自定义品牌仓库的技术栈可以从 go.mod 中得到印证项目基于 Go 1.25toolchain go1.25.11核心依赖中能看到connectrpc.com/connectconnectRPC 传输、jackc/pgx/v5PostgreSQL 驱动、go-webauthn/webauthnPasskey/WebAuthn、crewjam/samlSAML、go-ldap/ldap/v3LDAP以及grpc-ecosystem/grpc-gateway/v2REST/gRPC 网关——这些与 README 宣称的协议与 API 能力一一对应。为什么选择 ZITADELREADME 中的横向对比README.md 给出了一张与其他主流身份平台的对比表这是官方文档的陈述选型时请结合最新版本自行验证维度ZITADELFusionAuthKeycloakAuth0/Okta开源是否是否可自托管是是是否基础设施级租户是Instances高扩展是Tenants部分Realms有扩展限制否多租户 多账号B2B 组织原生且无限制部分经 Entity Management是近年新增部分依赖套餐/账号完整审计轨迹是全面的事件流部分审计日志部分审计日志部分审计日志PasskeysFIDO2是是是是Actions / webhooks是是部分经 SPI是API-firstgRPC REST是部分仅 REST部分仅 REST部分仅 RESTSaaS 与自托管同构是是不适用不适用README 特别强调ZITADEL Cloud 与自托管版本运行同一套代码库即 SaaS 与 self-host 在能力上完全对等。面向架构师的四个关键差异点README 原文归纳关系型核心 事件驱动内核每一个变更mutation都会写成不可变事件形成完整、可通过 API 访问的审计轨迹。与只记录部分活动的系统不同ZITADEL 提供全面的事件流可被审计或通过 Webhook 流式转发到外部系统。严格的多租户层级Identity System实例→ Organizations组织→ Projects项目数据与策略在多个层级隔离。API-first 设计每一个资源和操作都可以通过 connectRPC、gRPC 与 HTTP/JSON API 访问。零停机更新与横向扩展且不需要外部会话存储。三分钟自托管Docker Compose 快速部署快速开始README.md 给出的快速部署命令是从本仓库拉取编排文件后一键启动# Docker Compose — 3 分钟内完成启动 curl -LO https://raw.githubusercontent.com/zitadel/zitadel/main/deploy/compose/docker-compose.yml \ curl -LO https://raw.githubusercontent.com/zitadel/zitadel/main/deploy/compose/.env.example \ cp .env.example .env \ docker compose up -d --wait如果你已经克隆了本仓库等价的做法是直接复用仓库内的两个文件deploy/compose/docker-compose.yml基础栈和 deploy/compose/.env.example配置模板把.env.example复制为.env并填写域名、主密钥等值后执行docker compose up -d --wait即可。仓库中还提供了几种 TLS 部署模式与进阶编排均以基础栈为起点叠加 overlay文件角色deploy/compose/docker-compose.yml基础栈所有模式的起点配合.env.example可独立运行deploy/compose/docker-compose.mode-letsencrypt.ymlTLS overlayACME HTTP challenge声明独立的letsencrypt卷deploy/compose/docker-compose.mode-external-tls.ymlTLS overlay由上游负载均衡器终结 TLS启用转发头deploy/compose/docker-compose.mode-local-tls.ymlTLS overlay自签名证书挂载./certs/与 deploy/compose/traefik-local-tls.ymldeploy/compose/docker-compose.prodlike.yml生产形态init/setup/start 分离启动用 YAML 锚点共享数据库环境变量deploy/compose/otel-collector-config.yamlOTEL Collector 管道配置默认将 trace 输出到 stdout可配置转发到后端部署架构五个服务的职责从 deploy/compose/docker-compose.yml 的编排结构看默认启动的栈由以下服务组成┌─────────────────────────┐ Browser ──────►│ Traefik (proxy) │ │ Port 80 / 443 │ └───┬──────────┬──────────┘ │ │ ┌──────────▼──┐ ┌───▼──────────┐ │ zitadel-api │ │ zitadel-login │ │ Go :8080 │ │ Next.js :3000 │ └──────┬───────┘ └──────────────┘ │ ┌──────▼───────┐ │ PostgreSQL │ └──────────────┘该架构图来自 deploy/compose/README.md面向贡献者的开发者参考文档。各服务的要点zitadel-api核心 Go 后端监听 8080镜像命令为start-from-init --masterkey ${ZITADEL_MASTERKEY}健康检查通过/app/zitadel ready子命令探测healthcheck配置start_period: 20s、重试 12 次。它依赖 PostgreSQL 健康后启动并挂载共享卷zitadel-bootstrap。zitadel-login基于 Next.js 的 Hosted Login V2 前端监听 3000以只读方式挂载zitadel-bootstrap卷通过ZITADEL_SERVICE_USER_TOKEN_FILE读取 API 侧生成的 bootstrap PATPersonal Access Token来调用后端 API。postgres唯一的强制外部依赖PostgreSQLREADME 注明生产要求 ≥ 14使用pg_isready做健康检查数据持久化在postgres-data卷。redis可选profilecache启用缓存连接器时使用编排中关闭了持久化--save --appendonly no。otel-collector可选profileobservabilityOpenTelemetry 采集管道默认将日志/trace 打到 stdout。此外zitadel-api 的环境变量中有一组值得注意的初始化配置ZITADEL_FIRSTINSTANCE_ORG_LOGINCLIENT_PAT_PATH指向/zitadel/bootstrap/login-client.pat——首次启动时后端会创建一个名为login-client的服务账号并写入 PAT 文件供 Login 前端使用ZITADEL_DEFAULTINSTANCE_FEATURES_LOGINV2_REQUIRED: true则强制默认实例启用 Login V2并把 OIDC/SAML 的默认登录 URL 指到/ui/v2/login/路径下。API 路由规则一个端口承载 OIDC、SAML、gRPC 与 RESTdeploy/compose/README.md 中的路由规则表值得完整保留它解释了 ZITADEL 为何不需要为 gRPC 单独配置路由优先级规则目标中间件400Path(/)zitadel-loginreplacepath/ui/v2/login/250PathPrefix(/ui/v2/login)zitadel-login—200PathPrefix(/api)zitadel-apistripprefix/api100其余全部OIDC、SAML、gRPC、gRPC-web、API v2 REST 等zitadel-apih2c—设计动机来自同一文档的 Why this routing model 一节/api前缀只是体验别名——工具可以用https://auth.example.com/api/...这种直观形式访问 APIOIDC/SAML 的协议规范路径如/.well-known/openid-configuration、/oauth/v2/...必须保留在根路径上因此不能被 rewrite 规则覆盖gRPC、gRPC-web 与 REST 共享同一个 catch-all 路由——Traefik 的h2c后端 scheme 让所有协议透明地走 HTTP/2无需专门的 gRPC 路由器。deploy/compose/docker-compose.yml 中的注释也明确写道All gRPC and Connect-RPC traffic is handled by the catch-all router below since the backend already uses h2c。webHTTP与websecureHTTPS两个 entrypoint 拥有完全一致的路由集合。部署的第一大坑外部域名必须一致deploy/compose/README.md 用一整节强调了一条部署不变量External Settings InvariantZITADEL_EXTERNALDOMAIN、ZITADEL_EXTERNALPORT和ZITADEL_EXTERNALSECURE必须与用户实际看到的公网 URL 完全一致。如果不一致ZITADEL 会返回 Instance not found 错误。这是部署中最常见的问题。在 deploy/compose/docker-compose.yml 中可以看到这三个变量直接映射为ZITADEL_EXTERNALDOMAIN、ZITADEL_EXTERNALPORT、ZITADEL_EXTERNALSECURE环境变量而 Login V2 的基础 URIZITADEL_DEFAULTINSTANCE_FEATURES_LOGINV2_BASEURI也是由ZITADEL_PUBLIC_SCHEME、ZITADEL_DOMAIN、ZITADEL_EXTERNALPORT组合拼出来的——三者任何一处与真实入口 URL 不符都会导致 OIDC 跳转或实例解析失败。冷启动命令的源码视角start-from-init 做了什么Docker 编排中zitadel-api的启动命令是start-from-init --masterkey ...。阅读 cmd/start/start_from_init.go 可以看到这个命令的完整执行链解析 TLS 模式tls.ModeFromFlag与主密钥key.MasterKey用于加密敏感数据缺失会直接报错初始化数据库initialise.InitAll完成最小启动要求schema、默认值等对应 cmd/initialise/init.go执行 setup 步骤setup.Setup按 cmd/setup/ 目录中编号01.go、02.go……的迁移步骤写入初始事件并绑定初始投影启动服务startZitadel加载 start 配置并拉起 HTTP/gRPC 服务。也就是说start-from-init 初始化init 迁移/初始事件setup 启动start三合一的冷启动这与 deploy/compose/docker-compose.prodlike.yml 中把三步拆分为独立容器init/setup/start的做法正好互补开发环境用一个命令搞定生产环境可以分阶段控制。程序入口 main.go 非常薄——构造 cobra 根命令并执行所有子命令start-from-init、ready、initialise、setup、key等都挂在 cmd/zitadel.go 下。API 集成用 V2 REST API 创建用户README.md 展示了 ZITADEL V2 REST API 的典型用法——创建一个人类用户curl -X POST https://$ZITADEL_DOMAIN/v2/users/human \ -H Authorization: Bearer $ACCESS_TOKEN \ -H Content-Type: application/json \ -d { username: aliceexample.com, profile: { givenName: Alice, familyName: Smith }, email: { email: aliceexample.com, sendCode: {} } }要点说明请求路径以/v2/开头。从路由设计上一节的优先级 100 catch-all与 deploy/compose/README.md 的说明可确认API v2 以 REST/JSON 形式经由 gRPC-gateway 在/v2/...路径上提供——也就是说 REST 层是 gRPC 服务的投影而非独立实现这与 go.mod 中grpc-ecosystem/grpc-gateway/v2依赖吻合。同一 API 也可以走 connectRPC / gRPC 传输三者共享同一套类型化定义。仓库根目录的 proto/ 目录152 个.proto文件buf.yaml/buf.lock管理是所有服务契约的来源buf.gen.yaml 与 buf.work.yaml 定义了代码生成工作流。认证使用 Bearer Access Token通过 OIDC 等流程获取。OpenAPI 文档同样内嵌在服务中openapi/handler.go 通过//go:embed把生成的 v2 OpenAPI 规范挂载到/openapi/v2/swagger前缀下并启用 CORS 放行——部署后可以直接访问https://$ZITADEL_DOMAIN/openapi/v2/swagger查看交互文档。功能全景与源码位置速查按 README.md 的功能分组结合仓库目录结构开发者可以在以下位置找到对应实现认证AuthenticationSSO、用户名/密码、PasskeysFIDO2/WebAuthnMFA 覆盖 OTP、U2F、OTP Email、OTP SMSLDAP、企业 IdP 与社交登录OIDC 认证、SAML 2.0、设备授权机器对机器JWT Profile、PAT、Client CredentialsToken 交换与模拟impersonation、面向 OIDC/SAML 之外流程的自定义会话代码位置协议层在 internal/api/oidc/、internal/api/saml/、internal/api/idp/WebAuthn 逻辑在 internal/webauthn/会话与 OTP 命令在 internal/command/session_otp.go 与 internal/command/session_webauhtn.go多租户Multi-Tenancy带预置 IdP 模板的身份代理可自定义的 B2B 自助注册向第三方委托角色管理域名发现代码位置组织与项目领域模型集中在 internal/command/org.go、internal/command/project.go 及 internal/ 下的org、project、iam子包集成Integration全部资源均提供 gRPC、connectRPC 与 REST APIActionswebhook、自定义代码、token enrichment——对应 internal/actions/ 目录含object/子包与 HTTP、日志、UUID 等内置模块RBAC、SCIM 2.0 Serverinternal/api/scim/、审计日志对接 SOC/SIEM自助与管理Self-Service Admin带邮箱/手机验证的自助注册面向组织与项目的 Admin Console按组织的自定义品牌代码位置控制台前端在 console/Angular 应用Login V2 前端在 apps/login/Next.js 应用部署DeploymentPostgreSQL≥ 14、零停机更新、高扩展能力数据库相关实现见 internal/database/事件存储与投影见 internal/eventstore/ 与 internal/query/仓库结构与延伸阅读├── backend/v3/ # 后端 v3 模块api、domain、instrumentation、storage ├── cmd/ # CLI 子命令start、setup、initialise、key、mirror、ready、tls ├── internal/ # 核心实现command、query、eventstore、apioidc/saml/scim/ui… ├── proto/ # 全部 .proto 契约与 buf 工作区配置 ├── openapi/ # v2 OpenAPI 规范的内嵌服务 ├── apps/ # 前端应用loginNext.js、consoleAngular、docs文档站、api服务 ├── packages/ # zitadel-client、zitadel-proto 等 npm 包 ├── deploy/compose/ # Docker Compose 编排与 TLS overlay ├── benchmark/ # 性能基准测试含 postmortems └── tests/ # functional-ui 等功能测试几个值得深入阅读的入口cmd/setup/steps.yamlsetup 步骤清单配合 cmd/setup/setup.go 可理解初始事件的写入顺序deploy/compose/README.mdcompose 栈的架构决策、路由逻辑与被否决的备选方案Rejected Alternatives是理解部署设计意图的最佳材料API_DESIGN.md 与 AGENTS.md仓库级 API 设计与协作约定TERMINOLOGY.mdZITADEL 术语表Instance、Organization、Project 等层级概念benchmark/README.md性能基准的说明与使用方式。安全与许可证安全策略见 SECURITY.md漏洞应通过其中描述的流程负责任地报告重大安全或稳定性问题会发布技术公告Technical Advisory。许可证仓库主体为 AGPL-3.0。LICENSING.md 明确了例外目录proto/、apps/docs/目录为Apache License 2.0apps/login/、packages/zitadel-client/、packages/zitadel-proto/目录为MIT License社区贡献统一以 Apache 2.0 许可提交无需额外的 CLA。如果你的应用会触发 AGPL-3.0 义务且希望规避LICENSING.md 建议咨询法律专业人士或联系官方讨论商业授权。贡献阅读 CONTRIBUTING.md 入门采用者名单维护在 ADOPTERS.md欢迎通过 PR 添加自己的组织。小结ZITADEL 的核心卖点可以概括为三句话关系型核心 事件驱动内核带来完整可审计的事件流Instance → Organization → Project 的严格多租户层级以及 connectRPC/gRPC/REST 三通道同构的 API-first 设计。部署侧一个 deploy/compose/docker-compose.yml 加上.env即可在几分钟内获得 Traefik Go API Next.js Login PostgreSQL 的完整栈start-from-init一个命令覆盖初始化、迁移与启动。需要特别注意的唯一硬性约束是ZITADEL_EXTERNALDOMAIN/EXTERNALPORT/EXTERNALSECURE必须与公网 URL 严格一致否则会出现 Instance not found。在此基础上/v2/...REST 端点、/openapi/v2/swagger文档端点与/api别名路由构成了完整的集成入口配合 proto/ 契约即可在任何支持 connectRPC 或 gRPC 的语言中接入。【免费下载链接】zitadelZITADEL - Identity infrastructure, simplified for you.项目地址: https://gitcode.com/GitHub_Trending/zi/zitadel创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考