跳至主要內容

升級你的 OSS 版本

Logto 遵循 semver。你可以在 GitHub Releases 找到每個版本及其變更。本指南說明升級的運作方式、如何升級各種常見部署類型，以及如何解決你可能遇到的問題。

升級的運作方式​

一次升級包含兩個部分：

  1. Logto 程式碼：你執行的 Docker 映像檔或發行版壓縮檔。
  2. 資料庫結構：版本間的結構變更會以資料庫變更檔（alterations）形式隨附，你需透過 Logto CLI 來部署。你的資料庫會記錄已部署的變更。

當 Logto 啟動時，會檢查資料庫。如果本版本包含的任何變更尚未部署，Logto 將拒絕啟動：

Found undeployed database alterations, you must deploy them first by npm run alteration deploy command.
...
Error: Undeployed database alterations found.

變更設計為與前一版本的 Logto 相容，因此仍在執行舊版本的實例在變更部署後可繼續運作。這帶來以下順序，可避免停機：

  1. 使用 新 版本的 Logto 部署變更。
  2. 用新版本取代正在執行的實例。

建議在開始前備份資料庫。

資訊:

務必使用你要升級到的新版本所附的 CLI 來部署變更，例如新的 Docker 映像檔或新的發行版壓縮檔。變更腳本與 CLI 綁定，舊版 CLI 無法部署新版 Logto 的變更。

你可以一次跨多個版本升級。部署目標版本的變更時，會依序部署所有中間版本的變更。

升級前須知​

  • 閱讀所有版本的發行說明，從你目前版本到目標版本。
  • 備份你的資料庫（建議），例如使用 pg_dump 或資料庫供應商的快照功能。雖然變更可回滾，但備份是最可靠的還原方式。
  • 鎖定目標版本。 請使用明確版本號（如 ghcr.io/logto-io/logto:1.45.0），不要用 latest。若用 latest，重啟或拉取新映像檔時可能會在變更尚未部署前升級 Logto，導致無法啟動。
  • 檢查 Node.js 需求，如果你直接用 Node.js 執行 Logto。每個發行版會在其 package.json 的 engines 欄位聲明需求。目前版本需 Node.js ^26.0.0。
  • 檢查你的自訂連接器，如果有的話。請參閱 升級後自訂連接器被略過。
  • 先升級測試環境，如果你有獨立資料庫的測試環境。若測試環境與正式環境共用資料庫，從測試環境部署變更也會改動正式資料庫。因為變更與前一版本相容，正式環境的舊版實例仍可運作。

升級步驟​

以下範例中，1.45.0 為目標版本。請用你自己的版本號與資料庫 URL 取代。

Docker​

  1. 拉取新映像檔：

    docker pull ghcr.io/logto-io/logto:1.45.0

  2. 用新映像檔部署變更。這步驟期間你現有的 Logto container 會持續運作：

    docker run --rm \
      -e DB_URL=postgres://username:password@your_postgres_url:port/db_name \
      ghcr.io/logto-io/logto:1.45.0 \
      alteration deploy 1.45.0

    你應會看到類似以下的輸出。變更的數量與名稱取決於你跨越的版本：

    info Deploy target 1.45.0
    info Found 1 alteration to deploy
    info Run alteration 1.45.0-1791531333-add-tenant-viewer-role.js `up()` function succeeded
    備註:

    映像檔的 entrypoint 是 npm run，所以映像檔名稱後的參數會傳給 npm run。請寫 alteration deploy 1.45.0，不要寫 npm run alteration deploy 1.45.0。

  3. 用新映像檔取代正在執行的 container。保持原有的 port、環境變數等設定：

    docker stop logto && docker rm logto
    docker run -d --name logto \
      -p 3001:3001 \
      -p 3002:3002 \
      -e DB_URL=postgres://username:password@your_postgres_url:port/db_name \
      ghcr.io/logto-io/logto:1.45.0

Docker Compose​

  1. 在 Compose 檔案中更新 Logto 服務的映像標籤，然後拉取：

    services:
      logto:
        image: ghcr.io/logto-io/logto:1.45.0
    docker compose pull logto

  2. 用新映像檔在一次性 container 中部署變更：

    docker compose run --rm --entrypoint sh logto -c "npm run alteration deploy 1.45.0"

    請將 logto 替換為你 Compose 檔案中 Logto 服務的名稱（demo docker-compose.yml 取名為 app）。覆寫 entrypoint 可確保即使服務自訂了 entrypoint（如 demo 檔案），指令也能運作。

  3. 用新映像檔重建 Logto container：

    docker compose up -d logto
提示:

如果你只執行單一 Logto 實例，可以讓 container 每次啟動時自動初始化新資料庫並部署變更：

services:
  logto:
    image: ghcr.io/logto-io/logto:1.45.0
    entrypoint:
      ['sh', '-c', 'npm run cli db seed -- --swe && npm run alteration deploy latest && npm start']

這裡的 latest 代表映像檔內含的最新版本，因此變更總是與你執行的映像檔一致。多實例時請勿用此方式。原因請見 Kubernetes。

注意:

如果你的架構基於 demo docker-compose.yml，其 Postgres container 資料存於匿名 volume。匿名 volume 在 docker compose down 後不會再掛載，所以下次 docker compose up 會用空資料庫。請在執行 docker compose down 前，將資料移至具名 volume 或外部資料庫。

Kubernetes​

先用 Job 部署變更，再發佈新映像檔。

  1. 建立一個 Job，使用新映像檔執行變更：

    apiVersion: batch/v1
    kind: Job
    metadata:
      name: logto-alteration-1-45-0
    spec:
      backoffLimit: 0
      template:
        spec:
          restartPolicy: Never
          containers:
            - name: alteration
              image: ghcr.io/logto-io/logto:1.45.0
              command: ['/bin/sh', '-c', 'npm run alteration deploy 1.45.0']
              env:
                - name: DB_URL
                  valueFrom:
                    secretKeyRef:
                      name: logto
                      key: db-url

    套用並等待完成：

    kubectl apply -f logto-alteration-job.yaml
    kubectl wait --for=condition=complete job/logto-alteration-1-45-0 --timeout=10m
    kubectl logs job/logto-alteration-1-45-0

  2. 更新 Logto Deployment 的映像檔並等待發佈。如果你的 Deployment 有使用 Logto 映像檔的 init container（如 共用連接器資料夾 範例），也要一併更新：

    kubectl set image deployment/logto logto=ghcr.io/logto-io/logto:1.45.0
    kubectl rollout status deployment/logto

如果你用 Helm 或 GitOps 工具部署，請在 Deployment 更新前先執行 Job，例如用 Helm 的 pre-upgrade hook 或 Argo CD 的 PreSync hook。

注意:

請只從一個地方部署變更。CLI 在部署變更時不會鎖定資料庫，因此不要在每個副本的啟動指令中都部署變更。

Node.js​

如果你用 npm init @logto 或發行版壓縮檔安裝 Logto，請將新版本安裝在現有版本旁邊。升級完成前保留原目錄，以便快速切換回去。

  1. 確認你的 Node.js 版本符合新版本需求。

  2. 下載並解壓新發行版：

    curl -fL -o logto-1.45.0.tar.gz https://github.com/logto-io/logto/releases/download/v1.45.0/logto.tar.gz
    mkdir logto-1.45.0
    tar -xzf logto-1.45.0.tar.gz -C logto-1.45.0 --strip-components=1

    若要取得最新版，也可執行 npm init @logto@latest -- --path ./logto-new --skip-seed。因為你的資料庫已存在，必須加上 --skip-seed。

  3. 從現有安裝（預設 ~/logto）複製設定檔：

    cp ~/logto/.env logto-1.45.0/.env

  4. 官方連接器已包含於發行版。如有其他連接器，請再次加入新目錄，例如：

    cd logto-1.45.0
    npm run cli connector add <connector-package-name>

  5. 從新目錄部署變更。CLI 會從 .env 讀取 DB_URL：

    npm run alteration deploy 1.45.0

  6. 停止現有 Logto 程序，並從新目錄啟動新版本：

    npm start

    如果你用 systemd 或 pm2 等程序管理器，請將其工作目錄更新為新目錄。

雲端主機服務商​

如果你用雲端主機服務商的一鍵部署模板安裝 Logto，請將 Logto 映像標籤改為目標版本。在新版本啟動前，使用服務商的一次性指令或 shell 功能，搭配新映像檔執行 npm run alteration deploy 1.45.0 部署變更。若為單一實例，也可參考 Docker Compose 小技巧 的啟動指令。模板由服務商維護，細節請查閱其文件。

回滾​

如果新版本運作不如預期：

  • 切回前一版本。 因為變更與前一版本的 Logto 相容，通常可直接執行前一版本而不需動資料庫。僅適用於目標版本的前一版。如果你跨多個版本升級，也需回滾變更。

  • 回滾變更。 請用 新 版本執行回滾，因為前一版本不含新版變更腳本。然後再啟動前一版本。例如，Docker 指令如下：

    docker run --rm \
      -e DB_URL=postgres://username:password@your_postgres_url:port/db_name \
      ghcr.io/logto-io/logto:1.45.0 \
      alteration rollback 1.44.0

    回滾後，若未重新部署變更，新版本將無法啟動。詳情請見 回滾變更。

  • 還原備份，如果你有備份的話。這是最可靠的方式，但備份後寫入的資料會遺失。

疑難排解​

升級後 Logto 無法啟動​

若日誌顯示 Undeployed database alterations found，請依 升級步驟 部署變更。

如果你已部署變更但仍出現此錯誤，可能是用舊版 CLI 部署（如全域安裝的 logto 指令或解析到舊版的 npx @logto/cli）。此時 CLI 會顯示 Found 0 alteration to deploy，因為它不認得新版變更。請用新版本的 CLI（新 Docker 映像檔、新發行版目錄，或 npx @logto/cli@1.45.0 db alteration deploy 1.45.0）重新部署。

重啟後 Logto 啟動失敗​

如果你用 latest 標籤，重啟或拉取新映像檔時可能已升級 Logto 但未部署變更。請用你正在執行的映像檔部署變更，並改用明確版本號以避免非預期升級。

Error: Missing target version​

沒有互動式終端機時，CLI 無法詢問要部署哪個版本。請明確傳入目標版本（如 alteration deploy 1.45.0），或用 alteration deploy latest 部署到 CLI 內含的最新版本。

npm error Missing script: "npm"​

你在 docker run 的映像檔名稱後加上了 npm run alteration ...。映像檔的 entrypoint 已是 npm run，請直接傳入 alteration deploy 1.45.0。

變更失敗​

每個變更都在交易中執行，因此失敗不會留下部分變更。請修正原因後重試，已部署的變更會自動略過。常見原因：

  • 語句逾時（Statement timeout）。 大型資料表的變更可能超過預設 60 秒逾時。請為變更指令設定 DATABASE_STATEMENT_TIMEOUT（單位毫秒），或設為 DISABLE_TIMEOUT。
  • 資料庫權限。 請用與初始化資料庫時相同權限的資料庫使用者執行變更。

部分變更包含非交易步驟。若錯誤訊息提及非交易步驟可能已執行，請在重試前檢查資料庫狀態。

升級後自訂連接器被略過​

Logto 會檢查每個連接器是否支援 Logto 內建的 @logto/connector-kit 版本。若不支援，Logto 會略過並記錄：

[load-connector] skip <connector-name> due to error: Connector requires @logto/connector-kit to be <range>, but the version here is <version>.

請將連接器升級以支援新版 @logto/connector-kit。設定 IGNORE_CONNECTOR_VERSION_CHECK=1 可略過檢查，但強烈不建議在正式環境使用。

這也可能發生在 共用連接器資料夾 的官方連接器：npm run cli connector add -- --official 會從 npm 下載最新版連接器，可能需要新版 Logto。此時請升級 Logto，或直接用 Docker 映像檔內建的官方連接器，不要用共用資料夾。

npm init @logto 會移除新目錄​

如果你在現有資料庫上執行 npm init @logto 且未加 --skip-seed，因資料庫已存在導致初始化失敗，CLI 會移除剛建立的目錄。你的資料庫不會被更動。請加上 --skip-seed 重新執行指令。