Spore 封禁场景应急手册
本手册覆盖 Telegram 资源（用户号 / Bot / 缓存频道 / 用户绑定频道）被封禁或失效时的预防、发现、处置与验证全流程。适用于已完成封禁韧性改造（数据库 v24 及以上）的 Spore 部署。
日常运维、升级回滚、常规备份恢复见 operations.md；一般故障排查见 troubleshooting.md。
0. 能力总览（v24 起）
| 场景 | 系统行为 | 恢复路径 |
|---|---|---|
| 用户号被封 / 会话撤销 | mtproto.banned Critical 事件（穿透静音计划）；状态页显示封禁详情与处置指引 | 管理端导出备份 → 清理会话文件 → 新号扫码 |
| Bot Token 失效（401） | Bot 标记停用（发送路由自动降级到其他 Bot）；bot.banned Critical 事件；名下排队任务标记 BOT_DISABLED 失败 | 管理端替换 Token（add + delete，重启生效） |
| 缓存频道被封 | 服务不中断，仅失去秒级复用（回退完整提取） | 管理端改缓存频道 ID（即时生效）→ 可选「迁移旧缓存」免重提取搬副本 |
| 用户绑定频道失效 | 副本投递检测到频道已不存在 → 自动软解绑（记录保留、状态置已解绑）+ 私聊通知该用户；管理端可查、可删除 | 用户创建新频道重新 /bind；Bot 被移出权限的场景只提醒不解绑 |
Critical 事件（mtproto.banned / bot.banned）不受通知静音计划与最低级别门槛约束——封禁发生时即使静音窗口开启也会送达；仅当管理员显式关闭该事件或渠道不可用时才收不到。backup.failed 为 error 级。
1. 日常预防（封禁发生前必须完成）
1.1 备用资源清单
以下资源必须提前准备好，封禁发生后再准备来不及：
| 资源 | 准备事项 | 状态 |
|---|---|---|
| 备用手机号 | 已注册 Telegram、已在 my.telegram.org 申请 API ID/Hash | ☐ |
| 备用 Bot Token × 2 | 已通过 @BotFather 创建、已加入缓存频道为管理员 | ☐ |
| 备用缓存频道 | 已创建私有频道、所有 Bot（含备用）已加为管理员 | ☐ |
| 通知渠道 | 至少配置一个非 Telegram 渠道（Webhook）或备用 Bot 通知 | ☐ |
| 最新数据库备份 | 确认自动备份正在运行（见 §1.2）、最近一次备份时间在窗口内 | ☐ |
| 云盘配置备份 | 已导出加密 ZIP、密码保存在密码管理器 | ☐ |
1.2 自动备份（v24 起）
- 容器内定时备份数据库一致性快照（
VACUUM INTO）到data/backups/（宿主机./data/backups，容器重建不丢失）。 - 运行设置页可调（即时生效）：自动备份间隔小时（默认 6，0 = 关闭）、备份保留份数（默认 8，默认间隔下约 48 小时滚动窗口，超出自动删除最老）。
- 备份前自动检查磁盘剩余空间（按数据库大小 ×1.2 预留），不足则跳过并触发
backup.failed事件——磁盘满曾在历史上引发媒体切段全线失败，备份不得成为压垮磁盘的最后一根稻草。 - 手动入口：容器内执行
spore admin backup（可选--output PATH精确输出）。 - 边界：自动/CLI 备份只含数据库。会话文件（session.json / peers.json）、机器人配置（bots.json）、云盘配置等运行文件需经 Web 管理端备份页「全量导出」单独备份。
1.3 定期检查（建议每周）
- [ ] 登录 Web 管理端，确认 MTProto 状态为「已连接」
- [ ] 确认事件中心无未处理的「严重/错误」事件
- [ ] 确认备份页「最近备份时间」在预期窗口内
- [ ] 给备用 Bot 发 /start 确认有回应（Token 未过期）
- [ ] 确认备用缓存频道仍存在、Bot 仍为管理员
- [ ] 容器内
spore admin backup手动跑一次，确认成功
2. 场景 A：MTProto 用户号被封
2.1 如何发现
| 渠道 | 表现 |
|---|---|
| 通知推送 | 收到 mtproto.banned 严重（critical） 通知（所有可用渠道同时推送，穿透静音计划） |
| Web 管理端 | Telegram 连接页显示「⛔ 账号已被封禁（USER_DEACTIVATED_BAN）」或「⚠️ 会话已被撤销」处置指引 |
| Web 事件中心 | mtproto.banned 事件（级别「严重」），状态未解决 |
| 用户侧 | 所有 Bot 完全静默——见 2.2 影响矩阵 |
2.2 影响范围（重要：与直觉相反）
MTProto 掉线期间所有 Bot 完全静默：Bot 长轮询挂在 MTProto 就绪生命周期内，用户号掉线后轮询随生命周期停止——用户收不到任何回应（包括 /status），也不存在「提交链接后一直等待」的状态。这是当前架构的已知单点，降级轮询（掉线期间 Bot 只回复维护提示）列为后续任务。
| 功能 | 影响 |
|---|---|
| 消息提取 | ❌ 完全不可用（无法读取任何源频道） |
| Bot 交互 | ❌ 完全静默（长轮询随生命周期停止，含 /status） |
| 缓存频道复用 | ⚠️ 已有副本不可用（复用同样需要 Bot 在线投递） |
| Web 管理端 | ✅ 正常（登录、备份、用户管理全部可用） |
| 频道副本投递 | ❌ 新任务无法完成，已有副本不受影响 |
| 云盘下载 | ❌ 不可用（依赖 MTProto 下载媒体） |
| 监听预热 | ❌ 不可用（回退路径依赖用户号） |
| 自动备份 | ✅ 正常（只依赖数据库） |
2.3 处置 SOP
text
┌─────────────────────────────────────────────────┐
│ MTProto 用户号被封 — 应急流程 │
└─────────────────────────────────────────────────┘
① 确认封禁（1 分钟）
登录 Web 管理端 → Telegram 连接页
状态为「未连接」且提示「账号已被封禁」或「会话已被撤销」
② 立即备份（5 分钟）
备份页 → 「导出数据库」（数据库快照）
备份页 → 「全量导出」（含 session/peers/bots/云盘配置等 JSON）
保存到受保护位置
③ 通知用户（可选）
若有公告渠道，告知服务暂停原因与预计恢复时间
④ 准备新号（10–30 分钟）
备用手机号 + 该号已有的 API ID / API Hash
（没有则登录 my.telegram.org 申请）
⑤ 清理旧会话（1 分钟）
Telegram 连接页（状态必须为「未连接」）→ 「清理会话文件」
删除 session.json + peers.json，写审计日志
（在线状态按钮禁用；bot 直传会话文件不受影响）
⑥ 新号登录（5 分钟）
Telegram 连接页 → 「重连 / 重新扫码登录」→ 新号扫码
等待状态变为「已连接」
⑦ 恢复频道访问（10–30 分钟）
公开频道自动可访问；私有频道需重新 /join 邀请链接
peers.json 首次访问自动重建
⑧ 验证恢复（5 分钟）
发送测试链接确认提取成功
事件中心 resolve mtproto.banned 事件（重连成功会自动解决）
⑨ 准备下一个备用号2.4 注意事项
- 不要用同一个手机号反复尝试：被封后短期内用同号重试可能加重处罚。
- 新号 API ID/Hash 与旧号不同时：修改
.env的TG_API_ID/TG_API_HASH后spore recreate；相同时只需扫码，无需改.env。 - 旧号在 Telegram 客户端中终止会话：设置 → 设备 → 找到 Spore 的会话 → 终止。
AUTH_KEY_UNREGISTERED归类为「会话已被撤销」（会话失效，非封号），处置相同但通常无需换号——清理会话后原号扫码即可。
3. 场景 B：Bot 被封禁 / Token 被撤销
3.1 如何发现
| 渠道 | 表现 |
|---|---|
| 通知推送 | bot.banned 严重（critical） 通知（经其他 Bot / Webhook / 管理端提醒） |
| Web 事件中心 | bot.banned 事件，附带被封 Bot ID |
| Web 管理端 | 机器人池管理页该 Bot 显示「已停用（Token 失效）」徽标 |
| 用户侧 | 给该 Bot 发消息完全无回应（Telegram 侧限制，无法自动告知） |
3.2 影响范围
| 场景 | 单 Bot 部署 | 多 Bot 池部署 |
|---|---|---|
| 用户交互 | ❌ 完全不可用 | ⚠️ 该 Bot 用户不可用，其他 Bot 正常 |
| 消息提取 | ❌ 无法投递结果 | ✅ 其他 Bot 正常 |
| 名下排队任务 | ❌ 标记失败 BOT_DISABLED（提示用户向其他机器人重新提交） | 同左（不做自动改派：用户未向其他 Bot 发过 /start 时改派必然失败） |
| 缓存频道写入 | ❌ 不可用 | ✅ 其他 Bot 代为路由（发送通道降级到第一个可用 Bot） |
| 大文件直传 | ❌ 该 Bot MTProto 会话不可用 | ✅ 其他 Bot 正常 |
| Web 管理端 | ✅ 正常 | ✅ 正常 |
停用不删除 Token 配置、不自动恢复；进程重启后重新探测，Token 仍失效会再次标记停用（替换 Token 是唯一恢复路径）。
3.3 处置 SOP（多 Bot 池）
text
① 确认封禁：机器人池管理页确认哪个 Bot 已停用（记录 ID / @username）
② 评估：是否唯一 Bot？是 → 按下方单 Bot 流程；否 → 继续
③ 通知受影响用户（可选）：经公告渠道「Bot @xxx 暂不可用，请使用 @yyy」
④ 准备新 Bot：@BotFather 创建 → 加入缓存频道管理员 → 加入需要的绑定频道管理员
⑤ 替换 Token：管理端「添加机器人」（新 Token）+「移除」（旧 Token）
均需重启生效（管理端有受控重启入口）；暂停/恢复才是即时生效的运行时操作
⑥ 验证：重启后新 Bot 在线（无停用徽标）、发测试消息
⑦ 事件中心 resolve bot.banned3.4 处置 SOP（单 Bot 部署）
text
① 确认封禁 + 立即备份（Web 管理端不依赖 Bot）
② 准备新 Bot：@BotFather 创建 → 记录 Token → 加入缓存频道管理员
③ 替换 Token：修改 .env 的 BOT_TOKEN（或 BOT_TOKENS）→ spore recreate
④ 验证：新 Bot 在线；用户需找到新 Bot 重新 /start
⑤ 强烈建议此时补 1–2 个备用 Bot 进池（BOT_TOKENS 逗号分隔）3.5 注意事项
- 被封 Bot 无法发送任何消息告知用户，只能通过外部渠道通知。
- 用户绑定频道的路由 bot 若指向被封 Bot：绑定仍生效（v21 路由），恢复或替换 Bot 后需用户视情况重新 /bind 归属新 Bot。
- 预防建议：始终保持至少 3 个 Bot 在池中，分散风险。
4. 场景 C：缓存频道被封
4.1 如何发现
- 系统日志：缓存频道写入连续失败 Warn。
- 用户侧：之前秒回的链接变慢（复用降级为完整提取）。
- 缓存频道被封不会产生事件（服务不中断，只是性能降级）；发现渠道是用户反馈变慢或日志巡检。
4.2 影响范围
缓存频道被封是影响最小的封禁场景：消息提取、Bot 交互、频道副本、Web 管理端全部正常，只是失去秒级复用。
4.3 处置 SOP
text
① 确认：频道设置页查看当前缓存频道 ID；Telegram 客户端确认频道状态
② 切换：频道设置页把缓存频道改为备用频道（即时生效，无需重启）
旧频道的缓存条目因频道归属不匹配自动不再命中，新提交走完整提取
③ （可选）迁移旧缓存：源频道仍可读时，用「迁移旧缓存」工具把旧频道
副本整批复制到新频道（免重新提取、后台执行、断点可续）；
源频道不可读则跳过——剩余条目由用户再次提交时自愈重建
④ 验证：提交一条新链接（完整提取、写入新频道）；
同链接二次提交确认秒级复用（delivery_mode = reuse）
⑤ 创建下一个备用频道并加入所有 Bot 为管理员手动迁移工具说明（频道设置页「迁移旧缓存」）：
- 只迁移当前副本格式（
format_version）的条目；历史格式行不迁移（本就不命中）。 - 迁移会回写新频道内的消息 ID；目标频道已有同链接条目时跳过并清理旧行。
- 分批限速执行，占用 Bot API 配额；重启即停、重新发起从断点继续。
- 单条失败（原频道消息被删等）不影响其余；源频道整体不可读时中止并提示。
4.4 关于历史副本
旧缓存频道被封意味着其中的副本不可恢复；对用户透明——再次提交已有链接时走一次完整提取后自愈恢复秒回，只是那一次稍慢。
5. 场景 D：用户绑定的转发频道被封
5.1 如何发现
| 渠道 | 表现 |
|---|---|
| 系统自动 | 副本投递检测到频道不存在（chat not found / deactivated / banned）→ 自动软解绑 |
| 用户侧 | 收到 Bot 私聊通知：「您绑定的频道 XXX 已不可用，已自动解绑…」 |
| Web 管理端 | 频道绑定页该行显示「已解绑 · 频道已失效（自动解绑）」+ 时间，写审计 channel_binding.auto_unbind |
5.2 软解绑语义（v24 起）
- 解绑一律为软解绑（用户 /unbind、管理端解绑、频道失效自动解绑）：记录保留、状态置「已解绑」并记原因与时间；不再参与副本投递与 Bot 交互。
- 重新绑定同频道即复活（他人接管已解绑的频道也允许）。
- 删除是物理清行：频道绑定页行内「删除」（danger 确认）与勾选后「批量删除」，用于清理留痕；active 行删除等价强制解绑 + 清痕。
- Bot 被移出频道 / 权限不足不触发自动解绑（只私聊提醒用户重新加回管理员）——那是可恢复的权限问题，与频道本体消失不同。
5.3 处置 SOP（用户侧）
text
① 收到自动解绑通知
② 创建新频道（或将机器人重新加回，视通知内容而定）
③ 给 Bot 发送 /bind 选择新频道
④ 提交测试链接确认新频道收到副本5.4 管理员侧注意
- 转发频道是用户自有资源，管理员通常无需介入；绑定页可按需查看/删除留痕。
- 大量用户的频道同时失效可能是平台级行动，应评估整体风险。
- 建议用户经 /download 把频道内容定期同步到云盘，作为独立于 Telegram 的存档。
6. 组合场景：多个资源同时被封
最严重情况（用户号 + 所有 Bot 同时被封）：
text
① Web 管理端仍可登录（不依赖 MTProto 和 Bot）
② 立即备份：备份页「导出数据库」+「全量导出」（最高优先级）
③ 评估是否迁移服务器（IP 被关联封禁 → 新服务器，见 operations.md §3.5）
④ 按优先级恢复：
P0 数据库备份（保住历史记录，其他都是身外物）
P1 Bot Token（恢复最快：创建新 Bot 即可，用户至少能交互）
P2 MTProto 用户号（新手机号 + 扫码，核心功能回归）
P3 缓存频道（只影响性能，最后恢复）7. 验证检查清单（任何恢复操作后统一执行）
text
基础检查：
[ ] Web 管理端可正常登录
[ ] /healthz 返回成功
[ ] /readyz 返回成功（注意：readyz 只探测数据库连通，
不反映 MTProto/Bot 降级状态，通过 ≠ 全功能可用）
MTProto：
[ ] Telegram 连接页显示「已连接」
Bot：
[ ] 机器人池管理页无「已停用」徽标
[ ] 给每个 Bot 发 /status，确认收到回复
提取功能：
[ ] 发送一条公开频道链接，确认提取成功
[ ] 发送一条私有频道链接，确认提取成功（需用户号已加入）
缓存频道：
[ ] 首次提取后日志显示缓存副本写入
[ ] 同链接二次提交确认秒级复用（delivery_mode = reuse）
转发频道（如有绑定）：
[ ] 提取成功后确认绑定频道收到副本
通知渠道：
[ ] 测试一条通知推送到非 Telegram 渠道
备份：
[ ] 容器内 spore admin backup 成功、data/backups 有新文件8. 事后复盘模板
markdown
## 封禁事件复盘 — YYYY-MM-DD
### 事件概况
- 被封资源：[ ] 用户号 [ ] Bot [ ] 缓存频道 [ ] 转发频道
- 发现时间 / 恢复时间 / 影响时长：
### 影响评估
- 受影响用户数：
- 丢失的请求数（排队中被标记失败的）：
- 缓存频道副本损失：
### 处置过程
- 谁发现的？（Critical 通知 / 用户反馈 / 巡检）
- 处置步骤与耗时：
- 是否使用了备用资源？
### 根因分析
- 封禁可能原因（操作频率过高 / 被举报 / 平台策略调整）：
- 是否有可改进的使用方式：
### 改进措施
- [ ] 备用资源是否需要补充
- [ ] 操作频率是否需要调整
- [ ] 通知渠道是否及时送达（Critical 是否穿透了静音计划）
- [ ] 文档是否需要更新附：封禁相关事件一览
| 事件 Key | 级别 | 触发条件 | 静音计划 |
|---|---|---|---|
mtproto.banned | 严重（critical） | 用户号被封禁（USER_DEACTIVATED_BAN）或会话被撤销（SESSION_REVOKED / AUTH_KEY_UNREGISTERED） | 不受限（穿透） |
bot.banned | 严重（critical） | Bot Token 失效（401：被封禁或撤销），该 Bot 已标记停用 | 不受限（穿透） |
backup.failed | 错误（error） | 自动/手动备份失败（含磁盘空间不足跳过） | 受限（按规则） |
mtproto.session_offline | 错误（error） | MTProto 会话离线（含网络等非封禁原因） | 受限（按规则） |
bot.poll_conflict | 错误（error） | Bot Token 被其他服务占用（409，非封禁） | 受限（按规则） |