全球地震大数据分析平台（项目说明）

基于 Python(FastAPI) + MySQL + Vue 3 的前后端分离 Web 应用，实现全球地震数据的采集、清洗、存储、查询、统计、推测、可视化与导出全流程。

---

1. 项目简介

系统以本机 data/ 目录下的 USGS 全球地震历史 CSV（1900 年至今，约 107 万条）为历史基线，结合 USGS FDSN Event API 实现实时增量更新，并提供：

• 用户/管理员双角色：管理员可查看用户操作轨迹（操作日志）、管理用户、监控数据同步；
• 四大核心功能：实时地震分布（USGS API 采集 + 遗漏补全）、选定地区时间频度分布、近 10 年年内频度分布、区域 + 时间范围查询；
• 完整分析链路：多条件组合查询、关键词搜索、统计分析（频度/震级/深度/区域排行）、进阶分析（散点、多区域对比、b 值）、推测分析（频次趋势预测、强震概率、余震序列）、CSV/Excel 导出与分析报告。

2. 技术栈

层	技术
前端	Vue 3 + Vite + Element Plus + ECharts + Leaflet
后端	Python 3.10+ / FastAPI / SQLAlchemy / APScheduler
数据库	MySQL 8（默认）/ PostgreSQL / SQLite（开发演示）
数据源	USGS FDSN Event API（历史批量 + 实时增量）

3. 目录结构

EarthquakeProgram/
├── data/                        # 历史 CSV 基线（77 个文件，约 107 万条）
├── 项目文档.md                  # 详细项目文档（v3.1）
├── README.md                    # 本文档（项目说明）
├── sql/schema.sql               # MySQL 建表脚本（含按年分区）
├── docker-compose.yml           # 一键部署（MySQL + 后端 + 前端）
├── backend/
│   ├── requirements.txt
│   ├── .env.example             # 环境变量示例
│   ├── Dockerfile
│   ├── app/
│   │   ├── main.py              # FastAPI 入口（启动时建表 + 初始化管理员/区域）
│   │   ├── config.py            # 配置（数据库、JWT、USGS、同步间隔）
│   │   ├── database.py          # SQLAlchemy 引擎与会话
│   │   ├── models.py            # 全部数据模型
│   │   ├── schemas.py           # Pydantic 请求/响应模型
│   │   ├── security.py          # bcrypt 密码 + JWT 认证 + 管理员依赖
│   │   ├── middleware.py        # 操作日志中间件（记录所有 /api 请求）
│   │   ├── serializers.py       # 地震事件序列化
│   │   ├── routers/             # 接口分组（见第 6 节）
│   │   └── services/            # 业务服务（USGS 采集/清洗/统计/推测/报告/初始化）
│   └── scripts/
│       ├── import_csv.py        # 历史 CSV 批量导入（清洗 + 去重 + 日志）
│       └── backfill_usgs.py     # USGS 历史批量采集（断点续传 + 失败重试）
└── frontend/
    ├── package.json
    ├── vite.config.js           # 开发代理 /api -> 127.0.0.1:8000
    ├── Dockerfile
    ├── nginx.conf
    └── src/
        ├── api/                 # 按模块封装的接口（auth/earthquakes/stats/prediction/user/admin/export）
        ├── components/          # BaseMap 地图、BaseChart 图表、RegionSelect 区域选择
        ├── views/               # 页面（实时/查询/统计/推测/导出/个人中心/管理端）
        ├── router/              # 路由与权限守卫
        └── store/               # Pinia 用户状态

4. 快速开始

4.1 启动后端

当前项目已配置为连接本机 MySQL 8（backend/.env 中 DATABASE_URL=mysql+pymysql://root:123456@127.0.0.1:3306/earthquake?charset=utf8mb4）， 数据库 earthquake 及表结构（含按年分区）已初始化，约 105 万条历史数据已从 SQLite 迁移入库。 若本机未安装 MySQL，可删除 backend/.env 回退到 SQLite（sqlite:///./earthquake.db，需重新导入数据）。

cd backend
python -m venv .venv
.venv\Scripts\activate        # Windows
source .venv/bin/activate     # Linux/macOS
pip install -r requirements.txt

# 仅首次或切换数据库时需要：初始化 MySQL 表结构 + 导入/迁移历史数据
python scripts/init_mysql.py --password 123456
python scripts/import_csv.py --path ../data
# 或从已有 SQLite 库迁移：python scripts/migrate_sqlite_to_mysql.py --src sqlite:///./earthquake.db

# 启动服务
uvicorn app.main:app --reload --port 8000

启动后访问：

• 接口文档：http://127.0.0.1:8000/docs
• 健康检查：http://127.0.0.1:8000/api/health

默认管理员：admin / admin123（可在 .env 中修改，首次启动自动创建）。

4.2 启动前端

cd frontend
npm install
npm run dev

浏览器访问 http://127.0.0.1:5173（开发服务器已将 /api 代理到 8000 端口）。

4.3 USGS 历史批量采集（可选）

cd backend
python scripts/backfill_usgs.py --start-year 1900 --min-mag 2.5

脚本按年切片拉取，进度写入 backend/checkpoints/backfill.json，中断后再次运行自动从断点继续。

4.4 定时同步（可选）

在 backend/.env 中设置 START_SCHEDULER=true，后端启动后每 SYNC_INTERVAL_MINUTES 分钟自动拉取 USGS 最新事件；也可以在管理端"数据监控"页手动触发增量同步/对账补全。

5. 默认账号

角色	用户名	密码	说明
管理员	admin	admin123	全部功能 + 用户管理 + 操作日志 + 数据监控
普通用户	自行注册	-	查询、统计、推测、导出、收藏、条件保存

6. 接口分组说明

接口按业务模块分组，路径前缀清晰，可在 /docs（Swagger UI）中按标签浏览与调试：

分组	前缀	主要接口	说明
用户认证	/api/auth	register login me password	注册、登录、JWT、修改密码
地震数据	/api/earthquakes	realtime query search {id}	实时分布、多条件查询、关键词搜索、详情
统计分析	/api/stats	frequency mag-distribution depth-distribution region-ranking scatter compare gutenberg-richter	频度、分布、排行、散点、对比、b 值
推测分析	/api/prediction	frequency hazard aftershock results	频次趋势、强震概率、余震序列、推测历史
导出	/api/export	csv excel report	CSV/Excel 导出、HTML 分析报告
区域	/api/regions	列表	预设区域（国家/地震带/矩形）
个人中心	/api/user	favorites filters	收藏区域、保存的筛选条件
管理端	/api/admin	users logs logs/export sync-records clean-logs sync/run stats	用户管理、操作日志（操作轨迹）、数据同步监控

7. 数据库设计

核心表：

• users：用户（角色 user/admin，状态启用/禁用）
• earthquake_events：地震主表（USGS id 主键，时间/震级/经纬度/国家索引，year 冗余字段）
• operation_logs：操作日志（用户轨迹，含模块、动作、参数、IP、耗时、状态）
• sync_records：采集/同步/对账记录（拉取、新增、更新、补全数量）
• clean_logs：清洗日志（输入、去重、缺失、异常、输出）
• saved_filters / user_favorites：筛选条件与区域收藏
• prediction_results：推测结果
• stats_summary：预聚合统计（预留性能优化）

MySQL 生产环境请先执行 sql/schema.sql（含按年 RANGE 分区）；SQLite 开发环境由 SQLAlchemy 自动建表。

8. 数据说明

• 历史基线：data/ 下 77 个 CSV，共 1,072,516 条，覆盖 1900-01-05 至 2026-08-24，震级范围 0.7 ~ 9.5；
• 当前 MySQL earthquake_events 已入库 1,058,054 条（清洗剔除非地震类型与异常记录后），M≥8 强震 100 条；
• 清洗规则：按 USGS id 去重、过滤非地震类型、剔除异常震级/深度/坐标、时间标准化、地点编码统一；
• 国家/地区字段为按地点关键词的简化推断（用于区域排行，仅教学用途）；
• 历史早期记录存在小震漏记，统计结论需注意口径。

9. 常见问题

Q1：MySQL 连接失败？ 确认 MySQL 已启动、.env 中 DATABASE_URL 正确，并已执行 sql/schema.sql 建库（或删除 DATABASE_URL 使用 SQLite 快速体验）。

Q2：实时地震页没有数据？ 需先导入历史数据（python scripts/import_csv.py）或触发一次同步；实时接口拉取的是最近 24 小时记录。

Q3：USGS 接口超时？ 采集脚本已内置指数退避重试；如网络受限，可在管理端"数据监控"页手动触发，或在 .env 中关闭定时同步。

Q4：前端 401 跳转登录？ JWT 过期后前端自动清除本地令牌并跳转登录页，重新登录即可。

10. 科学边界声明

系统的推测功能（频次趋势、强震概率、余震序列）均基于历史统计模型，不构成地震预报或减灾决策依据，页面中已显著标注。如需进一步扩展，可接入深度学习时间序列模型（LSTM）、ETAS 模型或专业地学数据。

11. PyCharm 使用指南

1. 打开项目：File → Open → 选择 D:\EarthquakeProgram 根目录；
2. 配置后端解释器：Settings → Project → Python Interpreter → Add Interpreter → 选择已装好依赖的运行时 C:\Users\Lenovo\.cache\codex-runtimes\codex-primary-runtime\dependencies\python\python.exe， 或新建 venv 后 pip install -r backend/requirements.txt；
3. 运行后端：直接右键 backend/app/main.py → Run（已内置 uvicorn 入口，默认 8000 端口）；
4. 运行前端：Settings → Languages & Frameworks → Node.js 指向 D:\Node.js\node.exe，然后在终端执行 cd frontend + npm run dev，或配置 npm run 启动项；
5. 访问：前端 http://127.0.0.1:5173，接口文档 http://127.0.0.1:8000/docs；
6. 查看数据：PyCharm 内置 Database 工具连接 MySQL（127.0.0.1:3306，root/123456，库 earthquake）可直接浏览表数据。