데이터 대량 적재

대량 적재 기능을 사용하면 명령줄에서 JSONL 파일의 대량 데이터를 Mattermost로 가져올 수 있습니다. 이 기능은 기존 시스템의 데이터를 마이그레이션하거나 새로 설치한 환경에 데이터를 미리 채워 넣을 때 가장 적합합니다.

가져올 수 있는 데이터 유형은 다음과 같습니다.

• 팀
• 스레드 대화
• 채널(공개 및 비공개)
• 사용자
• 사용자의 팀 멤버십
• 사용자의 채널 멤버십
• 사용자의 알림 환경 설정
• 사용자의 커스텀 상태
• 게시물(답글이 아닌 일반 게시물)
• 게시물의 답글
• 게시물의 반응
• 게시물의 파일 첨부
• 다이렉트 메시지 및 그룹 메시지 채널
• 다이렉트 메시지 및 그룹 메시지 채널의 읽음/읽지 않음 상태
• 다이렉트 메시지와 그룹 메시지
• 사용자가 자기 자신에게 보낸 다이렉트 메시지
• 권한 스킴
• 커스텀 이모지
• 봇 사용자

그 밖의 게시물 유형을 가져오는 기능은 아직 지원되지 않습니다.

대량 적재 명령에 대하여

대량 적재 명령은 중단할 수 있고 멱등적입니다

어떤 이유로든 가져오기가 중단되면 다음에 실행할 때 중단된 지점부터 이어서 진행됩니다. 같은 데이터 파일로 명령을 반복 실행해도 데이터는 한 번만 가져옵니다. 들어오는 게시물과 타임스탬프가 일치하는 게시물은 첨부 파일이 들어오는 데이터로 대체됩니다. v5.20 이전에는 타임스탬프가 일치하는 게시물에 대한 갱신 내용이 기존 게시물에 덧붙여졌습니다.

대량 적재 명령은 운영 중인 시스템에서도 실행할 수 있습니다

명령을 실행하기 위해 Mattermost를 종료할 필요는 없지만, 실행 사이에 시스템 사용자가 변경한 내용은 해당 필드가 데이터 파일에 있으면 덮어써질 수 있습니다.

일부 데이터 필드는 선택 사항입니다

모든 필드가 필수는 아닙니다. 가져오는 객체에 선택적 필드가 없으면 데이터베이스에 있는 해당 필드의 현재 값은 변경되지 않습니다.

대량 적재 명령은 동기화 도구가 아닙니다

대량 적재 명령으로는 Mattermost 데이터베이스에서 객체나 그 필드를 제거할 수 없습니다. 이 명령은 필드를 생성하거나 덮어쓰기만 합니다.

데이터 대량 적재하기

대량 적재 명령을 실행하기 전에, 먼저 Mattermost 디렉터리에 가져올 데이터가 담긴 JSONL 파일을 만들어야 합니다. 파일 이름은 무엇이든 상관없으며, 이 예시에서는 data.jsonl이라고 부릅니다. 파일 형식은 데이터 형식 절에서 설명합니다.

그다음 zip -r data.zip data.jsonl 명령을 실행해 압축합니다.

mmctl 로컬 모드 사용

Mattermost v9.5부터 로컬 모드의 mmctl bulk import process 명령은 가져오기 파일을 서버에 업로드하지 않고 처리하는 것을 지원합니다.

mmctl import process --bypass-upload <file>.zip --local을 실행하면 가져오기가 시작되고 Mattermost 서버가 파일을 직접 읽을 수 있습니다.

mmctl 로컬 모드를 사용하지 않는 경우

mmctl 명령을 로컬 모드로 실행하지 않는다면 다음을 수행하세요.

1. mmctl import upload 명령을 실행해 ZIP 파일을 데이터베이스로 업로드합니다. 예: mmctl import upload data.zip. 업로드가 끝나면 두 개의 ID가 반환되는데, 첫 줄은 업로드 세션 ID이고 둘째 줄은 파일 이름입니다.
2. mmctl import list available 명령을 실행해 파일이 업로드되어 사용할 준비가 되었는지 확인합니다.
3. 파일 이름이 아니라 업로드 세션 ID를 사용해 mmctl import process 명령을 실행해 업로드한 파일을 가져옵니다. 예: mmctl import process <upload_session_id>_data.zip. 여기서 <upload_session_id>는 업로드 명령이 반환한 업로드 세션 ID입니다.

데이터 형식

입력 데이터 파일은 다음 객체들이 각각 한 줄씩 들어 있는 유효한 JSONL 파일이어야 합니다. 객체는 아래 나열된 순서대로 파일에 나타나야 합니다.

Version

필수. Version 객체는 파일의 첫 줄이어야 하며 한 번만 나타나야 합니다. 이 버전은 대량 가져오기 도구의 버전이며 현재는 1입니다.

Scheme

선택. 있는 경우 Scheme 객체는 Version 객체 뒤, Team 객체보다는 앞에 나타나야 합니다.

Emoji

선택. 있는 경우 Emoji 객체는 Version 객체 뒤, Team 객체보다는 앞에 나타나야 합니다.

Team

선택. 있는 경우 Team 객체는 모든 Scheme 객체 뒤, Channel 객체보다는 앞에 나타나야 합니다.

Channel

선택. 있는 경우 Channel 객체는 모든 Team 객체 뒤, User 객체보다는 앞에 나타나야 합니다.

User

선택. 있는 경우 User 객체는 파일에서 Team 및 Channel 객체 뒤, Post 객체보다는 앞에 나타나야 합니다. 각 User 객체는 그 사용자가 속한 팀과 채널을 정의합니다. 해당 팀과 채널이 데이터 파일에 없다면 Mattermost 데이터베이스에 이미 존재해야 합니다.

Post

선택. 있는 경우 Post 객체는 마지막 User 객체 뒤, DirectChannel 객체보다는 앞에 나타나야 합니다. 각 Post 객체는 팀, 채널, 그리고 메시지를 게시한 사용자의 사용자 이름을 정의합니다. 해당 팀, 채널, 사용자가 데이터 파일에 없다면 Mattermost 데이터베이스에 이미 존재해야 합니다.

DirectChannel

선택. 있는 경우 DirectChannel 객체는 파일의 모든 Post 객체 뒤, DirectPost 객체보다는 앞에 나타나야 합니다.

DirectPost

선택. 있는 경우 DirectPost 객체는 파일의 다른 모든 객체 뒤에 나타나야 합니다. 각 DirectPost 객체는 채널 멤버의 사용자 이름과 메시지를 게시한 사용자의 사용자 이름을 정의합니다. 해당 사용자 이름이 데이터 파일에 없다면 Mattermost 데이터베이스에 이미 존재해야 합니다.

Version 객체를 제외한 각 객체에는 해당 객체의 고유 식별자로 사용되는 필드 또는 필드 조합이 있습니다. 대량 적재기는 이 고유 식별자를 사용해 가져오는 객체가 새 객체인지 기존 객체의 갱신인지 판단합니다.

각 객체의 식별자는 다음 표와 같습니다.

다음은 두 개의 팀과 각 팀의 채널 두 개, 다수의 사용자, 다수의 게시물을 가져오는 파일의 일부입니다.

{ "type": "version", ... }
{ "type": "team", "team": { "name": "TeamA", ...} }
{ "type": "team", "team": { "name": "TeamB", ...} }
{ "type": "channel", "channel": { "team": "TeamA", "name": "channel_a1", ...} }
{ "type": "channel", "channel": { "team": "TeamA", "name": "channel_a2", ...} }
{ "type": "channel", "channel": { "team": "TeamB", "name": "channel_b1", ...} }
{ "type": "channel", "channel": { "team": "TeamB", "name": "channel_b2", ...} }
{ "type": "user", "user": { "username": "user001", ...} }
{ "type": "user", "user": { "username": "user002", ...} }
{ "type": "user", "user": { "username": "user003", ...} }
{ "type": "user", ... }
{ "type": "user", ... }
{ "type": "user", ... }
.
.
.
{ "type": "post", { "team": "TeamA", "name": "channel_a1", "user": "user001", ...} }
{ "type": "post", { "team": "TeamA", "name": "channel_a1", "user": "user001", ...} }
{ "type": "post", { "team": "TeamA", "name": "channel_a1", "user": "user001", ...} }
.
.
.

Version 객체

Version 객체는 데이터 파일의 첫 번째 객체여야 하며 한 번만 나타날 수 있습니다. 이 버전은 대량 가져오기 도구의 버전을 나타내며 현재는 1입니다.

Version 객체 예시

이해를 돕기 위해 일반적인 JSON 서식으로 표시했지만, 데이터 파일에서는 여러 줄에 걸쳐 쓸 수 없습니다. 반드시 한 줄이어야 합니다.

{
  "type": "version",
  "version": 1
}

Version 객체의 필드

Scheme 객체

Scheme 객체는 Mattermost 권한 시스템의 권한 스킴(Permissions Schemes)을 나타냅니다. 있는 경우 Scheme 객체는 Version 객체 뒤, Team 객체보다는 앞에 나타나야 합니다.

Scheme 객체 예시

이해를 돕기 위해 일반적인 JSON 서식으로 표시했지만, 데이터 파일에서는 여러 줄에 걸쳐 쓸 수 없습니다. 반드시 한 줄이어야 합니다.

{
  "type": "scheme",
  "scheme": {
    "name": "custom_scheme_name",
    "display_name": "Custom Scheme Name",
    "description": "This is a custom override scheme.",
    "scope": "team",
    "default_team_admin_role": {
      "name": "custom_scheme_team_admin_role",
      "display_name": "Custom Scheme Team Admin Role",
      "description": "This is the default team admin role for the custom scheme.",
      "permissions": ["add_user_to_team", "manage_team_roles"],
    },
    "default_team_user_role": {
      "name": "custom_scheme_team_user_role",
      "display_name": "Custom Scheme Team User Role",
      "description": "This is the default team user role for the custom scheme.",
      "permissions": ["create_public_channel", "create_private_channel"],
    },
    "default_channel_admin_role": {
      "name": "custom_scheme_channel_admin_role",
      "display_name": "Custom Scheme Channel Admin Role",
      "description": "This is the default channel admin role for the custom scheme.",
      "permissions": ["manage_private_channel_members", "manage_channel_roles"],
    },
    "default_channel_user_role": {
      "name": "custom_scheme_channel_user_role",
      "display_name": "Custom Scheme Channel User Role",
      "description": "This is the default channel user role for the custom scheme.",
      "permissions": ["manage_public_channel_members", "manage_public_channel_properties"],
    },
  }
}

Scheme 객체의 필드

Role 객체의 필드

이 객체는 Scheme 객체의 구성 요소입니다.

Emoji 객체

Emoji 객체는 커스텀 이모지를 나타냅니다. 있는 경우 Emoji 객체는 Version 객체 뒤, Team 객체보다는 앞에 나타나야 합니다.

Emoji 객체 예시

이해를 돕기 위해 일반적인 JSON 서식으로 표시했지만, 데이터 파일에서는 여러 줄에 걸쳐 쓸 수 없습니다. 반드시 한 줄이어야 합니다.

{
"type": "emoji",
"emoji": {
  "name": "custom-emoji-troll",
  "image": "bulkdata/emoji/trollolol.png"
  }
}

Emoji 객체의 필드

Team 객체

있는 경우 Team 객체는 Version 객체 뒤, Channel 객체보다는 앞에 나타나야 합니다.

Team 객체 예시

이해를 돕기 위해 일반적인 JSON 서식으로 표시했지만, 데이터 파일에서는 여러 줄에 걸쳐 쓸 수 없습니다. 반드시 한 줄이어야 합니다.

{
"type": "team",
"team": {
  "name": "team-name",
  "display_name": "Team Display Name",
  "type": "O",
  "description": "The Team Description",
  "allow_open_invite": true
  }
}

Team 객체의 필드

Channel 객체

있는 경우 Channel 객체는 모든 Team 객체 뒤, User 객체보다는 앞에 나타나야 합니다.

Channel 객체 예시

이해를 돕기 위해 일반적인 JSON 서식으로 표시했지만, 데이터 파일에서는 여러 줄에 걸쳐 쓸 수 없습니다. 반드시 한 줄이어야 합니다.

{
  "type": "channel",
  "channel": {
    "team": "team-name",
    "name": "channel-name",
    "display_name": "Channel Name",
    "type": "O",
    "header": "The Channel Header",
    "purpose": "The Channel Purpose",
  }
}

Channel 객체의 필드

User 객체

있는 경우 User 객체는 파일에서 Team 및 Channel 객체 뒤, Post 객체보다는 앞에 나타나야 합니다.

User 객체 예시

이해를 돕기 위해 일반적인 JSON 서식으로 표시했지만, 데이터 파일에서는 여러 줄에 걸쳐 쓸 수 없습니다. 반드시 한 줄이어야 합니다.

{
  "type": "user",
  "user": {
    "profile_image": "profile-picture.png",
    "username": "username",
    "email": "email@example.com",
    "auth_service": "",
    "password": "passw0rd",
    "nickname": "bobuser",
    "first_name": "Bob",
    "last_name": "User",
    "position": "Senior Developer",
    "roles": "system_user",
    "locale": "pt_BR",
    "teams": [
      {
        "name": "team-name",
        "theme": "{
            \"awayIndicator\":\"#DBBD4E\",
            \"buttonBg\":\"#23A1FF\",
            \"buttonColor\":\"#FFFFFF\",
            \"centerChannelBg\":\"#ffffff\",
            \"centerChannelColor\":\"#333333\",
            \"codeTheme\":\"github\",
            \"linkColor\":\"#2389d7\",
            \"mentionBg\":\"#2389d7\",
            \"mentionColor\":\"#ffffff\",
            \"mentionHighlightBg\":\"#fff2bb\",
            \"mentionHighlightLink\":\"#2f81b7\",
            \"newMessageSeparator\":\"#FF8800\",
            \"onlineIndicator\":\"#7DBE00\",
            \"sidebarBg\":\"#fafafa\",
            \"sidebarHeaderBg\":\"#3481B9\",
            \"sidebarHeaderTextColor\":\"#ffffff\",
            \"sidebarText\":\"#333333\",
            \"sidebarTextActiveBorder\":\"#378FD2\",
            \"sidebarTextActiveColor\":\"#111111\",
            \"sidebarTextHoverBg\":\"#e6f2fa\",
            \"sidebarUnreadText\":\"#333333\",
            }",
        "roles": "team_user team_admin",
        "channels": [
          {
            "name": "channel-name",
            "roles": "channel_user",
            "notify_props": {
              "desktop": "default",
              "mark_unread": "all"
            }
          }
        ]
      }
    ]
  }
}

User 객체의 필드

UserNotifyProps 객체의 필드

이 객체는 User 객체의 구성 요소입니다.

UserTeamMembership 객체의 필드

이 객체는 User 객체의 구성 요소입니다.

UserChannelMembership 객체의 필드

이 객체는 TeamMembership 객체의 구성 요소입니다.

ChannelNotifyProps 객체의 필드

이 객체는 ChannelMembership 객체의 구성 요소입니다.

Post 객체

있는 경우 Post 객체는 파일의 마지막 User 객체 뒤, DirectChannel 객체보다는 앞에 나타나야 합니다.

Post 객체 예시

이해를 돕기 위해 일반적인 JSON 서식으로 표시했지만, 데이터 파일에서는 여러 줄에 걸쳐 쓸 수 없습니다. 반드시 한 줄이어야 합니다.

{
  "type": "post",
  "post": {
    "team": "team-name",
    "channel": "channel-name",
    "user": "username",
    "message": "The post message",
    "props": {
      "attachments": [{
        "pretext": "This is the attachment pretext.",
        "text": "This is the attachment text."
      }]
    },
    "create_at": 140012340013,
    "flagged_by": [
      "username1",
      "username2",
      "username3"
    ],
    "replies": [{
      "user": "username4",
      "message": "The reply message",
      "create_at": 140012352049,
      "attachments": [{
          "path": "/some/valid/file/path/1"
      }],
    }, {
      "user": "username5",
      "message": "Other reply message",
      "create_at": 140012353057,
    }],
    "reactions": [{
      "user": "username6",
      "emoji_name": "+1",
      "create_at": 140012356032,
    }, {
      "user": "username7",
      "emoji_name": "heart",
      "create_at": 140012359034,
    }],
    "attachments": [{
      "path": "/some/valid/file/path/1"
    }, {
      "path": "/some/valid/file/path/2"
    }]
  }
}

Post 객체의 필드

Reply 객체의 필드

이 객체는 Post/DirectPost 객체의 구성 요소입니다.

Reaction 객체의 필드

이 객체는 Post/DirectPost 객체의 구성 요소입니다.

Attachment 객체의 필드

이 객체는 Post/DirectPost 객체의 구성 요소입니다.

DirectChannel 객체

다이렉트 채널에는 2명에서 8명까지의 사용자가 채널 멤버로 참여할 수 있습니다. 멤버가 2명뿐이면 Mattermost는 이를 다이렉트 메시지 채널로 취급합니다. 멤버가 3명 이상이면 그룹 메시지 채널로 취급합니다.

DirectChannel 객체 예시

이해를 돕기 위해 일반적인 JSON 서식으로 표시했지만, 데이터 파일에서는 여러 줄에 걸쳐 쓸 수 없습니다. 반드시 한 줄이어야 합니다.

{
  "type": "direct_channel",
  "direct_channel": {
    "members": [
      "username1",
      "username2",
      "username3"
    ],
    "header": "The Channel Header",
    "favorited_by": [
      "username1",
      "username2",
      "username3"
    ]
  }
}

DirectChannel 객체의 필드

DirectPost 객체

DirectPost 객체는 파일의 다른 모든 객체 뒤에 나타나야 합니다.

DirectPost 객체 예시

이해를 돕기 위해 일반적인 JSON 서식으로 표시했지만, 데이터 파일에서는 여러 줄에 걸쳐 쓸 수 없습니다. 반드시 한 줄이어야 합니다.

{
  "type": "direct_post",
  "direct_post": {
    "channel_members": [
      "username1",
      "username2",
      "username3",
    ],
    "user": "username2",
    "message": "Hello Group Channel",
    "create_at": 140012340013,
    "flagged_by": [
      "username1",
      "username2",
      "username3"
    ],
    "replies": [{
      "user": "username4",
      "message": "The reply message",
      "create_at": 140012352049,
    }, {
      "user": "username5",
      "message": "Other reply message",
      "create_at": 140012353057,
    }],
    "reactions": [{
      "user": "username6",
      "emoji_name": "+1",
      "create_at": 140012356032,
    }, {
      "user": "username7",
      "emoji_name": "heart",
      "create_at": 140012359034,
    }]
  }
}

DirectPost 객체의 필드

자주 발생하는 문제

대량 가져오기 명령은 mattermost 사용자로 실행하세요. root나 다른 사용자로 실행하면 가져온 첨부 파일의 파일 권한에 문제가 생깁니다.

파일 첨부가 활성화되어 있는지, 들어오는 첨부 파일을 감당할 만큼 파일 스토리지 시스템에 여유 공간이 있는지, 그리고 최대 파일 크기가 적절한지 확인하세요.

Mattermost 서버에 로그를 저장할 여유 공간이 충분한지, 그리고 데이터베이스 서버에 데이터베이스 자체와 트랜잭션 로그를 위한 여유 공간이 충분한지 확인하세요.

첨부 파일 업로드를 방해할 수 있는 안티바이러스나 기타 플러그인을 비활성화하세요. 잘못 구성되어 있으면 첨부 파일 업로드를 차단해 가져오기가 실패할 수 있습니다. 안티바이러스 검사가 필요하다면 가져오기 전에 첨부 파일 폴더를 검사하세요.

문제 해결

대량 적재 도구를 실행하면 멈추고 완료되지 않음

Bleve 검색 인덱싱이 활성화되어 있다면 System Console > Experimental > Bleve에서 일시적으로 비활성화한 뒤 명령을 다시 실행하세요.

Bleve는 여러 프로세스가 동일한 인덱스를 열고 조작하는 것을 지원하지 않습니다. 따라서 Mattermost 서버가 실행 중일 때 대량 적재 도구를 실행하면 인덱스를 열려고 시도하는 과정에서 잠깁니다.