วิธีแก้ไขข้อผิดพลาดในบันทึกการเชื่อมต่อ Collabora Online ด้วยระดับบันทึก coolwsd

เทมเพลตการกำหนดค่าสาธารณะปัจจุบันของ Collabora Online ยังคงแสดงค่าlogging.levelในcoolwsd.xml<log_name> โดยมีค่าที่รองรับตั้งแต่ <log_name> ถึง warning<log_name> debugและtrace<log_name> หากการเชื่อมต่อล้มเหลว ให้เพิ่มระดับ <log_name> ชั่วครู่ ทำซ้ำการเชื่อมต่อที่ล้มเหลวหนึ่งครั้ง ตรวจสอบปลายทางบันทึกจริงของบริการ และคืนค่าระดับปกติเมื่อเสร็จสิ้น ค่าที่แสดงใน XML ไม่ใช่ค่าที่มีผลเสมอไป คำสั่งเริ่มต้นหรือการตั้งค่าคอนเทนเนอร์อาจแทนที่ค่านี้ได้ และส่วนที่มีรายละเอียดสูง เช่น การบันทึก WebSocket อาจถูกปิดใช้งานแยกต่างหาก

คู่มือนี้เน้นการวินิจฉัยปัญหาการเชื่อมต่อระหว่างเบราว์เซอร์กับ Collabora หรือปัญหาการเปิดเอกสาร โดยใช้coolwsd.xml.inเทมเพลตซอร์สโค้ดสาธารณะปัจจุบันและเอกสารอย่างเป็นทางการของ Collabora ที่ตรวจสอบเมื่อวันที่ 6 ตุลาคม 2026 ค่าเริ่มต้นของแพ็กเกจและชื่อบริการอาจแตกต่างกันไปตามรุ่นและการใช้งาน ดังนั้นโปรดตรวจสอบอินสแตนซ์ที่ใช้งานอยู่ของคุณก่อนคัดลอกเส้นทางหรือคำสั่งรีสตาร์ท

การเปลี่ยนแปลงระดับการบันทึกข้อมูลของ coolwsd

coolwsdคือ Collabora Online WebSocket Daemon ซึ่งเป็นกระบวนการเซิร์ฟเวอร์ที่จัดการเซสชันของเบราว์เซอร์และกิจกรรมของเอกสาร ระดับการบันทึกของมันจะกำหนดว่ากระบวนการนั้นจะแสดงรายละเอียดมากน้อยเพียงใด เทมเพลตซอร์สโค้ดปัจจุบันแสดงรายการระดับที่มีชื่อ ได้แก่fatal, critical, error, warning, notice, information, debug, และ รวม traceถึงระดับตัวเลข 0–8 ค่าตัวเลขจะเรียงลำดับจากน้อยที่สุดไปมากที่สุด สำหรับการวินิจฉัยเบื้องต้น ระดับdebugเป็นขั้นตอนที่เหมาะสม ควรใช้traceเฉพาะเมื่อคุณต้องการรายละเอียดการเชื่อมต่อที่ละเอียดกว่านี้

การตั้งค่า แยกต่างหากlevel_startupจะควบคุมการบันทึกข้อมูลระหว่างการเริ่มต้นระบบครั้งแรก จากนั้นการบันทึกข้อมูลจะกลับไปสู่ระดับปกติlevelเทมเพลตปัจจุบันตั้งค่าการบันทึกข้อมูลเมื่อเริ่มต้นระบบเป็นtrace; ซึ่งไม่ได้หมายความว่าการทำงานปกติจะยังคงอยู่ที่ระดับการติดตาม (trace) หลีกเลี่ยงการเปลี่ยนแปลงการตั้งค่านี้level_startupเมื่อเกิดปัญหาหลังจากที่บริการทำงานอยู่แล้ว

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

ขั้นตอนที่ 1: ระบุวิธีการทำงานของอินสแตนซ์ Collabora นี้

ขั้นแรก ให้ตรวจสอบว่า Collabora Online ทำงานเป็นบริการระบบ ใน Docker หรือ Podman หรือใน Kubernetes สิ่งนี้สำคัญเพราะการเปลี่ยนแปลงไฟล์ภายในคอนเทนเนอร์ที่กำลังทำงานอยู่อาจไม่คงอยู่ และบันทึกของคอนเทนเนอร์อาจแสดงออกทางเอาต์พุตมาตรฐานแทนที่จะบันทึกเป็นไฟล์

• แพ็คเกจระบบ:ตรวจสอบบริการที่กำลังทำงานอยู่และชื่อหน่วย ซึ่งโดยทั่วไปคือcoolwsd. การกำหนดค่าโดยทั่วไปคือ/etc/coolwsd/coolwsd.xml. เวอร์ชันเก่าอาจใช้loolwsdเส้นทาง แบบเดิม
• Docker หรือ Podman:ระบุชื่อคอนเทนเนอร์และวิธีการกำหนดค่า โดยปกติแล้วไฟล์ที่เชื่อมต่อผ่าน bind-mount หรือตัวแปรการปรับใช้เป็นแหล่งข้อมูลการกำหนดค่าถาวร
• Kubernetes:ตรวจสอบค่า Helm, ConfigMap หรือไฟล์ manifest ของ deployment ที่ให้มาcoolwsd.xmlการแก้ไข pod โดยตรงเป็นการแก้ไขชั่วคราวเท่านั้น

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

ขั้นตอนที่ 2: เพิ่มระดับการทำงานชั่วคราว

ในส่วนที่ใช้งานcoolwsd.xmlอยู่ ให้ค้นหา<logging>ส่วนนั้นและเปลี่ยนเฉพาะค่าภายใน<level>เริ่มต้นด้วยdebugหากการพยายามเชื่อมต่อยังคงไม่ให้รายละเอียดที่เพียงพอ ให้ใช้traceเพื่อจำลองสถานการณ์หนึ่งครั้งโดยย่อ เก็บlevel_startupการตั้งค่าไฟล์และการกำหนดค่าที่ไม่เกี่ยวข้องที่มีอยู่ไว้เหมือนเดิม

<config>
  <logging>
    <level>trace</level>
    <level_startup>trace</level_startup>
  </logging>
</config>

นี่เป็นตัวอย่างย่อของโครงสร้าง XML ที่เกี่ยวข้อง ไม่ใช่สิ่งที่จะมาแทนที่ไฟล์การกำหนดค่าฉบับเต็ม สำหรับการใช้งานคอนเทนเนอร์ ให้ตั้งค่าตัวเลือกผ่านกลไกการคงอยู่ของข้อมูลที่รองรับโดยอิมเมจหรือชาร์ตนั้น ซอร์สโค้ดอย่างเป็นทางการของ Collabora มีการกำหนดค่าแบบบรรทัดคำสั่ง ดังนั้นหากค่าปรากฏว่าถูกละเลย ให้ตรวจสอบอาร์กิวเมนต์เริ่มต้นหรือพารามิเตอร์การปรับใช้เพื่อหาlogging.levelค่า ที่สอง

หากบันทึกข้อมูลไปยังไฟล์ เทมเพลตซอร์สโค้ดปัจจุบันจะระบุเส้นทางไฟล์ไว้ภายใต้ <filename> logging.fileซึ่งโดยทั่วไปคือ/var/log/coolwsd.log<filename> อย่างไรก็ตาม การบันทึกข้อมูลลงไฟล์อาจถูกปิดใช้งานในเวอร์ชันใช้งานจริง หากคุณเปิดใช้งานการส่งออกไฟล์หรือใช้เส้นทางที่กำหนดเอง โปรดตรวจสอบให้แน่ใจว่าcoolบัญชีบริการสามารถเขียนลงในไฟล์นั้นได้ และ systemd อนุญาตให้บริการเขียนไปยังตำแหน่งนั้นได้ อย่าทำให้ไฟล์บันทึกสามารถอ่านได้โดยทุกคนเพื่อแก้ปัญหาเรื่องสิทธิ์การเข้าถึง

ขั้นตอนที่ 3: รีสตาร์ทหรือปรับใช้ใหม่ จากนั้นลองทำซ้ำอีกครั้ง

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

sudo systemctl restart coolwsd
sudo systemctl status coolwsd --no-pager

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

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

ขั้นตอนที่ 4: อ่านซอร์สโค้ดบันทึกการปรับใช้ของคุณ

สำหรับบริการ systemd ให้ทำตามขั้นตอนในบันทึกขณะจำลองปัญหา:

sudo journalctl -u coolwsd -f

ในการตรวจสอบหน้าต่างล่าสุดที่มีขอบเขต ให้ใช้ คำสั่ง sudo journalctl -u coolwsd --since "10 minutes ago"`log` หากหน่วยของคุณมีชื่ออื่น ให้แทนที่ด้วยชื่อนั้น สำหรับ Docker ให้ใช้ คำสั่ง `log` docker logs --since 10m --follow CONTAINER_NAMEและแทนที่CONTAINER_NAMEด้วยชื่อหรือ ID ของคอนเทนเนอร์จริง Podman และ Kubernetes มีคำสั่งบันทึกของตัวเอง ตรวจสอบเอกสารประกอบการทำงานของการปรับใช้แทนที่จะสันนิษฐานว่ามีไฟล์ host อยู่

หากเปิดใช้งานการบันทึกไฟล์ ให้ตรวจสอบเส้นทางที่กำหนดค่าไว้ เช่นsudo tail -F /var/log/coolwsd.logเส้นทางในไฟล์ของคุณอาจแตกต่างออกไป การที่ไฟล์หายไปไม่ได้หมายความว่าบริการไม่ได้สร้างบันทึกใดๆ เลย อาจเป็นการเขียนไปยังบันทึกประจำวันหรือเอาต์พุตของคอนเทนเนอร์แทนก็ได้

ขั้นตอนที่ 5: เชื่อมโยงลำดับการเชื่อมต่อ

เริ่มต้นด้วยรายการตามเวลาที่บันทึกไว้ ค้นหาเครื่องหมายเตือนและข้อผิดพลาด รวมถึงคำที่เกี่ยวข้องกับการเชื่อมต่อ เช่นWOPI, WebSocket, Socket, หรือเส้นทางการร้องขอที่เกี่ยวข้อง ในไฟล์ ตัวกรองแรกที่เน้นเฉพาะเจาะจงอาจเป็น:

grep -Ei 'ERR|WRN|WOPI|WebSocket' /var/log/coolwsd.log

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

เทมเพลตการกำหนดค่าปัจจุบันแสดงรายการSocket, WebSocket, Admin, และPixelไว้ในค่าเริ่มต้นdisabled_areasสำหรับการแสดงผลที่มีรายละเอียดสูง หากเปิดใช้งานการบันทึกการติดตาม แต่ไม่มีรายละเอียดซ็อกเก็ต ให้ตรวจสอบการตั้งค่านี้ สำหรับการวินิจฉัยแบบสั้น ให้ลบเฉพาะส่วนที่เกี่ยวข้องSocketหรือWebSocketส่วนที่เกี่ยวข้องออกจากรายการที่ปิดใช้งานซึ่งคั่นด้วยเครื่องหมายจุลภาค โดยคงการยกเว้นที่ไม่เกี่ยวข้องไว้ เริ่มใหม่หรือปรับใช้ใหม่ และทำการทดสอบที่ควบคุมซ้ำอีกครั้ง คืนค่ารายการเดิมหลังจากรวบรวมหลักฐานแล้ว

ขั้นตอนที่ 6: คืนค่าการบันทึกข้อมูลตามปกติและปกป้องหลักฐาน

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

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

ข้อผิดพลาดทั่วไปในการดีบัก

• การเปลี่ยนแปลงเพียงอย่างเดียวlevel_startup:การตั้งค่านี้จะมีผลเฉพาะในช่วงเริ่มต้นการทำงานเท่านั้น จากนั้นจะกลับไปใช้ค่าเริ่มต้นlevelหากเกิดความล้มเหลวหลังจากเริ่มต้นการทำงาน ให้เปลี่ยนlevelค่า
• สมมติว่าtraceเปิดใช้งานทุกหมวดหมู่:พื้นที่ที่ปิดใช้งานสามารถระงับข้อความซ็อกเก็ตหรือ WebSocket ที่มีรายละเอียดสูงได้ ตรวจสอบรายการตัวกรอง
• การค้นหาผิดที่:บันทึกเหตุการณ์ (journal), เอาต์พุตของคอนเทนเนอร์ (container output) และไฟล์ เป็นแหล่งข้อมูลบันทึกเหตุการณ์ที่แตกต่างกัน ตรวจสอบว่าแหล่งข้อมูลใดกำลังทำงานอยู่ก่อนที่จะแก้ไขปัญหาไฟล์ว่างเปล่า
• เปิดใช้งานการติดตาม:การบันทึกข้อมูลปริมาณมากอาจทำให้ข้อมูลเพิ่มขึ้นอย่างรวดเร็วและเผยรายละเอียดการทำงานมากขึ้น คืนค่ากลับเป็นค่าก่อนหน้าทันทีที่การทดสอบเสร็จสิ้น
• การเปลี่ยนแปลงการตั้งค่าหลายอย่างพร้อมกัน:จะทำให้ระบุได้ยากขึ้นว่าการตั้งค่าใดส่งผลต่อผลลัพธ์ ปรับค่าทีละค่า ทำให้เกิดข้อผิดพลาดหนึ่งครั้ง และบันทึกผลลัพธ์

แหล่งที่มา

• แหล่งที่มาของ Collabora Online: coolwsd.xml.in ตัวเลือกการบันทึกข้อมูล
• แหล่งที่มาของ Collabora Online: ค่าเริ่มต้นการบันทึกข้อมูลในเวอร์ชันใช้งานจริง
• คู่มือ SDK ออนไลน์ของ Collabora, 24.04
• ค่า Helm สำหรับการกำหนดค่าการปรับใช้ Collabora Online