360 lines
13 KiB
Markdown
360 lines
13 KiB
Markdown
# 开发工具
|
||
|
||
<cite>
|
||
**本文档引用的文件**
|
||
- [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)
|
||
</cite>
|
||
|
||
## 目录
|
||
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。
|
||
|
||
```mermaid
|
||
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](file://docker-compose.yml#L1-L71)
|
||
|
||
章节来源
|
||
- [docker-compose.yml:1-71](file://docker-compose.yml#L1-L71)
|
||
- [backend/Dockerfile:1-41](file://backend/Dockerfile#L1-L41)
|
||
- [frontend/Dockerfile:1-15](file://frontend/Dockerfile#L1-L15)
|
||
|
||
## 核心组件
|
||
- 后端服务（FastAPI）
|
||
- 应用入口与生命周期管理、CORS配置、路由注册与健康检查接口
|
||
- 配置加载与外部服务密钥（数据库、Redis、JWT、浏览器路径等）
|
||
- 数据库迁移（Alembic）
|
||
- 异步迁移环境、日志级别与SQLAlchemy连接配置
|
||
- 前端应用（Next.js App Router）
|
||
- API封装、类型配置、ESLint规则与构建配置
|
||
- 定时任务调度器（APScheduler + Playwright）
|
||
- 异步调度、周期性查询检查与执行
|
||
|
||
章节来源
|
||
- [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/alembic/env.py:1-89](file://backend/alembic/env.py#L1-L89)
|
||
- [backend/alembic.ini:1-150](file://backend/alembic.ini#L1-L150)
|
||
- [frontend/lib/api.ts:1-58](file://frontend/lib/api.ts#L1-L58)
|
||
- [frontend/tsconfig.json:1-27](file://frontend/tsconfig.json#L1-L27)
|
||
- [frontend/.eslintrc.json:1-4](file://frontend/.eslintrc.json#L1-L4)
|
||
- [backend/app/workers/scheduler.py:1-95](file://backend/app/workers/scheduler.py#L1-L95)
|
||
|
||
## 架构总览
|
||
下图展示本地开发与容器化运行时的交互关系，以及各组件在容器内的端口映射与依赖顺序。
|
||
|
||
```mermaid
|
||
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](file://docker-compose.yml#L3-L66)
|
||
|
||
章节来源
|
||
- [docker-compose.yml:1-71](file://docker-compose.yml#L1-L71)
|
||
|
||
## 详细组件分析
|
||
|
||
### 后端服务（FastAPI）调试与配置
|
||
- 应用入口与生命周期
|
||
- 使用生命周期钩子初始化模型与启动调度器，并在关闭时优雅停机
|
||
- 注册认证、查询、引用、报告等路由前缀与标签
|
||
- CORS策略
|
||
- 允许来自前端开发地址的跨域请求
|
||
- 健康检查
|
||
- 提供基础健康检查端点用于容器健康探测
|
||
|
||
```mermaid
|
||
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](file://backend/app/main.py#L13-L47)
|
||
- [backend/app/api/auth.py:1-43](file://backend/app/api/auth.py#L1-L43)
|
||
- [frontend/lib/api.ts:1-58](file://frontend/lib/api.ts#L1-L58)
|
||
|
||
章节来源
|
||
- [backend/app/main.py:1-48](file://backend/app/main.py#L1-L48)
|
||
- [backend/app/api/auth.py:1-43](file://backend/app/api/auth.py#L1-L43)
|
||
- [frontend/lib/api.ts:1-58](file://frontend/lib/api.ts#L1-L58)
|
||
|
||
### 数据库迁移（Alembic）流程
|
||
- 运行模式
|
||
- 支持离线与在线两种迁移模式，使用异步引擎连接数据库
|
||
- 日志配置
|
||
- 控制根日志、SQLAlchemy引擎与Alembic的日志级别
|
||
- 数据库URL
|
||
- 默认指向本地或容器内Postgres服务
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
Start(["启动迁移"]) --> Mode{"选择模式"}
|
||
Mode --> |离线| Offline["使用配置URL直接迁移"]
|
||
Mode --> |在线| Online["创建异步引擎并连接"]
|
||
Offline --> Tx["开启事务并执行迁移"]
|
||
Online --> Tx
|
||
Tx --> Done(["完成"])
|
||
```
|
||
|
||
图表来源
|
||
- [backend/alembic/env.py:33-88](file://backend/alembic/env.py#L33-L88)
|
||
- [backend/alembic.ini:115-150](file://backend/alembic.ini#L115-L150)
|
||
|
||
章节来源
|
||
- [backend/alembic/env.py:1-89](file://backend/alembic/env.py#L1-L89)
|
||
- [backend/alembic.ini:1-150](file://backend/alembic.ini#L1-L150)
|
||
|
||
### 前端（Next.js App Router）配置要点
|
||
- TypeScript与路径别名
|
||
- 严格类型检查、Bundler模块解析、路径别名配置
|
||
- ESLint规则
|
||
- 继承Next.js核心Web Vitals与TypeScript规则
|
||
- 构建与开发
|
||
- 开发服务器端口、构建产物与类型生成
|
||
|
||
```mermaid
|
||
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](file://frontend/tsconfig.json#L1-L27)
|
||
- [frontend/.eslintrc.json:1-4](file://frontend/.eslintrc.json#L1-L4)
|
||
- [frontend/next.config.mjs:1-5](file://frontend/next.config.mjs#L1-L5)
|
||
|
||
章节来源
|
||
- [frontend/tsconfig.json:1-27](file://frontend/tsconfig.json#L1-L27)
|
||
- [frontend/.eslintrc.json:1-4](file://frontend/.eslintrc.json#L1-L4)
|
||
- [frontend/next.config.mjs:1-5](file://frontend/next.config.mjs#L1-L5)
|
||
|
||
### 定时任务调度器（APScheduler + Playwright）
|
||
- 调度策略
|
||
- 每小时触发一次检查，筛选到期的活跃查询并交由引文引擎执行
|
||
- 异常处理
|
||
- 单条任务失败不影响整体调度；关闭时优雅停止调度器与浏览器资源
|
||
|
||
```mermaid
|
||
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](file://backend/app/workers/scheduler.py#L25-L95)
|
||
|
||
章节来源
|
||
- [backend/app/workers/scheduler.py:1-95](file://backend/app/workers/scheduler.py#L1-L95)
|
||
|
||
## 依赖分析
|
||
- 后端依赖
|
||
- Web框架、异步数据库、序列化、认证、缓存、任务调度、浏览器自动化、HTTP客户端、环境变量、测试工具
|
||
- 前端依赖
|
||
- Next.js、React、UI库、Tailwind、TypeScript与开发工具链
|
||
|
||
```mermaid
|
||
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](file://backend/requirements.txt#L1-L35)
|
||
- [frontend/package.json:1-40](file://frontend/package.json#L1-L40)
|
||
|
||
章节来源
|
||
- [backend/requirements.txt:1-35](file://backend/requirements.txt#L1-L35)
|
||
- [frontend/package.json:1-40](file://frontend/package.json#L1-L40)
|
||
|
||
## 性能考虑
|
||
- 后端
|
||
- 使用异步ORM与连接池，避免阻塞；合理设置任务调度间隔，避免频繁扫描
|
||
- 浏览器自动化（Playwright）需预装浏览器二进制，减少重复下载开销
|
||
- 前端
|
||
- 开发模式启用快速刷新；生产构建建议启用最小化与Tree-shaking
|
||
- 数据库
|
||
- 迁移日志级别按需调整，避免过度输出影响性能
|
||
|
||
## 故障排查指南
|
||
- 容器健康与端口
|
||
- 确认数据库与缓存容器健康检查通过，端口映射正确
|
||
- 后端与前端容器分别监听8000与3000端口
|
||
- 数据库连接
|
||
- 检查数据库URL与凭据；确认Alembic配置与容器网络可达
|
||
- 调试与日志
|
||
- 后端生命周期钩子负责启动/关闭调度器；查看容器日志定位异常
|
||
- 前端API封装统一处理错误响应，便于定位后端返回的错误详情
|
||
- 定时任务
|
||
- 若查询未按时执行，检查调度器状态与异常日志；确认UTC时间与时区一致性
|
||
|
||
章节来源
|
||
- [docker-compose.yml:16-34](file://docker-compose.yml#L16-L34)
|
||
- [backend/app/main.py:13-21](file://backend/app/main.py#L13-L21)
|
||
- [frontend/lib/api.ts:16-21](file://frontend/lib/api.ts#L16-L21)
|
||
- [backend/app/workers/scheduler.py:42-90](file://backend/app/workers/scheduler.py#L42-L90)
|
||
|
||
## 结论
|
||
通过容器化编排与严格的前后端配置，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](file://backend/requirements.txt#L1-L35)
|
||
- [backend/Dockerfile:28-33](file://backend/Dockerfile#L28-L33)
|
||
- [frontend/Dockerfile:6-7](file://frontend/Dockerfile#L6-L7)
|
||
- [docker-compose.yml:36-66](file://docker-compose.yml#L36-L66) |