사용 가능 플랜: Enterprise, Enterprise Advanced

이 가이드는 통화 녹음 및 전사 기능에 사용되는 Mattermost calls-offloader 서비스를 설정, 구성, 검증하는 방법을 자세히 설명합니다.

• 개요
• 사전 요구 사항
• 설치 및 배포
• 구성
• 검증 및 테스트
• Mattermost와 연동
• 문제 해결
• 에어 갭 배포

개요#

calls-offloader 서비스는 Mattermost Calls에서 리소스를 많이 사용하는 작업을 처리하는 전용 마이크로서비스이며, 다음 기능을 담당합니다.

• 통화 녹음: 통화의 오디오와 화면 공유 콘텐츠를 캡처합니다.
• 통화 전사: 녹음된 통화를 자동으로 전사합니다.
• 실시간 자막(실험적 기능): 진행 중인 통화에서 실시간으로 전사합니다.

이러한 작업을 전용 서비스로 분리하면 메인 Mattermost 서버와 RTCD 서비스가 핵심 기능에 집중하면서 최적의 성능을 유지할 수 있습니다.

사전 요구 사항#

calls-offloader를 배포하기 전에 다음 사항을 갖추었는지 확인하세요.

• Mattermost Enterprise 라이선스
• 올바르게 구성된 Mattermost Calls 배포(통합 방식 또는 RTCD 사용 방식)
• Docker가 설치되어 실행 중인 적절한 사양의 서버
• 녹음 파일을 저장할 충분한 스토리지 공간(스토리지 요구 사항 참고)

시스템 요구 사항#

자세한 시스템 요구 사항과 성능 권장 사항은 calls-offloader 성능 문서를 참고하세요.

스토리지 요구 사항#

통화 녹음은 상당한 스토리지 공간을 차지할 수 있습니다. 화면 공유를 켠 상태(오디오 트랙 하나 포함)의 평균 녹음 크기를 기준으로, 선택한 품질에 따른 스토리지 사용량은 대략 다음과 같습니다.

• 낮음: 약 0.5GB/시간(또는 약 8MB/분)
• 중간: 약 0.7GB/시간(또는 약 12MB/분)
• 높음: 약 1.2GB/시간(또는 약 20MB/분)

참고: 오디오만 녹음하면 참가자당 분당 약 1MB를 사용합니다.

설치 및 배포#

베어메탈 또는 VM 배포#

1. calls-offloader GitHub 리포지터리에서 최신 릴리즈를 다운로드합니다.

2. 필요한 디렉터리를 만듭니다.

   sudo mkdir -p /opt/calls-offloader/data/db
   sudo useradd --system --home /opt/calls-offloader calls-offloader
   sudo chown -R calls-offloader:calls-offloader /opt/calls-offloader
   

3. 구성 파일(/opt/calls-offloader/config.toml)을 만듭니다.

   [api]
   http.listen_address = ":4545"
   http.tls.enable = false
   http.tls.cert_file = ""
   http.tls.cert_key = ""
   security.allow_self_registration = true
   security.enable_admin = false
   security.admin_secret_key = ""
   security.session_cache.expiration_minutes = 1440
   
   [store]
   data_source = "/opt/calls-offloader/data/db"
   
   [jobs]
   api_type = "docker"
   max_concurrent_jobs = 100
   failed_jobs_retention_time = "30d"
   image_registry = "mattermost"
   
   [logger]
   enable_console = true
   console_json = false
   console_level = "INFO"
   enable_file = true
   file_json = true
   file_level = "DEBUG"
   file_location = "/opt/calls-offloader/calls-offloader.log"
   enable_color = true
   

4. systemd 서비스 파일(/etc/systemd/system/calls-offloader.service)을 만듭니다.

   [Unit]
   Description=Mattermost Calls Offloader Service
   After=network.target docker.service
   Requires=docker.service
   
   [Service]
   Type=simple
   User=calls-offloader
   WorkingDirectory=/opt/calls-offloader
   ExecStart=/opt/calls-offloader/calls-offloader --config /opt/calls-offloader/config.toml
   Restart=always
   RestartSec=10
   LimitNOFILE=65536
   
   [Install]
   WantedBy=multi-user.target
   

5. 서비스를 활성화하고 시작합니다.

   sudo systemctl daemon-reload
   sudo systemctl enable calls-offloader
   sudo systemctl start calls-offloader
   

6. 서비스 상태를 확인합니다.

   sudo systemctl status calls-offloader
   

7. 서비스가 응답하는지 확인합니다.

   curl http://localhost:4545/version
   # Example output:
   # {"buildDate":"2025-03-10 19:13","buildVersion":"v0.9.2","buildHash":"a4bd418","goVersion":"go1.23.6"}
   

구성#

API 구성#

API 섹션은 서비스가 요청을 수락하는 방식을 제어합니다.

• http.listen_address: 서비스가 수신 대기하는 주소와 포트(기본값: :4545)
• http.tls.enable: API에 TLS 암호화를 사용할지 여부
• security.allow_self_registration: 클라이언트가 작업 관리를 위해 스스로 등록하도록 허용
• security.enable_admin: 관리자 기능 활성화
• security.admin_secret_key: 관리자 인증용 비밀 키(기본값에서 반드시 변경하세요!)

스토어 구성#

영구 데이터 저장소를 제어합니다.

• data_source: 클라이언트(즉, 연결하는 Mattermost 노드)의 ID와 자격 증명을 저장할 디렉터리 경로

작업 구성#

작업 처리 동작을 제어합니다.

• api_type: 작업 실행 백엔드(docker 또는 kubernetes)
• max_concurrent_jobs: 동시에 실행할 수 있는 녹음/전사 작업의 최대 개수
• failed_jobs_retention_time: 실패한 작업 데이터를 정리하기 전까지 보관하는 기간
• image_registry: 작업 러너 이미지를 가져올 Docker 레지스트리(일반적으로 mattermost)

로거 구성#

로그 출력을 제어합니다.

• enable_console: 콘솔 출력에 로그 기록
• console_json: 콘솔 로그에 JSON 형식 사용
• console_level: 콘솔 로그 수준(DEBUG, INFO, WARN, ERROR)
• enable_file: 파일에 로그 기록
• file_location: 로그 파일 경로
• enable_color: 콘솔 로그에 색상 출력 사용

프라이빗 네트워크 구성#

Mattermost 배포가 프라이빗 네트워크에서 실행되는 경우, calls-offloader 서비스가 생성한 작업이 Mattermost 서버에 접근할 수 있도록 추가 구성이 필요할 수 있습니다.

이런 경우 Mattermost 서버에 다음 환경 변수를 설정하여 녹음 작업이나 전사 작업이 Mattermost에 연결할 때 사용하는 사이트 URL을 재정의할 수 있습니다.

• MM_CALLS_RECORDER_SITE_URL: 녹음 작업에서 사용하는 사이트 URL을 재정의합니다.
• MM_CALLS_TRANSCRIBER_SITE_URL: 전사 작업에서 사용하는 사이트 URL을 재정의합니다.

구성 예시:

Mattermost 환경 파일(/opt/mattermost/config/mattermost.environment)을 만들거나 편집합니다.

MM_CALLS_RECORDER_SITE_URL="http://internal-mattermost-server:8065"
MM_CALLS_TRANSCRIBER_SITE_URL="http://internal-mattermost-server:8065"

그런 다음 Mattermost systemd 서비스가 이 환경 파일을 참조하는지 확인합니다.

[Unit]
Description=Mattermost
After=network.target

[Service]
Type=notify
EnvironmentFile=/opt/mattermost/config/mattermost.environment
ExecStart=/opt/mattermost/bin/mattermost
TimeoutStartSec=3600
KillMode=mixed
Restart=always
RestartSec=10
WorkingDirectory=/opt/mattermost
User=mattermost
Group=mattermost

[Install]
WantedBy=multi-user.target

이 구성은 특히 다음과 같은 경우에 유용합니다.

• calls-offloader 서비스가 클라이언트와 다른 네트워크 세그먼트에서 실행되는 경우
• 내부 DNS 확인 결과가 외부 URL과 다른 경우
• 작업 통신에 내부 로드 밸런서 엔드포인트를 사용해야 하는 경우

검증 및 테스트#

calls-offloader를 배포한 후 설치를 검증하세요.

1. 서비스 상태 확인:

   # For systemd
   sudo systemctl status calls-offloader
   

2. API 연결 테스트:

   calls-offloader 서버에서(localhost 테스트):

   curl http://localhost:4545/version
   # Should return version information
   # Example: {"buildDate":"2025-03-10 19:13","buildVersion":"v0.9.2","buildHash":"a4bd418","goVersion":"go1.23.6"}
   

   Mattermost 서버에서:

   curl http://YOUR_CALLS_OFFLOADER_SERVER:4545/version
   # Should return the same version information
   # This confirms network connectivity from Mattermost to calls-offloader
   

   localhost 테스트는 성공하지만 Mattermost 서버에서의 테스트가 실패하면 다음을 확인하세요.

   • calls-offloader 서버의 방화벽 규칙 또는 SELinux 정책(4545 포트에 접근할 수 있어야 함)
   • Mattermost 서버와 calls-offloader 서버 사이의 네트워크 연결

3. Docker 서비스 확인(docker api_type을 사용하는 경우):

   # Check that system user running calls-offloader can access Docker
   sudo -u calls-offloader docker ps
   

Mattermost와 연동#

calls-offloader를 올바르게 설정하고 검증했다면 Mattermost가 이를 사용하도록 구성하세요.

1. System Console > Plugins > Calls로 이동합니다.

2. 작업 서비스 섹션에서 다음을 설정합니다.

   • 작업 서비스 URL을 calls-offloader 서비스 주소로 설정합니다(예: http://calls-offloader-server:4545).

3. 필요에 따라 녹음 및 전사 기능을 활성화합니다.

   • 통화 녹음 활성화: 통화 녹음을 허용하려면 켭니다.
   • 통화 전사 활성화: 통화 전사를 허용하려면 켭니다.
   • 실시간 자막 활성화(실험적 기능): 실시간 전사를 허용하려면 켭니다.

4. 구성을 저장합니다.

5. 상태를 다시 설정하기 위해 Calls 플러그인을 다시 시작합니다.

   • System Console > Plugins > Plugin Management로 이동합니다.
   • Calls 플러그인을 찾아 비활성화를 클릭합니다.
   • 몇 초 기다린 후 활성화를 클릭합니다.

6. 통화를 시작하고 녹음을 시작하여 테스트합니다.

문제 해결#

일반적인 문제#

"failed to create recording job: max concurrent jobs reached"

이 오류는 calls-offloader 서비스가 구성된 작업 한도에 도달했을 때 발생하며, 보통 Mattermost Calls 플러그인 쪽에서 실패 메시지(예: 시간 초과)가 나타납니다.

해결 방법:

• 구성에서 max_concurrent_jobs 값을 늘립니다.
• 작업이 멈춰 있는지 확인하고 서비스를 다시 시작합니다.
• 시스템 리소스를 모니터링하고 필요하면 스케일 업합니다.

작업이 처리되지 않는 경우

다음 사항을 확인하세요.

• calls-offloader 서비스가 실행 중인지 확인합니다: sudo systemctl status calls-offloader
• Mattermost와 calls-offloader 사이의 네트워크 연결을 확인합니다.
• Docker 데몬이 실행 중이며 Calls Offloader 서비스를 실행하는 사용자(예: 사용자: calls-offloader)가 접근할 수 있는지 확인합니다.
• 서비스 간에 인증 구성이 일치하는지 확인합니다.
• 서비스 로그에서 구체적인 오류 메시지를 검토합니다.

Docker 권한 문제

Docker API를 사용하는 중에 권한 오류가 발생하면 다음을 실행하세요.

# Add calls-offloader user to docker group
sudo usermod -a -G docker calls-offloader
sudo systemctl restart calls-offloader

디버깅 명령어#

calls-offloader 작업 컨테이너를 모니터링합니다.

# View running job containers
docker ps --format "{} {}" | grep "calls"

# Follow logs for debugging
docker ps --format "{} {}" | grep "calls" | awk '{print $1}' | xargs -I {} docker logs -f {}

# View completed job containers
docker ps -a --filter "status=exited"

서비스 상태를 모니터링합니다.

# Check service version and health
curl http://localhost:4545/version

서비스 로그를 확인합니다.

# View recent logs
sudo journalctl -u calls-offloader -f

# View log file (if file logging enabled)
tail -f /opt/calls-offloader/calls-offloader.log

성능 모니터링#

calls-offloader의 성능과 리소스 사용량을 모니터링하여 최적의 상태로 운영되고 있는지 확인하세요. 메트릭과 관측 도구를 설정하는 방법은 Calls 메트릭 및 모니터링을 참고하세요.

calls-offloader 에어 갭 설치#

이 가이드는 인터넷에 접근할 수 없는 환경에 calls-offloader를 배포하는 방법을 설명합니다. 이 과정은 calls-install-scripts 리포지터리의 스크립트를 사용하며, 인터넷에 연결된 머신에서 전송 번들을 준비한 다음 격리된 대상 머신에 배포하는 두 단계 워크플로로 진행됩니다.

개요#

calls-offloader는 녹음기 및 전사기 작업에 Docker 이미지를 사용하므로, 에어 갭 배포에서는 해당 이미지를 미리 가져와 calls-offloader 바이너리와 함께 패키징한 후 대상 환경으로 전송해야 합니다.

설치 스크립트는 이 과정을 두 단계로 처리합니다.

1. 준비(인터넷에 연결된 머신) — setup-airgap-offloader.sh가 필요한 Docker 이미지를 가져오고 calls-offloader 바이너리를 다운로드한 다음, 모든 항목을 전송 번들로 패키징하고 바로 실행할 수 있는 배포 스크립트를 생성합니다.
2. 배포(에어 갭 머신) — 번들을 전송하고 생성된 deploy-airgap-offloader.sh 스크립트를 실행하면 Docker 이미지를 로컬 레지스트리에 로드하고 서비스를 설치합니다.

사전 요구 사항#

• Docker가 설치된 인터넷 연결 Linux 머신(준비 단계용)
• 다음을 갖춘 대상 에어 갭 Linux 머신
  • systemd
  • Docker 설치
  • root 또는 sudo 권한
• 인터넷에 연결된 머신에 클론한 calls-install-scripts 리포지터리

1단계: 전송 번들 준비#

인터넷에 연결된 머신에서 패키징할 각 구성 요소의 버전을 지정하여 setup-airgap-offloader.sh를 실행합니다.

./setup-airgap-offloader.sh \
  --offloader v0.9.5 \
  --recorder v0.9.0 \
  --transcriber v0.3.0 \
  --arch amd64

이 스크립트는 다음 작업을 수행합니다.

1. Docker Hub에서 calls-recorder 및 calls-transcriber Docker 이미지를 가져옵니다.
2. GitHub 릴리즈에서 calls-offloader 바이너리를 다운로드합니다.
3. Docker 이미지를 .tar 아카이브로 저장합니다.
4. 선택한 버전에 맞게 구성된 deploy-airgap-offloader.sh 배포 스크립트를 생성합니다.
5. 위의 모든 항목을 포함하는 전송 번들을 만듭니다.

2단계: 에어 갭 머신으로 전송#

환경에서 사용할 수 있는 전송 방법(USB 드라이브, 보안 파일 전송 등)으로 생성된 번들을 대상 머신에 복사합니다.

scp calls-offloader-airgap-bundle.tar.gz user@airgap-host:/tmp/

에어 갭 머신에서 번들의 압축을 풉니다.

tar -xzf calls-offloader-airgap-bundle.tar.gz
cd calls-offloader-airgap-bundle/

3단계: 에어 갭 머신에 배포#

root 또는 sudo 권한으로 생성된 배포 스크립트를 실행합니다.

sudo ./deploy-airgap-offloader.sh

이 스크립트는 다음 작업을 수행합니다.

1. 로컬 Docker 데몬이 로컬 이미지 레지스트리를 사용하도록 구성합니다.
2. 패키징된 Docker 이미지를 해당 레지스트리에 로드합니다.
3. calls-offloader 바이너리를 /usr/local/bin/에 설치합니다.
4. mattermost 시스템 사용자를 만들고 docker 그룹에 추가합니다.
5. systemd 서비스 유닛을 생성하고 활성화합니다.
6. 서비스를 시작하고 실행 중인지 확인합니다.

완료되면 서비스가 실행 중인지 확인합니다.

curl http://localhost:4545/version

Mattermost에 연결#

System Console > Plugins > Calls > Job service URL에서 http://<offloader-host>:4545로 설정하여 Mattermost Calls 플러그인이 offloader 서비스를 사용하도록 구성합니다.

프라이빗 네트워크 고려 사항#

에어 갭 환경에서는 녹음기 및 전사기 컨테이너가 보통 내부 URL을 통해 Mattermost 서버에 접근해야 합니다. 생성된 작업이 사용하는 사이트 URL을 재정의하려면 Mattermost 서버에 다음 환경 변수를 설정하세요.

MM_CALLS_RECORDER_SITE_URL=http://internal-mattermost-server:8065
MM_CALLS_TRANSCRIBER_SITE_URL=http://internal-mattermost-server:8065

Mattermost 서버 구성의 ServiceSettings.AllowCorsFrom에 내부 URL을 추가해야 할 수도 있습니다.

사용자 지정 Docker 레지스트리#

에어 갭 환경에 내부 Docker 레지스트리가 이미 있다면, 배포 스크립트가 설정하는 로컬 레지스트리 대신 install-offloader.sh가 해당 레지스트리를 직접 가리키도록 할 수 있습니다.

sudo ./install-offloader.sh \
  --binary ./calls-offloader-linux-amd64 \
  --image-registry registry.internal.example.com/mattermost \
  --arch amd64

--image-registry 플래그는 offloader가 작업마다 녹음기 및 전사기 이미지를 가져올 때 사용하는 레지스트리 접두사를 설정합니다.

기타 Calls 문서#

• Calls 배포 가이드: 배포 옵션과 아키텍처 개요
• RTCD 설정 및 구성: 전용 RTCD 서비스를 설정하기 위한 종합 가이드
• Calls 메트릭 및 모니터링: 메트릭과 관측 도구로 Calls 성능을 모니터링하는 가이드
• 쿠버네티스에서 Calls 배포: 쿠버네티스 환경에 Calls를 배포하기 위한 상세 가이드
• Calls 로깅: Calls 로그와 클라이언트 진단 정보를 수집하는 방법에 대한 상세 안내
• calls-offloader 성능 문서: 상세한 성능 튜닝 및 모니터링 권장 사항