Teams 세션 파이프라인 운영

anchor alias

Teams 세션 파이프라인 운영

Teams 세션에서 기능을 이미 활성화한 후 이 가이드를 사용하세요.

이 페이지에서는 다음 내용을 다룹니다.

• 운영자 CLI 흐름
• 정기 구독 유지 관리
• 실패 분류
• 가동 점검
• 출시 워크시트

핵심 운영자 명령

구성 스냅샷 검증

hermes teams-pipeline validate

구성을 변경한 후 먼저 이것을 사용하세요.

토큰 상태 검사

hermes teams-pipeline token-health
hermes teams-pipeline token-health --force-refresh

오래된 인증 상태가 의심되는 경우 --force-refresh을 사용하세요.

구독 검사

hermes teams-pipeline subscriptions

만료가 임박한 구독 갱신

hermes teams-pipeline maintain-subscriptions
hermes teams-pipeline maintain-subscriptions --dry-run

구독 갱신 자동화(프로덕션에 필수)

Microsoft Graph 구독은 최대 72시간 후에 만료됩니다. 아무것도 갱신되지 않으면 모임 알림은 3일 후에 자동으로 중지되고 파이프라인이 "손상된" 것처럼 보입니다. 이는 모든 Graph 지원 통합에 대한 최고의 작동 실패 모드입니다.

일정에 따라 maintain-subscriptions을 실행해야 합니다. 다음 세 가지 옵션 중 하나를 선택하세요.

옵션 1: Hermes cron(Hermes 게이트웨이를 이미 실행 중인 경우 권장)

Hermes는 내장 cron 스케줄러를 제공합니다. --no-agent 모드는 LLM을 사용하지 않고 스크립트를 작업으로 실행하며 --script은 ~/.hermes/scripts/ 아래의 파일을 가리켜야 합니다. 먼저 스크립트를 작성하세요.

mkdir -p ~/.hermes/scripts
cat > ~/.hermes/scripts/maintain-teams-subscriptions.sh <<'EOF'
#!/usr/bin/env bash
exec hermes teams-pipeline maintain-subscriptions
EOF
chmod +x ~/.hermes/scripts/maintain-teams-subscriptions.sh

그런 다음 12시간마다 실행되는 스크립트 전용 cron 작업을 등록합니다(72시간 만료 창에 대해 6배의 헤드룸 제공).

hermes cron create "0 */12 * * *" \
  --name "teams-pipeline-maintain-subscriptions" \
  --no-agent \
  --script maintain-teams-subscriptions.sh \
  --deliver local

등록되었는지 확인하고 다음 런타임을 검사합니다.

hermes cron list
hermes cron status        # scheduler status

옵션 2: systemd 타이머(Linux 프로덕션 배포에 권장됨)

/etc/systemd/system/hermes-teams-pipeline-maintain.service 생성:

[Unit]
Description=Hermes Teams pipeline subscription maintenance
After=network-online.target

[Service]
Type=oneshot
User=hermes
EnvironmentFile=/etc/hermes/env
ExecStart=/usr/local/bin/hermes teams-pipeline maintain-subscriptions

그리고 /etc/systemd/system/hermes-teams-pipeline-maintain.timer:

[Unit]
Description=Run Hermes Teams pipeline subscription maintenance every 12 hours

[Timer]
OnBootSec=5min
OnUnitActiveSec=12h
Persistent=true

[Install]
WantedBy=timers.target

활성화:

sudo systemctl daemon-reload
sudo systemctl enable --now hermes-teams-pipeline-maintain.timer
systemctl list-timers hermes-teams-pipeline-maintain.timer

옵션 3: 일반 crontab

0 */12 * * * /usr/local/bin/hermes teams-pipeline maintain-subscriptions >> /var/log/hermes/teams-pipeline-maintain.log 2>&1

cron 환경에 MSGRAPH_* 자격 증명이 있는지 확인하세요. 가장 간단한 수정: crontab이 호출하는 래퍼 스크립트 상단의 소스 ~/.hermes/.env.

갱신이 작동하는지 확인 중

일정을 설정한 후 첫 번째 예약된 실행 후 갱신 활동을 확인하세요.

hermes teams-pipeline subscriptions   # should show expirationDateTime advanced
hermes teams-pipeline maintain-subscriptions --dry-run   # should show "0 expiring soon" most of the time

정확히 72시간 후에 그래프 웹후크가 이상하게도 "작동 중지"되는 것을 본 경우 가장 먼저 확인해야 할 사항은 갱신 작업이 실제로 실행되었는지 여부입니다.

최근 작업 검사

hermes teams-pipeline list
hermes teams-pipeline list --status failed
hermes teams-pipeline show <job-id>

저장된 작업 재생

hermes teams-pipeline run <job-id>

테스트 실행 세션 아티팩트 가져오기

hermes teams-pipeline fetch --meeting-id <meeting-id>
hermes teams-pipeline fetch --join-web-url "<join-url>"

루틴 런북

첫 번째 설정 후

다음을 순서대로 실행하세요.

hermes teams-pipeline validate
hermes teams-pipeline token-health --force-refresh
hermes teams-pipeline subscriptions

그런 다음 실제 세션 이벤트를 트리거하거나 기다리고 다음을 확인합니다.

hermes teams-pipeline list
hermes teams-pipeline show <job-id>

일일 또는 정기 점검

• hermes teams-pipeline maintain-subscriptions --dry-run 실행
• hermes teams-pipeline list --status failed 검사
• Teams 전달 대상이 여전히 올바른 채팅 또는 채널인지 확인하세요.

웹훅 URL이나 전달 대상을 변경하기 전

• 공개 알림 URL 또는 Teams 대상 구성 업데이트
• hermes teams-pipeline validate 실행
• 영향을 받는 구독을 갱신하거나 다시 생성
• 새로운 이벤트가 예상되는 싱크에 도달했는지 확인

실패 분류

일자리가 창출되지 않습니다.

확인:

• msgraph_webhook이 활성화되었습니다.
• 공개 알림 URL은 /msgraph/webhook을 가리킵니다.
• 구독의 클라이언트 상태가 MSGRAPH_WEBHOOK_CLIENT_STATE과 일치합니다.
• 구독은 여전히 원격으로 존재하며 만료되지 않았습니다.

작업이 재시도 상태로 유지되거나 요약 전에 실패함

확인:

• 성적 증명서 승인 및 가용성
• 녹음 권한 및 아티팩트 가용성
• ffmpeg 녹화 대체가 활성화된 경우 가용성
• 그래프 토큰 상태

요약이 생성되지만 Teams에 전달되지는 않습니다.

확인:

• platforms.teams.enabled: true
• delivery_mode
• 웹훅 모드의 경우 incoming_webhook_url
• chat_id 또는 team_id + 그래프 모드의 경우 channel_id
• 그래프 게시가 사용되는 경우 Teams 인증 구성

중복되거나 예상치 못한 재생

확인:

• hermes teams-pipeline run을 사용하여 작업을 수동으로 재생했는지 여부
• 해당 세션에 대한 싱크 기록이 이미 존재하는지 여부
• 로컬 구성에서 의도적으로 재전송 경로를 활성화했는지 여부

가동 체크리스트

• 그래프 자격 증명이 있고 정확합니다.
• msgraph_webhook이 활성화되어 공용 인터넷에서 연결할 수 있습니다.
• MSGRAPH_WEBHOOK_CLIENT_STATE이 설정되어 구독과 일치합니다.
• 성적표 구독이 생성되었습니다
• STT 대체가 필요한 경우 녹음 구독이 생성됩니다.
• 녹화 대체가 활성화된 경우 ffmpeg이 설치됩니다.
• Teams 아웃바운드 배달 대상이 구성 및 확인되었습니다.
• Notion 및 Linear 싱크는 실제로 필요한 경우에만 구성됩니다.
• hermes teams-pipeline validate은 OK 스냅샷을 반환합니다.
• hermes teams-pipeline token-health --force-refresh 성공
• maintain-subscriptions이 예정되어 있습니다(Hermes cron, systemd 타이머 또는 crontab — 구독 갱신 자동화 참조). 그렇지 않으면 Graph 구독이 72시간 이내에 자동으로 만료됩니다.
• 실제 종단 간 세션 이벤트로 인해 저장된 작업이 생성되었습니다.
• 하나 이상의 요약이 의도한 배달 싱크에 도달했습니다.

제공 모드 결정 가이드

모드	다음과 같은 경우에 사용하세요.	트레이드오프
incoming_webhook	Teams에 간단한 게시만 하면 됩니다.	가장 간단한 설정, 더 적은 제어
graph	Graph를 통한 채널 또는 채팅 게시가 필요합니다.	더 많은 제어, 더 많은 인증 및 대상 구성

운영자 워크시트

출시 전에 다음 사항을 작성하세요.

품목	가치
공고 URL
그래프 테넌트 ID
그래프 클라이언트 ID
웹훅 클라이언트 상태
성적 증명서 자원 구독
녹음 리소스 구독
팀 배달 모드
Teams 채팅 ID 또는 팀/채널
노션 데이터베이스 ID
선형 팀 ID
저장 경로 재정의(있는 경우)
일일 점검 소유자

변경 검토 워크시트

배포를 변경하기 전에 다음을 사용하세요.

질문	답변
공개 웹훅 URL이 변경되나요?
Graph 자격 증명을 교체하고 있나요?
Teams 제공 모드를 변경하고 있나요?
새로운 Teams 채팅이나 채널로 이동하고 있나요?
구독을 다시 생성하거나 갱신해야 합니까?
새로운 엔드투엔드 검증 실행이 필요합니까?

관련 문서

• 팀 세션 설정
• Microsoft Teams 봇 설정