ข้ามไปยังเนื้อหาหลัก

การอัปเกรดเวอร์ชัน OSS ของคุณ

Logto ปฏิบัติตาม semver. คุณสามารถดูการปล่อยแต่ละเวอร์ชันและการเปลี่ยนแปลงได้ที่ GitHub Releases. คู่มือนี้อธิบายวิธีการอัปเกรด วิธีอัปเกรดสำหรับแต่ละประเภทการปรับใช้ที่พบบ่อย และวิธีแก้ไขปัญหาที่อาจพบ

วิธีการอัปเกรดทำงานอย่างไร​

การอัปเกรดประกอบด้วยสองส่วน:

  1. โค้ดของ Logto: คือ Docker image หรือ release tarball ที่คุณรัน
  2. สคีมาฐานข้อมูล: การเปลี่ยนแปลงสคีมาระหว่างเวอร์ชันจะถูกจัดส่งเป็นการเปลี่ยนแปลงฐานข้อมูล และคุณต้องปรับใช้ด้วย Logto CLI. ฐานข้อมูลของคุณจะบันทึกว่ามีการปรับใช้อะไรไปแล้วบ้าง

เมื่อ Logto เริ่มทำงาน มันจะตรวจสอบฐานข้อมูล หากมีการเปลี่ยนแปลงที่รวมอยู่ในเวอร์ชันนี้ของ Logto แต่ยังไม่ได้ปรับใช้ Logto จะปฏิเสธที่จะเริ่มทำงาน:

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

การเปลี่ยนแปลง (alterations) ถูกออกแบบให้เข้ากันได้กับเวอร์ชันก่อนหน้าของ Logto ดังนั้นอินสแตนซ์ที่ยังรันเวอร์ชันเก่าจะยังคงทำงานได้หลังจากปรับใช้ alteration แล้ว ลำดับที่แนะนำเพื่อหลีกเลี่ยง downtime คือ:

  1. ปรับใช้ alteration โดยใช้ Logto เวอร์ชันใหม่
  2. แทนที่อินสแตนซ์ที่กำลังรันด้วยเวอร์ชันใหม่

แนะนำให้สำรองฐานข้อมูลก่อนเริ่มกระบวนการ

ข้อมูล:

ควรปรับใช้ alteration ด้วย CLI ที่มาพร้อมกับเวอร์ชันที่คุณกำลังจะอัปเกรดไป เช่น Docker image ใหม่ หรือ release tarball ใหม่ สคริปต์ alteration จะถูกรวมมากับ CLI ดังนั้น CLI เก่าไม่สามารถปรับใช้ alteration ของ Logto เวอร์ชันใหม่ได้

คุณสามารถอัปเกรดข้ามหลายเวอร์ชันได้ในครั้งเดียว การปรับใช้ alteration ไปยังเวอร์ชันเป้าหมายจะปรับใช้ alteration ทั้งหมดที่อยู่ระหว่างทางตามลำดับ

ก่อนอัปเกรด​

  • อ่าน release notes ของทุกเวอร์ชันระหว่างเวอร์ชันปัจจุบันกับเวอร์ชันเป้าหมาย
  • สำรองฐานข้อมูลของคุณ (แนะนำ) เช่น ด้วย pg_dump หรือ snapshot จากผู้ให้บริการฐานข้อมูลของคุณ แม้ alteration จะสามารถย้อนกลับได้ แต่การสำรองข้อมูลเป็นวิธีที่เชื่อถือได้ที่สุด
  • ระบุเวอร์ชันเป้าหมายให้ชัดเจน ใช้เวอร์ชันที่ระบุแน่นอน เช่น ghcr.io/logto-io/logto:1.45.0 แทนที่จะใช้ latest เพราะหากใช้ latest การรีสตาร์ทหรือ pull ใหม่อาจอัปเกรด Logto ก่อนที่ alteration จะถูกปรับใช้ และ Logto จะไม่เริ่มทำงาน
  • ตรวจสอบข้อกำหนด Node.js หากคุณรัน Logto ด้วย Node.js โดยตรง แต่ละ release จะระบุไว้ในฟิลด์ engines ของ package.json ปัจจุบันต้องใช้ Node.js ^26.0.0
  • ตรวจสอบ custom connectors ของคุณ หากมี ดู Custom connectors are skipped after upgrading
  • อัปเกรด staging ก่อน หากคุณมี staging environment ที่ใช้ฐานข้อมูลแยก หาก staging ใช้ฐานข้อมูลร่วมกับ production การปรับใช้ alteration จาก staging จะเปลี่ยนฐานข้อมูล production ด้วย อินสแตนซ์ production ที่ยังใช้เวอร์ชันเก่าจะยังทำงานได้ เพราะ alteration เข้ากันได้กับเวอร์ชันก่อนหน้า

ขั้นตอนการอัปเกรด​

ในตัวอย่างด้านล่าง 1.45.0 คือเวอร์ชันเป้าหมาย กรุณาแทนที่และ URL ฐานข้อมูลด้วยค่าของคุณเอง

Docker​

  1. ดึง image ใหม่:

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

  2. ปรับใช้ alteration ด้วย image ใหม่ ขณะที่ container Logto ปัจจุบันยังคงทำงาน:

    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

    คุณควรเห็น output ประมาณนี้ จำนวนและชื่อ alteration ขึ้นอยู่กับเวอร์ชันที่คุณอัปเกรดข้าม:

    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 ของ image คือ npm run ดังนั้น argument หลังชื่อ image จะถูกส่งต่อไปยัง npm run ให้เขียน alteration deploy 1.45.0 ไม่ใช่ npm run alteration deploy 1.45.0

  3. แทนที่ container ที่กำลังรันด้วย image ใหม่ โดยใช้พอร์ต, environment variables และ options เดิม:

    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. อัปเดต image tag ของ Logto service ในไฟล์ Compose แล้วดึง image:

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

  2. ปรับใช้ alteration ใน one-off container ของ image ใหม่:

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

    แทนที่ logto ด้วยชื่อ service ในไฟล์ Compose ของคุณ (ใน demo docker-compose.yml ใช้ชื่อ app) การ override entrypoint ทำให้คำสั่งนี้ทำงานได้แม้ service จะกำหนด entrypoint เอง

  3. สร้าง Logto container ใหม่ด้วย image ใหม่:

    docker compose up -d logto
เคล็ดลับ:

หากคุณรัน Logto เพียงอินสแตนซ์เดียว คุณสามารถตั้งค่าให้ container seed ฐานข้อมูลใหม่และปรับใช้ alteration ทุกครั้งที่เริ่มต้นได้:

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 หมายถึงเวอร์ชันล่าสุดที่รวมอยู่ใน image ดังนั้น alteration จะตรงกับ image เสมอ ห้ามใช้วิธีนี้กับหลายอินสแตนซ์ ดู Kubernetes สำหรับเหตุผล

คำเตือน:

หากคุณใช้ setup จาก demo docker-compose.yml container Postgres จะเก็บข้อมูลใน anonymous volume ซึ่งจะไม่ถูก mount อีกหลังจาก docker compose down ดังนั้น docker compose up ครั้งถัดไปจะเริ่มด้วยฐานข้อมูลว่าง ก่อนรัน docker compose down ให้ย้ายข้อมูลไปยัง named volume หรือฐานข้อมูลภายนอก

Kubernetes​

ปรับใช้ alteration หนึ่งครั้งด้วย Job จากนั้น rollout image ใหม่

  1. สร้าง Job ที่รัน alteration ด้วย image ใหม่:

    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

    Apply และรอให้เสร็จสิ้น:

    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. อัปเดต image ของ Logto Deployment และรอ rollout หาก Deployment ของคุณมี init container ที่ใช้ Logto image เช่นตัวอย่าง shared connectors folder ให้อัปเดตด้วย:

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

หากคุณ deploy ด้วย Helm หรือ GitOps tool ให้รัน Job ก่อนอัปเดต Deployment เช่นเป็น Helm pre-upgrade hook หรือ Argo CD PreSync hook

คำเตือน:

ปรับใช้ alteration จากที่เดียวเท่านั้น CLI จะไม่ล็อกฐานข้อมูลขณะ deploy alteration ดังนั้นอย่า deploy จาก startup command ของ replica ทุกตัว

Node.js​

หากคุณติดตั้ง Logto ด้วย npm init @logto หรือจาก release tarball ให้ติดตั้งเวอร์ชันใหม่ไว้ข้างๆ เวอร์ชันปัจจุบัน เก็บไดเรกทอรีเดิมไว้จนกว่าจะอัปเกรดเสร็จ เพื่อให้สามารถย้อนกลับได้อย่างรวดเร็ว

  1. ตรวจสอบว่า Node.js ของคุณตรงตามข้อกำหนดของเวอร์ชันใหม่

  2. ดาวน์โหลดและแตกไฟล์ release ใหม่:

    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

    หากต้องการ release ล่าสุด สามารถรัน npm init @logto@latest -- --path ./logto-new --skip-seed ได้ ตัวเลือก --skip-seed จำเป็นเพราะฐานข้อมูลของคุณมีอยู่แล้ว

  3. คัดลอกไฟล์ config จากการติดตั้งปัจจุบัน (~/logto โดยค่าเริ่มต้น):

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

  4. ตัวเชื่อมต่อ (connectors) อย่างเป็นทางการถูกรวมอยู่ใน release แล้ว หากคุณเพิ่ม connectors อื่น ให้เพิ่มเข้าไปในไดเรกทอรีใหม่อีกครั้ง เช่น:

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

  5. ปรับใช้ alteration จากไดเรกทอรีใหม่ CLI จะอ่าน DB_URL จากไฟล์ .env:

    npm run alteration deploy 1.45.0

  6. หยุด Logto process ปัจจุบัน แล้วเริ่มใหม่จากไดเรกทอรีใหม่:

    npm start

    หากใช้ process manager เช่น systemd หรือ pm2 ให้เปลี่ยน working directory ไปยังไดเรกทอรีใหม่

ผู้ให้บริการโฮสติ้ง​

หากคุณ deploy Logto ด้วย one-click template จากผู้ให้บริการโฮสติ้ง ให้เปลี่ยน image tag ของ Logto เป็นเวอร์ชันเป้าหมาย ก่อนที่เวอร์ชันใหม่จะเริ่มต้น ให้ปรับใช้ alteration ด้วย image ใหม่โดยใช้ one-off command หรือ shell feature ของผู้ให้บริการ โดยรัน npm run alteration deploy 1.45.0 สำหรับอินสแตนซ์เดียว คุณสามารถใช้ start command จาก Docker Compose tip ได้เช่นกัน เทมเพลตเหล่านี้ดูแลโดยผู้ให้บริการ กรุณาตรวจสอบเอกสารของผู้ให้บริการสำหรับรายละเอียด

การย้อนกลับ (Roll back)​

หากเวอร์ชันใหม่ทำงานไม่เป็นไปตามที่คาดหวัง:

  • สลับกลับไปใช้เวอร์ชันก่อนหน้า เนื่องจาก alteration เข้ากันได้กับ Logto เวอร์ชันก่อนหน้า คุณจึงสามารถรันเวอร์ชันก่อนหน้าได้โดยไม่ต้องแตะฐานข้อมูล วิธีนี้ใช้ได้กับเวอร์ชันที่อยู่ก่อนเวอร์ชันเป้าหมายเท่านั้น หากคุณอัปเกรดข้ามหลายเวอร์ชัน ให้ย้อนกลับ alteration ด้วย

  • ย้อนกลับ alteration รัน rollback ด้วย เวอร์ชันใหม่ เพราะเวอร์ชันเก่าไม่มีสคริปต์ alteration ใหม่ จากนั้นเริ่มเวอร์ชันก่อนหน้า ตัวอย่างเช่นกับ 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

    หลัง rollback เวอร์ชันใหม่จะไม่เริ่มจนกว่าคุณจะ deploy alteration อีกครั้ง ดู Rollback alterations สำหรับรายละเอียด

  • กู้คืนข้อมูลสำรอง หากคุณได้สำรองไว้ วิธีนี้เชื่อถือได้ที่สุด แต่ข้อมูลที่เขียนหลังจากสำรองจะสูญหาย

การแก้ไขปัญหา​

Logto ไม่เริ่มหลังอัปเกรด​

หาก log แสดง Undeployed database alterations found ให้ปรับใช้ alteration ตามที่อธิบายไว้ใน Upgrade steps

หากคุณได้ปรับใช้ alteration แล้วแต่ยังเห็น error นี้ อาจเป็นเพราะ deploy ด้วย CLI เก่า เช่น logto ที่ติดตั้งแบบ global หรือ npx @logto/cli ที่เป็นเวอร์ชันเก่า ในกรณีนี้ CLI จะรายงานว่า Found 0 alteration to deploy เพราะไม่รู้จัก alteration ใหม่ ให้ deploy อีกครั้งด้วย CLI ของเวอร์ชันใหม่: Docker image ใหม่, ไดเรกทอรี release ใหม่ หรือ npx @logto/cli@1.45.0 db alteration deploy 1.45.0

Logto ไม่สามารถเริ่มหลังรีสตาร์ท​

หากคุณใช้ tag latest การรีสตาร์ทหรือ pull image ใหม่อาจอัปเกรด Logto โดยที่ยังไม่ได้ deploy alteration ให้ deploy alteration ด้วย image ที่คุณกำลังรัน แล้วระบุเวอร์ชันให้แน่นอนเพื่อป้องกันการอัปเกรดโดยไม่ตั้งใจ

Error: Missing target version​

หากไม่มี terminal แบบ interactive CLI จะไม่สามารถถามเวอร์ชันเป้าหมายได้ ให้ระบุเวอร์ชันเป้าหมายโดยตรง เช่น alteration deploy 1.45.0 หรือใช้ alteration deploy latest เพื่อ deploy จนถึงเวอร์ชันล่าสุดที่รวมใน CLI

npm error Missing script: "npm"​

คุณใส่ npm run alteration ... หลังชื่อ image ใน docker run แต่ entrypoint ของ image คือ npm run อยู่แล้ว ให้ใส่ alteration deploy 1.45.0 แทน

alteration ล้มเหลว​

แต่ละ alteration จะรันใน transaction ดังนั้นหากล้มเหลวจะไม่ทิ้งการเปลี่ยนแปลงบางส่วนไว้ ให้แก้ไขสาเหตุแล้วรันคำสั่งเดิมอีกครั้ง alteration ที่ deploy ไปแล้วจะถูกข้าม สาเหตุที่พบบ่อย:

  • Statement timeout alteration บนตารางขนาดใหญ่อาจใช้เวลานานกว่าค่า timeout เริ่มต้น 60 วินาที ให้ตั้งค่า DATABASE_STATEMENT_TIMEOUT (เป็นมิลลิวินาที) หรือใช้ DISABLE_TIMEOUT สำหรับคำสั่ง alteration
  • สิทธิ์ฐานข้อมูล ให้รัน alteration ด้วยผู้ใช้ฐานข้อมูลที่มีสิทธิ์เท่ากับตอน seed ฐานข้อมูล

alteration บางรายการมีขั้นตอนที่รันนอก transaction หาก error แจ้งว่ามีขั้นตอนนอก transaction อาจถูกนำไปใช้แล้ว ให้ตรวจสอบสถานะฐานข้อมูลก่อนรันคำสั่งอีกครั้ง

custom connectors ถูกข้ามหลังอัปเกรด​

Logto จะตรวจสอบว่าแต่ละ connector รองรับเวอร์ชันของ @logto/connector-kit ที่มาพร้อม Logto หรือไม่ หากไม่รองรับ Logto จะข้ามและ log ข้อความ:

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

ให้อัปเดต connector ให้รองรับ @logto/connector-kit เวอร์ชันใหม่ การตั้งค่า IGNORE_CONNECTOR_VERSION_CHECK=1 จะข้ามการตรวจสอบนี้ แต่ไม่แนะนำอย่างยิ่งใน production

กรณีนี้อาจเกิดกับ official connectors ใน shared connectors folder ด้วย: npm run cli connector add -- --official จะดาวน์โหลด connectors ล่าสุดจาก npm ซึ่งอาจต้องใช้ Logto เวอร์ชันใหม่ ในกรณีนี้ให้อัปเกรด Logto หรือใช้ official connectors ที่รวมใน Docker image แทน shared folder

npm init @logto ลบไดเรกทอรีใหม่​

หากคุณรัน npm init @logto กับฐานข้อมูลที่มีอยู่โดยไม่ใช้ --skip-seed การ seed จะล้มเหลวเพราะฐานข้อมูลมีอยู่แล้ว และ CLI จะลบไดเรกทอรีที่เพิ่งสร้าง ฐานข้อมูลของคุณจะไม่ถูกเปลี่ยนแปลง ให้รันคำสั่งอีกครั้งพร้อม --skip-seed