InfoGrab Docs

일반 배포 문제 해결

요약

이 문서에서는 일반적인 배포 문제 해결 방법을 요약합니다. Mattermost 서버가 시스템 부팅 시 시작되도록 하려면 systemd 유닛 파일을 활성화해야 합니다. 데이터베이스가 Mattermost 서버와 같은 시스템에 있는 경우, 기본 /lib/systemd/system/mattermost.service systemd 유닛 파일을 편집하여 [Unit] 섹션에 After=postgresql.service 와 BindsTo=p...

이 문서에서는 일반적인 배포 문제 해결 방법을 요약합니다. 일부는 직접 수행할 수 있고, 다른 일부는 네트워크 관리자와 상담이 필요할 수 있습니다.

시스템 부팅 시 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 바이너리는 해당 바인딩을 위한 올바른 권한이 필요합니다. 다음 명령을 실행하여 새 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 서버 로그#

  • 로그 파일이 생성되고 있는지 확인합니다: 시스템 콘솔 > 환경 > 로깅 으로 이동하여 파일에 로그 출력 이 true 로 설정되어 있는지 확인합니다.
  • 시스템 콘솔 > 환경 > 로깅 > 파일 로그 디렉터리 에서 로그 파일 경로를 확인할 수 있습니다.
결과 서버 로그 파일은 mattermost.log 라고 하며 표준 텍스트 편집기로 열거나 직접 공유할 수 있습니다.
Note

더 완전한 로그를 위해 시스템 콘솔 > 환경 > 로깅 을 열고 파일 로그 레벨 을 DEBUG 로 설정한 다음 문제를 다시 발생시켜 로그를 기록합니다. 디스크 공간을 절약하기 위해 문제 해결 후 파일 로그 레벨을 INFO 로 되돌려 놓으세요.

파일시스템 접근이 불가능한 경우 시스템 콘솔 > 보고 > 서버 로그 로 이동하여 파일로 복사할 수 있는 현재 시스템 로그를 찾으세요.

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

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

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

  1. 시스템 콘솔 > 보고 > 서버 로그 나 지원 패킷에 로그 파일이 표시되지 않으면 서버 콘솔에서 오류 메시지를 확인하여 로그 파일 경로가 허용된 디렉터리 외부에 있는지 확인합니다: "Blocked attempt to read log file outside allowed root" MM_LOG_PATH 환경 변수로 지정된 디렉터리 외부에 있는 로그 파일 경로는 오류를 생성하고 지원 패킷 다운로드에서 제외됩니다. MM_LOG_PATH 가 설정되지 않은 경우 기본 logs 디렉터리가 사용됩니다.

    2. 오류 메시지는 잘못된 경로가 있는 구성 설정을 식별합니다:

    • LogSettings.FileLocation - 기본 서버 로그 파일
    • LogSettings.AdvancedLoggingJSON - 고급 로깅 파일 대상
    • ExperimentalAuditSettings.AdvancedLoggingJSON - 감사 로깅 파일 대상
  2. 다음 해결 방법 중 하나를 선택합니다:

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

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

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

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 환경 검토#

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

  • 일정 기간의 정상 작동 후 문제가 발생한 경우, 환경에서 변경된 사항이 있나요?
  • 클라이언트, 호스트 또는 서버가 업그레이드되었나요?
  • 운영 체제 업데이트가 적용되었나요?
  • 네트워크 환경이 변경되었나요? 예를 들어, 서버가 이동되거나 도메인이 마이그레이션되었나요?
  • 시스템(클라이언트 또는 서버)이 최근 실패하거나 비정상적으로 종료되었나요?
  • 영향을 받는 사용자는 몇 명인가요?
  • 이 문제가 한 명, 일부 또는 모든 사용자에게 영향을 미치나요?
  • 신입사원과 같이 최근 환경에 추가된 사용자에게만 문제가 발생하나요?
  • 영향을 받는 사용자와 받지 않는 사용자 사이에 차이점이 있나요?
오류 메시지를 온라인에서 검색할 수도 있습니다. 포럼 에서 기존 해결 방법을 찾아 적용할 수 있습니다.

다른 서버에 연결#

  1. https://community.mattermost.com에서 계정을 생성합니다.
  2. 모바일 애플리케이션을 삭제하고 다시 설치합니다.
  3. 모바일 앱에서 서버 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;

<p><strong>리버스 프록시 구성</strong>

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

<p>압축된 로그는 서버의 <code>/tmp/mattermost.log.tgz</code> 에 저장됩니다.

압축 파일이 여전히 너무 큰 경우 다음 명령을 사용하여 압축 파일을 20MB 파일 두 개 이상으로 분할합니다:

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

<p>압축된 파일은 서버의 <code>/tmp/mattermost-logs</code> 에 저장되며 <code>mattermost.log.tgz.aa</code>, <code>mattermost.log.tgz.ab</code> 등으로 이름이 지정됩니다. Cyberduck과 같이 SSH/SFTP를 지원하는 파일 전송 클라이언트를 사용하여 서버에서 이 파일들을 복사합니다.

Elasticsearch, LDAP 또는 데이터베이스와 관련된 문제가 있는 경우 각 설정 아래의 Trace 를 true 로 설정하여 config.json 에서 추적 로깅을 활성화할 수 있습니다. 이를 DEBUG 레벨 파일 로그 출력과 결합하면 엄청나게 큰 로그 파일이 생성되므로 동작을 재현하기에 충분한 시간 동안만 추적 로깅을 켜두세요. 결과 로그에는 사용자 데이터를 포함하여 훨씬 더 많은 민감한 데이터가 포함되므로 공유하기 전에 완전히 정리하세요.

시스템 로그

다른 시스템의 로그 파일 위치는 다양하지만 Mattermost 서버의 모든 프로세스에 대한 로그를 가져오는 좋은 방법은 다음과 같이 journalctl 을 사용하는 것입니다:

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

<p>2020-08-23 17:15:00을 오류가 발생한 날짜와 시간(서버 기준)으로 바꿉니다. 동일한 타임스탬프 형식으로 <code>--until</code> 을 사용하여 두 시간 사이의 로그를 가져올 수 있습니다:

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

<h3 id="영향받는-사용자">영향받는 사용자</h3>

<h4 id="필요한-이유">필요한 이유</h4>

<p>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 with these plugins
  • 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 서버가 시스템 부팅 시 시작되도록 하려면 systemd 유닛 파일을 활성화해야 합니다. 데이터베이스가 Mattermost 서버와 같은 시스템에 있는 경우, 기본 /lib/systemd/system/mattermost.service systemd 유닛 파일을 편집하여 [Unit] 섹션에 After=postgresql.service 와 BindsTo=p...

이 문서에서는 일반적인 배포 문제 해결 방법을 요약합니다. 일부는 직접 수행할 수 있고, 다른 일부는 네트워크 관리자와 상담이 필요할 수 있습니다.

시스템 부팅 시 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 바이너리는 해당 바인딩을 위한 올바른 권한이 필요합니다. 다음 명령을 실행하여 새 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 서버 로그#

  • 로그 파일이 생성되고 있는지 확인합니다: 시스템 콘솔 > 환경 > 로깅 으로 이동하여 파일에 로그 출력 이 true 로 설정되어 있는지 확인합니다.
  • 시스템 콘솔 > 환경 > 로깅 > 파일 로그 디렉터리 에서 로그 파일 경로를 확인할 수 있습니다.
결과 서버 로그 파일은 mattermost.log 라고 하며 표준 텍스트 편집기로 열거나 직접 공유할 수 있습니다.
Note

더 완전한 로그를 위해 시스템 콘솔 > 환경 > 로깅 을 열고 파일 로그 레벨 을 DEBUG 로 설정한 다음 문제를 다시 발생시켜 로그를 기록합니다. 디스크 공간을 절약하기 위해 문제 해결 후 파일 로그 레벨을 INFO 로 되돌려 놓으세요.

파일시스템 접근이 불가능한 경우 시스템 콘솔 > 보고 > 서버 로그 로 이동하여 파일로 복사할 수 있는 현재 시스템 로그를 찾으세요.

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

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

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

  1. 시스템 콘솔 > 보고 > 서버 로그 나 지원 패킷에 로그 파일이 표시되지 않으면 서버 콘솔에서 오류 메시지를 확인하여 로그 파일 경로가 허용된 디렉터리 외부에 있는지 확인합니다: "Blocked attempt to read log file outside allowed root" MM_LOG_PATH 환경 변수로 지정된 디렉터리 외부에 있는 로그 파일 경로는 오류를 생성하고 지원 패킷 다운로드에서 제외됩니다. MM_LOG_PATH 가 설정되지 않은 경우 기본 logs 디렉터리가 사용됩니다.

    2. 오류 메시지는 잘못된 경로가 있는 구성 설정을 식별합니다:

    • LogSettings.FileLocation - 기본 서버 로그 파일
    • LogSettings.AdvancedLoggingJSON - 고급 로깅 파일 대상
    • ExperimentalAuditSettings.AdvancedLoggingJSON - 감사 로깅 파일 대상
  2. 다음 해결 방법 중 하나를 선택합니다:

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

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

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

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 환경 검토#

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

  • 일정 기간의 정상 작동 후 문제가 발생한 경우, 환경에서 변경된 사항이 있나요?
  • 클라이언트, 호스트 또는 서버가 업그레이드되었나요?
  • 운영 체제 업데이트가 적용되었나요?
  • 네트워크 환경이 변경되었나요? 예를 들어, 서버가 이동되거나 도메인이 마이그레이션되었나요?
  • 시스템(클라이언트 또는 서버)이 최근 실패하거나 비정상적으로 종료되었나요?
  • 영향을 받는 사용자는 몇 명인가요?
  • 이 문제가 한 명, 일부 또는 모든 사용자에게 영향을 미치나요?
  • 신입사원과 같이 최근 환경에 추가된 사용자에게만 문제가 발생하나요?
  • 영향을 받는 사용자와 받지 않는 사용자 사이에 차이점이 있나요?
오류 메시지를 온라인에서 검색할 수도 있습니다. 포럼 에서 기존 해결 방법을 찾아 적용할 수 있습니다.

다른 서버에 연결#

  1. https://community.mattermost.com에서 계정을 생성합니다.
  2. 모바일 애플리케이션을 삭제하고 다시 설치합니다.
  3. 모바일 앱에서 서버 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;

<p><strong>리버스 프록시 구성</strong>

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

<p>압축된 로그는 서버의 <code>/tmp/mattermost.log.tgz</code> 에 저장됩니다.

압축 파일이 여전히 너무 큰 경우 다음 명령을 사용하여 압축 파일을 20MB 파일 두 개 이상으로 분할합니다:

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

<p>압축된 파일은 서버의 <code>/tmp/mattermost-logs</code> 에 저장되며 <code>mattermost.log.tgz.aa</code>, <code>mattermost.log.tgz.ab</code> 등으로 이름이 지정됩니다. Cyberduck과 같이 SSH/SFTP를 지원하는 파일 전송 클라이언트를 사용하여 서버에서 이 파일들을 복사합니다.

Elasticsearch, LDAP 또는 데이터베이스와 관련된 문제가 있는 경우 각 설정 아래의 Trace 를 true 로 설정하여 config.json 에서 추적 로깅을 활성화할 수 있습니다. 이를 DEBUG 레벨 파일 로그 출력과 결합하면 엄청나게 큰 로그 파일이 생성되므로 동작을 재현하기에 충분한 시간 동안만 추적 로깅을 켜두세요. 결과 로그에는 사용자 데이터를 포함하여 훨씬 더 많은 민감한 데이터가 포함되므로 공유하기 전에 완전히 정리하세요.

시스템 로그

다른 시스템의 로그 파일 위치는 다양하지만 Mattermost 서버의 모든 프로세스에 대한 로그를 가져오는 좋은 방법은 다음과 같이 journalctl 을 사용하는 것입니다:

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

<p>2020-08-23 17:15:00을 오류가 발생한 날짜와 시간(서버 기준)으로 바꿉니다. 동일한 타임스탬프 형식으로 <code>--until</code> 을 사용하여 두 시간 사이의 로그를 가져올 수 있습니다:

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

<h3 id="영향받는-사용자">영향받는 사용자</h3>

<h4 id="필요한-이유">필요한 이유</h4>

<p>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 with these plugins
  • 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-----$ 로 끝나야 합니다.