SSD Nodes Learn Hosting plans →
Hướng dẫn Matt ConnorBởi Matt Connor · Cập nhật ngày 2026-11-21

Tự host Zitadel trên VPS bằng Docker

Hướng dẫn chạy Zitadel trên một VPS: cần khoảng 512 MB RAM cho app, cấu hình PostgreSQL, masterkey, TLS, SMTP, backup và kiểm tra upgrade database.

Cần gì để tự host Zitadel trên VPS

Để tự host Zitadel trên VPS, bạn cần một Docker host, một tên DNS public trỏ đến host đó, PostgreSQL và đủ CPU, RAM cho cả ứng dụng lẫn cơ sở dữ liệu. Production guide của Zitadel ước tính riêng ứng dụng này dùng khoảng 512 MB RAM và dưới 1 CPU core. Phần làm tài nguyên tăng lên là database và việc băm mật khẩu. Zitadel là một identity provider. Nó phát hành token qua OIDC (OpenID Connect) và SAML (security assertion markup language) để các service khác không phải tự quản lý danh sách user riêng. Bộ cài gồm một curl và một docker compose up. Các thành phần quyết định hệ thống có hoạt động ổn định hay không là masterkey, database user, SMTP (simple mail transfer protocol), backup và lần upgrade đầu tiên.

Toàn bộ nội dung dưới đây giả định bạn dùng Ubuntu 24.04, Docker Engine 24 hoặc mới hơn với Compose plugin phiên bản 2.24.4 hoặc mới hơn, và một tên như auth.example.com đã phân giải đến server. Các lớp phủ TLS dùng !override, nên yêu cầu phiên bản Compose đó.

Zitadel cần VPS cỡ nào?

Compose quickstart trong tài liệu Zitadel yêu cầu 2 GB RAM. Con số này dành cho quickstart. Production guide của Zitadel đưa ra các mức khác.

Biểu đồZitadel's own published sizing guidance, October 2026
Dữ liệu đằng sau biểu đồ này
[
  {
    "config": "Zitadel itself, under 1 core",
    "cpu_cores": 0.5,
    "ram_gb": 0.5
  },
  {
    "config": "HA node, reduced setup",
    "cpu_cores": 4,
    "ram_gb": 8
  },
  {
    "config": "HA node, logs and metrics on",
    "cpu_cores": 4,
    "ram_gb": 16
  }
]

Đó là các khuyến nghị đã công bố, không phải số đo từ một máy đang chạy. Hãy xem chúng như quy mô của bài toán. Bản thân tiến trình Zitadel khá nhỏ: guide ước tính cần khoảng 0.5 GB RAM và nói rằng nó có thể chạy với chưa đến 1 CPU core. Các core là để xử lý password hashing. Tác vụ này được cố ý làm chậm, nên một đợt đăng nhập dồn dập sẽ tạo ra CPU spike. Guide khuyến nghị dành sẵn 4 CPU cores cho việc này. PostgreSQL là phần chi phí tài nguyên còn lại: cùng guide ước tính khoảng 1 core cho mỗi 100 requests mỗi giây và 4 GB RAM cho mỗi core.

Hai dòng lớn hơn không phải là con số cho một máy đơn. Với cấu hình high availability tối thiểu, guide khuyến nghị một cluster gồm 3 nodes, mỗi node có 4 cores và 16 GB. Guide cũng nói có thể giảm xuống khoảng 4 cores và 8 GB cho mỗi node nếu không thu thập log và metrics. Guide không đưa ra sizing cho một node đơn.

Vì vậy, VPS 2 GB sẽ khởi động được stack này, nhưng thấp hơn nhiều so với mức guide dự trù riêng cho database khi có traffic thực tế. Login là service mà mọi service khác phụ thuộc vào. Khi nó down, mọi service tin cậy nó sẽ không cho bất kỳ ai đăng nhập. Nếu bạn quyết định ngân sách cho database và password hashing trong guide vượt quá mức muốn chi cho authentication, đó là một quyết định hợp lý. Đưa ra quyết định ngay bây giờ sẽ rẻ hơn nhiều so với sau khi migration. So sánh Keycloak, Authentik và Zitadel trình bày chi phí của từng hệ thống về memory và công việc vận hành. Một server Authentik tự host thường là lựa chọn phù hợp trên máy nhỏ hơn.

Lấy stack và ghim phiên bản

mkdir zitadel-compose && cd zitadel-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
cp .env.example .env
chmod 600 .env

File này định nghĩa 4 service mà bạn sẽ thực sự chạy. Traefik là reverse proxy: nó định tuyến theo path và, cùng với overlay ở phần dưới, thực hiện TLS termination (bảo mật lớp truyền tải). zitadel-api là binary Go chạy trên cổng 8080. zitadel-login là giao diện đăng nhập được cung cấp tại /ui/v2/login. postgres chứa mọi thứ. Redis cache và OpenTelemetry collector nằm trong cùng file, được đặt sau Compose profile và vẫn tắt cho đến khi bạn yêu cầu chạy.

Chưa chạy docker compose up. Lần start đầu tiên sẽ tạo instance, và sau đó một số setting bên dưới không thể thay đổi nếu không thực hiện thêm công việc.

.env mà bạn đã copy ghim các image tag của chính nó:

ZITADEL_VERSION=v4.16.0
TRAEFIK_IMAGE=traefik:v3.7.7
POSTGRES_IMAGE=postgres:17.10-alpine

Bản release v4 hiện tại là v4.20.3, được phát hành vào ngày 13 tháng 11 năm 2026, mới hơn 4 minor version so với phiên bản được ghim trong file đi kèm. Bản release trước v4.20.0, v4.19.5 từ ngày 15 tháng 10 năm 2026, là bản đầu tiên thuộc phạm vi technical advisory A-10018 của Zitadel: các list endpoint bị ảnh hưởng trong API v1 và v2 hiện áp dụng giới hạn mặc định và giới hạn tối đa, nên client thực hiện list mà không đặt giới hạn sẽ không còn nhận được mọi kết quả mà phải phân trang, còn request yêu cầu nhiều hơn giới hạn tối đa sẽ bị từ chối. Mọi bản release sau đó, bao gồm v4.20.0, đều có thay đổi này. Đặt ZITADEL_VERSION thành phiên bản bạn muốn chạy và dùng dòng v4 thay vì theo dõi bất kỳ phiên bản mới nhất nào. Bỏ qua v4.18.0 nếu bạn tự chọn phiên bản: release note của phiên bản đó cho biết bước setup bị lỗi trong phiên bản này và yêu cầu dùng v4.19.0 thay thế. curl ở trên lấy docker-compose.yml từ nhánh main, nhánh này không được ghim vào commit nào, vì vậy hãy commit bản copy của cả 2 file vào một git repository. Nếu không, cùng một command trên một máy mới vào tháng sau sẽ cho bạn một file khác và bạn sẽ không biết thay đổi nào đã xảy ra.

Thay LOGIN_SESSION_COOKIE_SECRET trong .env bằng một giá trị ngẫu nhiên được tạo bởi openssl rand -base64 32. Login UI dùng giá trị này để ký session cookie, và release note của v4.19.5 cảnh báo rõ không được giữ giá trị mẫu.

Cấp cho Postgres một user riêng và mật khẩu thật

.env đi kèm kết nối Zitadel với PostgreSQL bằng superuser, dùng mật khẩu postgres:

POSTGRES_ADMIN_USER=postgres
POSTGRES_ADMIN_PASSWORD=postgres
ZITADEL_DATABASE_POSTGRES_DSN=postgresql://postgres:postgres@postgres:5432/zitadel?sslmode=disable

Bước hardening ở đây có một điểm dễ nhầm. Tài liệu Zitadel hướng dẫn nối thêm POSTGRES_ZITADEL_PASSWORD vào .env, nhưng docker-compose.yml gốc không đọc biến đó, nên đặt biến này không thay đổi gì. Chỉ thay đổi POSTGRES_ADMIN_PASSWORD sẽ làm hỏng kết nối, vì mật khẩu cũng được ghi trực tiếp bên trong chuỗi DSN (data source name). DSN là dòng quyết định cách Zitadel kết nối.

Các comment trong .env.example giải thích rõ phần còn lại: khi đã cấu hình DSN, Zitadel dùng trực tiếp user đó và không tự tạo user không có đặc quyền cho bạn. Vì vậy role phải tồn tại trước lần khởi động đầu tiên. Tạo một mật khẩu cho role, đặt POSTGRES_ADMIN_PASSWORD thành một mật khẩu ngẫu nhiên riêng trong .env trước khi khởi động Postgres, sau đó chỉ khởi động Postgres và tạo role. Postgres image chỉ áp dụng mật khẩu admin đó khi khởi tạo một data directory trống; thay đổi .env sau đó không đổi mật khẩu của database hiện có.

tr -dc A-Za-z0-9 </dev/urandom | head -c 32; echo

docker compose --env-file .env -f docker-compose.yml up -d postgres

docker compose --env-file .env -f docker-compose.yml exec -T postgres \
  psql -U postgres -d postgres <<'SQL'
CREATE ROLE zitadel LOGIN PASSWORD 'the-password-you-generated';
ALTER DATABASE zitadel OWNER TO zitadel;
SQL

Các lệnh gọi psql chạy bên trong container qua local socket của nó. Official Postgres image tin cậy socket này, nên các lệnh không yêu cầu mật khẩu. Phần quan trọng là ownership. Giai đoạn init của Zitadel tạo các schema riêng (eventstore, projections, system) và các bảng của chúng. Quyền sở hữu database cấp cho role quyền CREATE cần thiết để bootstrap các schema đó. Thay đổi của PostgreSQL 15 đối với quyền CREATE trên schema public là vấn đề riêng và không có nghĩa là việc bootstrap schema của Zitadel sẽ thất bại.

Bây giờ trỏ DSN đến role mới và giữ lại mật khẩu admin bạn đã đặt trước khi khởi động Postgres:

POSTGRES_ADMIN_PASSWORD=a-32-character-random-string
ZITADEL_DATABASE_POSTGRES_DSN=postgresql://zitadel:the-password-you-generated@postgres:5432/zitadel?sslmode=disable

sslmode=disable giữ kết nối database ở trạng thái không mã hóa trên private Compose network; port của nó không bao giờ được publish ra host. Hướng dẫn database của Zitadel khuyến nghị dùng TLS cho kết nối database trong production. Sau lần khởi động đầy đủ đầu tiên, hãy kiểm tra role thực sự sở hữu dữ liệu của mình:

docker compose exec -T postgres psql -U zitadel -d zitadel -c '\dn'

Kết quả phải liệt kê một schema eventstore, một schema projections và một schema system. Nếu thiếu các schema đó, giai đoạn init chưa chạy đến bước này và log của API container sẽ cho biết lý do.

Masterkey và cái giá của việc làm mất nó

Zitadel mã hóa secret trước khi lưu: thông tin xác thực của identity provider, mật khẩu SMTP, seed của one-time-password và machine key. Masterkey mở khóa toàn bộ dữ liệu này. Masterkey có đúng 32 byte. Tài liệu nói rõ hậu quả: không thể thay đổi masterkey nếu không mất quyền truy cập vào dữ liệu đã mã hóa.

Tạo một masterkey rồi thay dòng placeholder trong .env:

tr -dc A-Za-z0-9 </dev/urandom | head -c 32; echo

Sửa dòng ZITADEL_MASTERKEY=MasterkeyNeedsToHave32Characters thay vì thêm một dòng thứ hai. Compose dùng định nghĩa cuối cùng của một key bị lặp, nên thêm dòng mới vẫn có tác dụng. Tuy nhiên, file có hai dòng masterkey sẽ dễ gây nhầm lẫn cho người đọc và bảo trì tiếp theo.

Bây giờ hãy xem key đó nằm ở đâu. Compose khởi động API container như sau:

command: start-from-init --masterkey "${ZITADEL_MASTERKEY}"

Vì vậy, masterkey nằm trên command line của container. docker inspect hiển thị masterkey cho bất kỳ ai có thể truy cập Docker socket. Trên một VPS chỉ có một admin, đây là một đánh đổi có thể chấp nhận được. Mode trên .env là thứ bảo vệ masterkey trên disk. Nếu cách này không chấp nhận được, hãy mount key dưới dạng file và dùng --masterkeyFile /run/secrets/zitadel-masterkey thay thế. Cách này giữ giá trị đó khỏi process arguments.

Hãy sao chép masterkey vào password manager trước lần khởi động đầu tiên. Masterkey không xuất hiện trong database dump. Vì vậy, nếu restore dump bằng một masterkey khác, instance sẽ không thể đọc các secret của chính nó. Lưu masterkey ở nơi khác với archive chứa dump, để một backup bị đánh cắp không đồng thời chứa cả dữ liệu đã mã hóa và key dùng để mở khóa dữ liệu đó.

Đặt domain bên ngoài trước lần khởi động đầu tiên

ZITADEL_DOMAIN trong .env truyền giá trị vào ZITADEL_EXTERNALDOMAIN trong container, đồng thời đây là tên mà người dùng nhập. Zitadel dùng giá trị này để tạo OIDC issuer, base URI của giao diện đăng nhập, các endpoint SAML và tên đăng nhập của admin đầu tiên, nên đây không phải thông tin chỉ để hiển thị.

ZITADEL_DOMAIN=auth.example.com
ZITADEL_EXTERNALPORT=443
ZITADEL_EXTERNALSECURE=true

Zitadel xác định instance mà bạn đang truy cập dựa trên header Host. Nếu header đó không khớp với domain mà Zitadel biết, mọi request đều nhận cùng một phản hồi:

ID=QUERY-1kIjX Message=Instance not found

Khi thấy lỗi đó, hãy kiểm tra hai điểm. Có thể ZITADEL_DOMAIN không phải là tên bạn đang truy cập, hoặc proxy phía trước đang sửa Host thành địa chỉ upstream. Truy cập server bằng địa chỉ IP thay vì tên cũng gây ra lỗi này.

Bạn có thể thay đổi các giá trị này sau. Zitadel phải chạy lại giai đoạn thiết lập để nhận thay đổi, và mọi ứng dụng đã đăng ký vẫn giữ các redirect URI cũ. Chọn tên cuối cùng ngay bây giờ sẽ ít tốn công hơn nhiều so với việc đổi tên sau này.

Kết thúc TLS bằng overlay Let's Encrypt

Với domain public, hãy thêm overlay Let's Encrypt của Zitadel. Overlay này chuyển Traefik sang HTTP challenge của ACME (automatic certificate management environment) và thay các port được publish bằng 80 và 443, vì vậy không có tiến trình nào khác trên máy được chiếm một trong hai port này.

curl -fsSLO https://raw.githubusercontent.com/zitadel/zitadel/main/deploy/compose/docker-compose.mode-letsencrypt.yml
echo 'LETSENCRYPT_EMAIL=ops@example.com' >> .env

Overlay cũng đặt ZITADEL_EXTERNALPORT: 443 và ZITADEL_EXTERNALSECURE: true trên API container. Vì vậy, public URL và các URL mà Zitadel tự tạo sẽ khớp nhau. A record phải phân giải được trước khi bạn khởi động, vì HTTP challenge sẽ fail nếu không có bản ghi này.

Nếu bạn đã terminate TLS trên nginx hoặc load balancer, hãy dùng docker-compose.mode-external-tls.yml thay thế và đặt TRAEFIK_TRUSTED_IPS thành các range mà proxy của bạn gửi request từ đó. Traefik chỉ chấp nhận các header X-Forwarded-* từ những địa chỉ nằm trong danh sách đó. Overlay đặt rõ external URL và login URL của Zitadel thành HTTPS.

Upstream proxy phải làm đúng hai việc mà Zitadel yêu cầu nghiêm ngặt. Proxy phải dùng HTTP/2 để kết nối đến backend, vì API dùng gRPC. Proxy cũng phải chuyển tiếp nguyên trạng Host cùng với X-Forwarded-Proto: https. Với Compose stack này, cấu hình nginx có dạng sau:

server {
    listen 443 ssl;
    http2 on;
    ssl_certificate     /etc/certs/selfsigned.crt;
    ssl_certificate_key /etc/certs/selfsigned.key;
    location /ui/v2/login {
        proxy_pass http://YOUR_LOGIN_UPSTREAM:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto https;
    }
    location / {
        grpc_pass grpc://YOUR_API_UPSTREAM:8080;
        grpc_set_header Host $host;
        grpc_set_header X-Forwarded-Proto https;
    }
}

Thay các placeholder của upstream bằng những địa chỉ mà nginx có thể truy cập. Nếu bạn serve Zitadel trên port khác 443, hãy dùng grpc_set_header Host $host:$server_port; để port được truyền kèm theo header. Phần còn lại là một virtual host thông thường. Cấu hình nginx reverse proxy được giải thích từng dòng trình bày các phần không riêng cho Zitadel.

Quản trị viên đầu tiên và buộc đổi mật khẩu

Lần khởi động đầu tiên tạo một instance, một organisation và một tài khoản admin người dùng. Tên đăng nhập là zitadel-admin@ cộng với zitadel. cộng với domain bên ngoài của bạn. Với ZITADEL_DOMAIN=auth.example.com, tên này là:

zitadel-admin@zitadel.auth.example.com

Mật khẩu là Password1! nếu bạn không đặt mật khẩu riêng. Mặc định từ upstream của Zitadel là buộc đổi mật khẩu ở lần đăng nhập đầu tiên, nhưng file compose được cung cấp đã ghi đè mặc định đó:

ZITADEL_FIRSTINSTANCE_ORG_HUMAN_PASSWORDCHANGEREQUIRED: false

Dòng này được hardcode trong docker-compose.yml thay vì đọc từ .env. Vì vậy, hãy đặt các giá trị riêng trong một overlay nhỏ của bạn. Đặt tên file là docker-compose.local.yml:

services:
  zitadel-api:
    environment:
      ZITADEL_FIRSTINSTANCE_ORG_HUMAN_EMAIL_ADDRESS: you@example.com
      ZITADEL_FIRSTINSTANCE_ORG_HUMAN_PASSWORD: "a-long-temporary-password"
      ZITADEL_FIRSTINSTANCE_ORG_HUMAN_PASSWORDCHANGEREQUIRED: "true"

Compose chỉ tự tải docker-compose.override.yml khi bạn chạy lệnh mà không có flag -f. Tuy nhiên, mọi lệnh trong hướng dẫn của Zitadel đều truyền -f, khiến cơ chế đó bị tắt. Thay vì phải lặp lại danh sách flag ngày càng dài, hãy cố định danh sách file trong .env:

COMPOSE_FILE=docker-compose.yml:docker-compose.mode-letsencrypt.yml:docker-compose.local.yml

Bây giờ hãy khởi động:

docker compose pull
docker compose up -d --wait

--wait giữ lệnh chạy cho đến khi các healthcheck đạt yêu cầu. Khi API container không bao giờ đạt trạng thái đó, Compose dừng với dependency failed to start: container zitadel-zitadel-api-1 is unhealthy, còn docker compose logs zitadel-api chứa lý do. Container được đặt tên theo project. File compose được cung cấp tự đặt tên này bằng name: zitadel ở cấp cao nhất, nên tên thư mục không xuất hiện. Ở lần khởi động đầu tiên, nguyên nhân thường là độ dài masterkey hoặc DSN của database.

Đăng nhập tại https://auth.example.com/ui/console, đổi mật khẩu, rồi bật second factor cho tài khoản đó trước khi tạo bất kỳ thứ gì khác. Mỗi giá trị ZITADEL_FIRSTINSTANCE_* chỉ có hiệu lực trong lúc instance đầu tiên được tạo. Sau khi instance đã tồn tại, chỉnh sửa các giá trị này sẽ không có tác dụng.

Vì sao password reset không làm gì cho đến khi SMTP hoạt động

Một identity provider không thể gửi mail sẽ hỏng theo cách khó phát hiện trong nhiều tuần. Zitadel gửi email cho lời mời người dùng, xác minh địa chỉ, link password reset, mã dùng một lần và thông báo claim domain. Khi chưa cấu hình SMTP provider, Console vẫn báo thao tác đã hoàn tất, còn message được chuyển sang xử lý notification nhưng không có nơi để gửi. Trong v4.20.0, notification mặc định dùng legacy mode (LegacyEnabled: true), nên bỏ qua các thiết lập MaxAttempts: 3 và MaxTtl: 5m của worker chạy song song. Các giá trị đó không mô tả hành vi retry notification mặc định. Người đang chờ link không nhận được thông báo nào.

Cấu hình trong Console, tại phần instance settings ở https://auth.example.com/ui/console/settings. Form SMTP provider yêu cầu email người gửi, tên người gửi, host và port, user, SMTP password và tùy chọn TLS. Hãy dùng nút test trong form trước khi lưu, vì nút này gửi một message thật: message sẽ đến nơi hoặc không. Kích hoạt provider để Zitadel dùng provider đó gửi mail.

Có một bộ environment variable tương ứng là ZITADEL_DEFAULTINSTANCE_SMTPCONFIGURATION_SMTP_HOST và các biến liên quan. Chúng được áp dụng khi tạo instance. Với stack đã chạy, các biến này không có tác dụng, vì vậy Console là nơi phù hợp để cấu hình instance hiện có.

Có 2 điểm cần lưu ý về việc gửi mail từ VPS, vì đây là nguyên nhân thường gây lỗi. Hãy kiểm tra chính sách SMTP outbound của provider trước khi chọn relay: DigitalOcean mặc định chặn port 25, 465 và 587 trên Droplet, nên port 587 không phải cách khắc phục dùng được trong mọi trường hợp. Hãy dùng authenticated relay trên một port được provider cho phép. Đồng thời, hãy publish bản ghi SPF (sender policy framework) và DKIM (domainkeys identified mail) cho domain gửi mail; nếu không, link reset sẽ rơi vào spam, khiến người dùng thấy đúng như mail chưa từng được gửi.

Trên v4.20.0, các kết nối SMTP TLS outbound từ chối certificate chain đi qua các intermediate CA eMudhra đã bị compromise. Relay bị ảnh hưởng cần dùng certificate thay thế.

Hãy kiểm tra trước khi mời bất kỳ ai. Tạo một user dùng tạm, yêu cầu password reset và theo dõi xem message có đến nơi không. Nếu message không đến, docker compose logs -f zitadel-api cho biết lỗi SMTP. SMTP password được lưu dưới dạng encrypted trong database; đó là một dữ liệu khác mà masterkey đang bảo vệ cho bạn.

Sao lưu riêng biệt Postgres và masterkey

Mọi dữ liệu mà Zitadel quản lý đều nằm trong PostgreSQL. Thành phần giải mã dữ liệu đó là masterkey. Hãy sao lưu chúng vào hai vị trí khác nhau.

Đầu tiên là dump dữ liệu:

sudo install -d -m 700 /srv/zitadel-backups
docker compose exec -T postgres \
  pg_dump -U postgres -Fc zitadel > "/srv/zitadel-backups/zitadel-$(date +%F).dump"

-Fc là định dạng tùy chỉnh, giúp nén dữ liệu ngay khi xuất ra và pg_restore có thể đọc chọn lọc. exec -T loại bỏ terminal, điều này quan trọng vì lệnh này chạy từ cron mà không có terminal đính kèm.

Sau đó, đẩy thư mục đó ra ngoài site bằng restic, công cụ này sẽ mã hóa và khử trùng lặp dữ liệu:

export RESTIC_REPOSITORY="sftp:backup@backup.example.com:/srv/restic/zitadel"
export RESTIC_PASSWORD_FILE=/root/.restic-password
restic init
restic backup /srv/zitadel-backups
restic forget --keep-daily 7 --keep-weekly 4 --keep-monthly 6 --prune

restic init chỉ chạy một lần vào ngày đầu tiên. Đặt lệnh dump và hai lệnh cuối vào /usr/local/bin/zitadel-backup.sh và chạy hàng đêm:

0 3 * * * /usr/local/bin/zitadel-backup.sh

Sao lưu .env và mọi file compose bạn sử dụng vào git. Masterkey là ngoại lệ đối với tất cả các quy trình này. Nó phải nằm trong trình quản lý mật khẩu của bạn và tại một vị trí thứ hai không phải là repository restic này, vì một kho lưu trữ chứa cả cơ sở dữ liệu và khóa giải mã của nó sẽ không còn là bản sao lưu của một hệ thống đã mã hóa nữa.

Một bản sao lưu chưa được khôi phục chỉ là một sự phỏng đoán. Hãy khôi phục vào một cơ sở dữ liệu tạm trên cùng máy chủ và kiểm tra nó:

docker compose exec -T postgres createdb -U postgres zitadel_restore_test
docker compose exec -T postgres pg_restore -U postgres -d zitadel_restore_test \
  < /srv/zitadel-backups/zitadel-2026-08-21.dump
docker compose exec -T postgres psql -U postgres -d zitadel_restore_test -c '\dt eventstore.*'
docker compose exec -T postgres dropdb -U postgres zitadel_restore_test

Danh sách các bảng trong schema eventstore cho thấy bản dump hợp lệ. Lỗi thông báo schema không tồn tại nghĩa là bản dump không hợp lệ, và bạn đã phát hiện ra điều đó vào một ngày mà bạn không bị thiệt hại gì. Mô hình chung để sao lưu và nâng cấp một Compose stack áp dụng ở đây gần như không thay đổi, và việc giữ masterkey nằm ngoài kho lưu trữ là phần duy nhất dành riêng cho Zitadel.

Nâng cấp Zitadel mà không làm mất instance

Nâng cấp là đổi version trong .env rồi chạy hai lệnh:

docker compose pull
docker compose up -d --wait

Hãy hiểu lệnh thứ hai làm gì trước khi chạy nó trên một hệ thống có người dùng đăng nhập. Command của container là start-from-init. Command này chạy các phase init và setup trước khi bắt đầu phục vụ request, trong đó phase setup là các migration cho database. Vì vậy, việc đổi version sẽ chạy schema migration trên database đang hoạt động ngay khi container start, không cần thao tác thủ công, trong khi --wait chờ healthcheck. Đó là lý do duy nhất khiến việc test restore ở trên không phải tùy chọn.

Tạo một dump mới ngay trước khi nâng cấp. Dump của tối hôm trước là một thứ khác.

Với v4.20.3, các lần đăng nhập qua external identity provider đang diễn ra phải được bắt đầu lại, còn các authorization code của Login V1 chưa được redeem sẽ bị từ chối một lần. Login UI tùy chỉnh cần permission session.link để hoàn tất request OIDC hoặc SAML; hãy cấp role IAM_LOGIN_CLIENT cho service user của UI trước khi nâng cấp. Service user đi kèm Login V2 đã có role đó. Kiểm tra password qua Session API hiện tuân theo login policy của organisation của user, vì vậy các organisation tắt đăng nhập bằng username/password phải đưa user đến identity provider của họ.

Không được bỏ qua một major version. Trước khi chuyển từ v3 sang v4, trước hết hãy dùng v3.4.1 hoặc mới hơn. v4 bắt buộc phải có OIDC web keys và loại bỏ signing path cũ. Vì vậy, nếu instance v3 của bạn chưa từng bật web keys, các token được ký bằng legacy keys cũ sẽ không còn xác minh được sau khi nâng cấp. Technical advisory A-10017 của Zitadel cho biết access token JWT và ID token hiện có có thể mất hiệu lực ngay lập tức, đồng thời user có thể phải đăng nhập lại. Cách khắc phục là chuyển qua v3.4.1 hoặc mới hơn, rồi chờ các token được ký bằng legacy keys và session hết hạn trước khi nâng cấp; hoặc chấp nhận một khoảng thời gian người dùng phải đăng nhập lại theo kế hoạch. Nếu bạn đã chạy v3.4.1 hoặc mới hơn và đã chờ kể từ khi bật web keys, advisory cho biết không cần thực hiện thêm hành động nào.

Theo dõi phase setup bằng docker compose logs -f zitadel-api. Migration trên eventstore lớn có thể mất vài phút, còn Traefik sẽ không route đến API cho đến khi healthcheck pass, nên site sẽ down trong khoảng thời gian đó. Hãy lập kế hoạch cho việc này thay vì để đến lúc xảy ra mới phát hiện.

Rollback không chỉ là đặt lại tag cũ. Sau khi migration đã chạy, binary cũ không hiểu schema mà nó gặp, nên rollback có nghĩa là restore dump. Khi instance đã có user thật, hãy chuyển sang docker-compose.prodlike.yml, overlay chạy init và setup thành các bước tách biệt với start. Khi đó, migration là việc bạn chủ động trigger và theo dõi, thay vì là tác dụng phụ của việc restart container.

Cấu hình trỏ đến identity provider mới của bạn

Trong Console, hãy tạo một project và sau đó là một application bên trong đó. Hãy chọn OIDC cho bất kỳ ứng dụng hiện đại nào, Zitadel sẽ cung cấp cho bạn một client ID, một client secret và một discovery document tại https://auth.example.com/.well-known/openid-configuration. Hầu hết các phần mềm tự host hỗ trợ single sign-on đều yêu cầu chính xác các thông tin này.

Nhiều phần mềm không hỗ trợ tính năng này, hoặc chỉ hỗ trợ trong các gói trả phí. Đối với trường hợp đầu tiên, oauth2-proxy đặt trước ứng dụng sẽ biến bất kỳ dịch vụ HTTP nào thành một dịch vụ được Zitadel bảo vệ. Đối với trường hợp thứ hai, bạn nên đọc bài thuế SSO trong các ứng dụng tự host trước khi lên kế hoạch di chuyển hệ thống dựa trên một tính năng mà bạn chưa trả phí.

FAQ

Tự host Zitadel cần bao nhiêu RAM và CPU?

Production guide của Zitadel cho biết bản thân Zitadel cần khoảng 0.5 GB RAM và có thể chạy với dưới 1 CPU core, đồng thời khuyến nghị dành sẵn 4 cores cho việc băm mật khẩu. PostgreSQL được tính riêng, khoảng 1 core cho mỗi 100 requests/giây và 4 GB RAM cho mỗi core. Các con số lớn hơn trong guide là cho mỗi node trong một cluster high availability 3 node: 4 cores và 16 GB mỗi node, hoặc khoảng 4 cores và 8 GB nếu không thu thập log và metrics. Compose quickstart yêu cầu ít nhất 2 GB, đủ để dùng thử nhưng còn rất ít dung lượng cho database mà các service khác trên hệ thống sẽ cần.

Nếu mất masterkey của Zitadel thì chuyện gì xảy ra?

Mọi dữ liệu được mã hóa bằng key đó vẫn ở trạng thái mã hóa. Không thể giải mã thông tin xác thực của identity provider, mật khẩu SMTP và seed của one-time password; đồng thời không thể thay key sau đó. Chỉ có database dump thì không thể khôi phục instance hoạt động, vì dump chứa ciphertext nhưng không có key. Hãy lưu masterkey trong password manager và tại một nơi tách biệt với backup chứa dump. Nếu mất cả hai, cách duy nhất còn lại là dựng lại instance từ đầu.

Vì sao email reset mật khẩu Zitadel không bao giờ đến?

Vì chưa cấu hình SMTP provider hoặc provider đã cấu hình không thể gửi email. Zitadel v4.20.0 mặc định sử dụng cơ chế xử lý notification cũ, nên các thiết lập 3 lần thử và 5 phút của parallel worker bị bỏ qua. Hãy cấu hình SMTP provider trong instance settings và dùng nút test trong form đó; nút này sẽ gửi một email thật. Kích hoạt provider, dùng authenticated relay trên một port mà nhà cung cấp VPS cho phép, đồng thời publish các record SPF và DKIM cho sending domain để email không bị lọc thành spam.

Có thể đổi external domain của Zitadel sau khi cài đặt không?

Có, nhưng không phải chỉ bằng cách sửa .env. Hãy đổi ZITADEL_EXTERNALDOMAIN, ZITADEL_EXTERNALPORT và ZITADEL_EXTERNALSECURE, sau đó để Zitadel chạy lại setup phase để nhận thay đổi. Các application đã đăng ký vẫn giữ redirect URI cũ và phải cập nhật thủ công. Mọi request có header Host không khớp với domain mà Zitadel biết sẽ nhận về Instance not found. Chọn tên cuối cùng trước lần khởi động đầu tiên sẽ tránh được toàn bộ vấn đề này.

Bài viết này có hữu ích không?