# news-tracker

**Repository Path**: epsos/news-tracker

## Basic Information

- **Project Name**: news-tracker
- **Description**: 新闻追踪系统是一个简化的新闻抓取工具，专注于从RSSHub拉取新闻内容，并通过GitHub Action自动执行，将抓取的数据直接写入项目仓库。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-06
- **Last Updated**: 2026-02-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 新闻追踪系统（News Tracker）项目文档

## 1. 项目概述

新闻追踪系统是一个简化的新闻抓取工具，专注于从RSSHub拉取新闻内容，并通过GitHub Action自动执行，将抓取的数据直接写入项目仓库。

## 2. 技术栈

| 类别 | 技术 | 版本 | 用途 |
|------|------|------|------|
| 编程语言 | JavaScript | - | 核心开发语言 |
| 运行环境 | Node.js | - | 运行时环境 |
| HTTP客户端 | Axios | ^1.6.0 | API请求 |
| RSS解析 | xml2js | ^0.6.2 | RSS订阅源解析 |
| CI/CD | GitHub Actions | - | 自动执行抓取任务 |

## 3. 系统架构

### 3.1 架构图

```
+----------------+    +----------------+    +----------------+
| RSSHub拉取模块 |    | 数据处理模块   |    | 数据存储模块   |
| RSSFetcher     |    | DataProcessor  |    | FileStorage    |
+----------------+    +----------------+    +----------------+
        |                      |                      |
        v                      v                      v
+----------------+    +----------------+    +----------------+
| GitHub Action  |    | 配置管理       |    | 输出文件       |
| workflow.yml   |    | config.json    |    | news.json      |
+----------------+    +----------------+    +----------------+
```

### 3.2 模块说明

| 模块 | 主要职责 | 核心文件 |
|------|----------|----------|
| RSSHub拉取 | 从RSSHub抓取新闻内容 | src/fetcher/RSSFetcher.js |
| 数据处理 | 处理和格式化抓取的新闻数据 | src/processor/DataProcessor.js |
| 数据存储 | 将处理后的数据写入本地文件 | src/storage/FileStorage.js |
| 配置管理 | 管理系统配置 | config.json |
| GitHub Action | 自动执行抓取任务 | .github/workflows/fetch-news.yml |

## 4. 核心功能

### 4.1 RSSHub新闻拉取

- **单源聚焦**：专注于RSSHub订阅源的抓取
- **配置驱动**：通过配置文件定义要抓取的RSSHub端点
- **错误处理**：网络请求失败时的重试和错误日志
- **数据格式化**：将RSS格式转换为统一的JSON格式

### 4.2 GitHub Action自动化

- **定时执行**：可配置的定时抓取任务
- **自动提交**：抓取完成后自动将数据提交到仓库
- **可触发执行**：支持手动触发抓取任务
- **运行日志**：完整的运行日志记录

## 5. 数据格式

### 5.1 输出JSON格式

```json
[
  {
    "title": "新闻标题",
    "link": "新闻链接",
    "description": "新闻描述",
    "pubDate": "发布时间",
    "source": "rsshub-global"
  }
]
```

## 6. 配置文件

系统使用JSON格式的配置文件（`config.json`），支持以下配置项：

```json
{
  "rssHubEndpoints": [
    {
      "name": "rsshub-global",
      "url": "https://rsshub.rssforever.com/global"
    },
    {
      "name": "rsshub-china",
      "url": "https://rsshub.rssforever.com/china"
    },
    {
      "name": "rsshub-tech",
      "url": "https://rsshub.rssforever.com/tech"
    },
    {
      "name": "rsshub-finance",
      "url": "https://rsshub.rssforever.com/finance"
    }
  ],
  "outputPath": "data/news.json",
  "maxItems": 50
}
```

| 配置项 | 类型 | 描述 |
|--------|------|------|
| rssHubEndpoints | Array | RSSHub端点配置列表 |
| rssHubEndpoints[].name | String | 端点名称 |
| rssHubEndpoints[].url | String | 端点URL |
| outputPath | String | 输出文件路径 |
| maxItems | Number | 每个端点最大抓取数量 |

## 7. 系统流程

### 7.1 抓取流程

1. 读取配置文件，获取RSSHub端点列表
2. 遍历端点列表，依次发送HTTP请求获取RSS内容
3. 解析RSS内容，提取新闻信息
4. 格式化新闻数据
5. 合并所有端点的新闻数据
6. 写入JSON文件

### 7.2 GitHub Action工作流

1. 触发条件：定时触发（如每天一次）或手动触发
2. 环境设置：安装Node.js和依赖
3. 执行抓取脚本：`node src/index.js`
4. 检查数据变化：使用git diff检查outputPath文件
5. 提交数据：如果文件有变化，自动提交到仓库

## 8. 核心API

### 8.1 RSSFetcher

| 方法 | 描述 |
|------|------|
| fetch(url, maxItems) | 从指定URL抓取RSS内容，返回指定数量的新闻项 |
| parseRSS(xmlContent) | 解析RSS XML内容，返回结构化的新闻数据 |

### 8.2 DataProcessor

| 方法 | 描述 |
|------|------|
| formatNewsItem(item, source) | 格式化单个新闻项 |
| mergeNewsItems(itemsList) | 合并多个来源的新闻项 |

### 8.3 FileStorage

| 方法 | 描述 |
|------|------|
| writeFile(filePath, data) | 将数据写入指定文件 |

## 9. 项目结构

```
.
├── src/
│   ├── fetcher/
│   │   └── RSSFetcher.js        # RSS抓取器
│   ├── processor/
│   │   └── DataProcessor.js      # 数据处理器
│   ├── storage/
│   │   └── FileStorage.js        # 文件存储
│   └── index.js                  # 应用入口
├── config.json                   # 配置文件
├── data/
│   └── news.json                 # 输出的新闻数据
├── package.json                  # 项目依赖
├── .gitignore                    # Git忽略文件
└── .github/
    └── workflows/
        └── fetch-news.yml        # GitHub Action工作流
```

## 10. GitHub Action配置

### 10.1 工作流文件

```yaml
name: Fetch News from RSSHub

on:
  # 定时触发：每天凌晨1点执行
  schedule:
    - cron: '0 1 * * *'
  # 手动触发
  workflow_dispatch:

jobs:
  fetch-news:
    runs-on: ubuntu-latest
    steps:
      # 1. 检出代码
      - name: Checkout code
        uses: actions/checkout@v3

      # 2. 设置Node.js环境
      - name: Set up Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'

      # 3. 安装依赖
      - name: Install dependencies
        run: npm install

      # 4. 执行抓取脚本
      - name: Fetch news
        run: node src/index.js

      # 5. 检查数据变化
      - name: Check for changes
        id: check_changes
        run: |
          git diff --exit-code ${{ env.OUTPUT_PATH }} || echo "changes=true" >> $GITHUB_OUTPUT
        env:
          OUTPUT_PATH: data/news.json

      # 6. 提交数据到仓库
      - name: Commit and push changes
        if: steps.check_changes.outputs.changes == 'true'
        run: |
          git config --global user.name 'github-actions[bot]'
          git config --global user.email 'github-actions[bot]@users.noreply.github.com'
          git add ${{ env.OUTPUT_PATH }}
          git commit -m 'Update news data from RSSHub'
          git push
        env:
          OUTPUT_PATH: data/news.json
```

## 11. 开发与使用

### 11.1 开发命令

| 命令 | 描述 |
|------|------|
| npm install | 安装依赖 |
| node src/index.js | 本地执行抓取任务 |

### 11.2 本地使用

1. 配置`config.json`文件，添加要抓取的RSSHub端点
2. 执行`node src/index.js`
3. 查看`data/news.json`文件获取抓取结果

### 11.3 GitHub Action使用

1. 将项目推送到GitHub仓库
2. 确保`.github/workflows/fetch-news.yml`文件存在
3. 等待定时触发或手动在GitHub Actions页面触发
4. 查看仓库中的`data/news.json`文件获取最新数据

## 12. 配置说明

### 12.1 RSSHub端点配置

可以根据需要在`config.json`中添加或修改RSSHub端点：

```json
{
  "rssHubEndpoints": [
    {
      "name": "自定义端点名称",
      "url": "RSSHub端点URL"
    }
  ]
}
```

### 12.2 输出路径配置

可以修改`outputPath`配置项，指定新闻数据的输出位置：

```json
{
  "outputPath": "custom/path/to/news.json"
}
```

### 12.3 最大抓取数量配置

可以修改`maxItems`配置项，控制每个端点的最大抓取数量：

```json
{
  "maxItems": 100
}
```

## 13. 扩展性设计

### 13.1 添加新的RSS源

1. 在`config.json`的`rssHubEndpoints`数组中添加新的端点配置
2. 执行抓取脚本或等待GitHub Action自动执行

### 13.2 调整抓取频率

修改GitHub Action工作流文件中的cron表达式，调整抓取频率：

```yaml
# 每小时执行一次
cron: '0 * * * *'
```

## 14. 性能优化

- **请求节流**：避免同时发送过多请求
- **合理配置抓取频率**：根据RSS源的更新频率调整抓取间隔
- **限制最大抓取数量**：避免抓取过多数据导致性能问题

## 15. 安全考虑

- **输入验证**：验证配置文件中的URL格式
- **错误处理**：避免因单个端点故障导致整个抓取任务失败
- **合理的请求频率**：避免对RSSHub服务器造成过大压力

## 15. Docker Compose 部署

### 15.1 环境准备

- Docker 和 Docker Compose 已安装
- Git 已安装
- GitHub Token（可选，用于 GitHub Trending 功能）
- Bilibili Cookie（可选，用于 Bilibili 相关功能）

### 15.2 使用方法

1. **克隆项目**

   ```bash
   git clone <repository-url>
   cd news-tracker
   ```

2. **配置 Docker Compose**

   - 复制示例配置文件

     ```bash
     cp docker-compose.example.yaml docker-compose.yaml
     ```

   - 编辑 `docker-compose.yaml` 文件，填写必要的配置项：
     - `GITHUB_TOKEN`：GitHub Token（可选）
     - `BILIBILI_COOKIE_554649598`：Bilibili Cookie（可选）

3. **启动服务**

   ```bash
   docker-compose up -d --build
   ```

4. **访问服务**

   - RSSHub：`http://localhost:1200`
   - News Tracker：`http://localhost:3000`

### 15.3 服务管理

- **查看服务状态**

  ```bash
  docker-compose ps
  ```

- **查看服务日志**

  ```bash
  docker-compose logs -f
  ```

- **停止服务**

  ```bash
  docker-compose down
  ```

## 16. 总结

本项目是一个简化的新闻追踪系统，专注于从RSSHub拉取新闻内容，并通过GitHub Action自动执行。系统具有以下特点：

- **简单易用**：配置简单，使用方便
- **自动化**：通过GitHub Action实现完全自动化
- **可扩展**：支持添加新的RSS源
- **轻量级**：无数据库依赖，直接写入文件
- **透明**：所有数据直接存储在项目仓库中，便于查看和使用
- **容器化**：支持通过Docker Compose快速部署

该系统可以广泛应用于个人新闻聚合、网站内容更新、数据备份等场景，为用户提供简单可靠的RSS内容获取解决方案。