LatestNews -中文资讯聚合实时阅读开源项目-开源项目

评论
24 views

bruceblink/LatestNews 开源仓库全面系统介绍

仓库地址：https://github.com/bruceblink/LatestNews LatestNews 是一套前后端同仓、轻量化中文资讯聚合实时阅读开源项目，主打干净无干扰的新闻浏览体验，支持多端部署、PWA、用户配置云同步、数据源健康监控，基于 React + Vite + Nitro 全栈 TypeScript 开发，开源协议 MIT。

一、项目定位与核心简介

1. 项目初衷

打造轻量、干净、可私有化部署的中文实时资讯聚合工具，解决通用资讯工具广告多、数据源杂乱、无法自定义布局、多端配置不互通的痛点。项目早期参考 ourongxing/newsnow 思路，在此基础上重构架构、完善数据源治理与多端适配能力。

2. 核心聚焦四大方向

  1. 多渠道中文热点新闻稳定实时抓取聚合
  2. GitHub 账号登录，用户首页布局云端同步
  3. 移动端优先 PWA 完整离线使用体验
  4. 全链路数据源健康监控、抓取质量治理

3. 版本迭代时间线（关键节点）

  • 2025-09-21：项目初始化提交，基础脚手架搭建
  • 2025-12：完善 Docker 部署支持，修复环境变量读取问题
  • 2026-03：优化 Vite 打包体积、修复 Cloudflare Pages 构建报错
  • 2026-04：完善主题切换、Git 提交规范、系统架构文档
  • 2026-05：发布正式 v0.5.1 版本
  • 2026-06：完善开发计划、Docker 可复现构建、依赖更新

二、产品完整功能能力

（一）资讯聚合核心功能

  1. 多源实时抓取：自动拉取聚合各类中文资讯、热点 RSS 源，内置解析器处理 XML/HTML 新闻页面
  2. 自定义栏目布局：拖拽调整首页板块，支持一键重置布局，个性化资讯视图
  3. 抓取限流与缓存：服务端缓存、抓取频率限制，减少源站压力，加速页面访问
  4. 强制刷新机制：登录用户可手动触发全量刷新，同步状态实时展示、失败自动重试

（二）用户云同步系统

  1. GitHub OAuth 登录，基于 JWT 鉴权
  2. 布局配置云端持久化，多设备打开自动同步个性化栏目
  3. 同步状态可视化提示，网络异常重试逻辑

（三）数据源运维治理（特色功能）

  1. 数据源健康面板：统一查看所有资讯源运行状态
  2. 异常源告警、抓取错误日志展示、单源独立探测诊断
  3. 抓取鉴权加固、元数据同步安全校验，防止越权访问

（四）PWA 移动端能力

  1. 完整 PWA 标准实现，可添加到手机桌面
  2. 离线缓存阅读、应用版本更新弹窗提示
  3. 移动端适配阅读布局，轻量化无冗余 DOM

（五）配套工程能力

  • 深色/浅色主题一键切换
  • 完整单元测试、类型校验、代码格式化规范
  • 多渠道一键部署：本地、Docker、Cloudflare Pages + D1 数据库

三、完整技术栈分层拆解

1. 前端（Client / src）

  • 框架：React 18 + Vite 7
  • 路由/请求：TanStack Router、TanStack Query（数据缓存）
  • 状态管理：Jotai
  • 样式：UnoCSS（原子化 CSS，轻量化打包）
  • PWA：pwa.config.ts 配置离线缓存、桌面图标

2. 服务端（Server / Nitro 后端）

  • 运行时：Nitro + H3（轻量 Node 服务框架）
  • 数据库：better-sqlite3 / Cloudflare D1
  • ORM：db0
  • 爬虫解析：Cheerio（HTML解析）、ofetch（网络请求）、fast-xml-parser（RSS解析）
  • 鉴权：JWT 实现 GitHub 登录与用户会话

3. 前后端共享层（shared）

统一存放共享 TypeScript 类型、常量、数据源定义，避免前后端类型不一致，降低联调成本。

4. 工程化 & 质量保障

  • 语言：全量 TypeScript
  • 代码规范：ESLint + Prettier
  • 提交规范：Commitlint + Conventional Commits
  • 单元测试：Vitest
  • CI/CD：GitHub Actions，支持 Docker Hub 自动打包发布

四、仓库目录结构详解

LatestNews/
├── .github/workflows    # CI/CD 流水线，Docker 自动构建推送
├── .vscode              # VSCode 开发配置
├── patches              # 第三方依赖补丁，解决 vite-plugin-nitro 兼容性
├── public               # 静态资源、PWA图标、logo
├── screenshots          # 项目截图（已移除赞赏码）
├── scripts              # 资源脚本：图标生成、favicon 下载、数据源工具
├── server               # Nitro 后端核心：API、爬虫、数据库、鉴权中间件
├── shared               # 前后端共享类型、常量、数据源配置
├── src                  # React 前端页面、组件、hooks、全局状态
├── test                 # Vitest 单元测试用例
├── tools                # 辅助工程工具
├── architecture.md      # News TimeStream Platform 系统架构设计文档
├── DEVELOPMENT_PLAN.md  # 中长期开发路线规划
├── Dockerfile / docker-compose.yml  # 容器部署配置
├── example.env.server   # 服务端环境变量模板
├── example.wrangler.toml # Cloudflare Pages/D1 部署配置
├── nitro.config.ts      # Nitro 后端配置
├── vite.config.ts       # Vite 构建优化（分包、减小主包体积）
├── package.json         # 项目依赖、脚本命令
└── README.md            # 官方使用文档

五、环境要求与本地开发流程

1. 基础环境

  • Node.js ≥ 22
  • pnpm ≥ 10

2. 本地开发启动

# 安装依赖
pnpm install
# 启动开发服务
pnpm dev

默认自动执行资源预处理脚本；如需登录/云同步，必须配置服务端环境变量。

3. 环境变量说明（example.env.server）

变量 作用
TZ=Asia/Shanghai 统一时区为东八区
VITE_APP_TITLE 网站浏览器标题
VITE_API_URL 后端同步接口地址
JWT_SECRET 登录鉴权密钥（无则关闭登录功能）
ENABLE_CACHE 是否开启服务端抓取缓存
INIT_TABLE=true 首次运行自动初始化数据库表
PRODUCTHUNT_API_TOKEN 第三方扩展接口密钥（可选）

未配置 VITE_API_URL + JWT_SECRET 时，项目可正常运行，但隐藏登录、云端同步功能。

4. 常用工程脚本

pnpm dev         # 本地开发调试
pnpm build       # 生产打包
pnpm brand:assets# 批量生成 favicon、PWA 图标、分享图
pnpm preview     # 本地预览打包产物
pnpm check       # 全量校验：lint + 类型检查 + 单元测试
pnpm typecheck   # 单独 TS 类型校验
pnpm test        # 执行 Vitest 测试用例
pnpm deploy      # 一键部署 Cloudflare Pages

六、三种部署方案完整说明

方案1：Docker 容器部署（私有化自建推荐）

仓库内置完整容器配置，支持单机快速部署：

# 生产部署
docker compose -f docker-compose.yml up -d
# 本地开发联调容器
docker compose -f docker-compose.local.yml up

修复点：早期版本存在容器无法读取环境变量问题，2025-12 已更新 Dockerfile 修复；构建支持可复现安装，保证环境一致性。

方案2：Cloudflare Pages 云端免费部署

  1. 构建命令：pnpm run build
  2. 输出目录：dist/output/public
  3. 如需持久化用户数据、缓存：
  4. 创建 Cloudflare D1 数据库
  5. 修改 example.wrangler.toml，填入 database_id、database_name
  6. 重新执行部署脚本

方案3：纯本地静态模式

不配置后端 API 环境变量，仅前端浏览新闻，无登录同步、数据持久化能力，适合临时体验。

七、开发路线规划（DEVELOPMENT_PLAN.md）

项目长期迭代三大主线： 1. 多端同步体验优化：完善同步状态提示、弱网重试、跨端配置一致性 2. 数据源治理体系升级：提升异常源自动诊断、批量运维、抓取排障效率 3. 阅读体验强化：移动端离线缓存、PWA 更新优化、扩展更多高质量资讯分类

八、贡献规范与开源协议

  1. 提交规范：强制 Conventional Commits（feat/fix/chore/docs/refactor 等前缀），由 commitlint 校验
  2. 贡献流程：先提 Issue 沟通需求，再提交 PR，提交前执行 pnpm check 通过校验
  3. License：MIT 开源协议，可商用、二次修改分发，保留原版权声明

九、项目优势总结

  1. 轻量化：Vite 分包优化，主包体积精简，页面加载速度快；UnoCSS 减少样式冗余
  2. 全栈同仓：前后端一套代码库，类型共享，开发、部署成本低
  3. 私有化友好：Docker 一键部署，支持本地 SQLite 或 Cloudflare D1，数据自主可控
  4. 运维友好：内置数据源监控面板，方便排查抓取失败、资讯源失效问题
  5. 移动端完善：标准 PWA，离线可用，无需客户端 APP
  6. 可扩展：模块化数据源解析层，可自行新增自定义资讯 RSS 源

十、适用人群

  1. 个人开发者：自建无广告私人新闻阅读器
  2. 技术爱好者：学习 Nitro + React 全栈同仓、PWA、爬虫、JWT 鉴权实战项目
  3. 小型团队：内部资讯聚合平台，统一聚合行业媒体、行业热点 RSS

LatestNews-Github