Tuần này trên Hacker News có bài viết về việc European Commission triển khai Matrix cho hơn 40.000 nhân viên. Bài này lên top với gần 500 điểm. Lý do khá dễ hiểu: các tổ chức lớn ngày càng không muốn dữ liệu chat nội bộ nằm trên server của bên thứ ba. Ở Việt Nam, nhiều team vẫn trao đổi công việc, kể cả gửi credential production, qua Zalo hoặc Telegram cá nhân. Nếu bạn từng thấy ai đó gửi file .env vào group chat thì bạn hiểu vì sao chuyện này đáng lo.
Trong bài này mình chia sẻ cách dựng một Matrix homeserver cho team từ 10 đến 50 người: Synapse + PostgreSQL + Caddy chạy bằng Docker Compose, và một bot Python nhỏ để đẩy alert từ hệ thống vào phòng chat. Đây là setup mình đã chạy thật, không phải demo.
1. Kiến trúc tổng quan: cần những gì?
Matrix là một protocol chứ không phải một app. Bạn cần một homeserver (Synapse là bản reference implementation, viết bằng Python, ổn định nhất hiện nay). User dùng client như Element (web, desktop, mobile) để kết nối vào homeserver. Mỗi homeserver có thể federate với homeserver khác, giống cách email server nói chuyện với nhau.
graph LR
U1[Element Web/Desktop] -->|HTTPS 443| C[Caddy reverse proxy]
U2[Element Mobile] -->|HTTPS 443| C
B[Python bot] -->|Client-Server API| C
C -->|:8008| S[Synapse]
S --> P[(PostgreSQL 16)]
S -.->|Federation 443| O[Homeserver khác]
Cấu hình tối thiểu cho team 50 người: VPS 2 vCPU, 4GB RAM, 40GB SSD. Synapse khá tốn RAM khi join các room lớn được federate (ví dụ room public trên matrix.org có hàng chục nghìn member). Nếu chỉ dùng nội bộ thì 2GB vẫn chạy được.
Lưu ý quan trọng: server_name (phần sau dấu : trong user ID như @andy:example.com) không đổi được sau khi đã tạo. Hãy chọn domain chính của công ty, sau đó dùng delegation để trỏ về subdomain matrix.example.com.
2. Dựng Synapse bằng Docker Compose
Đầu tiên, generate file config:
mkdir -p ~/matrix/{synapse,postgres} && cd ~/matrix
docker run -it --rm \
-v $(pwd)/synapse:/data \
-e SYNAPSE_SERVER_NAME=example.com \
-e SYNAPSE_REPORT_STATS=no \
matrixdotorg/synapse:latest generate
Lệnh trên tạo ra synapse/homeserver.yaml và signing key. Mặc định Synapse dùng SQLite, cái này chỉ hợp để test. Bạn sửa phần database:
database:
name: psycopg2
args:
user: synapse
password: "doi-mat-khau-nay"
database: synapse
host: postgres
cp_min: 5
cp_max: 10
enable_registration: false
Tiếp theo là docker-compose.yml. Chỗ hay bị bỏ sót nhất: PostgreSQL phải được init với collation C. Nếu không, Synapse sẽ báo lỗi và từ chối khởi động. Lỗi này mình đã gặp một lần và mất cả buổi tối mới tìm ra.
services:
postgres:
image: postgres:16-alpine
restart: unless-stopped
environment:
POSTGRES_USER: synapse
POSTGRES_PASSWORD: doi-mat-khau-nay
POSTGRES_DB: synapse
POSTGRES_INITDB_ARGS: "--encoding=UTF-8 --lc-collate=C --lc-ctype=C"
volumes:
- ./postgres:/var/lib/postgresql/data
synapse:
image: matrixdotorg/synapse:latest
restart: unless-stopped
depends_on: [postgres]
volumes:
- ./synapse:/data
caddy:
image: caddy:2
restart: unless-stopped
ports: ["80:80", "443:443"]
volumes:
- ./Caddyfile:/etc/caddy/Caddyfile
- caddy_data:/data
volumes:
caddy_data:
Caddy tự lấy cert Let's Encrypt, nên đỡ phải cấu hình certbot. Caddyfile gồm cả phần delegation qua .well-known:
matrix.example.com {
reverse_proxy /_matrix/* synapse:8008
reverse_proxy /_synapse/client/* synapse:8008
}
example.com {
header /.well-known/matrix/* Content-Type application/json
header /.well-known/matrix/* Access-Control-Allow-Origin *
respond /.well-known/matrix/server `{"m.server":"matrix.example.com:443"}`
respond /.well-known/matrix/client `{"m.homeserver":{"base_url":"https://matrix.example.com"}}`
}
Khởi động rồi tạo tài khoản admin. Registration công khai đã tắt, nên user sẽ được tạo bằng tay hoặc qua SSO:
docker compose up -d
docker compose exec synapse register_new_matrix_user \
-c /data/homeserver.yaml -a -u admin http://localhost:8008
3. Delegation và federation hoạt động thế nào?
Đây là phần nhiều người thấy rối nhất. Khi server khác muốn gửi tin cho @andy:example.com, nó cần tìm ra server thật đang chạy ở đâu:
sequenceDiagram
participant R as Remote homeserver
participant W as example.com
participant M as matrix.example.com
R->>W: GET /.well-known/matrix/server
W-->>R: {"m.server": "matrix.example.com:443"}
R->>M: PUT /_matrix/federation/v1/send/...
M-->>R: 200 OK
Client (Element) cũng làm tương tự với /.well-known/matrix/client. Nhờ đó user chỉ cần gõ example.com khi đăng nhập. Sau khi setup xong, dùng Matrix Federation Tester để kiểm tra. Nếu bạn chỉ dùng nội bộ và không muốn federate, đặt federation_domain_whitelist: [] trong homeserver.yaml. Đây cũng là cách nhiều tổ chức chính phủ đang làm: chỉ federate với danh sách server đã duyệt.
4. Bot Python: đẩy alert vào phòng chat
Đây là phần khiến team mình bỏ hẳn được việc dùng Telegram bot cho monitoring. Cách đơn giản nhất là gọi thẳng Client-Server API bằng curl, rất tiện để nhét vào cron job hay CI pipeline:
#!/usr/bin/env bash
# send_alert.sh "Disk 90% tren db-01"
HS="https://matrix.example.com"
ROOM="!abcXYZ:example.com" # room ID, lay trong Element > Settings > Advanced
TOKEN="${MATRIX_BOT_TOKEN}"
TXN=$(date +%s%N) # transaction ID phai unique de tranh gui trung
curl -s -X PUT \
-H "Authorization: Bearer ${TOKEN}" \
-H "Content-Type: application/json" \
"${HS}/_matrix/client/v3/rooms/${ROOM}/send/m.room.message/${TXN}" \
-d "{\"msgtype\":\"m.text\",\"body\":\"🚨 $1\"}"
Nếu cần bot tương tác hai chiều (nhận lệnh !deploy, !status...), dùng thư viện matrix-nio (pip install matrix-nio):
import asyncio, os
from nio import AsyncClient, RoomMessageText
client = AsyncClient(os.environ["HS_URL"], os.environ["BOT_USER"])
async def on_message(room, event):
if event.sender == client.user_id:
return # bo qua tin cua chinh bot
if event.body.strip() == "!ping":
await client.room_send(
room.room_id, "m.room.message",
{"msgtype": "m.text", "body": f"pong tu {room.display_name}"},
)
async def main():
await client.login(os.environ["BOT_PASSWORD"])
# sync mot lan truoc de khong xu ly lai tin nhan cu
await client.sync(timeout=10000, full_state=True)
client.add_event_callback(on_message, RoomMessageText)
await client.sync_forever(timeout=30000)
asyncio.run(main())
Để ý dòng client.sync() chạy trước khi đăng ký callback. Nếu bỏ dòng này, mỗi lần restart bot sẽ trả lời lại toàn bộ lịch sử !ping. Mình bị team chửi một lần vì vụ này rồi.
Về E2EE: room nội bộ nên bật encryption, nhưng bot sẽ phức tạp hơn vì phải lưu key store (matrix-nio[e2e]). Với bot chỉ gửi alert, cách thực dụng là để bot dùng một room riêng không mã hóa, chỉ chứa thông tin ít nhạy cảm.
Kết luận
Một Matrix homeserver cho team là việc làm được trong một cuối tuần. Đổi lại, bạn kiểm soát hoàn toàn dữ liệu chat. Những điểm cần nhớ:
-
Chọn
server_namecẩn thận ngay từ đầu. Dùng domain chính rồi delegate qua.well-known, vì sau này không đổi được. -
PostgreSQL phải có
--lc-collate=C. Đừng chạy production bằng SQLite. -
Tắt
enable_registration. Tạo user bằngregister_new_matrix_userhoặc tích hợp SSO (Synapse hỗ trợ OIDC với Keycloak, Google Workspace). -
Giới hạn federation bằng
federation_domain_whitelistnếu chỉ dùng nội bộ. -
Backup hai thứ: dump PostgreSQL (
pg_dump) và file signing key trongsynapse/. Mất signing key thì coi như mất danh tính server khi federate. -
Bắt đầu với bot alert bằng
curl. Đây là use case dễ thuyết phục team chuyển sang nhất, vì không ai muốn alert production lẫn giữa ảnh meme trong group Zalo.
Khi team đã quen, bạn có thể tìm hiểu thêm các bridge (nối Matrix với Slack hay Telegram) hoặc chuyển sang Matrix Authentication Service để quản lý đăng nhập tập trung. Nhưng hãy bắt đầu nhỏ: một server, một room alert, năm người dùng thử.
Top comments (0)