From 244a43ba77c8bb6a1433afec1a0725ad6ee4443a Mon Sep 17 00:00:00 2001 From: ryan Date: Tue, 17 Mar 2026 19:22:36 +0800 Subject: [PATCH] =?UTF-8?q?=E6=9B=B4=E6=96=B0README?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.en.md | 243 --------------------------------------------------- README.md | 33 ++----- 2 files changed, 5 insertions(+), 271 deletions(-) delete mode 100644 README.en.md diff --git a/README.en.md b/README.en.md deleted file mode 100644 index 0b95e28b..00000000 --- a/README.en.md +++ /dev/null @@ -1,243 +0,0 @@ -

- 中文 | English -

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

- - license - - - release - - - ghcr - - - GoReportCard - -

- -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 - -```text -OpenFlare Server (Gin + GORM + SQLite/PostgreSQL + 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 - -![OpenFlare dashboard overview](./docs/assets/readme/dashboard-overview.png) - -### Node Detail and Install Command - -![OpenFlare node detail](./docs/assets/readme/node-detail.png) - -### Version Release Workflow - -![OpenFlare version release](./docs/assets/readme/version-release.png) - -## Quick Start - -### 1. Start the Server - -```yaml -services: - postgres: - image: postgres:17-alpine - restart: unless-stopped - environment: - POSTGRES_DB: openflare - POSTGRES_USER: openflare - POSTGRES_PASSWORD: replace-with-strong-password - volumes: - - postgres-data:/var/lib/postgresql/data - healthcheck: - test: ["CMD-SHELL", "pg_isready -U openflare -d openflare"] - interval: 10s - timeout: 5s - retries: 5 - - openflare: - image: ghcr.io/rain-kl/openflare:latest - restart: unless-stopped - depends_on: - postgres: - condition: service_healthy - ports: - - "3000:3000" - environment: - SESSION_SECRET: replace-with-random-string - SQLITE_PATH: /data/openflare.db - DSN: postgres://openflare:replace-with-strong-password@postgres:5432/openflare?sslmode=disable - GIN_MODE: release - LOG_LEVEL: info - PORT: "3000" - volumes: - - openflare-data:/data - -volumes: - postgres-data: - openflare-data: -``` - -```bash -docker compose up -d -``` - -Open `http://localhost:3000` - -Default credentials: - -* Username: `root` -* Password: `123456` - -### 2. Install an Agent - -First-time registration with `discovery_token`: - -```bash -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`: - -```bash -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/PostgreSQL -* `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 - -```bash -cd openflare_server -export SESSION_SECRET='replace-with-random-string' -export SQLITE_PATH='./openflare.db' -# Optional: switch to PostgreSQL by setting either DSN or SQL_DSN. -# If the PostgreSQL database is empty and ./openflare.db exists, -# OpenFlare migrates SQLite data automatically at startup. -# export DSN='postgres://openflare:secret@127.0.0.1:5432/openflare?sslmode=disable' -go run . -``` - -### Frontend - -```bash -cd openflare_server/web -corepack enable -pnpm install -pnpm build -``` - -### Agent - -```bash -cd openflare_agent -go run ./cmd/agent -config /path/to/agent.json -``` - -### Useful Checks - -```bash -cd openflare_server -GOCACHE=/tmp/openflare-go-cache go test ./... -``` - -```bash -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](./LICENSE). diff --git a/README.md b/README.md index 6711ce0d..a2b7b067 100644 --- a/README.md +++ b/README.md @@ -21,13 +21,8 @@ ghcr - - GoReportCard -

-OpenFlare `1.0.0` 是当前稳定基线。第六版开发工作已经完成，相关能力已并入正式版，仓库文档不再保留阶段性实施记录，而只维护当前有效的设计、约束和部署方式。 - ## 为什么存在 OpenFlare 解决的是一类朴素但高频的运维问题： @@ -38,18 +33,13 @@ OpenFlare 解决的是一类朴素但高频的运维问题： * 统一托管证书、域名、节点凭证与版本状态 * 提供足够实用的总览、节点详情与访问分析能力 -它不是 CDN SaaS，也不试图在 1.0 阶段演变成多租户平台、日志平台或通用调度系统。 - ## 核心能力 -* 配置版本化：支持预览、发布、激活、历史回滚，版本不可变 -* 节点接入：支持全局 `discovery_token` 首次接入，也支持节点专属 `agent_token` +* 配置版本化：支持预览、发布、激活、历史回滚 * Agent 自动应用：周期性同步、落盘、`openresty -t`、`openresty -s reload`、失败自动回滚 * OpenResty 托管：统一管理主配置模板、性能参数、缓存参数与受管路由 * TLS 与域名管理：支持证书托管、域名资产维护、精确匹配与通配符匹配 * 访问与节点观测：支持请求窗口聚合、状态码分布、来源分布、节点资源与健康事件展示 -* 版本运维：支持 Server 与 Agent 的正式版升级，以及受控的 preview 检查与手动升级 -* 管理端 UI：基于 Next.js App Router、React 19、Tailwind CSS 4 的正式前端 ## 系统架构 @@ -79,11 +69,11 @@ Origin ![OpenFlare dashboard overview](./docs/assets/readme/dashboard-overview.png) -### 节点详情与安装命令 +### 节点详情 ![OpenFlare node detail](./docs/assets/readme/node-detail.png) -### 配置发布与版本管理 +### 配置新增 ![OpenFlare version release](./docs/assets/readme/version-release.png) @@ -142,7 +132,7 @@ docker compose up -d ### 2. 接入 Agent -使用 `discovery_token` 首次接入： +使用 `discovery_token` 接入： ```bash curl -fsSL https://raw.githubusercontent.com/Rain-kl/OpenFlare/main/scripts/install-agent.sh | bash -s -- \ @@ -195,9 +185,8 @@ go run . ```bash cd openflare_server/web -corepack enable pnpm install -pnpm build +pnpm dev ``` ### Agent @@ -207,18 +196,6 @@ cd openflare_agent go run ./cmd/agent -config /path/to/agent.json ``` -### 常用验证命令 - -```bash -cd openflare_server -GOCACHE=/tmp/openflare-go-cache go test ./... -``` - -```bash -cd openflare_agent -GOCACHE=/tmp/openflare-go-cache go test ./... -``` - ## 文档导航 建议按以下顺序阅读：