Crucix 部署教程：个人开源情报终端

Crucix 是一个自托管的开源情报 (OSINT) 聚合与监控系统。它从 27 个公开数据源并行获取信息，并通过一个炫酷的“Jarvis 风格”仪表盘进行可视化展示。您可以把它想象成您的个人情报分析员，持续关注全球动态，并在重要事件发生时通过 Telegram 或 Discord 向您发出警报。本教程将指导您完成 Crucix 的部署与基本配置。

核心概念与架构

  • 数据来源广泛：涵盖卫星火灾探测、航班追踪、辐射监测、经济指标、冲突数据、制裁名单、社交媒体情绪等 27 个来源。
  • 本地优先，无云依赖：所有数据处理和存储都在您自己的机器上完成 (runs/ 目录)。无需注册云服务，无遥测，无订阅。
  • 自动刷新与变化追踪：系统每 15 分钟（可配置）自动执行一次“信息扫描 (Sweep)”，并行查询所有数据源。它会智能计算与上次扫描的差异 (Delta)，高亮显示新增、升级或降级的事件。
  • 双向通知与交互：您可以将 Crucix 连接到 Telegram 或 Discord，它不仅会推送分级警报，还能响应您通过聊天发送的命令（如 /brief 获取简报，/sweep 手动触发扫描）。

准备工作：硬件与软件要求

  • 操作系统：macOS、Linux 或 Windows (通过 WSL2 或原生支持)。
  • Node.js 环境：需要 Node.js 22 或更高版本。可使用 node --version 检查。推荐使用 nvm 管理 Node 版本。
  • 包管理器：npm (随 Node.js 安装)。
  • 网络：需要能够访问 GitHub 以及各类公开数据源 API 的网络环境。

第一步：获取代码与安装依赖

  1. 克隆项目仓库：

    1
    2
    git clone https://github.com/calesthio/Crucix.git
    cd Crucix

  2. 安装项目依赖：
    项目核心依赖较少，主要是 Express。执行：

    1
    npm install

    (可选) Discord 完整支持：如果您计划使用 Discord 机器人（而非仅用 Webhook），需额外安装 discord.js：

    1
    npm install discord.js

第二步：配置环境变量

  1. 创建配置文件：复制示例环境变量文件。

    1
    cp .env.example .env

  2. 编辑 .env 文件：使用文本编辑器打开 .env，至少配置以下三类免费且关键的 API 密钥以解锁最有价值的数据（注册通常只需 60 秒）：

    • FRED_API_KEY：来自 fred.stlouisfed.org (经济数据)。
    • FIRMS_MAP_KEY：来自 firms.modaps.eosdis.nasa.gov (卫星火灾数据)。
    • EIA_API_KEY：来自 api.eia.gov (能源信息)。
    • 可选：如希望使用 AI 生成交易想法或智能警报，需配置 LLM_PROVIDER 和对应的 LLM_API_KEY（支持 Claude、OpenAI、Gemini 等）。
    • 可选：如希望启用 Telegram 或 Discord 通知，填入对应的 TELEGRAM_BOT_TOKEN / TELEGRAM_CHAT_ID 或 DISCORD_BOT_TOKEN / DISCORD_CHANNEL_ID。

第三步：启动仪表盘

  1. 启动服务：

    1
    npm run dev
    • 此命令会启动服务器，并自动在您的浏览器中打开 http://localhost:3117。

  2. 首次扫描：

    • 仪表盘最初可能显示为空。这是正常的——首次“信息扫描”需要 30-60 秒来并行查询所有 27 个数据源。
    • 请观察终端中的日志输出，等待扫描完成。完成后，仪表盘会自动填充数据。之后系统会每 15 分钟自动刷新。

第四步：使用与配置进阶

  1. 仪表盘操作：
    • 您可以在 3D 地球 和 平面地图 间切换。
    • 使用区域过滤器（如 “Americas”, “Europe”）聚焦特定地区。
    • 点击 “VISUALS LITE” 按钮可降低视觉效果，提升在低性能设备上的运行流畅度。
  2. 配置自动扫描与警报：
    • 扫描间隔可在 .env 中通过 REFRESH_INTERVAL_MINUTES 调整（默认 15 分钟）。
    • 如果配置了 Telegram/Discord，您可以在手机或电脑上通过 /brief、/sweep、/status 等命令与 Crucix 交互，即使不在电脑前也能获取情报。
  3. 手动运行一次扫描 (命令行)：
    • npm run sweep：执行一次完整扫描，并将 JSON 结果输出到终端。
    • npm run brief:save：执行扫描并将结果（带时间戳）保存到 runs/ 目录。

故障排查与常见问题

  • npm run dev 无输出直接退出：
    • 原因：npm 在某些系统（尤其是 Windows PowerShell）上可能吞掉错误信息。
    • 解决：直接使用 Node 运行 node --trace-warnings server.mjs，或运行诊断脚本 node diag.mjs 来精确定位问题（如端口占用、Node 版本不符等）。
  • 端口 3117 已被占用：
    • 关闭其他占用该端口的进程，或在 .env 文件中设置 PORT=3118 更换端口。
  • 某些数据源持续报错：
    • 这是预期行为。未配置 API 密钥的来源会返回错误，但不会影响其他来源的扫描。检查 .env 是否已配置 FRED_API_KEY、FIRMS_MAP_KEY 和 EIA_API_KEY 这三个最重要的免费密钥。
  • Telegram 或 Discord 机器人无响应：
    • 仔细检查 .env 中的 TELEGRAM_BOT_TOKEN、TELEGRAM_CHAT_ID 或 DISCORD_BOT_TOKEN、DISCORD_CHANNEL_ID 是否正确。
    • 对于 Discord，确保已安装 discord.js (npm install discord.js)，并且邀请机器人时授予了 applications.commands 和 Send Messages 权限。

Crucix 是一个强大且独特的开源情报聚合器，它将大量公开数据整合到一个统一的界面中。您无需任何 API 密钥也可以运行，体验部分功能，但配置上三个免费的 API 密钥 (FRED、FIRMS、EIA) 将极大丰富其数据维度。建议从运行 npm run dev 开始，观察一次完整的扫描周期，然后逐步配置通知和 LLM 功能，将其打造成您的专属情报中心。请务必阅读项目 README.md 中关于 “Token / Asset Warning” 的警告。