배포 문제 해결

요약

이 문서는 일반적인 배포 문제 해결 사항과 해결 방법을 요약하고, 지원 티켓을 열기 전에 수집해야 할 진단 데이터를 설명합니다. 배포에서 어느 부분이 실패하고 있는지 이미 알고 있다면, 해당 계층의 가이드부터 시작하세요.

이 문서는 일반적인 배포 문제 해결 사항과 해결 방법을 요약하고, 지원 티켓을 열기 전에 수집해야 할 진단 데이터를 설명합니다. 이러한 제안 중 일부는 직접 수행할 수 있으며, 다른 일부는 네트워크 관리자와의 상담이 필요할 수 있습니다.

배포에서 어느 부분이 실패하고 있는지 이미 알고 있다면, 해당 계층의 가이드부터 시작하세요.

PostgreSQL 문제 해결: 준비 아래의 데이터베이스 설정 페이지에 있습니다.
Docker 배포 문제 해결: 배포 방법 선택 아래의 컨테이너 배포 단계와 함께 있습니다.
데스크톱 앱 문제 해결: 데스크톱 앱 배포의 끝부분에 있습니다.
모바일 배포 문제 해결: 모바일 앱 배포의 끝부분에 있습니다.

시스템 부팅 시 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

Note

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

Mattermost 로그 검토#

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

Mattermost 서버 로그#

로그 파일이 생성되고 있는지 확인합니다. System Console > Environment > Logging 으로 이동하여 파일에 로그 출력 이 true 로 설정되어 있는지 확인합니다.
System Console > Environment > Logging > File Log Directory 에서 로그 파일 경로를 확인할 수 있습니다.

생성된 서버 로그 파일은 mattermost.log 라고 하며 표준 텍스트 편집기로 열거나 직접 공유할 수 있습니다.

Note

더 완전한 로그를 얻으려면 System Console > Environment > Logging 을 열고 파일 로그 레벨 을 DEBUG 로 설정한 다음, 문제를 다시 발생시켜 로그를 기록합니다. 디스크 공간을 절약하기 위해 문제 해결 후에는 파일 로그 레벨을 INFO 로 되돌려 놓으세요.

파일 시스템에 접근할 수 없는 경우 System Console > Reporting > Server Logs 로 이동하여 현재 시스템 로그를 찾으세요. 이 로그는 파일로 복사할 수 있습니다.

로깅 설정에 대한 자세한 내용은 여기를 참조하세요.

로그 파일에 접근할 수 없음#

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

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.FileName - 감사 로그 파일
- ExperimentalAuditSettings.AdvancedLoggingJSON - 감사 로깅 파일 대상
다음 해결 방법 중 하나를 선택합니다.

옵션 A - 기본 로깅 디렉터리 사용:
- 기본 logs 디렉터리를 사용하도록 구성을 업데이트합니다
- MM_LOG_PATH 환경 변수를 제거하거나 업데이트합니다
- Mattermost 서버를 다시 시작합니다
옵션 B - 로그 경로와 일치하도록 로깅 루트 구성:
- MM_LOG_PATH 환경 변수를 모든 로그 파일이 포함된 디렉터리로 설정합니다
- 구성된 모든 로그 파일 경로가 이 루트 디렉터리 내에 있는지 확인합니다
- Mattermost 서버를 다시 시작합니다
로그에 접근할 수 있는지 확인합니다.
- System Console > Reporting > Server Logs 로 이동합니다
- 로그 항목이 보이는지 확인합니다
- 테스트 지원 패킷을 생성하여 로그가 포함되어 있는지 확인합니다

자세한 구성 예시는 로그 경로 제한 문서를 참조하세요.

로그 경로 오류로 서버가 시작되지 않음#

EnforceLogPathRoot 기능 플래그가 활성화된 경우(MM_FEATUREFLAGS_ENFORCELOGPATHROOT=true), 로깅 루트 외부로 확인되는 로그 또는 감사 파일 경로가 있으면 오류만 기록하는 대신 서버가 시작되지 않습니다. 시작 실패 시 다음과 같은 메시지가 표시됩니다.

failed to initialize logging: log file paths outside logging root: LogSettings.AdvancedLoggingJSON target "custom": path /var/log/custom.log is outside logging root /opt/mattermost/logs

플래그가 활성화된 상태에서는 이러한 경로를 도입하는 구성 변경도 거부되며, System Console에서 구성을 저장하면 저장되지 않고 오류가 반환됩니다.

해결하려면 MM_LOG_PATH 환경 변수를 구성된 모든 로그 경로를 포함하는 상위 디렉터리로 설정하거나, 로그 파일을 기존 로깅 루트 안으로 옮긴 다음 서버를 다시 시작하세요. 오류 메시지에 구성 설정과 문제가 되는 경로가 표시됩니다. MM_FEATUREFLAGS_ENFORCELOGPATHROOT=false 로 설정하면 경고만 하는 동작으로 되돌아가지만, 가능하면 강제 적용을 켜 두세요. 강제 적용은 향후 릴리즈에서 기본값이 됩니다.

Mattermost 데스크톱 앱 로그#

메뉴 표시줄의 도움말 > 로그 표시 로 이동하여 데스크톱 앱 로그에 접근합니다.

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

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 (앱스토어 설치만 해당)

Mattermost 웹 로그#

브라우저 기반 앱은 추가 로그 파일을 생성하지 않습니다. 앱을 디버그해야 하는 경우 브라우저에 통합된 개발 도구를 사용하여 작업 기록을 확인하세요.

Mattermost 푸시 알림 서비스 로그#

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

Mattermost 환경 검토#

오류나 문제가 발생하기 이전의 이벤트를 제외해 나갈 수 있도록 타임라인을 작성합니다. 예를 들어, 최근 방화벽을 재구성했고 이제 연결 문제가 발생하는 경우 설정을 검토하거나 롤백하여 문제가 해결되는지 확인해 볼 만합니다.

일정 기간의 정상 작동 후 문제가 발생한 경우, 환경에서 변경된 사항이 있습니까?
- 클라이언트, 호스트 또는 서버가 업그레이드되었습니까?
- 운영 체제 업데이트가 적용되었습니까?
- 네트워크 환경이 변경되었습니까? 예를 들어, 서버가 이동되었거나 도메인이 마이그레이션되었습니까?
- 시스템(클라이언트 또는 서버)이 최근 실패했거나 비정상적으로 종료되었습니까?
영향을 받는 사용자는 몇 명입니까?
- 이 문제가 한 명, 일부 또는 모든 사용자에게 영향을 미칩니까?
- 신입사원과 같이 최근 환경에 추가된 사용자에게만 문제가 발생합니까?
- 영향을 받는 사용자와 받지 않는 사용자 사이에 차이점이 있습니까?

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

다른 서버에 연결#

https://community.mattermost.com 에서 계정을 생성합니다.
모바일 애플리케이션을 삭제하고 다시 설치합니다.
모바일 앱에서 서버 URL https://community.mattermost.com 을 입력하고 로그인 자격 증명을 입력하여 연결이 작동하는지 테스트합니다.

다른 기기로 연결#

다른 모바일 기기가 있으면 그 기기로 연결하여 문제가 계속 재현되는지 확인합니다.
다른 기기가 없으면 동료들에게 동일한 문제가 발생하는지 확인합니다.

자체 호스팅 배포를 위한 지원 티켓 열기#

Mattermost Professional 또는 Mattermost Enterprise와 같은 Mattermost 제품의 유료 구독이 있으면 온라인 지원 포털을 통해 지원 티켓을 열 수 있습니다.

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

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

C.L.U.E.S.는 문제를 명확히 하는 모든 정보를 나타냅니다. 이러한 세부 사항을 통해 단순한 구성 변경인지 제품 버그인지 원인을 찾기 시작할 수 있습니다. 또한 개발자들이 최대한 많은 시간을 제품 개선에 사용할 수 있도록 이슈를 개발자에게 에스컬레이션해야 할 때도 도움이 됩니다.

정보 제공을 위한 일반 지침#

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

몇 줄만 제공하지 말고 가능한 한 완전한 파일을 제공하세요. 전체 로그 파일과 구성은 중요한 컨텍스트를 제공합니다.
스크린샷보다 훨씬 쉽게 검색할 수 있으므로 가능하면 구성 및 로그 파일을 일반 텍스트 형식으로 제공하세요.
구성 및 로그 파일을 정리하여 사용자 이름, 비밀번호 및 LDAP 그룹을 제거하세요. 특수 문자가 구성 오류의 일반적인 원인이므로 가능하면 동일한 특수 문자가 포함된 예시 문자열로 대체하세요.
사용자가 정확히 무엇을 보고 있는지 알 수 있도록 예상치 못한 제품 동작의 스크린샷이나 화면 녹화를 제공하세요.

구성#

구성 데이터가 필요한 이유#

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, 바인드 사용자 이름 및 바인드 비밀번호.
사용자, 그룹, 게스트 및 관리자 필터.
표시 속성.

이러한 값은 텍스트 파일 또는 LDAP 서버의 스크린샷으로 제공할 수 있습니다.

기타 구성

모바일에서 문제가 발생하고 MDM 또는 VPN을 사용하여 서버에 연결하는 경우 해당 구성이 문제 진단에 필요합니다. 외부 시스템의 시스템 관리자가 구성을 제공할 수 있습니다.

로그#

필요한 이유#

거의 모든 컴퓨터 시스템에는 애플리케이션이 실행될 때 어떤 일이 일어나는지 보여 줄 수 있는 오류 및 애플리케이션 동작 로그가 있습니다. 오류 로그는 문제를 진단할 때 매우 유용하지만, 가능한 한 완전한 경우에만 그렇습니다.

사용 가능한 로그#

Mattermost

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

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

프록시

위치는 프록시 구성에 따라 다르지만 /var/log 에서 찾기 시작하는 것이 좋습니다. 프록시 관리자가 로그를 찾는 데 도움을 줄 수 있습니다.

데이터베이스

PostgreSQL과 MySQL은 서로 다른 로그를 가지며 위치는 구성에 따라 다릅니다. 문제가 데이터베이스 연결과 관련된 경우 데이터베이스 문서를 확인하여 로그를 찾으세요.

SAML, LDAP 및 기타 시스템

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

로그 접근 방법#

Mattermost

로그에서 최대한 많은 정보를 얻을 수 있도록 디버그 로깅이 활성화되어 있는지 확인합니다. 이를 위해 System Console > Environment > Logging 으로 이동한 다음 콘솔 파일 레벨 과 파일 로그 레벨 을 모두 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 또는 데이터베이스와 관련된 문제가 있는 경우 각 설정 아래의 Trace 를 true 로 설정하여 config.json 에서 추적 로깅을 활성화할 수 있습니다. 이를 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

영향받는 사용자#

필요한 이유#

Mattermost 서버는 복잡한 환경입니다. 사용자가 여러 팀의 수십 개 채널에 속해 있는 동안 매초 수천 개의 게시물, 웹소켓 작업 및 웹훅 호출이 발생합니다. 어떤 사용자가 문제의 영향을 받는지 알면 이 모든 정보를 걸러내어 근본 원인을 찾는 데 도움이 됩니다.

포함할 정보#

예상치 못한 동작을 보고하는 최종 사용자들이 공통으로 가지고 있는 사항에 대한 자세한 설명이어야 합니다. 여기에는 다음이 포함됩니다(이에 국한되지 않음).

다이렉트 메시지 및 그룹 메시지를 포함한 팀 및 채널 구성원.
인증 방법.
클라이언트 운영 체제 및 앱 버전.
사용자가 Mattermost 서버에 연결하는 방법.
가입 시기, 로그인 정보가 최근 변경되었는지, LDAP를 통해 동기화되고 있는지 등 이 사용자들이 공통으로 가지고 있는 다른 사항들.

에이전트 참고: 다음 정보도 필요합니다.

고객 이름
고객 연락처
고객 라이선스(예: Enterprise/Professional)
고객 티어

환경#

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의 유형 및 버전

환경을 설명할 때 가능한 한 구체적으로 설명하세요. 연결 거부 와 같은 오류가 발생하는 경우 인바운드 또는 아웃바운드에 관계없이 네트워크에 있을 수 있는 방화벽이나 필터링 프록시를 포함해야 합니다.

예시

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

기본: db1.local.lan

읽기 전용: db2.local.lan, db3.local.lan

PostgreSQL v13

Elasticsearch 서버

호스트 이름: elastic.local.lan

다음 플러그인이 설치된 Elasticsearch v7.9

analysis-icu

재현 단계#

재현 단계란#

특정 작업을 수행할 때만 동작이 발생하는 경우, 자세한 재현 단계를 제공하면 올바른 버그를 찾아 수정하는 데 도움이 됩니다. 이러한 세부 사항은 가능한 한 설명적이어야 하지만, 동작을 담은 스크린샷이나 화면 녹화보다 나은 것은 없습니다.

재현 단계의 간단한 요약도 도움이 됩니다. 예시를 원한다면 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-----$ 로 끝나야 합니다.

배포 문제 해결

Mattermost v12.0

원문 보기

번역일: 2026-10-19

요약

배포에서 어느 부분이 실패하고 있는지 이미 알고 있다면, 해당 계층의 가이드부터 시작하세요.

PostgreSQL 문제 해결: 준비 아래의 데이터베이스 설정 페이지에 있습니다.
Docker 배포 문제 해결: 배포 방법 선택 아래의 컨테이너 배포 단계와 함께 있습니다.
데스크톱 앱 문제 해결: 데스크톱 앱 배포의 끝부분에 있습니다.
모바일 배포 문제 해결: 모바일 앱 배포의 끝부분에 있습니다.

시스템 부팅 시 Mattermost 시작#

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

sudo systemctl enable mattermost.service

프록시 없이 Mattermost 실행#

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

Note

Mattermost 로그 검토#

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

Mattermost 서버 로그#

로그 파일이 생성되고 있는지 확인합니다. System Console > Environment > Logging 으로 이동하여 파일에 로그 출력 이 true 로 설정되어 있는지 확인합니다.
System Console > Environment > Logging > File Log Directory 에서 로그 파일 경로를 확인할 수 있습니다.

생성된 서버 로그 파일은 mattermost.log 라고 하며 표준 텍스트 편집기로 열거나 직접 공유할 수 있습니다.

Note

로깅 설정에 대한 자세한 내용은 여기를 참조하세요.

로그 파일에 접근할 수 없음#

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

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.FileName - 감사 로그 파일
- ExperimentalAuditSettings.AdvancedLoggingJSON - 감사 로깅 파일 대상
다음 해결 방법 중 하나를 선택합니다.

옵션 A - 기본 로깅 디렉터리 사용:
- 기본 logs 디렉터리를 사용하도록 구성을 업데이트합니다
- MM_LOG_PATH 환경 변수를 제거하거나 업데이트합니다
- Mattermost 서버를 다시 시작합니다
옵션 B - 로그 경로와 일치하도록 로깅 루트 구성:
- MM_LOG_PATH 환경 변수를 모든 로그 파일이 포함된 디렉터리로 설정합니다
- 구성된 모든 로그 파일 경로가 이 루트 디렉터리 내에 있는지 확인합니다
- Mattermost 서버를 다시 시작합니다
로그에 접근할 수 있는지 확인합니다.
- System Console > Reporting > Server Logs 로 이동합니다
- 로그 항목이 보이는지 확인합니다
- 테스트 지원 패킷을 생성하여 로그가 포함되어 있는지 확인합니다

자세한 구성 예시는 로그 경로 제한 문서를 참조하세요.

로그 경로 오류로 서버가 시작되지 않음#

failed to initialize logging: log file paths outside logging root: LogSettings.AdvancedLoggingJSON target "custom": path /var/log/custom.log is outside logging root /opt/mattermost/logs

플래그가 활성화된 상태에서는 이러한 경로를 도입하는 구성 변경도 거부되며, System Console에서 구성을 저장하면 저장되지 않고 오류가 반환됩니다.

Mattermost 데스크톱 앱 로그#

메뉴 표시줄의 도움말 > 로그 표시 로 이동하여 데스크톱 앱 로그에 접근합니다.

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

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 (앱스토어 설치만 해당)

Mattermost 웹 로그#

Mattermost 푸시 알림 서비스 로그#

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

Mattermost 환경 검토#

일정 기간의 정상 작동 후 문제가 발생한 경우, 환경에서 변경된 사항이 있습니까?
- 클라이언트, 호스트 또는 서버가 업그레이드되었습니까?
- 운영 체제 업데이트가 적용되었습니까?
- 네트워크 환경이 변경되었습니까? 예를 들어, 서버가 이동되었거나 도메인이 마이그레이션되었습니까?
- 시스템(클라이언트 또는 서버)이 최근 실패했거나 비정상적으로 종료되었습니까?
영향을 받는 사용자는 몇 명입니까?
- 이 문제가 한 명, 일부 또는 모든 사용자에게 영향을 미칩니까?
- 신입사원과 같이 최근 환경에 추가된 사용자에게만 문제가 발생합니까?
- 영향을 받는 사용자와 받지 않는 사용자 사이에 차이점이 있습니까?

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

다른 서버에 연결#

https://community.mattermost.com 에서 계정을 생성합니다.
모바일 애플리케이션을 삭제하고 다시 설치합니다.
모바일 앱에서 서버 URL https://community.mattermost.com 을 입력하고 로그인 자격 증명을 입력하여 연결이 작동하는지 테스트합니다.

다른 기기로 연결#

다른 모바일 기기가 있으면 그 기기로 연결하여 문제가 계속 재현되는지 확인합니다.
다른 기기가 없으면 동료들에게 동일한 문제가 발생하는지 확인합니다.

자체 호스팅 배포를 위한 지원 티켓 열기#

Mattermost Professional 또는 Mattermost Enterprise와 같은 Mattermost 제품의 유료 구독이 있으면 온라인 지원 포털을 통해 지원 티켓을 열 수 있습니다.

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

정보 제공을 위한 일반 지침#

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

몇 줄만 제공하지 말고 가능한 한 완전한 파일을 제공하세요. 전체 로그 파일과 구성은 중요한 컨텍스트를 제공합니다.
스크린샷보다 훨씬 쉽게 검색할 수 있으므로 가능하면 구성 및 로그 파일을 일반 텍스트 형식으로 제공하세요.
구성 및 로그 파일을 정리하여 사용자 이름, 비밀번호 및 LDAP 그룹을 제거하세요. 특수 문자가 구성 오류의 일반적인 원인이므로 가능하면 동일한 특수 문자가 포함된 예시 문자열로 대체하세요.
사용자가 정확히 무엇을 보고 있는지 알 수 있도록 예상치 못한 제품 동작의 스크린샷이나 화면 녹화를 제공하세요.

구성#

구성 데이터가 필요한 이유#

포함되는 구성 데이터#

구성에는 다음이 포함됩니다(이에 국한되지 않음).

Mattermost config.json 파일.
리버스 프록시(예: NGINX, HAProxy, AWS)의 구성.
데이터베이스 구성.
SAML 인증과 관련된 문제인 경우 SAML 구성. Mattermost 서비스의 구성은 SAML IdP에 있습니다.
Mattermost가 연결하는 다른 시스템이나 사용자와 Mattermost 서버 사이에 있는 시스템.

구성 데이터 접근 방법#

Mattermost 구성

SELECT Value FROM Configurations WHERE Active = 1;

리버스 프록시 구성

SAML 구성

LDAP 구성

LDAP 관리자는 다음 Mattermost LDAP 설정에 대한 올바른 값을 확인해야 합니다.

LDAP 서버 호스트 이름.
LDAP 연결 포트, 보안 및 인증서.
BaseDN, 바인드 사용자 이름 및 바인드 비밀번호.
사용자, 그룹, 게스트 및 관리자 필터.
표시 속성.

이러한 값은 텍스트 파일 또는 LDAP 서버의 스크린샷으로 제공할 수 있습니다.

기타 구성

로그#

필요한 이유#

사용 가능한 로그#

Mattermost

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

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

프록시

위치는 프록시 구성에 따라 다르지만 /var/log 에서 찾기 시작하는 것이 좋습니다. 프록시 관리자가 로그를 찾는 데 도움을 줄 수 있습니다.

데이터베이스

SAML, LDAP 및 기타 시스템

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

로그 접근 방법#

Mattermost

동작이 알려진 시간 또는 날짜에 시작된 경우 journalctl 을 사용하여 다음과 같이 로그를 가져옵니다.

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

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.

시스템 로그

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

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

영향받는 사용자#

필요한 이유#

포함할 정보#

다이렉트 메시지 및 그룹 메시지를 포함한 팀 및 채널 구성원.
인증 방법.
클라이언트 운영 체제 및 앱 버전.
사용자가 Mattermost 서버에 연결하는 방법.
가입 시기, 로그인 정보가 최근 변경되었는지, LDAP를 통해 동기화되고 있는지 등 이 사용자들이 공통으로 가지고 있는 다른 사항들.

에이전트 참고: 다음 정보도 필요합니다.

고객 이름
고객 연락처
고객 라이선스(예: Enterprise/Professional)
고객 티어

환경#

포함할 정보#

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의 유형 및 버전

예시

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

기본: db1.local.lan

읽기 전용: db2.local.lan, db3.local.lan

PostgreSQL v13

Elasticsearch 서버

호스트 이름: elastic.local.lan

다음 플러그인이 설치된 Elasticsearch v7.9

analysis-icu

재현 단계#

재현 단계란#

재현 단계의 간단한 요약도 도움이 됩니다. 예시를 원한다면 Mattermost Jira 티켓 중 버그 티켓을 참고하세요.

이러한 세부 사항을 제공하는 방법#

macOS

Windows

Ctrl Shift S 를 눌러 스니핑 도구를 열어 스크린샷을 찍습니다. 화면 녹화를 원한다면 OBS와 같은 서드파티 소프트웨어를 설치해야 합니다.

iOS

iPhone에서 스크린샷이나 화면 녹화를 합니다.

Android

Android 기기에서 스크린샷을 찍거나 화면을 녹화합니다.

부록#

모바일 문제 관련 참고 사항

SAML 로그인 문제

키 및 인증서 확인#

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

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

-----BEGIN CERTIFICATE-----$ 로 시작해야 합니다.
모든 줄은 $ 로 끝나야 합니다. ^M$ 로 끝나는 경우 dos2unix 로 UNIX 줄 끝으로 변환합니다.
-----END CERTIFICATE-----$ 로 끝나야 합니다.