GitHub Trending Projects Platform

一个现代化的 GitHub 热门项目追踪平台，集成 AI 智能分析、自动化文档生成和项目知识库管理功能。

✨ 功能特性

• 🔥 GitHub Trending 热门项目追踪（多语言、多时间范围）
• 🧠 智能缓存：SQLite 持久化，支持手动更新
• 📥 批量下载 README 并自动跳过已存在文件
• 🤖 基于 OpenAI 兼容 API 自动生成项目介绍
• 📚 项目知识库：标签、收藏、备注、搜索
• 🎨 现代化响应式界面，支持深色 / 浅色主题
• 📡 SSE 实时日志展示文档生成进度
• ⚙️ 管理员设置页：配置 AI API 和 GitHub Token

🛠️ 技术栈

层	技术
前端	React 18、Vite、React Router、Axios
后端	Node.js 24、Express、node:sqlite
文档生成	Python 3、OpenAI SDK、httpx
数据存储	SQLite（Node 内置 node:sqlite）
部署	Docker、Docker Compose、Nginx

注意：项目使用 Node.js 内置 node:sqlite，要求 Node.js >= 22.5。

📁 项目结构

.
├── server/                    # Express 后端
│   ├── src/
│   │   ├── config/            # 环境变量配置
│   │   ├── db/                # SQLite 初始化与迁移
│   │   ├── repositories/      # 数据访问层
│   │   ├── routes/            # HTTP 路由
│   │   ├── services/          # 业务逻辑
│   │   ├── middleware/        # 中间件
│   │   └── utils/             # 工具函数
│   ├── app.js
│   └── index.js
├── frontend/                  # React 前端
│   └── src/
│       ├── pages/             # 页面组件
│       ├── components/        # 通用组件
│       ├── contexts/          # 全局状态
│       ├── hooks/             # 自定义 Hooks
│       ├── services/          # API 请求
│       └── utils/             # 工具函数
├── doc_generator/             # Python 文档生成器
├── data/                      # SQLite 数据库目录（运行时生成）
├── reports/                   # 下载的 README 文件
├── introductions/             # 生成的项目介绍
└── tests/                     # 后端测试

🚀 本地运行

环境要求

• Node.js >= 22.5
• npm
• Python >= 3.8（仅文档生成功能需要）

1. 安装依赖

# 后端 / 根目录
npm install

# 前端
cd frontend
npm install
cd ..

2. 配置环境变量

复制根目录 .env.example 为 .env，并填写必要配置：

cp .env.example .env

文档生成器配置：

cp doc_generator/.env.example doc_generator/.env

3. 启动后端

npm start

后端默认运行在 http://localhost:3000，健康检查地址为 http://localhost:3000/health。

4. 启动前端（开发模式）

cd frontend
npm run dev

前端开发服务器默认运行在 http://localhost:5173。

🐳 Docker 运行

# 使用 docker-compose 启动前后端
docker-compose up -d --build

• 前端：http://localhost
• 后端 API：http://localhost:3000
• 健康检查：http://localhost:3000/health

⚙️ 环境变量

变量	说明	默认值
PORT	后端端口	3000
NODE_ENV	运行环境	development
GITHUB_TOKEN	GitHub Token，提高 API 速率限制	空
ADMIN_TOKEN	管理员令牌，保护设置页	空
ALLOWED_ORIGINS	允许的 CORS 来源，逗号分隔	http://localhost:5173,http://localhost:3000
DB_PATH	SQLite 数据库路径	data/github_crawler.db
RATE_LIMIT_WINDOW_MS	限流窗口（毫秒）	900000
RATE_LIMIT_MAX_REQUESTS	窗口内最大请求数	100
PROXY_HOST / PROXY_PORT / PROXY_PROTOCOL	代理配置	空
HTTP_PROXY	标准 HTTP 代理	空
NO_PROXY	设为 true 禁用代理	空
PYTHON_BIN	Python 可执行文件路径	python3

📡 主要 API

热门项目

• GET /api/trending?since=daily|weekly|monthly|all&language=javascript
• GET /api/github/trending：兼容旧路由
• POST /api/scheduler/fetch：手动触发缓存更新
• GET /api/scheduler/status：获取调度器状态
• GET /api/scheduler/logs：SSE 实时日志

项目介绍

• GET /api/introductions
• GET /api/introductions/:id

标签 / 收藏 / 备注

• GET /api/project-status
• PUT /api/project-status/:id
• POST /api/project-status/tags
• PUT /api/project-status/tags/:tagId
• DELETE /api/project-status/tags/:tagId
• POST /api/project-status/favorites/:id
• DELETE /api/project-status/favorites/:id
• GET /api/project-status/notes/:projectId
• PUT /api/project-status/notes/:projectId
• DELETE /api/project-status/notes/:projectId

文档生成器

• POST /api/doc-generator/run
• POST /api/doc-generator/stop
• GET /api/doc-generator/status
• GET /api/doc-generator/logs：SSE 实时日志

设置（需要 ADMIN_TOKEN）

• GET /api/settings/doc-generator
• POST /api/settings/doc-generator
• POST /api/settings/test-connection

系统

• GET /health
• GET /ready

🧪 测试与代码质量

# lint
npm run lint

# 测试
npm test

# 前端构建
npm run build

🤝 贡献

请阅读 CONTRIBUTING.md。

📄 许可证

MIT