วิธีการตั้งค่า Collabora CODE บน Kubernetes ด้วย Helm

หน้า Collabora Online อาจว่างเปล่าหรือแจ้งว่าเซิร์ฟเวอร์สำนักงานไม่พร้อมใช้งาน แม้ว่าพอด CODE จะทำงานอยู่แล้วก็ตาม พอดที่ทำงานได้อย่างสมบูรณ์เป็นเพียงส่วนหนึ่งของการตั้งค่าเท่านั้น เบราว์เซอร์และแอปพลิเคชัน WOPI ของคุณต้องเข้าถึง Collabora ผ่านชื่อโฮสต์สาธารณะ การตั้งค่า TLS และพร็อกซีต้องตรงกัน และ Collabora ต้องเชื่อถือโฮสต์ WOPI แผนภูมิ Helm อย่างเป็นทางการของ Collabora จะติดตั้งเซิร์ฟเวอร์ลงใน Kubernetes แต่จะไม่ติดตั้งหรือกำหนดค่า Nextcloud, ownCloud หรือโฮสต์ WOPI อื่น ๆ ให้คุณ

คู่มือนี้ใช้ Helm chart ที่ดูแลโดย Collabora พร้อมตัวอย่าง NGINX Ingress โปรดแทนที่โดเมนตัวอย่างด้วยโดเมนของคุณเอง CODE คือ Collabora Online Development Edition ซึ่งมีไว้สำหรับการประเมินผล การใช้งานในบ้าน และทีมขนาดเล็ก Collabora ระบุว่าไม่แนะนำให้ใช้ในสภาพแวดล้อมการผลิตที่ต้องการเวอร์ชันที่เสถียรและได้รับการสนับสนุน สำหรับงานในระดับการผลิต โปรดประเมินข้อเสนอ Collabora Online ที่ได้รับการสนับสนุน รวมถึงข้อกำหนดด้านใบอนุญาตและการสนับสนุน

สิ่งที่คุณต้องเตรียมก่อนการติดตั้ง

• คลัสเตอร์ Kubernetes ที่ใช้งานได้kubectlและ Helm 3 ที่สามารถเข้าถึงคลัสเตอร์ได้
• มีการติดตั้ง Ingress controller ในคลัสเตอร์ ตัวอย่างด้านล่างใช้ ingress-nginx; เอกสารของ Collabora ยังกล่าวถึง HAProxy และรองรับการกำหนดค่าการกำหนดเส้นทางอื่นๆ ด้วย
• ชื่อ DNS เช่น ที่office.example.comชี้ไปยังที่อยู่ ingress สาธารณะ พร้อมด้วยใบรับรอง TLS ที่จัดเก็บเป็น Kubernetes Secret ในเนมสเปซ Collabora
• แอปพลิเคชัน WOPI เช่น Nextcloud ที่มี URL เช่นcloud.example.com. Collabora จะต้องสามารถเข้าถึงแอปพลิเคชัน WOPI ได้ และทั้งแอปพลิเคชันและเบราว์เซอร์ของผู้ใช้จะต้องสามารถเข้าถึง Collabora ได้เช่นกัน
• แผน TLS ที่ชัดเจน ตัวอย่างนี้จะยุติ HTTPS ที่ฝั่งขาเข้าและส่งต่อไปยัง HTTP ในบริการ Collabora ภายในคลัสเตอร์

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

ขั้นตอนที่ 1: เพิ่มแผนภูมิอย่างเป็นทางการและเลือกเวอร์ชัน

Collabora เผยแพร่แผนภูมิจากโครงการ CollaboraOnline ปัจจุบันหน้าการเผยแพร่แสดงเวอร์ชันแผนภูมิ 1.3.5 (ตรวจสอบเมื่อวันที่ 6 ตุลาคม 2026) ตรวจสอบเวอร์ชันที่มีอยู่ในสภาพแวดล้อมของคุณและตรึงเวอร์ชันแผนภูมิไว้ เพื่อป้องกันไม่ให้การอัปเดตที่เก็บข้อมูลในภายหลังเปลี่ยนแปลงแผนภูมิที่คุณใช้งานโดยไม่แจ้งให้ทราบล่วงหน้า:

helm repo add collabora https://collaboraonline.github.io/online/
helm repo update
helm search repo collabora/collabora-online --versions

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

helm show values collabora/collabora-online --version 1.3.5

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

ขั้นตอนที่ 2: สร้างเนมสเปซและปกป้องรหัสผ่านผู้ดูแลระบบ

สร้างเนมสเปซและ Kubernetes Secret สำหรับข้อมูลรับรองผู้ดูแลระบบ Collabora ที่เป็นตัวเลือกของชาร์ต แทนที่รหัสผ่านตัวอย่างด้วยรหัสลับที่รัดกุม หรือสร้าง Secret ผ่านตัวจัดการรหัสลับขององค์กรหรือเวิร์กโฟลว์รหัสลับ GitOps อย่าบันทึกรหัสผ่านจริงลงในไฟล์values.yaml.

kubectl create namespace collabora

kubectl -n collabora create secret generic collabora-admin \
  --from-literal=username=admin \
  --from-literal=password='REPLACE_WITH_A_LONG_RANDOM_PASSWORD'

แผนภูมิรองรับการอ้างอิง Secret ที่มีอยู่แล้ว การเปิดใช้งานฟังก์ชันนี้จะช่วยหลีกเลี่ยงการใส่รหัสผ่านผู้ดูแลระบบลงในไฟล์ค่า Helm โดยตรง ควรจำกัดการใช้งาน Secret ไว้เฉพาะในเนมสเปซและผู้ใช้หรือบัญชีบริการที่ดูแลการปรับใช้ครั้งนี้เท่านั้น

ขั้นตอนที่ 3: กำหนดค่าชื่อโฮสต์ โฮสต์ WOPI และอินเกรส

สร้างไฟล์ชื่อcollabora-values.yaml. ตัวอย่างนี้สมมติว่าใช้ ingress-nginx, TLS Secret ชื่อoffice-example-com-tlsและ Nextcloud ที่https://cloud.example.comกลุ่มนามแฝงต้องระบุชื่อโฮสต์แอปพลิเคชัน WOPI ที่ Collabora ได้รับอนุญาตให้ติดต่อ ไม่ใช่ชื่อโฮสต์สาธารณะของ Collabora

replicaCount: 1

autoscaling:
  enabled: false

ingress:
  enabled: true
  className: nginx
  annotations:
    nginx.ingress.kubernetes.io/proxy-body-size: "0"
    nginx.ingress.kubernetes.io/proxy-read-timeout: "600"
    nginx.ingress.kubernetes.io/proxy-send-timeout: "600"
  hosts:
    - host: office.example.com
      paths:
        - path: /
          pathType: ImplementationSpecific
  tls:
    - secretName: office-example-com-tls
      hosts:
        - office.example.com

collabora:
  aliasgroups:
    - host: "https://cloud.example.com:443"
  extra_params: "--o:ssl.enable=false --o:ssl.termination=true"
  existingSecret:
    enabled: true
    secretName: collabora-admin

ตัวอย่างที่แสดงในแผนภูมิใช้aliasgroupsเพื่ออนุญาตโฮสต์ WOPI และพารามิเตอร์ SSL เหล่านี้เมื่อพร็อกซีแบบย้อนกลับยุติ TLS ในการจัดเรียงนี้ การรับส่งข้อมูลภายนอกจะoffice.example.comใช้ HTTPS ในขณะที่ขาเข้าจะส่งต่อการรับส่งข้อมูลไปยัง Collabora ผ่าน HTTP ภายในคลัสเตอร์ หากขาเข้าของคุณใช้ TLS passthrough หรือโปรโตคอลภายในอื่น อย่าคัดลอกแฟล็ก SSL เหล่านี้โดยไม่ปรับค่า ให้ปรับค่าเหล่านั้นให้ตรงกับเส้นทาง TLS จริงและค่าปัจจุบันของแผนภูมิ

ตรวจสอบให้แน่ใจว่า TLS Secret มีอยู่ในcollaboraเนมสเปซ หากคุณใช้ตัวควบคุมการเข้าถึง (ingress controller) อื่น ให้แทนที่คลาสและคำอธิบายประกอบด้วยค่าที่เทียบเท่าตามเอกสารของตัวควบคุมนั้น เปิดใช้งานการรับส่งข้อมูล WebSocket และอนุญาตการเชื่อมต่อที่มีอายุการใช้งานยาวนาน ค่าเริ่มต้นของตัวควบคุมแต่ละตัวอาจแตกต่างกันไป

ขั้นตอนที่ 4: แสดงผลและติดตั้งแผนภูมิ

ก่อนอื่นให้แสดงไฟล์ manifest เพื่อตรวจจับข้อผิดพลาดของ YAML และตรวจสอบการตั้งค่า Ingress, Service และ workload ที่สร้างขึ้น จากนั้นจึงติดตั้ง chart เวอร์ชันที่กำหนดไว้:

helm template collabora-online collabora/collabora-online \
  --namespace collabora \
  --version 1.3.5 \
  --values collabora-values.yaml

helm upgrade --install collabora-online collabora/collabora-online \
  --namespace collabora \
  --version 1.3.5 \
  --values collabora-values.yaml

ติดตามชมแหล่งข้อมูลต่างๆ เมื่อมีการเริ่มใช้งาน:

kubectl get pods,services,ingress -n collabora
kubectl get events -n collabora --sort-by=.lastTimestamp

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

ขั้นตอนที่ 5: เชื่อมต่อ Nextcloud หรือโฮสต์ WOPI อื่นๆ

เปิดการตั้งค่า Office หรือ Collabora ของแอปพลิเคชัน WOPI ของคุณ แล้วป้อน URL ของบริการภายนอกhttps://office.example.comใน Nextcloud คู่มือการดูแลระบบจะอธิบายวิธีการตั้งค่า URL ของเซิร์ฟเวอร์ Collabora Online ในการตั้งค่าการดูแลระบบ Office นอกจากนี้ ให้ตรวจสอบรายการอนุญาตคำขอ WOPI ของ Nextcloud หากการตั้งค่าของคุณจำกัดโฮสต์ที่สามารถเชื่อมต่อได้ ที่อยู่ดังกล่าวต้องสามารถเข้าถึงได้ทั้งจากเบราว์เซอร์ของผู้ใช้ปลายทางและจากเซิร์ฟเวอร์แอปพลิเคชันที่ทำการร้องขอ WOPI

หากการเชื่อมต่อล้มเหลวโดยมีข้อความว่า “โฮสต์ WOPI ไม่ได้รับอนุญาต” หรือข้อความที่คล้ายกัน ให้เปรียบเทียบ URL ของโฮสต์ WOPI จริงกับcollabora.aliasgroupsตรวจสอบรูปแบบ ชื่อโฮสต์ และพอร์ต และเพิ่มชื่อโฮสต์ทางเลือกที่ถูกต้องโดยเจตนา หลีกเลี่ยงการใช้รูปแบบโฮสต์แบบกว้างๆ เว้นแต่คุณจะเข้าใจผลกระทบของมัน หากคุณใช้แอปพลิเคชัน WOPI มากกว่าหนึ่งรายการ ให้ปฏิบัติตามโครงสร้างกลุ่มนามแฝงที่ระบุไว้ในแผนภูมิสำหรับแต่ละโฮสต์ แทนที่จะอนุญาตทุกโดเมน

เมื่อไหร่จึงควรขยายระบบให้มากกว่าหนึ่งพอด?

สำหรับการทดลองขนาดเล็ก การใช้สำเนาเดียวโดยปิดใช้งานการปรับขนาดอัตโนมัติจะช่วยลดความซับซ้อนของการกำหนดเส้นทาง สำหรับสำเนาหลายชุด เอกสาร README ของ Collabora chart จะแสดงความสัมพันธ์ของ NGINX โดยอิงตามอาร์กิวเมนต์WOPISrcการสืบค้น เพิ่มคำอธิบายประกอบที่ระบุไว้ในเอกสารลงใน ingress เมื่อใช้ ingress-nginx:

nginx.ingress.kubernetes.io/upstream-hash-by: "$arg_WOPISrc"

การตั้งค่านี้จะส่งคำขอเอกสารเดียวกันไปยังพอดแบ็กเอนด์เดียวกัน ซึ่งมีความสำคัญสำหรับการแก้ไขร่วมกันและการร้องขอคลิปบอร์ด ตรวจสอบเอกสารประกอบสำหรับเวอร์ชัน ingress-controller ของคุณอย่างถูกต้อง คำอธิบายประกอบที่รองรับโดย ingress-nginx อาจไม่ถูกต้องโดยอัตโนมัติสำหรับ HAProxy, Traefik หรือการใช้งาน Gateway API หลังจากเปิดใช้งานการจำลองเพิ่มเติมหรือการปรับขนาดอัตโนมัติแล้ว ให้ทดสอบการแก้ไขเอกสารเดียวกันพร้อมกัน และตรวจสอบบันทึก Collabora และบันทึกการเข้าถึง ingress การกำหนดขนาดทรัพยากร พฤติกรรมเซสชัน และความพร้อมใช้งานสูงจำเป็นต้องมีการตรวจสอบเฉพาะสำหรับภาระงาน

ตรวจสอบการติดตั้งจากภายนอก

1. ยืนยันว่า Kubernetes รายงานสถานะ Pod เป็น Ready และ Service กับ Ingress มีอยู่จริง: kubectl get pods,svc,ingress -n collabora.
2. ตรวจสอบเอนด์พอยต์การค้นหาสาธารณะ ควรส่งคืนข้อมูล XML แทนที่จะเป็นข้อผิดพลาดของเบราว์เซอร์หรือพร็อกซี:

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

3. เปิดแอปพลิเคชัน WOPI และแก้ไขเอกสารทดสอบ ตรวจสอบว่าโปรแกรมแก้ไขโหลดขึ้นมา การเปลี่ยนแปลงถูกบันทึก และเมื่อเปิดเอกสารอีกครั้ง เนื้อหาที่บันทึกไว้ก็จะปรากฏขึ้น
4. หากใช้สำเนาหลายชุด ให้เปิดเอกสารเดียวกันในสองเซสชัน และตรวจสอบให้แน่ใจว่าทั้งสองเซสชันสามารถทำงานร่วมกันได้โดยไม่ต้องเชื่อมต่อใหม่ซ้ำๆ วิธีนี้ช่วยระบุความสัมพันธ์ของเซสชันที่ขาดหายไปได้
5. ตรวจสอบบันทึกข้อผิดพลาดเพื่อหาข้อผิดพลาดเกี่ยวกับ TLS, การอนุญาต WOPI หรือข้อผิดพลาดจากต้นทาง:

   kubectl logs -n collabora deploy/collabora-online --tail=100

   หากแผนภูมิสร้างเวิร์กโหลดที่มีชื่อแตกต่างกัน ให้ใช้kubectl get deployments -n collaboraและแทนที่ด้วยชื่อจริง

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

จุดบกพร่องที่พบได้ทั่วไป

• หาก Ingress ส่งคืนรหัส 404 หรือ 502:ตรวจสอบ DNS, คลาส Ingress, รหัสลับ TLS และปลายทางบริการ ยืนยันว่า Ingress สามารถเข้าถึงบริการ Collabora บนพอร์ตบริการของชาร์ตได้
• การค้นหาทำงานได้ แต่หน้าแก้ไขข้อความยังว่างเปล่า:ตรวจสอบข้อผิดพลาดในคอนโซลของเบราว์เซอร์และบันทึกพร็อกซี ตรวจสอบการตั้งค่าการยุติ HTTPS การจัดการเว็บซ็อกเก็ต และการหมดเวลาของคำขอที่นานเกินไป
• โฮสต์ WOPI ที่ไม่ได้รับอนุญาต:อนุญาตให้แอปพลิเคชัน WOPI เข้าถึงจากแหล่งกำเนิดภายในaliasgroups; ห้ามแทนที่ด้วยชื่อโฮสต์ของเซิร์ฟเวอร์สำนักงาน
• หาก Pod รีสตาร์ทหรือถูกขับไล่ออก ให้ตรวจสอบkubectl describe podบันทึกของคอนเทนเนอร์ จากนั้นตั้งค่าการร้องขอทรัพยากรและขีดจำกัดที่เหมาะสมสำหรับคลัสเตอร์ที่มีอยู่
• การแก้ไขจะไม่เสถียรหลังจากเพิ่มสำเนา:ตรวจสอบความสัมพันธ์ตาม WOPISrc และยืนยันว่าคอนโทรลเลอร์รักษาอาร์กิวเมนต์การค้นหาไว้เมื่อกำหนดเส้นทางการร้องขอ

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

เอกสารอ้างอิงอย่างเป็นทางการ

• แผนภูมิ Helm และคู่มือการใช้งาน Kubernetes ที่ดูแลโดย Collabora
• ค่าแผนภูมิ Helm ของ Collabora
• การเผยแพร่ชาร์ต Collabora
• คำแนะนำสำหรับ Collabora Online Development Edition (CODE)
• คู่มือการตั้งค่า Nextcloud Office
• เอกสารประกอบคำอธิบายประกอบ ingress-nginx
• คู่มือคำสั่งติดตั้ง Helm