AgentSkillsCN

vi-zitadel-admin

通过仅需调整配置的变更，实现可靠且自托管的 ZITADEL 管理与日常运维：初始设置（`zitadel init/setup/start`）、加固措施（TLS、HTTP/2、主密钥、SMTP）、升级与扩展、备份、可观测性，以及常见故障排查。当您处理 ZITADEL 部署配置（Helm、Docker Compose、Linux 服务）、ZITADEL 配置/步骤 YAML 文件，或诊断自托管 ZITADEL 运行时问题时使用。

SKILL.md
--- frontmatter
name: vi-zitadel-admin
description: "Reliable self-hosted ZITADEL administration and day-2 operations with configuration-only changes: initial setup (`zitadel init/setup/start`), hardening (TLS, HTTP/2, masterkey, SMTP), upgrades/scaling, backups, observability, and common troubleshooting. Use when working with ZITADEL deployment config (Helm, Docker Compose, Linux service), ZITADEL config/steps YAML, or diagnosing self-hosted ZITADEL runtime issues."

Vi Zitadel Admin

Administer ZITADEL (self-hosted) via configuration and operational workflows. Avoid patching ZITADEL source unless explicitly requested.

Quick intake (ask first)

  • •Deployment: Kubernetes (Helm), Docker Compose, or Linux/service
  • •Version/DB: ZITADEL major version (v2 vs v3), Postgres vs CockroachDB (v2 only)
  • •External access: ExternalDomain, TLS termination (--tlsMode), reverse proxy/WAF/CDN, HTTP/2/h2c
  • •Config delivery: where --config and --steps files live; how --masterkey* is provided

Source of truth (upstream)

Use the upstream ZITADEL repo + docs as the authoritative config catalog:

If you have a local clone, prefer grepping local files for speed/offline work (any path; example: ~/contrib/zitadel).

Recommended workflow

  1. •Locate current runtime config (--config) and setup steps (--steps).
  2. •Compare against the production checklist and close gaps (TLS/HTTP/2, non-default credentials, SMTP, backups, observability).
  3. •Apply changes as configuration-only:
    • •Use multiple --config / --steps files to separate public config from secrets.
    • •Keep secrets out of git (masterkey, DB creds, SMTP creds, TLS private key).
  4. •For installs/upgrades, follow the phase separation:
    • •First install: zitadel init (once) → zitadel setup → zitadel start
    • •Upgrade: run zitadel setup with the new version, then roll out zitadel start
  5. •Verify with health endpoints and logs:
    • •Ready: /debug/ready
    • •Health: /debug/healthz
    • •Metrics: /debug/metrics

Common tasks (short recipes)

  • •Find config keys: search cmd/defaults.yaml and cmd/setup/steps.yaml in the ZITADEL repo (look for # ZITADEL_... comments).
  • •Fix “Instance not found”: validate ExternalDomain/Port/Secure, reverse proxy host headers, then rerun zitadel setup.
  • •Prepare for production: follow references/production-hardening.md and cross-check the upstream production checklist.
  • •Plan upgrades and scaling: use references/upgrade-scaling.md (init/setup/start separation, probes, zero downtime).
  • •Validate database posture: use references/database.md (supported versions, credential rotation, v2→v3 CRDB migration notes).
  • •Verify HTTP/2 + TLS: use references/networking-http2-tls.md.

Resources

  • •Config discovery and file layout: references/config-discovery.md
  • •Production hardening checklist: references/production-hardening.md
  • •Init/setup/start + upgrades + scaling: references/upgrade-scaling.md
  • •Database operations and credential rotation: references/database.md
  • •HTTP/2, h2c, TLS modes, reverse proxies: references/networking-http2-tls.md
  • •Observability: readiness/liveness/metrics/logging: references/observability.md
  • •Optional migration (v2 CockroachDB → Postgres): references/migration-crdb-to-pg.md