World Monitor 本地部署教程：Docker、Ollama、PMTiles 与离线情报面板

World Monitor 是一个聚合新闻、市场、航空、地缘风险、基础设施和公开情报数据的实时面板。它在 GitHub Trending 一周增加约 13,231 stars，但“能打开前端”与“完整离线运行”是两种不同部署目标。本文先把组件和网络依赖拆开，再给出源码开发、容器前端和本地 AI 摘要三条可验证路径。

先决定要部署到哪一种离线程度

项目文档描述了三类隐私模式。最简单的是本地打开应用，但继续请求公共 API 和云端 LLM。第二类是桌面端配合 Ollama、LM Studio、llama.cpp 或 vLLM，让新闻摘要留在本机，其他数据源仍联网。第三类是隔离网络：本地模型、本地 PMTiles、预先准备的数据快照，并禁用实时外部源。第三类无法凭一个 Docker 容器自动完成，因为航班、市场、RSS 和风险源本身需要更新。在动手前写下允许访问的域名、数据更新时间要求和是否允许云端摘要。

World Monitor 的运行组件并不只有网页

前端是 Vanilla TypeScript 应用，地图由 MapLibre GL、deck.gl 和 globe.gl 等组件渲染。服务端部分包含 Edge handler、RPC 网关、缓存和数据种子任务。 AIS Relay 负责部分实时流与周期数据。 Redis 用于缓存、限流和避免多个请求同时刷新同一数据。桌面端使用 Tauri，并带有 Node.js sidecar。 PMTiles 可以把底图放到对象存储或局域网 HTTP 服务。因此，自托管需要明确哪些组件由自己运行，哪些继续借用上游服务。

许可证先于部署方式

仓库采用 AGPL-3.0，并对商业用途有额外说明。个人、研究和教育用途可以在遵守署名与许可证条件的前提下自托管。商业 SaaS、去除品牌或重新包装需要查看项目的商业许可要求。不要把“代码能公开下载”理解成可以无条件闭源销售。计划对外提供服务时，先阅读仓库中的 LICENSE 和 README 许可表。

准备 Node 22 与基础工具

项目变更记录已把 Node 22 固定为开发基线。在 Windows 上建议使用 WSL2 Ubuntu，Linux 和 macOS 可直接操作。

1
2
3
4


node --version
npm --version
git --version
make --version

Node 主版本不是 22 时，使用 nvm 切换：

1
2
3


nvm install 22
nvm use 22
node --version

不要在系统 Node 与 nvm Node 之间混用全局包。

从源码启动完整开发面板

先 fork 或直接克隆官方仓库：

1
2
3


git clone https://github.com/koala73/worldmonitor.git
cd worldmonitor
git rev-parse HEAD

保存 commit SHA，后续文档与配置变化都能追溯到明确版本。官方贡献文档提供了统一安装目标：

1

make install

它会准备 buf、sebuf 插件、npm 依赖和 Playwright 浏览器。只想查看帮助时运行：

1

make help

完整变体的开发服务器：

1

npm run dev

默认地址是 http://localhost:3000。

不同变体不是不同仓库

World Monitor 通过 variant 控制面板、地图层、刷新周期和默认数据源。技术、金融和完整面板可以分别启动：

1
2


npm run dev:tech
npm run dev:finance

生产构建也有对应命令：

1
2
3


npm run build
npm run build:tech
npm run build:finance

切换 variant 会重置部分设置，不要把不同变体的浏览器 localStorage 当作同一份配置。

环境变量按数据源逐项开启

复制示例文件：

1

cp .env.example .env.local

先不要把所有 API key 一次填满。从不需要凭据的面板开始，确认前端、地图和基本 RPC 正常。再逐个增加新闻、市场、航班或 LLM 供应商。每增加一个变量就重启服务并检查网络请求。 .env.local 不进入 Git：

1
2


git status --short
git check-ignore .env.local

若第二条没有输出，先检查 .gitignore，不要继续填写真实密钥。

Docker 路线适合托管前端

仓库的 docker/Dockerfile 构建多架构镜像，由 nginx 提供 SPA，并把 API 请求代理到上游。先在本地构建：

1
2


docker build -f docker/Dockerfile -t worldmonitor:local .
docker image inspect worldmonitor:local

查看 Dockerfile 暴露端口和 nginx 配置后再运行，不要猜端口：

1
2


docker image inspect worldmonitor:local \
  --format '{{json .Config.ExposedPorts}}'

假设镜像暴露 80，可用仅回环映射测试：

1
2
3


docker run --rm --name worldmonitor-test \
  -p 127.0.0.1:8080:80 \
  worldmonitor:local

如果实际端口不同，以镜像检查结果为准。

容器前端并不等于所有 API 都本地化

打开浏览器开发者工具的 Network 面板。刷新页面并按域名分组请求。任何访问 Vercel、Railway、Upstash、第三方新闻或市场接口的请求，都说明当前仍有云依赖。不要用“网页来自自己的服务器”推导“数据没有离开局域网”。需要隔离时，逐项替换 API endpoint，或禁用无法本地运行的面板。

用 Ollama 提供本地摘要

World Monitor 的本地 LLM 路线支持 OpenAI-compatible 服务，并能发现 Ollama、LM Studio、llama.cpp 和 vLLM 模型。安装 Ollama 后先确认服务：

1
2
3


ollama --version
ollama list
curl http://127.0.0.1:11434/api/tags

拉取一个适合本机资源的指令模型：

1

ollama pull qwen3:8b

再测试 OpenAI 兼容端点：

1

curl http://127.0.0.1:11434/v1/models

应用中把 base URL 指向回环地址，并选择实际存在的模型 ID。

本地 LLM 回退链需要主动验证

项目文档描述的摘要回退顺序包括本地 LLM、Groq、OpenRouter 和浏览器 T5。如果目标是数据不出网，仅配置 Ollama 不够。还要移除云端 key，阻止相关域名，并确认浏览器没有在本地超时后静默回退。把 Ollama 服务停止：

1

sudo systemctl stop ollama

再次触发摘要。严格离线配置应明确显示本地服务不可用，而不是产生云端摘要。

PMTiles 解决的是底图依赖

传统地图会按视口不断请求在线瓦片。 PMTiles 把瓦片组织为单个归档，可放在本地磁盘、NAS、对象存储或普通 HTTP 服务。准备文件后先做最小 HTTP 服务：

1

python3 -m http.server 9000 --directory /srv/pmtiles

从浏览器访问 PMTiles 文件，确认支持 Range 请求。没有 Range 支持时，地图可能尝试下载整个大文件或无法定位瓦片。反向代理需要保留 Range 与 Accept-Ranges 相关 Header。

Cloudflare R2 与局域网存储怎么选

R2 适合公网服务，能减轻源站带宽并提供对象级访问。局域网 MinIO、NAS 或 nginx 更适合隔离环境。底图文件可能很大，发布前记录尺寸和哈希：

1
2


sha256sum world.pmtiles
du -h world.pmtiles

客户端配置 URL 后，用浏览器确认请求返回 206 Partial Content。

Redis 不是本地试用的硬门槛

单人开发可以先不部署完整缓存体系。多人或公网服务需要 Redis 来控制刷新风暴、缓存 seed 结果和限流。启动本地 Redis：

1
2


docker run --rm --name worldmonitor-redis \
  -p 127.0.0.1:6379:6379 redis:7-alpine

验证：

1

docker exec worldmonitor-redis redis-cli ping

应返回 PONG。 Redis 不要直接暴露到公网，也不要依赖默认无密码配置跨主机访问。

外部数据源失败时怎样判断责任位置

先检查浏览器请求的 URL、状态码和响应时间。 401 或 403 通常是 key、配额或授权范围。 429 表示速率限制，增加重试可能让问题更严重。 5xx 需要区分自己的代理、上游服务和缓存层。空数组不一定是故障，也可能是区域和时间范围没有数据。保存 request ID 和响应 Header，不要只截一张空白面板截图。

AIS 与实时流不能靠静态构建代替

航运 AIS、航班和 GPS 干扰层依赖持续数据流或周期 seed。纯 nginx SPA 只能展示已有数据和调用上游接口。需要自托管相关流时，阅读 scripts/ais-relay.cjs 和部署配置，确认数据提供商许可。不要把公开网页上看到的数据源无条件镜像并重新发布。

开启健康检查与数据新鲜度监控

应用能返回 200，不代表数据在更新。监控至少分三层：静态页面、API endpoint 和 seed freshness。记录每个数据源最后成功时间与连续失败次数。当新闻仍更新而市场停止时，不应把整个站点标成完全健康。

构建前运行项目自己的检查

1
2
3
4


npm run typecheck
npm run test:data
npm run test:e2e
npm run build:full

命令存在性以当前仓库 package.json 和 make help 为准。数据测试失败时不要删除失败源来让 CI 变绿，先确认格式是否变更。 E2E 需要浏览器依赖和稳定测试数据，容器 CI 要预留共享内存。

反向代理只开放需要的入口

公网部署使用 HTTPS，并把管理端、Redis、Ollama 和内部 seed endpoint 留在私网。 Ollama 默认不应直接暴露到互联网。若前端与 API 分域，明确设置 CORS 允许列表。不要使用允许任意 origin 同时携带凭据的组合。

做一次真正的断网演练

加载面板后断开互联网容易得到误判，因为 service worker、浏览器缓存和 IndexedDB 仍保存旧数据。先清空测试 Profile，阻止外部域名，再重新打开应用。记录哪些面板正常、哪些显示旧缓存、哪些报错。检查时间戳是否明确标识数据已经过期。离线模式应优雅降级，而不是把旧信息伪装成实时信息。

升级时保留 variant 和地图配置

升级前保存 commit、.env.local 变量名、PMTiles URL、Redis schema 和反向代理配置。

1
2
3


git fetch --tags
git log --oneline --decorate -10
git diff -- .env.example docker/ deploy/

先在新工作树构建，不要直接覆盖运行目录。前端 localStorage 的设置格式可能变化，升级后抽查 variant、图层和刷新周期。

自托管完成的判定清单

页面与所需 variant 可以构建。
Docker 镜像端口来自 inspect，而不是猜测。
所有 API key 都在 Git 之外。
本地 LLM 失败时不会静默转到云端。
PMTiles 返回 Range 请求。
Redis、Ollama 和内部服务不暴露公网。
每个实时数据源都有最后更新时间。
断网测试能区分缓存和真实可用。
商业用途已经核对许可证。

World Monitor 的自托管边界取决于你保留多少实时数据源。先把网络依赖画清楚，再决定是本地前端、隐私摘要还是完整隔离，比直接追求“一条 Docker 命令”更可靠。

先区分网页、CLI、REST API 和 MCP

这一节解决的是“先区分网页、CLI、REST API 和 MCP”。先记录当前状态，再执行最小动作，最后用独立证据确认结果。

对 World Monitor 而言，判断依据是：公开 MCP 允许列出工具，但需要授权的调用仍要 API Key 或 OAuth；返回的聚合情报必须回查原始来源。不要在这个阶段顺手打开更多权限。

1

npx worldmonitor tools

执行后保留命令输出和时间戳。若输出依赖当前终端里的临时变量，打开新终端复查一次。

公开 tools/list 能验证什么

按下面顺序处理：

读取实际版本和当前配置。
只改变与本节相关的一项设置。
运行一个只读或可撤销的请求。
检查日志、退出码和最终文件。
失败时恢复刚才那一项修改。

1
2


npm install -g worldmonitor
worldmonitor tools

这里的完成标准不是界面出现，而是“公开 tools/list 能验证什么”有可重复结果。

取得并保存 World Monitor API Key

要检查的内容	合格表现	需要停止的信号
取得并保存 World Monitor API Key	输入和输出范围明确	自动扩大到其他项目或账号
权限	只获得完成任务所需权限	要求管理员权限或完整密钥
日志	能定位失败且已经脱敏	出现 Token、Cookie 或私有正文
回退	能恢复上一步状态	修改不可逆且没有备份

1

worldmonitor risk IR --api-key wm_xxx

表格中的停止信号一旦出现，先撤销本节改动，不要继续后面的自动化。

在 Codex 中登记 Streamable HTTP MCP

围绕“在 Codex 中登记 Streamable HTTP MCP”准备一个成功样本和一个失败样本。成功样本验证正常路径，失败样本验证限制是否真的生效。

1
2


# MCP URL
https://worldmonitor.app/mcp

建议记录以下四项：

执行前的版本或 Git 提交。
实际输入，不记录秘密值。
可观察的输出、状态码或 diff。
恢复动作以及恢复后的复查结果。

如果失败原因仍不清楚，每次只修改一个变量；不要同时换端口、运行时、Provider 和代理。

用 CLI 先跑一次国家风险查询

这一节解决的是“用 CLI 先跑一次国家风险查询”。先记录当前状态，再执行最小动作，最后用独立证据确认结果。

把 MCP 结果限制为只读研究

1

worldmonitor tools

这里的完成标准不是界面出现，而是“把 MCP 结果限制为只读研究”有可重复结果。

新闻摘要如何回到原始来源

要检查的内容	合格表现	需要停止的信号
新闻摘要如何回到原始来源	输入和输出范围明确	自动扩大到其他项目或账号
权限	只获得完成任务所需权限	要求管理员权限或完整密钥
日志	能定位失败且已经脱敏	出现 Token、Cookie 或私有正文
回退	能恢复上一步状态	修改不可逆且没有备份

市场和地缘数据不能混为一谈

围绕“市场和地缘数据不能混为一谈”准备一个成功样本和一个失败样本。成功样本验证正常路径，失败样本验证限制是否真的生效。

处理 401、403 与工具列表为空

这一节解决的是“处理 401、403 与工具列表为空”。先记录当前状态，再执行最小动作，最后用独立证据确认结果。

1

curl.exe -i https://worldmonitor.app/mcp

控制查询范围和调用成本

这里的完成标准不是界面出现，而是“控制查询范围和调用成本”有可重复结果。

撤销密钥与删除 MCP 配置

要检查的内容	合格表现	需要停止的信号
撤销密钥与删除 MCP 配置	输入和输出范围明确	自动扩大到其他项目或账号
权限	只获得完成任务所需权限	要求管理员权限或完整密钥
日志	能定位失败且已经脱敏	出现 Token、Cookie 或私有正文
回退	能恢复上一步状态	修改不可逆且没有备份

1

npm uninstall -g worldmonitor

一份可复制的情报核验清单

围绕“一份可复制的情报核验清单”准备一个成功样本和一个失败样本。成功样本验证正常路径，失败样本验证限制是否真的生效。

OAuth 与 API Key 怎么选

这一节解决的是“OAuth 与 API Key 怎么选”。先记录当前状态，再执行最小动作，最后用独立证据确认结果。

限制允许查询的国家与指标

这里的完成标准不是界面出现，而是“限制允许查询的国家与指标”有可重复结果。

同一事件交叉验证两个来源

要检查的内容	合格表现	需要停止的信号
同一事件交叉验证两个来源	输入和输出范围明确	自动扩大到其他项目或账号
权限	只获得完成任务所需权限	要求管理员权限或完整密钥
日志	能定位失败且已经脱敏	出现 Token、Cookie 或私有正文
回退	能恢复上一步状态	修改不可逆且没有备份

删除失效的 World Monitor 连接

围绕“删除失效的 World Monitor 连接”准备一个成功样本和一个失败样本。成功样本验证正常路径，失败样本验证限制是否真的生效。

World Monitor 常见问题

是否可以跳过测试环境，直接把 World Monitor 用到正式项目？

不建议。至少先完成一次最小成功请求、一次故意失败和一次恢复演练。

World Monitor 命令能运行但结果不对，先查哪里？

先查输入范围、实际生效的配置和上游响应，再查模型总结。进程正常不代表业务结果正确。

如何避免 World Monitor 的密钥或令牌进入 Git？

使用系统环境变量、Secret 管理或项目外配置文件，并在提交前搜索 diff。发现泄露后必须轮换密钥。

升级 World Monitor 时最容易漏掉什么？

最容易漏掉配置格式、默认监听地址、权限范围和缓存兼容性。升级前保存版本与验证样本。

项目资料

World Monitor Docker Compose 自托管补充

World Monitor 是一个开源全球态势看板，可以聚合新闻、地缘事件、灾害、金融、能源、航空、航运与基础设施数据。它既能作为网页和桌面应用使用，也提供 REST API、CLI 与 MCP 接口。

项目地址：

https://github.com/koala73/worldmonitor

如果只是体验界面，运行前端开发服务器即可；如果要长期自建，应使用项目提供的 Docker Compose 完整栈。完整栈不只是一个静态页面，还包括 Node.js API、Redis、Redis REST 代理和 AIS 船舶数据中继。

自托管前需要什么

官方自托管文档当前要求：

Docker 或 Podman；
Docker Compose 或 podman-compose；
Node.js 22 或更高版本，用于在宿主机执行数据初始化脚本；
足够的磁盘空间保存镜像、依赖和 Redis 数据。

Windows 用户适合在 WSL2 中执行后续命令。虽然 Docker Desktop 能启动容器，但官方初始化脚本是 Shell 脚本，直接在普通 PowerShell 中运行并不顺手。

Docker Compose 完整部署

先克隆项目并安装依赖：

1
2
3


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

新版完整栈必须设置三个随机密钥，否则部分容器会直接退出：

1
2
3


echo "RELAY_SHARED_SECRET=$(openssl rand -hex 32)" >> .env
echo "REDIS_PASSWORD=$(openssl rand -hex 32)" >> .env
echo "REDIS_TOKEN=$(openssl rand -hex 32)" >> .env

然后启动容器：

1

docker compose up -d

第一次启动后还要执行数据初始化：

1

./scripts/run-seeders.sh

最后访问：

1

http://localhost:3000

如果页面能打开但健康检查显示 0/55 OK，通常不是前端故障，而是还没有运行 seeders。

哪些数据源不需要 API Key

不配置第三方密钥也能看到地震、天气、自然事件、部分冲突与迁徙、稳定币、加密货币、气候异常、海底电缆和网络安全等公共数据。

更多数据需要单独申请 API Key，例如：

数据类型	常见配置
LLM 分析	`GROQ_API_KEY`、`OPENROUTER_API_KEY` 或本地 OpenAI 兼容接口
市场和经济	`FINNHUB_API_KEY`、`FRED_API_KEY`、`EIA_API_KEY`
冲突事件	ACLED 账号或令牌
火灾监测	`NASA_FIRMS_API_KEY`
航空和航运	AviationStack、AISStream
网络中断	Cloudflare Radar 相关令牌，可能需要付费权限

建议将额外配置写进 docker-compose.override.yml。项目默认忽略这个文件，能降低密钥误提交到 Git 的风险。

接入 Ollama 或其他本地模型

World Monitor 能连接任何兼容 OpenAI Chat Completions 的服务，包括 Ollama、vLLM 和 llama.cpp server。

可在 docker-compose.override.yml 中加入：

1
2
3
4
5
6
7
8


services:
  worldmonitor:
    environment:
      LLM_API_URL: "http://your-host:8000/v1/chat/completions"
      LLM_API_KEY: "your-key"
      LLM_MODEL: "your-model-name"
    extra_hosts:
      - "your-host:192.168.1.100"

如果 Ollama 运行在 Docker 宿主机上，容器里的 localhost 指向容器自身，不能直接写 http://localhost:11434。Docker Desktop 通常可尝试：

1

http://host.docker.internal:11434/v1/chat/completions

Linux 主机则可以使用宿主机局域网地址，或给 Compose 配置 host-gateway。同时确认 Ollama 已监听容器可访问的地址，并用防火墙限制来源。

MCP 怎么接入 Agent

官方公共 MCP 地址为：

1

https://worldmonitor.app/mcp

它使用 Streamable HTTP。公开的 tools/list 可以列出工具，但调用部分能力需要 World Monitor API Key 或 OAuth。自托管时不要因为看见 MCP 入口就默认所有数据都在本机：Agent 最终访问的是你配置的 MCP 地址，公共地址仍会连接官方服务。

接入 Codex、Claude Code 或其他 Agent 前，先确认：

MCP 服务指向官方实例还是自己的实例；
API Key 会保存到哪个配置文件；
Agent 能调用哪些查询工具；
返回的新闻和风险判断是否保留来源；
是否允许把内部查询条件发送到外部服务。

数据刷新与持久化

Redis 数据会保存在 redis-data volume 中。普通容器重启不会清空数据，但下面的命令会删除 volume：

1

docker compose down -v

删除后需要重新执行：

1

./scripts/run-seeders.sh

长期运行可以用 cron 定期刷新：

1

*/30 * * * * cd /path/to/worldmonitor && ./scripts/run-seeders.sh >> /tmp/wm-seeders.log 2>&1

上游接口可能限流或暂时不可用，刷新频率不是越高越好。应根据 API 配额、数据时效和服务器负载调整。

常见问题排查

容器启动后马上退出

先检查 .env 是否同时存在 RELAY_SHARED_SECRET、REDIS_PASSWORD 和 REDIS_TOKEN，再查看：

1
2


docker compose ps
docker compose logs --tail=200

旧版公开默认令牌已经被移除，不应为了省事恢复固定弱口令。

没有船舶或火灾数据

船舶数据需要在主应用和 AIS relay 中配置 AISSTREAM_API_KEY；火灾数据需要 NASA_FIRMS_API_KEY。只填一处可能导致页面存在但数据为空。

Ollama 连接失败

依次检查：

Ollama 的 /v1/chat/completions 是否能从宿主机访问；
容器能否解析并连接宿主机地址；
LLM_MODEL 是否与已下载模型名称完全一致；
防火墙是否拦截容器网段；
是否错误地把容器内的 localhost 当成宿主机。

Redis 数据一直为空

确认 Redis REST 代理已经启动，并优先用官方包装脚本：

1

./scripts/run-seeders.sh

手动执行单个 seeder 时，还要正确提供 UPSTASH_REDIS_REST_URL 和 UPSTASH_REDIS_REST_TOKEN。

隐私和安全边界

自托管并不等于完全离线。World Monitor 会从大量外部数据源抓取内容；如果配置 Groq、OpenRouter、第三方市场接口或公共 MCP，查询和上下文仍可能离开服务器。

部署前至少处理这些问题：

不把 Redis、Redis REST 代理和 AIS relay 直接暴露到公网；
使用随机密钥，不提交 .env 和 override 文件；
通过反向代理启用 HTTPS 和访问控制；
限制 Ollama 或其他模型接口的监听地址；
定期更新镜像和依赖；
对新闻、金融、冲突与风险判断保留来源并交叉验证。

World Monitor 适合帮助人更快发现信号，不应被当成已经核实的情报结论或投资建议。

AGPL 许可证要注意什么

项目源码使用 AGPL-3.0-only。个人研究、自托管和修改通常可以按许可证进行；如果修改后通过网络向用户提供服务，通常需要向这些用户提供相应源码。闭源商业部署、官方品牌使用或不想承担 AGPL 义务的团队，应在上线前检查许可证原文并咨询专业意见，必要时联系项目方获取商业授权。

对大多数个人用户，最稳妥的路线是先在局域网部署，确认数据源、LLM、MCP 和刷新任务都符合预期，再决定是否开放公网访问。