วิธีใช้งาน ONLYOFFICE Document Server ร่วมกับ HAProxy Load Balancer

กฎที่สำคัญที่สุดคือ การวาง ONLYOFFICE Document Server ไว้หลัง HAProxy นั้นทำได้ง่ายสำหรับแบ็กเอนด์เดียว แต่คลัสเตอร์ตัวแก้ไขแบบหลายโหนดต้องการมากกว่าการกระจายแบบวนรอบธรรมดา เอกสาร API ปัจจุบันของ ONLYOFFICE ระบุว่า คำขอสำหรับเอกสารเดียวกันจะต้องไปถึงโหนด Document Server เดียวกันในระหว่างการแก้ไขร่วมกัน สำหรับการผสานรวมสมัยใหม่ กลไกที่แนะนำคือshardkeyพารามิเตอร์การค้นหา ซึ่งตัวโหลดบาลานเซอร์สามารถใช้เพื่อกำหนดความสัมพันธ์ตามเอกสารได้

หากคุณมี Document Server เพียงเครื่องเดียวและต้องการใช้ HAProxy สำหรับการยุติการเชื่อมต่อ HTTPS, ชื่อโฮสต์สาธารณะที่เสถียร หรือการตรวจสอบสถานะส่วนกลาง การกำหนดค่าจะง่ายกว่า แต่หากคุณมี Document Server สองเครื่องขึ้นไป ให้ใช้หลักการพื้นฐานของพร็อกซีแบบเดียวกัน แต่เพิ่มการกำหนดเส้นทางโดยอิงจากเงื่อนไขต่างๆshardkeyแทนที่จะคิดว่าการกำหนดเส้นทางแบบวนรอบธรรมดาเพียงพอแล้ว

ตัวอย่างด้านล่างนี้ได้รับการตรวจสอบกับเอกสารพร็อกซี ONLYOFFICE ฉบับปัจจุบัน เอกสารคีย์ชาร์ด ONLYOFFICEและคำแนะนำ WebSocket ของ HAProxyฉบับ ปัจจุบัน

เมื่อการตั้งค่านี้เหมาะสม

HAProxy เป็นส่วนหน้า (front-end) ที่เหมาะสมเมื่อคุณต้องการ URL สาธารณะเพียง URL เดียว เช่นhttps://docs.example.comการยุติการเชื่อมต่อ TLS ที่ตัวกระจายโหลด (load balancer) การตรวจสอบสถานะการทำงานแบบเรียลไทม์ หรือโหนดเซิร์ฟเวอร์เอกสารหลายโหนดอยู่เบื้องหลังปลายทางเดียว นอกจากนี้ยังเป็นประโยชน์เมื่อ Nextcloud, ownCloud, DMS ที่กำหนดเอง หรือแอปพลิเคชันของคุณไม่ควรเชื่อมต่อโดยตรงกับโหนดเซิร์ฟเวอร์เอกสารแต่ละโหนด

คู่มือนี้ตั้งอยู่บนสมมติฐานว่า:

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

ขั้นตอนที่ 1: ตรวจสอบ Document Server ทุกเครื่องก่อนเพิ่ม HAProxy

อย่าเริ่มต้นด้วย Load Balancer ก่อนอื่นให้ตรวจสอบว่าแบ็กเอนด์ทุกตัวทำงานได้อย่างปกติจากโฮสต์ HAProxy เอกสาร ONLYOFFICE /healthcheckใช้เป็นจุดตรวจสอบความพร้อมใช้งานของโปรแกรมแก้ไขข้อความ เซิร์ฟเวอร์ที่ทำงานได้อย่างปกติจะส่งคืนค่าtrue; การตรวจสอบครอบคลุมถึงส่วนประกอบหลัก เช่น ฐานข้อมูล ตัวกลางรับส่งข้อความ การเชื่อมต่อ Redis และพื้นที่จัดเก็บข้อมูล

curl -sS http://10.0.10.21/healthcheck
curl -sS http://10.0.10.22/healthcheck

ผลลัพธ์ที่คาดหวัง:

true
true

หากระบบแบ็กเอนด์ใดระบบหนึ่งล้มเหลว ให้ตรวจสอบปัญหาที่โหนดนั้นก่อน สาเหตุทั่วไป ได้แก่ กฎไฟร์วอลล์ พอร์ตภายในไม่ถูกต้อง บริการเซิร์ฟเวอร์เอกสารไม่ทำงาน หรือบริการสนับสนุนไม่พร้อมใช้งาน

ขั้นตอนที่ 2: ตั้งค่าโหมด HTTP และระยะเวลาหมดเวลาที่ยอมรับการเชื่อมต่อของโปรแกรมแก้ไข

ONLYOFFICE เป็นแอปพลิเคชัน HTTP และใช้การเชื่อมต่อ WebSocket ที่มีอายุการใช้งานยาวนานระหว่างการแก้ไข HAProxy สามารถทำหน้าที่เป็นพร็อกซี WebSocket โดยอัตโนมัติหลังจากการอัปเกรด HTTP แต่ค่ากำหนดระยะเวลาหมดเวลา (timeout policy) ของ HAProxy ก็ยังมีความสำคัญอยู่ เอกสารประกอบของ HAProxy เองแนะนำtimeout tunnelค่าที่เหมาะสมสำหรับการเชื่อมต่อ WebSocket ที่ได้รับการอัปเกรดแล้ว

หลักเกณฑ์พื้นฐานที่นำไปใช้ได้จริงคือ:

global
    log /dev/log local0
    log /dev/log local1 notice
    daemon
    maxconn 4096

defaults
    log global
    mode http
    option httplog
    option dontlognull
    timeout connect 5s
    timeout client 60s
    timeout server 60s
    timeout tunnel 1h

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

ขั้นตอนที่ 3: ยุติการเชื่อมต่อ HTTPS และเก็บรักษาบริบทคำขอเดิมไว้

ONLYOFFICE กำหนดให้ต้องมีการส่งต่อส่วนหัวอย่างชัดเจนเมื่อทำงานอยู่เบื้องหลังพร็อกซี โดยเฉพาะอย่างยิ่งX-Forwarded-Protoจะแจ้งให้ Document Server ทราบว่าไคลเอ็นต์ดั้งเดิมใช้ HTTP หรือ HTTPS ในขณะที่X-Forwarded-Hostยังคงรักษาชื่อโฮสต์ที่ไคลเอ็นต์ร้องขอไว้

ส่วนหน้าของ HAProxy ที่ดูเรียบร้อยสวยงามสามารถมีลักษณะดังนี้:

frontend onlyoffice_http
    bind *:80
    mode http
    http-request redirect scheme https code 301

frontend onlyoffice_https
    bind *:443 ssl crt /etc/haproxy/certs/docs.example.com.pem
    mode http
    option httplog

    http-request set-header X-Forwarded-Proto https
    http-request set-header X-Forwarded-Host %[req.hdr(Host)]

    default_backend onlyoffice_docs

โดยปกติแล้ว คุณไม่จำเป็นต้องสร้างกฎแบบ NGINX UpgradeและConnectionกฎส่วนหัวขึ้นมาใหม่ด้วยตนเองในโหมด HTTP ของ HAProxy รุ่นใหม่ HAProxy จะตรวจจับการอัปเกรดจาก HTTP เป็น WebSocket และเปลี่ยนการเชื่อมต่อเป็นโหมดอุโมงค์ สิ่งสำคัญคืออย่าใส่กฎที่ตัดทอนหรือทำให้คำขออัปเกรดเสียหาย

สำหรับการตรวจสอบ IP ของไคลเอ็นต์ ให้เพิ่มoption forwardforในส่วนแบ็กเอนด์ ซึ่งจะสร้างX-Forwarded-Forส่วนหัวจากที่อยู่ต้นทางของไคลเอ็นต์

ขั้นตอนที่ 4: เพิ่มการตรวจสอบสุขภาพและเลือกกฎการปรับสมดุลที่เหมาะสม

เซิร์ฟเวอร์เอกสารเดี่ยว

หาก HAProxy ทำหน้าที่เป็นส่วนหน้าของ Document Server เพียงเครื่องเดียว ส่วนหลังบ้านก็สามารถเรียบง่ายได้:

backend onlyoffice_docs
    mode http
    option forwardfor
    option httpchk GET /healthcheck
    http-check expect status 200
    timeout tunnel 1h

    server ds1 10.0.10.21:80 check

ในการออกแบบนี้ HAProxy ทำหน้าที่หลักๆ คือ เป็นรีเวิร์สพร็อกซี, เอนด์พอยต์ TLS และเกตตรวจสอบสถานะสุขภาพ

โหนดเซิร์ฟเวอร์เอกสารหลายตัว

สำหรับการใช้งานแบบหลายโหนดอย่างแท้จริง อย่าพึ่งพาการกระจายทรัพยากรแบบวนรอบ (round-robin) เพียงอย่างเดียวสำหรับการแก้ไขร่วมกัน เอกสารปัจจุบันของ ONLYOFFICE ระบุว่าคำขอทั้งหมดที่เกี่ยวข้องกับเอกสารเดียวกันจะต้องส่งไปยังเซิร์ฟเวอร์เดียวกัน คำขอแก้ไขจากเบราว์เซอร์ไปยังเซิร์ฟเวอร์จะรวมคีย์ชาร์ดโดยอัตโนมัติ และแอปพลิเคชันควรเพิ่มคีย์ชาร์ดลง?shardkey=<document-key>ในคำขอคำสั่ง การแปลง และการสร้างเอกสารตามที่ระบุไว้ในเอกสาร

HAProxy รองรับการแฮชบนพารามิเตอร์การค้นหาใน URL ดังนั้นแบ็กเอนด์ที่เหมาะสมสำหรับ API มาตรฐานของ ONLYOFFICE Docs คือ:

backend onlyoffice_docs
    mode http
    option forwardfor
    option httpchk GET /healthcheck
    http-check expect status 200
    timeout tunnel 1h

    balance url_param shardkey

    server ds1 10.0.10.21:80 check
    server ds2 10.0.10.22:80 check

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

WOPI แตกต่างออกไป ONLYOFFICE ระบุว่าการผสานรวม WOPI ใช้WOPISrcพารามิเตอร์การค้นหาเพื่อวัตถุประสงค์การกำหนดเส้นทางเดียวกัน อย่าคัดลอกbalance url_param shardkeyบรรทัดโดยไม่เปลี่ยนแปลงลงในการออกแบบ WOPI แล้วคิดว่ามันจะให้ความสัมพันธ์ที่ต้องการ

ตรวจสอบและโหลด HAProxy ใหม่ได้อย่างปลอดภัย

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

sudo haproxy -c -f /etc/haproxy/haproxy.cfg

โหลดหน้าเว็บใหม่หลังจากตรวจสอบความถูกต้องของไวยากรณ์สำเร็จแล้วเท่านั้น:

sudo systemctl reload haproxy
sudo systemctl status haproxy

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

ทดสอบผ่าน URL สาธารณะ ไม่ใช่แค่จากภายในเครือข่ายแบ็กเอนด์เท่านั้น

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

curl -sS https://docs.example.com/healthcheck

โครงสร้างที่คาดหวังคือ:

true

จากนั้นตรวจสอบใบรับรอง TLS:

openssl s_client -connect docs.example.com:443   -servername docs.example.com </dev/null 2>/dev/null   | openssl x509 -noout -subject -issuer -dates

สุดท้ายนี้ ให้เปิดเอกสารจริงผ่านแอปพลิเคชันที่เชื่อมต่อ การตรวจสอบสถานะความสมบูรณ์ (Health Check) พิสูจน์ได้เพียงว่าปลายทางของเซิร์ฟเวอร์เอกสารพร้อมใช้งานเท่านั้น ไม่ได้พิสูจน์ว่า URL การเรียกกลับ (Callback URL) การกำหนดค่า JWT การดาวน์โหลดเอกสาร การเรียกกลับสำหรับการบันทึก หรือความสัมพันธ์ระหว่างโหนดหลายโหนดนั้นถูกต้องทั้งหมด

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

คุณต้องการการให้คำปรึกษาแบบติดหนึบหรือไม่?

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

ความแตกต่างเดียวกันนี้อธิบายได้ว่าทำไมการใช้ sticky session แบบง่ายๆ โดยใช้คุกกี้จึงไม่ควรใช้แทนพฤติกรรมการกำหนดเส้นทางที่ระบุไว้ใน ONLYOFFICE ควรใช้คีย์ shard ที่ระบุไว้ในเอกสารของแอปพลิเคชันเมื่อคุณกำลังสร้างการปรับใช้ Docs API แบบหลายโหนด

รายการตรวจสอบการกำหนดค่าขั้นสุดท้าย

• เซิร์ฟเวอร์เอกสารทุกตัวจะส่งคืนค่าtrueจาก/healthcheckก่อนที่จะถูกเพิ่มเข้าไปใน HAProxy
• HAProxy ทำงานในโหมด HTTP สำหรับทั้งส่วนหน้าและส่วนหลังของ ONLYOFFICE
• HTTPS ถูกยุติด้วยใบรับรองที่ถูกต้องสำหรับชื่อโฮสต์ของเซิร์ฟเวอร์เอกสารสาธารณะ
• X-Forwarded-ProtoและX-Forwarded-Hostส่งต่ออย่างถูกต้อง
• ระยะเวลาหมดเวลาของอุโมงค์ WebSocket นั้นนานพอสำหรับการใช้งานตัดต่อวิดีโอจริง ๆ
• การตรวจสอบสถานะระบบแบ็กเอนด์จะลบโหนดที่ล้มเหลวออกจากระบบ
• การรับส่งข้อมูล API เอกสารแบบหลายโหนดใช้shardkeyการจัดกลุ่มตามความสัมพันธ์ ไม่ใช่แค่การกระจายแบบรอบเดียว
• การใช้งาน WOPI จะใช้การกำหนดเส้นทางที่เหมาะสมกับWOPISrc...
• ระบบตรวจสอบด้านสาธารณสุขใช้งานได้ผล และสามารถเปิด แก้ไข และบันทึกเอกสารจริงผ่านการเชื่อมต่อได้

สำหรับ Document Server เพียงเครื่องเดียว HAProxy ทำหน้าที่เป็นเพียง reverse-proxy และ TLS layer ที่สะอาดหมดจด แต่สำหรับ Document Server หลายเครื่อง ความแตกต่างที่สำคัญคือการกำหนดเส้นทางตามเอกสารแต่ละฉบับ ดังนั้นควรสร้าง proxy โดยคำนึงถึงข้อกำหนดนั้นก่อน จากนั้นจึงเพิ่มการตรวจสอบสถานะ การใช้งาน HTTPS และการปรับแต่งเวลาหมดอายุเข้าไป