설정

Antimatter가 설정을 저장하는 위치, 설정을 변경하는 세 가지 방법(시스템 콘솔, 환경 변수, amctl), 그리고 로그가 기록되는 위치.

설정이 저장되는 위치

서버 설정의 이름은 섹션과 키로 구성되며, ServiceSettings.SiteURL 또는 EmailSettings.SMTPServer와 같습니다. 이 둘이 결합되어 하나의 설정을 형성하며, 다음 두 곳 중 한 곳에 저장됩니다:

• 데이터베이스에. 사이트의 compose 파일이 AM_CONFIG를 PostgreSQL 연결 URL로 설정하므로, 설정은 데이터베이스의 한 행이 되고 컨테이너는 디스크에 아무것도 저장하지 않습니다. 하나의 데이터베이스를 공유하는 여러 서버는 설정도 함께 공유합니다.
• 파일로 설정하는 경우. AM_CONFIG가 없으면 서버는 bin/ 디렉터리 옆의 config/config.json 파일을 읽습니다(Docker 이미지에서는 /antimatter/config/config.json). 릴리스 아카이브와 antimatter-docker의 프로덕션 compose 파일, 그리고 .deb와 .rpm 패키지도 이 방식으로 동작하며, 패키지 파일의 경로는 /etc/antimatter/config/config.json입니다. 이 파일에는 비밀번호와 키가 포함되어 있으므로 서버 사용자만 읽을 수 있도록 설정하세요.

AM_CONFIG(또는 antimatter 명령의 --config 플래그)는 파일 경로 또는 postgres:// URL을 둘 다 받아들입니다. 명시하지 않은 설정은 기본값을 사용합니다.

기존 설정을 파일에서 데이터베이스로 이동하려면 서버에서 다음을 실행한 후, AM_CONFIG를 동일한 URL로 설정하여 서버를 시작하세요:

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

환경 변수

모든 설정을 환경 변수로도 지정할 수 있습니다. 환경 변수는 저장된 설정보다 우선하므로, 배포에 속하는 항목(데이터베이스, 사이트 URL, 파일 저장소, 포트)에 적합합니다.

이름 규칙

AM_를 쓰고, 섹션을 쓰고, 키를 대문자와 밑줄로 구분하여 씁니다. 섹션 또는 키 이름 안의 단어는 구분되지 않습니다:

• 참/거짓 설정은 true 또는 false를, 숫자는 일반 숫자를 사용합니다.
• 목록 설정은 값을 공백으로 구분하여 지정합니다. 예를 들어 AM_SERVICESETTINGS_TRUSTEDPROXYIPHEADER="X-Forwarded-For X-Real-IP".
• 객체인 설정은 JSON을 사용합니다. 앱에 해당되는 유일한 변수는 AM_PLUGINSETTINGS_PLUGINS이며, 이 변수는 모든 앱의 설정을 한 번에 대체합니다: 대신 시스템 콘솔 또는 amctl로 앱 설정을 설정하세요(아래 참조).
• 구형 Mattermost 설정은 MM_ 접두사를 사용합니다. 예를 들어 MM_SQLSETTINGS_DATASOURCE입니다. 이는 레거시 별칭으로 여전히 동작합니다. 두 변수가 모두 설정된 경우 AM_ 변수가 우선합니다.

환경 변수로 설정된 항목은 시스템 콘솔에서 잠금 처리되며, "이 설정은 환경 변수를 통해 설정되었습니다. 시스템 콘솔을 통해 변경할 수 없습니다."라는 주석이 표시됩니다. 저장된 설정 파일에는 기록되지 않으며, 환경 변수를 제거하면 다시 저장된 값이 적용됩니다.

Docker Compose 사용 시

antimatter 서비스의 environment: 아래에 변수를 추가하거나, compose.yaml 옆에 compose.override.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(설정 파일 위치)와, 모델 연결의 API 키를 암호화하는 키인 AM_AI_ENCRYPTION_KEY 및 AM_AI_ENCRYPTION_PREVIOUS_KEYS(AI 참고)가 해당됩니다.

일부 앱은 antimatter 서비스에 설정된 자체 변수를 읽습니다. Calls 앱은 AM_CALLS_*를 읽으며(자세한 내용은 통화와 음성 참조), GIFs 앱은 AM_GIFS_SERVICE_URL, AM_GIFS_API_KEY, AM_GIFS_UPLOAD_KEY를 읽습니다(자세한 내용은 기본 제공 앱 참조).

시스템 콘솔

시스템 콘솔은 웹 앱의 관리 영역으로, 시스템 관리자를 위한 것입니다. 열려면 앱 레일 상단의 프로필 사진을 클릭하고 시스템 콘솔을 선택하거나, https://chat.example.com/admin_console로 이동하세요. 사이드바에는 모든 페이지를 검색할 수 있는 검색 설정 상자가 있습니다.

섹션은 다음과 같습니다:

• 리포팅: 통계 및 서버 로그.
• 사용자 관리: 사용자, 그룹, 커뮤니티(팀으로 나열됨), 채널, 권한 및 위임 관리.
• 시스템 속성: 사용자 정의 프로필 속성 및 속성 기반 접근 제어.
• 환경: 웹 서버, 데이터베이스, 파일 저장소, 이미지 프록시, SMTP, 푸시 알림, 속도 제한, 로깅, 세션 길이, 성능 모니터링.
• 사이트 구성: 브랜딩, 팀과 사용자, 알림, 게시물, 파일 공유 및 기타 서버 전체 동작 설정.
• 인증: 가입, 이메일 및 비밀번호 로그인, MFA, AD/LDAP, SAML 2.0, OAuth 2.0, OpenID Connect 및 게스트 접근.
• AI: 모델 연결 및 내장 AI 기능(문장 다듬기, 요약, 자동 번역, 텍스트 음성 변환). AI 참고.
• 플러그인: 앱 관리 및 각 설치된 앱의 설정.
• 통합: 웹훅, 슬래시 명령, 봇 계정, GIF, 텍스트 음성 변환, CORS.
• 컴플라이언스: 데이터 보존, 컴플라이언스 내보내기 및 모니터링, 감사 로그, 사용자 정의 서비스 약관.
• 실험용: 변경될 수 있는 기능.

이 가이드에서는 설정을 시스템 콘솔의 경로, 레이블, 구성 키 순서로 표기합니다. 예를 들어 관리자 도구 › 사이트 구성 › 팀과 사용자 › 무시, 차단 및 메시지 요청 활성화 (PrivacySettings.EnableUserBlocking).

대부분의 변경 사항은 저장을 클릭하는 즉시 적용됩니다. 일부 설정(리스닝 주소, 일부 데이터베이스 및 캐시 설정)은 재시작이 필요하며, 해당 페이지에 명시되어 있습니다.

업무 공간 또는 커뮤니티

각 커뮤니티에는 유형이 있으며, 이는 기본값의 일부를 결정합니다:

• 커뮤니티: 공개 또는 취미 기반 커뮤니티용입니다. 채널에서 통화가 비활성화되어 있으며(사용자는 음성 채널에서 대화합니다), 채널 아카이브는 관리자 및 채널을 관리하는 역할만 수행할 수 있습니다.
• 업무 공간: 회사 또는 조직용입니다. 채널에서 통화가 활성화되어 있으며, 채널 관리자(채널 생성자 및 그로 하여금 관리자로 임명한 사용자)도 채널을 아카이브할 수 있습니다.

시스템 콘솔 › 사이트 구성 › 팀과 사용자 › 새 커뮤니티 유형(TeamSettings.DefaultCommunityKind, AM_TEAMSETTINGS_DEFAULTCOMMUNITYKIND)은 이후 생성되는 커뮤니티의 유형을 결정하며, community(기본값) 또는 workplace 중 하나를 선택할 수 있습니다. 커뮤니티 생성 시 선택한 레이아웃 프리셋은 자체 유형을 설정합니다. 각 커뮤니티의 관리자는 팀 설정 › 채널 › 커뮤니티 유형에서 나중에 유형을 변경할 수 있습니다.

amctl 명령줄 도구

amctl는 명령줄에서 서버를 관리합니다: 사용자, 커뮤니티, 채널, 앱, 설정, 작업 등. 서버와 두 가지 방식으로 통신합니다.

로컬 모드, 서버에서

로컬 모드는 amctl이 로그인 없이 Unix 소켓을 통해 서버와 통신할 수 있게 합니다. 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

원격, 계정 사용

어떤 기기에서든 시스템 관리자 계정(또는 개인 액세스 토큰)으로 로그인한 후 해당 서버에 대해 명령을 실행합니다:

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

설정 명령

앱 설정은 PluginSettings.Plugins.<app id> 아래에 있으며, 키는 소문자로 사용됩니다. 예를 들어, Docker 호스트에서 GIFs 앱의 서비스 URL과 키를 설정하려면:

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)은 관리자 도구 › 환경 › 로그에서 설정합니다:

로그 파일은 100 MB에서 회전되며, 이전 파일은 압축됩니다.

사이트의 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로 기록됩니다. 패키지는 파일 로그 기록을 비활성화하므로, 로그는 저널에만 기록됩니다.

파일 로그가 활성화된 경우, 시스템 관리자는 관리자 도구 › 리포팅 › 서버 로그에서 최신 로그 줄을 읽거나 amctl logs 명령을 사용할 수 있습니다.