运维指南
运维指南解决“Sub2API 上线后怎么用、怎么维护、出了问题怎么办”。它面向管理员和一线运维人员，不要求先读懂全部 Go/Vue 源码。
如果你的目标是修改网关、增加平台或优化热路径，请从项目指南开始；如果服务还没有安装，请先完成部署指南。
三套指南的边界
| 指南 | 回答的问题 | 主要读者 | 典型内容 |
|---|---|---|---|
| 项目指南 | 它是什么、为什么这样设计 | 开发者 | 架构、领域模型、请求链路、代码模块、扩展点 |
| 部署指南 | 怎样把它安装并安全上线 | 部署者 | Docker、二进制、配置、HTTPS、数据库、多实例 |
| 运维指南 | 上线后每天怎样使用和处置问题 | 运维者 | 账号池、用户、流量、监控、告警、Runbook、变更恢复 |
运维者需要掌握的最小模型
text
用户 User
└── Sub2API Key
└── Group（权益、协议和路由边界）
└── Account Pool
├── Account A（凭证、模型、并发、优先级）
├── Account B
└── Proxy（可选网络出口）绝大多数线上问题都能落在五层之一：
- 入口层：域名、HTTPS、反向代理、请求体或 WebSocket/SSE。
- 用户层：用户、Sub2API Key、余额、订阅、平台配额。
- 路由层：Group、Channel、模型映射、平台和调度规则。
- 账号层：上游凭证、状态、限流、并发、代理和可用模型。
- 基础设施层：应用、PostgreSQL、Redis、磁盘和后台任务。
排障时先确定层级，再修改配置。不要一看到 503 就重启服务，也不要一看到 401 就直接清理所有账号状态。
推荐阅读顺序
第一次接手
发生故障
做变更或优化
运维的基本原则
- 先建立测试 Group，再操作生产 Group。
- 账号下线先关闭调度，等待活跃请求结束，再撤销凭证。
- 把“永久错误”“临时不可调度”“限流”“过载”“手动停用”分开处理。
- 每次变更都记录版本、操作者、前后值、验证结果和回退方式。
/health只是进程存活检查；它当前不会主动验证 PostgreSQL、Redis 或上游。- 成功率正常不代表计费正常；发布后必须同时检查 usage、模型映射和费用。
- 不把“清除错误状态”当成修复。根因未消除时，账号会立即再次进入错误或冷却状态。
最小生产运维闭环
text
监控发现异常
→ 确定影响范围（平台/分组/用户/模型）
→ 用 Request ID 查看请求与上游错误
→ 摘除问题账号或暂停变更
→ 修复凭证、映射、代理或容量
→ 在测试 Group 验证
→ 恢复生产调度
→ 核对用量与费用
→ 记录事件和改进项上线后的第一周
建议保持保守配置：
- 每个平台至少一个隔离测试 Group。
- 每类上游至少一个备用账号或明确降级方案。
- 新账号初始并发设小，观察上游 429、TTFT 和费用后再提高。
- 暂时不要过滤“无可用账号”错误，它通常是最有价值的配置告警。
- 开启 Ops 监控、错误日志和邮件告警，完成一次真实触发测试。
- 每天核对上游账单与 Sub2API 的 account cost、用户费用。
与基础设施文档的关系
运维指南告诉你何时做、怎样判断和如何处置；具体安装命令仍以部署文档为准：
- 数据库与 Redis：PostgreSQL 与 Redis
- 反向代理：反向代理与 HTTPS
- 多实例：多实例与高可用
- 上线检查：生产环境检查表