操作 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 timer（推薦用於 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 調用的包裝腳本頂部 source ~/.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

如果你發現 Graph webhook 在恰好約 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 交付目標是否仍為正確的聊天或頻道

更改 webhook URL 或交付目標之前

• 更新公共通知 URL 或 Teams 目標配置
• 運行 hermes teams-pipeline validate
• 續訂或重新創建受影響的訂閱
• 確認新事件進入預期的接收端

故障分類排查

未創建任何任務

檢查：

• msgraph_webhook 是否已啟用
• 公共通知 URL 是否指向 /msgraph/webhook
• 訂閱中的客戶端狀態是否與 MSGRAPH_WEBHOOK_CLIENT_STATE 匹配
• 遠程訂閱是否仍然存在且未過期

任務停留在重試狀態或在摘要生成前失敗

檢查：

• 轉錄權限和可用性
• 錄製權限和工件可用性
• 如果啟用了錄製回退，檢查 ffmpeg 可用性
• Graph 令牌健康狀態

已生成摘要但未交付到 Teams

檢查：

• platforms.teams.enabled: true
• delivery_mode
• webhook 模式下的 incoming_webhook_url
• Graph 模式下的 chat_id 或 team_id 加上 channel_id
• 如果使用 Graph 發帖，檢查 Teams 身份驗證配置

重複或意外的重放

檢查：

• 是否使用 hermes teams-pipeline run 手動重放了任務
• 該會議的接收端記錄是否已存在
• 是否在本地配置中有意啟用了重新發送路徑

上線檢查清單

• Graph 憑據存在且正確
• 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 timer 或 crontab — 參見 自動化訂閱續訂）。如果沒有此項，Graph 訂閱將在 72 小時內靜默過期。
• 真實的端到端會議事件已生成存儲的作業
• 至少有一個摘要已到達預期的交付接收端

交付模式決策指南

模式	適用場景	權衡
incoming_webhook	只需簡單發佈到 Teams	設置最簡單，控制力較少
graph	需要通過 Graph 發佈到頻道或聊天	控制力更強，但需要更多身份驗證和目標配置

操作員工作表

在 rollout 之前填寫此表：

項目	值
公共通知 URL
Graph 租戶 ID
Graph 客戶端 ID
Webhook 客戶端狀態
轉錄資源訂閱
錄製資源訂閱
Teams 交付模式
Teams 聊天 ID 或團隊/頻道
Notion 數據庫 ID
Linear 團隊 ID
存儲路徑覆蓋（如果有）
每日檢查負責人

變更審查工作表

在更改部署之前使用此表：

問題	回答
我們是否正在更改公共 webhook URL？
我們是否正在輪換 Graph 憑據？
我們是否正在更改 Teams 交付模式？
我們是否正在遷移到新的 Teams 聊天或頻道？
是否需要重新創建或續訂訂閱？
我們是否需要進行全新的端到端驗證運行？

相關文檔

• Teams 會議設置
• Microsoft Teams 機器人設置