วิธีย้ายจาก Gitea ไปยัง Forgejo โดยไม่ทำให้ repository ของคุณเสียหาย

คุณหยุด Gitea ติดตั้ง Forgejo คัดลอก app.ini และ data directory ของคุณ แล้วเริ่มบริการตามที่คู่มือการย้ายข้อมูลทุกฉบับอธิบายไว้ web UI ขึ้นมาทำงาน จากนั้นการย้ายฐานข้อมูลก็ล้มเหลว หรือแย่กว่านั้น Forgejo ปฏิเสธที่จะเริ่มทำงานเพราะเวอร์ชัน schema ของคุณใหม่เกินกว่าที่มันจะเข้าใจได้ คุณกำลังใช้ Gitea 1.23 หรือใหม่กว่า และการอัปเกรดในที่เดิมแบบง่าย ๆ ที่ทุกคนอธิบายไว้ ไม่สามารถใช้กับคุณได้อีกต่อไป

Forgejo กลายเป็น hard fork ของ Gitea ในช่วงต้นปี 2024 และตั้งแต่นั้นมาทั้งสองโปรเจกต์ก็แยกออกจากกันในระดับ schema ของฐานข้อมูล วิธีที่คุณย้าย Gitea ไปยัง Forgejo ในตอนนี้ขึ้นอยู่กับเวอร์ชัน Gitea ของคุณทั้งหมด คู่มือนี้ให้เส้นทางที่แน่นอนสำหรับเวอร์ชันของคุณ คำสั่งฉบับเต็มสำหรับทั้งการติดตั้งแบบ native และ Docker วิธีแก้ปัญหาสำหรับ Gitea 1.23+ และเช็คลิสต์การตรวจสอบ เพื่อให้คุณย้ายข้อมูลได้โดยไม่สูญเสีย repository ปัญหา หรือผู้ใช้

TL;DR (สรุปย่อ)

• หน้าผาของเวอร์ชันนี้มีอยู่จริง Forgejo v10.0 เป็นรีลีสสุดท้ายที่รองรับการอัปเกรดโดยตรงแบบโปร่งใสจาก Gitea Gitea v1.22 เป็นเวอร์ชันสูงสุดที่สามารถใช้เส้นทางตรงที่รองรับได้
• บน Gitea v1.22 หรือเก่ากว่า: ย้ายไปยัง Forgejo v10.0.x ก่อน จากนั้นอัปเกรด Forgejo v10 ไปยังรุ่นปัจจุบัน (v15) สองขั้นตอน ทั้งคู่ได้รับการรองรับ
• บน Gitea v1.23 หรือใหม่กว่า: ไม่มีเส้นทางตรงที่รองรับอย่างเป็นทางการ คุณต้องเลือกระหว่างการลดระดับ SQL/schema, สคริปต์ย้ายข้อมูลจากชุมชน, การย้ายข้อมูลผ่าน repo/API หรือการจัดเตรียมเซิร์ฟเวอร์ใหม่โดยใช้หนึ่งในวิธีเหล่านั้น แต่ละวิธีมีข้อแลกเปลี่ยนด้านการสูญเสียข้อมูลที่แตกต่างกัน
• สำรองไดเรกทอรีข้อมูลและฐานข้อมูลของคุณก่อนที่จะแตะต้องสิ่งใด ทุกเส้นทางด้านล่างนี้ตั้งอยู่บนสมมติฐานว่าคุณมีข้อมูลสำรองที่กู้คืนได้ ส่วนเส้นทางที่ไม่ได้รับการรองรับนั้นสำคัญยิ่งกว่าเป็นสองเท่า
• มีบางสิ่งที่ต้องได้รับความสนใจหลังการย้ายข้อมูลเสมอ วางแผนที่จะสร้างใหม่หรือตรวจสอบ Personal Access Tokens ลงทะเบียน Actions runner ใหม่ และลบแล้วสร้างดัชนีค้นหา Bleve ขึ้นใหม่ ควรวางแผนสิ่งเหล่านี้ไม่ว่าจะเลือกเส้นทางใดก็ตาม
• การย้ายข้อมูลไม่ใช่ข้อบังคับ Gitea ได้รับการดูแลอย่างต่อเนื่อง การตัดสินใจ "อยู่กับ Gitea ต่อ" ยังคงสมเหตุสมผล หากความเสี่ยงจากการย้ายข้อมูลมีน้ำหนักมากกว่าประโยชน์สำหรับสถานการณ์ของคุณ

อยู่นอกขอบเขตของบทความนี้ ได้แก่ การย้ายจาก Gogs, GitHub หรือ GitLab ไปยัง Forgejo และการตั้งค่า Forgejo Actions ตั้งแต่ต้น

สิ่งที่ต้องมีก่อนเริ่ม / สิ่งที่คุณต้องใช้

ก่อนที่คุณจะรันคำสั่งใดๆ ให้ยืนยันว่าคุณมีข้อมูลสำรองแบบเต็มที่กู้คืนได้ของสองสิ่ง คือไดเรกทอรีข้อมูล Gitea ของคุณ (/var/lib/gitea บนการติดตั้งแบบ native เริ่มต้น) และฐานข้อมูลของคุณ หากฐานข้อมูลของคุณเป็น SQLite ไฟล์นั้นอยู่ในไดเรกทอรีข้อมูล หากเป็น PostgreSQL หรือ MySQL ให้ดัมป์แยกต่างหากด้วย pg_dump หรือ mysqldump การย้ายข้อมูลโดยไม่มีการสำรองที่ตรวจสอบแล้วไม่ใช่การย้ายข้อมูล แต่เป็นการพนัน

คุณจะต้องมีสิ่งเหล่านี้ด้วย:

• เวอร์ชัน Gitea ปัจจุบันของคุณ รัน gitea --version (หรือ docker exec <container> gitea --version) ตัวเลขนี้เป็นตัวกำหนดเส้นทางทั้งหมดของคุณ
• ประเภทฐานข้อมูลของคุณ: SQLite, PostgreSQL หรือ MySQL วิธีแก้ปัญหาบางแบบใช้ได้เฉพาะกับฐานข้อมูลบางประเภทเท่านั้น
• สิทธิ์ root หรือ sudo บนเซิร์ฟเวอร์
• ควรตระหนักว่าเส้นทางที่รองรับนั้นติดตั้ง Forgejo v10.0 เป็นจุดกลางทาง Forgejo v10.0 อยู่ในสถานะ EOL ตั้งแต่วันที่ April 16, 2025 คุณติดตั้งมันเพียงเพื่อใช้ระหว่างการย้ายข้อมูลเท่านั้น แล้วอัปเกรดออกจากมันทันที

เหตุใดเส้นทางอัปเกรดโดยตรงจึงใช้ไม่ได้อีกต่อไป

ในเดือน December 2024 โปรเจกต์ Forgejo ได้เผยแพร่ คำแถลงเรื่องความเข้ากันได้ ที่ขีดเส้นแบ่งไว้ชัดเจนว่า "Forgejo เวอร์ชันในอนาคตจะไม่รองรับการอัปเกรดจาก Gitea instance ที่รันเวอร์ชัน v1.23 ขึ้นไป" ประโยคนั้นคือปัญหาทั้งหมดในบรรทัดเดียว

เมื่อ Forgejo แยกตัว (fork) จาก Gitea ในช่วงต้นปี 2024 โค้ดเบสทั้งสองก็แยกออกจากกันมากขึ้นเรื่อย ๆ และ database schema ก็ค่อย ๆ เบี่ยงเบนออกจากกัน Forgejo คงช่วงเวลาความเข้ากันได้ไว้เพื่อให้ผู้ดูแลระบบ Gitea เดิมสามารถย้ายมาได้ แต่ช่วงเวลานั้นก็มีจุดสิ้นสุด Forgejo v10.0 ซึ่งเปิดตัวเมื่อวันที่ 16 มกราคม 2025 คือ "the last version to allow a transparent upgrade from Gitea v1.22 or lower." ทุกเวอร์ชันที่ใหม่กว่า v10.0 จะไม่สามารถอ่านฐานข้อมูล Gitea ได้โดยตรง

จังหวะเวลาคือสิ่งที่ทำให้หลายคนพลาด Gitea v1.23 เปิดตัวในช่วงปลายปี 2024 และ รุ่น Gitea ปัจจุบัน ณ เดือนมิถุนายน 2026 คือ v1.26.4 หากคุณอัปเดต Gitea instance ของคุณให้ทันสมัยพอสมควรอยู่แล้ว แสดงว่าคุณผ่านจุดหักเหมาแล้ว และคู่มือมาตรฐานทั่วไปจะไม่ตรงกับสถานการณ์ของคุณอีกต่อไป

สรุปประเด็นสำคัญ: เส้นทางอัปเกรดโดยตรงที่รองรับอย่างเป็นทางการรองรับสูงสุดถึง Gitea v1.22 เท่านั้น เวอร์ชันที่ใหม่กว่านั้นต้องมีขั้นตอนเพิ่มเติม

หาเส้นทางการย้ายข้อมูลของคุณตามเวอร์ชัน Gitea

รัน gitea --version, หาแถวของคุณ แล้วทำตามเส้นทางในคอลัมน์ที่สาม ส่วนที่เหลือในคู่มือนี้คือรายละเอียดเบื้องหลังแถวเหล่านี้

คำแถลงเรื่องความเข้ากันได้ของเวอร์ชันมาจาก ประกาศความเข้ากันได้อย่างเป็นทางการของ Forgejo: Gitea จนถึง v1.21 สามารถย้ายไปยัง Forgejo v7.0 ถึง v10.0 ได้ และ Gitea v1.22 สามารถย้ายไปยัง Forgejo v8.0 ถึง v10.0 ได้ ทั้งสองกรณีสูงสุดอยู่ที่ v10.0 ซึ่งเป็นเป้าหมายตรงที่รองรับเป็นตัวสุดท้าย

ภายใต้คำถามเรื่องเวอร์ชันนั้น มีกลยุทธ์การย้ายข้อมูลสามแบบซ่อนอยู่ และการทำความเข้าใจก่อนจะช่วยได้มากก่อนที่จะเข้าสู่ขั้นตอนแบบทีละขั้น

• ในที่เดิม เซิร์ฟเวอร์เดียวกัน สลับไบนารีหรือ container image บนเครื่องเดิม ใช้ความพยายามน้อยที่สุดหากเวอร์ชันของคุณรองรับ แต่ต้องผ่านขั้นตอนกลางที่ v10.0
• การเตรียมการบนเซิร์ฟเวอร์ใหม่ จัดเตรียมเซิร์ฟเวอร์ใหม่และใช้เป็นเป้าหมายที่ปลอดภัยสำหรับวิธีการย้ายข้อมูลที่ตรงกับเวอร์ชัน Gitea ของคุณ วิธีนี้ช่วยปกป้องเครื่อง Gitea เดิมและทำให้การย้อนกลับทำได้ง่ายขึ้น แต่ไม่ได้ช่วยข้ามปัญหา database schema ของ Gitea 1.23 ขึ้นไป
• การย้ายข้อมูลผ่าน Repo/API ใช้เครื่องมือย้ายข้อมูลของ Forgejo เพื่อดึง repository จาก Gitea instance เดิม ประวัติ git คือส่วนที่เชื่อถือได้ ส่วนเมทาดาต้า เช่น issue, PR, label, release, ข้อมูล wiki และความคิดเห็น ควรถือว่าเป็นการพยายามเท่าที่ทำได้และควรตรวจสอบทีละ repo

เส้นทางที่รองรับอย่างเป็นทางการ: Gitea v1.22 หรือเก่ากว่า

หากคุณใช้ Gitea v1.22 หรือเก่ากว่า เอกสารการย้ายข้อมูลอย่างเป็นทางการ อธิบายเส้นทางสองขั้นตอน คือย้ายไปยัง Forgejo v10.0.x ก่อน จากนั้นอัปเกรด Forgejo v10 ไปยังรุ่นปัจจุบัน ขั้นตอนแรกเป็นการสลับแบบพร้อมใช้ทันที เพราะ Forgejo v10.x อ่านฐานข้อมูล Gitea v1.22 ได้โดยตรง ส่วนขั้นตอนที่สองก็เป็นการอัปเกรด Forgejo แบบปกติ

มีสองวิธีในการทำเช่นนี้ ขึ้นอยู่กับว่า Gitea ทำงานบนเซิร์ฟเวอร์ของคุณอย่างไร ให้เลือกวิธีที่ตรงกับการตั้งค่าที่มีอยู่แล้วของคุณ หาก Gitea ทำงานเป็น system service ให้ใช้เส้นทางแบบเนทีฟ หาก Gitea ทำงานใน container ให้ใช้เส้นทางแบบ Docker Forgejo v10.x ทำหน้าที่เป็นตัวทดแทนโดยตรงสำหรับ Gitea v1.22.x

เส้นทาง Native (systemd)

สำรองข้อมูลก่อน จากนั้นติดตั้ง Forgejo v10.0.x โดยใช้แพ็กเกจของดิสโทรของคุณหรือไบนารีรีลีสที่ล็อกไว้ที่ v10.0 หยุด Gitea ก่อนที่จะคัดลอกสิ่งใด บริการที่กำลังรันและเขียนลงในไดเรกทอรีข้อมูลระหว่างการคัดลอกจะทำให้สำเนาเสียหาย

# Stop the running Gitea service before touching its data
systemctl stop gitea

คัดลอกไฟล์คอนฟิกและไดเรกทอรีข้อมูลไปยังตำแหน่งของ Forgejo แล้วแก้ไขสิทธิ์ความเป็นเจ้าของ ไฟล์คอนฟิกต้องให้กลุ่ม forgejo อ่านได้ และข้อมูลต้องเป็นของผู้ใช้ forgejo

# Copy the existing Gitea config to Forgejo's config path
cp /etc/gitea/app.ini /etc/forgejo/app.ini

# Back up the copied config before rewriting paths
cp /etc/forgejo/app.ini /etc/forgejo/app.ini.bak

# Update old Gitea data paths to Forgejo data paths
sed -i 's#/var/lib/gitea#/var/lib/forgejo#g' /etc/forgejo/app.ini

# Forgejo reads its config as the forgejo group; grant group write
chown root:forgejo /etc/forgejo/app.ini && chmod g+w /etc/forgejo/app.ini

# Copy the data directory and hand ownership to the forgejo user
rsync -aHAX --numeric-ids /var/lib/gitea/ /var/lib/forgejo/
chown -R forgejo:forgejo /var/lib/forgejo

เริ่มการทำงานของ Forgejo และเปิดใช้งานให้ทำงานตอนบูตเครื่อง

# Start Forgejo and enable it at boot
systemctl start forgejo && systemctl enable forgejo

ก่อนที่คุณจะอัปเกรดออกจาก v10.0 ให้เคลียร์คิวก่อน เพื่อไม่ให้งานที่กำลังดำเนินการสูญหายระหว่างการกระโดดเวอร์ชัน

# Flush pending queue items before the version upgrade
forgejo manager flush-queues

ตอนนี้ให้อัปเกรด Forgejo v10.0.x ไปเป็นรีลีสปัจจุบัน โดยแทนที่ไบนารีด้วย v15 แล้วรีสตาร์ตบริการ ตามขั้นตอนมาตรฐาน คู่มืออัปเกรด Forgejo หลังจากผ่านทั้งสองขั้นแล้ว ให้รันคำสั่ง doctor เพื่อตรวจสอบฐานข้อมูลและแก้ไขสิ่งที่มันแก้ได้

# Check everything; write a log you can read if something is wrong
forgejo doctor check --all --log-file /tmp/doctor.log

อ่าน /tmp/doctor.log ก่อนที่จะใช้การแก้ไขอัตโนมัติใด ๆ ใช้ --fix เฉพาะเมื่อผลลัพธ์จากคำสั่ง doctor ระบุการซ่อมแซมที่เจาะจงซึ่งคุณเข้าใจ หรือเมื่อคุณกำลังทำตามขั้นตอนแก้ไขปัญหาอย่างเป็นทางการเท่านั้น

หากคำสั่ง doctor รายงานว่าไม่มีข้อผิดพลาดร้ายแรง และ web UI แสดงรายการ repository ของคุณครบถ้วน แสดงว่าการย้ายข้อมูลรอบแรกเสร็จสมบูรณ์

เส้นทาง Docker / Container

หาก Gitea รันเป็นคอนเทนเนอร์ ให้รัน Forgejo ในแบบเดียวกัน ใช้อิมเมจ Forgejo v10.x แทนที่อิมเมจ Gitea v1.22.x ของคุณโดยตรง โดยชี้ไปยัง data volume และฐานข้อมูลเดียวกัน ตรวจสอบก่อนว่าเวอร์ชัน Docker ของคุณอย่างน้อย 20.10.6 เวอร์ชันที่เก่ากว่านี้จะทำให้เกิดพฤติกรรมที่ไม่แน่นอนกับคอนเทนเนอร์ Forgejo

รายละเอียดหนึ่งเฉพาะสำหรับ container ที่มักทำให้คนสับสน คือตัวแปรสภาพแวดล้อม (environment variables) Forgejo ยังคงใช้ prefix GITEA_ ไว้เพื่อความเข้ากันได้ แต่เอกสารแนะนำให้ส่ง prefix ทั้งสองแบบ เพื่อให้การตั้งค่าของคุณยังใช้งานได้แม้ในอนาคต Forgejo จะเลิกใช้ชื่อเดิม

# docker-compose.yml (excerpt): pass both prefixes for forward compatibility
environment:
  - GITEA__database__DB_TYPE=postgres
  - FORGEJO__database__DB_TYPE=postgres
  # ...repeat the dual-prefix pattern for every config override you pass

สำหรับคอนเทนเนอร์แบบ rootless ข้อมูลต้องเป็นของผู้ใช้ 1000 และกลุ่ม 1000 ให้ตรงกับผู้ใช้ runtime ของอิมเมจแบบ rootless หลังจากคอนเทนเนอร์เริ่มทำงานบน v10.x แล้ว ให้รันคำสั่งเดียวกัน forgejo doctor check --all จากภายใน container จากนั้นอัปเกรด image tag ไปยังรุ่น v15 ปัจจุบัน แล้วรีสตาร์ท

หากคุณใช้ Gitea v1.23 หรือใหม่กว่า

นี่คือจุดที่คู่มือมาตรฐานหยุดลง และเป็นจุดที่การติดตั้งส่วนใหญ่ในปัจจุบันอยู่จริง ไม่มีเส้นทางตรงที่รองรับอย่างเป็นทางการจาก Gitea v1.23 ขึ้นไป ดังนั้นทุกตัวเลือกด้านล่างนี้จึงมาจากชุมชนหรือมีการสูญเสียข้อมูล ก่อนที่คุณจะรันตัวเลือกใด ๆ เหล่านี้ ให้สำรองข้อมูล data directory และฐานข้อมูลของคุณให้ครบถ้วน และยืนยันว่าคุณสามารถกู้คืนได้ วิธีการเหล่านี้จะแก้ไขข้อมูลจริงในระบบใช้งาน การสำรองข้อมูลคือทางเดียวที่จะย้อนกลับได้

ตัวเลือกทั้งสามแตกต่างกันในเรื่องความเสี่ยงและปริมาณข้อมูลที่คงไว้ได้ ให้เลือกตัวเลือกที่คุณยอมรับข้อแลกเปลี่ยนได้

ตัวเลือก A: การลดระดับ SQL Schema / แพตช์เวอร์ชัน

วิธีแก้ปัญหาที่แคบที่สุดคือการลดระดับเวอร์ชันของ database schema เพื่อให้ Forgejo v10 มองว่าเป็นฐานข้อมูลเวอร์ชัน v1.22

หมายเหตุ: อย่าถือว่าการอัปเดตเวอร์ชันเป็นการดาวน์เกรดที่สมบูรณ์ด้วยตัวมันเอง เวอร์ชันการย้ายข้อมูลที่บันทึกไว้และ schema จริงต้องตรงกัน บน Gitea 1.23.x ให้ทดสอบการดาวน์เกรดแบบเต็มบนสำเนาก่อน แล้วเปรียบเทียบ schema ก่อนที่จะชี้ Forgejo ไปยังมัน

ผู้ดูแลโครงการ Forgejo คนหนึ่งได้อธิบาย SQL ไว้ใน Codeberg issue #7638:

-- Downgrade the recorded schema version to the v1.22 baseline (PostgreSQL/MySQL)
UPDATE version SET version=305 WHERE id=1;

หลังจากนี้ คุณจะทำตามเส้นทางที่รองรับเหมือนกับว่าคุณอยู่บน v1.22 ข้อควรระวังสำคัญคือ ผู้ดูแลโครงการยืนยันเรื่องนี้เฉพาะสำหรับ Gitea v1.23.1 เท่านั้น ไม่ใช่ v1.23.x ทั้งหมด หมายเลขเวอร์ชันของ schema ต้องตรงเป๊ะ การใส่ค่าเป้าหมายที่ผิดให้กับรีลีส Gitea ที่ผิดอาจทำให้ฐานข้อมูลอยู่ในสถานะที่ไม่มีการย้ายข้อมูลใดกู้คืนได้ นี่คือ PostgreSQL/MySQL ซึ่งไม่ได้รับการรองรับอย่างเป็นทางการ และไม่ได้ผ่านการทดสอบในฐานะขั้นตอนทั่วไป

เคล็ดลับ: การตั้งค่า version=305 โดยตรงจะข้ามการย้ายข้อมูลจาก 304→305 ซึ่งเป็นขั้นตอนที่เปลี่ยนวิธีการเข้ารหัสคีย์ลับของ TOTP Codeberg issue #8210 ระบุไว้ว่าปัญหานี้ทำให้ระบบยืนยันตัวตนสองขั้นตอน (two-factor authentication) เสียหายสำหรับผู้ใช้ที่ได้รับผลกระทบ วิธีแก้คือตั้งค่าเวอร์ชันเป็น 304 แล้วปล่อยให้การย้ายข้อมูลรันไป หรือลบแถวข้อมูลในตาราง two_factor เพื่อให้ผู้ใช้ลงทะเบียนใหม่ อย่าข้ามขั้นตอนนี้หากมีบัญชีใดที่ใช้ TOTP

ตัวเลือก B: สคริปต์ลดระดับ SQL แบบต่อเนื่อง (Gitea 1.24–1.25.2)

สำหรับเวอร์ชันระหว่าง 1.24 ถึง 1.25.2 การแพตช์เวอร์ชันเดียวไม่เพียงพอ เพราะ schema ผ่านสถานะกลางหลายขั้นตอน สคริปต์จากชุมชนที่ xlrl/prepare-gitea-migration-to-forgejo ปรับ schema ย้อนกลับผ่านเวอร์ชันกลางต่าง ๆ จนถึง v1.22 จากนั้นคุณจึงใช้เส้นทางที่รองรับอย่างเป็นทางการต่อไป สคริปต์เหล่านี้เป็นผลงานของชุมชน ไม่ใช่ขั้นตอนที่เป็นทางการ และออกแบบมาสำหรับ SQLite เป็นกรณีหลัก ให้รันเฉพาะกับฐานข้อมูลที่คุณสำรองไว้แล้วเท่านั้น

ตัวเลือก C: การย้ายข้อมูลผ่าน API ทีละ Repo (Gitea 1.26+ หรือเวอร์ชันใดก็ได้)

เส้นทางผ่าน repo/API คงข้อมูล Git ไว้ได้อย่างน่าเชื่อถือที่สุด ขึ้นอยู่กับต้นทาง สิทธิ์การเข้าถึง และวิธีการย้ายข้อมูล ข้อมูลเมทาดาต้าเสริม เช่น issue, pull request, label, milestone, release, ข้อมูล wiki และความคิดเห็น อาจสามารถย้ายมาได้เช่นกัน แต่ควรถือว่าเป็นการพยายามเท่าที่ทำได้ (best-effort) และควรตรวจสอบทีละ repo สำหรับการเก็บถาวรเฉพาะโค้ด วิธีนี้มักใช้ได้ดี แต่สำหรับเซิร์ฟเวอร์ที่ issue tracker คือความทรงจำของทีม ควรทดสอบการย้ายเมทาดาต้าก่อนที่จะตัดสินใจใช้เส้นทางนี้

มีเครื่องมือทดลองสองตัวที่พยายามทำการย้ายข้อมูลให้ครบถ้วนยิ่งขึ้นสำหรับ 1.23 ขึ้นไป แต่ก็มีข้อจำกัดของตัวเองเช่นกัน pacnpal/gitea2forgejo (GitHub) ทำการดัมป์ข้อมูลแบบเต็มพร้อมซิงค์ผ่าน API และต้องใช้ SECRET_KEY ที่ตรงกันเพื่อให้ฟิลด์ที่เข้ารหัสย้ายข้อมูลได้ แต่จะไม่ย้าย Personal Access Tokens, Actions runners, webhook callback URLs หรือ 2FA nicoverbruggen/gitea-to-forgejo (GitHub) เป็นเครื่องมือทดลองที่ใช้ Podman ซึ่งย้ายผู้ใช้ คีย์ องค์กร repo ปัญหา PR รีลีส และมิเรอร์ แต่ไม่ย้าย 2FA token ข้อมูล runtime ของ Actions หรือ OCI package manifest ที่ค้างอยู่ ให้ถือว่าทั้งสองเครื่องมือนี้เป็นแบบทดลอง และตรวจสอบผลลัพธ์เทียบกับตารางการย้ายข้อมูลด้านล่าง

สรุปประเด็นสำคัญ: ไม่มีเส้นทางอัปเกรดโดยตรงที่รองรับอย่างเป็นทางการจาก Gitea 1.23 ขึ้นไป ให้เลือกตัวเลือกที่คุณยอมรับการสูญเสียข้อมูลได้ และสำรองข้อมูลก่อนเริ่มดำเนินการ

การย้ายข้อมูลบนเซิร์ฟเวอร์ใหม่ปลอดภัยกว่า แต่ไม่ได้ข้ามจุดหักเหเวอร์ชัน

เซิร์ฟเวอร์ใหม่เป็นที่ที่ปลอดภัยที่สุดสำหรับเตรียมและตรวจสอบการย้ายข้อมูล แต่มันไม่ใช่เส้นทางความเข้ากันได้ของ schema แยกต่างหาก หากแหล่งข้อมูลของคุณเป็น Gitea v1.22 หรือเก่ากว่า ให้ติดตั้ง Forgejo v10.0.x บนเป้าหมายก่อน กู้คืนหรือคัดลอกข้อมูล Gitea ไปที่นั่น ปล่อยให้ Forgejo รันการย้าย database ที่รองรับ แล้วจึงอัปเกรด Forgejo v10 instance นั้นไปเป็นรีลีส Forgejo ปัจจุบัน

หากแหล่งข้อมูลของคุณคือ Gitea v1.23 หรือใหม่กว่า อย่ากู้คืนฐานข้อมูล Gitea เข้าไปยัง Forgejo เวอร์ชันปัจจุบันโดยตรงแล้วคาดหวังว่ามันจะเริ่มทำงานได้ คุณยังต้องใช้หนึ่งในแนวทาง 1.23+ ที่ไม่ได้รับการรองรับข้างต้น ไม่ว่าจะเป็นการดาวน์เกรดหรือย้อนกลับ SQL แบบเป็นขั้นตอน เครื่องมือย้ายข้อมูลจากชุมชน หรือการย้ายข้อมูลผ่าน repo/API เซิร์ฟเวอร์ใหม่ช่วยลดความเสี่ยงในการย้อนกลับ เพราะเครื่อง Gitea ต้นฉบับจะไม่ถูกแตะต้อง แต่ไม่ได้ขจัดความจำเป็นในการจัดการความไม่ตรงกันของเวอร์ชันฐานข้อมูล

นี่คือจุดที่ Forgejo แบบคลิกเดียวของ Cloudzy แอปสามารถช่วยได้ ใช้เป็น instance เป้าหมายที่สะอาด จากนั้นรันวิธีการย้ายข้อมูลที่ตรงกับเวอร์ชัน Gitea ของคุณ image ใน marketplace ของ Cloudzy มอบเป้าหมาย Forgejo ที่พร้อมใช้งานบน VPS ประสิทธิภาพสูง, เพื่อให้คุณสามารถโฟกัสที่ขั้นตอนการกู้คืน การตรวจสอบ และการสลับระบบ แทนที่จะเป็นการติดตั้งเริ่มต้น แผนการย้ายข้อมูลยังคงขึ้นอยู่กับว่าคุณอยู่ก่อนหรือหลังจุดหักเห Gitea 1.22

อะไรที่ย้ายได้ และอะไรที่คุณต้องทำใหม่

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

มีสี่รายการที่ได้รับผลกระทบหนักที่สุด เพราะมันเสียหายแบบเงียบๆ หรือส่งผลต่อผู้ใช้ทุกคน จึงต้องจัดการอย่างระมัดระวัง คือผู้ใช้ควรสร้างใหม่หรือตรวจสอบ Personal Access Tokens ของตน คุณต้องลงทะเบียน Actions runners ใหม่กับชื่อโฮสต์ใหม่ คุณต้องลบดัชนีค้นหา Bleve เพื่อให้ Forgejo สร้างใหม่อย่างสะอาด และคุณต้องเขียนใหม่ทุก uses: การอ้างอิงแบบสั้นใน Actions workflow ของคุณ ให้เปลี่ยนเป็น URL แบบเต็มของ GitHub เพราะ Forgejo และ Gitea ดึง action มาจาก mirror คนละแหล่งกัน และการอ้างอิงแบบสัมพัทธ์จะชี้ไปยังตำแหน่งที่ผิด

เคล็ดลับ: หากคุณรัน Gitea และ Forgejo พร้อมกันระหว่างการย้ายข้อมูล และทั้งสองชี้ไปยัง Redis instance เดียวกัน ให้เปลี่ยน Forgejo ให้ใช้ Redis db=1 ก่อนเริ่มต้น ทั้งสองระบบใช้ค่าเริ่มต้นเป็น db=0 และหากใช้ร่วมกัน Gitea จะดึงเหตุการณ์การย้ายข้อมูลของ Forgejo ไปใช้และทำลายคิวการย้ายข้อมูล (blog.mei-home.net documents this exact failure.)

สรุปประเด็นสำคัญ: Personal Access Tokens, Actions runner, deploy key ต่อ repo และดัชนีค้นหา Bleve ต้องทำด้วยตนเองเสมอ ควรกำหนดให้เป็นงานหนึ่งในแผนการย้ายข้อมูล ไม่ใช่สิ่งที่นึกขึ้นได้ทีหลัง

ตรวจสอบว่าการย้ายข้อมูลสำเร็จ

เริ่มต้นด้วยคำสั่ง doctor จากนั้นตรวจสอบตัวเลข แล้วจึงทดสอบสิ่งที่ผู้ใช้งานจริงทำ คำสั่ง doctor จะตรวจจับปัญหาระดับฐานข้อมูล ส่วนการตรวจสอบด้วยตนเองจะจับปัญหาการสูญเสียข้อมูลและการเข้าถึงที่ doctor มองไม่เห็น

1. รัน forgejo doctor check --all --log-file /tmp/doctor.log, จากนั้นอ่านล็อกก่อนทำการเปลี่ยนแปลงใดๆ ใช้ --fix เฉพาะสำหรับการซ่อมแซมที่เจาะจงซึ่งคุณเข้าใจเท่านั้น
2. ยืนยันว่าจำนวน repository จำนวนปัญหาและ PR รวมถึงจำนวนออบเจกต์ LFS และขนาดรวม ตรงกับตัวเลขก่อนการย้ายข้อมูลทั้งหมด หากไม่ตรงกัน แสดงว่ามีบางอย่างไม่ถูกย้ายมา
3. ทดสอบ push และ pull ผ่าน SSH หากไคลเอนต์พบข้อผิดพลาด host-key mismatch แสดงว่าคุณยังไม่ได้คัดลอก /etc/ssh/ssh_host_* ไปยังเซิร์ฟเวอร์ใหม่
4. เข้าสู่ระบบและยืนยันว่า 2FA ทำงานได้สำหรับบัญชีที่ใช้งานมัน หาก TOTP เสีย ให้ดูข้อควรระวังของตัวเลือก A ด้านบน
5. สร้าง Personal Access Tokens ใหม่ ลงทะเบียน Actions runner ใหม่ และรัน workflow ทดสอบ

อาการที่พบหลังการย้ายข้อมูลบางอย่างมีสาเหตุที่ทราบแล้ว หาก favicon หรือโลโก้หายไป แสดงว่าไฟล์แบรนด์ของคุณยังอยู่ที่ public/assets/img/ แทนที่จะเป็น custom/ ซึ่งเป็นตำแหน่งที่ Forgejo คาดหวังในปัจจุบัน ข้อผิดพลาด 404 บนเส้นทาง package บ่งชี้ถึงเส้นทางจัดเก็บข้อมูลที่ตั้งค่าผิด ส่วน Actions ที่ล้มเหลวด้วยข้อความ "repository not found" คือ uses: ปัญหาเรื่อง mirror ให้เปลี่ยนไปใช้ URL แบบเต็ม หน้าว่างเปล่าหรือข้อผิดพลาด 500 หลังเข้าสู่ระบบบนฐานข้อมูล SQLite หมายความว่าคุณต่ำกว่าค่าต่ำสุดที่กำหนด ซึ่ง เอกสารการอัปเกรด กำหนดไว้ที่ Forgejo v1.19.3-0

เมื่อใดที่การอยู่กับ Gitea ต่อไปสมเหตุสมผล

การย้ายข้อมูลเป็นทางเลือก ไม่ใช่ข้อบังคับ หากคุณผ่านจุดหักเหมาแล้วและความซับซ้อนของการย้ายข้อมูลมีน้ำหนักมากกว่าประโยชน์ด้านการกำกับดูแลหรือฟีเจอร์สำหรับสถานการณ์ของคุณ การอยู่กับ Gitea ต่อก็เป็นทางเลือกที่ชอบธรรม Gitea ได้รับการดูแลอย่างต่อเนื่อง (หลายรีลีสต่อเดือน ปัจจุบันอยู่ที่ v1.26.4) และ CommitGo มีตัวเลือกเชิงพาณิชย์ให้เลือกรวมถึง Gitea Enterprise, Gitea Cloud และการรับรอง SOC 2 Type 2 สำหรับทีมที่ต้องการสิ่งเหล่านี้

ยังมีข้อกังวลเรื่องขั้นตอนกลางที่ EOL แล้วที่ต้องพิจารณาอย่างตรงไปตรงมาด้วย เส้นทางตรงที่รองรับอย่างเป็นทางการกำหนดให้ต้องติดตั้ง Forgejo v10.0 ชั่วคราว ซึ่งหมดอายุการสนับสนุน (EOL) ตั้งแต่เดือนเมษายน 2025 นั่นเป็นสิ่งที่ยอมรับได้ในฐานะขั้นตอนการย้ายข้อมูลชั่วคราวที่คุณจะอัปเกรดออกจากมันทันที แต่ผู้ดูแลระบบบางรายอาจคัดค้านด้วยเหตุผลด้านนโยบาย สำหรับคนกลุ่มนี้ การย้ายข้อมูลผ่าน repo/API ไปยัง Forgejo instance ใหม่สามารถหลีกเลี่ยงขั้นตอน EOL นี้ได้ทั้งหมด ในขณะที่การจัดเตรียมเซิร์ฟเวอร์ใหม่ยังคงขึ้นอยู่กับวิธีการย้ายข้อมูลที่คุณเลือก

หากเหตุผลที่คุณต้องการย้ายคือกิจกรรมการพัฒนา ข้อมูลสนับสนุนว่า Forgejo เป็นโปรเจกต์ที่มีความเคลื่อนไหวมากกว่า การวิเคราะห์โดย honeypot.net นับได้ 3,039 commit ของ Forgejo เทียบกับ 1,228 commit ของ Gitea ในช่วงเดือนกรกฎาคม 2024 ถึงพฤษภาคม 2025 และผู้มีส่วนร่วม (contributor) ของ Forgejo 232 คน เทียบกับ 153 คนของ Gitea ในช่วงหนึ่งปีที่สิ้นสุดเดือนพฤษภาคม 2025 นั่นเป็นสัญญาณหนึ่งในหลายสัญญาณ ควรชั่งน้ำหนักกับความเสี่ยงในการย้ายข้อมูลของคุณ มากกว่าที่จะถือว่าเป็นตัวชี้ขาด

สรุปประเด็นสำคัญ: การย้ายข้อมูลไม่ใช่สิ่งจำเป็น การตัดสินใจขึ้นอยู่กับความชอบด้านการกำกับดูแลและความเคลื่อนไหวของโครงการ เทียบกับความเสี่ยงของการย้ายข้อมูล และทั้งสองทางเลือกล้วนมีเหตุผลรองรับ

เลือกเส้นทางของคุณและสำรองข้อมูลก่อน

เส้นทางการย้ายข้อมูลของคุณขึ้นอยู่กับตัวเลขเพียงตัวเดียว นั่นคือเวอร์ชัน Gitea ของคุณ หากเป็น v1.22 หรือเก่ากว่า คุณจะใช้เส้นทางสองขั้นตอนที่รองรับอย่างเป็นทางการผ่าน Forgejo v10 หากเป็น v1.23 หรือใหม่กว่า คุณจะเลือกวิธีแก้ปัญหาตามระดับการสูญเสียข้อมูลที่คุณยอมรับได้ ไม่ว่าจะเป็นการลดระดับ SQL/schema, สคริปต์จากชุมชน, การย้ายข้อมูลผ่าน repo/API หรือการจัดเตรียมเซิร์ฟเวอร์ใหม่ ไม่ว่าคุณจะเลือกเส้นทางใด ให้สำรอง data directory และฐานข้อมูลของคุณก่อน แล้วจึงรัน forgejo doctor หลังจากนั้น และยืนยันว่าจำนวน repository, issue และ LFS ตรงกับที่คุณมีอยู่ตอนเริ่มต้น

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

คำถามที่พบบ่อย

ฉันสามารถอัปเกรดจาก Gitea ไปยัง Forgejo ได้โดยตรงหรือไม่

ได้ หากคุณใช้ Gitea v1.22 หรือเก่ากว่า ให้อัปเกรดตรงไปยัง Forgejo v10.0 จากนั้นอัปเกรด Forgejo v10 ไปยังรุ่นปัจจุบัน ไม่ได้ หากคุณใช้ Gitea v1.23 หรือใหม่กว่า เนื่องจาก Forgejo v10.0 เป็นรุ่นสุดท้ายที่รองรับการอัปเกรดโดยตรงแบบโปร่งใส เวอร์ชัน Gitea ที่ใหม่กว่านั้นจึงต้องใช้วิธีแก้ปัญหาทางอ้อมแทน

Gitea เวอร์ชันใดที่เข้ากันได้กับ Forgejo?

Gitea v1.22 และเก่ากว่านั้นมีเส้นทางอัปเกรดตรงไปยัง Forgejo ที่รองรับ (ไปจนถึง Forgejo v10.0 แล้วต่อไปยังเวอร์ชันปัจจุบัน) ส่วน Gitea v1.23 และใหม่กว่านั้นไม่มีเส้นทางตรงที่ได้รับการรองรับอย่างเป็นทางการ เพราะ Forgejo หยุดรองรับการอัปเกรดแบบโปร่งใสจาก Gitea v1.23+ ตั้งแต่รีลีสหลังจาก v10.0 เป็นต้นไป

ฉันสามารถย้ายจาก Gitea 1.26 ไปยัง Forgejo ได้หรือไม่

ได้ แต่ไม่ใช่ผ่านการอัปเกรดโดยตรงที่รองรับอย่างเป็นทางการ ตัวเลือกของคุณคือการย้ายข้อมูลผ่าน repo/API ซึ่งประวัติ Git เป็นส่วนที่เชื่อถือได้และต้องทดสอบเมทาดาต้าทีละ repo สคริปต์ย้ายข้อมูลทดลอง หรือการจัดเตรียมเซิร์ฟเวอร์ใหม่โดยใช้หนึ่งในวิธีที่ไม่ได้รับการรองรับสำหรับ 1.23 ขึ้นไปข้างต้น ไม่มีเส้นทางในที่เดิม (in-place) ที่รองรับอย่างเป็นทางการจาก Gitea 1.26

Personal Access Tokens ของฉันจะถูกย้ายไปด้วยหรือไม่

วางแผนที่จะสร้างใหม่หรือหมุนเวียน Personal Access Tokens หลังการย้ายข้อมูล เส้นทางการย้ายข้อมูลบางแบบไม่คงค่าโทเคนเหล่านี้ไว้ และแม้ในกรณีที่โทเคนยังคงอยู่ ผู้ใช้ก็ควรตรวจสอบขอบเขตสิทธิ์ (scope) ก่อนที่จะนำกลับมาใช้อีกครั้ง สคริปต์หรือระบบเชื่อมต่อใด ๆ ที่ใช้โทเคนเก่าควรได้รับการทดสอบและอัปเดตหลังจากการเปลี่ยนระบบเสร็จสิ้น

Gitea Actions workflow ของฉันจะทำงานใน Forgejo ได้หรือไม่

ส่วนใหญ่ใช่ โดยต้องมีการแก้ไขที่จำเป็นสองอย่าง Workflow uses: การอ้างอิงแบบสั้นจะใช้งานไม่ได้ เพราะ Forgejo และ Gitea ดึง action มาจาก mirror คนละแหล่งกัน ให้เปลี่ยนไปใช้ URL แบบเต็มของ GitHub (ตัวอย่างเช่น uses: https://github.com/sammcj/dotenv-output-action@main) คุณต้องลงทะเบียน Actions runners ใหม่ด้วย เพราะโทเคนการลงทะเบียนของมันผูกอยู่กับชื่อโฮสต์เดิม

การย้ายจาก Gogs ไปยัง Forgejo ล่ะ?

นั่นคือการย้ายข้อมูลอีกแบบที่มีเส้นทางต่างออกไปและอยู่นอกขอบเขตของบทความนี้ คู่มือนี้ครอบคลุมเฉพาะการย้ายจาก Gitea ไปยัง Forgejo หากต้นทางเป็น Gogs ให้ดูเอกสารการย้ายข้อมูลอย่างเป็นทางการของ Forgejo สำหรับขั้นตอนเฉพาะของ Gogs