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

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

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

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

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

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

พบการเปลี่ยนแปลงฐานข้อมูลที่ยังไม่ได้ deploy คุณต้อง deploy ก่อนด้วยคำสั่ง npm run alteration deploy
...
Error: Undeployed database alterations found.

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

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

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

ข้อมูล:

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

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

ก่อนอัปเกรด

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

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

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

Docker

1. ดึง image ใหม่:

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

2. Deploy alterations ด้วย 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 ประมาณนี้ จำนวนและชื่อของ alterations ขึ้นอยู่กับเวอร์ชันที่คุณอัปเกรดข้าม:

   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. Deploy alterations ใน 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 ฐานข้อมูลใหม่และ deploy alterations ทุกครั้งที่เริ่มต้นได้:

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

คำเตือน:

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

Kubernetes

Deploy alterations หนึ่งครั้งด้วย Job แล้วจึง roll out image ใหม่

1. สร้าง Job เพื่อรัน alterations ด้วย 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

คำเตือน:

Deploy alterations จากที่เดียวเท่านั้น CLI จะไม่ล็อกฐานข้อมูลขณะ deploy alterations ดังนั้นอย่า 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. Deploy alterations จากไดเรกทอรีใหม่ 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 เป็นเวอร์ชันเป้าหมาย ก่อนที่เวอร์ชันใหม่จะเริ่มต้น ให้ deploy alterations ด้วย image ใหม่โดยใช้ one-off command หรือ shell feature ของผู้ให้บริการ โดยรัน npm run alteration deploy 1.45.0 สำหรับอินสแตนซ์เดียว คุณสามารถใช้ start command จาก Docker Compose tip ได้เช่นกัน เทมเพลตเหล่านี้ดูแลโดยผู้ให้บริการ กรุณาตรวจสอบเอกสารของผู้ให้บริการสำหรับรายละเอียด

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

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

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

• ย้อนกลับ alterations รัน 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 alterations อีกครั้ง ดู Rollback alterations สำหรับรายละเอียด

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

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

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

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

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

Logto ไม่สามารถเริ่มหลัง restart

หากคุณใช้ tag latest การ restart หรือ pull image ใหม่อาจอัปเกรด Logto โดยยังไม่ได้ deploy alterations ให้ deploy alterations ด้วย 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 ดังนั้นหากล้มเหลวจะไม่ทิ้งการเปลี่ยนแปลงบางส่วนไว้ ให้แก้ไขสาเหตุแล้วรันคำสั่งเดิมอีกครั้ง Alterations ที่ deploy ไปแล้วจะถูกข้าม สาเหตุที่พบบ่อย:

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

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

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