백업 및 업그레이드

무엇을 백업해야 하는지, 새 호스트에 어떻게 복원하는지, 어떻게 업그레이드하는지, 그리고 Mattermost 서버나 단일 커뮤니티를 Antimatter로 어떻게 이전하는지 안내합니다.

백업 대상

AI 암호화 키가 없으면 복원된 서버는 모델 연결의 API 키를 읽을 수 없고, 각각 다시 입력해야 합니다. 키의 사본을 데이터베이스 백업과 별도로 보관하여, 한 개의 백업이 탈취되어도 두 가지가 모두 노출되지 않도록 하세요. 암호화 키를 참조하세요.

데이터베이스와 파일은 함께 묶여 있습니다: 동시에 백업하고, 서버 외부에 사본을 보관하세요. 볼륨 이름은 compose 프로젝트 이름인 antimatter로 시작합니다 (docker volume ls로 목록을 볼 수 있습니다).

백업

compose.yaml가 있는 디렉터리에서 실행하세요. Antimatter를 먼저 중지하면 완전히 일관된 사본을 얻을 수 있습니다. 실행 중에 백업하는 것도 일반적으로 문제없지만, 백업 중에 업로드된 파일이 백업에 포함되지 않을 수 있습니다.

stamp=$(date +%Y%m%d-%H%M%S)
mkdir -p backups
docker compose stop antimatter
# Database
docker compose exec -T postgres pg_dump -U antimatter -d antimatter -Fc \
    > "backups/antimatter-db-$stamp.dump"
# File storage, GIF service and the data directory (the AI key file)
for v in files gifs data; do
    docker run --rm -v "antimatter_$v:/data:ro" -v "$PWD/backups:/backup" \
        alpine tar -czf "/backup/antimatter-$v-$stamp.tar.gz" -C /data .
done
docker compose start antimatter
# Secrets
cp .env "backups/env-$stamp"

AM_AI_ENCRYPTION_KEY를 설정하지 않았다면, 서버의 키 파일은 위의 루프가 파일과 함께 저장하는 data 볼륨에 있습니다. 더 좋은 방법은 암호화 키에 설명된 대로 그 내용을 .env에 넣고, 사본을 데이터베이스 백업과 별도로 보관하는 것입니다.

cron을 통해 매일 백업하도록 설정하고, backups/ 디렉터리를 다른 기계로 복사하세요. .env의 사본은 서버만큼 안전하게 보관하세요: 비밀번호가 포함되어 있기 때문입니다.

업로드된 파일을 개별로 복사하려면(예: 다른 S3 저장소로), bucket 서비스의 AWS 명령줄 도구를 사용하세요:

docker compose run --rm -v "$PWD/backups/files:/backup" bucket \
    "aws --endpoint-url http://files:9000 s3 sync s3://antimatter /backup"

릴리스 아카이브를 사용하는 경우, pg_dump -Fc로 데이터베이스를 백업하고, data/와 config/ 디렉터리는 기존에 사용하던 도구로 백업하세요(data/에는 AI 키 파일이 있습니다). 패키지를 사용하는 경우, 데이터베이스는 동일한 방식으로 백업하고, /etc/antimatter, /var/lib/antimatter, /etc/gifs-server, /var/lib/gifs-server를 백업하세요.

새 호스트에 복원

compose.yaml, 저장된 .env 및 백업 파일을 새 디렉터리에 배치한 다음:

stamp=20261016-030000          # the backup to restore
docker compose create           # creates the volumes, starts nothing
docker compose up -d postgres
docker compose exec -T postgres pg_restore -U antimatter -d antimatter --no-owner \
    < "backups/antimatter-db-$stamp.dump"
for v in files gifs data; do
    docker run --rm -v "antimatter_$v:/data" -v "$PWD/backups:/backup" \
        alpine tar -xzf "/backup/antimatter-$v-$stamp.tar.gz" -C /data
done
docker compose up -d

동일한 .env를 사용하세요: 저장소와 데이터베이스는 이전의 비밀번호를 유지해야 하고, 모델 연결에는 동일한 AI 암호화 키가 필요합니다. 새 호스트의 주소가 다르면 SITE_URL(그리고 DOMAIN)을 업데이트하세요.

가끔 다른 기계에 백업을 복원하여 백업이 정상 작동하는지 테스트하세요.

업그레이드

1. 백업을 수행하세요.
2. 고정(pinned)하는 경우, 권장 사항에 따라 .env의 이미지 태그(ANTIMATTER_IMAGE)를 변경하세요.
3. 이미지를 가져오고 다시 시작하세요:

   docker compose pull
   docker compose up -d
   docker compose logs -f antimatter

서버가 시작되면 데이터베이스 스키마가 업그레이드되고(로그에서 진행 상황을 확인할 수 있으며, 규모가 큰 서버의 경우 몇 분 정도 소요될 수 있음) 이미지에서 번들된 앱의 최신 버전이 설치됩니다. 릴리스 아카이브를 사용하는 경우: 서버를 중지하고, config/, data/, logs/, plugins/, client/plugins/를 제외한 모든 내용을 새 아카이브의 내용으로 교체한 후 다시 시작합니다. .deb 또는 .rpm 패키지를 사용하는 경우, 패키지 업그레이드에 설명된 대로 새 패키지를 설치합니다.

버전

Antimatter 서버는 기반이 되는 Mattermost 라인(현재 12.0.0)의 버전을 보고합니다. 아카이브와 패키지를 포함하는 GitHub의 릴리스는 자체 버전 번호를 가지며, 베타 기간 동안에는 0.9.0 시리즈입니다. antimatter version 명령은 이를 빌드 번호로 표시합니다. 이미지는 main 브랜치에서 다시 빌드됩니다: antimatter-next는 매일 밤(태그 nightly-<YYYYMMDD>), 두 이미지 모두 각 변경 사항마다(태그 sha-<commit>) 빌드됩니다. 이러한 태그 중 하나를 고정하고, 의도적으로 업그레이드하며, 이전 태그를 기록해 두어 해당 백업이 어느 버전에 해당하는지 파악할 수 있도록 합니다.

PostgreSQL 주요 버전

컴포즈 파일은 postgres:17-alpine를 사용합니다. Antimatter에는 PostgreSQL 15 이상이 필요합니다. PostgreSQL의 새 주요 버전은 이전 버전의 데이터 디렉터리를 읽을 수 없습니다. 새 버전으로 이동하려면 데이터베이스를 덤프하고, 새 볼륨에서 새 버전을 시작한 후 덤프를 복원해야 합니다.

0.9.0으로 업그레이드

0.9.0 버전(또는 2026년 10월 17일 이후에 빌드된 이미지)의 첫 시작 시 데이터에 몇 가지 일회성 변경 사항이 적용됩니다. 각 변경 사항은 한 번만 실행되며 데이터베이스에 기록됩니다. 이러한 변경 사항은 이전 기본값으로 남아 있던 설정을 새 기본값으로 가져오고, 관리자가 명시적으로 선택한 설정은 그대로 유지합니다. 로그에서 진행 상황을 추적할 수 있습니다.

Agents 앱의 서비스

업그레이드는 에이전트 앱의 각 AI 서비스를 서버 전체의 모델 연결로 복사하며, 이 연결은 모든 커뮤니티와 공유되고 게스트를 제외한 모든 사용자가 사용할 수 있습니다(게스트도 사용할 수 있도록 하려면 게스트도를 켜세요). 키는 전송 중 암호화되므로 서버에 AI 암호화 키가 필요합니다. 파일이 S3에 있는 클러스터의 경우 AM_AI_ENCRYPTION_KEY를 먼저 설정해야 하며, 그렇지 않으면 복사가 다음 시작 시까지 대기합니다. 그런 다음 시스템 콘솔 › AI › 모델 연결을 확인하세요:

• 각 연결은 해당 서비스의 ID를 유지하므로, 앱의 에이전트와 에이전트 서비스로 설정된 자동 번역도 여전히 해당 서비스를 찾을 수 있습니다.
• OpenAI, OpenAI 호환, Anthropic, Mistral, Cohere 및 Gemini 서비스는 해당 OpenAI 호환(또는 Anthropic) 엔드포인트로의 연결이 됩니다. Azure 서비스는 리소스의 OpenAI 호환 엔드포인트로의 연결이 됩니다: 테스트해 보세요.
• AWS Bedrock, Google Vertex AI 및 Cohere North 서비스, 그리고 알 수 없는 유형은 조치가 필요함으로 표시되며, 그 이유가 함께 표시됩니다. 클라우드 자격 증명은 복사되지 않습니다: 제공자의 OpenAI 호환 엔드포인트나 LiteLLM과 같은 게이트웨이를 지정하고 저장하세요.
• 임베딩 서비스는 동일한 주소와 키를 가진 연결의 임베딩 모델이 되거나, 자체 연결이 됩니다. 녹취록 서비스에는 whisper-1 모델이 설정됩니다.
• 리라이팅과 요약에 아직 연결이 없으면, 앱의 기본 에이전트의 서비스와 모델이 사용됩니다.

에이전트 앱 자체의 설정과 데이터는 그대로 유지됩니다: 해당 에이전트는 여전히 앱의 서비스를 사용합니다.

기본값의 기타 변경 사항

• 통화: 테스트 모드는 기본적으로 꺼져 있고 비디오 사용은 켜져 있습니다. 설정에 저장된 선택 사항은 유지됩니다. 통화는 커뮤니티의 유형을 따릅니다(자세한 내용은 통화와 음성 참조).
• 메시지를 상단에 고정하는 기능은 채널 관리자, 커뮤니티 관리자 및 모더레이터(메시지 관리 권한 보유)에게만 제공됩니다. 다이렉트 메시지 또는 그룹 메시지의 멤버는 여전히 이 기능을 사용할 수 있습니다.
• 아카이브된 채널에는 새 멤버가 참여할 수 있으며, 이들은 과거 기록을 읽을 수 있습니다. 하지만 아무도 게시, 반응 또는 변경 작업을 수행할 수 없습니다.

Mattermost에서 이동

Antimatter는 Mattermost의 데이터베이스 스키마를 사용하면서 자체 테이블을 추가하므로, Mattermost 서버의 PostgreSQL 데이터베이스와 파일을 인수할 수 있습니다. 먼저 복사본에서 시도해 보세요:

1. Mattermost 데이터베이스, 파일 저장소(data/ 또는 S3 버킷) 및 config.json를 백업한 후 Mattermost를 중지합니다.
2. 데이터베이스를 Antimatter의 PostgreSQL로 복원하거나, Antimatter를 해당 데이터베이스의 복사본을 가리키도록 설정합니다(AM_SQLSETTINGS_DATASOURCE).
3. 파일을 Antimatter의 저장소로 복사하되, 경로를 유지합니다: S3 도구를 사용하여 antimatter 버킷으로, 또는 릴리스 아카이브를 사용하여 data/로 복사합니다.
4. 설정을 재사용합니다: config.json를 복사하거나, amctl --local config migrate를 사용하여 데이터베이스로 이동합니다(자세한 내용은 설정 참고). MM_ 환경 변수는 계속 작동하며, 편리할 때 AM_으로 이름을 변경할 수 있습니다.
5. Antimatter를 시작하고 데이터베이스가 업그레이드되는 동안 로그를 추적하세요. 그런 다음 시스템 콘솔 › 플러그인 › 플러그인 관리를 확인하세요. Antimatter는 설치된 버전보다 새로운 경우 Calls, Playbooks, Kanban(Boards), Agents 및 통합의 자체 빌드를 설치합니다. Mattermost에 해당 앱의 더 새로운 버전이 있었다면, 해당 앱을 제거하고 Antimatter를 다시 시작하여 자체 빌드가 설치되도록 하세요.
6. 자체 푸시 프록시를 사용하여 푸시 알림을 다시 설정하세요. Antimatter는 Mattermost의 푸시 서비스(테스트 또는 호스팅)에 알림을 보내지 않으며, 해당 서비스는 Mattermost의 자체 앱에만 전달됩니다. 푸시 알림 서버를 변경하기 전까지 서버는 푸시 알림을 보내지 않습니다(자세한 내용은 푸시 알림 참고).

Antimatter는 Mattermost, Inc.가 운영하는 어떤 서비스에도 연결하지 않습니다(자세한 내용은 Connections to outside services 참고). 설정에 해당 서비스가 명시되어 있더라도 마찬가지입니다:

• Mattermost의 푸시 알림 서버는 설정에 남아있지만 사용되지 않습니다;
• 앱 마켓플레이스(마켓플레이스 URL) 및 제품 공지사항의 Mattermost 주소가 비워집니다.
• Mattermost 기본값이었던 앱 다운로드 링크(Antimatter Apps Download Page Link, 안드로이드 앱 다운로드 링크, iOS 앱 다운로드 링크)가 GitHub의 Antimatter 앱 다운로드 페이지로 대체되며, 직접 설정한 링크는 유지됩니다.
• Calls 앱은 Mattermost의 서버 대신 Cloudflare의 공개 STUN 서버를 사용하며, 저장된 설정은 변경되지 않습니다(자세한 내용은 Calls 참고);
• 보안 업데이트 확인 및 크래시 보고 기능이 제거되며, 관련 시스템 콘솔 설정(보안 알림 사용, 진단 및 오류 보고 사용)과 공지사항 페이지도 함께 제거됩니다.

로컬 모드 소켓은 이제 /var/tmp/antimatter_local.socket입니다. amctl은 이전의 /var/tmp/mattermost_local.socket도 시도합니다. Mattermost의 최신 버전은 PostgreSQL만 지원하며, Antimatter도 마찬가지입니다: MySQL 데이터베이스를 먼저 PostgreSQL로 이관해야 합니다. Antimatter가 데이터베이스를 업그레이드한 후 Mattermost로 돌아가려면 Mattermost 백업을 복원해야 합니다.

데이터 내보내기 및 가져오기

벌크 내보내기 형식은 서버 간 데이터를 이동합니다. 원할 경우 첨부 파일, 프로필 사진 및 사용자 정의 이모지를 포함하여 서버 전체, 일부 커뮤니티 또는 일부 채널의 데이터를 내보낼 수 있습니다.

# on the source server
amctl export create --team-name design --include-profile-pictures
amctl export list
amctl export download <export file> design.zip
# on the destination server
amctl import upload design.zip
amctl import list available
amctl import process <uploaded file> --imported-users active

amctl export job list와 amctl import job list를 사용하여 작업을 확인하세요. 커뮤니티 또는 채널 내보내기의 경우 --imported-users가 필수입니다. 사람들이 이 서버로 이동하는 경우 active, 이미 계정이 있는 서버로 가져오는 경우 inactive를 사용하세요. 이렇게 하면 불확실한 일치 항목에서 생성된 계정은 관리자가 확인하기 전까지 비활성 상태로 유지됩니다. --destination-team-name를 사용하면 기존 커뮤니티로 가져올 수 있습니다. 내보내기 및 가져오기는 기본적으로 서버 저장소(ExportSettings.Directory, ImportSettings.Directory)에 30일간 보관됩니다.

서버 자체에서는 antimatter export bulk와 antimatter import bulk --apply를 사용하여 API 없이 파일에서 동일한 작업을 수행할 수 있습니다.