operate-teams-meeting-pipeline
1|---
2|title: "操作 Teams 会议流水线"
3|description: "Microsoft Teams 会议流水线的运行手册、上线前检查清单和操作员工作表"
4|---
5|
6|# 操作 Teams 会议流水线
7|
8|当你已经从 Teams 会议 启用该功能后，使用本指南。
9|
10|本页涵盖：
11|- 操作员 CLI 流程
12|- 日常订阅维护
13|- 故障分类
14|- 上线前检查
15|- 部署工作表
16|
17|## 核心操作员命令
18|
19|### 验证配置快照
20|
21|bash 22|hermes teams-pipeline validate 23|
24|
25|在任何配置更改后首先使用此命令。
26|
27|### 检查令牌健康状态
28|
29|bash 30|hermes teams-pipeline token-health 31|hermes teams-pipeline token-health --force-refresh 32|
33|
34|当你怀疑认证状态过期时使用 --force-refresh。
35|
36|### 检查订阅
37|
38|bash 39|hermes teams-pipeline subscriptions 40|
41|
42|### 续订即将过期的订阅
43|
44|bash 45|hermes teams-pipeline maintain-subscriptions 46|hermes teams-pipeline maintain-subscriptions --dry-run 47|
48|
49|### 自动化订阅续订（生产环境必需）
50|
51|Microsoft Graph 订阅最多在 72 小时后过期。 如果没有任何续订机制，会议通知会在 3 天后静默停止，流水线看起来"坏了"。这是任何基于 Graph 的集成的 #1 运维故障模式。
52|
53|你必须定期运行 maintain-subscriptions。从以下三个选项中选择一个：
54|
55|#### 选项 1：Hermes cron（如果你已经运行 Hermes 网关，推荐使用）
56|
57|Hermes 内置了 cron 调度器。--no-agent 模式将脚本作为作业运行（而不是使用 LLM），并且 --script 必须指向 ~/.hermes/scripts/ 下的文件。首先创建脚本：
58|
59|bash 60|mkdir -p ~/.hermes/scripts 61|cat > ~/.hermes/scripts/maintain-teams-subscriptions.sh <<'EOF' 62|#!/usr/bin/env bash 63|exec hermes teams-pipeline maintain-subscriptions 64|EOF 65|chmod +x ~/.hermes/scripts/maintain-teams-subscriptions.sh 66|
67|
68|然后注册一个每 12 小时运行一次的纯脚本 cron 作业（在 72 小时过期窗口期内提供 6 倍冗余）：
69|
70|bash 71|hermes cron create "0 */12 * * *" \ 72| --name "teams-pipeline-maintain-subscriptions" \ 73| --no-agent \ 74| --script maintain-teams-subscriptions.sh \ 75| --deliver local 76|
77|
78|验证是否已注册并检查下次运行时间：
79|
80|bash 81|hermes cron list 82|hermes cron status # 调度器状态 83|
84|
85|#### 选项 2：systemd 定时器（Linux 生产部署推荐使用）
86|
87|创建 /etc/systemd/system/hermes-teams-pipeline-maintain.service：
88|
89|ini 90|[Unit] 91|Description=Hermes Teams pipeline subscription maintenance 92|After=network-online.target 93| 94|[Service] 95|Type=oneshot 96|User=hermes 97|EnvironmentFile=/etc/hermes/env 98|ExecStart=/usr/local/bin/hermes teams-pipeline maintain-subscriptions 99|
100|
101|和 /etc/systemd/system/hermes-teams-pipeline-maintain.timer：
102|
103|ini 104|[Unit] 105|Description=Run Hermes Teams pipeline subscription maintenance every 12 hours 106| 107|[Timer] 108|OnBootSec=5min 109|OnUnitActiveSec=12h 110|Persistent=true 111| 112|[Install] 113|WantedBy=timers.target 114|
115|
116|启用：
117|
118|bash 119|sudo systemctl daemon-reload 120|sudo systemctl enable --now hermes-teams-pipeline-maintain.timer 121|systemctl list-timers hermes-teams-pipeline-maintain.timer 122|
123|
124|#### 选项 3：普通 crontab
125|
126|cron 127|0 */12 * * * /usr/local/bin/hermes teams-pipeline maintain-subscriptions >> /var/log/hermes/teams-pipeline-maintain.log 2>&1 128|
129|
130|确保 cron 环境具有 MSGRAPH_* 凭据。最简单的修复方法：在 crontab 调用的包装脚本顶部引入 ~/.hermes/.env。
131|
132|#### 验证续订是否正常工作
133|
134|设置计划后，在第一次计划运行后检查续订活动：
135|
136|bash 137|hermes teams-pipeline subscriptions # 应显示 expirationDateTime 已更新 138|hermes teams-pipeline maintain-subscriptions --dry-run # 大多数时候应显示 "0 expiring soon" 139|
140|
141|如果你看到 Graph webhook 在大约 72 小时后神秘地"停止工作"，这是首先要检查的事情：续订作业是否实际运行了？
142|
143|### 检查最近作业
144|
145|bash 146|hermes teams-pipeline list 147|hermes teams-pipeline list --status failed 148|hermes teams-pipeline show <job-id> 149|
150|
151|### 重放存储的作业
152|
153|bash 154|hermes teams-pipeline run <job-id> 155|
156|
157|### 预运行会议 artifact 获取
158|
159|bash 160|hermes teams-pipeline fetch --meeting-id <meeting-id> 161|hermes teams-pipeline fetch --join-web-url "<join-url>" 162|
163|
164|## 日常运行手册
165|
166|### 首次设置后
167|
168|按顺序运行这些命令：
169|
170|bash 171|hermes teams-pipeline validate 172|hermes teams-pipeline token-health --force-refresh 173|hermes teams-pipeline subscriptions 174|
175|
176|然后触发或等待真实的会议事件并确认：
177|
178|bash 179|hermes teams-pipeline list 180|hermes teams-pipeline show <job-id> 181|
182|
183|### 每日或定期检查
184|
185|- 运行 hermes teams-pipeline maintain-subscriptions --dry-run
186|- 检查 hermes teams-pipeline list --status failed
187|- 验证 Teams 传递目标仍然是正确的聊天或频道
188|
189|### 更改 webhook URL 或传递目标之前
190|
191|- 更新公共通知 URL 或 Teams 目标配置
192|- 运行 hermes teams-pipeline validate
193|- 续订或重新创建受影响的订阅
194|- 确认新事件到达预期的接收端
195|
196|## 故障分类
197|
198|### 没有作业被创建
199|
200|检查：
201|- msgraph_webhook 已启用
202|- 公共通知 URL 指向 /msgraph/webhook
203|- 订阅中的客户端状态与 MSGRAPH_WEBHOOK_CLIENT_STATE 匹配
204|- 订阅在远程仍然存在且未过期
205|
206|### 作业在摘要生成之前保持重试或失败状态
207|
208|检查：
209|- 转录权限和可用性
210|- 录制权限和 artifact 可用性
211|- 如果启用了录制回退，检查 ffmpeg 是否可用
212|- Graph 令牌健康状态
213|
214|### 摘要已生成但未传递到 Teams
215|
216|检查：
217|- platforms.teams.enabled: true
218|- delivery_mode
219|- webhook 模式的 incoming_webhook_url
220|- Graph 模式的 chat_id 或 team_id 加 channel_id
221|- 如果使用 Graph 发布，检查 Teams 认证配置
222|
223|### 重复或意外的重放
224|
225|检查：
226|- 是否手动使用 hermes teams-pipeline run 重放了作业
227|- 该会议的接收端记录是否已存在
228|- 是否在本地配置中有意启用了重发路径
229|
230|## 上线前检查清单
231|
232|- [ ] Graph 凭据存在且正确
233|- [ ] msgraph_webhook 已启用且可从公共互联网访问
234|- [ ] MSGRAPH_WEBHOOK_CLIENT_STATE 已设置且与订阅匹配
235|- [ ] 已创建转录订阅
236|- [ ] 如果需要 STT 回退，已创建录制订阅
237|- [ ] 如果启用了录制回退，已安装 ffmpeg
238|- [ ] Teams 出站传递目标已配置且验证
239|- [ ] Notion 和 Linear 接收端仅在实际需要时才配置
240|- [ ] hermes teams-pipeline validate 返回 OK 快照
241|- [ ] hermes teams-pipeline token-health --force-refresh 成功
242|- [ ] maintain-subscriptions 已计划（Hermes cron、systemd 定时器或 crontab — 参见自动化订阅续订）。没有这个，Graph 订阅会在 72 小时内静默过期。
243|- [ ] 真实的端到端会议事件已生成存储的作业
244|- [ ] 至少一份摘要已到达预期的传递接收端
245|
246|## 传递模式决策指南
247|
248|| 模式 | 使用场景 | 权衡 |
249||------|----------|------|
250|| incoming_webhook | 只需要简单发布到 Teams | 最简单的设置，控制较少 |
251|| graph | 需要通过 Graph 发布到频道或聊天 | 更多控制，更多认证和目标配置 |
252|
253|## 操作员工作表
254|
255|在部署前填写：
256|
257|| 项目 | 值 |
258||------|-------|
259|| 公共通知 URL | |
260|| Graph 租户 ID | |
261|| Graph 客户端 ID | |
262|| Webhook 客户端状态 | |
263|| 转录资源订阅 | |
264|| 录制资源订阅 | |
265|| Teams 传递模式 | |
266|| Teams 聊天 ID 或团队/频道 | |
267|| Notion 数据库 ID | |
268|| Linear 团队 ID | |
269|| 存储路径覆盖（如果有） | |
270|| 日常检查负责人 | |
271|
272|## 变更审查工作表
273|
274|在更改部署之前使用此表：
275|
276|| 问题 | 答案 |
277||----------|--------|
278|| 我们是否更改了公共 webhook URL？ | |
279|| 我们是否轮换了 Graph 凭据？ | |
280|| 我们是否更改了 Teams 传递模式？ | |
281|| 我们是否迁移到新的 Teams 聊天或频道？ | |
282|| 是否需要重新创建或续订订阅？ | |
283|| 我们是否需要新的端到端验证运行？ | |
284|
285|## 相关文档
286|
287|- Teams 会议设置
288|- Microsoft Teams 机器人设置
289|