일반 배포 문제 해결#

이 문서는 일반적인 배포 문제 해결 이슈와 해결 방법을 요약합니다. 일부 제안사항은 직접 수행할 수 있지만, 다른 사항들은 네트워크 관리자의 상담이 필요할 수 있습니다.

시스템 부팅 시 Mattermost 시작하기#

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

sudo systemctl enable mattermost.service

데이터베이스가 Mattermost 서버와 동일한 시스템에 있는 경우, 기본 /lib/systemd/system/mattermost.service systemd 유닛 파일을 편집하여 [Unit] 섹션에 After=postgresql.service 와 BindsTo=postgresql.service 를 추가하는 것을 권장합니다.

프록시 없이 Mattermost 실행하기#

Mattermost는 8065 대신 443에 바인딩됩니다. Mattermost 바이너리는 해당 바인딩을 위해 올바른 권한이 필요합니다. 다음 명령어를 실행하여 CAP_NET_BIND_SERVICE 기능을 활성화하여 새 Mattermost 바이너리가 1024 미만의 포트에 바인딩할 수 있도록 해야 합니다:

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

참고

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

Mattermost 로그 검토하기#

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

Mattermost 서버 로그#

로그 파일이 생성되고 있는지 확인하세요: 시스템 콘솔 > 환경 > 로깅 으로 이동하여 파일에 로그 출력 이 true 로 설정되어 있는지 확인하세요.
시스템 콘솔 > 환경 > 로깅 > 파일 로그 디렉토리 에서 로그 파일의 경로를 확인할 수 있습니다.

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

참고

더 자세한 로그를 위해 시스템 콘솔 > 환경 > 로깅 을 열고 파일 로그 레벨 을 DEBUG 로 설정한 다음 문제를 재현하여 다시 로그를 기록하세요. 문제 해결 후 디스크 공간을 절약하기 위해 파일 로그 레벨을 INFO 로 되돌리는 것을 잊지 마세요.

파일 시스템에 접근할 수 없는 경우 시스템 콘솔 > 보고서 > 서버 로그 로 이동하여 파일로 복사할 수 있는 현재 시스템 로그를 찾을 수 있습니다.

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

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 (Appstore 설치만 해당)

Mattermost 웹 로그#

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

Mattermost 푸시 알림 서비스 로그#

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

Mattermost 환경 검토#

오류/문제가 발생하기 전의 이벤트를 제거하기 위해 타임라인을 작성하세요. 예를 들어, 최근에 방화벽을 재구성했고 현재 연결 문제가 발생하고 있다면 설정을 검토하거나 롤백하여 문제가 해결되는지 확인하는 것이 좋습니다.

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

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

다른 서버에 연결#

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

다른 기기로 연결#

다른 모바일 기기를 사용할 수 있다면, 해당 기기로 연결하여 문제가 여전히 재현되는지 확인해보세요.
다른 기기를 사용할 수 없는 경우, 다른 팀원들에게 동일한 문제가 발생하는지 확인하세요.

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

Mattermost 제품의 유료 구독 이 있는 경우, 예를 들어 Mattermost Professional 또는 Mattermost Enterprise 가 있다면, 온라인 지원 포털 을 통해 지원 티켓을 열 수 있습니다.

유료 구독의 일부로 지원 티켓을 열 때는 가능한 한 많은 정보를 적시에 제공하는 것이 중요합니다. 어떤 정보가 관련 있는지 파악하는 것이 혼란스러울 수 있습니다. 우리는 필요한 사항을 기억하기 위해 C.L.U.E.S.라는 약어를 사용합니다:

구성
로그
영향을 받는 사용자
환경
재현 단계

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

로그에서 최대한 많은 정보를 얻을 수 있도록 디버그 로깅이 활성화되어 있는지 확인하세요. 이를 위해 시스템 콘솔 > 환경 > 로깅 으로 이동한 다음 콘솔 파일 레벨 과 파일 로그 레벨 을 모두 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

영향을 받는 사용자#

필요한 이유#

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 13)
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

주 서버: 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-----$ 로 끝나야 합니다.