ZITADEL Monorepo 工程指南仓库地图、多租户语义规范与 AI Agent 协作约定【免费下载链接】zitadelZITADEL - Identity infrastructure, simplified for you.项目地址: https://gitcode.com/GitHub_Trending/zi/zitadel本文基于 ZITADEL 仓库根目录的 AGENTS.md 展开系统讲解这个 Go Angular/React 单体仓库Monorepo的目录结构地图、Nx/pnpm 工程约定、多租户领域模型System/Instance/Organization/Project与权限边界、Instance 术语的翻译守则以及命令规则、Nx 目标清单与 PR 标题规范。读完后你可以像仓库的 AI Agent 一样快速定位任意模块、正确使用已验证的构建目标并为文档与代码产出术语一致的多租户内容。1. 项目定位与文档使命AGENTS.md 开头即给出项目的一句话定义ZITADEL 是一个用 Go 和 Angular/React 编写的开源身份管理系统IAM提供安全登录、多租户multi-tenancy与审计追踪audit trails。该文件是面向 AI Agent 的仓库指南它与面向人类的 CONTRIBUTING.md 互补共同构成仓库的导航层。文档末尾给出了阅读指引人类读者查阅 CONTRIBUTING.md 获取环境搭建与贡献流程API 设计决策遵循 API_DESIGN.md 中的 API 规范。2. 文档导航分级 AGENTS.md 的阅读顺序仓库采用根文档 分域文档的层级结构。根 AGENTS.md 规定的阅读顺序是先读根文档本文件再读待编辑区域最近的分级AGENTS.md若多个作用域同时适用以路径最具体的那个为准。当前仓库实际存在的分级文档包括区域分级文档Login UINext.js 认证界面apps/login/AGENTS.mdDocsFumadocs 文档应用apps/docs/AGENTS.mdAPI 后端Nx 应用目标apps/api/AGENTS.mdManagement ConsoleAngular 管理台console/AGENTS.md后端领域与服务逻辑internal/AGENTS.mdAPI 协议定义proto/AGENTS.md共享 TypeScript 包packages/AGENTS.mdCypress 功能 UI 测试tests/functional-ui/AGENTS.mdDocker Compose 部署deploy/compose/AGENTS.md分级文档会进一步强化根文档的约定。例如 internal/AGENTS.md 明确了两条边界规则业务行为应实现在 command/query 层与 repository 包中而不是传输层 handler保持 API/service 适配器薄化可复用的领域行为放入内部 domain 包。它给出的后端改动验证流程是pnpm nx run zitadel/api:lint pnpm nx run zitadel/api:test-unit pnpm nx run zitadel/api:test-integration3. 仓库结构地图根 AGENTS.md 给出的目录地图如下每一条目均可以在仓库中直接找到对应路径apps/面向消费者的 Web 应用loginNext.js 认证 UI见 apps/login/AGENTS.mddocsFumadocs 文档应用见 apps/docs/AGENTS.mdapi后端 Nx 应用目标见 apps/api/AGENTS.mdconsole/Angular Management Console见 console/AGENTS.mdinternal/后端领域与服务逻辑见 internal/AGENTS.mdproto/API 定义见 proto/AGENTS.md其中proto/zitadel/下有 150 余个.proto文件packages/共享 TypeScript 包zitadel-client、zitadel-prototests/functional-ui/Cypress 功能 UI 测试从源码结构看pnpm workspace 与这份地图完全对应。pnpm-workspace.yaml 声明的包为packages: - console - tests/* - packages/* - apps/* - deploy/compose exclude: - benchmark # because of the node 18 or 20 dependency即 Go 后端internal/、cmd/、pkg/不参与 pnpm 工作区而是通过zitadel/api这个 Nx 应用目标来构建与验证。nx.json 进一步声明了工作区布局workspaceLayout.libsDir: packages与统一的targetDefaults缓存策略generate、build、lint、test、test-unit、test-integration均开启缓存且build通过dependsOn: [^build, generate]强制先构建依赖项目、再执行代码生成——这与文档中不要假设各项目都有 test/lint/build/generate 目标的规则互为印证。4. 技术栈与工程约定4.1 编排与包管理Nx pnpmOrchestration使用Nx做构建与任务编排入口 nx.json、project.jsonPackage Managerpnpm通过 Corepack 保证版本一致CONTRIBUTING.md 的 Quick Start 要求 Node.js v22.x 并执行corepack enable后pnpm install。CONTRIBUTING.md 中的开发命令速查表给出了标准工作流pnpm nx run-many --target generate生成 .gitignored 文件、pnpm nx run PROJECT:dev/build/lint/test执行对应任务。4.2 Go 版本以 go.mod 为唯一事实来源根 AGENTS.md 要求开始 Go 工作前先检查 go.mod 中的go与可选toolchain指令。当前仓库的实际声明为go.modmodule github.com/zitadel/zitadel go 1.25.0 toolchain go1.25.114.3 API 通信connectRPC 为主传输文档约定对 V2 APIconnectRPC 是主要传输协议同时支持 gRPC 与 HTTP/JSON 端点。这一约定在依赖清单中得到确认——go.mod 引入了connectrpc.com/connect v1.19.2 connectrpc.com/grpcreflect v1.3.0 connectrpc.com/otelconnect v0.9.0生成的 connect/go 桩代码位于internal/api/grpc/**如 internal/api/grpc/action/v2/server.go由buf generate驱动详见下文 8.3 节。4.4 数据模型关系型为主事件保留审计根 AGENTS.md 明确指出后端正在向关系型设计过渡。事件仍持久化在独立表中用于历史/审计但事件不再是记录系统system of record。internal/AGENTS.md 用更工程化的表述复述了这条约定Relational data is the system of record; keep existing event writes that provide history/audit trails并要求避免绕过既有的 event/repository 流程、用临时性的直接持久化方式写库。从目录结构看internal/command/写入、internal/query/读取、internal/repository/持久化与internal/eventstore/的分层正是这一模式的物理落点。4.5 前端双技术栈应用技术栈Management ConsoleAngular RxJSLogin / DocsNext.js React5. ZITADEL 领域模型与多租户逻辑这一节是根 AGENTS.md 的核心规定了编写代码、逻辑或翻译时必须遵守的层次结构与术语规范。5.1 层次与归属Hierarchy OwnershipZITADEL 遵循严格的层次包含模型SystemInstallation安装实例整个 ZITADEL 部署。全局设置通过运行时配置文件或环境变量下发参考 cmd/defaults.yaml。InstanceIdentity System定义逻辑分区/虚拟租户是System 里的 SystemSystem inside a System隔离实例之间的数据与设置严格隔离翻译规则永远不要译成Example/Case例子/案例应使用 Tenant租户、Environment环境 或当地语言中逻辑系统实体的等价技术词。OrganizationInstance 内的分组拥有 Users、Projects、Roles。ProjectOrganization 内 Applications 与 Auth Policies 的集合。System 级配置走配置文件/环境变量这一点可以在 cmd/defaults.yaml 中逐行验证——每个 YAML 字段后都标注了对应环境变量例如Instrumentation: ServiceName: zitadel # ZITADEL_INSTRUMENTATION_SERVICENAME Trace: Exporter: Type: none # ZITADEL_INSTRUMENTATION_TRACE_EXPORTER_TYPE这也支撑了 6 节中所有部署方式共用同一套ZITADEL_*环境变量模型的约定。5.2 权限作用域Administrative ContextSystem User管理整个 Installation并通过 system API 创建 InstanceInstance Admin管理 Instance 级策略密码复杂度、Identity Providers、Organizations;Organization Admin管理特定 Organization 内的用户与访问。这套三级管理上下文与 5.1 的层次一一对应每一级管理员的权限被约束在自己的实体边界内。5.3 语言与语气准则避免歧义凡指代 Instance上下文永远是基础设施/租户tenancy层面技术精确性在 UI 文案中若 Instance 在目标语言里容易被误解清晰度优先于简洁。5.4 技术术语与本地化映射表语言技术术语SaaS/Cloud为什么用这个词避免Example 陷阱中文简体实例 (Shílì)云资源/实体的标准译法例子 (Lìzi)日语インスタンス (Insutansu)片假名转写业界标准例 (Rei)韩语인스턴스 (Inseuteonseu)谚文转写业界标准예 (Ye)德语Instanz与英文对应且表示技术性发生/实例Beispiel法语Instance标准但常需 de ZITADEL 增加明确性Exemple西班牙语Instancia软件架构中的技术实体Ejemplo葡萄牙语Instância标准技术术语Exemplo俄语Инстанс (Instans)现代 SaaS 术语转写Пример (Primer)5.5 翻译护栏Translation Guardrails当需要为上述清单之外的语言翻译 Instance 时按以下优先级规则处理优先级 1转写使用本地文字母的语音转写日语/韩语/俄语中常见优先级 2系统实体使用暗示运行中的进程或逻辑环境的词优先级 3租户若 Instance 本身有歧义用当地语言中 Tenant 的词如中文的租户严格禁令绝不用表示插图、案例、样本、例子的词。6. 部署目标Deployment TargetsZITADEL 支持多种部署方式每种有独立目录与约定。根 AGENTS.md 给出的清单为目标位置状态说明Docker Composedeploy/compose/Supported单节点从 quickstart 到半生产可用目录规则见 deploy/compose/AGENTS.mdKubernetes (Helm)外部维护的 zitadel-charts 仓库Helm chartSupported面向生产负载的官方 Helm chart文档位于apps/docs/content/self-hosting/deploy/kubernetes/apt/rpm 包—Planned尚未提供生成部署相关内容时的准则上手入门与家庭实验室/单节点部署推荐 Docker Compose生产负载推荐 Kubernetes始终根据用户上下文引用正确的部署方式所有部署方式共用同一套ZITADEL_*环境变量模型。7. 命令规则从仓库根目录运行根 AGENTS.md 对命令执行的硬性规定命令一律从仓库根目录运行只使用已验证verified的 Nx 目标目标可用性不明时先运行pnpm nx show project project查询不要假设所有项目都具备test、lint、build或generate目标已知例外zitadel/console没有配置test目标。7.1 已验证的常用目标清单文档逐项目列出了经确认存在的目标项目已验证目标zitadel/apiprod、build、build-linux、pack、generate、generate-install、lint、test、test-unit、test-integrationzitadel/logindev、build、pack、lint、test、test-unit、test-integrationzitadel/docsdev、build、generate、install-proto-plugins、check-links、check-types、test、lintzitadel/consoledev、build、generate、install-proto-plugins、lintzitadel/composetest-config、test-run、test-e2e、test、test-full、stop以zitadel/api为例apps/api/project.json 中确实定义了上述全部目标并且可以进一步看到目标的真实行为例如buildCGO_ENABLED0 go build -o .artifacts/bin/$(go env GOOS)/$(go env GOARCH)/zitadel.local -ldflags-s -w且dependsOn于generate与build-console把 Console 静态文件拷入 API 内嵌目录test-unitgo test -race -coverprofile... ./...test-integration先起数据库/缓存容器再用go test -race -count 1 -tags integration -timeout 60m -parallel 1针对进程外 API运行集成测试并生成覆盖率报告prod以start-from-init --config ... --masterkey ...启动已构建的二进制支持 default / test-integration-api / test-functional-ui 三种配置。8. Proto 插件二进制与代码生成8.1 统一安装目录文档约定所有 proto 插件统一安装到.artifacts/bin/GOOS/GOARCH/并享受 Nx 缓存generate目标会自动接好安装依赖并把.artifacts/bin/前置到$PATH——无需手工安装步骤。8.2 安装目标的实现该约定由 apps/api/project.json 中的generate-install目标落地它通过GOBIN${PWD}/.artifacts/bin/$(go env GOOS)/$(go env GOARCH) go install ...安装整套工具链buf、protoc-gen-go、protoc-gen-go-grpc、protoc-gen-connect-go、protoc-gen-openapiv2、statik、mockgen、stringer、enumer以及仓库自研的protoc-gen-authoption、protoc-gen-zitadel等并在outputs中登记每个二进制供 Nx 缓存命中。目标描述中特别解释了动机避免使用 go tools以免开发工具依赖干扰生产依赖。8.3 生成链路generate目标分解为三个子目标apps/api/project.jsongenerate-stubs执行buf generate将产物拷贝到pkg/grpc/与openapi/v2/zitadel/生成 gRPC 与 OpenAPI 桩generate-assets运行资产生成器产出资产路由与文档internal/api/assets/、apps/docs/content/apis/assets/assets.mdxgenerate-statik用statik把登录页静态资源、通知模板等嵌入 Go 二进制。CONTRIBUTING.md 的命令速查表也列出了对应入口pnpm nx run zitadel/api:generate-installInstalls Go-based plugins (protoc-gen-go, connect-go, …) to.artifacts/bin/. Run automatically bygeneratetargets; Nx caches the outputs.与根文档的约定完全一致。9. PR 标题规范PR 标题由Semantic PR应用校验格式为type(scope): short summaryTypes必须来自 .github/semantic.yml 中types:列表feat、fix、docs、refactor、perf、test、build、ci、chore、revertScopes可选若使用必须来自同文件scopes:列表。拿不准就省略 scope——不要发明不在列表中的值。.github/semantic.yml 是这一约定的唯一事实来源titleOnly: true即只校验 PR 标题、不校验 commit其 scope 列表按领域分组节选如下后端领域api、session、authz、command、query、eventstore、actions、crypto、domain、feature、idp、notification、oidc、saml、webauthn后端基础设施cache、config、database、migration、setup、telemetry、queue前端console、loginAPI 层grpc、proto部署deploy横切build、ci、deps、i18n、integration、perf、security、test注意该文件注释中特别强调docs是 type 而不是 scope——文档类改动直接用docs(...)类型。10. 小结把 AGENTS.md 当作仓库的接口契约AGENTS.md 的价值在于把三类信息收敛到一处结构契约目录地图 分级AGENTS.md阅读顺序保证任何新协作者人或 Agent都能在 O(1) 内定位到正确的作用域规则领域契约System/Instance/Organization/Project 层次、三级管理权限、以及带严格禁令的翻译守则确保多租户概念在代码、UI 文案与多语言文档中不漂移工程契约以 go.mod 为 Go 版本事实来源、connectRPC 优先的传输约定、关系数据为准 事件保留审计的存储模式、pnpm nx show project的探询纪律、.artifacts/bin/工具链缓存机制以及 semantic.yml 驱动的 PR 标题规范。配合 CONTRIBUTING.md 的环境搭建流程与 API_DESIGN.md 的 API 设计规范即可完整覆盖在 ZITADEL monorepo 中开发、验证pnpm nx run zitadel/api:lint/test-unit/test-integration与提交的日常闭环。【免费下载链接】zitadelZITADEL - Identity infrastructure, simplified for you.项目地址: https://gitcode.com/GitHub_Trending/zi/zitadel创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
ZITADEL Monorepo 工程指南：仓库地图、多租户语义规范与 AI Agent 协作约定
ZITADEL Monorepo 工程指南仓库地图、多租户语义规范与 AI Agent 协作约定【免费下载链接】zitadelZITADEL - Identity infrastructure, simplified for you.项目地址: https://gitcode.com/GitHub_Trending/zi/zitadel本文基于 ZITADEL 仓库根目录的 AGENTS.md 展开系统讲解这个 Go Angular/React 单体仓库Monorepo的目录结构地图、Nx/pnpm 工程约定、多租户领域模型System/Instance/Organization/Project与权限边界、Instance 术语的翻译守则以及命令规则、Nx 目标清单与 PR 标题规范。读完后你可以像仓库的 AI Agent 一样快速定位任意模块、正确使用已验证的构建目标并为文档与代码产出术语一致的多租户内容。1. 项目定位与文档使命AGENTS.md 开头即给出项目的一句话定义ZITADEL 是一个用 Go 和 Angular/React 编写的开源身份管理系统IAM提供安全登录、多租户multi-tenancy与审计追踪audit trails。该文件是面向 AI Agent 的仓库指南它与面向人类的 CONTRIBUTING.md 互补共同构成仓库的导航层。文档末尾给出了阅读指引人类读者查阅 CONTRIBUTING.md 获取环境搭建与贡献流程API 设计决策遵循 API_DESIGN.md 中的 API 规范。2. 文档导航分级 AGENTS.md 的阅读顺序仓库采用根文档 分域文档的层级结构。根 AGENTS.md 规定的阅读顺序是先读根文档本文件再读待编辑区域最近的分级AGENTS.md若多个作用域同时适用以路径最具体的那个为准。当前仓库实际存在的分级文档包括区域分级文档Login UINext.js 认证界面apps/login/AGENTS.mdDocsFumadocs 文档应用apps/docs/AGENTS.mdAPI 后端Nx 应用目标apps/api/AGENTS.mdManagement ConsoleAngular 管理台console/AGENTS.md后端领域与服务逻辑internal/AGENTS.mdAPI 协议定义proto/AGENTS.md共享 TypeScript 包packages/AGENTS.mdCypress 功能 UI 测试tests/functional-ui/AGENTS.mdDocker Compose 部署deploy/compose/AGENTS.md分级文档会进一步强化根文档的约定。例如 internal/AGENTS.md 明确了两条边界规则业务行为应实现在 command/query 层与 repository 包中而不是传输层 handler保持 API/service 适配器薄化可复用的领域行为放入内部 domain 包。它给出的后端改动验证流程是pnpm nx run zitadel/api:lint pnpm nx run zitadel/api:test-unit pnpm nx run zitadel/api:test-integration3. 仓库结构地图根 AGENTS.md 给出的目录地图如下每一条目均可以在仓库中直接找到对应路径apps/面向消费者的 Web 应用loginNext.js 认证 UI见 apps/login/AGENTS.mddocsFumadocs 文档应用见 apps/docs/AGENTS.mdapi后端 Nx 应用目标见 apps/api/AGENTS.mdconsole/Angular Management Console见 console/AGENTS.mdinternal/后端领域与服务逻辑见 internal/AGENTS.mdproto/API 定义见 proto/AGENTS.md其中proto/zitadel/下有 150 余个.proto文件packages/共享 TypeScript 包zitadel-client、zitadel-prototests/functional-ui/Cypress 功能 UI 测试从源码结构看pnpm workspace 与这份地图完全对应。pnpm-workspace.yaml 声明的包为packages: - console - tests/* - packages/* - apps/* - deploy/compose exclude: - benchmark # because of the node 18 or 20 dependency即 Go 后端internal/、cmd/、pkg/不参与 pnpm 工作区而是通过zitadel/api这个 Nx 应用目标来构建与验证。nx.json 进一步声明了工作区布局workspaceLayout.libsDir: packages与统一的targetDefaults缓存策略generate、build、lint、test、test-unit、test-integration均开启缓存且build通过dependsOn: [^build, generate]强制先构建依赖项目、再执行代码生成——这与文档中不要假设各项目都有 test/lint/build/generate 目标的规则互为印证。4. 技术栈与工程约定4.1 编排与包管理Nx pnpmOrchestration使用Nx做构建与任务编排入口 nx.json、project.jsonPackage Managerpnpm通过 Corepack 保证版本一致CONTRIBUTING.md 的 Quick Start 要求 Node.js v22.x 并执行corepack enable后pnpm install。CONTRIBUTING.md 中的开发命令速查表给出了标准工作流pnpm nx run-many --target generate生成 .gitignored 文件、pnpm nx run PROJECT:dev/build/lint/test执行对应任务。4.2 Go 版本以 go.mod 为唯一事实来源根 AGENTS.md 要求开始 Go 工作前先检查 go.mod 中的go与可选toolchain指令。当前仓库的实际声明为go.modmodule github.com/zitadel/zitadel go 1.25.0 toolchain go1.25.114.3 API 通信connectRPC 为主传输文档约定对 V2 APIconnectRPC 是主要传输协议同时支持 gRPC 与 HTTP/JSON 端点。这一约定在依赖清单中得到确认——go.mod 引入了connectrpc.com/connect v1.19.2 connectrpc.com/grpcreflect v1.3.0 connectrpc.com/otelconnect v0.9.0生成的 connect/go 桩代码位于internal/api/grpc/**如 internal/api/grpc/action/v2/server.go由buf generate驱动详见下文 8.3 节。4.4 数据模型关系型为主事件保留审计根 AGENTS.md 明确指出后端正在向关系型设计过渡。事件仍持久化在独立表中用于历史/审计但事件不再是记录系统system of record。internal/AGENTS.md 用更工程化的表述复述了这条约定Relational data is the system of record; keep existing event writes that provide history/audit trails并要求避免绕过既有的 event/repository 流程、用临时性的直接持久化方式写库。从目录结构看internal/command/写入、internal/query/读取、internal/repository/持久化与internal/eventstore/的分层正是这一模式的物理落点。4.5 前端双技术栈应用技术栈Management ConsoleAngular RxJSLogin / DocsNext.js React5. ZITADEL 领域模型与多租户逻辑这一节是根 AGENTS.md 的核心规定了编写代码、逻辑或翻译时必须遵守的层次结构与术语规范。5.1 层次与归属Hierarchy OwnershipZITADEL 遵循严格的层次包含模型SystemInstallation安装实例整个 ZITADEL 部署。全局设置通过运行时配置文件或环境变量下发参考 cmd/defaults.yaml。InstanceIdentity System定义逻辑分区/虚拟租户是System 里的 SystemSystem inside a System隔离实例之间的数据与设置严格隔离翻译规则永远不要译成Example/Case例子/案例应使用 Tenant租户、Environment环境 或当地语言中逻辑系统实体的等价技术词。OrganizationInstance 内的分组拥有 Users、Projects、Roles。ProjectOrganization 内 Applications 与 Auth Policies 的集合。System 级配置走配置文件/环境变量这一点可以在 cmd/defaults.yaml 中逐行验证——每个 YAML 字段后都标注了对应环境变量例如Instrumentation: ServiceName: zitadel # ZITADEL_INSTRUMENTATION_SERVICENAME Trace: Exporter: Type: none # ZITADEL_INSTRUMENTATION_TRACE_EXPORTER_TYPE这也支撑了 6 节中所有部署方式共用同一套ZITADEL_*环境变量模型的约定。5.2 权限作用域Administrative ContextSystem User管理整个 Installation并通过 system API 创建 InstanceInstance Admin管理 Instance 级策略密码复杂度、Identity Providers、Organizations;Organization Admin管理特定 Organization 内的用户与访问。这套三级管理上下文与 5.1 的层次一一对应每一级管理员的权限被约束在自己的实体边界内。5.3 语言与语气准则避免歧义凡指代 Instance上下文永远是基础设施/租户tenancy层面技术精确性在 UI 文案中若 Instance 在目标语言里容易被误解清晰度优先于简洁。5.4 技术术语与本地化映射表语言技术术语SaaS/Cloud为什么用这个词避免Example 陷阱中文简体实例 (Shílì)云资源/实体的标准译法例子 (Lìzi)日语インスタンス (Insutansu)片假名转写业界标准例 (Rei)韩语인스턴스 (Inseuteonseu)谚文转写业界标准예 (Ye)德语Instanz与英文对应且表示技术性发生/实例Beispiel法语Instance标准但常需 de ZITADEL 增加明确性Exemple西班牙语Instancia软件架构中的技术实体Ejemplo葡萄牙语Instância标准技术术语Exemplo俄语Инстанс (Instans)现代 SaaS 术语转写Пример (Primer)5.5 翻译护栏Translation Guardrails当需要为上述清单之外的语言翻译 Instance 时按以下优先级规则处理优先级 1转写使用本地文字母的语音转写日语/韩语/俄语中常见优先级 2系统实体使用暗示运行中的进程或逻辑环境的词优先级 3租户若 Instance 本身有歧义用当地语言中 Tenant 的词如中文的租户严格禁令绝不用表示插图、案例、样本、例子的词。6. 部署目标Deployment TargetsZITADEL 支持多种部署方式每种有独立目录与约定。根 AGENTS.md 给出的清单为目标位置状态说明Docker Composedeploy/compose/Supported单节点从 quickstart 到半生产可用目录规则见 deploy/compose/AGENTS.mdKubernetes (Helm)外部维护的 zitadel-charts 仓库Helm chartSupported面向生产负载的官方 Helm chart文档位于apps/docs/content/self-hosting/deploy/kubernetes/apt/rpm 包—Planned尚未提供生成部署相关内容时的准则上手入门与家庭实验室/单节点部署推荐 Docker Compose生产负载推荐 Kubernetes始终根据用户上下文引用正确的部署方式所有部署方式共用同一套ZITADEL_*环境变量模型。7. 命令规则从仓库根目录运行根 AGENTS.md 对命令执行的硬性规定命令一律从仓库根目录运行只使用已验证verified的 Nx 目标目标可用性不明时先运行pnpm nx show project project查询不要假设所有项目都具备test、lint、build或generate目标已知例外zitadel/console没有配置test目标。7.1 已验证的常用目标清单文档逐项目列出了经确认存在的目标项目已验证目标zitadel/apiprod、build、build-linux、pack、generate、generate-install、lint、test、test-unit、test-integrationzitadel/logindev、build、pack、lint、test、test-unit、test-integrationzitadel/docsdev、build、generate、install-proto-plugins、check-links、check-types、test、lintzitadel/consoledev、build、generate、install-proto-plugins、lintzitadel/composetest-config、test-run、test-e2e、test、test-full、stop以zitadel/api为例apps/api/project.json 中确实定义了上述全部目标并且可以进一步看到目标的真实行为例如buildCGO_ENABLED0 go build -o .artifacts/bin/$(go env GOOS)/$(go env GOARCH)/zitadel.local -ldflags-s -w且dependsOn于generate与build-console把 Console 静态文件拷入 API 内嵌目录test-unitgo test -race -coverprofile... ./...test-integration先起数据库/缓存容器再用go test -race -count 1 -tags integration -timeout 60m -parallel 1针对进程外 API运行集成测试并生成覆盖率报告prod以start-from-init --config ... --masterkey ...启动已构建的二进制支持 default / test-integration-api / test-functional-ui 三种配置。8. Proto 插件二进制与代码生成8.1 统一安装目录文档约定所有 proto 插件统一安装到.artifacts/bin/GOOS/GOARCH/并享受 Nx 缓存generate目标会自动接好安装依赖并把.artifacts/bin/前置到$PATH——无需手工安装步骤。8.2 安装目标的实现该约定由 apps/api/project.json 中的generate-install目标落地它通过GOBIN${PWD}/.artifacts/bin/$(go env GOOS)/$(go env GOARCH) go install ...安装整套工具链buf、protoc-gen-go、protoc-gen-go-grpc、protoc-gen-connect-go、protoc-gen-openapiv2、statik、mockgen、stringer、enumer以及仓库自研的protoc-gen-authoption、protoc-gen-zitadel等并在outputs中登记每个二进制供 Nx 缓存命中。目标描述中特别解释了动机避免使用 go tools以免开发工具依赖干扰生产依赖。8.3 生成链路generate目标分解为三个子目标apps/api/project.jsongenerate-stubs执行buf generate将产物拷贝到pkg/grpc/与openapi/v2/zitadel/生成 gRPC 与 OpenAPI 桩generate-assets运行资产生成器产出资产路由与文档internal/api/assets/、apps/docs/content/apis/assets/assets.mdxgenerate-statik用statik把登录页静态资源、通知模板等嵌入 Go 二进制。CONTRIBUTING.md 的命令速查表也列出了对应入口pnpm nx run zitadel/api:generate-installInstalls Go-based plugins (protoc-gen-go, connect-go, …) to.artifacts/bin/. Run automatically bygeneratetargets; Nx caches the outputs.与根文档的约定完全一致。9. PR 标题规范PR 标题由Semantic PR应用校验格式为type(scope): short summaryTypes必须来自 .github/semantic.yml 中types:列表feat、fix、docs、refactor、perf、test、build、ci、chore、revertScopes可选若使用必须来自同文件scopes:列表。拿不准就省略 scope——不要发明不在列表中的值。.github/semantic.yml 是这一约定的唯一事实来源titleOnly: true即只校验 PR 标题、不校验 commit其 scope 列表按领域分组节选如下后端领域api、session、authz、command、query、eventstore、actions、crypto、domain、feature、idp、notification、oidc、saml、webauthn后端基础设施cache、config、database、migration、setup、telemetry、queue前端console、loginAPI 层grpc、proto部署deploy横切build、ci、deps、i18n、integration、perf、security、test注意该文件注释中特别强调docs是 type 而不是 scope——文档类改动直接用docs(...)类型。10. 小结把 AGENTS.md 当作仓库的接口契约AGENTS.md 的价值在于把三类信息收敛到一处结构契约目录地图 分级AGENTS.md阅读顺序保证任何新协作者人或 Agent都能在 O(1) 内定位到正确的作用域规则领域契约System/Instance/Organization/Project 层次、三级管理权限、以及带严格禁令的翻译守则确保多租户概念在代码、UI 文案与多语言文档中不漂移工程契约以 go.mod 为 Go 版本事实来源、connectRPC 优先的传输约定、关系数据为准 事件保留审计的存储模式、pnpm nx show project的探询纪律、.artifacts/bin/工具链缓存机制以及 semantic.yml 驱动的 PR 标题规范。配合 CONTRIBUTING.md 的环境搭建流程与 API_DESIGN.md 的 API 设计规范即可完整覆盖在 ZITADEL monorepo 中开发、验证pnpm nx run zitadel/api:lint/test-unit/test-integration与提交的日常闭环。【免费下载链接】zitadelZITADEL - Identity infrastructure, simplified for you.项目地址: https://gitcode.com/GitHub_Trending/zi/zitadel创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考