일반 배포 문제 해결

Mattermost v11.11번역일: 2026-09-02원본 보기

이 문서는 배포 과정에서 흔히 발생하는 문제와 해결 방법을 정리한 것입니다. 일부는 직접 처리할 수 있지만, 일부는 네트워크 관리자와 상의해야 할 수도 있습니다.

시스템 부팅 시 Mattermost 시작

시스템이 부팅될 때 Mattermost 서버가 시작되도록 하려면 systemd 유닛 파일을 활성화해야 합니다. 다음 명령을 실행하세요.

sudo systemctl enable mattermost.service

데이터베이스가 Mattermost 서버와 같은 시스템에 있다면, 기본 /etc/systemd/system/mattermost.service systemd 유닛 파일의 [Unit] 섹션에 After=postgresql.service와 BindsTo=postgresql.service를 추가하는 것을 권장합니다.

프록시 없이 Mattermost 실행

Mattermost는 8065 대신 443 포트에 바인딩됩니다. Mattermost 바이너리가 이 바인딩을 하려면 적절한 권한이 필요합니다. 새 Mattermost 바이너리가 1024 미만 포트에 바인딩할 수 있도록 다음 명령을 실행해 CAP_NET_BIND_SERVICE 기능을 활성화해야 합니다.

sudo setcap cap_net_bind_service=+ep ./mattermost/bin/mattermost
참고

동시 접속 사용자 200명까지는 Mattermost 서버 앞에 프록시를 두는 것을 강력히 권장합니다. 동시 접속 사용자가 200명 미만이라면 (선택) TLS 설정을 사용할 수 있습니다. 200명을 초과한다면 트래픽을 관리하기 위해 Mattermost 앞에 NGINX 같은 프록시가 필요합니다.

Mattermost 로그 확인

Mattermost 로그에 접근해 문제 해결에 활용할 수 있습니다. 아래 단계는 이를 수행할 적절한 시스템 관리자 권한이 있다고 가정합니다.

Mattermost 서버 로그

  • 로그 파일이 생성되고 있는지 확인합니다. System Console > Environment > Logging으로 이동해 Output logs to file이 true로 설정되어 있는지 확인하세요.
  • 로그 파일 경로는 System Console > Environment > Logging > File Log Directory에서 확인할 수 있습니다.

생성되는 서버 로그 파일의 이름은 mattermost.log이며, 일반 텍스트 편집기로 열거나 그대로 공유할 수 있습니다.

참고

더 완전한 로그를 얻으려면 System Console > Environment > Logging을 열고 File Log Level을 DEBUG로 설정한 뒤 문제를 재현해 다시 기록하세요. 문제 해결이 끝나면 디스크 공간을 절약하기 위해 파일 로그 레벨을 INFO로 되돌리세요.

파일 시스템에 접근할 수 없다면 System Console > Reporting > Server Logs로 이동해 현재 시스템 로그를 확인하고 파일로 복사할 수 있습니다.

로깅 설정에 대한 자세한 내용은 여기에서 확인할 수 있습니다.

로그 파일에 접근할 수 없는 경우

Mattermost v11.4부터 로그 파일 경로는 지정된 로깅 루트 디렉터리 내에 있는지 검증됩니다.

  1. System Console > Reporting > Server Logs나 지원 패킷에 로그 파일이 나타나지 않는다면, 서버 콘솔의 오류 메시지를 확인해 로그 파일 경로가 허용된 디렉터리 밖에 있는지 확인하세요. "Blocked attempt to read log file outside allowed root" MM_LOG_PATH 환경 변수로 지정된 디렉터리 밖에 있는 로그 파일 경로는 오류를 발생시키며 지원 패킷 다운로드에서 제외됩니다. MM_LOG_PATH가 설정되어 있지 않으면 기본 logs 디렉터리가 사용됩니다.

    오류 메시지는 어떤 설정 항목의 경로가 잘못되었는지 알려줍니다.

    • LogSettings.FileLocation - 주 서버 로그 파일
    • LogSettings.AdvancedLoggingJSON - 고급 로깅 파일 대상
    • ExperimentalAuditSettings.AdvancedLoggingJSON - 감사 로깅 파일 대상

  2. 다음 해결 방법 중 하나를 선택하세요.

    옵션 A - 기본 로깅 디렉터리 사용:

    • 기본 logs 디렉터리를 사용하도록 설정을 변경합니다
    • MM_LOG_PATH 환경 변수를 제거하거나 수정합니다
    • Mattermost 서버를 다시 시작합니다

    옵션 B - 로그 경로에 맞게 로깅 루트 설정:

    • MM_LOG_PATH 환경 변수를 모든 로그 파일이 들어 있는 디렉터리로 설정합니다
    • 설정된 모든 로그 파일 경로가 이 루트 디렉터리 안에 있는지 확인합니다
    • Mattermost 서버를 다시 시작합니다

  3. 로그에 접근할 수 있는지 확인합니다.

    • System Console > Reporting > Server Logs로 이동합니다
    • 로그 항목이 보이는지 확인합니다
    • 테스트 지원 패킷을 생성해 로그가 포함되는지 확인합니다

자세한 설정 예시는 로그 경로 제한 문서를 참고하세요.

Mattermost 데스크톱 앱 로그

메뉴 바에서 Help > Show logs를 선택하면 데스크톱 앱 로그에 접근할 수 있습니다.

또는 다음 디렉터리에서 데스크톱 앱 로그 파일에 접근할 수 있습니다.

  • Windows: %userprofile%\AppData\Roaming\Mattermost\logs
  • Linux: ~/.local/share/Mattermost/logs 또는 ~/.config/Mattermost/logs
  • MacOS: ~/Library/Logs/Mattermost (DMG 설치) 또는 ~Library/Containers/Mattermost.Desktop/Data/Library/Logs/Mattermost (App Store 설치 전용)

Mattermost 웹 로그

브라우저 기반 앱은 별도의 로그 파일을 생성하지 않습니다. 앱을 디버깅해야 한다면 브라우저에 내장된 개발자 도구로 동작 이력을 확인하세요.

Mattermost 푸시 알림 서비스 로그

Mattermost 푸시 알림 서비스의 로깅은 logger를 통해 시스템 로그로 처리되며 /var/log/syslog에 추가됩니다.

Mattermost 환경 점검

오류나 문제가 발생하기 전의 사건들을 배제할 수 있도록 타임라인을 정리하세요. 예를 들어 최근에 방화벽을 재구성한 뒤 연결 문제가 발생했다면, 설정을 다시 살펴보거나 이전 상태로 되돌려 문제가 해결되는지 확인해 볼 만합니다.

  • 정상적으로 운영되던 기간 이후에 문제가 발생했다면, 환경에 어떤 변화가 있었습니까?
    • 클라이언트, 호스트, 서버가 업그레이드되었습니까?
    • 운영 체제 업데이트가 적용되었습니까?
    • 네트워크 환경이 바뀌었습니까? 예를 들어 서버를 옮기거나 도메인을 이전했습니까?
    • 시스템(클라이언트 또는 서버)이 최근에 장애를 겪거나 비정상 종료되었습니까?
  • 영향을 받는 사용자는 몇 명입니까?
    • 이 문제가 한 명, 일부, 또는 모든 사용자에게 영향을 주고 있습니까?
    • 신규 입사자처럼 최근에 환경에 추가된 사용자에게만 문제가 발생합니까?
    • 영향을 받는 사용자와 받지 않는 사용자 사이에 차이가 있습니까?

오류 메시지를 온라인에서 검색해 볼 수도 있습니다. 포럼에서 기존 해결책을 찾아 적용할 수 있는 경우가 많습니다.

다른 서버에 연결해 보기

  1. https://community.mattermost.com에서 계정을 만듭니다.
  2. 모바일 애플리케이션을 삭제하고 다시 설치합니다.
  3. 모바일 앱에서 서버 URL https://community.mattermost.com과 로그인 정보를 입력해 연결이 정상적으로 되는지 확인합니다.

다른 기기로 연결해 보기

  • 사용할 수 있는 다른 모바일 기기가 있다면 그 기기로 연결해 문제가 여전히 재현되는지 확인하세요.
  • 다른 기기가 없다면 동료들에게 같은 문제가 발생하는지 확인해 보세요.

자체 호스팅 배포의 지원 티켓 등록

Mattermost Professional이나 Mattermost Enterprise처럼 Mattermost 제품의 유료 구독을 사용 중이라면, 온라인 지원 포털을 통해 지원 티켓을 등록할 수 있습니다.

유료 구독의 일부로 지원 티켓을 등록할 때는 가능한 한 많은 정보를 신속하게 제공하는 것이 중요합니다. 어떤 정보가 필요한지 판단하기 어려울 수 있습니다. Mattermost는 필요한 항목을 기억하기 위해 C.L.U.E.S.라는 약어를 사용합니다.

  • Configurations(설정)
  • Logs(로그)
  • Users affected(영향받는 사용자)
  • Environment(환경)
  • Steps to reproduce(재현 단계)

C.L.U.E.S.는 문제를 명확히 파악하는 데 필요한 모든 정보를 뜻합니다. 이 정보가 있으면 단순한 설정 변경이든 제품 버그든 원인을 찾기 시작할 수 있습니다. 또한 문제를 개발자에게 에스컬레이션해야 할 때, 개발자가 제품 개선에 더 많은 시간을 쓸 수 있도록 도와줍니다.

정보 제공 일반 지침

진단 데이터를 제공할 때는 다음 지침을 따르세요.

  • 몇 줄만 발췌하지 말고 가능한 한 완전한 파일을 제공하세요. 전체 로그 파일과 설정은 중요한 맥락을 제공합니다.
  • 가능하면 설정과 로그 파일을 평문 형식으로 제공하세요. 스크린샷보다 훨씬 검색하기 쉽습니다.
  • 설정과 로그 파일에서 사용자 이름, 비밀번호, LDAP 그룹을 제거해 반드시 정제하세요. 특수 문자는 설정 오류의 흔한 원인이므로, 가능하면 동일한 특수 문자를 포함한 예시 문자열로 대체하세요.
  • 예상과 다른 제품 동작의 스크린샷이나 화면 녹화를 제공해 사용자가 정확히 무엇을 보고 있는지 알 수 있게 하세요.

설정(Configuration)

설정 데이터가 필요한 이유

Linux 시스템에서 설정은 대개 설정 파일에 저장됩니다. 많은 문제는 설정 항목을 켜거나 끄는 것만으로 해결됩니다. 해결책을 찾으려면 시스템 구성 전체를 최대한 파악해야 합니다. 이는 개발자가 버그를 수정할 수 있도록 재현하는 데도 도움이 됩니다.

설정 데이터에 포함되는 것

설정에는 다음이 포함됩니다(이에 국한되지는 않습니다).

  • Mattermost config.json 파일.
  • NGINX, HAProxy, AWS 등 리버스 프록시 설정.
  • 데이터베이스 설정.
  • SAML 인증과 관련된 문제인 경우 SAML 설정. Mattermost 서비스에 대한 설정은 SAML IdP에 있습니다.
  • Mattermost가 연결하는 다른 시스템, 또는 사용자와 Mattermost 서버 사이에 존재하는 시스템.

설정 데이터에 접근하는 방법

Mattermost 설정

Mattermost 설정은 보통 /opt/mattermost/config/config.json에 저장됩니다. Mattermost 설정을 데이터베이스로 이전했다면 mmctl을 사용하거나 다음 데이터베이스 쿼리를 실행해 설정을 가져올 수 있습니다.

SELECT Value FROM Configurations WHERE Active = 1;

리버스 프록시 설정

NGINX는 대개 설정을 두 부분으로 나눕니다. 주 서버 설정은 /etc/nginx/nginx.conf에, 가상 서버 설정은 별도로 둡니다. Ubuntu에서는 후자가 /etc/nginx/sites-available에 저장됩니다. 두 설정 파일을 모두 제공하면 도움이 되지만, 후자가 더 중요합니다.

SAML 설정

SAML 로그인에서 문제가 발생한다면 SAML 공급자에 등록된 Mattermost 서비스의 전체 설정을 확인해야 합니다. Mattermost 서비스에 대한 설정은 SAML IdP에 있습니다. 대부분의 SAML 공급자는 웹 인터페이스로 설정하므로, 설정 문서에 있는 것과 비슷한 스크린샷을 제공하면 충분합니다.

LDAP 설정

LDAP 관리자는 다음 Mattermost LDAP 설정 값이 올바른지 확인해야 합니다.

  • LDAP 서버 호스트 이름.
  • LDAP 연결 포트, 보안, 인증서.
  • BaseDN, 바인드 사용자 이름, 바인드 비밀번호.
  • User, Group, Guest, Admin 필터.
  • 표시 속성(Display attributes).

이 정보는 텍스트 파일이나 LDAP 서버의 스크린샷으로 제공할 수 있습니다.

기타 설정

모바일에서 문제가 발생하고 MDM이나 VPN을 통해 서버에 연결하고 있다면, 해당 설정도 문제 진단에 필요합니다. 외부 시스템의 시스템 관리자가 설정을 제공해 줄 수 있습니다.

로그(Logs)

로그가 필요한 이유

거의 모든 컴퓨터 시스템은 오류와 애플리케이션 동작에 대한 로그를 남기며, 이를 통해 애플리케이션 실행 중에 무슨 일이 일어나는지 파악할 수 있습니다. 오류 로그는 문제 진단에 매우 유용하지만, 가능한 한 완전할 때만 그렇습니다.

사용할 수 있는 로그

Mattermost

Mattermost에는 두 개의 로그 파일이 있습니다. 하나는 일반 메시지용, 다른 하나는 알림 관련 메시지용입니다. 위치는 다음과 같습니다.

  • /opt/mattermost/logs/mattermost.log
  • /opt/mattermost/logs/notification.log

프록시

위치는 프록시 설정에 따라 다르지만 /var/log부터 찾아보는 것이 좋습니다. 프록시 관리자가 로그를 찾는 데 도움을 줄 수 있습니다.

데이터베이스

PostgreSQL과 MySQL은 서로 다른 로그를 남기며, 위치도 설정에 따라 달라집니다. 데이터베이스 연결과 관련된 문제라면 데이터베이스 문서를 참고해 로그 위치를 확인하세요.

SAML, LDAP 및 기타 시스템

조직의 시스템 관리자가 찾아 줄 수 있습니다.

로그에 접근하는 방법

Mattermost

로그에서 최대한 많은 정보를 얻을 수 있도록 디버그 로깅이 활성화되어 있는지 확인하세요. System Console > Environment > Logging으로 이동해 Console File Level과 File Log Level을 모두 DEBUG로 설정합니다. 변경 사항 저장을 잊지 마세요.

문제가 시작된 시각이나 날짜를 알고 있다면 journalctl로 다음과 같이 로그를 가져오세요.

sudo journalctl -u mattermost --since "2020-08-23 17:15:00" > mattermost_journalctl.log

2020-08-23 17:15:00 부분을 문제가 시작된 (서버 기준) 날짜와 시각으로 바꾸세요. 서버 시각은 date 명령으로 확인할 수 있습니다. 생성된 로그 파일이 너무 커서 전송하기 어렵다면 다음 명령으로 압축하세요.

tar -czf /tmp/mattermost.log.tgz

압축된 로그는 서버의 /tmp/mattermost.log.tgz에 생성됩니다.

압축 파일이 여전히 너무 크다면 다음 명령으로 20MB 단위의 파일 여러 개로 분할하세요.

mkdir -p /tmp/mattermost-logs
cd /tmp/mattermost-logs
tar czf - /opt/mattermost/logs/mattermost.log | split -b 20m - mattermost.log.tgz.

압축 파일들은 서버의 /tmp/mattermost-logs에 생성되며 mattermost.log.tgz.aa, mattermost.log.tgz.ab와 같은 이름을 갖습니다. Cyberduck처럼 SSH/SFTP를 지원하는 파일 전송 클라이언트를 사용해 서버에서 이 파일들을 복사하세요.

Elasticsearch, LDAP, 데이터베이스에서 문제가 발생한다면 config.json의 해당 설정 아래에서 Trace를 true로 설정해 트레이스 로깅을 활성화할 수 있습니다. 이를 DEBUG 레벨 파일 로그 출력과 함께 사용하면 로그 파일이 매우 커지므로, 문제를 재현할 수 있을 만큼만 트레이스 로깅을 켜 두세요. 이렇게 생성된 로그에는 사용자 데이터를 포함한 민감한 정보가 훨씬 많이 담기므로, 공유하기 전에 반드시 완전히 정제하세요.

시스템 로그

다른 시스템의 로그 파일 위치는 제각각이지만, Mattermost 서버의 모든 프로세스 로그를 가져오려면 다음과 같이 journalctl을 사용하는 것이 좋습니다.

sudo journalctl --since "2020-08-23 17:15:00" > mattermost_journalctl.log

2020-08-23 17:15:00 부분을 오류가 발생한 (서버 기준) 날짜와 시각으로 바꾸세요. 같은 형식의 타임스탬프와 함께 --until을 사용하면 두 시각 사이의 로그를 가져올 수 있습니다.

sudo journalctl --since "2020-08-23 17:15:00" --until "2020-08-23 16:30:00" > mattermost_journalctl.log

영향받는 사용자(Users affected)

이 정보가 필요한 이유

Mattermost 서버는 매우 분주한 곳입니다. 매초 수천 건의 게시물, 웹소켓 동작, 웹훅 호출이 발생하며, 사용자는 여러 팀에 걸쳐 수십 개의 채널에 속할 수 있습니다. 어떤 사용자가 문제의 영향을 받는지 알면 이 방대한 정보 속에서 근본 원인을 찾아내는 데 도움이 됩니다.

포함해야 할 정보

예상과 다른 동작을 보고한 최종 사용자들의 공통점을 상세히 설명해야 합니다. 여기에는 다음이 포함됩니다(이에 국한되지는 않습니다).

  • 다이렉트 메시지와 그룹 메시지를 포함한 팀·채널 멤버십.
  • 인증 방식.
  • 클라이언트 운영 체제와 앱 버전.
  • 사용자가 Mattermost 서버에 연결하는 방식.
  • 가입 시점, 최근 로그인 정보 변경 여부, LDAP 동기화 여부 등 해당 사용자들의 다른 공통점.

에이전트를 위한 참고 사항: 다음 정보도 필요합니다.

  • 고객사 이름
  • 고객 담당자
  • 고객 라이선스(예: Enterprise/Professional)
  • 고객 등급

환경(Environment)

아키텍처에서 Mattermost 서버가 어디에 위치하는지는 발생 가능한 문제에 큰 영향을 미칩니다. 예를 들어 프록시 서버가 잘못 설정되어 있으면 Mattermost 자체에 문제가 없어도 사용자가 연결하지 못할 수 있습니다.

포함해야 할 정보

따라서 Mattermost 서버가 동작하는 서버와 네트워크 전반을 완전히 파악하는 것이 문제 해결의 핵심입니다. 여기에는 다음이 포함됩니다(이에 국한되지는 않습니다).

  • Mattermost 버전(예: 7.3.0, 7.8.3)
  • 서버 OS와 버전(예: RHEL7, Ubuntu 20.04)
  • Docker나 Kubernetes 같은 오케스트레이션·자동화 도구 사용 여부
  • 리버스 프록시와 버전(예: NGINX 1.16)
  • 데이터베이스 종류와 버전(예: PostgreSQL 14)
  • SAML 공급자(예: Windows Server 2012 Active Directory, Okta, KeyCloak)
  • LDAP 공급자(예: Windows Server 2016 Active Directory, Okta, OpenLDAP)
  • Mattermost 서버가 경유하는 네트워크상의 프록시나 VPN의 종류와 버전

환경을 설명할 때는 가능한 한 구체적으로 작성하세요. Connection Refused 같은 오류가 보인다면, 네트워크의 인바운드·아웃바운드 방화벽이나 필터링 프록시도 빠짐없이 알려주세요.

예시

Mattermost 서버

  • 외부 호스트 이름: mattermost.example.com
  • 내부 호스트 이름: mattermost.lan
  • Mattermost v7.3.0
  • Zoom 플러그인 v1.4.1
  • NGINX v1.18.0

데이터베이스 서버

  • 내부 호스트 이름: postgresql.lan
  • PostgreSQL v13
  • LDAP 공급자 - 192.168.1.102
  • 내부 호스트 이름: ldap.lan
  • OpenLDAP 2.4.54 (Docker 컨테이너)

Mattermost 서버들

  • 호스트 이름: mm1.local.lan, mm2.local.lan, mm3.local.lan, mm4.local.lan

Mattermost 서버 버전

  • mm1-3: 5.25.4
  • mm4: 5.21.0

프록시 서버

  • 외부 호스트 이름: mattermost.example.com
  • 내부 호스트 이름: proxy.local.lan
  • NGINX v1.16.0

데이터베이스 서버들

  • 호스트 이름: db1.local.lan, db2.local.lan, db3.local.lan
  • 기본(Primary): db1.local.lan
  • 읽기 전용(Read-Only): db2.local.lan, db3.local.lan
  • PostgreSQL v13

Elasticsearch 서버

  • 호스트 이름: elastic.local.lan
  • Elasticsearch v7.9와 다음 플러그인
  • analysis-icu

재현 단계(Steps to reproduce)

재현 단계란

사용자가 특정 동작을 할 때만 문제가 발생한다면, 상세한 재현 단계를 제공해 주어야 올바른 버그를 찾아 수정할 수 있습니다. 가능한 한 자세히 설명하되, 해당 동작의 스크린샷이나 화면 녹화보다 좋은 것은 없습니다.

재현 단계를 간단히 요약해 주어도 도움이 됩니다. 예시가 필요하다면 Mattermost Jira의 버그 티켓들을 참고하세요.

이 정보를 제공하는 방법

macOS

⌘ ⇧ 5를 눌러 화면 녹화 도구를 열고 녹화할 화면 영역을 선택하세요. 스크린샷을 찍으려면 ⌘ ⇧ 4를 누르고 영역을 선택합니다. 스크린샷 파일은 기본적으로 바탕화면에 저장됩니다.

Windows

Ctrl Shift S를 눌러 캡처 도구를 열고 스크린샷을 찍으세요. 화면 녹화를 하려면 OBS 같은 서드파티 소프트웨어를 설치해야 합니다.

iOS

iPhone에서 스크린샷을 찍거나 화면을 녹화하세요.

Android

Android 기기에서 스크린샷을 찍거나 화면을 녹화하세요.

부록

모바일 문제에 관한 참고 사항

모바일 앱에는 디버그 모드가 없기 때문에, 사용자 데이터에서 비롯된 문제를 진단하려면 Charles나 mitmproxy 같은 프록시가 필요합니다. 이런 도구는 클라이언트의 트래픽을 가로채 기록하며, 기록한 트래픽을 다시 재생해 문제를 재현할 수 있습니다. 설정에 도움이 필요하면 Mattermost 전문가에게 문의하세요.

SAML 로그인 문제

SAML 로그인에서 문제가 발생한다면 SAML 로그인 흐름이 중요한 맥락이 됩니다. 여기에는 헤더와 인증 정보가 담겨 있어 쉽게 고칠 수 있는 문제를 드러내 주기도 합니다. SAML 인증에서 문제를 겪고 있다면 다음 안내에 따라 SAML 로그인 흐름을 확인하세요.

키와 인증서 확인

키와 인증서 파일은 절대 공유해서는 안 됩니다. 다만 오류가 키나 인증서의 형식 문제를 가리킨다면 다음 명령을 실행해 키와 인증서의 형식을 확인해야 합니다.

cat -A /path/to/key-or.cert

출력이 유효하려면 다음 조건을 정확히 충족해야 합니다.

  • -----BEGIN CERTIFICATE-----$로 시작합니다.
  • 모든 줄이 $로 끝나야 합니다. ^M$로 끝난다면 dos2unix로 UNIX 줄바꿈으로 변환하세요.
  • -----END CERTIFICATE-----$로 끝납니다.