مدیریت Element، Synapse و Synapse Admin در Docker

مقدمه

Element یکی از کلاینت‌های شناخته‌شده پروتکل Matrix برای پیام‌رسانی و ارتباطات سازمانی است.

اما زمانی که Element را به‌صورت Self-Hosted راه‌اندازی می‌کنیم، معمولاً با یک سرویس واحد روبه‌رو نیستیم.

در یک نصب Docker معمولی ممکن است سرویس‌های زیر وجود داشته باشند:

Element Web
Synapse
Synapse Admin
PostgreSQL
Reverse Proxy

و در صورت نیاز به تماس صوتی و تصویری، سرویس‌هایی مانند TURN یا سایر اجزای مرتبط نیز به مجموعه اضافه شوند.

در این معماری، Synapse هسته اصلی سرور Matrix است، Element رابط کاربری کاربران و Synapse Admin پنل مدیریتی سرور محسوب می‌شود.

در این مقاله فرض می‌کنیم این سرویس‌ها با Docker Compose نصب شده‌اند و فایل‌های پروژه در مسیری مانند:

~/matrix-stack

قرار دارند.

هدف این مقاله بررسی کارهای روزمره مدیریتی، ساختار سرویس، مدیریت کاربران، تنظیمات، Logها، Backup و همچنین روش صحیح Update کردن Containerها برای دریافت نسخه‌های جدید است.

معماری سرور Element چگونه است؟

یک ساختار ساده می‌تواند به شکل زیر باشد:

                    Internet
                       |
                       v
                Reverse Proxy
                 HTTPS / TLS
                       |
          +------------+-------------+
          |                          |
          v                          v
     Element Web                Synapse Admin
          |                          |
          |                          |
          +------------+-------------+
                       |
                       v
                    Synapse
                       |
              +--------+--------+
              |                 |
              v                 v
          PostgreSQL         Media Store

هر کدام از این اجزا وظیفه متفاوتی دارند.

Element Web چیست؟

Element Web رابطی است که کاربران از طریق Browser مشاهده می‌کنند.

Element خودش Database پیام‌ها یا Userها نیست.

وظیفه Element این است که از طریق Matrix API با Synapse ارتباط برقرار کند.

کاربر معمولاً از طریق آدرسی مانند:

https://element.example.com

وارد Element می‌شود.

Element Web به‌صورت رسمی نیز به شکل Docker Image قابل اجرا است و فایل تنظیمات سفارشی آن معمولاً به /app/config.json داخل Container Mount می‌شود.

Synapse چیست؟

Synapse همان Matrix Homeserver است.

تقریباً تمام عملیات اصلی سمت Server در Synapse انجام می‌شوند.

از جمله:

• مدیریت Userها
• Authentication
• مدیریت Roomها
• ذخیره Eventهای Matrix
• نگهداری Message Metadata
• مدیریت Media
• Federation
• Device Management
• Admin API
• مدیریت ارتباط میان Matrix Serverها

به همین دلیل مهم‌ترین Container این Stack معمولاً:

synapse

است.

Synapse Admin چیست؟

Synapse Admin یک Web Interface برای مدیریت Synapse است.

این پنل از Synapse Admin API استفاده می‌کند و مدیریت بسیاری از عملیات را بدون استفاده مستقیم از API یا Database ساده می‌کند.

بسته به نسخه Synapse Admin می‌توانید قابلیت‌هایی مانند موارد زیر را در اختیار داشته باشید:

• مشاهده کاربران
• ایجاد User
• تغییر Password
• فعال یا غیرفعال کردن User
• تبدیل User به Server Admin
• مشاهده Last Activity
• مشاهده Roomهای کاربر
• مدیریت Roomها
• بررسی Deviceها
• مشاهده Media
• Deactivate کردن Account

خود Synapse Admin اطلاعات اصلی را ذخیره نمی‌کند؛ داده‌های واقعی همچنان داخل Synapse و Database قرار دارند.

Synapse Admin از Admin API رسمی Synapse استفاده می‌کند و خود Synapse APIهای مدیریت User، Room و Media را ارائه می‌کند.

PostgreSQL چه کاری انجام می‌دهد؟

در Environmentهای Production بهتر است Synapse از PostgreSQL استفاده کند.

اطلاعاتی مانند:

• کاربران
• Roomها
• Eventها
• Membershipها
• Deviceها
• Federation State
• Metadata

داخل Database نگهداری می‌شوند.

Docker Image رسمی Synapse نیز برای Production استفاده از PostgreSQL جداگانه را توصیه می‌کند.

Media Store چیست؟

فایل‌هایی که کاربران ارسال می‌کنند معمولاً داخل Media Store نگهداری می‌شوند.

برای مثال:

Image
Video
Audio
Document
Avatar

در Docker Image رسمی Synapse، داده‌های Persistent به‌صورت پیش‌فرض زیر مسیر:

/data

قرار می‌گیرند و Media Store نیز معمولاً بخشی از همین Persistent Data است.

به همین دلیل Volume مربوط به Synapse نباید هنگام Update حذف شود.

مشاهده Containerهای سرور

ابتدا وارد Directory پروژه شوید:

cd ~/matrix-stack

سپس:

docker compose ps

نمونه:

NAME             STATUS
synapse          Up
element          Up
synapse-admin    Up
postgres         Up

در بعضی Stackها ممکن است Containerهای دیگری مانند:

coturn
nginx
traefik

نیز وجود داشته باشند.

مشاهده تمام Containerهای Docker

برای بررسی کلی:

docker ps

برای مشاهده Containerهای متوقف‌شده نیز:

docker ps -a

اگر Container مرتب Restart می‌شود، ستون:

STATUS

می‌تواند اولین سرنخ مشکل باشد.

مشاهده Imageهای استفاده‌شده

برای مشاهده Imageهای Stack:

docker compose images

همچنین می‌توانید فایل Compose را بررسی کنید:

grep -n "image:" docker-compose.yml

نمونه:

synapse:
  image: matrixdotorg/synapse:v1.x.x

element:
  image: vectorim/element-web:v1.x.x

synapse-admin:
  image: awesometechnologies/synapse-admin:latest

postgres:
  image: postgres:15

نسخه‌ها در Server واقعی شما ممکن است متفاوت باشند.

مشاهده Logهای Synapse

یکی از مهم‌ترین Commandها:

docker compose logs synapse

برای مشاهده آخرین 100 خط:

docker compose logs --tail=100 synapse

برای مشاهده Log به‌صورت زنده:

docker compose logs -f synapse

این Command هنگام Troubleshooting بسیار کاربردی است.

مشاهده Log بقیه سرویس‌ها

Element:

docker compose logs element

Synapse Admin:

docker compose logs synapse-admin

PostgreSQL:

docker compose logs postgres

اگر اسم Service در فایل Compose متفاوت است، ابتدا:

docker compose ps

را بررسی کنید.

Restart کردن Synapse

اگر فقط Synapse باید Restart شود:

docker compose restart synapse

برای Element:

docker compose restart element

برای Synapse Admin:

docker compose restart synapse-admin

برای Restart تمام Stack:

docker compose restart

معمولاً بهتر است فقط همان Service که تغییر کرده Restart شود.

Stop و Start کردن Stack

برای Stop:

docker compose stop

برای Start:

docker compose start

این کار Containerها را حذف نمی‌کند.

Recreate کردن Containerها

اگر فایل Compose یا Image تغییر کرده باشد:

docker compose up -d

Docker Compose در صورت تغییر Image یا Configuration، Container مربوطه را Recreate می‌کند و Mounted Volumeها را حفظ می‌کند.

تفاوت Restart و Recreate

دستور:

docker compose restart synapse

فقط همان Container موجود را Restart می‌کند.

اما:

docker compose up -d synapse

در صورت تغییر Image یا Configuration می‌تواند Container جدید ایجاد کند.

بنابراین برای Upgrade معمولاً restart کافی نیست.

فایل homeserver.yaml چیست؟

یکی از مهم‌ترین فایل‌های Synapse:

homeserver.yaml

است.

در Docker معمولاً داخل Container در مسیر:

/data/homeserver.yaml

قرار دارد.

اگر Bind Mount استفاده شده باشد ممکن است روی Host چیزی مشابه زیر داشته باشید:

./synapse/data/homeserver.yaml

چه تنظیماتی داخل homeserver.yaml قرار دارند؟

این فایل تنظیمات اصلی Synapse را کنترل می‌کند.

برای مثال:

server_name:
listeners:
database:
media_store_path:
max_upload_size:
registration_shared_secret:
trusted_key_servers:
log_config:

همچنین تنظیمات مربوط به:

• Registration
• Federation
• Media
• Authentication
• Rate Limit
• Server Notice
• Logging
• Database

در همین فایل قرار می‌گیرند.

مستندات رسمی Synapse تمام تنظیمات موجود را در Configuration Manual توضیح می‌دهند.

قبل از تغییر homeserver.yaml چه کنیم؟

همیشه Backup بگیرید.

برای مثال:

cp synapse/data/homeserver.yaml \
synapse/data/homeserver.yaml.bak.$(date +%Y-%m-%d-%H%M)

سپس:

nano synapse/data/homeserver.yaml

را اجرا کنید.

بررسی صحت homeserver.yaml

بعد از تغییر فایل، قبل از Restart می‌توان Configuration را Validate کرد:

docker exec synapse \
python -m synapse.config \
-c /data/homeserver.yaml

اگر Configuration صحیح باشد، معمولاً Error دریافت نمی‌کنید.

این روش Validation در مستندات رسمی Synapse نیز معرفی شده است.

اعمال تغییرات Synapse

بعد از Validation:

docker compose restart synapse

سپس Log را بررسی کنید:

docker compose logs -f --tail=100 synapse

اگر Error مشاهده نشد، سرویس به‌درستی بالا آمده است.

بررسی سلامت Synapse

ابتدا Container:

docker compose ps

سپس می‌توانید Client API را بررسی کنید:

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

اگر Synapse پاسخ JSON برگرداند، Client API فعال است.

Port داخلی معمول Synapse:

8008

است، هرچند ممکن است در Configuration شما متفاوت باشد. Docker Image رسمی نیز به‌صورت پیش‌فرض از Port 8008 برای HTTP استفاده می‌کند.

فایل config.json در Element

Element Web تنظیمات خود را معمولاً از:

config.json

دریافت می‌کند.

ممکن است روی Host در مسیری مانند:

./element/config.json

قرار داشته باشد و به:

/app/config.json

داخل Container متصل شود. این همان روش رسمی ارائه Configuration سفارشی به Element Web Docker است.

مهم‌ترین کاربرد config.json

Element باید بداند به کدام Homeserver متصل شود.

برای مثال ساختار آن ممکن است شامل تنظیماتی مانند:

{
  "default_server_config": {
    "m.homeserver": {
      "base_url": "https://matrix.example.com",
      "server_name": "example.com"
    }
  }
}

بعد از تغییر:

docker compose restart element

را اجرا کنید.

قابلیت‌های اصلی Element

کاربران از طریق Element می‌توانند از امکانات Matrix استفاده کنند.

از جمله:

• Direct Message
• Group Room
• Private Room
• Public Room
• End-to-End Encryption
• ارسال فایل
• ارسال عکس و ویدئو
• Reply
• Reaction
• Thread
• Search
• Notification
• Spaces
• مدیریت Deviceها
• Federation با Serverهای دیگر

بعضی قابلیت‌ها مانند تماس صوتی و تصویری به Infrastructure و تنظیمات تکمیلی Server بستگی دارند و صرف نصب Element Web و Synapse الزاماً تمام قابلیت‌های Call را فراهم نمی‌کند.

Room چیست؟

Room اصلی‌ترین فضای گفتگو در Matrix است.

Room می‌تواند:

Public
Private
Encrypted
Unencrypted

باشد.

هر Room دارای:

Room ID
Members
Power Levels
Events
Aliases
State

است.

Space چیست؟

Space را می‌توان شبیه یک مجموعه یا ساختار سازمان‌دهی برای Roomها در نظر گرفت.

برای مثال:

Company
├── Management
├── Technical
├── Sales
├── Support
└── Announcements

این قابلیت برای سازمان‌هایی که تعداد زیادی Room دارند بسیار مفید است.

Federation چیست؟

Federation اجازه می‌دهد کاربران دو Matrix Server مختلف داخل Room مشترک حضور داشته باشند.

برای مثال:

@ali:company-a.com

می‌تواند با:

@sara:company-b.com

داخل یک Room گفتگو کند، به شرط آنکه Federation Serverها فعال و قابل دسترس باشد.

مستندات Synapse توضیح می‌دهند که Federation امکان شرکت کاربران Serverهای مختلف در Room مشترک را فراهم می‌کند.

اگر Server فقط برای ارتباط داخلی شرکت استفاده می‌شود، باید تصمیم بگیرید Federation واقعاً موردنیاز است یا خیر.

مدیریت کاربران با Synapse Admin

Synapse Admin معمولاً ساده‌ترین روش مدیریت Userها است.

بعد از Login با Server Admin می‌توانید Userها را مشاهده کنید.

اطلاعاتی مانند:

User ID
Display Name
Admin Status
Account Status
Creation Time
Last Seen

قابل مشاهده هستند.

Synapse Admin API رسمی همین اطلاعات را برای Userها ارائه می‌کند.

تفاوت Server Admin و Room Admin

این دو مفهوم متفاوت هستند.

Server Admin دسترسی مدیریتی روی Synapse دارد.

اما Room Admin فقط Permission بالایی داخل یک Room مشخص دارد.

داشتن Power Level بالا داخل Room به معنی Server Administrator بودن نیست.

ایجاد Administrator جدید از Command Line

Synapse ابزار:

register_new_matrix_user

را ارائه می‌کند.

اگر registration_shared_secret در Configuration تنظیم شده باشد:

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

سپس ابزار مواردی مانند:

New user localpart
Password
Make admin

را از شما دریافت می‌کند.

Docker Image رسمی Synapse نیز همین ابزار را برای ایجاد User و Admin معرفی می‌کند.

اگر registration_shared_secret فقط برای این کار ایجاد شده، نگه داشتن غیرضروری آن توصیه نمی‌شود.

Deactivate کردن User

اگر کاربری دیگر نباید به Server دسترسی داشته باشد، بهتر است Account او Deactivate شود.

این عملیات را می‌توان از Synapse Admin یا Admin API انجام داد.

Deactivate با حذف ساده User متفاوت است و باید قبل از انجام آن وضعیت Roomها، Media و نیازهای سازمان بررسی شود.

مشاهده Roomهای یک User

Synapse Admin API امکان مشاهده Roomهایی که User عضو آنهاست را ارائه می‌کند.

این قابلیت برای مواردی مانند:

• بررسی دسترسی کاربر
• Offboarding
• Incident Investigation
• مدیریت Account

کاربرد دارد.

مدیریت Media

Media یکی از بخش‌هایی است که می‌تواند به مرور فضای Disk زیادی مصرف کند.

Synapse Admin API امکان مشاهده Media مربوط به کاربران و Roomها را فراهم می‌کند و Media می‌تواند در صورت نیاز Quarantine نیز شود.

برای بررسی Disk:

df -h

برای بررسی مصرف Directoryهای Stack:

du -sh *

یا:

du -sh synapse/data/*

مشاهده مصرف Containerها

برای بررسی CPU و RAM:

docker stats

در Serverهای پرکار معمولاً مهم‌ترین سرویس‌ها از نظر Resource عبارت‌اند از:

Synapse
PostgreSQL

اگر RAM یا CPU دائماً بالا است، Log و Database Performance باید بررسی شوند.

مشاهده فضای Docker

برای مشاهده مصرف Docker:

docker system df

این Command حجم:

Images
Containers
Volumes
Build Cache

را نمایش می‌دهد.

Backup چه چیزهایی ضروری است؟

در این Stack حداقل موارد زیر اهمیت دارند:

docker-compose.yml
homeserver.yaml
Synapse Signing Key
Element config.json
Synapse Admin config
PostgreSQL Database
Media Store
Reverse Proxy Configuration

اگر یکی از این بخش‌ها بدون Backup از بین برود، Recovery می‌تواند دشوار شود.

Backup فایل Compose

cp docker-compose.yml \
docker-compose.yml.bak.$(date +%Y-%m-%d-%H%M)

Backup تنظیمات Synapse

اگر Data Directory شما:

synapse/data

است، فایل‌های مهم Configuration را جداگانه Backup کنید.

برای مثال:

cp synapse/data/homeserver.yaml \
synapse/data/homeserver.yaml.bak.$(date +%Y-%m-%d-%H%M)

Signing Key نیز بسیار مهم است و باید در Backup نگهداری شود.

Backup Element

اگر Configuration در:

element/config.json

است:

cp element/config.json \
element/config.json.bak.$(date +%Y-%m-%d-%H%M)

Backup PostgreSQL

اگر Container Database شما postgres نام دارد، ابتدا Environment مربوط به Database را در Compose بررسی کنید.

سپس می‌توانید از pg_dump یا pg_dumpall استفاده کنید.

برای مثال:

docker exec -t postgres \
pg_dumpall -U postgres \
> postgres-backup-$(date +%Y-%m-%d).sql

Username واقعی PostgreSQL ممکن است در Stack شما متفاوت باشد.

قبل از Upgrade مهم Synapse، Backup Database ضروری است.

Update کردن Containerها چگونه انجام می‌شود؟

مهم‌ترین نکته این است:

Update کردن Docker Container یعنی دریافت Image جدید و Recreate کردن Container با همان Persistent Data.

صرف اجرای:

docker compose restart

نسخه نرم‌افزار را تغییر نمی‌دهد.

مرحله اول: نسخه‌های فعلی را ثبت کنید

قبل از Update:

docker compose images

همچنین:

docker compose ps

و:

grep -n "image:" docker-compose.yml

را ذخیره یا یادداشت کنید.

این اطلاعات برای Rollback بسیار مهم هستند.

latest بهتر است یا Version مشخص؟

دو روش وجود دارد.

روش اول:

image: matrixdotorg/synapse:latest

روش دوم:

image: matrixdotorg/synapse:vX.Y.Z

برای Production معمولاً Pin کردن نسخه مشخص کنترل بیشتری ایجاد می‌کند.

یعنی ابتدا Release Note و Upgrade Note نسخه جدید بررسی شود و سپس Tag در Compose تغییر کند.

استفاده دائمی از latest باعث می‌شود دقیقاً مشخص نباشد Update بعدی چه Versionی وارد Server خواهد کرد.

قبل از Update Synapse چه کنیم؟

برای Synapse مهم‌ترین مرحله:

خواندن Upgrade Notes از Version فعلی تا Version مقصد

است.

Synapse گاهی:

• Database Migration
• Configuration Change
• Dependency Change
• PostgreSQL Requirement
• Module Compatibility Change

دارد.

مستندات رسمی Synapse تأکید می‌کنند اگر از Version قدیمی Upgrade می‌کنید باید Upgrade Noteهای نسخه‌های بین نسخه فعلی و مقصد را بررسی کنید؛ Migrationهای Database نیز ممکن است هنگام Start انجام شوند.

بنابراین روی Server قدیمی نباید بدون بررسی مستقیماً به جدیدترین Tag Jump کنید.

Update کردن Synapse با Docker Compose

فرض کنید Tag جدید را در Compose قرار داده‌اید:

synapse:
  image: matrixdotorg/synapse:vX.Y.Z

ابتدا Image را Pull کنید:

docker compose pull synapse

دستور docker compose pull فقط Image جدید را دریافت می‌کند و Container را Start نمی‌کند.

سپس:

docker compose up -d synapse

Docker Container قبلی را در صورت تغییر Image Recreate می‌کند و Volumeهای Mount شده حفظ می‌شوند.

بعد از Update Synapse چه کنیم؟

ابتدا:

docker compose ps

سپس:

docker compose logs -f --tail=200 synapse

را اجرا کنید.

به مواردی مانند:

ERROR
CRITICAL
database migration
failed
traceback

توجه کنید.

سپس Client API را بررسی کنید:

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

در نهایت Login از Element، ارسال Message و Upload فایل را تست کنید.

Update کردن Element Web

اگر Compose از Tag مشخص استفاده می‌کند ابتدا Tag جدید را در:

docker-compose.yml

قرار دهید.

سپس:

docker compose pull element

و:

docker compose up -d element

بعد:

docker compose logs --tail=100 element

را بررسی کنید.

Element Web Docker رسمی از Image از پیش ساخته‌شده استفاده می‌کند و Configuration سفارشی را می‌توان از طریق /app/config.json به آن Mount کرد.

Update کردن Synapse Admin

ابتدا Image واقعی Stack را پیدا کنید:

docker compose config | grep -A5 synapse-admin

یا:

grep -n "synapse-admin" docker-compose.yml

ممکن است Image شما یکی از Variantهای Synapse Admin باشد.

بعد از مشخص شدن Image:

docker compose pull synapse-admin

سپس:

docker compose up -d synapse-admin

و:

docker compose logs --tail=100 synapse-admin

را بررسی کنید.

پروژه کلاسیک Synapse Admin همچنان Docker Deployment دارد و نسخه‌های جدیدتر این اکوسیستم نیز Container Image ارائه می‌کنند.

Update کردن کل Stack

اگر Versionها از قبل در Compose مشخص شده‌اند و Upgrade Noteها را بررسی کرده‌اید:

docker compose pull

سپس:

docker compose up -d

این روش تمام Imageهای تعریف‌شده را Pull و Serviceهای تغییرکرده را Recreate می‌کند.

اما روی Production معمولاً Update مرحله‌ای امن‌تر است:

1. PostgreSQL Compatibility
2. Synapse
3. Element
4. Synapse Admin
5. سایر سرویس‌ها

آیا برای Update باید docker compose down بزنیم؟

معمولاً خیر.

در بسیاری از موارد:

docker compose pull
docker compose up -d

کافی است.

استفاده غیرضروری از:

docker compose down

باعث Downtime بیشتر می‌شود.

هشدار درباره docker compose down -v

دستور زیر را برای Update معمولی اجرا نکنید:

docker compose down -v

گزینه:

-v

Volumeهای تعریف‌شده توسط Compose را نیز حذف می‌کند. Docker نیز صراحتاً --volumes را برای حذف Volumeها معرفی می‌کند.

اگر Database یا Media داخل Volume باشند، این کار می‌تواند باعث از دست رفتن داده شود.

چگونه بفهمیم Update واقعاً انجام شده است؟

بعد از Update:

docker compose images

را اجرا کنید.

همچنین:

docker inspect synapse --format '{{.Config.Image}}'

برای مشاهده Image Synapse:

docker inspect element --format '{{.Config.Image}}'

برای Element قابل استفاده است.

نام Container ممکن است در Server شما متفاوت باشد.

حذف Imageهای قدیمی بعد از Update

پس از اینکه مطمئن شدید Stack سالم است:

docker image prune

می‌تواند Imageهای Dangling را پاک کند.

برای پاک‌سازی تهاجمی‌تر عجله نکنید، زیرا نگه داشتن Image قبلی برای Rollback اولیه مفید است.

Rollback چگونه انجام می‌شود؟

فرض کنید Synapse قبلاً:

image: matrixdotorg/synapse:vOLD

بوده و به:

image: matrixdotorg/synapse:vNEW

Upgrade شده است.

برای Rollback می‌توان Tag قبلی را در Compose برگرداند و اجرا کرد:

docker compose up -d synapse

اما این نکته بسیار مهم است:

Rollback Synapse همیشه فقط با برگرداندن Docker Image امن نیست.

ممکن است Version جدید Database Migration انجام داده باشد که Version قدیمی با آن سازگار نباشد.

به همین دلیل Database Backup قبل از Upgrade اهمیت زیادی دارد و Upgrade Notes باید بررسی شوند.

امنیت Synapse Admin

Synapse Admin یک پنل مدیریتی حساس است.

بهتر است:

• فقط از HTTPS در دسترس باشد.
• در صورت امکان IP Restriction داشته باشد.
• مستقیماً بدون Reverse Proxy روی اینترنت منتشر نشود.
• Server Admin Account دارای Password قوی باشد.
• دسترسی آن محدود به Administratorها باشد.

Synapse Admin با Token یک Server Administrator به Admin API دسترسی پیدا می‌کند؛ بنابراین افشای Credential مدیریتی خطر بالایی دارد.

امنیت Port 8008

Synapse معمولاً داخل Container روی:

8008

گوش می‌دهد.

در معماری Production بهتر است کاربران مستقیماً از اینترنت به این Port متصل نشوند و ارتباط عمومی از طریق Reverse Proxy و HTTPS انجام شود.

مستندات رسمی Synapse نیز استفاده از Reverse Proxy را برای قرار دادن TLS در جلوی Synapse توصیه می‌کنند.

تنظیم Healthcheck

برای Synapse می‌توان Healthcheck تعریف کرد.

برای مثال:

healthcheck:
  test: ["CMD", "curl", "-fSs", "http://localhost:8008/health"]
  interval: 15s
  timeout: 5s
  retries: 3
  start_period: 5s

Docker Image رسمی Synapse نمونه مشابهی برای Healthcheck ارائه می‌کند.

سپس:

docker compose ps

می‌تواند وضعیت:

healthy

را نمایش دهد.

Monitoring چه چیزهایی مهم است؟

برای Server Matrix حداقل موارد زیر مانیتور شوند:

• CPU
• RAM
• Disk Usage
• PostgreSQL
• Container Status
• Synapse HTTP Availability
• TLS Certificate
• Media Store Size
• Database Size
• Backup Status

همچنین بهتر است Alert برای Down شدن Containerها ایجاد شود.

مشکلات رایج

برخی مشکلات متداول در مدیریت این Stack عبارت‌اند از:

• اشتباه در YAML فایل homeserver.yaml
• خراب شدن config.json Element
• پر شدن Disk توسط Media
• PostgreSQL Connection Error
• Permission اشتباه روی Volume
• Update بدون Backup
• Update جهشی از Version بسیار قدیمی
• حذف Volume هنگام docker compose down -v
• Publish شدن Portهای مدیریتی روی اینترنت
• Restart نکردن Synapse بعد از تغییر Configuration
• استفاده از latest بدون ثبت Version قبلی
• Update کردن Synapse بدون مطالعه Upgrade Notes

بهترین روش‌ها

برای مدیریت صحیح Server:

• همیشه Docker Compose File را Version Control یا Backup کنید.
• قبل از تغییر homeserver.yaml Backup بگیرید.
• Configuration را قبل از Restart Validate کنید.
• PostgreSQL را به‌صورت منظم Backup کنید.
• Media Store را Backup کنید.
• Signing Key را خارج از Server نیز نگهداری کنید.
• Updateها را مرحله‌ای انجام دهید.
• Versionها را در Production Pin کنید.
• قبل از Synapse Upgrade، Upgrade Notes را مطالعه کنید.
• Logها را بعد از هر Update بررسی کنید.
• Admin Panel را محدود کنید.
• Disk Usage را مانیتور کنید.
• از اجرای docker compose down -v بدون شناخت کامل اثر آن خودداری کنید.

Workflow پیشنهادی برای Update امن

برای Update یک Server Production این ترتیب مناسب است.

مرحله اول: مشاهده وضعیت

cd ~/matrix-stack
docker compose ps
docker compose images

مرحله دوم: Backup Compose

cp docker-compose.yml \
docker-compose.yml.bak.$(date +%Y-%m-%d-%H%M)

مرحله سوم: Backup Synapse Config

cp synapse/data/homeserver.yaml \
synapse/data/homeserver.yaml.bak.$(date +%Y-%m-%d-%H%M)

مرحله چهارم: Backup Database

docker exec -t postgres \
pg_dumpall -U postgres \
> postgres-before-upgrade-$(date +%Y-%m-%d).sql

نام Container و PostgreSQL User را با Environment واقعی خود جایگزین کنید.

مرحله پنجم: Upgrade Notes

Version فعلی Synapse را با Version مقصد مقایسه کنید و تمام Upgrade Noteهای میان آنها را بخوانید.

مرحله ششم: تغییر Tag

در:

docker-compose.yml

Version جدید Stable را وارد کنید.

مرحله هفتم: Pull

docker compose pull synapse

مرحله هشتم: Recreate

docker compose up -d synapse

مرحله نهم: بررسی Log

docker compose logs -f --tail=200 synapse

مرحله دهم: تست API

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

مرحله یازدهم: تست واقعی

از Element:

Login
Send Message
Receive Message
Upload File
Open Room

را تست کنید.

مرحله دوازدهم: Update Element و Admin

docker compose pull element synapse-admin
docker compose up -d element synapse-admin

در پایان:

docker compose ps

را دوباره بررسی کنید.

چک‌لیست مدیریت سرور Element

موارد زیر را به‌صورت دوره‌ای بررسی کنید:

• تمام Containerها Running هستند.
• Synapse Healthy است.
• PostgreSQL فعال است.
• Element به Synapse متصل می‌شود.
• Synapse Admin قابل Login است.
• Disk فضای کافی دارد.
• Media Store بیش از حد بزرگ نشده است.
• Database Backup سالم است.
• homeserver.yaml Backup دارد.
• Signing Key Backup دارد.
• TLS Certificate معتبر است.
• Docker Imageها بیش از حد قدیمی نیستند.
• Upgrade Notes بررسی شده‌اند.
• Synapse Admin فقط برای Administratorها قابل دسترس است.
• Portهای غیرضروری روی اینترنت Publish نشده‌اند.
• Logها Error جدی ندارند.

مطالعات بیشتر

برای مطالعه بیشتر درباره Element، Synapse، Synapse Admin و Docker می‌توانید از منابع رسمی زیر استفاده کنید:

• Element Web – Docker Installation
  نحوه اجرای Element Web با Docker، Mount کردن config.json و تنظیم Container.
  مستندات رسمی Element Web
• Synapse Docker Image
  مستندات Docker Image رسمی Synapse، Volumeها، /data، Port 8008، ایجاد Administrator و Healthcheck.
  Synapse Docker Image
• Synapse Administration
  راهنمای رسمی مدیریت User، Room، Media، Monitoring و Logging.
  Synapse Administration Documentation
• Synapse Configuration Manual
  مرجع تنظیمات homeserver.yaml و روش Validate کردن Configuration.
  Synapse Configuration Manual
• Synapse Upgrade Documentation
  مهم‌ترین مرجع قبل از Update کردن Synapse و بررسی Database Migrationها و تغییرات Versionها.
  Synapse Upgrade Notes
• Synapse Admin API
  مستندات APIهای مدیریتی Synapse.
  Synapse Admin API
• Synapse Admin
  پنل مدیریتی برای Synapse و روش اجرای Docker آن.
  Synapse Admin GitHub
• Docker Compose Pull
  نحوه دریافت Image جدید Serviceها.
  Docker Compose Pull Documentation
• Docker Compose Up
  نحوه Recreate کردن Containerها بعد از تغییر Image یا Configuration.
  Docker Compose Up Documentation

جمع‌بندی

یک Server Element مبتنی بر Docker در واقع از چند بخش مستقل تشکیل شده است.

Element Web رابطی است که کاربران مشاهده می‌کنند.

Synapse هسته اصلی Matrix Homeserver است و کاربران، Roomها، Eventها، Media، Federation و APIها را مدیریت می‌کند.

Synapse Admin رابط مدیریتی است که عملیات Admin API را ساده‌تر می‌کند.

و در محیط Production معمولاً PostgreSQL نیز Database اصلی Synapse است.

برای مدیریت روزمره Stack، دستورات زیر از مهم‌ترین Commandها هستند:

docker compose ps

برای مشاهده وضعیت Containerها،

docker compose logs -f synapse

برای بررسی Log،

و:

docker compose restart synapse

برای Restart سرویس.

اما برای Update باید تفاوت مهمی را در نظر داشت:

docker compose restart

نسخه نرم‌افزار را Update نمی‌کند.

برای دریافت Image جدید باید از:

docker compose pull

و سپس:

docker compose up -d

استفاده شود.

در مورد Synapse، Update باید با احتیاط بیشتری انجام شود. قبل از تغییر Version باید Database Backup گرفته شود، Upgrade Notes بین نسخه فعلی و نسخه جدید مطالعه شوند و سپس Container جدید اجرا شود.

در Production بهتر است به‌جای استفاده بدون کنترل از Tag:

latest

Version Stable مشخصی در docker-compose.yml ثبت شود تا Upgradeها قابل پیش‌بینی و Rollback آنها قابل مدیریت باشند.

همچنین Persistent Dataهایی مانند:

PostgreSQL Database
Media Store
homeserver.yaml
Signing Key
Element config.json

باید مستقل از Container نگهداری و Backup شوند.

در نهایت، مهم‌ترین اصل در مدیریت این Server این است که Container قابل تعویض است، اما Data و Configuration ارزش واقعی سرویس هستند. اگر Volumeها، Database، Signing Key و Configuration به‌درستی مدیریت و Backup شوند، Update و Recovery Stack بسیار ساده‌تر و کم‌ریسک‌تر خواهد بود.

کیان پور