geo/.qoder/repowiki/zh/content/故障排除与FAQ.md

# 故障排除与FAQ

<cite>
**本文引用的文件**
- [backend/app/main.py](file://backend/app/main.py)
- [backend/app/config.py](file://backend/app/config.py)
- [backend/app/database.py](file://backend/app/database.py)
- [backend/app/api/auth.py](file://backend/app/api/auth.py)
- [backend/app/services/auth.py](file://backend/app/services/auth.py)
- [backend/app/models/user.py](file://backend/app/models/user.py)
- [backend/app/schemas/auth.py](file://backend/app/schemas/auth.py)
- [backend/app/api/deps.py](file://backend/app/api/deps.py)
- [backend/app/api/queries.py](file://backend/app/api/queries.py)
- [backend/app/models/query.py](file://backend/app/models/query.py)
- [backend/app/workers/scheduler.py](file://backend/app/workers/scheduler.py)
- [frontend/app/api/auth/[...nextauth]/route.ts](file://frontend/app/api/auth/[...nextauth]/route.ts)
- [frontend/lib/auth.ts](file://frontend/lib/auth.ts)
- [docker-compose.yml](file://docker-compose.yml)
- [backend/requirements.txt](file://backend/requirements.txt)
</cite>

## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细组件分析](#详细组件分析)
6. [依赖分析](#依赖分析)
7. [性能考虑](#性能考虑)
8. [故障排除指南](#故障排除指南)
9. [结论](#结论)
10. [附录](#附录)

## 简介
本文件面向GEO平台的运维与开发人员，提供系统化的故障排除与常见问题解答（FAQ）。内容覆盖认证问题、数据库连接问题、API调用问题、性能问题的定位与修复；同时给出系统监控与诊断方法（健康检查、错误日志分析、性能指标监控）、调试技巧与工具使用（开发/生产环境），以及常见错误码含义与预防性维护最佳实践，并提供紧急故障恢复流程与应急处理方案。

## 项目结构
- 后端采用FastAPI + SQLAlchemy异步ORM + Redis/APScheduler任务调度，通过Docker Compose编排PostgreSQL、Redis、后端与前端服务。
- 前端使用Next.js + NextAuth进行会话管理，通过NextAuth路由对接后端认证接口。
- 关键路径：前端登录请求 → NextAuth → 后端认证接口 → 数据库用户校验 → JWT签发 → 前端会话存储。

```mermaid
graph TB
FE["前端应用<br/>Next.js + NextAuth"] --> NA["NextAuth路由<br/>/api/auth/[...nextauth]"]
NA --> BA["后端认证接口<br/>/api/v1/auth/*"]
BA --> DB["数据库<br/>PostgreSQL"]
BA --> CFG["配置中心<br/>settings/DATABASE_URL/JWT等"]
BA --> SCH["任务调度器<br/>APScheduler"]
BE["后端服务<br/>FastAPI"] --> DB
BE --> REDIS["缓存/队列<br/>Redis"]
```

图表来源
- [backend/app/main.py:24-47](file://backend/app/main.py#L24-L47)
- [frontend/app/api/auth/[...nextauth]/route.ts](file://frontend/app/api/auth/[...nextauth]/route.ts#L1-L7)
- [backend/app/config.py:7-13](file://backend/app/config.py#L7-L13)
- [backend/app/database.py:6-18](file://backend/app/database.py#L6-L18)
- [backend/app/workers/scheduler.py:25-95](file://backend/app/workers/scheduler.py#L25-L95)

章节来源
- [backend/app/main.py:1-48](file://backend/app/main.py#L1-L48)
- [docker-compose.yml:1-71](file://docker-compose.yml#L1-L71)

## 核心组件
- 应用入口与生命周期：定义FastAPI应用、CORS中间件、路由注册与健康检查端点。
- 配置管理：集中读取DATABASE_URL、REDIS_URL、JWT密钥、API密钥等。
- 数据库层：异步引擎与会话工厂，提供依赖注入式数据库会话。
- 认证模块：注册/登录/当前用户信息，JWT生成与校验，OAuth2 Bearer令牌解析。
- 查询模块：查询任务的增删改查，权限校验与分页参数控制。
- 任务调度：基于APScheduler的异步调度器，周期性扫描并执行到期查询任务。
- 前端认证：NextAuth凭据提供者对接后端登录接口，JWT会话策略。

章节来源
- [backend/app/main.py:13-47](file://backend/app/main.py#L13-L47)
- [backend/app/config.py:4-16](file://backend/app/config.py#L4-L16)
- [backend/app/database.py:1-29](file://backend/app/database.py#L1-L29)
- [backend/app/api/auth.py:1-43](file://backend/app/api/auth.py#L1-L43)
- [backend/app/services/auth.py:1-69](file://backend/app/services/auth.py#L1-L69)
- [backend/app/api/queries.py:1-86](file://backend/app/api/queries.py#L1-L86)
- [backend/app/models/query.py:1-55](file://backend/app/models/query.py#L1-L55)
- [backend/app/workers/scheduler.py:1-95](file://backend/app/workers/scheduler.py#L1-L95)
- [frontend/lib/auth.ts:1-56](file://frontend/lib/auth.ts#L1-L56)

## 架构总览
下图展示从浏览器到后端、数据库与外部平台的关键交互路径，以及认证与任务调度的运行时关系。

```mermaid
sequenceDiagram
participant U as "用户浏览器"
participant F as "前端NextAuth"
participant A as "后端认证接口"
participant D as "数据库"
participant J as "JWT令牌"
participant S as "任务调度器"
U->>F : "提交登录表单"
F->>A : "POST /api/v1/auth/login"
A->>D : "按邮箱查询用户"
D-->>A : "返回用户记录"
A->>A : "校验密码"
A->>J : "签发访问令牌"
A-->>F : "返回令牌与用户信息"
F-->>U : "建立会话并跳转"
Note over S,D : "后台定时扫描到期查询并执行"
```

图表来源
- [frontend/lib/auth.ts:13-31](file://frontend/lib/auth.ts#L13-L31)
- [backend/app/api/auth.py:22-37](file://backend/app/api/auth.py#L22-L37)
- [backend/app/services/auth.py:55-69](file://backend/app/services/auth.py#L55-L69)
- [backend/app/models/user.py:11-41](file://backend/app/models/user.py#L11-L41)
- [backend/app/workers/scheduler.py:51-84](file://backend/app/workers/scheduler.py#L51-L84)

## 详细组件分析

### 认证组件分析
- 登录流程要点
  - 前端NextAuth凭据提供者收集邮箱/密码，调用后端登录接口。
  - 后端根据邮箱查询用户，校验密码，成功则签发JWT。
  - 前端以JWT策略存储会话，后续受保护路由自动携带Bearer令牌。
- 常见问题与定位
  - 用户名或密码错误：后端返回未授权错误，需检查输入格式与用户是否存在。
  - JWT过期或密钥不一致：令牌解析失败导致“凭据无效”，需核对JWT_SECRET与过期时间。
  - CORS跨域：若前端端口变更但后端允许源未更新，会出现跨域错误。
- 安全建议
  - 生产环境必须更换默认JWT密钥，设置合理过期时间。
  - 密码使用哈希存储，传输层启用HTTPS。

```mermaid
sequenceDiagram
participant C as "客户端"
participant N as "NextAuth"
participant R as "认证路由"
participant M as "模型/服务"
participant T as "JWT"
C->>N : "凭据提交"
N->>R : "POST /api/v1/auth/login"
R->>M : "查询用户并校验密码"
M-->>R : "返回用户或空"
alt "用户存在且密码正确"
R->>T : "生成访问令牌"
R-->>N : "返回令牌与用户"
N-->>C : "会话建立"
else "用户不存在或密码错误"
R-->>N : "401 未授权"
N-->>C : "登录失败"
end
```

图表来源
- [frontend/lib/auth.ts:13-31](file://frontend/lib/auth.ts#L13-L31)
- [backend/app/api/auth.py:22-37](file://backend/app/api/auth.py#L22-L37)
- [backend/app/services/auth.py:37-69](file://backend/app/services/auth.py#L37-L69)
- [backend/app/models/user.py:11-41](file://backend/app/models/user.py#L11-L41)

章节来源
- [frontend/app/api/auth/[...nextauth]/route.ts](file://frontend/app/api/auth/[...nextauth]/route.ts#L1-L7)
- [frontend/lib/auth.ts:1-56](file://frontend/lib/auth.ts#L1-L56)
- [backend/app/api/auth.py:1-43](file://backend/app/api/auth.py#L1-L43)
- [backend/app/services/auth.py:1-69](file://backend/app/services/auth.py#L1-L69)
- [backend/app/api/deps.py:16-43](file://backend/app/api/deps.py#L16-L43)
- [backend/app/schemas/auth.py:1-34](file://backend/app/schemas/auth.py#L1-L34)
- [backend/app/models/user.py:1-41](file://backend/app/models/user.py#L1-L41)

### 数据库与会话组件分析
- 连接与依赖
  - 异步引擎与会话工厂统一由配置驱动，依赖注入在每个请求内创建会话并自动关闭。
  - 数据库URL来自环境变量，容器化部署通过compose的env_file注入。
- 常见问题
  - 连接字符串错误：确认主机、端口、数据库名、用户名与密码。
  - 权限不足：确保用户具备数据库访问权限。
  - 连接池耗尽：检查并发量与超时设置，必要时调整连接数。
- 诊断步骤
  - 在后端容器内使用psql连接数据库验证连通性。
  - 查看数据库慢查询日志与锁等待情况。

```mermaid
flowchart TD
Start(["请求进入"]) --> GetCfg["读取配置<br/>DATABASE_URL"]
GetCfg --> BuildEngine["创建异步引擎"]
BuildEngine --> Session["创建会话工厂"]
Session --> UseDB["依赖注入获取会话"]
UseDB --> Exec["执行SQL操作"]
Exec --> Close["关闭会话"]
Close --> End(["请求结束"])
```

图表来源
- [backend/app/config.py:7-13](file://backend/app/config.py#L7-L13)
- [backend/app/database.py:6-29](file://backend/app/database.py#L6-L29)

章节来源
- [backend/app/config.py:1-17](file://backend/app/config.py#L1-L17)
- [backend/app/database.py:1-29](file://backend/app/database.py#L1-L29)
- [docker-compose.yml:4-21](file://docker-compose.yml#L4-L21)

### 查询与任务调度组件分析
- 查询管理
  - 支持分页列表、创建、查询、更新、删除；创建时进行权限校验与配额检查。
  - 查询状态与下次执行时间字段用于调度决策。
- 任务调度
  - 每小时扫描一次到期查询，逐条执行并记录日志；异常不影响整体调度。
  - 调度器随应用生命周期启动与关闭。

```mermaid
flowchart TD
Tick["每小时触发"] --> Scan["扫描到期查询"]
Scan --> Found{"找到待执行项？"}
Found -- "否" --> Sleep["等待下次触发"]
Found -- "是" --> Exec["逐条执行查询"]
Exec --> Log["记录执行结果/异常"]
Log --> Sleep
```

图表来源
- [backend/app/workers/scheduler.py:30-90](file://backend/app/workers/scheduler.py#L30-L90)
- [backend/app/models/query.py:11-55](file://backend/app/models/query.py#L11-L55)

章节来源
- [backend/app/api/queries.py:1-86](file://backend/app/api/queries.py#L1-L86)
- [backend/app/models/query.py:1-55](file://backend/app/models/query.py#L1-L55)
- [backend/app/workers/scheduler.py:1-95](file://backend/app/workers/scheduler.py#L1-L95)

## 依赖分析
- 组件耦合
  - 认证路由依赖数据库与JWT服务；依赖注入贯穿API层与服务层。
  - 查询API依赖当前用户上下文与数据库会话。
  - 调度器依赖数据库会话与引用引擎，日志输出用于可观测性。
- 外部依赖
  - 数据库：PostgreSQL（异步驱动）
  - 缓存/队列：Redis
  - 任务调度：APScheduler
  - 浏览览器自动化：Playwright
  - 认证：JWT、BCrypt

```mermaid
graph LR
AUTH["认证路由"] --> DEPS["依赖注入"]
AUTH --> JWT["JWT服务"]
AUTH --> DB["数据库"]
QUERIES["查询路由"] --> DEPS
QUERIES --> DB
SCHED["调度器"] --> DB
SCHED --> CE["引用引擎"]
MAIN["应用入口"] --> AUTH
MAIN --> QUERIES
MAIN --> SCHED
```

图表来源
- [backend/app/main.py:6-42](file://backend/app/main.py#L6-L42)
- [backend/app/api/auth.py:1-43](file://backend/app/api/auth.py#L1-L43)
- [backend/app/api/queries.py:1-86](file://backend/app/api/queries.py#L1-L86)
- [backend/app/workers/scheduler.py:18-95](file://backend/app/workers/scheduler.py#L18-L95)

章节来源
- [backend/requirements.txt:1-35](file://backend/requirements.txt#L1-L35)

## 性能考虑
- 数据库层
  - 使用异步ORM减少阻塞；为高频查询字段建立索引（如查询表的用户ID、状态、下次执行时间）。
  - 控制事务范围，避免长事务；批量写入时合并提交。
- API层
  - 合理设置分页参数上限，避免一次性返回过多数据。
  - 对热点接口增加缓存（如用户信息、平台配置）。
- 调度与并发
  - 调度间隔与任务粒度平衡；单次任务失败不应阻塞其他任务。
  - 监控任务执行时长与积压情况，必要时拆分任务或引入队列。
- 前端
  - 减少不必要的重渲染，使用稳定的数据结构；对长列表使用虚拟滚动。
- 观测性
  - 记录关键链路耗时与错误率；结合日志与指标进行根因分析。

[本节为通用指导，无需列出章节来源]

## 故障排除指南

### 认证相关问题
- 症状：登录返回401未授权
  - 可能原因
    - 邮箱不存在或密码错误
    - JWT密钥不匹配或过期
    - CORS限制导致预检失败
  - 排查步骤
    - 确认用户是否已注册且密码正确
    - 检查后端JWT_SECRET与前端会话策略
    - 核对后端CORS允许源是否包含前端地址
  - 解决方案
    - 修正凭据或重置密码
    - 更新JWT密钥并重启服务
    - 调整CORS配置

- 症状：受保护接口返回401凭据无效
  - 可能原因
    - 令牌缺失或格式错误
    - 令牌解析失败（算法或密钥不一致）
    - 用户被禁用或不存在
  - 排查步骤
    - 检查请求头是否包含Bearer令牌
    - 校验JWT_SECRET与过期时间
    - 确认用户仍存在于数据库且处于激活状态
  - 解决方案
    - 重新登录获取新令牌
    - 修复配置并刷新令牌

章节来源
- [backend/app/api/auth.py:22-37](file://backend/app/api/auth.py#L22-L37)
- [backend/app/services/auth.py:24-34](file://backend/app/services/auth.py#L24-L34)
- [backend/app/api/deps.py:16-43](file://backend/app/api/deps.py#L16-L43)
- [backend/app/main.py:30-36](file://backend/app/main.py#L30-L36)

### 数据库连接问题
- 症状：应用启动时报数据库连接失败
  - 可能原因
    - DATABASE_URL配置错误
    - PostgreSQL未就绪或端口未映射
    - 用户/密码/数据库名不正确
  - 排查步骤
    - 在后端容器内使用psql连接验证
    - 检查compose健康检查与依赖顺序
    - 确认防火墙与网络策略放行
  - 解决方案
    - 修正.env中的DATABASE_URL
    - 等待数据库健康检查通过后再启动后端
    - 修正凭据与数据库名称

- 症状：运行中频繁出现连接超时或连接池耗尽
  - 可能原因
    - 并发过高或事务过长
    - 连接池参数过小
  - 排查步骤
    - 查看数据库连接数与慢查询
    - 检查后端连接池配置
  - 解决方案
    - 优化查询与事务边界
    - 调整连接池大小与超时参数

章节来源
- [backend/app/config.py:7-13](file://backend/app/config.py#L7-L13)
- [backend/app/database.py:6-18](file://backend/app/database.py#L6-L18)
- [docker-compose.yml:46-51](file://docker-compose.yml#L46-L51)

### API调用问题
- 症状：查询列表/详情/创建/更新/删除返回404
  - 可能原因
    - 资源不存在或ID格式错误
    - 权限不足（非本人资源）
  - 排查步骤
    - 校验UUID格式与资源归属
    - 检查当前用户上下文
  - 解决方案
    - 使用正确的用户与ID
    - 确保仅操作本人资源

- 症状：创建查询返回403
  - 可能原因
    - 配额不足或计划限制
  - 排查步骤
    - 检查用户计划与最大查询数
  - 解决方案
    - 升级计划或清理历史任务释放额度

章节来源
- [backend/app/api/queries.py:26-85](file://backend/app/api/queries.py#L26-L85)

### 性能问题
- 症状：查询列表加载缓慢
  - 可能原因
    - 分页参数过大
    - 缺少索引导致排序/过滤慢
  - 排查步骤
    - 降低limit并观察响应时间
    - 分析数据库执行计划
  - 解决方案
    - 合理设置分页上限
    - 为常用查询字段添加索引

- 症状：定时任务执行延迟或堆积
  - 可能原因
    - 单次任务耗时过长
    - 调度器未正确启动或关闭
  - 排查步骤
    - 查看调度器日志与任务耗时
    - 检查后端生命周期钩子
  - 解决方案
    - 将长任务拆分为多个短任务
    - 确保调度器随应用启动/停止

章节来源
- [backend/app/workers/scheduler.py:30-90](file://backend/app/workers/scheduler.py#L30-L90)
- [backend/app/main.py:13-21](file://backend/app/main.py#L13-L21)

### 健康检查与日志分析
- 健康检查
  - 后端健康端点：GET /health
  - compose健康检查：PostgreSQL与Redis分别提供ping/ready检测
- 日志分析
  - 后端日志：关注认证失败、数据库异常、任务执行错误
  - 前端日志：关注NextAuth回调与网络错误
- 性能指标
  - 记录关键API耗时、数据库查询耗时、任务执行耗时
  - 监控连接池使用率与队列长度

章节来源
- [backend/app/main.py:45-47](file://backend/app/main.py#L45-L47)
- [docker-compose.yml:16-34](file://docker-compose.yml#L16-L34)
- [backend/app/workers/scheduler.py:22-90](file://backend/app/workers/scheduler.py#L22-L90)

### 调试技巧与工具使用
- 开发环境调试
  - 启用后端reload与详细日志
  - 使用curl或Postman测试认证与查询接口
  - 在前端浏览器开发者工具查看Network与Console
- 生产环境排查
  - 通过日志聚合与告警系统定位异常
  - 快速回滚至上一版本以隔离变更
  - 使用只读副本进行慢查询分析
- 性能分析
  - 使用数据库性能分析工具识别慢查询
  - 对热点接口进行压力测试与容量评估

[本节为通用指导，无需列出章节来源]

### 常见错误码与含义
- 400 Bad Request
  - 场景：注册时邮箱已存在、密码长度不足
  - 处理：修正输入并重试
- 401 Unauthorized
  - 场景：登录失败、令牌无效、凭据无法验证
  - 处理：重新登录或检查JWT配置
- 403 Forbidden
  - 场景：创建查询时配额不足
  - 处理：升级计划或清理历史任务
- 404 Not Found
  - 场景：查询资源不存在或非本人资源
  - 处理：确认ID与权限

章节来源
- [backend/app/api/auth.py:17-19](file://backend/app/api/auth.py#L17-L19)
- [backend/app/api/queries.py:34-38](file://backend/app/api/queries.py#L34-L38)
- [backend/app/api/queries.py:49-53](file://backend/app/api/queries.py#L49-L53)

### 预防性维护最佳实践
- 定期备份数据库与Redis
- 保持依赖版本更新与安全补丁
- 设置合理的日志保留与轮转策略
- 对关键接口与任务设置告警阈值
- 制定发布前的回归测试清单

[本节为通用指导，无需列出章节来源]

### 紧急故障恢复流程与应急处理
- 立即行动
  - 降级非关键功能，优先保障认证与核心查询
  - 回滚最近一次变更
- 诊断与修复
  - 快速定位日志与指标异常点
  - 修复配置错误、扩容资源或修复慢查询
- 验证与复盘
  - 发布后持续监控关键指标
  - 形成故障报告与改进措施

[本节为通用指导，无需列出章节来源]

## 结论
通过明确的组件职责、完善的健康检查与日志体系、规范的调试与性能分析流程，以及针对认证、数据库、API与调度的专项排障清单，可以显著提升GEO平台的稳定性与可维护性。建议将本指南纳入团队知识库，并定期演练应急流程以提升响应效率。

## 附录
- 快速检查清单
  - 数据库连通性与权限
  - JWT密钥与过期时间
  - CORS允许源配置
  - 调度器状态与日志
  - 健康端点与compose健康检查
- 参考文件
  - 后端入口与路由：[backend/app/main.py:1-48](file://backend/app/main.py#L1-L48)
  - 配置与数据库：[backend/app/config.py:1-17](file://backend/app/config.py#L1-L17)、[backend/app/database.py:1-29](file://backend/app/database.py#L1-L29)
  - 认证与用户模型：[backend/app/api/auth.py:1-43](file://backend/app/api/auth.py#L1-L43)、[backend/app/services/auth.py:1-69](file://backend/app/services/auth.py#L1-L69)、[backend/app/models/user.py:1-41](file://backend/app/models/user.py#L1-L41)
  - 查询与调度：[backend/app/api/queries.py:1-86](file://backend/app/api/queries.py#L1-L86)、[backend/app/models/query.py:1-55](file://backend/app/models/query.py#L1-L55)、[backend/app/workers/scheduler.py:1-95](file://backend/app/workers/scheduler.py#L1-L95)
  - 前端认证：[frontend/lib/auth.ts:1-56](file://frontend/lib/auth.ts#L1-L56)、[frontend/app/api/auth/[...nextauth]/route.ts](file://frontend/app/api/auth/[...nextauth]/route.ts#L1-L7)
  - 编排与依赖：[docker-compose.yml:1-71](file://docker-compose.yml#L1-L71)、[backend/requirements.txt:1-35](file://backend/requirements.txt#L1-L35)