پیکربندی

محل نگهداری تنظیمات Antimatter، سه روش تغییر آن‌ها (کنسول سیستم، متغیرهای محیطی، amctl) و محل ذخیره لاگ‌ها.

محل نگهداری تنظیمات

هر تنظیم سرور نامی دارد که از یک بخش و یک کلید تشکیل شده، مانند ServiceSettings.SiteURL یا EmailSettings.SMTPServer. این دو با هم یک پیکربندی را تشکیل می‌دهند که در یکی از دو محل ذخیره می‌شود:

در پایگاه داده. فایل compose سایت مقدار AM_CONFIG را به URL اتصال PostgreSQL تنظیم می‌کند، بنابراین پیکربندی یک ردیف در پایگاه داده است و کانتینر چیزی روی دیسک نگه نمی‌دارد. چندین سرور که یک پایگاه داده را به اشتراک می‌گذارند، پیکربندی خود را نیز به اشتراک می‌گذارند.
در یک فایل. بدون AM_CONFIG، سرور فایل config/config.json را در کنار دایرکتوری bin/ خود (در تصویر Docker در مسیر /antimatter/config/config.json) می‌خواند. آرشیو نسخه انتشار و فایل‌های compose تولیدی antimatter-docker به همین شیوه کار می‌کنند، همچنین بسته‌های .deb و .rpm که فایل پیکربندی آن‌ها در /etc/antimatter/config/config.json قرار دارد. این فایل را فقط برای کاربر سرور خوانا نگه دارید؛ زیرا حاوی گذرواژه‌ها و کلیدهای امنیتی است.

AM_CONFIG (یا پرچم --config دستور antimatter) می‌تواند یک مسیر فایل یا یک URL postgres:// را بپذیرد. تنظیماتی که خالی بگذارید، مقدار پیش‌فرض خود را می‌گیرند.

برای جابه‌جایی یک پیکربندی موجود از فایل به پایگاه داده، این دستور را روی سرور اجرا کنید، سپس سرور را با AM_CONFIG تنظیم‌شده روی همان URL راه‌اندازی کنید:

amctl --local config migrate /opt/antimatter/config/config.json \
    "postgres://antimatter:PASSWORD@localhost:5432/antimatter?sslmode=disable&connect_timeout=10"

متغیرهای محیطی

هر تنظیمی می‌تواند به صورت یک متغیر محیطی نیز داده شود. متغیرها بر پیکربندی ذخیره‌شده اولویت دارند، بنابراین برای مواردی که به استقرار (deployment) تعلق دارند مناسب‌اند: پایگاه داده، URL سایت، ذخیره‌سازی فایل و پورت‌ها.

قانون نام‌گذاری

ابتدا AM_ را بنویسید، سپس بخش، و سپس کلید را با حروف بزرگ و جدا شده با خط زیر. کلمات داخل نام بخش یا کلید جدا نمی‌شوند:

تنظیم	متغیر
`ServiceSettings.SiteURL`	`AM_SERVICESETTINGS_SITEURL`
`SqlSettings.DataSource`	`AM_SQLSETTINGS_DATASOURCE`
`EmailSettings.SMTPServer`	`AM_EMAILSETTINGS_SMTPSERVER`
`PrivacySettings.EnableUserBlocking`	`AM_PRIVACYSETTINGS_ENABLEUSERBLOCKING`

تنظیمات صحیح و نادرست (true/false) مقدار true یا false می‌گیرند؛ اعداد به صورت اعداد ساده هستند.
تنظیمات فهرستی (List) مقادیر خود را با فاصله جدا می‌گیرند، برای مثال AM_SERVICESETTINGS_TRUSTEDPROXYIPHEADER="X-Forwarded-For X-Real-IP".
تنظیماتی که اشیاء (objects) هستند، JSON می‌گیرند. تنها متغیر محیطی از این نوع برای اپلیکیشن‌ها AM_PLUGINSETTINGS_PLUGINS است و تنظیمات همه اپلیکیشن‌ها را یکجا جایگزین می‌کند: به جای آن، تنظیمات اپلیکیشن‌ها را در کنسول سیستم یا با amctl تنظیم کنید (در ادامه).
پیکربندی‌های قدیمی Mattermost از پیشوند MM_ استفاده می‌کنند، برای مثال MM_SQLSETTINGS_DATASOURCE. این پیشوند همچنان به‌عنوان یک نام جایگزین قدیمی کار می‌کند. در صورتی که هر دو متغیر تنظیم شده باشند، متغیر AM_ اولویت دارد.

تنظیماتی که از طریق متغیر تعیین شده باشند، در کنسول سیستم قفل می‌شوند و با یادداشت «این تنظیم از طریق یک متغیر محیطی تعیین شده است. نمی‌توان آن را از طریق کنسول سیستم تغییر داد.» نمایش داده می‌شوند. این تنظیم به پیکربندی ذخیره‌شده نوشته نمی‌شود؛ متغیر را حذف کنید تا مقدار ذخیره‌شده دوباره اعمال شود.

با Docker Compose

متغیرها را در بخش environment: سرویس antimatter اضافه کنید، یا در یک فایل compose.override.yaml در کنار compose.yaml (Compose به‌طور خودکار آن را می‌خواند و در به‌روزرسانی‌های فایل دانلودشده باقی می‌ماند):

services:
  antimatter:
    environment:
      AM_EMAILSETTINGS_SMTPSERVER: smtp.example.com
      AM_EMAILSETTINGS_SMTPPORT: "587"
      AM_LOGSETTINGS_CONSOLELEVEL: INFO

تغییرات را با docker compose up -d اعمال کنید که کانتینر را دوباره ایجاد می‌کند.

متغیرهایی که توسط برنامه‌ها خوانده می‌شوند

چند متغیر تنظیم نیستند و فیلدی در کنسول سیستم ندارند: AM_CONFIG (محل قرارگیری پیکربندی) و AM_AI_ENCRYPTION_KEY و AM_AI_ENCRYPTION_PREVIOUS_KEYS، کلیدی که کلیدهای API اتصالات مدل‌ها را رمزگذاری می‌کند (به هوش مصنوعی مراجعه کنید).

چند برنامه متغیرهای خاص خود را که روی سرویس antimatter تنظیم شده‌اند، می‌خوانند: برنامه مکالمه‌ها AM_CALLS_* را می‌خواند (به مکالمه‌ها و صدا مراجعه کنید) و برنامه GIFs AM_GIFS_SERVICE_URL، AM_GIFS_API_KEY و AM_GIFS_UPLOAD_KEY را می‌خواند (به برنامه‌های همراه مراجعه کنید).

کنسول سیستم

کنسول سیستم بخش مدیریت اپلیکیشن وب برای مدیران سیستم است. برای باز کردن آن، روی عکس خود در بالای نوار اپلیکیشن کلیک کنید و کنسول سیستم را انتخاب کنید، یا به https://chat.example.com/admin_console بروید. نوار کناری آن جعبه‌ای به نام تنظیمات را پیدا کنید دارد که در تمام صفحات جستجو می‌کند.

The System Console, with its sidebar of sections on the left and the SAML 2.0 settings page on the right. — کنسول سیستم. نوار کناری صفحات را در بخش‌هایی مانند گزارش نویسی، مدیریت کاربر و محیط گروه‌بندی می‌کند.

بخش‌های آن عبارتند از:

گزارش نویسی: آمار و لاگ‌های سرور.
مدیریت کاربر: کاربران، گروه‌ها، جوامع (به‌عنوان تیم‌ها فهرست شده)، کانال‌ها، مجوزها و مدیریت تفویض‌شده.
ویژگی‌های سیستم: ویژگی‌های سفارشی پروفایل و دسترسی مبتنی بر ویژگی.
محیط: سرور وب، پایگاه داده، ذخیره‌سازی فایل، پروکسی تصویر، SMTP، اعلان‌های push، محدودیت نرخ، لاگ‌نویسی، مدت زمان نشست‌ها و پایش عملکرد.
پیکربندی سایت: برندینگ، کاربران و تیم‌ها، اعلان‌ها، پست‌ها، اشتراک‌گذاری فایل و سایر رفتارهای سراسری سرور.
احراز هویت: ثبت‌نام، ورود با ایمیل و رمز عبور، MFA، AD/LDAP، SAML 2.0، OAuth 2.0، OpenID Connect و دسترسی مهمان.
هوش مصنوعی: اتصالات مدل‌ها و قابلیت‌های داخلی هوش مصنوعی (بازنویسی، خلاصه‌سازی، ترجمه خودکار، تبدیل متن به گفتار). به هوش مصنوعی مراجعه کنید.
پلاگین ها: مدیریت برنامه‌ها و تنظیمات هر برنامه نصب‌شده.
ادغام ها: وب‌هوک‌ها، دستورات اسلش، حساب‌های ربات، GIFs، تبدیل متن به گفتار، CORS.
انطباق: نگهداری داده‌ها، خروجی انطباق و پایش، ثبت رویدادهای ممیزی، و شرایط استفاده سفارشی.
تجربی: ویژگی‌هایی که ممکن است تغییر کنند.

در این راهنما، هر تنظیم به‌صورت مسیر آن در کنسول سیستم، سپس برچسب آن، و در نهایت کلید پیکربندی نوشته می‌شود؛ برای مثال کنسول سیستم › پیکربندی سایت › کاربران و تیم ها › فعال‌سازی نادیده‌گرفتن، مسدودسازی و درخواست پیام (PrivacySettings.EnableUserBlocking).

بیشتر تغییرات به‌محض کلیک روی صرفه جویی اعمال می‌شوند. برخی از تنظیمات (مانند آدرس گوش‌دهی، برخی تنظیمات پایگاه داده و کش) به راه‌اندازی مجدد نیاز دارند و صفحه مربوطه این نکته را ذکر می‌کند.

انجمن یا فضای کاری

هر جامعه نوعی دارد که برخی پیش‌فرض‌های آن را تعیین می‌کند:

انجمن، برای جوامع عمومی یا سرگرمی: مکالمه‌ها در کانال‌های آن غیرفعال است (افراد در کانال‌های صوتی صحبت می‌کنند) و فقط مدیران آن و نقش‌هایی که کانال‌ها را مدیریت می‌کنند، می‌توانند کانال‌ها را بایگانی کنند.
فضای کاری، برای شرکت‌ها یا سازمان‌ها: مکالمه‌ها در کانال‌های آن فعال است و مدیران کانال (هر کسی که آن را ایجاد کرده و کسانی که او به عنوان مدیر تعیین کرده است) نیز می‌توانند آن را بایگانی کنند.

کنسول سیستم › پیکربندی سایت › کاربران و تیم ها › نوع جوامع جدید (TeamSettings.DefaultCommunityKind, AM_TEAMSETTINGS_DEFAULTCOMMUNITYKIND) نوع جوامعی است که از آن به بعد ایجاد می‌شوند: انجمن (پیش‌فرض) یا فضای کاری؛ این تنظیم همچنان مقادیر قدیمی‌تر community و workplace را ذخیره و خوانده می‌کند. یک پیش‌تنظیم چیدمان که هنگام ایجاد یک جامعه انتخاب می‌شود، نوع خود را تعیین می‌کند. مدیران هر جامعه می‌توانند نوع آن را بعداً در تنظیمات تیم › عمومی تغییر دهند. انجمن‌های جدید همه را در هر کانال قرار می‌دهند (TeamSettings.AllChannelsMembershipForNewTeams) فقط برای انجمن‌های جدید پیش‌فرض است: فضاهای کاری هرگز به این شکل شروع نمی‌شوند (به همه در هر کانال مراجعه کنید).

برای یک شرکت، قبل از ایجاد اولین جامعه یا قبل از ارتقای یک سرور موجود به نسخه 0.9.0، آن را روی فضای کاری تنظیم کنید: ارتقا به هر جامعه موجود، مقداری را که تنظیم در آن لحظه دارد می‌دهد (به ارتقا به 0.9.0 مراجعه کنید).

پیام‌های سوزانده‌شده پس از خواندن

افراد می‌توانند پیام‌هایی ارسال کنند که مدتی پس از باز شدن توسط هر خواننده حذف می‌شوند (به پیام‌های با قابلیت حذف پس از خواندن مراجعه کنید). تنظیمات در کنسول سیستم › پیکربندی سایت › پست‌ها، زیر پیام‌های با قابلیت حذف پس از خواندن قرار دارند:

تنظیم	کلید و متغیر	مقدار پیش‌فرض
فعال‌سازی پیام‌های سوزان‌شونده پس از خواندن	`ServiceSettings.EnableBurnOnRead`, `AM_SERVICESETTINGS_ENABLEBURNONREAD`	روشن
مدت زمان سوزان‌شونده پس از خواندن: مدت زمانی که یک پیام پس از باز شدن دوام می‌آورد، زمانی که فرستنده مدت زمانی را انتخاب نکرده است	`ServiceSettings.BurnOnReadDurationSeconds`, `AM_SERVICESETTINGS_BURNONREADDURATIONSECONDS`	600 (10 دقیقه)
طولانی‌ترین مدتی که فرستندگان می‌توانند انتخاب کنند: از 1 ساعت تا 7 روز؛ انتخاب طولانی‌تر به این مقدار کوتاه می‌شود	`ServiceSettings.BurnOnReadMaximumDurationSeconds`, `AM_SERVICESETTINGS_BURNONREADMAXIMUMDURATIONSECONDS`	86400 (1 روز)
حداکثر زمان ماندگاری پیام‌های «سوزانده‌شده پس از خواندن»: یک پیام این مدت پس از ارسال حذف می‌شود، حتی اگر همه آن را نخوانده باشند	`ServiceSettings.BurnOnReadMaximumTimeToLiveSeconds`, `AM_SERVICESETTINGS_BURNONREADMAXIMUMTIMETOLIVESECONDS`	604800 (7 روز)

طولانی‌ترین مدت زمانی که انتخاب شده است هنگام خوانده شدن پیام دوباره بررسی می‌شود، بنابراین کاهش آن باعث کوتاه شدن مدت پیام‌های از قبل ارسال شده نیز می‌شود.

ابزار خط فرمان amctl

amctl سرور را از خط فرمان مدیریت می‌کند: کاربران، جوامع، کانال‌ها، برنامه‌ها، پیکربندی، وظایف و موارد دیگر. این ابزار به یکی از دو روش با سرور ارتباط برقرار می‌کند.

حالت محلی، روی سرور

حالت محلی به amctl اجازه می‌دهد بدون ورود به سیستم، از طریق یک سوکت یونیکس با سرور ارتباط برقرار کند. این حالت در تصویر Docker و بسته‌های .deb و .rpm به‌طور پیش‌فرض فعال است. اگر سرور را از یک آرشیو نصب کرده‌اید، می‌توانید آن را با تنظیم ServiceSettings.EnableLocalMode (AM_SERVICESETTINGS_ENABLELOCALMODE=true) فعال کنید. مسیر پیش‌فرض سوکت /var/tmp/antimatter_local.socket است (ServiceSettings.LocalModeSocketLocation).

# with Docker Compose
docker compose exec antimatter amctl --local system status
# with a release archive
sudo -u antimatter /opt/antimatter/bin/amctl --local system status
# with the .deb or .rpm package
sudo -u antimatter amctl --local system status

هر کس که بتواند از سوکت استفاده کند یا دستور docker compose exec را روی میزبان اجرا کند، دسترسی کامل مدیر سیستم را دارد.

دورانی، با یک حساب کاربری

از هر دستگاهی، با یک حساب مدیر سیستم (یا یک توکن دسترسی شخصی) وارد شوید، سپس دستورات را روی آن سرور اجرا کنید:

amctl auth login https://chat.example.com --name prod --username admin
amctl system status

دستورات پیکربندی

دستور	عملکرد
`amctl config get ServiceSettings.SiteURL`	یک تنظیم را چاپ می‌کند.
`amctl config set TeamSettings.EnableOpenServer false`	یک تنظیم را تغییر می‌دهد. تنظیمات لیست یک مقدار یا چند مقدار را می‌پذیرند.
`amctl config patch settings.json`	یک فایل JSON شامل تنظیمات را با پیکربندی ادغام می‌کند.
`amctl config show`	کل پیکربندی را به‌صورت JSON چاپ می‌کند.
`amctl config edit`	پیکربندی را در ویرایشگر شما (`$EDITOR`) باز می‌کند.
`amctl config reset`	تنظیمات را به مقادیر پیش‌فرض بازمی‌گرداند.
`amctl config reload`	پیکربندی را از محل ذخیره‌سازی بارگذاری مجدد می‌کند، پس از تغییری که خارج از سرور انجام شده است.

تنظیمات برنامه‌ها زیر PluginSettings.Plugins.<app id> قرار دارند و کلیدها با حروف کوچک نوشته می‌شوند. برای مثال، برای تنظیم آدرس سرویس و کلید برنامه GIFs از میزبان Docker:

docker compose exec -T antimatter amctl --local config patch /dev/stdin <<'EOF'
{"PluginSettings": {"Plugins": {"com.antimatterchat.gifs": {
  "serviceurl": "http://gifs:8080/v2",
  "apikey": "the GIFS_API_KEY of your .env"
}}}}
EOF

دستورات مفید دیگر: amctl user create، amctl user deactivate، amctl team create، amctl plugin list، amctl plugin enable، amctl system supportpacket و amctl logs. برای مشاهده گزینه‌های هر دستور، amctl help <command> را اجرا کنید.

لاگ‌ها

سرور گزارش‌های خود را در دو مکان می‌نویسد؛ هر کدام دارای سطح اختصاصی (DEBUG، INFO، WARN یا ERROR) است که در کنسول سیستم › محیط › ورود به سیستم تنظیم می‌شود:

مقصد	تنظیمات	مقادیر پیش‌فرض
کنسول (خروجی استاندارد)	گزارش های خروجی به کنسول (`LogSettings.EnableConsole`)، سطح گزارش کنسول (`LogSettings.ConsoleLevel`)، گزارش های کنسول خروجی به صورت JSON (`LogSettings.ConsoleJson`)	روشن، `DEBUG`، JSON
فایل، `antimatter.log`	خروجی گزارش‌ها به فایل (`LogSettings.EnableFile`)، سطح گزارش فایل (`LogSettings.FileLevel`)، پوشه ردپای پرونده‌ها (`LogSettings.FileLocation`)	روشن، `INFO`، پوشه `logs/` در کنار `bin/`

فایل‌های گزارش در ۱۰۰ مگابایت چرخش داده می‌شوند و فایل‌های قدیمی فشرده می‌شوند.

فایل compose سایت، گزارش‌دهی فایل را غیرفعال می‌کند (AM_LOGSETTINGS_ENABLEFILE=false)، بنابراین گزارش‌ها فقط در خروجی کانتینر موجود هستند:

docker compose logs -f antimatter
docker compose logs --since 1h antimatter | grep -i error

سطح پیش‌فرض کنسول روی DEBUG تنظیم شده است که بسیار جزئی است. روی سرورهای پرمشغله، مقدار AM_LOGSETTINGS_CONSOLELEVEL=INFO را تنظیم کنید. فایل config.json موجود در آرشیو انتشار و بسته‌ها از پیش روی INFO تنظیم شده است. در صورت استفاده از آرشیو انتشار زیر systemd، خروجی کنسول به ژورنال (journalctl -u antimatter) و فایل لاگ به /opt/antimatter/logs/antimatter.log نوشته می‌شود. بسته‌ها لاگ‌نویسی فایل را غیرفعال می‌کنند، بنابراین لاگ‌های آن‌ها فقط در ژورنال موجود است.

فایل‌های لاگ و ممیزی باید در داخل ریشه ثبت لاگ، یعنی AM_LOG_PATH (مقدار قدیمی‌تر MM_LOG_PATH نیز همچنان کار می‌کند) اگر تنظیم شده باشد، در غیر این صورت در پوشه logs قرار گیرند. این الزام به طور پیش‌فرض فعال است: اگر پوشه ردپای پرونده‌ها، هدف لاگ‌نویسی پیشرفته، یا مسیر لاگ ممیزی خارج از ریشه باشد، سرور در هنگام راه‌اندازی متوقف می‌شود و در زمان ذخیره تنظیمات نیز رد می‌شود. برای غیرفعال کردن این الزام از AM_FEATUREFLAGS_ENFORCELOGPATHROOT=false استفاده کنید. اگر AM_LOG_PATH تنظیم شده باشد و پوشه ردپای پرونده‌ها خالی رها شده باشد، لاگ‌ها در AM_LOG_PATH ذخیره می‌شوند.

وقتی لاگ‌نویسی فایل فعال است، مدیران سیستم می‌توانند لاگ را در کنسول سیستم › گزارش نویسی › گزارش های سرور نیز بخوانند: نشان‌های سطح با رنگ‌بندی، فیلترهای سریع بر اساس سطح، دنبال کردن زنده، و پیش‌تنظیم‌های بازه زمانی از ۵ دقیقه تا ۲۴ ساعت، یا با استفاده از amctl logs.