วิธีการตั้งค่า Federation บน Matrix Synapse: คู่มือทีละขั้นตอน

การเชื่อมต่อแบบเมทริกซ์ (Matrix federation) ช่วยให้โฮมเซิร์ฟเวอร์ Synapse สามารถแลกเปลี่ยนข้อมูลเหตุการณ์ในห้องสนทนากับโฮมเซิร์ฟเวอร์อื่นๆ ได้ ทำให้ผู้ที่ใช้เซิร์ฟเวอร์ต่างกันสามารถเข้าร่วมในห้องสนทนาเดียวกันได้ ในการตั้งค่า ให้ทำให้ API การเชื่อมต่อของ Synapse สามารถเข้าถึงได้ผ่าน HTTPS เผยแพร่ข้อมูลการค้นหาเซิร์ฟเวอร์ที่ถูกต้อง อนุญาตการรับส่งข้อมูลเครือข่ายที่จำเป็น และทดสอบปลายทางสาธารณะ การเริ่มต้น Synapse หรือการเปิดพอร์ต 8448 เพียงอย่างเดียวไม่เพียงพอ หาก DNS, TLS หรือการกำหนดเส้นทางพร็อกซีไม่ถูกต้อง

คู่มือนี้ใช้การติดตั้งพร็อกซีแบบย้อนกลับทั่วไป: โดเมนประจำตัวของ Matrix คือexample.org, Synapse ทำงานที่matrix.example.org, และพร็อกซีจัดการ TLS บนพอร์ต 443 แทนที่โดเมนตัวอย่างทั้งสองด้วยโดเมนของคุณเอง หาก Synapse สามารถเข้าถึงได้ผ่าน HTTPS อยู่แล้วที่example.org:8448, โดยปกติคุณไม่จำเป็นต้องมีการมอบหมายสิทธิ์ คำสั่งและเส้นทางไฟล์จะขึ้นอยู่กับว่าคุณติดตั้ง Synapse จากแพ็กเกจ สภาพแวดล้อมเสมือน หรือคอนเทนเนอร์

อะไรบ้างที่ต้องเป็นจริงก่อนที่ระบบสหพันธรัฐจะทำงานได้?

• เซิร์ฟเวอร์ Synapse ของคุณมีโฮสต์สาธารณะที่เสถียรserver_nameชื่อนี้จะปรากฏใน Matrix ID เช่น@alex:example.org; การเปลี่ยนชื่อนี้ในภายหลังไม่ใช่การแก้ไขโฮสต์เนมทั่วไป
• โฮมเซิร์ฟเวอร์อื่นๆ สามารถเข้าถึง API ของสหพันธ์ผ่าน HTTPS และตรวจสอบความถูกต้องของใบรับรอง TLS ได้
• การค้นหาเซิร์ฟเวอร์จะนำโฮมเซิร์ฟเวอร์ระยะไกลไปยังโฮสต์และพอร์ตที่ถูกต้อง พอร์ตการเชื่อมต่อมาตรฐานคือ 8448 ส่วนการมอบหมายสามารถชี้ไปยัง HTTPS บนพอร์ต 443 ได้
• กฎไฟร์วอลล์จะอนุญาตการรับส่งข้อมูลขาเข้าที่ปลายทางของเฟเดอเรชันที่คุณเลือก และการเชื่อมต่อเฟเดอเรชันขาออก

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

ขั้นตอนที่ 1: ตรวจสอบชื่อเซิร์ฟเวอร์ Synapse และการติดตั้งใช้งาน

เปิดโดเมนที่ใช้งานอยู่homeserver.yamlและยืนยันว่าserver_nameเป็นโดเมนที่คุณต้องการใช้งานต่อไป โดยทั่วไปจะมีรูปแบบดังนี้:

server_name: "example.org"
public_baseurl: "https://matrix.example.org/"

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

ตรวจสอบวิธีการติดตั้งและจัดการ Synapse บริการ systemd, Docker Compose, การใช้งาน Kubernetes และผลิตภัณฑ์โฮสติ้งแบบจัดการ มีขั้นตอนการรีสตาร์ทและการเชื่อมต่อเครือข่ายที่แตกต่างกัน นำตัวอย่างด้านล่างไปใช้กับไฟล์การกำหนดค่าที่ถูกต้อง และรักษารายการฟัง (listener) และการตั้งค่าแบบกำหนดเองที่มีอยู่ทั้งหมด

ขั้นตอนที่ 2: เลือกการเชื่อมต่อโดยตรงผ่านพอร์ต 8448 หรือการมอบหมายสิทธิ์ผ่านพอร์ต 443

โดยทั่วไปแล้ว การเข้าร่วมสหพันธ์มี 2 ช่องทางหลัก:

• ใช้พอร์ตเริ่มต้น 8448:ชี้ DNS ของserver_nameโดเมนไปยังเซิร์ฟเวอร์ เปิดเผย HTTPS บนพอร์ต 8448 และแสดงใบรับรองที่ถูกต้องสำหรับโดเมนนั้น หาก API สามารถใช้งานได้ที่โดเมนที่ระบุserver_nameบนพอร์ต 8448 เอกสารของ Synapse ระบุว่าไม่จำเป็นต้องมีการมอบหมายสิทธิ์
• ใช้พอร์ต 443 ร่วมกับการมอบหมายสิทธิ์:ให้บริการhttps://example.org/.well-known/matrix/serverด้วย JSON โดยกำหนดให้เซิร์ฟเวอร์อื่นชี้ไปยังปลายทางจริง ตัวอย่างเช่น{"m.server":"matrix.example.org:443"}ชื่อโฮสต์ที่มอบหมายสิทธิ์จะต้องสามารถระบุได้ในที่สาธารณะและต้องมีใบรับรองที่ถูกต้องmatrix.example.orgสำหรับ

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

ขั้นตอนที่ 3: กำหนดเส้นทาง API ของ Synapse Federation ผ่านทาง Reverse Proxy

โดยทั่วไป Synapse จะรับฟังการเชื่อมต่อผ่านพอร์ต HTTP 8008 โดยอยู่เบื้องหลังพร็อกซีแบบย้อนกลับ พร็อกซีจะยุติการเชื่อมต่อ HTTPS และส่งต่อปลายทางของ Matrix ไปยัง Synapse ในhomeserver.yamlตัวรับฟังที่เกี่ยวข้อง โปรดตรวจสอบให้แน่ใจว่าตัวรับฟัง HTTP นั้นรวมทั้งทรัพยากรไคลเอ็นต์และเฟเดอเรชัน และเชื่อถือส่วนหัวของพร็อกซี:

listeners:
  - port: 8008
    type: http
    tls: false
    x_forwarded: true
    bind_addresses: ['127.0.0.1']
    resources:
      - names: [client, federation]

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

กำหนดค่าพร็อกซีเพื่อส่งต่อคำขอสำหรับ/_matrixและ/_synapse/clientไปยังพอร์ต 8008 โดยตั้งค่าX-Forwarded-ForและX-Forwarded-Protoสำหรับ NGINX ตำแหน่งที่สำคัญอาจมีลักษณะดังนี้:

location ~ ^(/_matrix|/_synapse/client) {
    proxy_pass http://127.0.0.1:8008;
    proxy_set_header X-Forwarded-For $remote_addr;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header Host $host;
}

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

ขั้นตอนที่ 4: กำหนดค่า TLS และ DNS

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

สร้างเรคอร์ด A สาธารณะ และหากคุณใช้ IPv6 ให้สร้างเรคอร์ด AAAA เพื่อmatrix.example.orgชี้ไปยังพร็อกซี ตรวจสอบให้แน่ใจว่าเรคอร์ดทั้งสองชี้ไปยังบริการที่ต้องการ เรคอร์ด AAAA ที่ไม่ถูกต้องอาจทำให้เกิดความล้มเหลวสำหรับเซิร์ฟเวอร์ระยะไกลที่รองรับ IPv6 แม้ว่า IPv4 จะใช้งานได้ก็ตาม หากคุณใช้พอร์ต 8448 โดยตรง DNS example.orgต้องชี้ไปยังตัวรับฟัง และใบรับรองต้องexample.orgตรงกัน

ขั้นตอนที่ 5: เผยแพร่ข้อมูลการค้นหาเซิร์ฟเวอร์

สำหรับตัวอย่างการมอบหมายสิทธิ์ ให้ตั้งค่า URL HTTPS ด้านล่างให้ส่งคืนสถานะ 200 และข้อมูล JSON ที่มีปลายทางที่แน่นอน:

https://example.org/.well-known/matrix/server

{
  "m.server": "matrix.example.org:443"
}

เผยแพร่ไฟล์ ดังกล่าวในรูปแบบapplication/json. ตรวจสอบให้แน่ใจว่าสามารถอ่านได้จากภายนอกโดยไม่ต้องล็อกอิน ไม่เกิดการวนลูป และชื่อโฮสต์และพอร์ตตรงกับพร็อกซี TLS matrix.example.orgหากพร็อกซีส่งต่อการเชื่อมต่อแบบเฟเดอเรชันไปยังที่อื่น ไม่ควรเผยแพร่ไฟล์ดังกล่าว

Synapse สามารถให้บริการไฟล์นี้ได้เองserve_server_wellknown: trueเฉพาะเมื่อhttps://<server_name>/มีการส่งคำขอไปยัง Synapse อย่างเหมาะสมเท่านั้น หากชื่อเซิร์ฟเวอร์ของคุณคือexample.orgแต่ Synapse โฮสต์อยู่ที่matrix.example.orgเซิร์ฟเวอร์เว็บแบบคงที่หรือพร็อกซีแบบย้อนกลับบนexample.orgมักจะเป็นสถานที่ที่เหมาะสมกว่าในการให้บริการการตอบสนองการมอบหมาย

ความสับสนที่พบบ่อยคือการใช้คำ ว่า "ไฟล์เซิร์ฟเวอร์" /.well-known/matrix/clientและ/.well-known/matrix/server"ไฟล์ไคลเอ็นต์" แทนกันได้ ไฟล์เซิร์ฟเวอร์ช่วยให้โฮมเซิร์ฟเวอร์อื่นๆ ค้นพบการเชื่อมต่อแบบเฟเดอเรชันที่เข้ามา ส่วนไฟล์ไคลเอ็นต์จะประกาศ URL ของโฮมเซิร์ฟเวอร์ที่ไคลเอ็นต์มองเห็นได้ และเป็นตัวเลือกเสริมสำหรับการเชื่อมต่อแบบเฟเดอเรชัน ตั้งค่าแยกต่างหากเฉพาะเมื่อคุณต้องการให้ไคลเอ็นต์ที่เข้ากันได้ค้นพบ URL ไคลเอ็นต์จาก Matrix ID ของผู้ใช้

ขั้นตอนที่ 6: เปิดเส้นทางไฟร์วอลล์ที่จำเป็น

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

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

ขั้นตอนที่ 7: เริ่มระบบใหม่อย่างปลอดภัยและตรวจสอบปลายทางสาธารณะ

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

curl -i https://example.org/.well-known/matrix/server
curl -i https://matrix.example.org/_matrix/federation/v1/version

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

ถัดไป ป้อน Matrix ของคุณserver_name(ตัวอย่างเช่นexample.orgไม่จำเป็นต้องเป็นชื่อโฮสต์พร็อกซี) ในMatrix Federation Testerแก้ไขข้อผิดพลาด DNS, การมอบหมายสิทธิ์, ใบรับรอง หรือปลายทางที่รายงาน และเรียกใช้การทดสอบอีกครั้ง สุดท้าย เชิญผู้ใช้บนโฮมเซิร์ฟเวอร์อื่นไปยังห้องทดสอบ หรือเข้าร่วมห้องที่โฮสต์อยู่ที่อื่น ผลลัพธ์การทดสอบที่ประสบความสำเร็จเป็นการตรวจสอบการเชื่อมต่อสาธารณะที่มีประโยชน์ แต่ไม่ได้รับประกันว่าเซิร์ฟเวอร์ระยะไกล นโยบายห้อง ไฟร์วอลล์ หรือการกำหนดค่าไคลเอ็นต์ทุกอย่างจะทำงานเหมือนกันทุกประการ

ความเข้าใจผิดที่นำไปสู่การตั้งค่าที่ผิดพลาดหรือไม่คาดคิด

• “ฉันต้องเปิดพอร์ต 8448 เสมอ”ไม่ใช่ ค่าเริ่มต้นคือ 8448 แต่การมอบหมายเซิร์ฟเวอร์สามารถกำหนดให้การเชื่อมต่อแบบเฟเดอเรชันขาเข้าไปที่พอร์ต 443 ได้ เปิดพอร์ตที่เส้นทางการค้นหาที่เผยแพร่ของคุณใช้งานจริง
• “ไฟล์ปลายทางที่รู้จักกันดีของไคลเอ็นต์ช่วยให้เกิดการเชื่อมต่อแบบเฟเดอเรชัน”ไม่ใช่เช่นนั้น การค้นหาการเชื่อมต่อแบบเฟเดอเรชันใช้ปลายทางที่รู้จักกันดีของเซิร์ฟเวอร์หรือการสำรองข้อมูล DNS ที่รองรับ ส่วนปลายทางของไคลเอ็นต์นั้นมีจุดประสงค์ที่แตกต่างออกไป
• “การใช้ Federation ทำให้ห้องสนทนาในพื้นที่ทั้งหมดเป็นสาธารณะ”ไม่ใช่ Federation ช่วยให้การสื่อสารระหว่างเซิร์ฟเวอร์เป็นไปได้ การมองเห็นห้องและการเป็นสมาชิกยังคงเป็นตัวกำหนดการเข้าร่วม ลองเชิญบัญชีจากระยะไกลเข้าร่วมห้องทดสอบเพื่อยืนยันกรณีการใช้งานที่คุณต้องการ
• “การตรวจสอบสุขภาพเครือข่ายภายในที่แสดงผลสีเขียวแสดงว่าการเชื่อมต่อเครือข่ายสมบูรณ์แล้ว”ไม่ใช่ การตรวจสอบภายในไม่ได้ทดสอบ DNS สาธารณะ การตรวจสอบ TLS ภายนอก NAT กฎไฟร์วอลล์บนคลาวด์ หรือการกำหนดเส้นทางพร็อกซี ควรทดสอบจากภายนอกและใช้เครื่องมือทดสอบการเชื่อมต่อเครือข่าย

เอกสารประกอบการใช้งาน Synapse แนะนำให้ใช้ Reverse Proxy สำหรับการยุติการเชื่อมต่อ TLS และอธิบายพอร์ตไคลเอ็นต์และพอร์ต Federation ที่แยกจากกัน โปรดดูคู่มืออย่างเป็นทางการสำหรับการกำหนดค่า Reverse Proxy , การมอบหมาย Federation ขาเข้า , ตัวเลือกการกำหนดค่า Synapseและคำแนะนำเกี่ยวกับไฟร์วอลล์และความปลอดภัยสำหรับกฎการค้นหาเซิร์ฟเวอร์ โปรดดูข้อกำหนด API ของ Matrix Server-Serverตัวอย่างในที่นี้สมมติว่าใช้ Synapse มาตรฐานที่อยู่เบื้องหลัง Reverse Proxy แบบ HTTPS การเชื่อมต่อเครือข่ายคอนเทนเนอร์ การปรับใช้แบบจัดการ และรูปแบบ Listener ที่กำหนดเองอาจต้องการค่าที่แตกต่างกัน