20 KiB

Raw Permalink Blame History

故障排除与FAQ

**本文引用的文件** - [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)

简介

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

项目结构

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

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"]

图表来源

章节来源

核心组件

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

章节来源

架构总览

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

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 : "后台定时扫描到期查询并执行"

图表来源

详细组件分析

认证组件分析

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

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

图表来源

章节来源

数据库与会话组件分析

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

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

图表来源

章节来源

查询与任务调度组件分析

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

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

图表来源

章节来源

依赖分析

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

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

图表来源

章节来源

backend/requirements.txt:1-35

性能考虑

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

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

故障排除指南

认证相关问题

症状：登录返回401未授权
- 可能原因
  - 邮箱不存在或密码错误
  - JWT密钥不匹配或过期
  - CORS限制导致预检失败
- 排查步骤
  - 确认用户是否已注册且密码正确
  - 检查后端JWT_SECRET与前端会话策略
  - 核对后端CORS允许源是否包含前端地址
- 解决方案
  - 修正凭据或重置密码
  - 更新JWT密钥并重启服务
  - 调整CORS配置
症状：受保护接口返回401凭据无效
- 可能原因
  - 令牌缺失或格式错误
  - 令牌解析失败（算法或密钥不一致）
  - 用户被禁用或不存在
- 排查步骤
  - 检查请求头是否包含Bearer令牌
  - 校验JWT_SECRET与过期时间
  - 确认用户仍存在于数据库且处于激活状态
- 解决方案
  - 重新登录获取新令牌
  - 修复配置并刷新令牌

章节来源

数据库连接问题

症状：应用启动时报数据库连接失败
- 可能原因
  - DATABASE_URL配置错误
  - PostgreSQL未就绪或端口未映射
  - 用户/密码/数据库名不正确
- 排查步骤
  - 在后端容器内使用psql连接验证
  - 检查compose健康检查与依赖顺序
  - 确认防火墙与网络策略放行
- 解决方案
  - 修正.env中的DATABASE_URL
  - 等待数据库健康检查通过后再启动后端
  - 修正凭据与数据库名称
症状：运行中频繁出现连接超时或连接池耗尽
- 可能原因
  - 并发过高或事务过长
  - 连接池参数过小
- 排查步骤
  - 查看数据库连接数与慢查询
  - 检查后端连接池配置
- 解决方案
  - 优化查询与事务边界
  - 调整连接池大小与超时参数

章节来源

API调用问题

症状：查询列表/详情/创建/更新/删除返回404
- 可能原因
  - 资源不存在或ID格式错误
  - 权限不足（非本人资源）
- 排查步骤
  - 校验UUID格式与资源归属
  - 检查当前用户上下文
- 解决方案
  - 使用正确的用户与ID
  - 确保仅操作本人资源
症状：创建查询返回403
- 可能原因
  - 配额不足或计划限制
- 排查步骤
  - 检查用户计划与最大查询数
- 解决方案
  - 升级计划或清理历史任务释放额度

章节来源

backend/app/api/queries.py:26-85

性能问题

症状：查询列表加载缓慢
- 可能原因
  - 分页参数过大
  - 缺少索引导致排序/过滤慢
- 排查步骤
  - 降低limit并观察响应时间
  - 分析数据库执行计划
- 解决方案
  - 合理设置分页上限
  - 为常用查询字段添加索引
症状：定时任务执行延迟或堆积
- 可能原因
  - 单次任务耗时过长
  - 调度器未正确启动或关闭
- 排查步骤
  - 查看调度器日志与任务耗时
  - 检查后端生命周期钩子
- 解决方案
  - 将长任务拆分为多个短任务
  - 确保调度器随应用启动/停止

章节来源

健康检查与日志分析

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

章节来源

调试技巧与工具使用

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

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

常见错误码与含义

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

章节来源

预防性维护最佳实践

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

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

紧急故障恢复流程与应急处理

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

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

结论

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

附录

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

20 KiB Raw Permalink Blame History Unescape Escape

故障排除与FAQ

目录

简介

项目结构

核心组件

架构总览

详细组件分析

认证组件分析

数据库与会话组件分析

查询与任务调度组件分析

依赖分析

性能考虑

故障排除指南

认证相关问题

数据库连接问题

API调用问题

性能问题

健康检查与日志分析

调试技巧与工具使用

常见错误码与含义

预防性维护最佳实践

紧急故障恢复流程与应急处理

结论

附录

20 KiB

Raw Permalink Blame History