OpenFlare/README.en.md

中文 | English

OpenFlare

A lightweight, self-hosted OpenResty control plane for reverse proxy management, configuration rollout, node sync, TLS assets, and practical observability.

OpenFlare 1.0.0 is the current stable baseline. Phase six is complete and fully shipped; the repository documentation now focuses on the living system rather than historical implementation notes.

Why It Exists

OpenFlare is built for a simple but recurring operational need:

• manage domain-to-origin reverse proxy rules from one control plane
• publish immutable OpenResty configuration versions
• let Agents pull, validate, reload, and roll back safely
• manage certificates, domains, node credentials, and version state
• expose practical dashboards for traffic, node health, and rollout status

It is not trying to be a CDN SaaS platform, a multi-tenant control plane, or a general-purpose logging system.

Core Capabilities

• Versioned configuration with preview, publish, activate, and rollback
• Node onboarding with discovery_token or per-node agent_token
• Automated Agent apply flow with openresty -t, reload, and rollback
• Managed OpenResty templates, performance settings, and cache settings
• TLS certificate and domain management with exact and wildcard matching
• Request analytics, node snapshots, and health event reporting
• Controlled Server and Agent upgrade flows
• A production frontend built with Next.js App Router, React 19, and Tailwind CSS 4

Architecture

OpenFlare Server (Gin + GORM + SQLite + Web UI)
        |
        | HTTP API / Config Pull
        v
OpenFlare Agent (register / heartbeat / sync / apply / update)
        |
        v
Local OpenResty or Docker OpenResty
        |
        v
Origin

Responsibilities:

• openflare_server: admin UI, management APIs, Agent APIs, rendering, rollout, and state storage
• openflare_agent: node registration, heartbeat, sync, local apply, validation, reload, rollback, and self-update
• openflare_server/web: the production admin frontend, exported statically and served by the Go server

UI Preview

Dashboard Overview

Node Detail and Install Command

Version Release Workflow

Quick Start

1. Start the Server

services:
  openflare:
    image: ghcr.io/rain-kl/openflare:latest
    restart: unless-stopped
    ports:
      - "3000:3000"
    environment:
      SESSION_SECRET: replace-with-random-string
      SQLITE_PATH: /data/openflare.db
      GIN_MODE: release
      LOG_LEVEL: info
      PORT: "3000"
    volumes:
      - openflare-data:/data

volumes:
  openflare-data:

docker compose up -d

Open http://localhost:3000

Default credentials:

• Username: root
• Password: 123456

2. Install an Agent

First-time registration with discovery_token:

curl -fsSL https://raw.githubusercontent.com/Rain-kl/OpenFlare/main/scripts/install-agent.sh | bash -s -- \
  --server-url http://your-server:3000 \
  --discovery-token YOUR_DISCOVERY_TOKEN

Registration with a per-node agent_token:

curl -fsSL https://raw.githubusercontent.com/Rain-kl/OpenFlare/main/scripts/install-agent.sh | bash -s -- \
  --server-url http://your-server:3000 \
  --agent-token YOUR_AGENT_TOKEN

The installer writes to /opt/openflare-agent by default, creates openflare-agent.service, and can be re-run for reinstall or upgrade.

3. Publish Your First Config

1. Sign in and create a reverse proxy rule
2. Review the preview or diff
3. Activate the new version
4. Wait for Agents to pick it up on the next heartbeat

Version numbers follow YYYYMMDD-NNN. Versions are immutable; rollback is implemented by reactivating an older version.

Repository Layout

• openflare_server: monolithic control plane built with Gin, GORM, and SQLite
• openflare_server/web: admin frontend built with Next.js 15 App Router
• openflare_agent: Go Agent
• scripts: install and helper scripts
• docs: design, guidelines, deployment, and configuration docs

Local Development

Server

cd openflare_server
export SESSION_SECRET='replace-with-random-string'
export SQLITE_PATH='./openflare.db'
go run .

Frontend

cd openflare_server/web
corepack enable
pnpm install
pnpm build

Agent

cd openflare_agent
go run ./cmd/agent -config /path/to/agent.json

Useful Checks

cd openflare_server
GOCACHE=/tmp/openflare-go-cache go test ./...

cd openflare_agent
GOCACHE=/tmp/openflare-go-cache go test ./...

Admin Surface

The admin UI currently covers:

• reverse proxy rules
• config versions
• node management
• apply logs
• TLS certificates
• domain management
• user management
• settings
• version upgrades

Swagger UI is available at /swagger/index.html after login.

License

OpenFlare is released under the Apache License 2.0.