การอัปเดต

การติดตั้งแบบ managed ตั้งแต่ 1.0.0 ขึ้นไป ติดตั้งอัปเดตได้จากหน้าแอดมิน ส่วนการติดตั้งแบบ build จากซอร์สโค้ด และการติดตั้ง 0.x ทุกเครื่อง อัปเกรดบนเซิร์ฟเวอร์ด้วยสคริปต์ deploy ตัวเดียวกับที่ใช้ติดตั้ง

ที่เมนู “ระบบ” หน้าแอดมินจะแสดงเวอร์ชันของคุณไว้ข้าง “เวอร์ชันที่ติดตั้งอยู่:” และตรวจกับ repository ทางการบน GitHub ว่ามีรุ่น stable ที่ใหม่กว่าหรือยัง ในการติดตั้งแบบ build จากซอร์สโค้ด หน้านั้นจะขึ้นว่า “อัปเดตจากหน้าผู้ดูแลไม่ได้” และ “โหมดการอัปเดต:” เป็น “แจ้งเตือนอย่างเดียว” คือบอกได้ว่ามีเวอร์ชันใหม่ แต่ติดตั้งให้ไม่ได้

อัปเดตการติดตั้งแบบ managed

ติดตั้งด้วย 1.0.1 หรือ 1.0.2

ก่อนอัปเดตจากหน้าแอดมินครั้งแรก ให้รันแอปภายใต้ init ด้วยสิทธิ์ root ถ้าไม่ทำ การอัปเดตจะหยุดที่ “เตรียมเข้าสู่โหมดปิดปรับปรุง” และเว็บจะใช้ไม่ได้ ตามที่หน้าแก้ปัญหาอธิบายไว้ การอัปเดตผ่านเว็บเปลี่ยนเฉพาะ image ของแอป ไฟล์ Compose จึงยังเป็นแบบเดียวกับตอนติดตั้งเซิร์ฟเวอร์ เซิร์ฟเวอร์ที่ติดตั้งด้วย 1.0.3 ขึ้นไปมีค่านี้อยู่แล้ว

grep -q '^    init: true' /opt/tome-cms/compose.managed.yaml || sed -i '/^  app:$/a\    init: true' /opt/tome-cms/compose.managed.yaml
cd /opt/tome-cms && docker compose -p tomecms -f compose.managed.yaml \
  --env-file /etc/tome-cms/tome-cms.env \
  --env-file /var/lib/tome-cms/updater/image.env up -d --wait --no-deps --pull never app

ในการติดตั้งแบบ managed “โหมดการอัปเดต:” จะเป็น “จากหน้าผู้ดูแล” เมื่อมี release ใหม่ออกมา เมนู “ระบบ” จะขึ้นว่า “มี TomeCMS เวอร์ชัน 1.3.4 ให้อัปเดตแล้ว” โดยแสดงเวอร์ชันของ release นั้น

1. กด “อ่านบันทึกการเปลี่ยนแปลง” แล้วอ่านบันทึกของทุกเวอร์ชันที่ใหม่กว่าเวอร์ชันของคุณ
2. กด “ติดตั้งเวอร์ชัน 1.3.4” หน้าแอดมินจะถามว่า “ติดตั้ง TomeCMS เวอร์ชัน 1.3.4?” กด “ติดตั้งเวอร์ชัน 1.3.4” อีกครั้ง แล้วยืนยันด้วย passkey ของคุณ
3. เปิดหน้านี้ค้างไว้ “ความคืบหน้าการติดตั้ง” จะติ๊กทีละขั้น ได้แก่ “ตรวจสอบเงื่อนไขเบื้องต้น”, “ตรวจสอบความถูกต้องของตัวอัปเดตทางการ”, “ดาวน์โหลดตัวอัปเดต”, “เตรียมเข้าสู่โหมดปิดปรับปรุง”, “สร้างข้อมูลสำรองสำหรับกู้คืน”, “ปรับโครงสร้างฐานข้อมูล”, “เริ่มการทำงาน TomeCMS ใหม่” และ “ตรวจสอบความพร้อมของระบบ” เว็บจะใช้ไม่ได้ชั่วครู่ระหว่างที่ TomeCMS รีสตาร์ต
4. เมื่อเสร็จแล้ว เมนู “ระบบ” จะขึ้นว่า “ติดตั้ง TomeCMS เวอร์ชัน 1.3.4 เรียบร้อยแล้ว”

หลังจากนั้น การ์ด “การอัปเดตล่าสุด” จะบอกเวลาที่อัปเดตเสร็จ และถ้า updater เป็นเวอร์ชัน 1.3.0 ขึ้นไป จะบอกด้วยว่าเว็บปิดไปนานเท่าไร และสำรองอะไรไว้

สิ่งที่ตัวอัปเดตทำ และไม่ทำ

• ติดตั้งเฉพาะ release ทางการที่ตรวจกับ attestation ของ release นั้นผ่านแล้ว ซึ่งเป็นการตรวจแบบเดียวกับที่ตัวติดตั้งทำ
• ก่อนอัปเดตทุกครั้ง จะสำรองข้อมูลไว้ที่ /var/backups/tome-cms/ แล้วจึงรัน migration ถ้าการอัปเดตนั้นมี migration จะสำรองเต็มชุด คือ PostgreSQL และ bucket ถ้าไม่มี ซึ่งเป็นการอัปเดตส่วนใหญ่ updater เวอร์ชัน 1.3.0 ขึ้นไปจะสำรองแค่ PostgreSQL เพราะทั้งสองเวอร์ชันมี migration ชุดเดียวกัน ตารางจึงไม่เปลี่ยน และการคัดลอกคลังมีเดียคือส่วนที่ทำให้เว็บปิดนานที่สุด การไม่สำรองไฟล์ตั้งอยู่บนสมมติฐานว่าการอัปเดตที่ไม่มี migration จะไม่เขียนไฟล์ใหม่ จึงควรเก็บสำเนาของ bucket ไว้เองตามหน้าสำรองและกู้คืนข้อมูล แอปเวอร์ชันที่กำลังจะอัปเดตออกไปต้องเป็น 1.3.0 ขึ้นไปด้วย เพราะการสำรองรันอยู่ในแอปนั้น ตัวอัปเดตไม่ลบชุดสำรองเก่าเลย จึงต้องเผื่อพื้นที่ดิสก์ไว้ และคัดลอกชุดสำรองออกไปเก็บนอกเซิร์ฟเวอร์เอง
• ถ้าอัปเดตล้มเหลวหลังจากเริ่มรัน migration ไปแล้ว ตัวอัปเดตจะกลับไปใช้แอปตัวเดิมก็ต่อเมื่อ release ใหม่ระบุไว้ว่าเวอร์ชันเดิมใช้กับฐานข้อมูลใหม่ได้ แล้วหน้าแอดมินจะขึ้นว่า “ระบบย้อนกลับไปใช้เวอร์ชันเดิมแล้ว” ถ้าไม่ได้ระบุไว้ การอัปเดตจะหยุดรอให้ผู้ดูแลเซิร์ฟเวอร์จัดการ ตามที่หน้ากลับเข้าหน้าผู้ดูแล อธิบายไว้ ส่วนการกู้ฐานข้อมูลและไฟล์คืนจากชุดสำรองต้องทำเองทุกครั้ง
• ไม่มีการอัปเดตอัตโนมัติ และไม่มีช่องทางรุ่น beta ส่วน image ของ PostgreSQL และ SeaweedFS ต้องอัปเกรดด้วยมือ service ของตัวอัปเดตเองก็เช่นกัน ตามหัวข้อถัดไป

อัปเกรดตัวอัปเดต

ตัวอัปเดตรันอยู่บนเซิร์ฟเวอร์เอง และถูก build ครั้งเดียวตอนติดตั้งเซิร์ฟเวอร์ การอัปเดตจากเมนู “ระบบ” เปลี่ยนแค่ตัวแอป เซิร์ฟเวอร์จึงยังใช้ตัวอัปเดตรุ่นที่ติดตั้งมา ดูรุ่นได้จาก "updaterVersion" ในสถานะของตัวอัปเดต

sudo curl -s --unix-socket /run/tome-cms/updater.sock http://localhost/v1/status

ถ้า release ไหนต้องใช้ตัวอัปเดตที่ใหม่กว่า เมนู “ระบบ” จะบอกไว้ นอกจากนั้นควรอัปเกรดเมื่อบันทึกของ release บอกว่าตัวอัปเดตเปลี่ยน ตั้งแต่ 1.3.0 คำสั่งนี้จะเปลี่ยนตัวอัปเดตเป็นตัวที่อยู่ใน checkout ของ release โดยเว็บยังเปิดอยู่

cd /opt/tome-cms-src
git fetch --depth 1 origin tag v1.4.0
git checkout --detach v1.4.0
npm ci
sudo npm run updater:upgrade -- --dry-run
sudo npm run updater:upgrade

เซิร์ฟเวอร์ที่ติดตั้งก่อน 1.0.2 จะไม่มี /opt/tome-cms-src ให้ clone release มาไว้ที่นั่นแทนสามบรรทัดแรก

git clone --depth 1 --branch v1.4.0 https://github.com/Dhanabhon/tome-cms.git /opt/tome-cms-src
cd /opt/tome-cms-src

--dry-run จะตรวจและบอกว่าจะเปลี่ยนอะไรบ้าง โดยไม่แก้อะไร ตัวอัปเกรดจะ build ตัวอัปเดตจาก checkout หยุด service tomecms-updater เปลี่ยน /opt/tome-cms/updater, ไฟล์ unit ของ service และ /opt/tome-cms/compose.managed.yaml เป็นของ release นั้น แล้วเริ่ม service ใหม่และรอจนตอบด้วยรุ่นใหม่ เว็บเปิดอยู่ตลอด ส่วนการเปลี่ยนแปลงในไฟล์ compose จะมีผลในครั้งถัดไปที่แอปเริ่มทำงาน ตัวอัปเดต ไฟล์ unit และไฟล์ compose ตัวเดิมถูกเก็บไว้ข้าง ๆ โดยมี .previous- และเวลาในชื่อ ถ้าตัวอัปเดตใหม่ไม่ตอบภายใน 30 วินาที จะเอาตัวเดิมกลับมาให้เอง สิ่งที่คุณแก้ในไฟล์ compose เองจะไม่ถูกเก็บไว้ คำสั่งจะบอกเมื่อไฟล์นั้นไม่ใช่ของ release และสำเนาของคุณคือไฟล์ .previous- ตัวอัปเดตรุ่นเก่าอ่านบันทึกงานที่รุ่นใหม่เขียนไม่ได้ พอมีการอัปเดตผ่านตัวอัปเดตใหม่ไปแล้ว อย่าเอาตัวอัปเดต .previous- กลับมาใช้เอง

คำสั่งนี้ไม่ทำงานระหว่างที่มีการอัปเดตค้างอยู่ ไม่ทำงานจาก checkout ที่ไม่ใช่สำเนาสะอาดของ tag ของ release และไม่ย้อนกลับไปใช้ตัวอัปเดตที่เก่ากว่า รุ่นเดิมซ้ำได้ ซึ่งช่วยซ่อมตัวอัปเดตที่ไฟล์เสียหาย

การติดตั้ง 0.x เปลี่ยนเป็นแบบ managed บนเครื่องเดิมไม่ได้ การย้ายไป 1.0.0 ต้องใช้เซิร์ฟเวอร์เครื่องใหม่ ตามที่อธิบายไว้ในหน้าติดตั้งบน VPS

อัปเกรดการติดตั้งแบบ build จากซอร์สโค้ด

1. หยุดแอป แล้วสำรอง PostgreSQL และ bucket ของมีเดียไว้พร้อมกัน และตรวจชุดสำรองตามหน้าสำรองและกู้คืนข้อมูล จากนั้นปล่อยแอปหยุดไว้อย่างนั้น เพื่อไม่ให้มีข้อมูลใหม่ที่ชุดสำรองไม่มี

2. อ่าน release notes ของทุกเวอร์ชันที่ใหม่กว่าเวอร์ชันของคุณ ไฟล์อยู่ใน docs/releases/ ของ repository เวอร์ชันละหนึ่งไฟล์ และแต่ละไฟล์บอกว่าการอัปเกรดเวอร์ชันนั้นต้องทำอะไรบ้าง

3. ในโฟลเดอร์โค้ด ดึงโค้ดใหม่แล้วรันสคริปต์

   git pull
   ./scripts/deploy-vps.sh

4. ตรวจว่าแอปพร้อมแล้ว แบบเดียวกับตอนติดตั้งครั้งแรก

   curl -s http://127.0.0.1:4321/health/ready

สคริปต์ใช้ .env.local เดิมโดยไม่แก้อะไร จากนั้น build image ใหม่ของแอป รัน migration ที่ค้างอยู่ในคอนเทนเนอร์ที่ใช้ครั้งเดียวแล้วทิ้ง แล้วจึงเปิดคอนเทนเนอร์แอปตัวใหม่ เว็บจะใช้ไม่ได้ตั้งแต่ตอนที่คุณหยุดแอปไปจนถึงตอนที่คอนเทนเนอร์ตัวใหม่พร้อม

เว็บที่ติดตั้งจาก 0.2.0 ยังไม่มีค่าบางตัวที่สคริปต์รุ่นใหม่เขียน สคริปต์จึงหยุดพร้อมข้อความ Existing .env.local needs updates; rerun with --force to merge values while preserving secrets. ให้รัน ./scripts/deploy-vps.sh --force สคริปต์จะเพิ่มค่าที่ขาดและคงค่าลับเดิมไว้

ปรับฐานข้อมูลด้วย migration

เวอร์ชันใหม่อาจเปลี่ยนโครงสร้างตารางในฐานข้อมูล การเปลี่ยนแต่ละครั้งเรียกว่า migration และคำสั่งนี้จะรันทุกตัวที่ฐานข้อมูลยังไม่มี

npm run db:migrate

ทั้งตัวอัปเดตและสคริปต์ deploy รันคำสั่งนี้ให้ในคอนเทนเนอร์แอปที่ใช้ครั้งเดียวแล้วทิ้ง คุณจึงไม่ต้องรันเอง ถ้าจะรันเองในโฟลเดอร์โค้ด ให้รัน npm ci ในโฟลเดอร์นั้นหนึ่งครั้งก่อน คำสั่งนี้อ่านข้อมูลการเชื่อมต่อจาก .env.local

คำสั่งจะพิมพ์ <name>: Success หนึ่งบรรทัดต่อ migration ที่รันสำเร็จ หรือพิมพ์ Up to date ถ้าไม่มีตัวไหนค้างอยู่ migration ที่ค้างอยู่ทั้งหมดรันใน transaction เดียวของ PostgreSQL ถ้ามีตัวใดล้มเหลว คำสั่งจะพิมพ์ Migration failed และจะไม่มี migration ตัวไหนมีผลเลย ฐานข้อมูลจะอยู่ในสภาพเดิม

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

จำนวน migration ที่ค้างอยู่

ดูว่าเว็บของคุณติดตั้งจากเวอร์ชันไหน หรืออัปเกรดครั้งล่าสุดเป็นเวอร์ชันไหน แล้วนับจากเวอร์ชันนั้น

ติดตั้งจากเวอร์ชัน	ค้างอยู่	ตัวไหนบ้าง
1.4.0, 1.3.3, 1.3.2, 1.3.1, 1.3.0, 1.2.1, 1.2.0, 1.1.2, 1.1.1, 1.1.0, 1.0.4, 1.0.3, 1.0.2, 1.0.1, 1.0.0, 0.14.1, 0.14.0, 0.13.0 หรือ 0.12.1	0	ไม่มี
0.12.0 หรือ 0.11.0	1	026_planned_dates
0.10.0	3	ตัวข้างบน 024_site_maintenance และ 025_content_stats
0.9.0 หรือ 0.8.0	4	สามตัวข้างบน และ 023_home_slides
0.7.0 หรือ 0.6.0	6	สี่ตัวข้างบน 021_media_documents และ 022_navigation_new_tab
0.5.0 หรือ 0.4.0	7	หกตัวข้างบน และ 020_site_brand
0.3.0	10	เจ็ดตัวข้างบน 017_scheduled_publishing, 018_thai_slugs และ 019_content_redirects
0.2.0	19	สิบตัวข้างบน และ 008_update_rate_limit_actions ไปจนถึง 016_theme_settings

ตัวเลขเหล่านี้นับตาม release notes ของแต่ละเวอร์ชัน ถ้าติดตั้งจากโค้ดที่อยู่ระหว่างสองรุ่น หรือจากโค้ดก่อน 0.2.0 จำนวนที่ค้างอาจไม่ตรงกับตาราง ประกาศในหน้าแอดมินจะบอกชื่อที่ค้างอยู่จริง

ประกาศในหน้าแอดมิน

เมื่อโค้ดต้องการ migration ที่ฐานข้อมูลยังไม่มี ทุกหน้าของแอดมินจะขึ้นประกาศ “ฐานข้อมูลยังไม่ได้อัปเดต” ไว้ด้านบน เตือนก่อนว่าการบันทึกจะไม่สำเร็จจนกว่าจะรันคำสั่ง npm run db:migrate บนเซิร์ฟเวอร์ แล้วตามด้วย “รายการที่รออยู่:” และชื่อ migration ที่ค้าง หน้าแอดมินถามฐานข้อมูลใหม่ทุกครั้งที่เปิดหน้า เมื่อรัน migration เสร็จแล้ว ประกาศจึงหายไปตั้งแต่หน้าถัดไปที่คุณเปิด

ระหว่างนั้น /health/ready จะรายงาน "migrations":"pending" และ "status":"not-ready"