从零开始部署 World Monitor 实时全球情报仪表板

目录

• 快速开始 (5分钟)
• 完整部署指南
• 生产环境部署
• 常见问题

---

快速开始 (5分钟)

如果你只想快速体验项目，按照以下步骤：

1. 克隆项目

git clone https://github.com/koala73/worldmonitor.git
cd worldmonitor

2. 安装依赖

npm install

3. 启动开发服务器

npm run dev

4. 访问应用

打开浏览器访问 http://localhost:3000

✅ 完成！基础功能无需任何 API 密钥即可使用。

---

完整部署指南

前置条件

在开始之前，请确保你的系统满足以下要求：

软件	版本要求	验证命令
Node.js	>= 18.0.0	node --version
npm	>= 9.0.0	npm --version
Git	>= 2.30.0	git --version

安装 Node.js

Windows/macOS:

1. 访问 https://nodejs.org/
2. 下载 LTS 版本 (推荐 20.x)
3. 运行安装程序

Linux (Ubuntu/Debian):

curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

使用 nvm (推荐):

# 安装 nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# 安装 Node.js 20
nvm install 20
nvm use 20
nvm alias default 20

---

步骤 1: 获取代码

方式 A: 克隆 GitHub 仓库 (推荐)

# 克隆项目
git clone https://github.com/koala73/worldmonitor.git

# 进入项目目录
cd worldmonitor

# 查看当前分支
git branch

方式 B: 下载 ZIP 压缩包

1. 访问 https://github.com/koala73/worldmonitor
2. 点击绿色 “Code” 按钮
3. 选择 “Download ZIP”
4. 解压到本地目录
5. 在终端中进入解压后的目录

---

步骤 2: 安装依赖

# 安装项目依赖
npm install

预期输出：

added 936 packages, and audited 937 packages in 2m

10 vulnerabilities (1 low, 3 moderate, 6 high)

To address issues that do not require attention, run:
  npm audit fix

💡 提示：安装时间取决于网络速度，通常需要 2-5 分钟。如果遇到错误，请检查 Node.js 版本。

---

步骤 3: 配置环境变量

3.1 创建环境文件

# 复制示例文件
cp .env.example .env.local

Windows:

copy .env.example .env.local

3.2 基础配置 (可选)

编辑 .env.local 文件：

# 打开文件进行编辑
# Windows: 使用记事本或 VS Code
# macOS/Linux: 使用 nano 或 vim

最少配置 (基础功能可用):

# 这个文件可以为空，基础功能无需 API 密钥
# 如需高级功能，取消注释并填写对应密钥

# AI 摘要功能 (可选)
# GROQ_API_KEY=your_key_here

# 股票数据 (可选)
# FINNHUB_API_KEY=your_key_here

3.3 完整配置 (推荐)

如需启用所有功能，参考 API 密钥配置 部分。

---

步骤 4: 启动开发服务器

4.1 标准模式

npm run dev

成功标志：

  VITE v6.4.1  ready in 1643 ms

  ➜  Local:   http://localhost:3000/
  ➜  Network: use --host to expose
  ➜  press h + enter to show help

4.2 访问应用

打开浏览器，访问：

• 本地地址: http://localhost:3000
• 网络地址: http://你的IP:3000 (使用 --host 参数)

4.3 不同变体

命令	变体	说明
npm run dev	Full	综合情报 (默认)
npm run dev:tech	Tech	科技/AI/网络安全
npm run dev:finance	Finance	金融/市场数据
npm run dev:happy	Happy	正面新闻

切换变体示例：

# 停止当前服务器 (Ctrl+C)
# 启动 Tech 变体
npm run dev:tech

---

步骤 5: 验证部署

5.1 功能检查清单

打开应用后，检查以下功能：

• 地图正常加载 (3D 地球或平面地图)
• 新闻面板显示内容
• 可以切换不同的数据图层
• 可以切换语言 (右上角)
• 设置面板可以打开

5.2 浏览器控制台检查

按 F12 打开开发者工具：

1. Console 标签: 检查是否有红色错误
2. Network 标签: 检查 API 请求是否正常
3. Application 标签: 检查 Service Worker (PWA)

5.3 运行测试

# 类型检查
npm run typecheck

# 数据测试
npm run test:data

# RSS 源测试
npm run test:feeds

---

生产环境部署

方案 A: Vercel 部署 (推荐)

Vercel 是项目原生支持的平台，部署最简单。

1. 准备工作

1. 注册 Vercel 账号
2. 将代码推送到 GitHub/GitLab/Bitbucket

2. 导入项目

1. 登录 Vercel Dashboard
2. 点击 “Add New Project”
3. 选择你的 Git 仓库
4. 点击 “Import”

3. 配置项目

Build & Output Settings:

• Framework Preset: Vite
• Build Command: npm run build
• Output Directory: dist

Environment Variables:
点击 “Environment Variables” 添加：

GROQ_API_KEY=your_groq_key
UPSTASH_REDIS_REST_URL=your_redis_url
UPSTASH_REDIS_REST_TOKEN=your_redis_token
# ... 其他密钥

4. 部署

点击 “Deploy” 按钮，等待 2-3 分钟。

部署成功后：

• 获得 .vercel.app 域名
• 每次推送代码自动重新部署
• 支持预览部署 (Pull Request)

---

方案 B: 自托管部署

1. 构建生产版本

# 构建完整版
npm run build

# 或构建特定变体
npm run build:tech
npm run build:finance

2. 检查构建输出

# 查看构建产物
ls -la dist/

# 应该包含:
# - index.html
# - assets/ (JS, CSS, 图片)

3. 部署到 Web 服务器

Nginx 示例:

server {
    listen 80;
    server_name your-domain.com;
    root /var/www/worldmonitor/dist;
    index index.html;

    # Gzip 压缩
    gzip on;
    gzip_types text/plain text/css application/json application/javascript;

    # SPA 路由支持
    location / {
        try_files $uri $uri/ /index.html;
    }
}

Apache 示例:

<VirtualHost *:80>
    ServerName your-domain.com
    DocumentRoot /var/www/worldmonitor/dist
    
    <Directory /var/www/worldmonitor/dist>
        Options -Indexes +FollowSymLinks
        AllowOverride All
        Require all granted
    </Directory>
</VirtualHost>

.htaccess 文件 (放在 dist 目录):

<IfModule mod_rewrite.c>
  RewriteEngine On
  RewriteBase /
  RewriteRule ^index\.html$ - [L]
  RewriteCond %{REQUEST_FILENAME} !-f
  RewriteCond %{REQUEST_FILENAME} !-d
  RewriteRule . /index.html [L]
</IfModule>

---

API 密钥配置

获取免费 API 密钥

1. Groq (AI 摘要)

1. 访问 https://console.groq.com
2. 注册账号
3. 创建 API Key
4. 免费额度: 14,400 请求/天

# 添加到 .env.local
GROQ_API_KEY=groq_xxxxxxxxxxxxxxxx

2. Upstash Redis (缓存)

1. 访问 https://upstash.com
2. 创建免费数据库
3. 获取 REST URL 和 Token

UPSTASH_REDIS_REST_URL=https://your-db.upstash.io
UPSTASH_REDIS_REST_TOKEN=your_token_here

3. Finnhub (股票数据)

1. 访问 https://finnhub.io
2. 注册获取免费 API Key
3. 免费额度: 60 请求/分钟

FINNHUB_API_KEY=cxxxxxxxxxxxxxxxx

完整环境变量模板

# ===== AI 服务 =====
GROQ_API_KEY=your_groq_key_here
OPENROUTER_API_KEY=your_openrouter_key_here

# ===== 缓存服务 =====
UPSTASH_REDIS_REST_URL=https://your-url.upstash.io
UPSTASH_REDIS_REST_TOKEN=your_token_here

# ===== 金融数据 =====
FINNHUB_API_KEY=your_finnhub_key_here
EIA_API_KEY=your_eia_key_here
FRED_API_KEY=your_fred_key_here

# ===== 冲突数据 =====
ACLED_ACCESS_TOKEN=your_acled_token_here
UCDP_ACCESS_TOKEN=your_ucdp_token_here

# ===== 网络监测 =====
CLOUDFLARE_API_TOKEN=your_cloudflare_token_here
NASA_FIRMS_API_KEY=your_nasa_firms_key_here
URLHAUS_AUTH_KEY=your_urlhaus_key_here
OTX_API_KEY=your_otx_key_here

# ===== 追踪服务 =====
WINGBITS_API_KEY=your_wingbits_key_here
AISSTREAM_API_KEY=your_aisstream_key_here
OPENSKY_CLIENT_ID=your_opensky_id
OPENSKY_CLIENT_SECRET=your_opensky_secret

# ===== World Monitor =====
WORLDMONITOR_API_KEY=your_wm_api_key_here

---

桌面端部署

环境准备

Windows

1. 安装 Rust:

   winget install Rustlang.Rustup
   

2. 安装 Visual Studio Build Tools:

   • 下载: https://visualstudio.microsoft.com/downloads/
   • 选择 “使用 C++ 的桌面开发” 工作负载

3. 安装 WebView2 Runtime (通常已预装)

macOS

# 安装 Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env

# 安装 Xcode 命令行工具
xcode-select --install

Linux (Ubuntu)

# 安装依赖
sudo apt update
sudo apt install -y libwebkit2gtk-4.1-dev build-essential curl wget file libssl-dev libgtk-3-dev libayatana-appindicator3-dev librsvg2-dev

# 安装 Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env

开发模式

# 启动桌面开发模式
npm run desktop:dev

构建桌面应用

# 构建完整版桌面应用
npm run desktop:build:full

# 构建 Tech 变体
npm run desktop:build:tech

打包分发

# Windows
npm run desktop:package:windows:full

# macOS
npm run desktop:package:macos:full

输出目录: src-tauri/target/release/bundle/

---

常见问题

Q1: 安装依赖时卡住/超时

解决方案:

# 使用淘宝镜像
npm config set registry https://registry.npmmirror.com
npm install

# 或使用 yarn
yarn install

Q2: 启动时报错 “Cannot find module”

解决方案:

# 清除缓存重新安装
rm -rf node_modules package-lock.json
npm cache clean --force
npm install

Q3: 地图不显示/空白

检查项:

1. 检查浏览器控制台是否有错误
2. 确认网络连接正常
3. 尝试清除浏览器缓存
4. 检查是否有广告拦截器阻止了地图资源

Q4: AI 摘要功能不工作

原因: 未配置 GROQ_API_KEY 或 OpenRouter API Key

解决方案:

1. 注册 Groq 获取免费 API Key
2. 添加到 .env.local
3. 重启开发服务器

降级方案: 应用会自动使用浏览器本地模型 (较慢但可用)

Q5: 如何修改默认端口

# 使用其他端口
npm run dev -- --port 3001

# 或修改 vite.config.ts
server: {
  port: 3001
}

Q6: 如何在局域网内访问

# 暴露网络接口
npm run dev -- --host

# 或使用
npx vite --host

Q7: 构建失败，内存不足

# Windows
set NODE_OPTIONS=--max-old-space-size=4096
npm run build

# macOS/Linux
export NODE_OPTIONS="--max-old-space-size=4096"
npm run build

Q8: 如何更新到最新版本

# 拉取最新代码
git pull origin main

# 重新安装依赖
rm -rf node_modules package-lock.json
npm install

# 重启开发服务器
npm run dev

---

下一步

部署成功后，你可以：

1. 探索功能

   • 切换不同的数据图层
   • 尝试 AI 摘要功能
   • 测试多语言支持

2. 自定义配置

   • 添加自己的 RSS 源
   • 配置本地 LLM (Ollama)
   • 修改地图样式

3. 贡献代码

   • 阅读 CONTRIBUTING.md
   • 提交 Issue 或 PR

4. 生产部署

   • 配置自定义域名
   • 启用 HTTPS
   • 设置监控告警

---

获取帮助

• 📖 完整文档: DEPLOYMENT.md
• 🐛 问题反馈: https://github.com/koala73/worldmonitor/issues
• 💬 社区讨论: GitHub Discussions
• 🌐 在线演示: https://worldmonitor.app

---

祝你部署顺利！ 🚀