Calls Offloader 설정과 구성

이 가이드는 통화 녹화와 전사 기능에 사용되는 Mattermost calls-offloader 서비스를 설정하고 구성하며 검증하는 방법을 상세히 안내합니다.

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

개요

calls-offloader 서비스는 Mattermost Calls의 리소스 집약적인 작업을 처리하는 전용 마이크로서비스로, 다음 기능을 담당합니다.

• 통화 녹화: 통화의 오디오와 화면 공유 내용을 캡처합니다
• 통화 전사: 녹화된 통화를 자동으로 전사합니다
• 실시간 자막(실험 기능): 통화가 진행되는 동안 실시간으로 전사합니다

이러한 작업을 전용 서비스로 넘김으로써 메인 Mattermost 서버와 RTCD(실시간 통신 데몬) 서비스는 핵심 기능에 집중하면서 최적의 성능을 유지할 수 있습니다.

사전 요구 사항

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

• Mattermost Enterprise 라이선스
• 올바르게 구성된 Mattermost Calls 배포(통합형 또는 RTCD 방식)
• Docker가 설치되어 실행 중인, 어느 정도 성능이 확보된 서버
• 녹화물을 저장할 충분한 스토리지 공간(스토리지 요구 사항 참고)

시스템 요구 사항

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

스토리지 요구 사항

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

• Low: 시간당 약 0.5GB(분당 약 8MB)
• Medium: 시간당 약 0.7GB(분당 약 12MB)
• High: 시간당 약 1.2GB(분당 약 20MB)

참고: 오디오 전용 녹화는 참가자 1명당 분당 약 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. Job Service 섹션에서 다음을 수행합니다.

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

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

   • Enable Call Recordings: 통화 녹화를 허용하도록 켭니다
   • Enable Call Transcriptions: 통화 전사를 허용하도록 켭니다
   • Enable Live Captions(실험 기능): 실시간 전사를 허용하도록 켭니다

4. 설정을 저장합니다

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

   • System Console > Plugins > Plugin Management로 이동합니다
   • Calls 플러그인을 찾아 Disable을 클릭합니다
   • 몇 초 기다린 뒤 Enable을 클릭합니다

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 "{{.ID}} {{.Image}}" | grep "calls"

# Follow logs for debugging
docker ps --format "{{.ID}} {{.Image}}" | 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에서 Mattermost Calls 플러그인이 오프로더 서비스를 사용하도록 설정하고, 값을 http://<offloader-host>:4545로 지정합니다.

사설 네트워크 고려 사항

에어갭 환경에서는 레코더와 트랜스크라이버 컨테이너가 일반적으로 내부 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 플래그는 오프로더가 각 잡에 필요한 레코더·트랜스크라이버 이미지를 받아올 때 사용하는 레지스트리 접두사를 지정합니다.

그 밖의 Calls 문서

• Mattermost Calls 배포 가이드: 배포 옵션과 아키텍처 개요
• RTCD 설정과 구성: 전용 RTCD 서비스 설정에 관한 종합 가이드
• Calls 지표와 모니터링: 지표와 관측성을 활용한 Calls 성능 모니터링 가이드
• Kubernetes에 Calls 배포: Kubernetes 환경에 Calls를 배포하는 상세 가이드
• Calls 로깅: Calls 로그와 클라이언트 진단 정보 수집에 관한 상세 안내
• calls-offloader 성능 문서: 상세한 성능 튜닝과 모니터링 권장 사항