Управление конвейером собраний Teams

Используйте это руководство после того, как вы уже включили функцию из раздела Teams Meetings.

Эта страница охватывает:

• рабочие процессы 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

Затем зарегистрируйте задание cron только со скриптом, которое запускается каждые 12 часов (даёт 6-кратный запас относительно 72-часового окна истечения):

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_*. Простейшее решение: подключите ~/.hermes/.env в начале скрипта-обёртки, который вызывает crontab.

Проверка работы обновления

После настройки расписания проверьте активность обновления после первого запланированного запуска:

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 таинственно «перестал работать» ровно через ~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

• подписки всё ещё существуют удалённо и не истекли

Задания остаются в повторных попытках или завершаются ошибкой до summarization

Проверьте:

• разрешения и доступность расшифровки

• разрешения и доступность записи и артефактов

• доступность ffmpeg, если включён резервный вариант записи

• состояние токена Graph

Сводки создаются, но не доставляются в Teams

Проверьте:

• platforms.teams.enabled: true

• delivery_mode

• incoming_webhook_url для режима вебхука

• chat_id или team_id плюс channel_id для режима Graph

• конфигурация аутентификации Teams, если используется отправка через Graph

Дублирующиеся или неожиданные повторные запуски

Проверьте:

• не запускали ли вы вручную задание с помощью 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 часов.

• [ ] реальное сквозное событие собрания создало сохранённое задание

• [ ] хотя бы одна сводка достигла целевого приёмника доставки

Руководство по выбору режима доставки

Рабочий лист оператора

Заполните это перед развёртыванием:

Рабочий лист проверки изменений

Используйте это перед изменением развёртывания:

Связанные документы

• Настройка Teams Meetings

• Настройка бота Microsoft Teams