需要自托管实时全球情报仪表盘时，用 World…

适用于需要将 World Monitor 作为实时全球情报仪表盘进行自托管、部署或集成到项目中的场景。

适用场景

解决思路

1. 安装与启动：执行 `git clone https://github.com/koala73/worldmonitor.git`、`cd worldmonitor`、`npm install`、`npm run dev`，打开 http://localhost:5173；基础运行无需环境变量，默认使用本地 Ollama。
2. 运行站点变体：使用 `npm run dev:tech`、`npm run dev:finance`、`npm run dev:commodity`、`npm run dev:happy` 启动对应 tech、finance、commodity、happy 变体。
3. 生产构建与校验：执行 `npm run typecheck` 做 TypeScript 校验，`npm run build:full` 构建所有变体，`npm run build` 构建默认 world 变体。
4. 按目录组织开发：在 `src/components/` 放 UI 组件，`src/feeds/` 放 435+ RSS/API feed 定义，`src/layers/` 放 deck.gl 地图图层，`src/ai/` 放 AI 合成管线，`src/signals/` 放跨流关联引擎，`src/finance/` 放 92 交易所市场数据，`src/variants/` 放 world/tech/finance/commodity/happy 站点变体，`src/protos/` 放 92 个 proto 与 22 个服务，`api/` 放 60+ Vercel Edge Functions，`src-tauri/` 放 Tauri 2 桌面应用，`docs/` 放文档，`vite.config.ts` 为 Vite 配置。
5. 配置环境变量：创建 `.env.local` 且不要提交 secrets；可设置 `VITE_OLLAMA_BASE_URL=http://localhost:11434`、`VITE_GROQ_API_KEY=$GROQ_API_KEY`、`VITE_OPENROUTER_API_KEY=$OPENROUTER_API_KEY`、`UPSTASH_REDIS_REST_URL=$UPSTASH_REDIS_REST_URL`、`UPSTASH_REDIS_REST_TOKEN=$UPSTASH_REDIS_REST_TOKEN`、`VITE_MAPTILER_API_KEY=$MAPTILER_API_KEY`、`VITE_SITE_VARIANT=world`（world | tech | finance | commodity | happy）。
6. 定义 feed 分类：在 `src/feeds/categories.ts` 按 `FeedCategory` 类型声明 15 个分类：geopolitics、military、economics、technology、climate、energy、health、finance、commodities、infrastructure、cyber、space、diplomacy、disasters、society。
7. 访问国家情报指数：从 `./signals/country-intelligence` 引入 `CountryIntelligence`，`new CountryIntelligence()` 后调用 `getCountryScore('UA')` 获取 composite、12 类 signals、trend、updatedAt；用 `subscribe('UA', callback)` 订阅实时更新。
8. 执行 AI 合成：从 `./ai/synthesizer` 引入 `AISynthesizer`，配置 provider 为 `ollama`、`groq` 或 `openrouter`，设置 model 与 baseUrl；调用 `synth.synthesize({ items, category, region, maxTokens, language })`，读取 `brief.summary`、`brief.signals`、`brief.confidence`。
9. 检测跨流信号关联：从 `./signals/correlator` 引入 `SignalCorrelator`，`new SignalCorrelator()` 后调用 `detectConvergence({ streams: ['military','economic','disaster','escalation'], timeWindow: '6h', threshold: 0.7, region: 'Middle East' })`，检查 `detected`、`signals`、`probability`、`events`。
10. 集成 3D 地球：在 `src/components/globe/GlobeView.ts` 引入 `Globe`，用 `Globe()(container)` 初始化并设置 `globeImageUrl('//unpkg.com/three-globe/example/img/earth-dark.jpg')`、`backgroundImageUrl('//unpkg.com/three-globe/example/img/night-sky.png')`；加载国家风险数据后设置 `polygonsData`、`polygonCapColor` 使用 `riskToColor`、`polygonSideColor`、`polygonLabel`；`riskToColor` 按 >0.8、>0.6、>0.4、>0.2 分级。
11. 集成 WebGL 平面地图：在 `src/components/map/DeckMap.ts` 引入 `Deck`、`ScatterplotLayer`、`ArcLayer`、`HeatmapLayer`、`maplibre-gl`；初始化 `maplibregl.Map` 使用 Carto dark-matter-gl-style、center [0,20]、zoom 2；初始化 `Deck` 使用 canvas deck-canvas、initialViewState、controller；添加 events `ScatterplotLayer`（含 getPosition、getRadius、getFillColor、pickable）与 supply-chains `ArcLayer`（含 getSourcePosition、getTargetPosition、getSourceColor、getTargetColor、getWidth）。
12. 使用 Finance Radar：从 `./finance/radar` 引入 `FinanceRadar`，`new FinanceRadar()` 后调用 `getMarketComposite()` 获取 7 信号 market composite；调用 `getExchange('NYSE')`、`getCrypto(['BTC','ETH','SOL'])`、`getCommodities(['GOLD','OIL','WHEAT'])` 获取对应市场数据。
13. 处理语言与 RTL：从 `./i18n` 引入 `setLanguage`、`getAvailableLanguages`，可用语言包括 en、ar、zh、ru、fr、es、de、ja、ko、pt、hi、fa、tr、pl、uk、nl、sv、he、it、vi、id；调用 `await setLanguage('ar')`、`'he'`、`'fa'` 自动触发 RTL；用 `new FeedManager({ language: 'ar', includeEnglish: true })` 配置 feed 语言过滤。
14. 使用 Protocol Buffers API 契约：在 `src/protos` 使用 92 个 proto、22 个服务；从 `./protos/generated/intelligence_grpc_web_pb` 引入 `IntelligenceServiceClient`，从 `./protos/generated/intelligence_pb` 引入 `CountryRequest`；用 `VITE_API_BASE_URL` 或 `http://localhost:8080` 创建 client；设置 countryCode、timeRange、signalTypes；调用 `getCountryIntelligence(request, {}, callback)`，成功后 `response.toObject()`。
15. 编写 Vercel Edge Function：在 `api/feeds/aggregate.ts` 使用 `export const config = { runtime: 'edge' }`；从 query 解构 category、region、limit；构造 `feeds:${category}:${region}:${limit}` 缓存键；先 `getCachedData`，命中直接 `res.json`；未命中调用 `aggregateFeeds`，再 `setCachedData(cacheKey, items, { ttl: 300 })`，返回 `res.json(items)`。
16. 打包桌面应用 Tauri 2：执行 `cargo install tauri-cli`，开发用 `npm run tauri:dev`，构建用 `npm run tauri:build`，输出 .exe、.dmg/.app、.AppImage；在 `src-tauri/src/main.rs` 用 `#[tauri::command] async fn fetch_intelligence(country: String)` 定义 IPC 命令，并在 `tauri::Builder` 中 `invoke_handler(tauri::generate_handler![fetch_intelligence])`。
17. Docker 自托管：执行 `docker build -t worldmonitor .`；`docker run -p 3000:3000 -e VITE_SITE_VARIANT=world -e UPSTASH_REDIS_REST_URL=$UPSTASH_REDIS_REST_URL -e UPSTASH_REDIS_REST_TOKEN=$UPSTASH_REDIS_REST_TOKEN worldmonitor`；或用 `docker compose up -d`；`docker-compose.yml` 中 app 服务 build .、ports 3000:3000、environment VITE_SITE_VARIANT=world 与 REDIS_URL=redis://redis:6379、depends_on redis，redis 服务 image redis:7-alpine、volumes redis_data:/data。
18. 部署到 Vercel：执行 `npm i -g vercel`，`vercel --prod`；用 `vercel env add GROQ_API_KEY production`、`vercel env add UPSTASH_REDIS_REST_URL production`、`vercel env add UPSTASH_REDIS_REST_TOKEN production` 添加生产环境变量。
19. 注册自定义 Feed：从 `./src/feeds/registry` 引入 `FeedRegistry`，调用 `FeedRegistry.register({ id, name, url, category, region, language, weight, refreshInterval, parser })`；weight 为 0-1，refreshInterval 单位秒，parser 为 rss2、atom 或 json。
20. 注册自定义地图图层：从 `./src/layers/registry` 引入 `LayerRegistry`，从 `@deck.gl/layers` 引入 `IconLayer`，调用 `LayerRegistry.register({ id, name, category, defaultVisible, factory: data => new IconLayer({ id, data, getPosition, getIcon, getSize, pickable }) })`。
21. 配置站点变体：在 `src/variants/my-variant.ts` 导出 `SiteVariant`，设置 id、name、title、defaultCategories、defaultRegion、defaultLanguage、mapStyle、enabledLayers、aiProvider、theme.primary、theme.background、theme.surface。
22. 故障排除地图：地图不渲染时检查 `VITE_MAPTILER_API_KEY` 或改用免费 CartoBasemap style。
23. 故障排除 AI：AI 合成慢或失败时确保 Ollama 运行，执行 `ollama serve && ollama pull llama3.2`。
24. 故障排除 feeds：feeds 返回 429 时通过 `UPSTASH_REDIS_REST_*` 环境变量启用 Redis 缓存。
25. 故障排除桌面：桌面应用无法构建时确保安装 Rust、`cargo install tauri-cli` 以及平台构建工具。
26. 故障排除 RTL：RTL 布局异常时确认 `setLanguage()` 已设置 `<html>` 的 `lang` 属性。
27. 故障排除 TypeScript：构建出现 TypeScript 错误时运行 `npm run typecheck`，并确保 proto 生成文件存在。
28. 故障排除 Redis：Redis 连接被拒时检查 `REDIS_URL`，或改用 Upstash REST API 而非 TCP。
29. 故障排除 build:full：`npm run build:full` 在某变体中途失败时，逐个构建，如 `npm run build -- --mode finance`。
30. 设置本地 Ollama：执行 `curl -fsSL https://ollama.ai/install.sh | sh`；拉取模型 `ollama pull llama3.2`、`ollama pull mistral`、`ollama pull gemma2:9b`；用 `curl http://localhost:11434/api/tags` 验证可访问。
31. 验证安装：执行 `npm run typecheck` 应退出 0；执行 `npm run dev` 应打开 localhost:5173；访问 `/api/health` 或执行 `curl http://localhost:5173/api/health` 检查 API 状态。
32. 查阅资源与许可：参考 live app worldmonitor.app、文档 docs.worldmonitor.app、架构 docs.worldmonitor.app/architecture、自托管 docs.worldmonitor.app/getting-started、贡献 docs.worldmonitor.app/contributing、SECURITY.md、许可证 AGPL-3.0（非商业）；SaaS/rebranding 需商业许可。

适用边界 · 注意事项

• 不适用于不想引入 World Monitor/TypeScript/Vite/deck.gl/globe.gl/Tauri/Docker/Vercel/Upstash 等特定技术栈的项目。
• 不适用于需要开箱即用且无需维护 feed、API、地图 key、AI provider 和自托管基础设施的商业闭源场景。
• AGPL-3.0 为非商业许可；不适用于未获商业许可的 SaaS、白标或二次品牌发布。