Zitadel 身份管理平台部署

Zitadel 是一款现代化的开源身份管理（IAM）平台，用 Go 语言编写，提供了完整的用户管理、OIDC/OAuth2 认证、多租户支持和细粒度权限控制。Zitadel 内置了用户注册、登录界面、双因素认证和审计日志等功能，是 Auth0 和 Okta 的优秀开源替代方案。在搬瓦工 VPS 上部署 Zitadel 可以为你的所有应用提供统一的身份认证服务。

一、系统要求

操作系统：Ubuntu 20.04+（推荐 Ubuntu 22.04）。
内存：至少 2GB，建议 4GB。
Docker：需要预先安装 Docker 和 Docker Compose。
域名：需要一个域名并配置 DNS 解析。

二、Docker Compose 部署

2.1 创建项目目录

mkdir -p /opt/zitadel && cd /opt/zitadel

2.2 编写 Docker Compose 文件

cat > docker-compose.yml <<'EOF'
version: '3.8'

services:
  zitadel:
    image: ghcr.io/zitadel/zitadel:latest
    container_name: zitadel
    restart: always
    command: start-from-init --masterkeyFromEnv --tlsMode external
    environment:
      - ZITADEL_DATABASE_POSTGRES_HOST=db
      - ZITADEL_DATABASE_POSTGRES_PORT=5432
      - ZITADEL_DATABASE_POSTGRES_DATABASE=zitadel
      - ZITADEL_DATABASE_POSTGRES_USER_USERNAME=zitadel
      - ZITADEL_DATABASE_POSTGRES_USER_PASSWORD=ZitadelDBPass123
      - ZITADEL_DATABASE_POSTGRES_USER_SSL_MODE=disable
      - ZITADEL_DATABASE_POSTGRES_ADMIN_USERNAME=postgres
      - ZITADEL_DATABASE_POSTGRES_ADMIN_PASSWORD=PostgresPass123
      - ZITADEL_DATABASE_POSTGRES_ADMIN_SSL_MODE=disable
      - ZITADEL_EXTERNALSECURE=true
      - ZITADEL_EXTERNALDOMAIN=auth.your-domain.com
      - ZITADEL_EXTERNALPORT=443
      - ZITADEL_MASTERKEY=ThisIsAMasterKeyThatMustBe32Chars
      - ZITADEL_FIRSTINSTANCE_ORG_HUMAN_USERNAME=admin
      - ZITADEL_FIRSTINSTANCE_ORG_HUMAN_PASSWORD=Admin123!
    depends_on:
      db:
        condition: service_healthy
    ports:
      - "127.0.0.1:8080:8080"

  db:
    image: postgres:16-alpine
    container_name: zitadel-db
    restart: always
    environment:
      - POSTGRES_USER=postgres
      - POSTGRES_PASSWORD=PostgresPass123
      - POSTGRES_DB=zitadel
    volumes:
      - zitadel-db:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 10s
      timeout: 5s
      retries: 5

volumes:
  zitadel-db:
EOF

重要：请修改所有密码和 MASTERKEY 为你自己的安全值。MASTERKEY 必须是 32 个字符。

2.3 启动服务

docker compose up -d

查看启动日志，等待初始化完成：

docker compose logs -f zitadel

三、配置 Nginx 反向代理

cat > /etc/nginx/sites-available/zitadel <<'EOF'
server {
    listen 443 ssl http2;
    server_name auth.your-domain.com;

    ssl_certificate /etc/letsencrypt/live/auth.your-domain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/auth.your-domain.com/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        # gRPC 支持
        grpc_pass grpc://127.0.0.1:8080;
    }
}
EOF

ln -sf /etc/nginx/sites-available/zitadel /etc/nginx/sites-enabled/
nginx -t && systemctl reload nginx

四、首次登录和配置

在浏览器中访问 https://auth.your-domain.com，使用初始管理员账号登录：

用户名：admin
密码：Admin123!（首次登录后请立即修改）

五、创建应用

在 Zitadel 管理界面中创建 OIDC 应用：

进入组织管理页面，点击"Projects"创建一个新项目。
在项目中添加应用，选择"Web"类型。
配置回调 URL（Redirect URI），例如 https://your-app.com/callback。
记录下 Client ID 和 Client Secret。

六、OIDC 集成示例

将 Zitadel 作为 OIDC Provider 集成到你的应用中。以下是关键的 OIDC 端点：

# Discovery 端点
https://auth.your-domain.com/.well-known/openid-configuration

# 授权端点
https://auth.your-domain.com/oauth/v2/authorize

# Token 端点
https://auth.your-domain.com/oauth/v2/token

# 用户信息端点
https://auth.your-domain.com/oidc/v1/userinfo

七、用户管理

Zitadel 的管理界面提供了完整的用户管理功能：

用户注册：支持自助注册或管理员创建。
多因素认证：支持 TOTP、WebAuthn 和 U2F。
密码策略：可配置密码复杂度、过期时间等规则。
登录策略：支持外部身份提供者（GitHub、Google 等）。

八、API 管理

Zitadel 提供了丰富的 API 接口用于编程管理：

# 获取管理员 Token
curl -X POST "https://auth.your-domain.com/oauth/v2/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET&scope=openid"

# 获取用户列表
curl "https://auth.your-domain.com/management/v1/users/_search" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query":{"limit":20}}'

九、数据备份

# 备份 PostgreSQL 数据库
docker exec zitadel-db pg_dump -U postgres zitadel > /opt/backups/zitadel_$(date +%Y%m%d).sql

# 设置定时备份
crontab -e
0 3 * * * docker exec zitadel-db pg_dump -U postgres zitadel > /opt/backups/zitadel_$(date +\%Y\%m\%d).sql 2>&1

十、常见问题

初始化失败

确保 PostgreSQL 已正常启动且数据库连接参数正确：

docker compose logs db
docker compose restart zitadel

登录页面无法加载

检查 EXTERNALDOMAIN 和 EXTERNALPORT 配置是否与实际域名一致。

总结

Zitadel 是功能完善的现代身份管理平台，在搬瓦工 VPS 上使用 Docker 可以快速部署。它提供了开箱即用的用户管理、OIDC 认证和多租户支持，非常适合作为个人项目或小型团队的统一身份认证服务。选购搬瓦工 VPS 请参考全部方案，购买时使用优惠码 NODESEEK2026 可享受 6.77% 折扣。相关平台：Casdoor 教程、Logto 教程、Authentik 教程。