Worldmonitor¶
Overview¶
Worldmonitor 係一套自我託管嘅全球事件監察服務，部署於 oracle-cloud 之上，用嚟彙合同分析多來源嘅世界實時數據。系統涵蓋海上船隻（AIS）、衝突事件（ACLED）、火點偵測（NASA FIRMS）、金融及能源指標（Finnhub、FRED、EIA），並且支援經 GROQ 或 OpenRouter 調用 AI 模型做智能分析。Worldmonitor 以容器方式運行，跟從「共用基礎設施」政策，唔會起獨立 Redis，而係使用現有嘅共用 Redis 實例，並以 DB 6 作為專屬邏輯空間。整個服務適合長時間喺雲端運行，預設時區係 Asia/Hong_Kong，方便香港營運者監察同除錯。
Architecture¶
Worldmonitor 嘅容器拓樸主要由三個部分組成：主程式容器、Redis REST 代理容器，以及 AIS relay 容器。
主程式容器使用 worldmonitor:latest 影像，容器名稱係 worldmonitor，執行策略係 restart: unless-stopped，並限制記憶體上限為 2GB，避免 Oracle Cloud 免費方案嘅細記憶體實例因記憶體洩漏而拖垮成個宿主。佢嘅後端數據層指向共用 Redis redis-main：REDIS_PASSWORD 用嚟直接連接 redis:6379 並使用 DB 6。由於 Docker 網路入面 host 唔一定可以直接解析到 Redis 容器，所以系統另設 worldmonitor-redis-rest 容器，呢個代理容器提供 HTTP 介面，UPSTASH_REDIS_REST_URL 指向 http://worldmonitor-redis-rest:80，令主程式可以經 REST 方式讀寫 Redis，而唔使直接暴露 Redis 埠。REDIS_TOKEN 同 UPSTASH_REDIS_REST_TOKEN 一致，用作代理認證。
實時訊息串流方面，Worldmonitor 連接 worldmonitor-ais-relay 容器，WS_RELAY_URL 設定為 http://worldmonitor-ais-relay:3004，並用 RELAY_SHARED_SECRET 做閘道認證。呢個 relay 主要用嚟轉發 AIS 船隻定位訊息或其他 WebSocket 數據流，令主程式可以專注處理業務邏輯，而唔使直接管理長連線。
主程式亦暴露內部 API，LOCAL_API_PORT=46123，LOCAL_API_MODE=docker，LOCAL_API_CLOUD_FALLBACK=false，意思係 API 喺容器內提供服務，並且唔會喺本地呼叫失敗時自動轉去雲端 API；呢個設計強調數據私隱同可控性。AI 及外部數據源嘅 API key 全部係可選，假如未設定，系統只會喪失對應功能，而唔會令主程式崩潰，日後可透過 Infisical 或 .env 補齊。
Deployment¶
Worldmonitor 部署喺 oracle-cloud 上，建議使用 Docker Compose 管理。部署前需要準備以下嘢：
- 一個已經運行緊嘅共用 Redis 實例，喺 Docker 網路內可經
redis:6379到達。 - Redis DB 6 必須可用，而且唔可以同其他服務衝突。
- 準備
.env檔案，填入所有密碼及 Token。 - 如果要用 AIS 訊息，需要預先起好
worldmonitor-ais-relay容器。 - 如果要用 Redis REST 介面，需要預先起好
worldmonitor-redis-rest容器。
基本部署步驟：
- 將 Compose 檔案放上 Oracle Cloud 實例。
- 建立
.env，包括REDIS_PASSWORD、REDIS_TOKEN、RELAY_SHARED_SECRET以及可選外部 API key。 - 確認 Redis 服務仲有其他 sidecar 容器已經運行。
- 執行
docker compose up -d worldmonitor。 - 用
docker compose ps檢查狀態，再用docker compose logs -f worldmonitor睇日誌。
部署可以放喺 Oracle Cloud 免費 ARM 實例（Ampere A1）上，因為 2GB 記憶體限制適合 1-2GB RAM 嘅細機。如果宿主本身有 4GB 或以上，就可以更從容咁同時運行 Redis、relay 同其他監察工具。
Configuration¶
Worldmonitor 嘅設定完全由環境變數驅動。以下係主要項目：
| 變數 | 用途 |
|---|---|
TZ |
時區，設為 Asia/Hong_Kong，令日誌同排程以香港時間顯示。 |
REDIS_PASSWORD |
直接連接 Redis 實例用嘅密碼，對應共用 redis-main。 |
REDIS_TOKEN |
Redis REST 代理或主程式認證用嘅 Token。 |
UPSTASH_REDIS_REST_URL |
指向本地 worldmonitor-redis-rest 容器，令主程式經 HTTP 連 Redis。 |
UPSTASH_REDIS_REST_TOKEN |
對應 REDIS_TOKEN，用作代理嘅 Bearer Token。 |
RELAY_SHARED_SECRET |
同 AIS relay 之間嘅共用密鑰，確保連線受控。 |
WS_RELAY_URL |
AIS relay 嘅 WebSocket 或 HTTP 端點。 |
LOCAL_API_PORT |
本地 API 監聽埠，容器內定為 46123。 |
LOCAL_API_MODE |
設為 docker，代表以容器模式運行。 |
LOCAL_API_CLOUD_FALLBACK |
設為 false，禁止雲端後備。 |
GROQ_API_KEY |
可選，Groq AI 模型存取。 |
OPENROUTER_API_KEY |
可選，OpenRouter 統一 AI 閘道。 |
FINNHUB_API_KEY |
可選，金融市場數據。 |
FRED_API_KEY |
可選，聯儲局經濟數據。 |
EIA_API_KEY |
可選，美國能源資訊署數據。 |
NASA_FIRMS_API_KEY |
可選，NASA 火點衛星數據。 |
AISSTREAM_API_KEY |
可選，AIS 船隻定位數據。 |
ACLED_EMAIL / ACLED_PASSWORD / ACLED_A |
可選，ACLED 衝突事件資料庫憑證。 |
所有可選變數留空並唔會令容器啟動失敗，系統會自動降級，並喺日誌顯示缺失功能。呢種設計係為咗配合「之後用 Infisical 補齊」嘅營運策略。
Operations¶
日常操作主要圍繞 Docker 容器管理。
- 啟動 / 停止：
docker compose up -d worldmonitor或者docker compose stop worldmonitor。 - 睇日誌：
docker compose logs -f worldmonitor，可以加--tail=100減少輸出。 - 重啟：
docker compose restart worldmonitor，適用於改咗環境變數之後快速套用。 - 進入容器：
docker exec -it worldmonitor sh，用嚟檢查內部網路或手動執行採集任務。 - 監察資源：
docker stats --no-stream worldmonitor，確認記憶體冇超出 2GB 上限。 - 更新影像：由於
worldmonitor:latest係固定標籤，可以執行docker compose pull worldmonitor再docker compose up -d更新。
Redis 方面，由於政策禁止獨立 Redis，所有資料都喺共用實例嘅 DB 6 入面。備份時要非常小心，應該用 redis-cli -a "$REDIS_PASSWORD" -n 6 --rdb /backup/worldmonitor.rdb 或者 BGSAVE，千祈唔好對整個 Redis 做 FLUSHALL，否則會影響其他共用服務。
AIS relay 如果出現斷線，可以重啟 worldmonitor-ais-relay，然後確認 WS_RELAY_URL 嘅連線狀態。大部份問題都可以靠日誌尾幾行判斷。
FAQ¶
點解唔用獨立 Redis？ 因為項目政策係「禁獨立 Redis」，所有服務共用 redis-main，Worldmonitor 只係用 DB 6 做邏輯隔離，咁樣可以減少資源浪費，亦方便統一備份同管理。
REDIS_PASSWORD 同 REDIS_TOKEN 有咩分別？
REDIS_PASSWORD 係 Redis 原生密碼，用於直接 RESP 連線；REDIS_TOKEN 係 Redis REST 代理嘅認證 Token，用於 HTTP 介面。喺 Worldmonitor 入面，兩者都指向同一個共用 Redis。
點解 UPSTASH 會指向本地代理而唔係真正 Upstash？
因為 Oracle Cloud 上冇必要用外部雲端 Redis，本地 worldmonitor-redis-rest 提供類似 Upstash 嘅 REST 介面，令 seed/host 喺同一 Docker 網路入面可以快速安全咁連線，而唔使暴露 Redis 6379 埠。
冇 API key 會點？
功能降級。例如冇 EIA_API_KEY 就冇能源數據，冇 GROQ_API_KEY 就冇 AI 摘要。系統照樣運行，日後只要喺 .env 或者 Infisical 補返 key，再重啟容器就可以啟用。
可唔可以喺香港時區以外運行？
可以，但唔建議。TZ=Asia/Hong_Kong 會影響日誌時間同新聞事件嘅時間排序，如果改做其他時區，可能令警報時間唔對。
LOCAL_API_CLOUD_FALLBACK=false 有咩好處？ 確保數據處理唔會依賴外部雲端 API，避免敏感監察資料外洩。即使本地 API 出錯，都唔會自動用雲端替代，反而會留低錯誤畀管理員跟進。
Related Links¶
docker
docker-compose
oracle-cloud
redis
litellm
Self-hosted service
AIS
ACLED
NASA FIRMS
Finnhub
FRED
EIA
香港
Source¶
Coverage auto (container scan)