跳至主要內容

部署與設定

在前一篇文章中，我們介紹了快速開始使用 Logto的基本流程。本篇將更深入探討，聚焦於在生產環境部署 Logto 的最佳實踐與詳細設定步驟。

環境變數​

我們在示範（docker-compose.yml）中使用了一組預設產生的環境變數，你應該替換為自己的設定，並在多個 Logto 實例間保持一致。

你可以直接設定環境變數，或將 .env 檔案放在 Logto 專案根目錄。如果你用 Docker 測試，請查看映像檔在 /etc/logto 產生的 .env。

基本必備​

  • DB_URL Logto 資料庫的 Postgres DSN。
  • PORT Logto 監聽的埠號，預設為 3001。
  • ENDPOINT 你可以指定自訂網域的 URL 作為生產環境端點（例如：ENDPOINT=https://logto.domain.com）。這也會影響 OIDC 簽發者識別碼 (Issuer Identifier) 的值。

啟用管理主控台（Admin Console）

  • ADMIN_PORT Logto 管理主控台監聽的埠號，預設為 3002。
  • ADMIN_ENDPOINT 你可以指定自訂網域的 URL 作為生產環境端點（例如：ADMIN_ENDPOINT=https://admin.domain.com）。這也會影響管理主控台重新導向 URI 的值。

停用管理主控台（Admin Console）

  • ADMIN_DISABLE_LOCALHOST 設為 1 或 true 可關閉管理主控台的埠號。若未設定 ADMIN_ENDPOINT，將完全停用管理主控台。

更多環境變數細節，請參閱設定說明。

啟用 Secret Vault

  • 若要使用 Secret Vault，你需要將 SECRET_VAULT_KEK 設為 Key Encryption Key (KEK) 的 base64 編碼字串。這用於加密 Secret Vault 中的 Data Encryption Keys (DEK)。建議使用 AES-256（32 bytes）。範例：crypto.randomBytes(32).toString('base64')。

HTTPS​

你可以直接用 Node.js 提供 HTTPS 服務，或在 Node.js 前設置 HTTPS 代理 / 負載平衡器。詳情請參閱啟用 HTTPS。

反向代理​

如果你想在伺服器上使用反向代理（如 Nginx 或 Apache），需要在代理設定中分別對應 3001 與 3002 埠。假設你使用 Nginx，Logto 驗證端點運行於 3001 埠，管理主控台運行於 3002 埠，請在 nginx.conf 中加入以下設定：

server {
  listen 443 ssl;
  server_name <your_endpoint_url>; // 例如 auth.your-domain.com
  ...

  location / {
    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 https;

    proxy_pass http://127.0.0.1:3001;
  }

  ssl_certificate <path-to-your-certificate-for-auth-endpoint>;
  ssl_certificate_key <path-to-your-certificate-key-for-auth-endpoint>
  ...
}

然後為管理主控台加入類似設定：

server {
  listen 443 ssl;
  server_name <your_admin_endpoint_url>; // 例如 admin.your-domain.com
  ...

  location / {
    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 https;

    proxy_pass http://127.0.0.1:3002;
  }

  ssl_certificate <path-to-your-certificate-for-admin-endpoint>;
  ssl_certificate_key <path-to-your-certificate-key-for-admin-endpoint>
  ...
}

重新載入 Nginx 設定以套用最新變更：

nginx -s reload

一切就緒。打開瀏覽器並造訪 https://admin.your-domain.com，你應該可以看到 Logto 歡迎頁面。

容器化​

在生產環境中，你可以使用 Docker 將 Logto 容器化。專案根目錄下有 Dockerfile。如果你想執行多個 Logto 實例，例如在 Kubernetes 叢集部署 Logto，還需額外步驟。

共用 connectors 資料夾​

預設情況下，Logto 會在 core 資料夾根目錄下建立 connectors 資料夾。我們建議多個 Logto 實例間共用此資料夾，你需要將 packages/core/connectors 資料夾掛載到容器，並執行 npm run cli connector add -- --official 來部署連接器。

以下是 Kubernetes 的最小範例 deployment：

apiVersion: extensions/v1beta1
kind: Deployment
metadata:
  name: logto
  namespace: default
spec:
  template:
    spec:
      volumes:
        - name: connectors
          emptyDir: {}
      initContainers:
        - image: ghcr.io/logto-io/logto
          command:
            - /bin/sh
          args:
            - '-c'
            - 'npm run cli connector add -- --official'
          name: init
          volumeMounts:
            - name: connectors
              mountPath: /etc/logto/packages/core/connectors
      containers:
        - image: ghcr.io/logto-io/logto
          name: logto
          volumeMounts:
            - name: connectors
              mountPath: /etc/logto/packages/core/connectors

在這個範例中，我們建立一個空目錄作為 volume 並掛載到容器。然後在 init container 執行 npm run cli connector add -- --official 下載連接器。最後，每個容器都會共用同一個已包含官方連接器的 connectors 資料夾。

備註:

這是一個 yaml 範例，實際執行 Logto 前，請正確設定環境變數。

在生產環境中，你可以將 "empty dir" volume 換成持久性 volume，並用你自己的方式執行 "init" 任務，只要你知道自己在做什麼！

資料庫變更​

與 connectors 類似，資料庫變更（alteration）需在單一實例執行。你可以用 job 來執行變更腳本。

當以非互動方式執行變更時，必須設定 CI=true 環境變數。

apiVersion: batch/v1
kind: Job
metadata:
  name: alteration
spec:
  template:
    spec:
      containers:
        - name: alteration
          image: ghcr.io/logto-io/logto
          imagePullPolicy: Always
          env:
            - name: CI
              value: 'true'
            - name: DB_URL
              value: postgresql://user:password@localhost:5432/logto
          command:
            - /bin/sh
          args:
            - '-c'
            - 'npm run alteration deploy latest'
      restartPolicy: Never

關於變更指令的詳細說明，請參閱資料庫變更。