개요#

Mattermost는 Rocket.Chat에서의 마이그레이션 경로를 제공하여, 사용자, 채널, 메시지, 스레드, 다이렉트 메시지, 반응, 파일 첨부 파일을 자체 호스팅형 Mattermost 환경으로 가져올 수 있도록 합니다.

Rocket.Chat에는 호스팅된 "워크스페이스 내보내기" 기능이 없습니다. 대신 mongodump로 기반이 되는 MongoDB 데이터베이스를 내보낸 다음, mmetl 도구를 사용해 그 덤프를 Mattermost 대량 가져오기 파일로 변환합니다. 즉, 내보내기 단계는 일반적으로 Rocket.Chat 서버와 해당 MongoDB 인스턴스에 대한 접근이 필요한 데이터베이스 작업입니다.

마이그레이션은 여러 단계로 이루어진 프로세스입니다:

1. 준비 — 마이그레이션 범위를 정하고, MongoDB 및 첨부 파일 스토리지 세부 정보를 수집하며, Mattermost 서버를 준비합니다.
2. Rocket.Chat 데이터 내보내기 — Rocket.Chat 데이터베이스의 mongodump를 생성합니다.
3. 내보내기 변환 — mmetl check rocketchat으로 검증하고 mmetl transform rocketchat으로 변환합니다.
4. Mattermost로 가져오기 — mmctl로 아카이브를 업로드하고 처리합니다.
5. 검증, 테스트 후 서비스 전환(go-live)을 진행합니다.

1. 준비#

이 가이드는 이미 데이터를 받을 준비가 된 Mattermost 서버가 배포되어 있다고 가정합니다. 그렇지 않다면 먼저 배포 문서를 검토하세요.

범위 정의#

• 데이터 기록: 필요한 기록 범위를 결정합니다. mongodump는 데이터베이스 전체를 캡처하므로, 범위 설정은 내보내기 자체를 축소하기보다는 마이그레이션하고 검증할 대상을 통해 주로 이루어집니다.
• 내보내기 크기: Rocket.Chat 데이터베이스와 첨부 파일의 크기는 처리 및 가져오기 시간에 직접적인 영향을 미칩니다. 대규모 배포 환경에서는 더 긴 반복 주기를 계획하세요.
• 파일 첨부 파일: 초기 테스트 실행 시 반복 속도를 높이기 위해 --skip-attachments로 매우 크거나 중요하지 않은 첨부 파일을 제외하는 것을 고려하세요.

Rocket.Chat / MongoDB 사전 요구 사항#

• Rocket.Chat MongoDB 인스턴스와 MongoDB Database Tools의 mongodump 도구에 접근할 수 있어야 합니다.
• 데이터베이스 이름(일반적으로 meteor)과 연결 URI를 확인합니다.
• 변환 과정은 덤프에서 다음 컬렉션을 읽습니다: users, rocketchat_room, rocketchat_message, rocketchat_subscription(모두 필수), 그리고 첨부 파일용 rocketchat_uploads와 rocketchat_uploads.chunks.

첨부 파일 스토리지: GridFS와 FileSystem#

Rocket.Chat은 업로드된 파일을 두 가지 방식 중 하나로 저장할 수 있습니다. 내보내기 전에 배포 환경이 어떤 방식을 사용하는지(Admin > Settings > File Upload > Storage Type) 확인하세요. 이에 따라 변환을 실행하는 방법이 달라집니다:

• GridFS(MongoDB 내부에 저장): 첨부 파일이 mongodump(rocketchat_uploads.chunks.bson)에 직접 캡처되어 자동으로 추출됩니다. 별도의 플래그가 필요하지 않습니다.
• FileSystem(디스크에 저장): mongodump에는 파일 메타데이터만 포함됩니다. Rocket.Chat 업로드 디렉터리도 별도로 복사한 다음, 변환 시 --uploads-dir로 해당 위치를 지정해야 합니다.

인프라 고려 사항#

• 테스트 환경: 항상 개발 또는 스테이징 환경에서 먼저 마이그레이션을 실행하세요. 대부분의 마이그레이션은 여러 차례의 반복이 필요합니다.
• 운영 체제: mmetl은 Linux와 macOS에서 지원됩니다. Windows(WSL 포함)는 권장되지 않습니다.
• 스토리지 요구 사항: mongodump 출력, 변환된 가져오기 파일, 추출된 첨부 파일을 저장할 공간이 충분한지 확인하세요. Rocket.Chat 데이터 크기의 몇 배에 해당하는 공간을 계획하세요.
• 파일 스토리지: 대용량 데이터셋의 경우 AWS S3(또는 S3 호환 스토리지)로의 가져오기가 로컬 또는 NFS 스토리지보다 일반적으로 더 빠르게 완료됩니다.

Mattermost 서버 고려 사항#

• 신규 서버: 가장 신뢰할 수 있는 가져오기는 새로 설치된 환경에서 이루어집니다. 기존 서버로 가져오는 경우, 기존 팀 위에 절대 덮어쓰기로 가져오지 말고 먼저 데이터베이스와 데이터 디렉터리를 백업하세요.
• 서버 버전: 최신 지원 버전의 Mattermost를 실행하세요.
• Mattermost에 대상 팀이 이미 존재해야 하며, 해당 팀에 대해 Allow any user with an account on this server to join this team이 활성화되어 있어야 합니다.
• 구성 설정: 가져오기 전에 다음을 조정하세요:
• TeamSettings.MaxChannelsPerTeam과 TeamSettings.MaxUsersPerTeam: 마이그레이션할 채널/사용자 수보다 훨씬 높게 설정합니다.
• EmailSettings.EnableSignUpWithEmail과 EmailSettings.EnableSignInWithEmail: 둘 다 true로 설정합니다.
• FileSettings.MaxFileSize: 내보내기에 포함된 가장 큰 파일보다 높게 설정합니다.
• ElasticsearchSettings.EnableIndexing, EnableSearching, EnableAutocomplete: 가져오기 중에는 false로 설정한 다음, 완료 후 삭제하고 다시 색인화합니다.

2. Rocket.Chat 데이터 내보내기#

mongodump로 Rocket.Chat MongoDB 데이터베이스를 내보냅니다. URI와 데이터베이스 이름을 배포 환경에 맞게 바꾸세요:

mongodump --uri="mongodb://localhost:3001/meteor" --out=/tmp/rc-dump

이 명령은 데이터베이스 이름을 딴 하위 디렉터리(예: /tmp/rc-dump/meteor)를 생성하며, 여기에 .bson 파일이 포함됩니다. 다음 단계에서 --dump-dir에 전달하는 것은 상위 디렉터리가 아니라 이 데이터베이스 하위 디렉터리입니다.

배포 환경이 첨부 파일에 FileSystem 스토리지를 사용하는 경우, Rocket.Chat 업로드 디렉터리도 알려진 위치로 복사하여 --uploads-dir로 참조할 수 있도록 하세요.

3. Mattermost를 위한 내보내기 변환#

사용 중인 OS와 아키텍처에 맞는 mmetl 최신 릴리즈 다운로드를 진행하세요. 도구에 대해 자세히 알아보려면 mmetl help를 실행하세요.

내보내기 검증#

변환하기 전에 덤프의 무결성을 확인하세요:

./mmetl check rocketchat --dump-dir /tmp/rc-dump/meteor

이 명령은 변환이나 가져오기를 실패하게 만들 수 있는 구조적 문제(예: 필수 컬렉션 누락 또는 잘못된 레코드)를 보고합니다. 자세한 내용은 check-rocketchat.log에 기록됩니다.

check rocketchat는 변환과 동일한 --guest-handling 플래그를 지원하므로, 전체 변환을 실행하기 전에 게스트 사용자가 어떻게 처리될지 미리 확인할 수 있습니다.

변환 실행#

덤프를 Mattermost 대량 가져오기 파일로 변환합니다. <TEAM-NAME>을 Mattermost 팀 이름으로 바꾸세요. 이름은 한 단어의 소문자여야 합니다(예: My Team이라는 팀은 my-team이 됩니다):

./mmetl transform rocketchat --team <TEAM-NAME> --dump-dir /tmp/rc-dump/meteor --output mattermost_import.jsonl

FileSystem 첨부 파일 스토리지의 경우 --uploads-dir를 추가합니다:

./mmetl transform rocketchat --team <TEAM-NAME> --dump-dir /tmp/rc-dump/meteor --uploads-dir /path/to/rocketchat/uploads --output mattermost_import.jsonl

이 도구는 사용자, 채널, 게시물이 포함된 .jsonl 파일과, 추출된 첨부 파일이 포함된 data 폴더를 생성합니다.

성공적으로 실행되면 transform-rocketchat.log에 다음과 같은 요약 줄이 기록됩니다:

Transformation succeeded! Users: 152, Public channels: 48, Private channels: 12, Posts: 39184

대신 오류와 함께 실행이 중단되는 경우 — 예를 들어 the RocketChat export contains bot users but --bot-owner was not specified — 유효한 가져오기 파일이 생성되지 않습니다. 오류를 해결한 다음(아래 플래그 참고) 다시 실행하세요.

유용한 변환 플래그#

• --uploads-dir <PATH>: Rocket.Chat FileSystem 업로드 디렉터리 경로입니다. 첨부 파일이 GridFS에 저장되어 있지 않은 경우 필수입니다.
• --bot-owner <USERNAME>: 가져온 모든 봇을 소유할 Mattermost 사용자의 사용자 이름입니다. 내보내기에 봇 사용자가 포함된 경우 필수이며, 지정하지 않으면 변환이 오류로 종료됩니다.
• --guest-handling <MODE>: Rocket.Chat 게스트 사용자를 마이그레이션하는 방식입니다(기본값 guest):
• guest — Mattermost 게스트로 마이그레이션합니다. 충실도가 가장 높지만, 대상 서버에서 Guest Accounts가 라이선스되어 있고(Professional/Enterprise) 활성화(GuestAccountsSettings.Enable)되어 있어야 합니다. 그렇지 않으면 계정이 올바르게 동작하지 않습니다.
• user — 일반 Mattermost 멤버로 마이그레이션합니다. 어디서나 동작하지만, 게스트에게 전체 멤버 권한이 부여됩니다.
• skip — 게스트 사용자를 멤버십 및 작성한 게시물과 함께 완전히 제외합니다.
• --skip-attachments / -a: 파일 첨부 파일 추출을 건너뜁니다. 테스트 중 더 빠르게 반복하는 데 유용합니다.
• --attachments-dir <PATH>: 추출된 첨부 파일을 저장할 디렉터리입니다(기본값 data).
• --default-email-domain <DOMAIN>: 사용자의 이메일이 없는 경우, 사용자 이름과 이 도메인을 조합해 이메일을 생성합니다(예: example.com).
• --skip-empty-emails: 이메일이 비어 있는 사용자를 허용합니다. 이렇게 하면 가져오기 전에 수정해야 하는 유효하지 않은 가져오기 데이터가 생성된다는 점에 유의하세요.
• --debug: 느리거나 실패하는 실행을 진단하는 데 도움이 되도록 transform-rocketchat.log에 DEBUG 수준의 세부 정보를 기록합니다.

4. Mattermost로 가져오기#

.jsonl 파일과 data 폴더를 하나의 zip 파일로 묶습니다:

zip -r mattermost-bulk-import.zip data mattermost_import.jsonl

업로드하기 전에 로컬에서 아카이브를 검증합니다:

mmctl import validate ./mattermost-bulk-import.zip

mmctl이 설치되어 있고 인증되어 있는지 확인합니다. 그런 다음 업로드 방식을 선택합니다.

표준 업로드#

대부분의 가져오기는 mmctl을 통해 업로드합니다:

mmctl import upload ./mattermost-bulk-import.zip
mmctl import list available

import list available에서 반환된 이름을 사용해 가져오기를 처리합니다:

mmctl import process <IMPORT FILE NAME>

작업 상태를 확인합니다. pending으로 표시되면 기다렸다가 다시 실행하세요. 오류 메시지를 확인하려면 --json 플래그가 필요합니다:

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

대용량 아카이브(수 GB)의 경우 mmctl을 통한 업로드는 느리고 오류가 발생하기 쉽습니다. 대신 아카이브를 서버의 가져오기 디렉터리에 직접 배치하여 서버가 그 자리에서 처리하도록 합니다:

1. Mattermost 파일 스토어의 data/import(로컬 데이터 디렉터리 또는 S3 버킷의 import 접두사)에 mattermost-bulk-import.zip(고유한 이름 사용)을 복사합니다.
2. mmctl import list available를 실행해 서버가 해당 파일을 인식하는지 확인합니다.
3. mmctl import process <IMPORT FILE NAME>를 실행하고 mmctl import job show <JOB ID> --json으로 진행 상황을 모니터링합니다.

이렇게 하면 API를 통해 기가바이트 단위의 데이터를 다시 업로드하지 않아도 되며, 대규모 마이그레이션에 권장되는 방식입니다.

읽지 않은 채널 및 스레드 수정#

가져온 후 모든 사용자에게 메시지가 읽지 않은 상태로 표시될 수 있습니다. 이를 해결하려면 Mattermost 데이터베이스에 다음을 실행하세요:

begin;
UPDATE channelmembers
SET
    msgcount = channels.totalmsgcount,
    lastupdateat = channels.lastpostat,
    lastviewedat = channels.lastpostat,
    msgcountroot = channels.totalmsgcountroot
FROM channels
WHERE channelmembers.channelid = channels.id;

INSERT INTO preferences (UserId, Category, Name, Value)
SELECT
    cm.userid,
    'channel_approximate_view_time',
    cm.channelid,
    cm.lastupdateat
FROM
    channelmembers cm
ON CONFLICT (userid, category, name)
DO UPDATE SET
    Value = EXCLUDED.Value;

update preferences set value = false where category = 'direct_channel_show';
update preferences set value = false where category = 'group_channel_show';

commit;

자리 표시자 이메일 및 계정 활성화#

Mattermost 계정은 내보내기에 포함된 이메일과 사용자 이름을 기반으로 생성됩니다. 이메일이 없는 경우 자리 표시자(예: username@local)가 생성되며, 시스템 관리자가 이를 수정해야 합니다. 가져오기 전에 최종 .jsonl 파일에서 자리 표시자 이메일을 검색하세요.

사용자는 이메일 주소를 사용해 Mattermost의 Password Reset 화면을 통해 계정을 활성화합니다:

• 시스템 관리자가 수행한 가져오기: 이메일이 자동으로 확인되며, 사용자는 즉시 비밀번호를 재설정할 수 있습니다.
• 관리자가 아닌 사용자가 수행한 가져오기: 사용자는 비밀번호를 재설정하기 전에 이메일 주소를 확인해야 합니다.

SSO를 사용하는 경우 사용자 인증을 LDAP 또는 SAML로 마이그레이션하는 방법을 참조하세요.

마이그레이션되는 항목과 되지 않는 항목#

게시물, 스레드, 반응, 첨부 파일, 사용자, 채널 등 핵심 협업 데이터는 높은 충실도로 마이그레이션됩니다. 통합 기능 및 Rocket.Chat 고유 기능은 이관되지 않습니다.

커스텀 이모지#

커스텀 이모지 이미지는 메시지와 함께 가져와지지 않습니다 — 반응에 사용된 이모지 이름만 보존됩니다. 반응은 텍스트(:emoji-name:)로 저장되며 렌더링 시점에 해석됩니다:

• Mattermost에 동일한 이름의 커스텀 이모지가 있으면 반응이 올바르게 렌더링됩니다.
• 없으면 이모지가 추가될 때까지 자리 표시자로 표시됩니다.

해석이 렌더링 시점에 이루어지므로, 가져오기 전이든 후든 언제든지 Mattermost에 커스텀 이모지를 추가할 수 있으며, 일치하는 이름이 존재하게 되면 과거 메시지의 반응도 렌더링됩니다. 이름은 정확히 일치해야 합니다.

FAQ#

가져오기 전에 사용자를 미리 만들어야 하나요?

아니요. mmetl과 가져오기 프로세스가 사용자 생성과 순서 지정을 자동으로 처리합니다.

동일한 가져오기를 두 번 실행하면 어떻게 되나요?

문제가 발생하지 않습니다. mmctl import는 멱등성을 가지므로 — 중복 게시물이 생성되지 않습니다 — 증분 가져오기와 반복적인 시범 가져오기 모두 안전합니다.

모든 채널과 DM은 어디로 가나요?

--team으로 지정한 단일 팀으로 들어갑니다. Rocket.Chat에는 다중 워크스페이스 개념이 없으므로 팀 매핑 단계가 필요하지 않습니다.

첨부 파일은 어떻게 저장되며, --uploads-dir가 왜 필요한가요?

Rocket.Chat은 파일을 MongoDB(GridFS) 또는 디스크(FileSystem)에 저장합니다. GridFS 파일은 mongodump에 자동으로 캡처되지만, FileSystem 파일은 그렇지 않으므로 --uploads-dir로 업로드 디렉터리를 지정해야 합니다. 첨부 파일 스토리지를 참조하세요.

가져오기 후 일부 채널이 누락된 이유는 무엇인가요?

종단 간 암호화된 채팅방은 건너뛰며 해당 메시지는 마이그레이션되지 않습니다. 건너뛴 채팅방은 transform-rocketchat.log에서 확인하세요.

메시지보다 먼저 커스텀 이모지를 가져와야 하나요?

아니요. 이모지는 렌더링 시점에 해석되므로 언제든 추가할 수 있습니다.

매우 큰 가져오기는 어떻게 처리하나요?

파일 스토어 방식을 사용하세요 — mmctl을 통해 업로드하는 대신 아카이브를 서버의 data/import 디렉터리에 직접 복사합니다. 대용량 가져오기를 참조하세요.

파싱 오류가 발생했습니다. 내보내기가 손상된 건가요?

반드시 그런 것은 아닙니다. Rocket.Chat은 버전 간에 MongoDB 스키마를 변경합니다(이 도구는 v8.5를 기준으로 검증되었습니다). 데이터에 문제가 있다고 단정하기 전에 먼저 mmetl check rocketchat을 실행하고 최신 mmetl 릴리즈가 있는지 확인하세요.