本機開發

本頁說明如何建立完整的 Osprey 本機開發環境。若只想用範例資料快速啟動，請改用開始使用中的 demo。

必要工具

• 作業系統　macOS、Linux 或 Windows，Windows 建議使用 WSL
• Python 3.11 以上　使用 python --version 檢查
• Git　版本控制
• uv　Python package management
• Node.js 22 以上　供 UI 使用。Corepack 隨 Node 提供，會從 osprey_ui/package.json 的 packageManager 欄位自動解析 pnpm，不需另外安裝 pnpm

專案設定

1. Clone repository

git clone git@github.com:roostorg/osprey.git
cd osprey

2. 安裝 dependencies

# Install all dependencies including development tools
uv sync

這會建立 virtual environment，並依 uv.lock 的 locked versions 安裝 production 與 development dependencies，包括 ruff、mypy 與 pre-commit。若只需要 production dependencies，使用 uv sync --no-dev。

3. 設定 pre-commit hooks

uv run pre-commit install

這會安裝 Git hooks，在每次 commit 前自動執行 code quality checks。

4. 驗證設定

執行下列 commands，確認各項工具正常運作。

# Check linting configuration
uv run ruff check

# Check formatting
uv run ruff format --diff

# Run type checking
uv run mypy .

# Test pre-commit hooks
uv run pre-commit run --all-files

Ruff 會顯示 All checks passed! 或需要修正的具體問題，mypy 與 pre-commit hooks 則應在沒有 errors 的情況下完成。

5. 啟動服務

docker compose --profile test_data up -d

也可以使用 wrapper script。

./start.sh --profile test_data up -d

test_data profile 包含產生範例 Events 的 producer。沒有這個 profile 時，技術堆疊仍會執行，但在自行傳入 Events 前，介面不會顯示資料。開始使用說明包裝上述流程的單一 command demo。

這個流程會啟動多項服務。

• Osprey Worker　主要引擎，依 Rules 與 UDFs 處理 input Events
  • Test Data Producer　由 --profile test_data 啟動的範例 event generator
• Osprey UI　提供 React 網頁介面並與 UI API 通訊的 frontend service
• Osprey UI API　為網頁介面提供資料與功能的 backend service
• Kafka，KRaft mode　傳送 user-generated Events 的 message streaming system
• Postgres　供 Worker、UI API 與 Druid 等元件使用的 database，例如範例 Plugins 中以 Postgres 為 backend 的 Labels Service
• Druid　消費 Osprey Worker outputs，支援 UI API 即時查詢的 database
• MinIO　與 S3 相容的 object storage，也是此技術堆疊預設的 Execution Result store，設定為 OSPREY_EXECUTION_RESULT_STORAGE_BACKEND=minio

也可以搭配 osprey-coordinator 啟動 Osprey。詳情請見 Coordinator README。

6. 選用，開放 UI 與 UI API ports

docker-compose.yaml 預設將執行中的服務綁定至 127.0.0.1。若在 headless machine 執行 Docker Compose，可能需要修改設定及 firewall，尤其是 ports 5002 與 5004。

例如使用 Tailscale 存取 Osprey instance 時，可以將 127.0.0.1:5002:5002 改為 <Tailscale IP>:5002:5002。若要讓 instance 從 public internet 存取，可以只設定 5002:5002，使服務綁定至 0.0.0.0。

Warning

綁定至 0.0.0.0 可能直接將 Osprey UI 或 API 暴露到 public internet。iptables 或 UFW 等部分 firewalls 無法阻止透過 Docker networking 使用的 ports。若沒有明確設定 bind address，只依賴 UFW 並不能防止 public internet 存取，除非已依 ufw-docker 等方式正確設定。開放前應另行確認認證、TLS、network policy 與最低權限。

7. 存取應用程式

UI 會自動連線至在 Docker containers 中執行的 backend services。

• Osprey UI　localhost:5002
• Backend API　localhost:5004
• Worker Service　localhost:5001

Plugins

Osprey 的 UDFs 與 output sinks 可透過以 pluggy 為基礎的 Plugin system 移植。Repository 提供範例 Plugin package，請見 example_plugins/src/register_plugins.py。包含 UDFs、sinks、hash-based lookups、ML models 與 labels service 的完整說明，請見英文官方文件 Integrations & Plugins。

@hookimpl_osprey
def register_udfs() -> Sequence[Type[UDFBase[Any, Any]]]:
    # Register custom user-defined functions

@hookimpl_osprey
def register_output_sinks(config: Config) -> Sequence[BaseOutputSink]:
    # Define output destinations
    # By default it prints the execution results to the console

@hookimpl_osprey
def register_ast_validators() -> Sequence[Type[BaseValidator]]:
    # Register AST validators

可用 hooks

可以在 Plugin 的 register_plugins.py 實作下列項目的任意子集。

Rules

Rules 使用 SML 撰寫，example_rules/ 提供搭配 YAML config 的範例。Containers 啟動時會將 Rules mount 至 Worker processes，並透過 environment variables 控制，例如下列 command。

OSPREY_RULES_PATH=./example_rules uv run python osprey_worker/src/osprey/worker/cli/sinks.py run-rules-sink

Rules 的其他說明目前請見英文官方文件撰寫規則。

測試資料

使用下列 command 產生範例 JSON actions。

docker compose --profile test_data up osprey-kafka-test-data-producer -d

這會產生包含 timestamps、user IDs 與 IP addresses 的 synthetic post-creation Events，並傳送至 osprey.actions_input topic。這個 producer 與 test_data profile 啟動的項目相同。