# hot-spot

**Repository Path**: neusu/hot-spot

## Basic Information

- **Project Name**: hot-spot
- **Description**: 时事热点舆情工作台是一款面向新闻聚合、热点事件分析与舆情监测的开源 Web 应用，采用 Vue 3、FastAPI、SQLAlchemy 和 MySQL 构建，支持多数据源采集、新闻搜索、热点事件分析、关键词监控、收藏标签、团队协作及可选 AI 摘要等功能。项目遵循 MIT License，不包含任何 API Key、密钥、用户数据或生产环境配置，欢迎开发者使用、反馈与贡献。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-28
- **Last Updated**: 2026-08-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 时事热点舆情工作台

时事热点舆情工作台是一款面向新闻聚合、热点事件分析和舆情监测的开源 Web 应用。后端使用 FastAPI 和 SQLAlchemy，前端使用 Vue 3 和 Vite，数据存储使用 MySQL。

## 功能

- 聚合新闻和热点榜单，支持多数据源扩展。
- 新闻搜索、筛选、收藏、标签管理以及 Markdown/Excel 导出。
- 热点事件聚合、趋势分析、风险评估和事件生命周期管理。
- 关键词监控、定时采集、站内通知和 WebSocket 推送。
- 可选的 AI 摘要、新闻分析、日报、周报和自定义简报。
- 用户认证、密码找回、团队协作、事件标注和任务管理。
- 管理后台、PWA、浏览器 Push 和邮件通知等可选能力。

## 技术栈

| 层级 | 技术 |
| --- | --- |
| 前端 | Vue 3、Vite 8、Pinia、Vue Router、Naive UI、Axios、Chart.js |
| 后端 | Python、FastAPI、SQLAlchemy、APScheduler |
| 数据库 | MySQL 5.7 或更高版本 |
| AI | OpenAI 兼容 API（可选） |
| 部署 | Uvicorn、Nginx、Windows/Linux 进程管理器 |

## 目录结构

```text
.
├── backend/
│   ├── api/                  API 路由
│   ├── models/               SQLAlchemy 数据模型
│   ├── monitor/              关键词监控
│   ├── notifier/             WebSocket 通知
│   ├── scheduler/            定时任务
│   ├── scrapers/             新闻与热点数据源
│   ├── summarizer/           AI 摘要服务
│   ├── tests/                后端测试
│   ├── init_db.sql           全量数据库初始化脚本
│   ├── requirements.txt      运行依赖
│   └── requirements-dev.txt  开发与测试依赖
├── frontend/
│   ├── public/               PWA 与静态资源
│   ├── src/                  页面、组件、状态和 API 封装
│   ├── package.json          前端脚本与依赖
│   └── package-lock.json     前端依赖锁文件
├── nginx.conf.example        Nginx 配置示例
├── run.py                    后端开发启动脚本
├── .env.example              环境变量示例
└── LICENSE                   MIT 许可证
```

## 环境要求

- Python 3.11 或更高版本。
- Node.js 20.19+ 或 22.12+，以及 npm。
- MySQL 5.7 或更高版本。
- PowerShell（Windows）或 Bash（Linux/macOS）。
- 能够访问已配置新闻数据源及可选外部服务的网络环境。

## 快速开始

以下命令默认在项目根目录执行。项目不包含任何数据库、密钥、用户上传文件或构建产物。

### 1. 获取源码

```powershell
git clone https://github.com/luckysus/hot-spot.git
Set-Location hot-spot
```

Gitee 镜像地址：`https://gitee.com/neusu/hot-spot.git`。

### 2. 创建配置文件

```powershell
Copy-Item .env.example .env
```

编辑 `.env`，至少设置数据库连接信息和 JWT 签名密钥。可以使用以下命令生成随机 JWT 密钥：

```powershell
python -c "import secrets; print(secrets.token_urlsafe(32))"
```

将命令输出填入 `JWT_SECRET_KEY`。生产环境不得使用示例值、空值或公开到仓库的固定密钥。

### 3. 初始化 MySQL

使用具有创建数据库和表权限的 MySQL 账号执行全量初始化脚本：

```powershell
mysql --default-character-set=utf8mb4 -u root -p -e "source backend/init_db.sql"
```

脚本会创建 `news_hotspot` 数据库、全部应用表、索引、外键和默认会员套餐。它面向全新部署，使用 `IF NOT EXISTS` 保证重复执行不会删除数据；它不会自动升级旧版本数据库，也不会创建 MySQL 登录账号或应用管理员账号。

生产环境建议使用独立的应用数据库账号，并在 `.env` 中填写对应的 `DB_USER` 和 `DB_PASSWORD`。例如在 MySQL 客户端中执行：

```sql
CREATE USER 'news_hotspot'@'127.0.0.1' IDENTIFIED BY '<strong-password>';
GRANT ALL PRIVILEGES ON news_hotspot.* TO 'news_hotspot'@'127.0.0.1';
FLUSH PRIVILEGES;
```

### 4. 安装后端并启动

```powershell
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -r backend/requirements.txt
python run.py
```

后端默认监听 `http://127.0.0.1:2106`，健康检查接口为 `http://127.0.0.1:2106/api/health`。

### 5. 安装前端并启动

在新的 PowerShell 窗口中执行：

```powershell
Set-Location frontend
npm ci
npm run dev
```

前端开发服务器默认监听 `http://127.0.0.1:5173`，并将 `/api`、`/ws` 和 `/avatars` 请求代理到后端。

## 可选服务配置

完整变量说明和示例值见 `.env.example`。

| 配置组 | 主要变量 | 未配置时的影响 |
| --- | --- | --- |
| 数据库 | `DB_*` | 应用无法启动 |
| 认证 | `JWT_*` | 登录令牌无法正常签发 |
| AI 服务 | `AI_*` | AI 摘要和分析降级为本地结果，不影响基础新闻功能 |
| 热点数据源 | `UAPI_*`、`JUHE_*` | 对应数据源不可用，其他数据源仍可使用 |
| 邮件 | `EMAIL_SMTP_*`、`EMAIL_SENDER_*` | 注册邮箱验证、密码找回和邮件通知不可用 |
| 浏览器 Push | `WEB_PUSH_VAPID_*` | 浏览器推送不可用 |
| 前端地址 | `FRONTEND_URL` | 邮件中的前端链接需要手动调整 |
| 运行参数 | `MAX_ITEMS_PER_SOURCE`、`ALLOW_MOCK_PAYMENT` | 控制采集数量和模拟支付开关 |

AI 服务未配置密钥时，后端会保留新闻原文并使用本地降级逻辑，不会因为缺少 AI 密钥而在启动或基础功能上崩溃。生产环境必须保持 `ALLOW_MOCK_PAYMENT=false`。

注册和密码找回需要可用的 SMTP 配置。只使用新闻浏览、搜索和本地功能时，可以暂不配置 AI、邮件、Push 及部分第三方数据源。

## 首个管理员账号

初始化脚本不会写入默认管理员或默认密码。完成注册后，使用有权限的数据库账号将指定用户提升为管理员：

```sql
USE news_hotspot;
UPDATE users SET is_admin = 1 WHERE username = '<your-username>';
```

请替换 `<your-username>`，并确认数据库中不存在不必要的管理员账号。

## 测试与构建

后端测试环境：

```powershell
python -m pip install -r backend/requirements-dev.txt
python -m pytest backend/tests -q
```

前端测试和生产构建：

```powershell
Set-Location frontend
npm ci
npm test
npm run build
```

前端依赖使用 `package-lock.json` 锁定版本。可以使用以下命令检查依赖安全状态：

```powershell
npm audit
npm audit --omit=dev
```

## 生产部署

生产环境建议在部署主机上构建前端，然后使用 Nginx 提供静态文件并反向代理 API 和 WebSocket。项目提供 `nginx.conf.example` 作为配置起点，部署时必须根据实际域名、证书、目录和后端端口调整配置。

典型流程如下：

1. 安装 Python、Node.js、MySQL 及项目运行依赖。
2. 在服务器上创建 `.env`，填写数据库、JWT 和实际启用服务的配置。
3. 执行 `backend/init_db.sql` 初始化全新数据库。
4. 在服务器的 `frontend/` 目录执行 `npm ci` 和 `npm run build`。
5. 使用进程管理器启动 `uvicorn backend.main:app --host 127.0.0.1 --port 2106`。
6. 配置并检查 Nginx 的静态文件、API 和 WebSocket 代理。
7. 验证健康检查、登录、新闻查询、热点采集和通知功能。

本公开版本只提供全量新库初始化，不包含旧版本数据库迁移脚本。已有生产数据请在升级前单独完成备份和迁移评估，不要直接对生产库重复初始化。

## 安全与数据责任

- `.env`、数据库密码、JWT 密钥、AI/API 密钥、SMTP 密码和 Web Push 私钥不得提交到 Git。
- 项目不内置第三方服务凭据，也不包含用户数据库、上传文件或运行日志。
- AI 生成内容和自动风险分析仅供参考，发布或用于业务决策前应进行人工核验。
- 使用第三方数据源时，应遵守服务条款、许可要求和适用法律法规。
- 发现安全问题时，请不要在公开 Issue 中发布密钥或敏感数据。

## 贡献

欢迎通过 Issue 反馈问题、提出功能建议或提交 Pull Request。提交代码前请运行后端测试、前端测试和生产构建，并在 Pull Request 中说明验证方式。

## 许可证

本项目采用 MIT License，详见 `LICENSE` 文件。