操作 Teams 会议流水线

本指南适用于已通过 Teams Meetings 启用该功能之后的操作阶段。

本页内容：

• 操作员 CLI 流程
• 日常订阅维护
• 故障排查
• 上线检查
• 上线工作表

核心操作员命令

验证配置快照

aigenlabs teams-pipeline validate

每次配置变更后首先执行此命令。

检查 token 健康状态

aigenlabs teams-pipeline token-health
aigenlabs teams-pipeline token-health --force-refresh

当怀疑 auth（认证）状态过期时，使用 --force-refresh。

检查订阅

aigenlabs teams-pipeline subscriptions

续期即将到期的订阅

aigenlabs teams-pipeline maintain-subscriptions
aigenlabs teams-pipeline maintain-subscriptions --dry-run

自动化订阅续期（生产环境必须配置）

Microsoft Graph 订阅最多 72 小时后过期。 若无任何续期操作，会议通知将在 3 天后静默停止，流水线看起来像是"故障"。这是所有基于 Graph 的集成中最常见的运维故障模式。

你必须按计划运行 maintain-subscriptions。从以下三种方式中选择一种：

方式一：AigenLabs cron（若已运行 AigenLabs gateway，推荐此方式）

AigenLabs 内置 cron 调度器。--no-agent 模式以脚本作为任务执行（而非使用 LLM），--script 必须指向 ~/.aigenlabs/scripts/ 下的文件。首先创建脚本：

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

然后注册一个每 12 小时运行一次的纯脚本 cron 任务（相对于 72 小时过期窗口有 6 倍余量）：

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

验证注册情况并查看下次运行时间：

aigenlabs cron list
aigenlabs cron status        # 调度器状态

方式二：systemd timer（推荐用于 Linux 生产部署）

创建 /etc/systemd/system/aigenlabs-teams-pipeline-maintain.service：

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

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

以及 /etc/systemd/system/aigenlabs-teams-pipeline-maintain.timer：

[Unit]
Description=Run AigenLabs 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 aigenlabs-teams-pipeline-maintain.timer
systemctl list-timers aigenlabs-teams-pipeline-maintain.timer

方式三：普通 crontab

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

确保 cron 环境中包含 MSGRAPH_* 凭据。最简单的方法：在 crontab 调用的包装脚本顶部 source ~/.aigenlabs/.env。

验证续期是否正常工作

设置好计划任务后，在首次计划运行后检查续期活动：

aigenlabs teams-pipeline subscriptions   # 应显示 expirationDateTime 已推进
aigenlabs teams-pipeline maintain-subscriptions --dry-run   # 大多数时候应显示"0 expiring soon"

如果你发现 Graph webhook 在恰好约 72 小时后神秘地"停止工作"，这是首先要检查的地方：续期任务是否实际运行了？

查看最近的任务

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

重放已存储的任务

aigenlabs teams-pipeline run <job-id>

干运行会议产物拉取

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

日常运行手册

首次设置后

按顺序执行：

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

然后触发或等待一个真实的会议事件，并确认：

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

每日或定期检查

• 运行 aigenlabs teams-pipeline maintain-subscriptions --dry-run
• 检查 aigenlabs teams-pipeline list --status failed
• 确认 Teams 投递目标仍为正确的聊天或频道

变更 webhook URL 或投递目标前

• 更新公共通知 URL 或 Teams 目标配置
• 运行 aigenlabs teams-pipeline validate
• 续期或重新创建受影响的订阅
• 确认新事件落入预期的接收端

故障排查

未创建任何任务

检查：

• msgraph_webhook 是否已启用
• 公共通知 URL 是否指向 /msgraph/webhook
• 订阅中的 client state 是否与 MSGRAPH_WEBHOOK_CLIENT_STATE 匹配
• 订阅是否在远端仍然存在且未过期

任务停留在重试状态或在摘要生成前失败

检查：

• 转录权限及可用性
• 录制权限及产物可用性
• 若启用了录制回退，检查 ffmpeg 是否可用
• Graph token 健康状态

摘要已生成但未投递到 Teams

检查：

• platforms.teams.enabled: true
• delivery_mode
• webhook 模式下的 incoming_webhook_url
• Graph 模式下的 chat_id 或 team_id 加 channel_id
• 若使用 Graph 发帖，检查 Teams auth 配置

重复或意外的重放

检查：

• 是否手动通过 aigenlabs teams-pipeline run 重放了任务
• 该会议的 sink 记录是否已存在
• 是否在本地配置中有意启用了重发路径

上线检查清单

• Graph 凭据已存在且正确
• msgraph_webhook 已启用且可从公网访问
• MSGRAPH_WEBHOOK_CLIENT_STATE 已设置且与订阅匹配
• 转录订阅已创建
• 若需要 STT 回退，录制订阅已创建
• 若启用录制回退，ffmpeg 已安装
• Teams 出站投递目标已配置并验证
• Notion 和 Linear 接收端仅在实际需要时配置
• aigenlabs teams-pipeline validate 返回 OK 快照
• aigenlabs teams-pipeline token-health --force-refresh 执行成功
• maintain-subscriptions 已配置计划任务（AigenLabs cron、systemd timer 或 crontab——参见自动化订阅续期）。若未配置，Graph 订阅将在 72 小时内静默过期。
• 一个真实的端到端会议事件已生成存储任务
• 至少一条摘要已到达预期的投递接收端

投递模式决策指南

模式	适用场景	权衡
incoming_webhook	仅需简单地向 Teams 发帖	配置最简单，控制较少
graph	需要通过 Graph 向频道或聊天发帖	控制更多，auth 和目标配置更复杂

操作员工作表

上线前填写：

项目	值
公共通知 URL
Graph 租户 ID
Graph 客户端 ID
Webhook client state
转录资源订阅
录制资源订阅
Teams 投递模式
Teams 聊天 ID 或团队/频道
Notion 数据库 ID
Linear 团队 ID
Store 路径覆盖（如有）
每日检查负责人

变更审查工作表

变更部署前使用：

问题	答案
是否正在变更公共 webhook URL？
是否正在轮换 Graph 凭据？
是否正在变更 Teams 投递模式？
是否正在迁移到新的 Teams 聊天或频道？
订阅是否需要重新创建或续期？
是否需要重新进行端到端验证？

相关文档

• Teams Meetings 设置
• Microsoft Teams bot 设置