วิธีการโฮสต์เว็บไคลเอ็นต์ Custom Element บน Nginx

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

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

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

โปรดเตรียมสิ่งเหล่านี้ให้พร้อมก่อนทำการแก้ไขไฟล์เซิร์ฟเวอร์:

• โดเมนหรือซับโดเมนสำหรับเว็บไคลเอ็นต์ โดยที่ DNS ชี้ไปยังโฮสต์ Nginx
• โฮมเซิร์ฟเวอร์ Matrix ที่ใช้งานได้และสามารถเข้าถึงได้ผ่าน URL HTTPS เช่นhttps://matrix.example.org.
• ติดตั้ง Nginx เรียบร้อยแล้ว โดยได้รับอนุญาตให้แก้ไขการตั้งค่าเว็บไซต์และรีโหลดบริการได้
• ต้องมีใบรับรอง TLS ที่ถูกต้องสำหรับชื่อโฮสต์ของเว็บไคลเอ็นต์ ผู้ใช้ควรเข้าสู่ระบบผ่าน HTTPS เนื่องจากเบราว์เซอร์ของผู้ใช้จะส่งข้อมูลประจำตัวและโทเค็นเซสชันไปยังเว็บไซต์
• ไฟล์เก็บถาวรเวอร์ชัน Element Web ที่เสถียรล่าสุดจากโครงการอย่างเป็นทางการ หลีกเลี่ยงการนำเวอร์ชันสำหรับการพัฒนาไปใช้งานบนบริการสาธารณะ เว้นแต่คุณตั้งใจจะใช้งานซอฟต์แวร์สำหรับการพัฒนาโดยเฉพาะ

Element Web เป็นแอปพลิเคชันบนเว็บเบราว์เซอร์ที่สร้างจากไฟล์คงที่ คำแนะนำในการติดตั้งปัจจุบันของโครงการแนะนำให้ดาวน์โหลดเวอร์ชันที่เผยแพร่แล้ว แตกไฟล์บนเซิร์ฟเวอร์ ชี้เว็บเซิร์ฟเวอร์ไปยังไฟล์ที่ได้ และกำหนดค่าต่างๆconfig.jsonบน Debian และ Ubuntu โครงการยังได้จัดทำเอกสารเกี่ยวกับแพ็คเกจ Element Web ที่ติดตั้งเว็บรูทไว้ภายใต้/usr/share/element-webและการกำหนดค่าไว้ภายใต้/etc/element-web/config.jsonขั้นตอนด้านล่างนี้ใช้ไฟล์เก็บถาวรเวอร์ชันที่เผยแพร่แล้ว ดังนั้นคุณสามารถเลือกไดเร็กทอรีเอกสารเฉพาะได้

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

1. ดาวน์โหลดและติดตั้งไฟล์ Element Web

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

sudo install -d -o root -g www-data -m 0755 /var/www/element
tar -xzf element-vX.Y.Z.tar.gz
ls

โดยปกติไฟล์เก็บถาวรจะถูกแตกไฟล์ไปยังไดเร็กทอรีที่มีการกำหนดเวอร์ชัน คัดลอกเนื้อหาของไดเร็กทอรีนั้น รวมถึงindex.htmlชุดไฟล์ JavaScript ฟอนต์ รูปภาพ และไฟล์การกำหนดค่าตัวอย่าง ไปยังไดเร็กทอรีหลักของ Nginx ตัวอย่างเช่น หากไดเร็กทอรีที่แตกไฟล์ออกมามีชื่อว่าelement-vX.Y.Z:

sudo cp -a element-vX.Y.Z/. /var/www/element/
sudo find /var/www/element -type d -exec chmod 755 {} \;
sudo find /var/www/element -type f -exec chmod 644 {} \;
ls -l /var/www/element/index.html /var/www/element/config.sample.json

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

2. ตั้งค่าไคลเอ็นต์ให้ใช้งานโฮมเซิร์ฟเวอร์ของคุณ

Element จำเป็นต้องมีที่อยู่โฮมเซิร์ฟเวอร์ก่อนจึงจะเริ่มต้นได้ คัดลอกไฟล์ตัวอย่างและตั้งค่า URL API ไคลเอ็นต์ Matrix เริ่มต้น ในตัวอย่างนี้ สามารถเข้าถึง Synapse ได้ที่https://matrix.example.org:

cd /var/www/element
sudo cp config.sample.json config.json
sudoedit /var/www/element/config.json

แก้ไข/var/www/element/config.jsonและตรวจสอบให้แน่ใจว่ามีออบเจ็กต์ JSON ที่ถูกต้องพร้อมdefault_server_configรายการ ตัวอย่างเช่น:

{
  "default_server_config": {
    "m.homeserver": {
      "base_url": "https://matrix.example.org"
    }
  }
}

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

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

โปรดดูเอกสารอ้างอิงการกำหนดค่าปัจจุบันของ Element Web เอกสาร นี้developอาจมีการเปลี่ยนแปลงเมื่อโครงการพัฒนาขึ้น ดังนั้นโปรดตรวจสอบคีย์เสริมใดๆ กับเวอร์ชันที่คุณใช้งาน

3. เพิ่มไซต์ Nginx สำหรับเว็บไคลเอ็นต์

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

server {
    listen 80;
    server_name chat.example.org;
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl;
    server_name chat.example.org;

    ssl_certificate     /etc/letsencrypt/live/chat.example.org/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/chat.example.org/privkey.pem;

    root /var/www/element;
    index index.html;

    # Revalidate the client files after deployments.
    add_header Cache-Control "no-cache" always;

    # Element Web hosting security headers.
    add_header X-Frame-Options "SAMEORIGIN" always;
    add_header X-Content-Type-Options "nosniff" always;
    add_header X-XSS-Protection "1; mode=block" always;
    add_header Content-Security-Policy "frame-ancestors 'self'" always;

    location / {
        try_files $uri $uri/ =404;
    }
}

ใส่โค้ดส่วนนี้ลงในไฟล์ไซต์ที่เหมาะสมสำหรับการแจกจ่ายของคุณ เปิดใช้งานไซต์นั้นหากจำเป็น และตรวจสอบว่าการกำหนดค่า Nginx ทั่วโลกโหลดmime.typesไฟล์มาตรฐานแล้ว Nginx ใช้ประเภท MIME เพื่อบอกเบราว์เซอร์ว่าการตอบสนองเป็น JavaScript, CSS, JSON หรือไฟล์ประเภทอื่นrootต้องชี้ไปยังไดเร็กทอรีที่มี ไฟล์นั้นอยู่ index.htmlโดยตรง

ส่วนหัว no-cache ด้านบนเป็นพื้นฐานที่เรียบง่ายและใช้งานง่าย: เบราว์เซอร์จะตรวจสอบไฟล์อีกครั้งหลังจากการอัปเดต แทนที่จะใช้โค้ดไคลเอ็นต์ที่ล้าสมัยต่อไป หมายเหตุการโฮสต์ของ Element ระบุไว้อย่างชัดเจนว่า/config.*.json, /i18n, /version, และ/index.htmlไม่ควรถูกแคช และแนะนำให้ตรวจสอบความถูกต้องอีกครั้งสำหรับไดเร็กทอรีรากของเว็บไซต์ หากคุณเพิ่มการแคชที่มีอายุการใช้งานยาวนานขึ้นสำหรับสินทรัพย์คงที่ขนาดใหญ่ในภายหลัง โปรดตรวจสอบให้แน่ใจว่าเส้นทางเหล่านั้นเป็นปัจจุบันอยู่เสมอ และตรวจสอบการตั้งชื่อสินทรัพย์ของเวอร์ชันใหม่ก่อนที่จะสร้างกฎการแคช

เอกสาร README ของ Element สำหรับเว็บไซต์ที่โฮสต์ด้วยตนเองแนะนำให้ใช้ส่วนหัวป้องกันเฟรมและส่วนหัวประเภทเนื้อหา หากคุณได้ตั้งค่า Content Security Policy (CSP) ไว้ที่อื่นแล้ว ให้เพิ่มframe-ancestors 'self'เข้าไปในนโยบายที่มีอยู่แทนที่จะส่งส่วนหัว CSP ครั้งที่สอง CSP ที่เข้มงวดอาจบล็อกสคริปต์แอปพลิเคชันที่จำเป็น ดังนั้นอย่าคัดลอกนโยบายที่กว้างเกินไปโดยไม่ทดสอบกับไคลเอ็นต์ที่ใช้งานอยู่ก่อน

โปรดอ่านข้อกำหนดการโฮสติ้งและการแคชของ Element Webและเอกสารโมดูลหลักอย่างเป็นทางการของ Nginxเพื่อทำความเข้าใจพฤติกรรมของroot, try_files, และการจัดการไฟล์คงที่

4. ตรวจสอบความถูกต้องของการตั้งค่าและรีโหลด Nginx

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

sudo nginx -t
sudo systemctl reload nginx
curl -I https://chat.example.org/
curl -I https://chat.example.org/config.json

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

curl -fsS https://chat.example.org/config.json | python3 -m json.tool

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

5. ทำให้การค้นหาโฮมเซิร์ฟเวอร์ทำงานได้เมื่อจำเป็น

หาก Matrix ID ของคุณใช้ชื่อเซิร์ฟเวอร์ เช่นexample.orgในขณะที่ Synapse API อยู่ที่matrix.example.orgไคลเอนต์ Matrix สามารถใช้การตอบสนองที่รู้จักกันดีของไคลเอนต์ที่https://example.org/.well-known/matrix/clientเพื่อค้นหา URL ของ API ได้ จุดสิ้นสุดการค้นหาเสริมนี้ควรอยู่ในโดเมนใน Matrix ID ไม่ใช่ในชื่อโฮสต์ของเว็บไคลเอนต์ Element โดยอัตโนมัติ การตอบสนองขั้นต่ำจะมีลักษณะดังนี้:

{
  "m.homeserver": {
    "base_url": "https://matrix.example.org"
  }
}

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

ปฏิบัติตามคำแนะนำที่เป็นที่รู้จักกันดีของ Synapse สำหรับลูกค้าและทดสอบ URL สุดท้ายcurlก่อนที่จะคาดหวังว่าการค้นหา User-ID จะทำงานได้ สำหรับการแยกความปลอดภัย คำแนะนำด้านความปลอดภัยของ Synapse แนะนำให้โฮสต์โฮมเซิร์ฟเวอร์บนโดเมนที่จดทะเบียนแยกต่างหากจากเว็บแอปพลิเคชันที่มีข้อมูลสำคัญ หากทำได้ โดเมนย่อยที่แยกต่างหากให้การป้องกันได้บ้าง แต่โดเมนที่จดทะเบียนแยกต่างหากเป็นคำแนะนำที่แข็งแกร่งกว่า

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

• Nginx แสดงข้อผิดพลาด 403:ตรวจสอบสิทธิ์การอ่านไฟล์และไดเร็กทอรี และยืนยันว่า Nginx worker สามารถเข้าถึงแต่ละไดเร็กทอรีแม่ได้
• หน้าเว็บว่างเปล่าหรือแสดงข้อผิดพลาด 404 สำหรับ JavaScript:โปรดตรวจสอบให้แน่ใจว่าrootชี้ไปยังเนื้อหาของไดเร็กทอรีที่แตกไฟล์ออกมา ไม่ใช่ไดเร็กทอรีที่อยู่เหนือหรือใต้ไดเร็กทอรีนั้น ตรวจสอบบันทึกข้อผิดพลาดและบันทึกการเข้าถึงของ Nginx ด้วย
• เว็บไซต์โหลดได้ แต่ไม่สามารถเชื่อมต่อหรือล็อกอินได้:ตรวจสอบbase_urlการตั้งค่าต่างๆconfig.jsonเช่น ใบรับรอง HTTPS ของโฮมเซิร์ฟเวอร์ การเข้าถึงไฟร์วอลล์ และการตั้งค่า CORS หรือ reverse-proxy ฝั่ง Synapse CORS ถูกบังคับใช้โดยเบราว์เซอร์ เว็บไซต์แบบคงที่ของ Nginx ไม่สามารถแก้ไขนโยบายต้นทางของโฮมเซิร์ฟเวอร์ได้ด้วยตัวเอง
• การเปลี่ยนแปลงล่าสุดไม่ปรากฏ:ตรวจสอบส่วนหัวแคชสำหรับ/, /index.html, /config.json, /version, และ/i18nจากนั้นรีเฟรชเบราว์เซอร์ใหม่ทั้งหมดหลังจากยืนยันว่าไฟล์ที่ปรับใช้ได้รับการแทนที่แล้ว
• หน้าล็อกอินใช้งานได้เฉพาะบน HTTP เท่านั้น:ดำเนินการตั้งค่า TLS ให้เสร็จสมบูรณ์และเปลี่ยนเส้นทาง HTTP ไปยัง HTTPS ก่อนที่จะเชิญผู้ใช้ให้ลงชื่อเข้าใช้

รายการตรวจสอบการใช้งานขั้นสุดท้าย

• ชื่อโฮสต์ของ Element Web ชี้ไปยังเซิร์ฟเวอร์ Nginx และมีใบรับรอง HTTPS ที่ถูกต้อง
• ไดเร็กทอรีหลักของเอกสารประกอบด้วยไฟล์เวอร์ชันindex.htmlไฟล์สินทรัพย์ และไฟล์ที่ถูกconfig.jsonต้อง
• ข้อมูล JSON m.homeserver.base_urlชี้ไปยัง API ไคลเอ็นต์ HTTPS ที่สามารถเข้าถึงได้สำหรับโฮมเซิร์ฟเวอร์ Matrix ของคุณ
• sudo nginx -tผ่านการตรวจสอบ และ Nginx ให้บริการทั้งหน้าแรกและconfig.jsonผ่าน HTTPS
• เบราว์เซอร์สามารถเข้าสู่ระบบและส่งคำขอจริงไปยังโฮมเซิร์ฟเวอร์ได้โดยไม่มีข้อผิดพลาดเกี่ยวกับใบรับรอง, CORS หรือไฟล์หาย
• กฎการแคชของคุณอนุญาตให้ไฟล์ไคลเอ็นต์และการกำหนดค่าใหม่มีผลหลังจากอัปเกรด

เมื่อการตรวจสอบเหล่านี้ผ่านแล้ว ไคลเอนต์ Element Web ที่กำหนดเองจะทำงานบน Nginx และสามารถสื่อสารกับโฮมเซิร์ฟเวอร์ Matrix ได้ หมั่นอัปเดต Element Web เก็บสำเนาการย้อนกลับของเวอร์ชันและการกำหนดค่าก่อนหน้า และตรวจสอบ URL ของโฮมเซิร์ฟเวอร์และคำขอเครือข่ายของเบราว์เซอร์อีกครั้งหลังจากการอัปเกรดแต่ละครั้ง

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

• เอกสารประกอบการติดตั้ง Element Web
• คู่มือการตั้งค่า Element Web
• คำแนะนำเกี่ยวกับการโฮสต์เว็บ ส่วนหัวด้านความปลอดภัย และการแคชข้อมูล
• เอกสารประกอบเกี่ยวกับ URI ที่รู้จักกันดีของไคลเอ็นต์ Synapse
• คำแนะนำด้านความปลอดภัยของ Synapse
• เอกสารประกอบโมดูลหลักของ Nginx