วิธีการติดตั้ง Synapse Matrix Server ด้วย Docker Compose

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

คู่มือนี้จะสร้างบริการ Synapse และฐานข้อมูล PostgreSQL โดยใช้ Docker Compose อิมเมจ Docker อย่างเป็นทางการของ Synapse เริ่มต้นด้วย SQLite เป็นค่าเริ่มต้น ซึ่งสะดวกสำหรับการทดลองใช้งานแบบชั่วคราว แต่เอกสารประกอบของ Synapse แนะนำให้ใช้ PostgreSQL สำหรับการใช้งานจริง ดังนั้น ตัวอย่างนี้จึงสร้างการกำหนดค่าของ Synapse ก่อน เปลี่ยนการตั้งค่าฐานข้อมูลเป็น PostgreSQL แล้วจึงเริ่มคอนเทนเนอร์ทั้งสอง อิมเมจอย่างเป็นทางการคือ [ชื่ออิมเมจ] ghcr.io/element-hq/synapseคำแนะนำและรายละเอียดของอิมเมจได้รับการตรวจสอบกับเอกสารอย่างเป็นทางการฉบับปัจจุบัน ณ วันที่ 6 ตุลาคม 2026 แท็กของอิมเมจและเวอร์ชันซอฟต์แวร์ที่รองรับอาจเปลี่ยนแปลงได้ ดังนั้น โปรดตรวจสอบเอกสารที่เชื่อมโยงก่อนการใช้งานระยะยาว

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

• เซิร์ฟเวอร์ Linux หรือโฮสต์อื่นที่รองรับ Docker ซึ่งติดตั้ง Docker Engine และปลั๊กอิน Docker Compose แล้ว ตรวจสอบว่า Compose พร้อมใช้งานหรือไม่โดยใช้คำสั่ง `docker log sudo apt install docker compeze` docker compose versionและทำตามคำแนะนำการติดตั้งอย่างเป็นทางการของ Docker สำหรับระบบปฏิบัติการของคุณ
• โดเมนหรือซับโดเมนที่ชี้ไปยังเซิร์ฟเวอร์ ในตัวอย่างนี้chat.example.comคือชื่อเซิร์ฟเวอร์ Synapse ดังนั้นรหัสผู้ใช้ในเครื่องจะมีลักษณะดังนี้@alex:chat.example.comแทนที่ด้วยโดเมนที่คุณควบคุมก่อนที่จะสร้างการกำหนดค่า
• พร็อกซีแบบย้อนกลับหรือวิธีการยุติ TLS อื่นๆ สำหรับการใช้งานสาธารณะ ตัวรับฟัง HTTP เริ่มต้นของ Synapse บนพอร์ตนั้น8008ไม่ใช่ปลายทาง HTTPS ที่เข้าถึงได้จากอินเทอร์เน็ต ตัวอย่าง Compose นี้จะผูกพอร์ตนั้นเข้ากับอินเทอร์เฟซ loopback ของโฮสต์ เพื่อให้พร็อกซีแบบย้อนกลับบนเครื่องเดียวกันสามารถเข้าถึงได้

ชื่อที่ระบุใน URL SYNAPSE_SERVER_NAMEไม่จำเป็นต้องเป็น URL ของการเชื่อมต่อไคลเอ็นต์ทุกราย หากคุณต้องการ ID ที่สั้นกว่า เช่น@alex:example.comในขณะที่ให้บริการลูกค้าจาก คุณchat.example.comจะต้องกำหนดค่าโดเมนและการค้นหาอย่างรอบคอบ ควรตัดสินใจเรื่องนี้ก่อนสร้างบัญชี

1. สร้างไดเร็กทอรีสำหรับทำงานและรหัสผ่านฐานข้อมูล

บนเซิร์ฟเวอร์ ให้สร้างไดเร็กทอรีสำหรับโปรเจ็กต์ Compose และไฟล์ Synapse ที่คงอยู่ถาวร:

mkdir -p ~/matrix-synapse/data
cd ~/matrix-synapse

สร้าง.envไฟล์ในเครื่องที่ Docker Compose จะอ่าน สร้างรหัสผ่านแบบสุ่มที่มีความยาวโดยใช้โปรแกรมจัดการรหัสผ่านหรือตัวสร้างรหัสผ่านที่ปลอดภัยในเครื่อง แล้ววางไว้หลัง <password> POSTGRES_PASSWORD=ในตัวอย่างนี้ใช้ตัวอักษรและตัวเลขเพื่อหลีกเลี่ยงปัญหาการอ้างอิง YAML ในภายหลัง อย่าส่งไฟล์นี้ไปยังที่เก็บข้อมูลสาธารณะ และจำกัดสิทธิ์การเข้าถึงของไฟล์:

umask 077
nano .env

ไฟล์ควรมีข้อความเพียงบรรทัดเดียว เช่นPOSTGRES_PASSWORD=replace-with-a-long-random-valueข้อความนี้เป็นเพียงตัวอย่าง ไม่ใช่รหัสผ่านที่จะนำกลับมาใช้ใหม่ เก็บรหัสผ่านนี้ไว้สำหรับใช้ในการตั้งค่าฐานข้อมูล Synapse ในขั้นตอนที่ 3

2. กำหนดค่าบริการ Synapse และ PostgreSQL

สร้างไฟล์compose.yamlในไดเร็กทอรีของโปรเจ็กต์:

services:
  postgres:
    image: postgres:16
    restart: unless-stopped
    environment:
      POSTGRES_USER: synapse
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?Set POSTGRES_PASSWORD in .env}
      POSTGRES_DB: synapse
      POSTGRES_INITDB_ARGS: "--encoding=UTF8 --locale=C"
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U synapse -d synapse"]
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 20s

  synapse:
    image: ghcr.io/element-hq/synapse:latest
    restart: unless-stopped
    depends_on:
      postgres:
        condition: service_healthy
    environment:
      SYNAPSE_SERVER_NAME: chat.example.com
      SYNAPSE_REPORT_STATS: "no"
    volumes:
      - ./data:/data
    ports:
      - "127.0.0.1:8008:8008"

volumes:
  postgres_data:

แทนที่chat.example.comด้วยชื่อเซิร์ฟเวอร์สุดท้ายที่คุณเลือก การตรวจสอบสถานะของ PostgreSQL จะทำให้ Compose รอจนกว่าฐานข้อมูลจะรายงานว่าพร้อมใช้งานก่อนที่จะเริ่ม Synapse วอลุ่มฐานข้อมูลที่มีชื่อและ./dataไดเร็กทอรีที่ติดตั้งบนโฮสต์จะยังคงอยู่แม้จะมีการเปลี่ยนคอนเทนเนอร์ การลบคอนเทนเนอร์เพียงอย่างเดียวจะไม่ลบพวกมันออกไป หลีกเลี่ยงการทำdocker compose down -vเช่นนั้นเว้นแต่คุณต้องการลบวอลุ่มฐานข้อมูลโดยเจตนา

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

3. สร้างไฟล์การกำหนดค่าของ Synapse และชี้ไปยัง PostgreSQL

เรียกใช้อิมเมจอย่างเป็นทางการหนึ่งครั้งในโหมดสร้างการกำหนดค่า เนื่องจาก Compose ติดตั้ง./dataอยู่ที่/dataดังนั้นการกำหนดค่าและคีย์ลงนามที่สร้างขึ้นจึงยังคงอยู่บนโฮสต์:

docker compose run --rm synapse generate

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

เปิดdata/homeserver.yamlและแทนที่database:ส่วนที่สร้างขึ้นด้วยการตั้งค่าต่อไปนี้ ใช้รหัสผ่านที่ถูกต้องจาก.envช่องที่กำหนดไว้แทนข้อความตัวอย่าง:

database:
  name: psycopg2
  args:
    user: synapse
    password: 'replace-with-the-same-random-value'
    dbname: synapse
    host: postgres
    port: 5432
    cp_min: 5
    cp_max: 10

รักษาการเยื้อง YAML รอบข้างให้ถูกต้อง และตรวจสอบให้แน่ใจว่ามีdatabase:ส่วนที่ใช้งานอยู่เพียงส่วนเดียวเท่านั้น ชื่อโฮสต์postgresคือชื่อบริการ Compose ซึ่งคอนเทนเนอร์สามารถแก้ไขได้บนเครือข่ายเริ่มต้นที่ใช้ร่วมกัน การกำหนดค่าใช้ชื่อเอ็นจิ้น PostgreSQL ที่ Synapse ได้บันทึกไว้psycopg2และชื่ออาร์กิวเมนต์ฐานข้อมูลรวมdbnameถึง

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

4. เริ่มใช้งาน Synapse ด้วย Docker Compose

เริ่มการทำงานของสแต็กในพื้นหลัง:

docker compose up -d

ตรวจสอบสถานะของบริการและอ่านบันทึกการเริ่มต้นระบบ:

docker compose ps
docker compose logs --tail=100 synapse

รอจนกว่า Synapse จะทำการตั้งค่าฐานข้อมูลครั้งแรกเสร็จสมบูรณ์ คอนเทนเนอร์ที่แสดงว่ากำลังทำงานอยู่หมายความว่ากระบวนการทำงานของมันกำลังทำงานอยู่เท่านั้น ตรวจสอบบันทึกเพื่อดูข้อผิดพลาดเกี่ยวกับการกำหนดค่า ฐานข้อมูล หรือสิทธิ์การเข้าถึงก่อนดำเนินการต่อ หากต้องการดูบันทึกแบบเรียลไทม์ ให้ใช้คำสั่งdocker compose logs -f synapseและกดCtrl+Cเพื่อหยุดการติดตามโดยไม่ต้องหยุดคอนเทนเนอร์

5. ตรวจสอบ API ในพื้นที่และกำหนดค่าการเข้าถึงแบบสาธารณะ

จากโฮสต์ Docker ให้ร้องขอเอนด์พอยต์เวอร์ชัน API ไคลเอ็นต์ของ Synapse:

curl -fsS http://127.0.0.1:8008/_matrix/client/versions

การตอบสนองที่สำเร็จคือข้อมูล JSON ที่อธิบายเวอร์ชัน API ไคลเอ็นต์ Matrix ที่รองรับ นี่เป็นการยืนยันว่าตัวรับฟัง HTTP ตอบสนองในเครื่อง แต่ไม่ได้พิสูจน์ว่า DNS, HTTPS หรือการเชื่อมต่อเครือข่ายได้รับการกำหนดค่าอย่างถูกต้อง

กำหนดค่าพร็อกซีแบบย้อนกลับของโฮสต์เพื่อส่งต่อคำขอสำหรับโดเมนที่เลือกไปยังhttp://127.0.0.1:8008และขอรับใบรับรอง TLS ที่ถูกต้อง รักษาเส้นทางคำขอของ Matrix ไว้เมื่อทำการพร็อกซี จากนั้นตรวจสอบปลายทางสาธารณะ:

curl -fsS https://chat.example.com/_matrix/client/versions

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

6. สร้างบัญชีผู้ดูแลระบบบัญชีแรก

โดยค่าเริ่มต้น Synapse จะปิดใช้งานการลงทะเบียนสาธารณะ สำหรับเซิร์ฟเวอร์ส่วนตัว ให้คงค่าเริ่มต้นนั้นไว้และสร้างบัญชีจากบรรทัดคำสั่ง เพิ่มregistration_shared_secretค่า ที่แข็งแกร่งให้กับชั่วคราว data/homeserver.yamlจากนั้นรีสตาร์ท Synapse เพื่อให้ระบบอ่านการเปลี่ยนแปลง:

docker compose restart synapse

เรียกใช้เครื่องมือลงทะเบียนภายในคอนเทนเนอร์ ระบบจะขอให้ป้อนชื่อผู้ใช้และรหัสผ่าน การตั้งค่านี้--adminจะสร้างผู้ดูแลระบบคนแรก:

docker compose exec synapse register_new_matrix_user \
  http://localhost:8008 \
  -c /data/homeserver.yaml \
  --admin

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

การสำรองข้อมูล การอัปเกรด และการแก้ไขปัญหาทั่วไป

• สำรองข้อมูลที่ถูกต้อง:หยุดหรือสร้างสแนปช็อตของข้อมูล PostgreSQL อย่างสม่ำเสมอ และสำรองข้อมูลทั้งหมด./dataรวมถึงการกำหนดค่า สื่อ และคีย์ลงนามcompose.yamlการสำรองข้อมูลเพียงอย่างเดียวไม่สามารถกู้คืนโฮมเซิร์ฟเวอร์ได้ จัดเก็บไฟล์สำรองไว้ในที่ที่แยกต่างหากจากเซิร์ฟเวอร์ และตรวจสอบเป็นระยะว่าคุณสามารถอ่านไฟล์สำรองเหล่านั้นได้
• Synapse ไม่สามารถเขียนไปยัง/data:ตรวจสอบความเป็นเจ้าของและการอนุญาตของโฮสต์บน./data. ผู้ใช้รันไทม์ของอิมเมจอย่างเป็นทางการจำเป็นต้องมีสิทธิ์ในการอ่านการกำหนดค่าและเขียนข้อมูล ปรับความเป็นเจ้าของโฮสต์อย่างระมัดระวัง แทนที่จะทำให้ไดเร็กทอรีสามารถเขียนได้โดยทุกคน
• การเชื่อมต่อฐานข้อมูลล้มเหลว:ตรวจสอบว่าการกำหนดค่าฐานข้อมูลใช้host: postgresรหัสผ่านตรงกัน.envและdocker compose logs postgresแสดงว่าฐานข้อมูลทำงานได้อย่างปกติ เงื่อนไขความพร้อมใช้งานของ Compose depends_onช่วยลดปัญหาการแข่งขันในการเริ่มต้นระบบ แต่ไม่ได้แก้ไขข้อมูลรับรองที่ไม่ถูกต้อง
• API ในเครื่องทำงานได้ แต่ไคลเอนต์ไม่สามารถเชื่อมต่อได้:ตรวจสอบระเบียน DNS, ใบรับรอง TLS, พร็อกซีแบบย้อนกลับต้นทาง และระเบียนการค้นหาสำหรับโครงสร้างโดเมนที่คุณเลือก การแมปพอร์ตแบบ loopback เท่านั้นเป็นไปตามเจตนาสำหรับพร็อกซีที่อยู่ในโฮสต์เดียวกัน พร็อกซีในคอนเทนเนอร์อื่นจำเป็นต้องใช้เครือข่าย Docker ที่ใช้ร่วมกันและการออกแบบการกำหนดเส้นทางที่แตกต่างกัน
• การอัปเกรด:ขั้นแรกให้สำรองข้อมูล ตรวจสอบบันทึกการเปลี่ยนแปลงของ Synapse อัปเดตแท็กรูปภาพที่ปักหมุดไว้ และสร้างบริการใหม่โดยใช้คำสั่ง `synapse_residence_service` docker compose pullตามด้วยdocker compose up -d`synapse_service` เก็บไดเร็กทอรีข้อมูล วอลุ่มฐานข้อมูล ชื่อเซิร์ฟเวอร์ และคีย์ลงนามเดิมไว้

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

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

• คำแนะนำในการติดตั้ง Synapse และคำแนะนำเกี่ยวกับการตั้งชื่อเซิร์ฟเวอร์
• ไฟล์ README ของอิมเมจ Docker อย่างเป็นทางการของ Synapse
• เอกสารอ้างอิงการกำหนดค่า Synapse
• คำแนะนำพร็อกซีย้อนกลับของไซแนปส์
• การติดตั้ง Docker Engine
• ลำดับการเริ่มต้นและการตรวจสอบสถานะของ Docker Compose