Mattermost 서버 업그레이드

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

Entry, Professional, Enterprise, Enterprise Advanced 플랜에서 사용할 수 있습니다.

대부분의 경우 Mattermost 서버 업그레이드는 몇 분이면 끝납니다. 다만 설치 규모와 복잡도, 그리고 업그레이드 이전 버전 등 여러 요인에 따라 더 오래 걸릴 수 있습니다.

Mattermost를 처음 업그레이드하는 경우라면 아래의 종합 업그레이드 가이드를 읽어 보시기 바랍니다. 업그레이드 절차에 익숙한 숙련된 시스템 관리자라면 빠른 시작 체크리스트를 참고하세요.

빠른 시작

Mattermost 업그레이드 절차를 빠르게 훑어보려는 숙련된 시스템 관리자는 다음 4단계 체크리스트를 사용할 수 있습니다.

진행하기 전에 데이터베이스와 애플리케이션을 포함한 시스템 전체 백업을 확보합니다.
시스템 요구 사항: 서버와 PostgreSQL 버전이 Mattermost 요구 사항을 충족하는지 확인합니다.
준비 단계
- 최신 서버 버전을 다운로드합니다.
- 새 파일을 임시 위치(/tmp)에 압축 해제합니다.
- 현재 Mattermost 디렉터리를 확인합니다(기본값: /opt/mattermost).
업그레이드 절차
- Mattermost 서비스를 중지합니다: sudo systemctl stop mattermost
- 기존 애플리케이션 파일을 제거합니다(config, data, logs, plugins는 보존).
- 새 파일을 설치 디렉터리로 복사합니다.
- 파일 소유권을 변경합니다: sudo chown -R mattermost:mattermost mattermost
- 필요한 경우 낮은 포트 사용을 위한 capability를 설정합니다: sudo setcap cap_net_bind_service=+ep ./mattermost/bin/mattermost
- Mattermost 서비스를 시작합니다: sudo systemctl start mattermost
- 임시 업그레이드 파일을 삭제합니다.

자세한 절차와 추가로 고려할 사항은 아래의 전체 업그레이드 가이드를 참고하세요.

팁

고가용성 및 Active/Active 지원을 위해 Kubernetes 배포를 안전하게 업그레이드하는 방법은 Kubernetes·고가용성 환경 업그레이드 문서를 참고하세요.

종합 업그레이드 가이드

시작하기 전에

이 안내를 처음부터 끝까지 꼼꼼히 읽으세요.

중요

Mattermost v11.0으로 업그레이드하기 전: 현재 Bleve 검색(System Console > Experimental > Bleve(시스템 콘솔 > 실험 기능 > Bleve))을 사용 중이라면, 업그레이드 전에 DisableDatabaseSearch가 false로 설정되어 있는지 확인하세요. 그렇지 않으면 업그레이드 후 검색이 동작하지 않습니다. Bleve 검색은 v11.0에서 제거되었습니다. 엔터프라이즈 검색 기능이 필요하다면 엔터프라이즈 검색 기능을 위해 Elasticsearch나 OpenSearch로의 마이그레이션을 검토하세요.

Mattermost 업그레이드를 시작하기 전에 업그레이드를 준비하는 방법을 이해하고, 소프트웨어 및 하드웨어 요구 사항을 모두 숙지하며, 주요 업그레이드 참고 사항을 읽고, 아래에 설명된 업그레이드 절차의 각 단계를 이해했는지 확인하세요. 궁금한 점이나 우려되는 부분이 있다면 Mattermost 포럼(https://forum.mattermost.com/)에서 문의할 수 있습니다.

업그레이드를 시작하기 전에 다음 정보를 수집하세요.

기존 설치 디렉터리 - {install-path}: Mattermost 서버가 어디에 설치되어 있는지 모른다면 whereis mattermost 명령으로 표준 바이너리 위치와 $PATH를 확인하세요.
- /opt/mattermost/bin이 PATH에 추가되어 있지 않으면 이 명령은 아무것도 반환하지 않습니다.
- 또는 find / -executable -type f -iname mattermost 2> /dev/null 명령으로 mattermost 바이너리를 찾을 수 있습니다.
- 출력은 /opt/mattermost/bin/mattermost와 비슷한 형태여야 합니다.
- 설치 디렉터리는 문자열 /mattermost가 처음 등장하기 전까지의 전체 경로입니다. 이 예시에서 {install-path}는 /opt입니다.
- 이 명령으로 아무 결과도 나오지 않는다면 버전이 오래되었을 가능성이 큽니다. 이 경우 whereis platform을 대신 사용해 보세요.
로컬 스토리지 디렉터리의 위치와 크기: 로컬 스토리지 디렉터리에는 사용자가 메시지에 첨부한 모든 파일이 들어 있습니다.
- 위치를 모른다면 시스템 콘솔을 열고 Environment > File Storage(환경 > 파일 스토리지)로 이동해 Local Storage Directory 값을 확인하세요.
- 경로는 mattermost 디렉터리를 기준으로 한 상대 경로입니다. 예를 들어 로컬 스토리지 디렉터리가 ./data/라면 절대 경로는 {install-path}/mattermost/data입니다.
데이터베이스 디스크 공간: 데이터베이스와 같은 서버에서 Mattermost 배포를 업그레이드하는 경우, 압축 해제·복사·정리를 위해 최소 2GB의 여유 디스크 공간과, 데이터베이스를 위해 Mattermost 설치 크기의 최소 두 배에 해당하는 공간을 확보할 것을 권장합니다.

팁

업그레이드 시 mattermost db migrate --save-plan CLI 명령으로 마이그레이션 계획을 생성해 두면 데이터베이스에 적용될 변경 사항을 상세히 기록할 수 있습니다. 이후 다운그레이드가 필요할 때 변경 사항을 되돌리기가 쉬워집니다.

Mattermost 서버 업그레이드

Mattermost가 실행 중인 서버에서 터미널 창을 열고 홈 디렉터리로 이동합니다. 이전에 내려받아 남아 있는 파일과 디렉터리가 있다면 삭제하세요.
```
cd /tmp
```
사용 중인 Mattermost 에디션에 맞는 최신 버전의 Mattermost 서버를 다운로드합니다.

Enterprise Edition

다음 명령에서 X.X.X를 내려받으려는 버전으로 바꾸세요.
```
wget https://releases.mattermost.com/X.X.X/mattermost-X.X.X-linux-amd64.tar.gz
```
Team Edition

다음 명령에서 X.X.X를 내려받으려는 버전으로 바꾸세요.
```
wget https://releases.mattermost.com/X.X.X/mattermost-team-X.X.X-linux-amd64.tar.gz
```
/tmp 디렉터리에 다른 Mattermost 압축 파일이 없는지 확인합니다. 다른 버전의 압축 파일이 있다면 삭제하거나 이름을 바꾸세요.
```
ls -- mattermost*.gz
```
위 명령에서 새 릴리스 외에 다른 것이 나온다면 해당 파일의 이름을 바꾸거나 완전히 삭제하세요.
Mattermost 서버 파일을 압축 해제합니다.
```
tar -xf mattermost*.gz --transform='s,^[^/]\+,\0-upgrade,'
```
transform 옵션은 압축 해제되는 최상위 디렉터리에 접미사를 붙여 기존 설치 디렉터리와 충돌하지 않도록 합니다.
Mattermost 서버를 중지합니다.
```
sudo systemctl stop mattermost
```
데이터와 애플리케이션을 백업합니다. 업그레이드를 계속하기 전에 데이터베이스가 제대로 백업되었는지 반드시 확인하세요. 예기치 못한 오류가 발생했을 때 이전 데이터베이스 스냅숏을 복원할 수 있어야 합니다.
1. 조직의 표준 데이터베이스 백업 절차에 따라 데이터베이스를 백업합니다.
2. 애플리케이션을 아카이브 폴더(예: mattermost-back-YYYY-MM-DD-HH-mm)로 복사해 백업합니다.
```
cd {install-path}
sudo cp -ra mattermost/ mattermost-back-$(date +'%F-%H-%M')/
```
현재 mattermost 디렉터리 안에서 data 디렉터리와 사용자 정의 디렉터리를 제외한 모든 파일을 제거합니다. 아래 명령을 실행하기 전에 이어지는 중요 안내를 반드시 읽어 보시기 바랍니다.
```
sudo find mattermost/ mattermost/client/ -mindepth 1 -maxdepth 1 \! $ -type d \( -path mattermost/client -o -path mattermost/client/plugins -o -path mattermost/config -o -path mattermost/logs -o -path mattermost/plugins -o -path mattermost/data $ -prune \) | sort | sudo xargs rm -r
```
중요
기본적으로 업그레이드 시 다음 하위 디렉터리는 보존됩니다: config, logs, plugins, client/plugins, data. 사용자 정의 디렉터리를 포함해 Mattermost에 직접 추가한 그 밖의 모든 디렉터리는 기본적으로 보존되지 않습니다. 일반적으로 이런 디렉터리에는 TLS 키나 그 밖의 사용자 정의 정보가 들어 있으며, data 이외의 위치로 설정한 로컬 스토리지 디렉터리나 첨부 파일 저장용 사용자 정의 디렉터리도 여기에 해당할 수 있습니다.

업그레이드를 계속하기 전에 다음을 수행할 것을 강력히 권장합니다.
1. 업그레이드 전에 Mattermost 설치 디렉터리에서 ls를 실행해 존재하는 기본 폴더를 모두 확인합니다.
  
  기본 Mattermost 설치에는 다음 파일과 디렉터리가 있습니다.
```
$ ls /opt/mattermost
ENTERPRISE-EDITION-LICENSE.txt README.md  client  data   i18n  manifest.txt  prepackaged_plugins
NOTICE.txt                      bin        config  fonts  logs  plugins       templates
```
2. 다음 명령을 실행해, 지정한 디렉터리와 그 내용만 보존하고 mattermost 폴더의 나머지 내용을 삭제하는 작업을 미리 시험해 봅니다. 위에 제시한 명령과 같지만 sudo xargs rm -r만 빠져 있습니다.
```
sudo find mattermost/ mattermost/client/ -mindepth 1 -maxdepth 1 \! $ -type d \( -path mattermost/client -o -path mattermost/client/plugins -o -path mattermost/config -o -path mattermost/logs -o -path mattermost/plugins -o -path mattermost/data $ -prune \) | sort
```
3. TLSCert/TLSKey 파일이나 그 밖의 정보를 /opt/mattermost 폴더 안에 저장하고 있다면, 백업에서 TLSCert/TLSKey 파일을 새 설치 디렉터리로 수동 복사하지 않아도 되도록 위 명령에 -o -path mattermost/yourFolderHere를 추가해야 합니다.
```
sudo find mattermost/ mattermost/client/ -mindepth 1 -maxdepth 1 \! $ -type d \( -path mattermost/client -o -path mattermost/client/plugins -o -path mattermost/config -o -path mattermost/logs -o -path mattermost/plugins -o -path mattermost/data -o -path  mattermost/yourFolderHere $ -prune \) | sort
```
4. Bleve 검색을 사용하고 있고 해당 디렉터리가 mattermost 디렉터리 안에 있다면, 위 명령으로는 인덱스 디렉터리 경로가 보존되지 않습니다.
  - 업그레이드 전에 bleve 인덱스 디렉터리를 mattermost 디렉터리 밖으로 옮기거나, 업그레이드 후 backup 디렉터리에서 bleve 인덱스 디렉터리의 내용을 복사할 수 있습니다.
  - 그런 다음 해당 디렉터리를 그대로 보관하거나 원하는 대로 다시 인덱싱하면 됩니다.
  - bleve 인덱스는 Mattermost 버전 간에 다시 인덱싱하지 않고도 마이그레이션할 수 있습니다. bleve 인덱스 디렉터리 설정에 대한 자세한 내용은 설정 항목 문서를 참고하세요.
위 단계를 모두(해당하는 경우) 완료했다면 이제 xargs rm -r가 포함된 전체 명령을 실행해 파일을 삭제할 수 있습니다. 다음 예시에는 -o -path mattermost/yourFolderHere가 포함되어 있습니다.
```
sudo find mattermost/ mattermost/client/ -mindepth 1 -maxdepth 1 \! $ -type d \( -path mattermost/client -o -path mattermost/client/plugins -o -path mattermost/config -o -path mattermost/logs -o -path mattermost/plugins -o -path mattermost/data -o -path  mattermost/yourFolderHere $ -prune \) | sort | sudo xargs rm -r
```
새 파일을 설치 디렉터리로 복사합니다.
```
sudo cp -an /tmp/mattermost-upgrade/. mattermost/
```
참고
n(no-clobber) 플래그와 원본 경로 끝의 .은 매우 중요합니다. n(no-clobber) 플래그는 설치 경로에 있는 기존 설정과 로그를 보존합니다. 원본 경로 끝의 .은 모든 설치 파일이 복사되도록 보장합니다.
파일을 복사한 뒤 새 파일의 소유권을 변경합니다. 예를 들면 다음과 같습니다.
```
sudo chown -R mattermost:mattermost mattermost
```
참고
- 설치 디렉터리의 소유자와 그룹으로 mattermost를 사용하지 않았다면 sudo chown -hR {owner}:{group} {install-path}/mattermost를 실행하세요.
- 어떤 소유자나 그룹이 지정되어 있는지 확실하지 않다면 ls -l {install-path}/mattermost/bin/mattermost 명령으로 확인할 수 있습니다.
서버 서비스에 80번 또는 443번 포트를 사용하려 하거나 Mattermost 서버에 TLS를 설정했다면, 새 Mattermost 바이너리가 1024번 미만 포트에 바인딩할 수 있도록 CAP_NET_BIND_SERVICE capability를 반드시 활성화해야 합니다. 예를 들면 다음과 같습니다.
```
sudo setcap cap_net_bind_service=+ep ./mattermost/bin/mattermost
```
Mattermost 서버를 시작합니다.
```
sudo systemctl start mattermost
```

임시 파일을 삭제합니다.

sudo rm -r /tmp/mattermost-upgrade/
sudo rm -i /tmp/mattermost*.gz

고가용성 배포를 사용하고 있다면 클러스터의 모든 노드에 위 단계를 적용해야 합니다. 작업이 끝나면 시스템 콘솔의 고가용성 섹션에서 Config File MD5 열이 녹색으로 표시되어야 합니다. 노란색으로 표시된다면 모든 노드가 동일한 서버 버전과 동일한 설정을 사용하고 있는지 확인하세요.

계속 노란색으로 표시된다면 시스템 콘솔을 열고 설정을 변경했다가 되돌려 클러스터 전체에 설정 전파를 트리거하세요. 그러면 해당 페이지의 Save(저장) 버튼이 활성화됩니다. 그다음 Save를 선택하세요. 이 작업은 설정을 변경하지는 않지만 기존 설정을 클러스터의 모든 노드로 전송합니다.

서버가 업그레이드된 후에는 사용자가 새 기능을 사용하기 위해 브라우저를 새로 고쳐야 할 수 있습니다.

Team Edition을 Enterprise Edition으로 업그레이드

Team Edition에서 Enterprise Edition으로 업그레이드하려면 위에 안내된 일반 업그레이드 절차를 따르되, 2단계에서 Enterprise Edition 버전의 Mattermost 서버를 내려받으면 됩니다.

라이선스 키 업로드

Enterprise Edition이 실행 중이면 System Console > About > Editions and License를 열고 라이선스 키를 업로드하세요.