codenametest/everywhereyougo repository overview

⁠EverywhereYouGo (EGo) v1.3.2

中文⁠ | English

Receives any HTTP request, extracts structured fields through parsers, routes by conditions to multiple push channels.

⁠Docker Deployment

One-click Deployment (Recommended):

curl -O https://raw.githubusercontent.com/codename-test/EverywhereYouGo/main/deploy/init.sh
chmod +x init.sh
./init.sh
# Follow prompts to select deployment mode

Supports 5 deployment modes: default (quick start), t1-host (host network), t2-bridge (bridge network), t3-nginx (Nginx + manual certificate), t4-acme (Nginx + Let's Encrypt auto certificate).

After startup: Admin UI at https://<Host IP>:5001 (self-signed certificate, browser needs to allow); Webhook receiver and health check on http://<Host IP>:5000.

⁠Architecture

HTTP POST → Data Source → Parser → Route Match → Template Render → Push Channel

⁠Authentication

Set EGO_AUTH_TOKEN environment variable to enable access control:

EGO_AUTH_TOKEN=your-secret-token python3 main.py

• Web pages require login via token input page
• API calls require Authorization: Bearer your-secret-token header
• Health check /api/health does not require authentication

Optionally set EGO_SECRET_KEY to customize Flask session key.

⁠Configuration Files

Configuration lives in two places, with distinct roles:

Load rules at startup:

1. Database not empty → the database wins; JSON is not read, and the current config is written back to config/*.json as a snapshot
2. Database empty and JSON present → import from JSON (first run / migration / restore)
3. Database empty and no JSON → export the initial config to JSON

So use the WebUI for day-to-day config changes (they take effect immediately). Hand-editing config/*.json is only read on first import when the database is empty — it is not the normal path for applying changes.

System settings (DND, log level, etc.), the message log and the queue are also stored in SQLite. For backup/restore use Settings → Backup, which packages config/*.json plus your uploaded parsers/*.py and channels/*.py.

Restore is not the same path as startup loading: on restore, config from the backup is written to the database (config/*.json → SQLite), then plugins are reloaded and every data-source listener is restarted.

Restore is a partial restore: only config files present in the backup are written to the database; anything not included is left unchanged (not wiped), and a notice listing the missing files is returned. A hand-made or truncated ZIP therefore cannot destroy data it never contained. To restore a table to empty, ship a file containing [] rather than omitting it (file present and [] → table cleared; file absent → table untouched).

⁠Plugin Directories

Built-in plugins and user-uploaded plugins live in separate directories:

Rules:

• Resolution order: user directory first, then built-in
• Uploading a name that collides with a built-in is rejected (with a clear error) — built-ins are updated with the image, so a same-named file would never take effect
• Built-in plugins are read-only: viewable in the WebUI, but not editable or deletable
• To actually change a built-in's behaviour, put your version under a different filename in the user directory, or edit the source and rebuild the image

Upgrading from v1.3.0 to v1.3.1+ Older versions wrote user-uploaded plugins directly into the built-in directory, which is not persisted — recreating the container would lose them. Before upgrading to v1.3.1+, back up your user plugins first:

1. Export (pick one):
   • Export a ZIP via the old container's Settings → Backup (if the old version supports it);
   • Or docker cp the plugin directory from the old container (in the old version, user plugins share one unvolume-mounted directory with the built-ins — the exact path depends on your old deployment):

     docker cp <ego-container>:/app/parsers_builtin  /tmp/old-parsers
     docker cp <ego-container>:/app/channels_builtin /tmp/old-channels
     

     Copy
2. Upgrade the image: from v1.3.1+ onward, user plugins live in the user directory backed by named volumes (ego_parsers/ego_channels). A regular image upgrade (pull the new image, recreate the container) does not require re-uploading plugins — they survive via the volumes.
3. Restore (only when migrating from the old version): restore writes into the new user directory and automatically skips entries that collide with built-ins (to prevent stale copies from shadowing the new built-in plugins).

⁠Parsers

Place .py files in parsers/ directory, define a parse() function:

def parse(raw_body: bytes, headers: dict, query_params: dict) -> dict:
    data = json.loads(raw_body)
    event = data.get("Event", "")
    name = data.get("Item", {}).get("Name", "")
    return {
        "title": name,
        "event": event,
        "name": name,
    }

Fields in returned dict except title are also used for:

• Route condition matching: event == 'library.new' and media_type == 'Movie'
• Template variable reference: {name} / {{ msg.name }}

⁠Route Conditions

Supports and, or, parentheses grouping:

⁠Features

⁠Do Not Disturb (DND)

Set DND time period, messages enter queue and wait, automatically flush when period ends. Urgent routes are not affected by DND.

⁠Message Deduplication

Deduplication granularity is message × channel: each channel binding has its own dedup_key_expr and dedup_window (default 3600 seconds), independent of the others. A channel that hits is skipped while the rest still send; the whole message is marked DISCARDED only when every channel hits.

⁠Parallel Push

When multiple channels match, thread pool sends in parallel, total latency depends on the slowest single channel.

⁠Sample Data & Online Debugging

Each data source automatically saves the last 20 request samples, can select samples in WebUI for test parsing and pushing.

⁠Message Resend

Failed messages support original resend (using the parsed msg_json) or re-parse and resend. By default only the channels that failed are retried — already-succeeded channels are not pushed a second time. Use scope=all to force a full re-push.

⁠Import & Export

• Backup: Download ZIP package (config/*.json + parsers/*.py + channels/*.py)
• Restore: Upload ZIP package; config from the backup is written to the database (JSON → DB), plugin files are restored and hot-reloaded. Config not included in the backup is left unchanged, with a notice listing the missing files
• Preview: runs the same validation as a real restore (size / completeness / JSON shape / plugin loadability); the "confirm restore" button only appears when it passes
• JSON Import: Supports dry_run preview, insert/overwrite two modes, dependency check

⁠Channel Circuit Breaker

Automatically isolates a channel that keeps failing, so one broken third party cannot drag down the whole send path:

• Failure ratio > 50% within a sliding window (default 60s), or 5 consecutive failures → trip
• Cooldown backs off exponentially: 30 → 60 → 120 → … → 600 s (capped at 10 min)
• After cooldown it enters half-open probing; 3 consecutive successes restore it
• 4xx does not count as failure (a business rejection is not a service outage) — only 5xx / timeouts / connection errors are counted
• While tripped, messages stay queued: no retry budget is consumed and nothing is dropped. State is persisted and survives restarts.

⁠Outbound Rate Limiting

Per-channel rate limit (messages per minute) to avoid getting blocked by the remote side. Retries cannot fix a 429 — limiting has to happen before sending. A message that cannot get a token waits in the queue instead of being dropped.

Token bucket: each channel has an independent token bucket whose capacity (burst) equals the configured per-minute quota; it refills at quota ÷ 60 tokens per second. Sending one message takes 1 token; when the bucket is empty the message is queued — not dropped — until a token is available (up to EGO_RATE_MAX_WAIT seconds, after which it is deferred instead).

⁠Resilience UI

Parameter precedence: system_config (settings page / direct DB edit) > environment variable > built-in default. Changes take effect immediately, no restart needed.

⁠Observability

⁠Graceful Stop

On SIGTERM EGo stops accepting new messages first, then waits for in-flight tasks (up to 30 seconds); anything unfinished is moved to the dead-letter queue — a container restart does not lose messages.

⁠Internationalization

Built-in Chinese and English bilingual support, switch languages anytime via language switch button in top-right corner of navigation bar.

⁠Channel Types

⁠Environment Variables

⁠License

MIT