dnasha/Seraphim

# Seraphim Seraphim 是一个实时的开源情报（OSINT）新闻聚合器，旨在为全球事件提供一个全面且互动的仪表板。该平台从各种来源抓取头条新闻，包括 RSS 源、Telegram 和 Reddit 等社交媒体平台，以及专业的新闻 API。通过采用先进的自然语言处理和自定义启发式引擎，Seraphim 从新闻内容中提取地理位置，并将其在高性能地图上进行可视化。 ## 架构与技术栈 该项目构建于现代且富有弹性的技术栈之上，专为高性能和可扩展性而设计。 ### 前端 用户界面由 Next.js 16 (App Router) 和 React 19 提供支持。它使用 MapLibre GL JS 进行 WebGL 加速的地图渲染。样式通过 Vanilla CSS 和 CSS Modules 进行处理，以确保组件的隔离和样式的可维护性。前端实现了一个持久化实体存储，在地图导航期间保留数据，并将视图状态与 URL 同步以生成可共享的链接。 ### 后端与 API 后端集成在 Next.js App Router 中，提供服务端渲染和 API 路由。它使用 Supabase 进行数据库管理，利用带有 PostGIS 的 PostgreSQL 进行空间查询，并使用 pgvector 实现语义搜索功能。使用 Upstash（本地 L1 和 Redis L2）的混合速率限制策略确保了 API 的稳定性。 ### 数据摄取 一个由 Bun 构建的专用摄取 worker 负责执行抓取和处理 pipeline。它处理来自 RSS 源的数据、基于 Cheerio 的 Telegram 网页抓取，以及与 GNews API 的集成。 ### 地理编码与 NLP Seraphim 具有一个自定义的地理编码引擎，可独立于外部的付费服务运行。它使用 compromise NLP 库以及多遍启发式系统，从非结构化文本中解析位置。使用 Hugging Face Transformers 库 (all-MiniLM-L6-v2) 执行本地向量化，以生成用于语义聚类的 embedding。 ## 项目结构 代码库被组织成多个逻辑目录，以区分整个技术栈中的不同关注点。 * src/app: 包含 Next.js 的页面、布局和 API 路由。 * src/components: 可重用的 UI 组件，包括核心地图引擎及其相关工具。 * src/scraper: 摄取 worker 逻辑、转换器和特定于来源的抓取器。 * src/lib/geocoding: 用于位置提取和地理解析的核心逻辑。 * src/hooks: 用于管理身份验证、新闻数据和地图状态的自定义 React hooks。 * data: 静态地理数据集和已编译的 GeoNames 信息。 * scripts: 维护实用程序、诊断工具和准确度评估器。 ## 安装与设置 要在本地设置该项目，请按照以下步骤操作。 ### 前置条件 * Bun（主要 runtime 和包管理器） * Node.js（如需要，用于辅助工具） * 启用了 PostGIS 和 pgvector 的 Supabase 项目 * Upstash Redis（可选，用于 L2 速率限制） ### 环境变量 在根目录中创建一个 .env 文件，并提供以下变量。 * SUPABASE_URL: 你的 Supabase 项目 URL。 * SUPABASE_SERVICE_ROLE_KEY: 用于管理数据库访问的 Service role key。 * GNEWS_API_KEY: 用于 GNews 集成的可选 API key。 * UPSTASH_REDIS_REST_URL: Upstash Redis 的可选 URL。 * UPSTASH_REDIS_REST_TOKEN: Upstash Redis 的可选 token。 ### 数据初始化 在运行项目之前，你必须编译地理数据。 1. 将所需的 GeoNames 数据集下载到 data 目录中。 2. 运行构建脚本：bun run scripts/build-geodata.mjs。 ## 操作指南 ### 开发 使用以下命令启动开发服务器： bun dev ### 数据摄取 运行抓取器以获取并处理新事件： bun run scrape ### 测试 Seraphim 使用 Vitest 进行单元和集成测试。 * 运行所有测试：bun test * 运行地理编码准确度基准测试：bun run test:accuracy ## 技术深入解析 ### 地理编码策略 地理编码引擎采用分层多遍处理方法，以确保高准确率并将误报降至最低。它根据以下条件确定位置的优先级： 1. 显式元数据（例如，日期线或特定于来源的标签）。 2. 诸如“城市, 国家”的模式或地标名称。 3. 针对 GeoNames 数据的加权字典查找。 4. 基于 NLP 的实体提取，用于上下文解析。 ### 数据 pipeline 与语义聚类 传入的新闻项需经过严格的合并过程。 1. 提取：从原始内容中提取位置和元数据。 2. 向量化：在本地将内容转换为 384 维 embedding。 3. 合并：使用分层相似度模型（全局语义、锚定位置和空间接近度）将新项与现有报道进行比较。 4. 聚类：将相关来源归类到一个“主”故事下，以减少地图上的杂乱。 ### 性能与弹性 * BBox 对齐：地图 API 实现了边界框对齐网格（0.5 到 10 度），以最大化服务端缓存命中率，并防止在轻微平移期间产生冗余查询。 * 故障开放 API：在发生数据库语句超时的情况下，API 会返回空结果或缓存数据，以防止 UI 崩溃。 * 仅限服务端保护：核心地理数据和地理编码逻辑被限制在服务端，以最小化客户端 bundle 大小。 ## 许可证 版权所有 Seraphim 2026。根据项目许可证的条款分发。

标签：ESC4, OSINT, 地图可视化, 数据聚合, 新闻聚合, 测试用例, 自动化攻击