diff --git a/README.en.md b/README.en.md index 4ae36a9..787d0fe 100644 --- a/README.en.md +++ b/README.en.md @@ -1,50 +1,73 @@ - # EverywhereYouGo (EGo) v1.2.3 +[中文](README.md) | English + > Universal Message Forwarding Platform — Data → Parse → Route → Push -EGo receives arbitrary HTTP requests, extracts structured fields through parsers, matches routes by conditions, and pushes to multiple channels. +Receives any HTTP request, extracts structured fields through parsers, routes by conditions to multiple push channels. + +## Docker Deployment -## Quick Start +**One-click Deployment (Recommended):** ```bash -pip install -r requirements.txt -python3 main.py +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 ``` -Open `https://localhost:5001` for the admin UI (self-signed cert; accept the browser warning). Webhook receivers and the health check run over plain HTTP on `http://localhost:5000`. +Supports 5 deployment modes: default (quick start), t1-host (host network), t2-bridge (bridge network), t3-nginx (Nginx + manual certificate), t4-certbot (Nginx + Let's Encrypt auto certificate). + +> More deployment options in [deploy/README.en.md](deploy/README.en.md). + +After startup: Admin UI at `https://:5001` (self-signed certificate, browser needs to allow); Webhook receiver and health check on `http://:5000`. ## Architecture ``` -HTTP POST → Source → Parser → Route Match → Template Render → Push Channel +HTTP POST → Data Source → Parser → Route Match → Template Render → Push Channel ``` | Component | Description | -|-----------|-------------| -| **Source** | Listens on a port, receives HTTP POST | +|------|------| +| **Data Source** | Listens on port to receive HTTP POST | | **Parser** | Python script, extracts fields and defines variable names | -| **Route** | Condition expression matching channel-template pairs | -| **Template** | Simple / Jinja2 rendering for title and content | +| **Route** | Condition expression matches channel-template pairs | +| **Template** | Simple / Jinja2 renders title and content | | **Channel** | WeChat Work, DingTalk, Feishu, Telegram, Bark | -## Config +## Authentication -Persistent configuration is stored as JSON files in `config/`: +Set `EGO_AUTH_TOKEN` environment variable to enable access control: + +```bash +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 is persisted as JSON files in `config/` directory: | File | Content | -|------|---------| +|------|------| | `config/parsers.json` | Parser metadata | -| `config/sources.json` | Source definitions | -| `config/channels.json` | Push channel configs | +| `config/sources.json` | Data source definitions | +| `config/channels.json` | Push channel configurations | | `config/templates.json` | Push templates | | `config/bindings.json` | Channel bindings (with condition expressions) | -Edit JSON directly and restart, or manage via WebUI. System settings (DND, log level) and runtime data (message logs) are stored in SQLite (`ego.db`). +Can directly edit JSON and restart to take effect, or manage via WebUI. System settings (DND, log level, etc.) and runtime data (message logs) are stored in SQLite (`ego.db`). -## Parser +## Parsers -Place `.py` files in `parsers/`, define a `parse()` function: +Place `.py` files in `parsers/` directory, define a `parse()` function: ```python def parse(raw_body: bytes, headers: dict, query_params: dict) -> dict: @@ -53,64 +76,55 @@ def parse(raw_body: bytes, headers: dict, query_params: dict) -> dict: name = data.get("Item", {}).get("Name", "") return { "title": name, - "content": "- **event**: " + event + "\n- **name**: " + name, "event": event, "name": name, } ``` -Fields other than `title`/`content` are used for: +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`, and parenthesized expressions: +Supports `and`, `or`, parentheses grouping: | Example | Description | -|---------|-------------| +|------|------| | `event == 'library.new'` | New items only | | `event == 'library.new' and media_type == 'Movie'` | New movies only | | `event == 'library.new' or event == 'test'` | New items or test messages | -| `media_type in ('Movie', 'Series')` | Movies or series | -## Deploy +## Features -### Docker +### 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. -**One-click deployment (recommended):** +### Message Deduplication +Channel bindings can configure `dedup_key_expr` and `dedup_window` (default 3600 seconds). Same dedup key will not be sent repeatedly within the window. -```bash -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 -``` +### Parallel Push +When multiple channels match, thread pool sends in parallel, total latency depends on the slowest single channel. -Supports 5 deployment modes: default (quick start), t1-host (host network), t2-bridge (bridge network), t3-nginx (Nginx + manual cert), t4-certbot (Nginx + Let's Encrypt auto cert). +### Sample Data & Online Debugging +Each data source automatically saves the last 20 request samples, can select samples in WebUI for test parsing and pushing. -> More deployment options are in the `deploy/` directory with `README.en.md` (English) and `README.md` (Chinese). +### Message Resend +Failed messages support original resend (using parsed msg_json) or re-parse and resend. -After startup: admin UI at `https://:5001` (self-signed cert, accept the browser warning); webhook receivers and health check at `http://:5000`. +### Import & Export +- **Backup**: Download ZIP package (`config/*.json` + `parsers/*.py`) +- **Restore**: Upload ZIP package, automatically takes effect after overwriting configuration +- **JSON Import**: Supports dry_run preview, insert/overwrite two modes, dependency check -### Env Variables +## Internationalization -| Variable | Default | Description | -|----------|---------|-------------| -| `WEB_PORT` | `5000` | HTTP port (webhook receivers / health check) | -| `WEB_SSL_PORT` | `5001` | HTTPS port (admin UI; disabled if no cert) | -| `EGO_SSL_ENABLED` | `1` | Set to `0` to fully disable built-in HTTPS (HTTP only, no redirect, no cert generation) | -| `EGO_SSL_DIR` | `./certs` | SSL certificate directory for `ego.crt` and `ego.key` | -| `EGO_SSL_CERT` | `./certs/ego.crt` | Certificate file path (overrides `EGO_SSL_DIR`) | -| `EGO_SSL_KEY` | `./certs/ego.key` | Private key file path (overrides `EGO_SSL_DIR`) | -| `DB_PATH` | `ego.db` | Database path | -| `LOG_LEVEL` | `INFO` | Log level | -| `EGO_AUTH_TOKEN` | `""` | Bearer token for API auth (empty = no auth) | +Built-in Chinese and English bilingual support, switch languages anytime via language switch button in top-right corner of navigation bar. ## Channel Types | Channel | Method | Type Identifier | -|---------|--------|-----------------| +|------|------|---------| | WeChat Work Bot | Webhook | `wechat_work_bot` | | WeChat Work API | App Message | `wechat_work_api` | | DingTalk | Webhook | `dingtalk` | @@ -118,12 +132,20 @@ After startup: admin UI at `https://:5001` (self-signed cert, accept th | Telegram | Bot API | `telegram_bot` | | Bark | API | `bark` | -## Backup & Restore +## Environment Variables -Available in System Settings: - -- **Backup**: Download ZIP containing `config/*.json` + `parsers/*.py` -- **Restore**: Upload ZIP, config is automatically reloaded +| Variable | Default | Description | +|------|--------|------| +| `WEB_PORT` | `5000` | HTTP port (Webhook receiver / health check) | +| `WEB_SSL_PORT` | `5001` | HTTPS port (Admin page, not enabled when certificate is missing) | +| `EGO_SSL_ENABLED` | `1` | Set to `0` to completely disable built-in HTTPS (HTTP only, no redirect, no certificate generation) | +| `EGO_SSL_DIR` | `./certs` | SSL certificate directory, where `ego.crt` and `ego.key` are stored | +| `EGO_SSL_CERT` | `./certs/ego.crt` | Certificate file path (overrides `EGO_SSL_DIR`) | +| `EGO_SSL_KEY` | `./certs/ego.key` | Private key file path (overrides `EGO_SSL_DIR`) | +| `DB_PATH` | `ego.db` | Database path | +| `LOG_LEVEL` | `INFO` | Log level | +| `EGO_AUTH_TOKEN` | *(empty)* | Access control Token | +| `EGO_SECRET_KEY` | *(auto)* | Flask session key | ## License diff --git a/README.md b/README.md index f3ba311..1d9d45d 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,7 @@ # EverywhereYouGo (EGo) v1.2.3 +[English](README.en.md) | 中文 + > 通用信息转发平台 — 数据 → 解析 → 路由 → 推送 接收任意 HTTP 请求，经解析器提取结构化字段，按条件路由到多个推送渠道。 @@ -17,7 +19,7 @@ chmod +x init.sh 支持 5 种部署模式：default（快速起步）、t1-host（host 网络）、t2-bridge（bridge 网络）、t3-nginx（Nginx + 手动证书）、t4-certbot（Nginx + Let's Encrypt 全自动证书）。 -> 更多部署形态说明见 `deploy/` 目录下的 `README.md`（中文）和 `README.en.md`（英文）。 +> 更多部署形态说明见 [deploy/README.md](deploy/README.md)。 启动后：管理页面 `https://<主机IP>:5001`（自签名证书，浏览器需放行）；Webhook 接收与健康检查走 `http://<主机IP>:5000`。 diff --git a/deploy/README.en.md b/deploy/README.en.md index 222e1c6..65c9413 100644 --- a/deploy/README.en.md +++ b/deploy/README.en.md @@ -1,5 +1,9 @@ # EGo Deployment Configurations +[中文](README.md) | English + +> Back to project home: [README.en.md](../README.en.md) + All Docker Compose configs are in this directory. `default/` is the recommended quick start; `t1`–`t4` correspond to the four deployment tiers in `doc/architecture.md`. Pick one, `cd` into it, and run. | Config | Directory | Network | Admin UI | Certificate | Use Case | diff --git a/deploy/README.md b/deploy/README.md index 5d6716b..95103a3 100644 --- a/deploy/README.md +++ b/deploy/README.md @@ -1,5 +1,9 @@ # EGo 部署配置 +[English](README.en.md) | 中文 + +> 返回项目主页：[README.md](../README.md) + 所有 Docker Compose 配置统一放在本目录。`default/` 是推荐快速起步；`t1`–`t4` 对应 `doc/architecture.md` 部署架构的四个层级。选一套、进入对应目录即可使用。 | 配置 | 目录 | 网络 | 管理页面 | 证书 | 适用场景 |