วิธีตั้งค่านามแฝงห้อง Matrix แบบกำหนดเองบนโดเมนของคุณ

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

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

ชื่อเรียกแทนห้องในเมทริกซ์คืออะไร

โฮมเซิร์ฟเวอร์คือเซิร์ฟเวอร์ของเมทริกซ์ที่จัดเก็บข้อมูลห้องของผู้ใช้และเชื่อมต่อกับเซิร์ฟเวอร์อื่นๆรหัสห้องเช่น ` !opaqueid:example.orgroom_id` ระบุห้องในเชิงเทคนิคส่วนชื่อเรียกแทนห้องเช่น `room_alias` #support:example.orgคือรายการในไดเร็กทอรีที่อ่านได้ ซึ่งแปลงเป็นรหัสห้องและรายชื่อเซิร์ฟเวอร์ที่สามารถช่วยให้ผู้ใช้เข้าร่วมได้

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

ก่อนที่คุณจะเริ่มต้น

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

หากเซิร์ฟเวอร์กำลังทำงานอยู่แล้วโดยใช้ชื่อเซิร์ฟเวอร์ที่แตกต่างกันprovider.netการสร้าง#support:example.orgชื่อแทน (alias) ไม่ใช่ทางลัดในการแมปโดเมน ควรสอบถามผู้ให้บริการเกี่ยวกับการสนับสนุนโดเมนแบบกำหนดเอง หรือวางแผนการติดตั้งและการย้ายข้อมูลโฮมเซิร์ฟเวอร์แยกต่างหาก Matrix ไม่ได้กำหนดกระบวนการสำหรับโฮมเซิร์ฟเวอร์หนึ่งในการสร้างชื่อแทนในเนมสเปซของเซิร์ฟเวอร์อื่น

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

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

เมื่อไม่สามารถเข้าถึงโฮมเซิร์ฟเวอร์ได้โดยตรงexample.orgผ่านพอร์ตเฟเดอเรชันเริ่มต้น 8448 นั้น Matrix จำเป็นต้องหาวิธีค้นหาเอนด์พอยต์เฟเดอเรชัน วิธีที่ใช้กันทั่วไปวิธีหนึ่งคือการมอบหมายแบบ .well-known : การตอบสนอง JSON HTTPS ขนาดเล็กในโดเมนชื่อเซิร์ฟเวอร์จะชี้การรับส่งข้อมูลเฟเดอเรชันไปยังโฮสต์ Matrix จริง ให้บริการสิ่งนี้ที่https://example.org/.well-known/matrix/server:

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

ตรวจสอบให้แน่ใจว่าการตอบกลับเป็น JSON ที่ถูกต้อง ส่งผ่าน HTTPS และโฮสต์เป้าหมายมีใบรับรองที่ถูกต้องและส่งต่อคำขอเฟเดอเรชันไปยัง Synapse พอร์ตสามารถละเว้นได้เมื่อปลายทางเฟเดอเรชันใช้พอร์ต 8448 ในตัวอย่างนี้ พอร์ต 443 ถูกระบุไว้อย่างชัดเจน หาก Synapse ให้บริการเฟเดอเรชันบนโดเมนชื่อเซิร์ฟเวอร์ที่พอร์ต 8448 อยู่แล้ว อาจไม่จำเป็นต้องมีการมอบหมายสิทธิ์/.well-known/matrix/clientไฟล์ที่ลูกค้าใช้งานเป็นกลไกการค้นหาที่แตกต่างออกไปและไม่สามารถใช้แทนการมอบหมายสิทธิ์เซิร์ฟเวอร์ได้

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

ขั้นตอนที่ 2: ตรวจสอบนโยบายการตั้งชื่อแทนของ Synapse

Synapse สามารถจำกัดผู้ที่สามารถสร้างนามแฝงและที่อยู่ห้องที่ได้รับอนุญาตได้homeserver.yamlตรวจสอบalias_creation_rulesว่าคำขอสร้างนามแฝงถูกปฏิเสธหรือไม่ Synapse จะประเมินกฎที่กำหนดค่าไว้ตามลำดับ กฎข้อแรกที่ตรงกันจะเป็นตัวตัดสินคำขอ และหากไม่มีกฎใดตรงกัน คำขอจะถูกปฏิเสธ รายการว่างเปล่าจะปฏิเสธคำขอสร้างนามแฝงทั้งหมด รายการที่เป็นค่าว่างหรือไม่ได้ระบุไว้จะอนุญาตให้สร้างนามแฝงได้โดยค่าเริ่มต้น โดยขึ้นอยู่กับการตรวจสอบอื่นๆ

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

ขั้นตอนที่ 3: สร้างชื่อเรียกแทน (alias) สำหรับห้อง

เข้าร่วมห้องที่ต้องการในโปรแกรม Matrix Client แล้วเปิดการตั้งค่าห้อง มองหาส่วนที่อยู่หรือชื่อเรียกแทน (คำและรูปแบบของ Client อาจแตกต่างกันไปในแต่ละเวอร์ชัน) ป้อนที่อยู่แบบเต็ม รวมถึงส่วนนำหน้า#และโดเมนของโฮมเซิร์ฟเวอร์ เช่น#support:example.orgเพิ่มที่อยู่ดังกล่าวเป็นที่อยู่ห้อง และหาก Client มีตัวเลือกนี้ ให้ตั้งค่าเป็นชื่อเรียกแทนหลักหรือชื่อเรียกแทนที่ต้องการ บันทึกการเปลี่ยนแปลง

หากไคลเอ็นต์ของคุณไม่ได้กำหนดการควบคุมนามแฝง การร้องขอ API ระหว่างไคลเอ็นต์และเซิร์ฟเวอร์สามารถสร้างการแมปได้ ปลายทางที่ต้องมีการ ตรวจสอบสิทธิ์ PUT /_matrix/client/v3/directory/room/{roomAlias}จะต้องมีรหัสห้องในเนื้อหาการร้องขอ ตัวอย่างเช่น สมาชิกห้องที่ได้รับอนุญาตหรือบัญชีเซิร์ฟเวอร์สามารถส่งคำร้องขอไปยังโฮมเซิร์ฟเวอร์ที่เป็นเจ้าของห้องนั้นได้example.org:

curl -X PUT \
  "https://matrix.example.org/_matrix/client/v3/directory/room/%23support%3Aexample.org" \
  -H "Authorization: Bearer $MATRIX_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"room_id":"!yourRoomId:example.org"}'

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

ขั้นตอนที่ 4: ตรวจสอบที่อยู่และแชร์ที่อยู่ดังกล่าว

ค้นหาชื่อแทนโดยใช้ API สาธารณะแบบไคลเอ็นต์-เซิร์ฟเวอร์ การค้นหานี้ไม่จำเป็นต้องมีการตรวจสอบสิทธิ์:

curl -i \
  "https://matrix.example.org/_matrix/client/v3/directory/room/%23support%3Aexample.org"

การตอบสนองที่สำเร็จควรมีข้อมูลที่คาดหวังroom_idและserversรายการ เปรียบเทียบรหัสห้องที่ได้รับกับห้องที่ต้องการ รหัส 404 หมายความว่าไม่มีการแมปชื่อเรียกบนเซิร์ฟเวอร์ที่จัดการเนมสเปซนั้น รหัส 400 ชี้ไปที่ที่อยู่ที่มีรูปแบบไม่ถูกต้อง จากนั้นทดสอบชื่อเรียกแบบเต็มในบัญชี Matrix หรือไคลเอนต์ตัวที่สองเพื่อยืนยันว่าห้องนั้นสามารถใช้งานได้และสามารถเข้าร่วมได้ตามกฎการเข้าร่วม

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

ปัญหาทั่วไปที่ควรหลีกเลี่ยง

• การใช้โดเมนที่โฮมเซิร์ฟเวอร์ไม่ได้เป็นเจ้าของ:ชื่อเซิร์ฟเวอร์ในนามแฝงต้องตรงกับเนมสเปซของโฮมเซิร์ฟเวอร์ที่สร้างนามแฝงนั้นขึ้นมา การใช้ DNS CNAME เพียงอย่างเดียวไม่สามารถอนุญาตโดเมนของเซิร์ฟเวอร์อื่นได้
• การสับสนระหว่างโดเมนและโฮสต์: example.orgอาจเป็นเนมสเปซนามแฝง ในขณะที่matrix.example.orgเป็นโฮสต์บริการ ควรตั้งชื่อเซิร์ฟเวอร์ Synapse และการมอบหมายสิทธิ์อย่างรอบคอบ
• การวางไฟล์ค้นหาไคลเอ็นต์ไว้ผิดที่:การมอบหมายสหพันธ์ใช้/.well-known/matrix/server. ไฟล์ค้นหาไคลเอ็นต์มีเส้นทางและวัตถุประสงค์ที่แตกต่างกัน
• สมมติว่านามแฝงเผยแพร่ห้องสนทนาสู่สาธารณะ:การแก้ไขนามแฝงและการเผยแพร่รายชื่อห้องสนทนาสู่สาธารณะเป็นกระบวนการที่แยกจากกัน ซึ่งอยู่ภายใต้นโยบายที่แยกจากกัน
• การเปลี่ยนชื่อเซิร์ฟเวอร์ในระบบที่ติดตั้งไว้แล้ว:รหัส Matrix ที่มีอยู่จะขึ้นอยู่กับเนมสเปซนั้น ควรพิจารณาการเปลี่ยนแปลงโดเมนเป็นการปรับเปลี่ยนโครงสร้างทางสถาปัตยกรรม ไม่ใช่การตั้งค่าชื่อแทนอย่างรวดเร็ว
• การแชร์โดยไม่ตรวจสอบการแมป:ตรวจสอบความถูกต้องของนามแฝงและเปรียบเทียบรหัสห้องที่ได้รับก่อนที่จะเผยแพร่ ที่อยู่แบบอ่านง่ายนั้นสะดวก แต่การแมปของเซิร์ฟเวอร์ต่างหากที่เป็นตัวกำหนดว่าจะนำไปสู่ที่ใด

สำหรับรายละเอียดของโปรโตคอล โปรดดูรูปแบบตัวระบุและนามแฝงของ MatrixและAPI นามแฝงห้องของ Matrixสำหรับการตั้งค่า Synapse โปรดดูคู่มือการมอบหมายสหพันธ์และการกำหนดค่า ของ Element ตัวเลือก Synapse และหน้าจอไคลเอ็นต์อาจเปลี่ยนแปลงไปในแต่ละเวอร์ชัน โปรดตรวจสอบเอกสารประกอบสำหรับเวอร์ชันที่คุณใช้งาน