Rocket.Chat에서 마이그레이션

개요

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. 검증, 테스트, 그리고 서비스 전환.

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 데이터 크기의 몇 배를 계획하세요.
• 파일 스토리지: 대용량 데이터셋에서는 로컬이나 NFS 스토리지보다 AWS S3(또는 S3 호환 스토리지)로 가져오는 편이 대체로 더 빠릅니다.

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: 느리거나 실패하는 실행을 진단할 수 있도록 DEBUG 수준의 상세 내용을 transform-rocketchat.log에 기록합니다.

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 플래그가 필요합니다.

mmctl import job show <JOB ID> --json

대용량 가져오기(파일 저장소 방식)

수 GB에 이르는 대용량 아카이브는 mmctl을 통해 업로드하면 느리고 오류가 발생하기 쉽습니다. 대신 아카이브를 서버의 가져오기 디렉터리에 직접 두고 서버가 그 자리에서 처리하도록 하세요.

1. mattermost-bulk-import.zip을 고유한 이름으로 Mattermost 파일 저장소의 data/import에 복사합니다. 로컬 데이터 디렉터리 또는 S3 버킷의 import 접두사 경로입니다.
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 릴리스가 있는지 확인하세요.