Mattermost는 사용자 업로드(첨부 파일, 프로필 이미지, 플러그인 자산, 이모지, 컴플라이언스 내보내기)를 Azure Storage 계정에 저장할 수 있습니다. 이 가이드는 관리자가 Azure 측을 프로비저닝하고 System Console을 통해 Mattermost 서버가 이를 가리키도록 설정하는 단계를 안내합니다.

사전 요구 사항#

• 스토리지 계정과 컨테이너가 이미 생성된 Azure 구독.
• Azure 포털, 또는 Azure CLI (az)가 설치되어 있고 az login으로 로그인되어 있어야 합니다. 두 가지 방법 모두 아래에 설명되어 있습니다.
• System Admin 계정으로 System Console에 접근할 수 있는 Mattermost 배포(v11.9 이상).

다른 백엔드에서 기존 파일을 마이그레이션할 계획이라면, 구성을 변경하기 전에 현재 스토리지 위치(S3 버킷, 로컬 디스크 등)를 백업하세요. 파일 드라이버를 전환해도 기존 파일이 자동으로 마이그레이션되지 않습니다.

1단계: 인증 모드 선택#

Mattermost는 서버가 Azure에 인증하는 두 가지 방법을 지원합니다. 서버가 실행되는 방식에 맞는 방법을 선택하세요:

• Shared key: 서버가 각 요청에 Storage Account access key 로 서명합니다. 호스트가 Azure ID를 가질 필요가 없으므로 Mattermost가 실행되는 어디에서나(온프레미스, Azure가 아닌 클라우드, 로컬 개발 환경) 작동합니다. 단점은 키가 config.json에 저장되는 장기 보관 시크릿이라는 점입니다.
• Default credential (Microsoft Entra ID): 서버가 Microsoft Entra ID에서 토큰을 가져와 요청에 서명합니다. Mattermost 구성에는 장기 보관 시크릿이 없습니다. 호스트 환경이 이미 ID를 제공하는(Azure VM/App Service/AKS의 관리 ID, 페더레이션 워크로드용 워크로드 ID, 또는 서비스 주체) Azure에서 실행되는 배포에 권장되는 모드입니다.

Azure 측 설정은 두 모드 간에 약간 다릅니다. 선택한 방식에 맞는 하위 섹션을 따르세요. 나중에 System Console의 Azure authentication 설정을 변경하여 모드를 전환할 수 있습니다.

옵션 A: Shared key#

Storage Account access key를 가져옵니다.

Azure 포털

1. 스토리지 계정을 열고 Security + networking > Access keys로 이동합니다.
2. key1(또는 key2) 옆의 Show를 선택하고 값을 복사합니다.

Azure CLI

az storage account keys list \
    --account-name acmemattermost \
    --resource-group mm-prod-files \
    --query "[0].value" -o tsv

옵션 B: Default credential (Microsoft Entra ID)#

서버는 Azure SDK의 DefaultAzureCredential을 사용하며, 이는 런타임에 다음 순서로 작동 가능한 ID를 검색합니다. 토큰을 반환하는 첫 번째 소스가 사용됩니다.

#. EnvironmentCredential -- 서비스 주체 환경 변수.

#. WorkloadIdentityCredential -- 페더레이션 워크로드 ID.

#. ManagedIdentityCredential -- 플랫폼이 제공하는 관리 ID.

#. AzureCLICredential -- 로그인된 az 세션으로, 로컬 개발에 유용합니다.

SDK가 어떤 ID를 선택하든, 해당 ID는 스토리지 계정 또는 컨테이너에 대해 Storage Blob Data Contributor(또는 동등한 읽기/쓰기/목록/삭제 데이터 플레인 작업을 갖는 커스텀 역할)가 필요합니다. 이 권한이 없으면 TestConnection이 AuthorizationPermissionMismatch를 반환합니다.

호스트에 맞는 ID 소스를 선택하세요:

사용할 계정을 준비하려면, 아래와 같이 Azure 포털 또는 Azure CLI를 사용하여 역할을 할당해야 합니다(Mattermost가 인증할 ID의 주체로 대체하세요):

STORAGE_ACCOUNT_ID=$(az storage account show \
    --name acmemattermost \
    --resource-group mm-prod-files \
    --query id -o tsv)

# 관리 ID의 경우 (VM/App Service/AKS 파드에서 시스템 할당):
az role assignment create \
    --assignee-object-id "<principalId-of-the-managed-identity>" \
    --assignee-principal-type ServicePrincipal \
    --role "Storage Blob Data Contributor" \
    --scope "$STORAGE_ACCOUNT_ID"

# 서비스 주체의 경우:
az role assignment create \
    --assignee "<appId-of-the-service-principal>" \
    --role "Storage Blob Data Contributor" \
    --scope "$STORAGE_ACCOUNT_ID"

2단계: Mattermost 구성#

System Admin으로 로그인하여 System Console > Environment > File Storage를 엽니다.

1. File storage system: Azure Blob Storage를 선택합니다. Azure 전용 필드가 나타나고 S3/로컬 필드는 숨겨집니다.
2. Azure cloud: 스토리지 계정을 호스팅하는 Azure 클라우드를 선택합니다:
• Azure Commercial (기본값): 전역 Azure 클라우드({account}.blob.core.windows.net)입니다. 스토리지 계정 이름만 필요합니다.
• Azure Government: 미국 정부용 클라우드({account}.blob.core.usgovcloudapi.net)입니다. 스토리지 계정 이름만 필요합니다.
• Custom Endpoint: 그 밖의 Azure 클라우드(예: Azure China), Azurite 에뮬레이터, 또는 리버스 프록시입니다. 아래 Azure endpoint를 통해 전체 Blob 서비스 URL을 제공하세요.
3. Azure Storage account: 스토리지 계정 이름(예: acmemattermost).
4. Azure container: 컨테이너 이름(예: mattermost).
5. Azure path prefix: 선택 사항입니다. Mattermost가 컨테이너 내부의 하위 경로(예: prod/)에 쓰도록 하려면 설정하세요. 컨테이너 루트를 사용하려면 비워 두세요.
6. Azure authentication: 1단계에서 설정한 모드를 선택합니다:
• Shared key (기본값): Mattermost가 Storage Account access key로 각 요청에 서명합니다. 옵션 A: Shared key 를 완료했다면 이 옵션을 선택하세요.
• Default credential (Microsoft Entra ID): Mattermost가 호스트 환경이 제공하는 ID로 인증합니다. 옵션 B: Default credential (Microsoft Entra ID) 를 완료했다면 이 옵션을 선택하세요. 이 모드에서는 액세스 키를 사용하지 않으므로 아래의 Azure Storage account key 필드는 숨겨집니다.
7. Azure Storage account key (Azure authentication이 Shared key일 때만 표시): 옵션 A: Shared key 에서 얻은 공유 키를 붙여넣습니다.
8. Azure endpoint (Azure cloud가 Custom Endpoint로 설정된 경우에만 표시): 스킴을 포함한 전체 Blob 서비스 URL입니다. Mattermost는 이 URL을 변경 없이 Azure SDK로 전달하므로, 스토리지 계정 이름이 이미 호스트 이름에 포함되어 있거나(vhost 방식, 예: https://acmemattermost.blob.core.chinacloudapi.cn/) 경로에 포함되어 있어야 합니다(경로 방식, 예: Azurite의 경우 http://localhost:10000/devstoreaccount1/). 선택한 인증 모드는 이 URL이 가리키는 호스트에 대해 서명하므로, 해당 호스트는 위에서 지정한 스토리지 계정을 제공해야 합니다.
9. Enable secure Azure Blob Storage connections (Azure cloud가 Azure Commercial 또는 Azure Government일 때만 표시): 기본값(활성화됨)을 유지하세요. Custom Endpoint 클라우드에서는 Azure endpoint URL에서 스킴이 결정되므로 이 모드에서는 이 토글이 숨겨집니다.
10. Azure request timeout (milliseconds): 기본값은 30000(30초)입니다. 네트워크에서 대용량 객체에 더 많은 시간이 필요한 경우에만 늘리세요.

설정을 저장하고 Test Connection을 클릭합니다. Mattermost는 폼에 제출된 자격 증명을 사용하여 구성된 컨테이너에 대해 무작동(no-op) 쓰기/읽기/삭제를 실행합니다. 녹색 Connection was successful 메시지는 자격 증명, 컨테이너 이름, 엔드포인트가 모두 올바르게 작동함을 확인해 줍니다. 빨간색 오류 메시지에는 근본 원인이 포함되며, 일반적인 원인은 문제 해결 에 나열되어 있습니다.

3단계: 확인#

1. 재시작 후 System Console 또는 아무 채널이나 다시 로드합니다.
2. 아무 채널에나 첨부 파일을 업로드합니다. Mattermost는 이미지에 대해 세 개의 블롭(원본, 미리보기, 썸네일)을 저장하므로 일반 파일보다 업로드 경로를 더 철저히 검증할 수 있어 작은 이미지가 좋은 테스트입니다.
3. 게시물에 첨부 파일과 미리보기가 평소처럼 렌더링되어야 합니다.
4. Azure 포털에서 컨테이너를 열어 <YYYYMMDD>/teams/<team>/channels/<channel>/users/<user>/<file_id>/ 경로 아래에 새 블롭이 나타났는지 확인합니다(로컬 디스크 및 S3 백엔드와 동일한 레이아웃입니다). 이미지의 경우 <name>.<ext>, <name>_preview.<ext>, <name>_thumb.<ext>가 표시됩니다.

Amazon S3에서 기존 파일 마이그레이션#

기존 배포를 S3에서 Azure Blob Storage로 전환하는 경우, 파일 콘텐츠가 Mattermost가 원래 쓰려던 것과 동일한 키로 Azure 컨테이너에 존재해야 합니다. Mattermost 자체는 백엔드 간에 파일을 이동하지 않으므로, 이는 드라이버를 전환하기 전에 한 번 실행하는 대역외(out-of-band) 복사 작업입니다.

Mattermost는 모든 백엔드에서 동일한 상대 경로에 블롭을 씁니다:

{path-prefix}/{YYYYMMDD}/teams/{teamID}/channels/{channelID}/users/{userID}/{fileID}/{filename}

즉, S3 버킷에서 Azure 컨테이너로 키 대 키로 직접 복사하는 것으로 충분합니다. S3 측에서 AmazonS3PathPrefix를 사용한다면, Azure 측에서도 AzurePathPrefix를 동일한 값으로 설정하세요(또는 복사하는 동안 접두사를 다시 작성하세요).

이를 수행하는 방법은 여러 가지입니다. 권장되는 방법은 Amazon S3에서 Azure Blob Storage로의 클라우드 간 마이그레이션을 제공하는 Azure Storage Mover 서비스 를 사용하는 것입니다.

rclone 및 AzCopy 와 같이 도움이 될 수 있는 다른 도구도 있습니다.

(선택 사항) 내보내기 백엔드 구성#

컴플라이언스 및 데이터 내보내기는 일반 파일 업로드와 별도로 저장할 수 있습니다. System Console에서 File Storage 바로 아래에 있는 File Storage (Exports) 섹션은 위와 동일한 필드를 미러링하며 동일한 Azure 자격 증명을 사용합니다. 고객은 일반적으로 내보내기를 다른 컨테이너(또는 다른 계정)로 지정하여 내보내기 보존 정책을 일반 업로드와 다르게 설정합니다. 내보내기 대상은 자체 드라이버와 자격 증명을 가진 독립적인 백엔드이므로 일반 업로드와 동일한 공급자를 사용할 필요가 없습니다. 예를 들어 업로드는 Amazon S3에 유지하고 내보내기는 Azure Blob Storage로 보내거나, 그 반대로 할 수도 있습니다.

ExportAzure* 키의 전체 목록은 전용 내보내기 파일 스토어 대상 활성화 를 참조하세요.

문제 해결#

참고 자료#

각 Azure 설정은 환경 구성 설정 에 자세히 문서화되어 있습니다:

• File storage system (FileSettings.DriverName)
• Azure Storage account (FileSettings.AzureStorageAccount)
• Azure container (FileSettings.AzureContainer)
• Azure path prefix (FileSettings.AzurePathPrefix)
• Azure authentication (FileSettings.AzureAuthMode)
• Azure Storage account key (FileSettings.AzureAccessKey)
• Azure cloud (FileSettings.AzureCloud)
• Azure endpoint (FileSettings.AzureEndpoint)
• Enable secure Azure Blob Storage connections (FileSettings.AzureSSL)
• Azure request timeout (FileSettings.AzureRequestTimeoutMilliseconds)