mirror of
https://github.com/Rain-kl/OpenFlare.git
synced 2026-10-12 10:16:37 +08:00
docs(readme): update project description and deployment instructions
This commit is contained in:
ryan
@@ -2,12 +2,10 @@
|
||||
|
||||
# OpenFlare
|
||||
|
||||
**Next-Gen Distributed Reverse Proxy & Edge Security Gateway for OpenResty / Nginx**
|
||||
|
||||
**[English](./README.md) | [简体中文](./README.zh-CN.md)**
|
||||
|
||||
OpenFlare is an open-source CDN orchestration and edge security platform. It supports reverse proxy, centralized configuration synchronization, in-network tunneling (Tunnels), dynamic WAF protection, and CC defense challenges.
|
||||
|
||||
</div>
|
||||
|
||||
<p align="center">
|
||||
<a href="https://raw.githubusercontent.com/Rain-kl/OpenFlare/main/LICENSE">
|
||||
<img src="https://img.shields.io/github/license/Rain-kl/OpenFlare?color=brightgreen" alt="license">
|
||||
@@ -20,65 +18,120 @@ OpenFlare is an open-source CDN orchestration and edge security platform. It sup
|
||||
</a>
|
||||
</p>
|
||||
|
||||
> [!WARNING]
|
||||
> After the first login with the `admin` user, you must change the default password `12345678`.
|
||||
>
|
||||
> The BETA version is a temporary product in the development and testing stage and may have unknown issues. It should not be used in production environments.
|
||||
</div>
|
||||
|
||||
## Documentation
|
||||
---
|
||||
|
||||
**https://openflare.fyrn.link**
|
||||
## 📖 What is OpenFlare?
|
||||
|
||||
Common entry points:
|
||||
**OpenFlare** is a modern, open-source **distributed reverse proxy and edge security gateway platform** designed for multi-server infrastructures and edge clusters.
|
||||
|
||||
* [Quick Start](https://openflare.fyrn.link/guide/quick-start)
|
||||
* [Deployment Guide](https://openflare.fyrn.link/deployment/deployment)
|
||||
* [Configuration Reference](https://openflare.fyrn.link/reference/configuration)
|
||||
* [System Design](https://openflare.fyrn.link/design/)
|
||||
Rather than a simple single-host admin panel, OpenFlare empowers traditional OpenResty / Nginx nodes with **centralized cluster orchestration, dynamic zero-reload sync, line-rate edge WAF defense, and secure in-network tunneling**:
|
||||
|
||||
## Core Capabilities
|
||||
* ⚡ **Zero-Reload Dynamic Orchestration**: Centralized control plane manages any number of edge nodes. Synchronize rule diffs in milliseconds with zero Nginx reload disruptions.
|
||||
* 🛡️ **Built-in Edge Security & Anti-CC (Turnstile Alternative)**: Comprehensive WAF rule engine, MaxMind GeoIP regional ACLs, and **client-side cryptographic Proof of Work (PoW) challenges** to eliminate botnets and CC attacks at line rate.
|
||||
* 🚇 **Zero-Trust Tunnels (Cloudflare Tunnel Alternative)**: Securely publish private homelab and internal web services to edge proxies via lightweight `openflared` clients without public IPs or open inbound ports.
|
||||
* 📦 **Pages Edge Hosting**: Host static sites and SPAs pulled directly from GitHub Releases or uploaded bundles, distributed across edge nodes with instant rollbacks and fallback routing.
|
||||
* 🔒 **Automated Certificates & SSO**: Automatic multi-domain Let's Encrypt certificates via ACME and enterprise single sign-on with GitHub OAuth and standard OIDC.
|
||||
|
||||
* **Reverse Proxy Configuration Management**: Uses website rules as the aggregation boundary, supports multi-domain binding and multi-upstream load balancing, and centrally manages reverse proxy configurations for all OpenResty nodes.
|
||||
* **Secure In-Network Tunneling (Tunnels)**: Open-source version of Cloudflare Tunnels. No public IP or exposed inbound ports are required. Securely reverse-proxy internal web services to the public internet through Relay relay nodes and OpenFlared clients.
|
||||
* **Edge WAF Security Protection**: Provides global and custom rule groups, supports manual/auto/subscription-type IP groups, MaxMind GeoIP national-level geographic access control, IP group member Checksum differential synchronization (no Nginx reload required), and custom blocking responses.
|
||||
* **CC Defense and Human-Computer Challenge (PoW)**: Built-in high-performance client-side cryptography Proof of Work challenge (similar to Turnstile). Secures high-speed interception and blocking of zombie networks and crawlers at the gateway edge.
|
||||
* **Pages Static Hosting**: Supports uploading or synchronizing pre-built artifacts from restricted Remote URLs or public GitHub Release assets. GitHub latest can be checked periodically and optionally auto-published. All sources are unified to generate immutable deployments, pulled by the edge Agent and served locally by OpenResty, supporting rollbacks, SPA Fallback, and API reverse proxy.
|
||||
* **TLS Certificate Automation**: Supports dynamic certificate uploads, automatic multi-domain certificate matching and binding, and automatic issuance and renewal of certificates from Let's Encrypt via the ACME protocol.
|
||||
* **Uptime Kuma Monitoring Synchronization**: Integrated with Uptime Kuma to automatically perform differential synchronization of monitoring site lists, real-time awareness of node availability and service status.
|
||||
* **SSO Single Sign-On**: Supports GitHub OAuth and standard OIDC protocol for seamless integration with enterprise identity providers to achieve unified login.
|
||||
* **Unified Observability**: Aggregates node request metrics, real-time access log details, host and Nginx resource snapshots, health events, and network fluctuation replenishment buffers.
|
||||
---
|
||||
|
||||
## Interface Preview
|
||||
## 🌐 Flexible Deployment: Standalone or Behind Cloudflare
|
||||
|
||||
OpenFlare is designed to operate seamlessly either as an independent edge gateway or in harmony with Cloudflare and public CDNs:
|
||||
|
||||
### 1. Standalone Edge Gateway (Private CDN)
|
||||
Ideal for developers managing multi-region VPS clusters or homelabs:
|
||||
* Deploy your own high-availability CDN and edge proxy cluster with 100% data and privacy ownership.
|
||||
* Protect origin sites with built-in Turnstile-like PoW human challenges, dynamic WAF, and automated SSL certs without expensive enterprise CDN security plans.
|
||||
|
||||
### 2. Behind Cloudflare (Hardened Origin Shield)
|
||||
Functions as an intelligent **origin shield and routing gateway** behind Cloudflare:
|
||||
* **Leaked Real IP Protection**: If attackers bypass Cloudflare and directly hit your origin's public IP address, OpenFlare's edge WAF and PoW challenges will immediately intercept and block the attack.
|
||||
* **Full Private Log & Metric Retention**: Overcomes Cloudflare Free tier limitations by retaining comprehensive, searchable request logs and operational metrics locally.
|
||||
* **Unified In-Network Routing**: Ingest incoming Cloudflare traffic and dynamically route it across internal backends or private homelab services through secure tunnels.
|
||||
|
||||
---
|
||||
|
||||
## 📊 Comparison: Traditional Nginx vs NPM vs OpenFlare
|
||||
|
||||
| Feature | Traditional Nginx (`nginx.conf`) | Nginx Proxy Manager (NPM) | **OpenFlare** |
|
||||
| :--- | :--- | :--- | :--- |
|
||||
| **Cluster Architecture** | Manual per-host editing via SSH | Single node only; no cluster sync | **Native Distributed Control Plane + Edge Agents** |
|
||||
| **Configuration Sync** | Requires `nginx -s reload` (connection churn) | Reloads on every change | **Shared memory dynamic sync (Zero-Reload)** |
|
||||
| **Anti-CC / Bot Protection** | Basic `limit_req` rate limiting only | Not supported | **Built-in Turnstile-like PoW Client Challenge** |
|
||||
| **In-Network Tunnels** | Requires separate third-party tools (frp) | Not supported | **Built-in OpenFlared Tunnels (Zero inbound ports)** |
|
||||
| **WAF & Threat Defense** | Requires manual ModSecurity compilation | Basic exploit rules only | **Dynamic WAF, GeoIP, IP list checksum sync** |
|
||||
| **Static Pages Hosting** | Manual directory copying and setup | Static file proxying only | **Automated GitHub Release deployment & rollbacks** |
|
||||
| **Works with Cloudflare** | Manual `set_real_ip_from` list maintenance | Complex proxy header tuning | **Native real IP restoration, ideal origin shield** |
|
||||
|
||||
---
|
||||
|
||||
## 🏗️ Architecture
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
subgraph Visitors ["Public Visitors & Clients"]
|
||||
User["Public Users / Browsers"]
|
||||
CF["Cloudflare CDN (Optional Edge Layer)"]
|
||||
end
|
||||
|
||||
subgraph EdgePlane ["Edge Data Plane (OpenResty Agent Nodes)"]
|
||||
Edge1["Edge Node A (OpenResty)"]
|
||||
Edge2["Edge Node B (OpenResty)"]
|
||||
end
|
||||
|
||||
subgraph ControlPlane ["Control Plane"]
|
||||
Server["OpenFlare Server (Web Dashboard)"]
|
||||
DB[("PostgreSQL + Redis")]
|
||||
end
|
||||
|
||||
subgraph Backend ["Upstream & Internal Services"]
|
||||
Origin["Public Origin Web Server"]
|
||||
subgraph PrivateNet ["Private Network / Homelab"]
|
||||
NAS["Internal Apps / NAS"]
|
||||
Client["OpenFlared Tunnel Client"]
|
||||
end
|
||||
end
|
||||
|
||||
User -->|Direct HTTPS Request| Edge1
|
||||
User -->|Proxied via Cloudflare| CF
|
||||
CF -->|Secure Upstream Traffic| Edge2
|
||||
|
||||
Server <-->|Dynamic Sync / Metrics| Edge1
|
||||
Server <-->|Dynamic Sync / Metrics| Edge2
|
||||
Server --- DB
|
||||
|
||||
Edge1 -->|Reverse Proxy| Origin
|
||||
Edge2 -->|Reverse Proxy| Origin
|
||||
|
||||
Client <-->|Encrypted Tunnel| Edge1
|
||||
NAS --- Client
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🖥️ UI Preview
|
||||
|
||||
### Dashboard Overview
|
||||
|
||||
|
||||
|
||||
### Edge WAF & Access Rules
|
||||
|
||||
|
||||
### Access Logs
|
||||
### Domain & Traffic Analytics
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
### WAF Protection
|
||||
## ⚡ Quick Start
|
||||
|
||||
|
||||
### 1. Launch OpenFlare Server
|
||||
|
||||
## Quick Start
|
||||
|
||||
### Hardware Configuration Recommendations
|
||||
|
||||
| Component | Minimum Hardware Requirements | Recommended Hardware Requirements | Notes |
|
||||
|------------------------|-----------------------------------|-----------------------------------|-------|
|
||||
| **Server Control Plane** | 1 CPU core / 2 GB RAM / 20 GB disk | 2 CPU cores / 4 GB RAM / 50 GB+ disk | Disk usage should be expanded reasonably based on access log retention duration and concurrent traffic |
|
||||
| **Agent Data Plane** | 1 CPU core / 512 MB RAM / 2 GB disk | 2 CPU cores / 2 GB RAM / 10 GB+ disk | Expanded based on OpenResty concurrent proxy connections and WAF interception processing |
|
||||
| **Relay Relay Node** | 1 CPU core / 1 GB RAM / 5 GB disk | 2 CPU cores / 2 GB RAM / 20 GB disk | frps transmission relay throughput is mainly limited by bandwidth and CPU throughput |
|
||||
| **OpenFlared Client** | 1 CPU core / 256 MB RAM / 1 GB disk | 1 CPU core / 512 MB RAM / 5 GB disk | Runs independently on the internal network with extremely low resource consumption; only network throughput needs to be guaranteed |
|
||||
|
||||
### 1. Start the Server
|
||||
|
||||
Use `docker-compose`:
|
||||
Deploy the control plane using `docker-compose`:
|
||||
|
||||
```bash
|
||||
# Download environment variable template and create .env file
|
||||
# Download environment template
|
||||
curl -o .env.example https://raw.githubusercontent.com/Rain-kl/OpenFlare/refs/heads/main/.env.example
|
||||
cp .env.example .env
|
||||
```
|
||||
@@ -130,46 +183,69 @@ services:
|
||||
start_period: 5s
|
||||
|
||||
volumes:
|
||||
openflare_uploads:
|
||||
openflare_postgres_data:
|
||||
openflare_redis_data:
|
||||
openflare_uploads:
|
||||
openflare_postgres_data:
|
||||
openflare_redis_data:
|
||||
```
|
||||
|
||||
See the [deployment documentation](https://openflare.fyrn.link/deployment/deployment) for details.
|
||||
* **Dashboard URL**: `http://localhost:3000`
|
||||
* **Default Credentials**: `admin` / `12345678`
|
||||
|
||||
Access address: `http://localhost:3000`
|
||||
> [!WARNING]
|
||||
> Change the default password `12345678` immediately upon first login.
|
||||
> The BETA version is in active development and testing; avoid using it in mission-critical production environments without regular backups.
|
||||
|
||||
Default account:
|
||||
### 2. Connect Edge Agent Node
|
||||
|
||||
* Username: `admin`
|
||||
* Password: `12345678`
|
||||
|
||||
### 2. Install Agent
|
||||
|
||||
Before installing the Agent, first install OpenResty on the node or use the built-in OpenResty Agent Docker image.
|
||||
|
||||
You can copy the installation command from the control panel's **Nodes Management -> Details -> Node Information -> Node ID and Deployment**, or use the script below:
|
||||
|
||||
#### Docker Deployment
|
||||
|
||||
Docker deployment can directly run the Agent image:
|
||||
Run the Agent container on any edge server (ensure ports 80/443 are open):
|
||||
|
||||
```bash
|
||||
docker pull ghcr.io/rain-kl/openflare-agent:latest
|
||||
docker rm -f openflare-agent 2>/dev/null || true
|
||||
docker run -d --name openflare-agent --restart unless-stopped \
|
||||
-p 80:80 -p 443:443/tcp -p 443:443/udp \
|
||||
-v openflare-agent-pages:/data/var/lib/openflare/pages \
|
||||
-e OPENFLARE_SERVER_URL=http://your-server:3000 \
|
||||
-e OPENFLARE_AGENT_TOKEN=YOUR_AGENT_TOKEN \
|
||||
-e OPENFLARE_SERVER_URL=http://<YOUR_SERVER_IP>:3000 \
|
||||
-e OPENFLARE_AGENT_TOKEN=<YOUR_AGENT_TOKEN> \
|
||||
ghcr.io/rain-kl/openflare-agent:latest
|
||||
```
|
||||
*(Copy the node token directly from Node Management in the dashboard)*
|
||||
|
||||
## Open Source License
|
||||
---
|
||||
|
||||
## 📚 Documentation
|
||||
|
||||
Official Documentation: **[https://openflare.fyrn.link](https://openflare.fyrn.link)**
|
||||
|
||||
* [Quick Start](https://openflare.fyrn.link/guide/quick-start)
|
||||
* [Deployment Guide](https://openflare.fyrn.link/deployment/deployment)
|
||||
* [Configuration Reference](https://openflare.fyrn.link/reference/configuration)
|
||||
* [System Design](https://openflare.fyrn.link/design/)
|
||||
|
||||
<details>
|
||||
<summary><b>🔍 Minimum & Recommended Hardware Specifications</b></summary>
|
||||
|
||||
| Component | Minimum Requirements | Recommended Requirements | Note |
|
||||
| :--- | :--- | :--- | :--- |
|
||||
| **Server Control Plane** | 1 CPU / 2 GB RAM / 20 GB Disk | 2 CPU / 4 GB RAM / 50 GB+ Disk | Scale disk based on access log retention |
|
||||
| **Agent Data Plane** | 1 CPU / 512 MB RAM / 2 GB Disk | 2 CPU / 2 GB RAM / 10 GB+ Disk | Scale based on concurrent connections & WAF load |
|
||||
| **Relay Node** | 1 CPU / 1 GB RAM / 5 GB Disk | 2 CPU / 2 GB RAM / 20 GB Disk | Mainly bound by bandwidth and CPU network throughput |
|
||||
| **OpenFlared Client** | 1 CPU / 256 MB RAM / 1 GB Disk | 1 CPU / 512 MB RAM / 5 GB Disk | Extremely lightweight client |
|
||||
|
||||
</details>
|
||||
|
||||
---
|
||||
|
||||
## ⚖️ Trademark Disclaimer
|
||||
|
||||
OpenFlare is an independent, community-driven open-source project. It is not affiliated with, endorsed by, or sponsored by Cloudflare, Inc. Cloudflare and related trademarks are the property of their respective owners.
|
||||
|
||||
---
|
||||
|
||||
## 📄 License
|
||||
|
||||
This project is licensed under the [Apache License 2.0](./LICENSE).
|
||||
|
||||
## Star History
|
||||
## ⭐ Star History
|
||||
|
||||
<a href="https://www.star-history.com/?repos=Rain-kl%2FOpenFlare&type=date&legend=bottom-right">
|
||||
<picture>
|
||||
|
||||
Reference in New Issue
Block a user