geo/.qoder/repowiki/zh/content/开发指南/开发工具.md

开发工具

**本文档引用的文件** - [docker-compose.yml](file://docker-compose.yml) - [backend/Dockerfile](file://backend/Dockerfile) - [frontend/Dockerfile](file://frontend/Dockerfile) - [backend/requirements.txt](file://backend/requirements.txt) - [frontend/package.json](file://frontend/package.json) - [backend/app/main.py](file://backend/app/main.py) - [backend/app/config.py](file://backend/app/config.py) - [backend/alembic.ini](file://backend/alembic.ini) - [backend/alembic/env.py](file://backend/alembic/env.py) - [backend/app/api/auth.py](file://backend/app/api/auth.py) - [backend/app/workers/scheduler.py](file://backend/app/workers/scheduler.py) - [frontend/lib/api.ts](file://frontend/lib/api.ts) - [frontend/tsconfig.json](file://frontend/tsconfig.json) - [frontend/.eslintrc.json](file://frontend/.eslintrc.json) - [frontend/next.config.mjs](file://frontend/next.config.mjs)

目录

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

简介

本文件面向GEO项目的开发者，提供从IDE配置、调试工具、开发辅助工具到命令行与脚本使用的完整指南。内容覆盖：

• VS Code配置与推荐插件（Python、TypeScript/Next.js）
• 断点调试、日志分析与性能分析方法
• API测试、数据库管理与Docker容器管理
• 命令行工具与脚本使用
• 开发环境优化与常见问题排查

项目结构

GEO采用前后端分离的多容器架构，通过Docker Compose编排数据库、缓存、后端服务与前端开发服务器。后端基于FastAPI，前端基于Next.js（App Router），数据库迁移使用Alembic。

graph TB
subgraph "本地开发环境"
VSCode["VS Code 开发环境"]
Postman["API 测试工具"]
DBTools["数据库管理工具"]
DockerCLI["Docker CLI"]
end
subgraph "容器编排"
DC["docker-compose.yml"]
DB["Postgres 容器"]
Redis["Redis 容器"]
BE["后端容器"]
FE["前端容器"]
end
VSCode --> DC
Postman --> BE
DBTools --> DB
DockerCLI --> DC
DC --> DB
DC --> Redis
DC --> BE
DC --> FE

图表来源

• docker-compose.yml:1-71

章节来源

• docker-compose.yml:1-71
• backend/Dockerfile:1-41
• frontend/Dockerfile:1-15

核心组件

• 后端服务（FastAPI）
  • 应用入口与生命周期管理、CORS配置、路由注册与健康检查接口
  • 配置加载与外部服务密钥（数据库、Redis、JWT、浏览器路径等）
• 数据库迁移（Alembic）
  • 异步迁移环境、日志级别与SQLAlchemy连接配置
• 前端应用（Next.js App Router）
  • API封装、类型配置、ESLint规则与构建配置
• 定时任务调度器（APScheduler + Playwright）
  • 异步调度、周期性查询检查与执行

章节来源

• backend/app/main.py:1-48
• backend/app/config.py:1-17
• backend/alembic/env.py:1-89
• backend/alembic.ini:1-150
• frontend/lib/api.ts:1-58
• frontend/tsconfig.json:1-27
• frontend/.eslintrc.json:1-4
• backend/app/workers/scheduler.py:1-95

架构总览

下图展示本地开发与容器化运行时的交互关系，以及各组件在容器内的端口映射与依赖顺序。

graph TB
Dev["开发者主机"]
subgraph "Docker Compose 编排"
subgraph "服务"
DB["db:5432 → POSTGRES"]
RD["redis:6379 → 缓存"]
BE["backend:8000 → FastAPI"]
FE["frontend:3000 → Next.js dev"]
end
end
Dev --> |"浏览器访问"| FE
Dev --> |"API 请求"| BE
BE --> |"数据库/缓存"| DB
BE --> |"缓存/队列"| RD
FE --> |"调用后端 API"| BE

图表来源

• docker-compose.yml:3-66

章节来源

• docker-compose.yml:1-71

详细组件分析

后端服务（FastAPI）调试与配置

• 应用入口与生命周期
  • 使用生命周期钩子初始化模型与启动调度器，并在关闭时优雅停机
  • 注册认证、查询、引用、报告等路由前缀与标签
• CORS策略
  • 允许来自前端开发地址的跨域请求
• 健康检查
  • 提供基础健康检查端点用于容器健康探测

sequenceDiagram
participant Client as "客户端"
participant FE as "前端(3000)"
participant API as "后端(8000)"
participant DB as "数据库"
participant Cache as "缓存"
Client->>FE : "打开应用"
FE->>API : "发起登录/查询/报告等请求"
API->>DB : "读写数据(异步ORM)"
API->>Cache : "读写缓存(可选)"
API-->>FE : "返回JSON响应"
FE-->>Client : "渲染界面"

图表来源

• backend/app/main.py:13-47
• backend/app/api/auth.py:1-43
• frontend/lib/api.ts:1-58

章节来源

• backend/app/main.py:1-48
• backend/app/api/auth.py:1-43
• frontend/lib/api.ts:1-58

数据库迁移（Alembic）流程

• 运行模式
  • 支持离线与在线两种迁移模式，使用异步引擎连接数据库
• 日志配置
  • 控制根日志、SQLAlchemy引擎与Alembic的日志级别
• 数据库URL
  • 默认指向本地或容器内Postgres服务

flowchart TD
Start(["启动迁移"]) --> Mode{"选择模式"}
Mode --> |离线| Offline["使用配置URL直接迁移"]
Mode --> |在线| Online["创建异步引擎并连接"]
Offline --> Tx["开启事务并执行迁移"]
Online --> Tx
Tx --> Done(["完成"])

图表来源

• backend/alembic/env.py:33-88
• backend/alembic.ini:115-150

章节来源

• backend/alembic/env.py:1-89
• backend/alembic.ini:1-150

前端（Next.js App Router）配置要点

• TypeScript与路径别名
  • 严格类型检查、Bundler模块解析、路径别名配置
• ESLint规则
  • 继承Next.js核心Web Vitals与TypeScript规则
• 构建与开发
  • 开发服务器端口、构建产物与类型生成

flowchart TD
TS["tsconfig.json<br/>严格类型/路径别名"] --> ESL[".eslintrc.json<br/>继承Next规则"]
ESL --> Build["next.config.mjs<br/>默认配置"]
Build --> Dev["npm run dev<br/>3000端口"]

图表来源

• frontend/tsconfig.json:1-27
• frontend/.eslintrc.json:1-4
• frontend/next.config.mjs:1-5

章节来源

• frontend/tsconfig.json:1-27
• frontend/.eslintrc.json:1-4
• frontend/next.config.mjs:1-5

定时任务调度器（APScheduler + Playwright）

• 调度策略
  • 每小时触发一次检查，筛选到期的活跃查询并交由引文引擎执行
• 异常处理
  • 单条任务失败不影响整体调度；关闭时优雅停止调度器与浏览器资源

classDiagram
class QueryScheduler {
+start()
+check_and_execute_queries()
+shutdown()
-_run_check()
-_execute_single_query(query, db)
}
class CitationEngine {
+execute_query(query, db)
+close()
}
QueryScheduler --> CitationEngine : "执行查询"

图表来源

• backend/app/workers/scheduler.py:25-95

章节来源

• backend/app/workers/scheduler.py:1-95

依赖分析

• 后端依赖
  • Web框架、异步数据库、序列化、认证、缓存、任务调度、浏览器自动化、HTTP客户端、环境变量、测试工具
• 前端依赖
  • Next.js、React、UI库、Tailwind、TypeScript与开发工具链

graph LR
BE["后端应用"] --> Req["requirements.txt"]
FE["前端应用"] --> Pkg["package.json"]
Req --> FastAPI["FastAPI"]
Req --> SQLA["SQLAlchemy/AsyncPG/Alembic"]
Req --> RedisDep["Redis/APScheduler"]
Req --> PW["Playwright"]
Req --> HTTPX["HTTPX/HTTPX"]
Req --> Test["pytest/pytest-asyncio/aiosqlite"]
Pkg --> Next["Next.js"]
Pkg --> UI["@radix-ui/*"]
Pkg --> Tail["Tailwind/Recharts"]
Pkg --> TSDev["TypeScript/ESLint"]

图表来源

• backend/requirements.txt:1-35
• frontend/package.json:1-40

章节来源

• backend/requirements.txt:1-35
• frontend/package.json:1-40

性能考虑

• 后端
  • 使用异步ORM与连接池，避免阻塞；合理设置任务调度间隔，避免频繁扫描
  • 浏览器自动化（Playwright）需预装浏览器二进制，减少重复下载开销
• 前端
  • 开发模式启用快速刷新；生产构建建议启用最小化与Tree-shaking
• 数据库
  • 迁移日志级别按需调整，避免过度输出影响性能

故障排查指南

• 容器健康与端口
  • 确认数据库与缓存容器健康检查通过，端口映射正确
  • 后端与前端容器分别监听8000与3000端口
• 数据库连接
  • 检查数据库URL与凭据；确认Alembic配置与容器网络可达
• 调试与日志
  • 后端生命周期钩子负责启动/关闭调度器；查看容器日志定位异常
  • 前端API封装统一处理错误响应，便于定位后端返回的错误详情
• 定时任务
  • 若查询未按时执行，检查调度器状态与异常日志；确认UTC时间与时区一致性

章节来源

• docker-compose.yml:16-34
• backend/app/main.py:13-21
• frontend/lib/api.ts:16-21
• backend/app/workers/scheduler.py:42-90

结论

通过容器化编排与严格的前后端配置，GEO提供了可复现的开发环境。配合本文档提供的IDE配置、调试与运维工具清单，开发者可以高效地进行功能迭代与问题定位。

附录

IDE配置与推荐插件（VS Code）

• Python相关
  • 扩展：Python、Pylance、Black、isort、pytest
  • 设置：启用Pylance类型检查、自动格式化、导入排序
• TypeScript/Next.js相关
  • 扩展：ESLint、TypeScript Importer、Tailwind CSS IntelliSense
  • 设置：启用严格模式、路径别名、TS/TSX语法高亮
• Docker
  • 扩展：Docker、Kubernetes（可选）
  • 用途：可视化容器状态、日志查看、镜像构建与部署

[本节为通用实践建议，不直接分析具体源码文件]

调试工具使用方法

• 断点调试
  • 后端：在FastAPI路由或业务逻辑处设置断点，结合容器调试或本地调试
  • 前端：在API封装函数与页面逻辑处设置断点，观察请求/响应
• 日志分析
  • 后端：关注调度器与API层日志；容器日志中过滤关键字定位异常
  • 数据库：调整Alembic日志级别以获取更详细的迁移信息
• 性能分析
  • 后端：对慢查询与任务执行耗时进行采样；评估浏览器自动化并发
  • 前端：利用Next.js开发服务器热重载与性能面板

[本节为通用实践建议，不直接分析具体源码文件]

开发辅助工具

• API测试
  • 工具：Postman、Insomnia、curl
  • 建议：使用环境变量管理不同环境的API基础URL与令牌
• 数据库管理
  • 工具：pgAdmin、DBeaver、DataGrip
  • 建议：使用Alembic进行版本化迁移，避免手写DDL
• Docker容器管理
  • 工具：Docker Desktop、Lens（可选）
  • 建议：使用Compose一键拉起所有服务，查看容器日志与健康状态

[本节为通用实践建议，不直接分析具体源码文件]

命令行工具与脚本使用

• 后端
  • 安装依赖：pip install -r requirements.txt
  • 运行开发服务器：uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload
  • 数据库迁移：alembic revision --autogenerate，alembic upgrade head
• 前端
  • 安装依赖：npm ci
  • 开发：npm run dev（3000端口）
  • 构建：npm run build（14.x）
• Docker
  • 构建与启动：docker-compose up --build
  • 查看日志：docker-compose logs -f 服务名
  • 进入容器：docker-compose exec 服务名 sh

章节来源

• backend/requirements.txt:1-35
• backend/Dockerfile:28-33
• frontend/Dockerfile:6-7
• docker-compose.yml:36-66