운영

서버 상태를 점검하고, 더 많은 사용자를 처리할 수 있도록 확장하며, 데이터 보존 기간을 결정하고, 관리자가 가장 자주 겪는 문제를 해결합니다.

헬스 체크

• amctl --local system status (컨테이너 내부에서는: docker compose exec antimatter amctl --local system status). Docker 이미지의 헬스 체크는 30초마다 이를 실행하므로, docker compose ps에서 healthy 또는 unhealthy 상태를 확인할 수 있습니다.
• GET /api/v4/system/ping는 로그인 없이 응답하므로, 외부 모니터나 로드 밸런서에서 사용할 수 있습니다: curl -fsS https://chat.example.com/api/v4/system/ping.
• antimatter db ping은 설정된 구성으로 데이터베이스에 접근할 수 있는지 확인합니다.
• 시스템 콘솔 › 리포팅 › 시스템 통계에서 사용자, 게시물 및 세션 수를 확인할 수 있으며, 작업 공간 최적화에서는 검토해야 할 구성 문제를 나열합니다.

메트릭스

서버는 Prometheus 지표를 게시할 수 있습니다: 요청 빈도와 소요 시간, WebSocket 연결, 데이터베이스 및 캐시 사용량, 작업, 플러그인 훅 등입니다. 시스템 콘솔 › 환경 › 성능 모니터링에서 활성화합니다:

Prometheus는 http://<server>:8067/metrics를 스크래프합니다. 각 지표는 Mattermost 이름(mattermost_…)과 Antimatter 이름(antimatter_…)으로 게시되므로, 기존 Mattermost 대시보드가 계속 작동합니다. 앱은 자체 지표를 게시하며, 예를 들어 Agents 앱은 /plugins/mattermost-ai/metrics에서 게시합니다.

지표 포트에는 로그인이 필요하지 않습니다: 비공개 네트워크에 유지하세요. 사이트의 compose 파일은 이를 게시하지 않습니다; 호스트에서 스크래프하려면 antimatter 서비스의 ports에 "127.0.0.1:8067:8067"를 추가하세요.

Metrics 앱

Prometheus 서버가 없는 경우, Metrics 앱(기본적으로 비활성화되어 있으며, 번들 앱 참고)은 Antimatter 내부의 소형 시계열 데이터베이스에 동일한 메트릭을 수집합니다. 60초 간격으로 수집하며, 15일치 데이터를 보관합니다. 앱이 시작되면 메트릭 엔드포인트를 활성화합니다. 관리자 도구 › 플러그인 페이지에서 데이터베이스 크기를 확인할 수 있으며, 자체 분석이나 버그 리포트 첨부를 위해 데이터 덤프를 다운로드할 수 있습니다. 최신 1일치의 데이터는 지원 패킷에도 포함됩니다.

지원 패킷

지원 패킷은 문제를 진단하는 데 필요한 정보가 담긴 zip 파일입니다. 버전, 통계, 시크릿이 제거된 설정, 앱 및 작업 목록, 데이터베이스 스키마, 최근 로그 및 성능 프로파일 등이 포함됩니다. amctl system supportpacket 명령을 사용하거나, 시스템 콘솔 사이드바 상단의 메뉴(유료 지원)에서 생성할 수 있으며, 이 경우 포함할 항목을 선택할 수 있습니다. 공유하기 전에 내용을 확인하세요. 메시지 내용은 포함되지 않지만, 커뮤니티, 사용자 및 설정 이름은 포함됩니다.

성능 및 확장

CPU 2코어, 메모리 4GB의 단일 서버로 수백 명을 서비스할 수 있습니다. 서버를 추가하기 전에 다음 사항을 확인하세요:

• 데이터베이스. 대부분의 작업은 PostgreSQL이 처리합니다. 빠른 저장소와 메모리를 제공하세요. 읽기 복제본을 사용하여 읽기 부하를 분산할 수 있습니다(SqlSettings.DataSourceReplicas, 연결 URL 목록).
• 검색. 기본적으로 메시지는 데이터베이스에서 검색됩니다. 대규모 서버의 경우 Elasticsearch 또는 OpenSearch로 검색 및 인덱싱을 전환할 수 있습니다: 관리자 도구 › 환경 › Elasticsearch (ElasticsearchSettings: 백엔드 유형 Elasticsearch 또는 OpenSearch, 서버 연결 주소, 인증 정보, 그리고 인덱싱 활성화, 인덱스 빌드, 검색 활성화).
• 통화. 통화 미디어는 가장 큰 부하를 유발합니다. 부하를 rtcd 서버로 이동하세요: 통화 및 음성 참고.
• 열린 파일. 각 연결된 사용자는 웹소켓을 유지합니다. antimatter-docker의 프로덕션 compose 파일은 한도값을 49152로 설정합니다(ulimits: nofile); systemd에서도 동일하게 설정하세요(LimitNOFILE).
• 로그. LogSettings.ConsoleLevel을 INFO 또는 WARN으로 낮추세요: DEBUG는 바쁜 서버에서 많은 양의 로그를 기록합니다.

고가용성

라이선스 없이 로드 밸런서 뒤에서 여러 Antimatter 서버를 클러스터로 실행할 수 있습니다. 모든 노드는 동일한 PostgreSQL 데이터베이스, 동일한 S3 파일 저장소, 그리고 데이터베이스 내 설정(AM_CONFIG)을 공유해야 합니다. 시스템 콘솔 › 환경 › 고가용성(ClusterSettings)에서 고 가용성 모드(ClusterSettings.Enable)를 켜고, 모든 노드에 동일한 클러스터명(ClusterSettings.ClusterName)을 지정하며, 노드들이 gossip 포트인 8074 TCP 및 UDP(ClusterSettings.GossipPort)를 통해 서로 통신할 수 있도록 설정합니다. 노드는 데이터베이스를 통해 서로를 찾습니다. 로드 밸런서는 WebSocket을 전달해야 합니다. 클러스터 내 통화를 위해 rtcd를 사용하세요.

데이터 보존

기본적으로 Antimatter는 모든 메시지와 파일을 영구적으로 보관합니다. 오래된 데이터를 자동으로 삭제하려면 시스템 콘솔 › 감사 › 데이터 보존 정책으로 이동하세요:

• 글로벌 리텐션 정책은 전체 서버에 대한 채널 및 다이렉트 메시지 보존과 파일 보존을 설정합니다: 영구 보관 또는 시간, 일, 연 단위 수치를 지정할 수 있습니다(DataRetentionSettings.EnableMessageDeletion, MessageRetentionHours, EnableFileDeletion, FileRetentionHours).
• 사용자 지정 보존 정책은 선택한 커뮤니티와 채널에 대해 다른 보존 기간을 설정합니다.
• 삭제 작업은 선택한 시각에 매일 실행됩니다(기본값은 UTC 02:00, DataRetentionSettings.DeletionJobStartTime). 삭제 작업 지금 실행을 사용하면 즉시 실행할 수 있으며, 정책 로그에는 각 실행에서 삭제된 항목이 나열됩니다.

컴플라이언스 내보내기 및 감사 로그

• 관리자 도구 › 감사 › 컴플라이언스 내보내기는 매일 모든 메시지와 파일을 아카이빙 시스템이 읽을 수 있는 형식 중 하나로 내보냅니다(컴플라이언스 내보내기, MessageExportSettings.EnableExport, 기본값: 꺼짐; 감사 보고서 내보내기 시간, 기본값: 01:00). 지원되는 형식은 CSV, Actiance XML, Global Relay(zip 파일 또는 SMTP로 전송되는 EML)입니다. amctl compliance-export 명령을 사용하면 명령줄에서 내보내기를 실행하고 결과를 다운로드할 수 있습니다.
• 컴플라이언스 모니터링(ComplianceSettings)은 디렉토리에 일일 보고서를 작성합니다. 이는 이전 메커니즘이며, 컴플라이언스 내보내기를 사용하는 것이 좋습니다.
• 감사 로깅(beta, ExperimentalAuditSettings)은 관리 및 보안 이벤트(로그인, 권한 및 설정 변경)를 전용 파일에 기록합니다.
• 고객 서비스 약관(Beta)은 Antimatter 사용 전 모든 사용자에게 약관을 수락하도록 요구하며, 약관을 변경한 후에도 다시 수락을 요구합니다.

자주 발생하는 문제

"서버에 연결할 수 없음" 또는 새로고침 후에만 메시지가 표시되는 경우

웹소켓이 통과하지 못합니다. 리버스 프록시가 Upgrade 및 Connection 헤더를 전달하는지 확인하고(nginx 예시 참조), 사이트 URL이 브라우저의 주소와 정확히 일치하는지( https 포함) 확인하세요.

"413 Request Entity Too Large" 오류로 업로드가 실패하는 경우

프록시가 크기를 거부합니다. 프록시 제한을 시스템 콘솔 › 환경 › 파일 저장의 최대 파일 크기(FileSettings.MaxFileSize, 기본값 100 MB) 이상으로 높여야 합니다(nginx의 경우 client_max_body_size).

통화를 시작할 수 없거나, 참여는 하지만 소리를 들을 수 없는 경우

관리자 외에는 통화를 시작할 수 없다면, 통화의 테스트 모드를 끕니다. 커뮤니티의 채널에 통화 버튼이 없다면, 해당 커뮤니티는 커뮤니티 유형이며 기본적으로 통화가 비활성화되어 있습니다. 채널 또는 커뮤니티 관리자가 채널에서 통화를 활성화하거나 커뮤니티 유형을 변경할 수 있습니다(자세한 내용은 통화가 활성화되는 위치 참고). 사람들이 참여했지만 아무 소리도 들리지 않는 경우, 미디어 포트가 차단되었거나 서버가 잘못된 주소를 보고하는 것입니다. 8443 UDP 및 TCP 포트를 개방하고 NAT 뒤에 ICE Host Override를 설정합니다. 두 프로토콜 모두 차단되는 네트워크에 있는 사용자는 TURN 서버가 필요합니다. 자세한 내용은 통화와 음성을 참고하세요.

GIF 선택기가 비어 있는 경우

시스템 콘솔 › 플러그인 › GIF에서 GIF 서비스 URL(사이트의 compose 파일 사용 시 http://gifs:8080/v2)과 API 키(.env의 GIFS_API_KEY)를 확인하고, gifs 서비스가 실행 중인지 확인하세요: docker compose ps gifs.

전자우편이 도착하지 않는 경우

시스템 콘솔 › 환경 › SMTP에서 연결 테스트를 사용하고, 발신자의 전자우편 주소가 여전히 test@example.com이 아닌지 확인한 후, 로그에서 smtp 또는 mail을 검색하세요.

앱에 "시작 실패"가 표시되는 경우

로그에서 해당 앱의 id를 찾아보세요(docker compose logs antimatter | grep <app id>). 플러그인 관리에서 해당 앱을 비활성화했다가 활성화하여 다시 시작하세요.

서버가 시작되지 않는 경우

로그의 끝부분을 읽어보세요. 가장 흔한 원인은 데이터베이스에 연결할 수 없는 경우(antimatter db ping로 AM_SQLSETTINGS_DATASOURCE를 확인), 데이터베이스 마이그레이션 실패(업그레이드 전에 만든 백업을 복원하고 오류를 보고), 또는 리스닝 포트가 이미 사용 중인 경우입니다.

관리자 계정에 잠금 해제되지 않는 경우

서버에서 로컬 모드는 비밀번호가 필요하지 않습니다:

docker compose exec antimatter amctl --local user change-password admin --password 'a-new-password'
docker compose exec antimatter amctl --local user resetmfa admin
docker compose exec antimatter amctl --local roles system-admin admin

버그 보고

Antimatter 커뮤니티 저장소에 버그를 보고할 때 버전, 설치 방법, 수행한 작업 및 관련 로그 줄을 포함하세요. 보안 문제는 보안 정책에 설명된 대로 비공개로 보고하세요.