วิธีตั้งค่า Collabora Online ให้ใช้งานร่วมกับ Nginx

สิ่งที่รีเวิร์สพร็อกซีที่ใช้งานได้ควรทำ

การใช้งาน Collabora Online อย่างมีประสิทธิภาพบน Nginx จะช่วยให้ผู้ใช้มีที่อยู่ HTTPS สาธารณะหนึ่งที่อยู่สำหรับโปรแกรมแก้ไข ในขณะที่ยังคงให้บริการ Collabora ไว้บนเครือข่ายส่วนตัว โปรแกรมแก้ไขควรโหลดส่วนประกอบของเบราว์เซอร์ ค้นหาความสามารถของโปรแกรม Office เปิดเอกสารผ่านแพลตฟอร์มจัดเก็บข้อมูลที่เชื่อมต่อ และรักษาการเชื่อมต่อ WebSocket ให้คงอยู่ระหว่างการแก้ไข การตรวจสอบไวยากรณ์ Nginx ที่ถูกต้องเพียงอย่างเดียวไม่ได้พิสูจน์ว่าเส้นทางเหล่านั้นใช้งานได้

ตัวอย่างนี้สมมติว่าเซิร์ฟเวอร์ Collabora หรือคอนเทนเนอร์ CODE แบบสแตนด์อโลนรับฟังที่พอร์ต 9980, Nginx ให้บริการoffice.example.comและ TLS สิ้นสุดที่ Nginx แทนที่ชื่อโฮสต์และเส้นทางใบรับรองด้วยของคุณเอง ที่อยู่แบ็กเอนด์127.0.0.1:9980จะใช้ได้เฉพาะเมื่อ Nginx และ Collabora ใช้โฮสต์เดียวกันและบริการถูกผูกไว้กับลูปแบ็ก สำหรับคอนเทนเนอร์ที่แยกต่างหาก ให้ใช้ชื่อบริการ Collabora บนเครือข่าย Docker ส่วนตัวhttp://collabora:9980เช่น

ก่อนที่จะเปลี่ยน Nginx

ตรวจสอบให้แน่ใจว่าชื่อ DNS สาธารณะสามารถแปลงเป็นพร็อกซีได้ ใบรับรอง TLS ครอบคลุมชื่อนั้นอย่างถูกต้อง และ Nginx สามารถเข้าถึง Collabora ได้ที่ที่อยู่ภายใน หากคุณใช้ Docker ให้เชื่อมต่อทั้งสองบริการเข้ากับเครือข่ายที่ผู้ใช้กำหนดเอง และอย่าเผยแพร่พอร์ต Collabora สู่สาธารณะ หาก Nginx ทำงานบนโฮสต์ ให้ผูกพอร์ตคอนเทนเนอร์เข้ากับ loopback ตัวอย่างเช่น127.0.0.1:9980:9980ไฟร์วอลล์ของคุณควรเปิดเผยพอร์ตเว็บสาธารณะที่คุณต้องการให้บริการ ไม่ใช่พอร์ตแบ็กเอนด์ของ Collabora

เลือกรูปแบบ TLS หนึ่งแบบ การกำหนดค่าด้านล่างใช้ TLS จากเบราว์เซอร์ไปยัง Nginx และ HTTP ธรรมดาบนเครือข่ายส่วนตัวที่เชื่อถือได้ไปยัง Collabora นี่คือการยุติ TLS หากนโยบายกำหนดให้มีการเข้ารหัสระหว่างพร็อกซีและ Collabora ด้วย ให้ใช้ HTTPS สำหรับฝั่งอัปสตรีมและกำหนดค่า Nginx ให้เชื่อถือใบรับรองแบ็กเอนด์ อย่าเปลี่ยนเฉพาะproxy_passรูปแบบ: การตั้งค่า TLS ฝั่งเซิร์ฟเวอร์ต้องตรงกับ Listener ของ Collabora จริง Collabora ได้อธิบายรูปแบบพร็อกซีทั้งสองแบบไว้ในคำแนะนำเกี่ยวกับ Reverse Proxy ของ Nginxและ คู่มือ SDK เวอร์ชัน25.04

ตั้งค่าตัวเลือก TLS ที่รองรับพร็อกซีของ Collabora

สำหรับการยุติการเชื่อมต่อ TLS ให้กำหนดค่าบริการของ Collabora coolwsdด้วยssl.enable=falseและssl.termination=trueวิธีการตั้งค่าเหล่านี้ขึ้นอยู่กับวิธีการติดตั้ง Collabora: แก้ไขcoolwsd.xmlการกำหนดค่าที่รองรับ หรือใช้ตัวเลือกที่ระบุไว้ในเอกสารสำหรับแพ็กเกจหรือคอนเทนเนอร์ของคุณ สำหรับอิมเมจ Docker CODE การใช้งานมักจะส่งผ่านตัวเลือกเป็นextra_params; ตรวจสอบเอกสารประกอบของอิมเมจสำหรับเวอร์ชันของคุณและใส่เครื่องหมายคำพูดให้กับอาร์กิวเมนต์อย่างถูกต้องใน Compose รีสตาร์ทหรือสร้างบริการ Collabora ใหม่หลังจากเปลี่ยนการกำหนดค่าแล้ว

การตั้งค่าเหล่านี้จะบอก Collabora ว่าการเชื่อมต่อภายนอกได้รับการปกป้องโดยพร็อกซี แม้ว่าการเชื่อมต่อจากพร็อกซีไปยังแบ็กเอนด์จะใช้ HTTP ก็ตาม การตั้งค่าเหล่านี้ไม่ได้ติดตั้งใบรับรองสาธารณะ กำหนดค่า DNS หรืออนุญาตให้เซิร์ฟเวอร์จัดเก็บข้อมูลใช้ Collabora โปรดกำหนดค่ารายการอนุญาตโฮสต์ WOPI หรือการตั้งค่าการรวมระบบแยกต่างหากตามแพลตฟอร์มจัดเก็บข้อมูลของคุณ

กำหนดค่า Nginx เพื่อส่งต่อเส้นทางของตัวแก้ไข

Nginx ต้องส่งต่อทรัพยากรการค้นหาและเบราว์เซอร์ และรักษาการอัปเกรด WebSocket ที่ใช้โดยการแก้ไขแบบโต้ตอบ ตัวอย่างต่อไปนี้เป็นตัวอย่างเซิร์ฟเวอร์เดียว กำหนดค่าmapในบริบทของ Nginx httpเช่น ในไฟล์หลักnginx.confไม่ใช่ภายในโฮสต์เสมือน:

map $http_upgrade $connection_upgrade {
    default upgrade;
    ''      close;
}

วางบล็อกเซิร์ฟเวอร์ไว้ในไฟล์การตั้งค่าเว็บไซต์ที่มาพร้อมกับ Nginx โดยสมมติว่าได้ติดตั้งใบรับรอง TLS แล้ว และการเชื่อมต่อพร็อกซีไปยัง Collabora เป็นแบบ HTTP:

server {
    listen 443 ssl;
    server_name office.example.com;

    ssl_certificate     /etc/letsencrypt/live/office.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/office.example.com/privkey.pem;

    location ^~ /browser {
        proxy_pass http://127.0.0.1:9980;
        proxy_set_header Host $host;
    }

    location ^~ /hosting/discovery {
        proxy_pass http://127.0.0.1:9980;
        proxy_set_header Host $host;
    }

    location ^~ /hosting/capabilities {
        proxy_pass http://127.0.0.1:9980;
        proxy_set_header Host $host;
    }

    location ~ ^/cool/(.*)/ws$ {
        proxy_pass http://127.0.0.1:9980;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
        proxy_set_header Host $host;
        proxy_read_timeout 36000s;
        proxy_buffering off;
    }

    location ~ ^/(c|l)ool {
        proxy_pass http://127.0.0.1:9980;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
        proxy_set_header Host $host;
        proxy_read_timeout 36000s;
    }
}

เส้นทางที่ขึ้นต้นด้วย/coolจะรับคำขอ WebSocket และคำขอแก้ไขหลัก รูปแบบนี้ยังรวมถึง/loolเส้นทางแบบเดิมเพื่อความเข้ากันได้ การพร็อกซี WebSocket ของ Nginx ต้องการส่วนหัวการอัปเกรด HTTP/1.1 เนื่องจากUpgradeและConnectionเป็นส่วนหัวแบบ hop-by-hop การหมดเวลาอ่านที่ยาวนานช่วยหลีกเลี่ยงการปิดการเชื่อมต่อการแก้ไขที่ใช้งานอยู่เนื่องจากการหมดเวลาพร็อกซีที่สั้นตามปกติ ดูเอกสารประกอบพร็อกซี WebSocket ของ Nginxและข้อมูลอ้างอิงโมดูลพร็อกซี

สำหรับการใช้งาน HTTPS บนฝั่งอัปสตรีม ให้เปลี่ยน URL ของแบ็กเอนด์https://และกำหนดค่าการตรวจสอบใบรับรองอัปสตรีมและห่วงโซ่ใบรับรองที่เชื่อถือได้ของ Nginx ให้เหมาะสม หลีกเลี่ยงการปิดใช้งานการตรวจสอบใบรับรองเป็นวิธีแก้ปัญหาถาวร หาก Nginx อยู่ในคอนเทนเนอร์อื่น ให้แทนที่ที่อยู่ลูปแบ็กด้วยชื่อบริการของ Collabora 127.0.0.1ภายในคอนเทนเนอร์พร็อกซี ให้ชี้กลับไปยังคอนเทนเนอร์พร็อกซีนั้น

เมื่อคุณใช้คำนำหน้า URI เช่น/collabora/แทนที่จะใช้ชื่อโฮสต์เฉพาะ การกำหนดค่าและ URL การค้นหาที่สร้างโดย Collabora จำเป็นต้องมีการจัดการเส้นทางเพิ่มเติม เริ่มต้นด้วยชื่อโฮสต์เฉพาะ เว้นแต่แพลตฟอร์มของคุณจะรองรับการใช้งานเส้นทางย่อยอย่างชัดเจน บล็อกเซิร์ฟเวอร์ที่ส่งต่อคำขอที่รูทไม่ได้ทำให้ URL ที่สร้างโดยการค้นหาใช้งานได้ภายใต้คำนำหน้าโดยอัตโนมัติ

โหลดซ้ำและตรวจสอบแต่ละเลเยอร์

ตรวจสอบความถูกต้องของการตั้งค่า Nginx ก่อนนำไปใช้ จากนั้นจึงรีโหลดบริการ:

sudo nginx -t
sudo systemctl reload nginx

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

curl -fsS https://office.example.com/hosting/discovery | head
curl -fsS https://office.example.com/hosting/capabilities

เอนด์พอยต์สำหรับการค้นหาควรส่งคืนข้อมูล XML แทนที่จะเป็นหน้า 404 ของ Nginx หรือหน้าล็อกอิน ส่วนเอนด์พอยต์สำหรับความสามารถต่างๆ ควรส่งคืนการตอบกลับจาก Collabora ตรวจสอบ URL ของตัวแก้ไขใน XML ของการค้นหา: ควรใช้ชื่อโฮสต์ HTTPS สาธารณะและเส้นทางที่สามารถเข้าถึงได้ ไม่ใช่ชื่อคอนเทนเนอร์หรือที่อยู่ภายในเท่านั้น ภาพตัวอย่างด้านล่างแสดงประเภทของการตอบกลับที่ควรตรวจสอบ ค่าที่แสดงเป็นเพียงตัวอย่าง ไม่ใช่ผลลัพธ์จากเซิร์ฟเวอร์จริง

สุดท้ายนี้ ให้ตั้งค่าแพลตฟอร์มเอกสารของคุณให้ใช้https://office.example.comCollabora เป็นเซิร์ฟเวอร์ และเปิดเอกสารทดสอบ สัญญาณความสำเร็จที่มีประโยชน์คือ ตัวแก้ไขโหลดและตอบสนองได้ดีขณะพิมพ์ บันทึก และเปิดเอกสารใหม่ ในเครื่องมือสำหรับนักพัฒนาของเบราว์เซอร์ คำขอ WebSocket /cool/ควรได้รับการอัปเกรดสำเร็จ สถานะ HTTP 101 Switching Protocolsคือผลลัพธ์การจับมือ WebSocket ที่คาดหวัง อย่าถือว่าสถานะตัวอย่างที่แสดงเป็นหลักฐานว่าเซิร์ฟเวอร์ของคุณผ่านการตรวจสอบนี้

อ่านความล้มเหลวจากอาการที่ปรากฏ

• 502 Bad Gateway: Nginx ไม่สามารถเชื่อมต่อกับเซิร์ฟเวอร์ต้นทางได้ โปรดตรวจสอบชื่อบริการ พอร์ต เครือข่ายคอนเทนเนอร์ ตัวรับฟัง และบันทึก หากคอนเทนเนอร์แยกจากกัน อย่าใช้ที่อยู่ลูปแบ็กของคอนเทนเนอร์พร็อกซี
• ข้อผิดพลาด 404 ในการค้นหาหรือการเข้าถึงไฟล์ในเบราว์เซอร์:ตรวจสอบให้แน่ใจว่าคำขอไปถึงโฮสต์เสมือนที่ถูกต้อง และตำแหน่งที่ตั้งส่งต่อเส้นทางโดยไม่มีการเขียน URI ใหม่โดยไม่ได้ตั้งใจ ทดสอบ URL สาธารณะ ไม่ใช่แค่ URL ของแบ็กเอนด์เท่านั้น
• โปรแกรมแก้ไขข้อความโหลดแล้วแต่ค้างหรือตัดการเชื่อมต่อ:ตรวจสอบ/cool/.../wsคำขอ ส่วนหัวการอัปเกรดหายไป การเชื่อมต่ออัปสตรีม HTTP/1.0 การหมดเวลาสั้นเกินไป หรือพร็อกซีที่บัฟเฟอร์การเชื่อมต่อ อาจทำให้การแก้ไขหยุดชะงัก ตรวจสอบให้แน่ใจว่าคำขอได้รับการอัปเกรดและยังคงเปิดอยู่ขณะที่เอกสารกำลังทำงาน
• โฮสต์ WOPI ที่ไม่ได้รับอนุญาต:พร็อกซีอาจทำงานได้ปกติ แต่ Collabora อาจปฏิเสธแพลตฟอร์มจัดเก็บข้อมูล ตรวจสอบชื่อโฮสต์ WOPI จริงกับรายการที่อนุญาตของ Collabora และการกำหนดค่าตัวเชื่อมต่อของแพลตฟอร์ม อย่าแก้ไขปัญหานี้โดยการเปิดแบ็กเอนด์สู่สาธารณะทางอินเทอร์เน็ต
• คำเตือนเกี่ยวกับเนื้อหาผสมหรือใบรับรอง:ตรวจสอบให้แน่ใจว่า URL ของตัวแก้ไขสาธารณะและ URL ในการค้นหาใช้ HTTPS และใบรับรองตรงกับชื่อโฮสต์ หากคุณทำการยุติ TLS ที่ Nginx โปรดตรวจสอบการตั้งค่าการยุติ TLS ของ Collabora ด้วย

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

แหล่งที่มาและหมายเหตุเกี่ยวกับเวอร์ชัน

รายละเอียดการกำหนดค่าได้รับการตรวจสอบกับเอกสารพร็อกซีของ Collabora และคู่มือ SDK เวอร์ชัน 25.04 รวมถึงเอกสารอ้างอิง WebSocket และ proxy-module ของ Nginx เมื่อวันที่ 6 ตุลาคม 2026 ตัวเลือกแพ็กเกจและคอนเทนเนอร์อาจแตกต่างกันไปตามเวอร์ชันของ Collabora โปรดยืนยันชื่อการตั้งค่าสำหรับเวอร์ชันที่คุณใช้งานก่อนนำไปใช้ บทความนี้ไม่ได้สมมติแพลตฟอร์มจัดเก็บข้อมูลเฉพาะหรือพิสูจน์การใช้งานจริง