mirror of
https://github.com/Rain-kl/OpenFlare.git
synced 2026-09-28 05:46:36 +08:00
[文档] 文档更新
This commit is contained in:
ryan
+215
-151
@@ -1,155 +1,219 @@
|
||||
<p align="right">
|
||||
<a href="./README.md">中文</a> | <strong>English</strong>
|
||||
</p>
|
||||
|
||||
<div align="center">
|
||||
|
||||
# OpenFlare
|
||||
|
||||
_✨ control plane for reverse proxy management ✨_
|
||||
|
||||
</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">
|
||||
</a>
|
||||
<a href="https://github.com/Rain-kl/OpenFlare/releases/latest">
|
||||
<img src="https://img.shields.io/github/v/release/Rain-kl/OpenFlare?color=brightgreen&include_prereleases" alt="release">
|
||||
</a>
|
||||
<a href="https://github.com/Rain-kl/OpenFlare/releases/latest">
|
||||
<img src="https://img.shields.io/github/downloads/Rain-kl/OpenFlare/total?color=brightgreen&include_prereleases" alt="release">
|
||||
</a>
|
||||
<a href="https://goreportcard.com/report/github.com/Rain-kl/OpenFlare">
|
||||
<img src="https://goreportcard.com/badge/github.com/Rain-kl/OpenFlare" alt="GoReportCard">
|
||||
</a>
|
||||
</p>
|
||||
|
||||
## Repository layout
|
||||
|
||||
- `openflare_server`: Gin + GORM + SQLite control plane, including admin API, Agent API and Web UI
|
||||
- `openflare_agent`: single-binary Go Agent for registration, heartbeat, config sync and OpenResty reload
|
||||
- `docs`: design, development guidelines, implementation plan and deployment docs
|
||||
|
||||
## Quick start
|
||||
|
||||
### 1. Start the Server
|
||||
|
||||
The fastest way is to run the published GHCR image with Docker Compose:
|
||||
|
||||
```yaml
|
||||
services:
|
||||
openflare:
|
||||
image: ghcr.io/rain-kl/openflare:latest
|
||||
container_name: openflare
|
||||
restart: unless-stopped
|
||||
ports:
|
||||
- "3000:3000"
|
||||
environment:
|
||||
SESSION_SECRET: replace-with-random-string
|
||||
SQLITE_PATH: /data/openflare.db
|
||||
GIN_MODE: release
|
||||
volumes:
|
||||
- openflare-data:/data
|
||||
|
||||
volumes:
|
||||
openflare-data:
|
||||
```
|
||||
|
||||
```bash
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
Default URL: `http://localhost:3000`
|
||||
|
||||
Notes:
|
||||
|
||||
* Replace `SESSION_SECRET` with a random string
|
||||
* Replace `latest` with a fixed version tag if needed, for example `ghcr.io/rain-kl/openflare:v0.3.0`
|
||||
* SQLite data is persisted in the Docker volume `openflare-data`
|
||||
* For source build and full deployment steps, see [docs/deployment.md](./docs/deployment.md)
|
||||
|
||||
### 1.1 Server environment variables
|
||||
|
||||
Common environment variables:
|
||||
|
||||
| Variable | Description | Default behavior |
|
||||
| --- | --- | --- |
|
||||
| `PORT` | Server listen port | Defaults to `3000` |
|
||||
| `GIN_MODE` | Gin runtime mode | Runs in release mode unless set to `debug` |
|
||||
| `SESSION_SECRET` | Session signing secret; should be set explicitly in production | Falls back to the built-in default |
|
||||
| `SQLITE_PATH` | SQLite database file path | Uses the built-in SQLite path |
|
||||
| `SQL_DSN` | MySQL DSN; when set, MySQL is used instead of SQLite | Uses SQLite when unset |
|
||||
| `REDIS_CONN_STRING` | Redis connection string for session/rate-limit related features | Redis is disabled when unset |
|
||||
| `UPLOAD_PATH` | Upload directory path | Defaults to `upload` |
|
||||
| `AGENT_TOKEN` | Legacy/global Agent token compatibility setting | Not required in the current default setup |
|
||||
|
||||
Example:
|
||||
|
||||
```bash
|
||||
export SESSION_SECRET='replace-with-random-string'
|
||||
export SQLITE_PATH='./openflare.db'
|
||||
export GIN_MODE='release'
|
||||
export PORT='3000'
|
||||
```
|
||||
|
||||
### 2. Install Agent with Discovery Token
|
||||
|
||||
Use this for first-time node bootstrap. The Agent will auto-register with `discovery_token` and exchange it for a node-specific `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 \
|
||||
--discovery-token YOUR_DISCOVERY_TOKEN
|
||||
```
|
||||
|
||||
### 3. Install Agent with Agent Token
|
||||
|
||||
Use this when the node has already been created in the control plane and you already have a dedicated `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
|
||||
```
|
||||
|
||||
Notes:
|
||||
|
||||
* Replace `--server-url` with your actual control plane address, for example `http://192.168.1.10:3000`
|
||||
* On Linux, the installer defaults to `/opt/openflare-agent` and creates the `openflare-agent` systemd service
|
||||
* Re-running the same command upgrades the Agent to the latest release
|
||||
|
||||
## Delivery channels
|
||||
<p align="right">
|
||||
<a href="./README.md">中文</a> | <strong>English</strong>
|
||||
</p>
|
||||
|
||||
Current release outputs:
|
||||
|
||||
* Server binaries: GitHub Releases
|
||||
* Server Docker image: GitHub Container Registry at `ghcr.io/rain-kl/openflare`
|
||||
* Agent binaries: GitHub Releases
|
||||
<div align="center">
|
||||
<img src="./openflare_server/web/public/logo.png" width="120" height="120" alt="OpenFlare logo">
|
||||
|
||||
# OpenFlare
|
||||
|
||||
A lightweight, self-hosted OpenResty control plane for reverse proxy management, configuration rollout, node sync, TLS assets, and practical observability.
|
||||
|
||||
</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">
|
||||
</a>
|
||||
<a href="https://github.com/Rain-kl/OpenFlare/releases/latest">
|
||||
<img src="https://img.shields.io/github/v/release/Rain-kl/OpenFlare?color=brightgreen&include_prereleases" alt="release">
|
||||
</a>
|
||||
<a href="https://github.com/Rain-kl/OpenFlare/pkgs/container/openflare">
|
||||
<img src="https://img.shields.io/badge/GHCR-ghcr.io%2Frain--kl%2Fopenflare-brightgreen" alt="ghcr">
|
||||
</a>
|
||||
<a href="https://goreportcard.com/report/github.com/Rain-kl/OpenFlare">
|
||||
<img src="https://goreportcard.com/badge/github.com/Rain-kl/OpenFlare" alt="GoReportCard">
|
||||
</a>
|
||||
</p>
|
||||
|
||||
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 + 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
|
||||
|
||||
```yaml
|
||||
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:
|
||||
```
|
||||
|
||||
```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
|
||||
* `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'
|
||||
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 licensed under the [Apache License 2.0](./LICENSE) and ships with a repository-level [NOTICE](./NOTICE).
|
||||
|
||||
If you redistribute modified versions, keep the license text, copyright notices and any required NOTICE attributions.
|
||||
|
||||
## Contributing
|
||||
|
||||
Before contributing, please read the project docs listed below.
|
||||
|
||||
Unless explicitly stated otherwise, any contribution intentionally submitted for inclusion in this repository is provided under Apache License 2.0.
|
||||
|
||||
## Documentation
|
||||
|
||||
See:
|
||||
|
||||
1. [docs/deployment.md](./docs/deployment.md)
|
||||
2. [docs/design.md](./docs/design.md)
|
||||
3. [docs/development-guidelines.md](./docs/development-guidelines.md)
|
||||
4. [docs/development-plan.md](./docs/development-plan.md)
|
||||
|
||||
Frontend notes:
|
||||
|
||||
* The new admin frontend lives in `openflare_server/web`
|
||||
* `pnpm` is the default package manager
|
||||
* `pnpm build` exports static assets into `openflare_server/web/build`
|
||||
OpenFlare is released under the [Apache License 2.0](./LICENSE).
|
||||
|
||||
@@ -7,7 +7,7 @@
|
||||
|
||||
# OpenFlare
|
||||
|
||||
轻量、自托管的反向代理控制面，用于管理 Nginx 配置发布、节点同步、TLS 证书与版本回滚。
|
||||
轻量、自托管的 OpenResty 控制面，用于管理反向代理规则、配置发布、节点同步、TLS 证书与基础可观测能力。
|
||||
|
||||
</div>
|
||||
|
||||
@@ -26,39 +26,55 @@
|
||||
</a>
|
||||
</p>
|
||||
|
||||
## 项目定位
|
||||
OpenFlare `1.0.0` 是当前稳定基线。第六版开发工作已经完成，相关能力已并入正式版，仓库文档不再保留阶段性实施记录，而只维护当前有效的设计、约束和部署方式。
|
||||
|
||||
OpenFlare 当前定位为内部自用的反向代理控制面，不面向外部租户提供 CDN SaaS 能力。
|
||||
## 为什么存在
|
||||
|
||||
它解决的是一套更直接的运维问题：
|
||||
OpenFlare 解决的是一类朴素但高频的运维问题：
|
||||
|
||||
* 在管理端维护域名到源站的反代规则
|
||||
* 生成完整 Nginx 配置并发布激活版本
|
||||
* 在一个管理端里维护域名到源站的反向代理规则
|
||||
* 生成完整 OpenResty 配置并以不可变版本发布
|
||||
* 让节点侧 Agent 自动拉取、校验、reload 与失败回滚
|
||||
* 托管 TLS 证书、管理节点与版本状态
|
||||
* 用更统一的 Web UI 完成日常运维操作
|
||||
* 统一托管证书、域名、节点凭证与版本状态
|
||||
* 提供足够实用的总览、节点详情与访问分析能力
|
||||
|
||||
当前明确不做多租户、复杂缓存平台、对象存储依赖、灰度分组发布等平台化扩展。详细边界见 [docs/design.md](./docs/design.md)。
|
||||
它不是 CDN SaaS，也不试图在 1.0 阶段演变成多租户平台、日志平台或通用调度系统。
|
||||
|
||||
## 核心能力
|
||||
|
||||
* 反向代理规则管理：一个域名对应一个源站地址，统一维护、统一发布
|
||||
* 配置版本化：支持预览、发布、激活、历史回滚，版本不可变
|
||||
* 节点接入：支持全局 `discovery_token` 首次接入，也支持节点专属 `agent_token`
|
||||
* Agent 自动应用：周期性同步、落盘、`openresty -t`、`openresty -s reload`、失败自动回滚
|
||||
* 节点观测：Agent 会向受管 OpenResty 注入 Lua 观测脚本，按 heartbeat 上报最近窗口请求、错误、UV 与连接指标
|
||||
* OpenResty 托管：统一管理主配置模板、性能参数、缓存参数与受管路由
|
||||
* TLS 与域名管理：支持证书托管、域名资产维护、精确匹配与通配符匹配
|
||||
* 运维能力：配置变更摘要、Agent 运行参数下发、Agent 正式版自动更新与 preview 手动升级、Server 正式版 GitHub 自升级、Server preview 手动检查升级、Server 手动上传二进制确认升级
|
||||
* 管理端 UI：基于 Next.js App Router + React 19 + Tailwind CSS 4 的新版前端
|
||||
* 访问与节点观测：支持请求窗口聚合、状态码分布、来源分布、节点资源与健康事件展示
|
||||
* 版本运维：支持 Server 与 Agent 的正式版升级，以及受控的 preview 检查与手动升级
|
||||
* 管理端 UI：基于 Next.js App Router、React 19、Tailwind CSS 4 的正式前端
|
||||
|
||||
## 系统架构
|
||||
|
||||
```text
|
||||
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
|
||||
```
|
||||
|
||||
职责划分：
|
||||
|
||||
* `openflare_server`：管理端 UI、管理 API、Agent API、配置渲染、版本发布与状态存储
|
||||
* `openflare_agent`：节点注册、心跳、同步、本地写入、校验、reload、回滚、自更新
|
||||
* `openflare_server/web`：新版管理端前端，静态导出后由 Go Server 托管
|
||||
|
||||
## 界面预览
|
||||
|
||||
以下图片当前为占位文件，后续你可以直接替换同名文件：
|
||||
|
||||
* `docs/assets/readme/dashboard-overview.svg`
|
||||
* `docs/assets/readme/node-detail.svg`
|
||||
* `docs/assets/readme/version-release.svg`
|
||||
|
||||
### 仪表盘总览
|
||||
|
||||
|
||||
@@ -71,39 +87,9 @@ OpenFlare 当前定位为内部自用的反向代理控制面，不面向外部
|
||||
|
||||
|
||||
|
||||
## 系统架构
|
||||
|
||||
```text
|
||||
OpenFlare Server (Gin + GORM + SQLite + Web UI)
|
||||
|
|
||||
| HTTP API / Config Pull
|
||||
v
|
||||
OpenFlare Agent (register / heartbeat / sync / apply / update)
|
||||
|
|
||||
v
|
||||
Local Nginx or Docker Nginx
|
||||
|
|
||||
v
|
||||
Origin
|
||||
```
|
||||
|
||||
职责划分：
|
||||
|
||||
* `openflare_server`：管理端 UI、管理 API、Agent API、配置渲染、发布与激活、状态存储
|
||||
* `openflare_agent`：节点注册、心跳、同步、本地文件写入、Nginx 校验、reload、回滚、自更新
|
||||
* `openflare_server/web`：新版管理端前端，静态导出后由 Go Server 托管
|
||||
|
||||
## 仓库结构
|
||||
|
||||
* `openflare_server`：Gin + GORM + SQLite 单体控制面
|
||||
* `openflare_server/web`：Next.js 15 App Router 管理端前端
|
||||
* `openflare_agent`：Go 单体 Agent
|
||||
* `scripts`：安装脚本与辅助脚本
|
||||
* `docs`：设计、开发规范、部署、配置项等文档
|
||||
|
||||
## 快速开始
|
||||
|
||||
### 1. 通过 Docker Compose 启动 Server
|
||||
### 1. 启动 Server
|
||||
|
||||
```yaml
|
||||
services:
|
||||
@@ -136,9 +122,9 @@ docker compose up -d
|
||||
* 用户名：`root`
|
||||
* 密码：`123456`
|
||||
|
||||
### 2. 使用 Discovery Token 一键接入 Agent
|
||||
### 2. 接入 Agent
|
||||
|
||||
适用于新节点首次接入，Agent 会自动注册并换取节点专属 `agent_token`。
|
||||
使用 `discovery_token` 首次接入：
|
||||
|
||||
```bash
|
||||
curl -fsSL https://raw.githubusercontent.com/Rain-kl/OpenFlare/main/scripts/install-agent.sh | bash -s -- \
|
||||
@@ -146,9 +132,7 @@ curl -fsSL https://raw.githubusercontent.com/Rain-kl/OpenFlare/main/scripts/inst
|
||||
--discovery-token YOUR_DISCOVERY_TOKEN
|
||||
```
|
||||
|
||||
### 3. 使用 Agent Token 一键接入 Agent
|
||||
|
||||
适用于已经在管理端预创建节点、并拿到节点专属 `agent_token` 的场景。
|
||||
使用节点专属 `agent_token`：
|
||||
|
||||
```bash
|
||||
curl -fsSL https://raw.githubusercontent.com/Rain-kl/OpenFlare/main/scripts/install-agent.sh | bash -s -- \
|
||||
@@ -156,74 +140,24 @@ curl -fsSL https://raw.githubusercontent.com/Rain-kl/OpenFlare/main/scripts/inst
|
||||
--agent-token YOUR_AGENT_TOKEN
|
||||
```
|
||||
|
||||
说明：
|
||||
安装脚本默认写入 `/opt/openflare-agent`，创建 `openflare-agent.service`，并可重复执行以重装或升级 Agent。
|
||||
|
||||
* `--server-url` 替换为实际控制面地址，例如 `http://192.168.1.10:3000`
|
||||
* 默认安装目录为 `/opt/openflare-agent`
|
||||
* 脚本会创建 `openflare-agent.service` 并启动 systemd 服务
|
||||
* 重复执行安装命令可用于重装或升级 Agent 到最新 Release
|
||||
* 重装时会先删除整个安装目录，再重新生成 `agent.json`、本地状态和二进制；旧数据不会保留
|
||||
### 3. 发布第一份配置
|
||||
|
||||
## 典型使用流程
|
||||
1. 登录管理端并新增反代规则
|
||||
2. 在发布前查看预览或变更摘要
|
||||
3. 激活新版本
|
||||
4. 等待 Agent 在后续 heartbeat 中拉取并应用配置
|
||||
|
||||
1. 启动 Server 并登录管理端
|
||||
2. 新增或编辑反代规则
|
||||
3. 预览配置或查看变更摘要
|
||||
4. 发布并激活新的配置版本
|
||||
5. Agent 在后续同步中拉取激活版本
|
||||
6. Agent 本地执行 `nginx -t`
|
||||
7. 校验成功后执行 `nginx -s reload`
|
||||
8. 若失败则自动回滚并上报最终结果
|
||||
版本号格式固定为 `YYYYMMDD-NNN`，历史版本不可变，回滚通过重新激活旧版本完成。
|
||||
|
||||
版本号格式固定为 `YYYYMMDD-NNN`，历史版本不可变，回滚通过重新激活旧版本实现。
|
||||
## 仓库结构
|
||||
|
||||
## 部署与交付
|
||||
|
||||
当前仓库的交付形式：
|
||||
|
||||
* Server 二进制发布到 GitHub Releases
|
||||
* Server Docker 镜像发布到 GitHub Container Registry：`ghcr.io/rain-kl/openflare`
|
||||
* Agent 二进制发布到 GitHub Releases
|
||||
|
||||
Docker 镜像工作流仅构建 `openflare_server`，并产出 `linux/amd64` 与 `linux/arm64` 多架构镜像。
|
||||
|
||||
## 常用配置
|
||||
|
||||
### Server 环境变量
|
||||
|
||||
| 环境变量 | 作用 | 默认值 |
|
||||
| --- | --- | --- |
|
||||
| `PORT` | Server 监听端口 | `3000` |
|
||||
| `GIN_MODE` | Gin 运行模式 | 非 `debug` 时按 release |
|
||||
| `SESSION_SECRET` | Session 签名密钥 | 启动时随机生成 |
|
||||
| `SQLITE_PATH` | SQLite 数据库文件路径 | `openflare.db` |
|
||||
| `SQL_DSN` | MySQL DSN，设置后优先于 SQLite | 空 |
|
||||
| `UPLOAD_PATH` | 上传目录 | `upload` |
|
||||
|
||||
### 前端构建变量
|
||||
|
||||
| 环境变量 | 作用 | 默认值 |
|
||||
| --- | --- | --- |
|
||||
| `NEXT_PUBLIC_API_BASE_URL` | 前端请求 API 的基础路径 | `/api` |
|
||||
| `NEXT_PUBLIC_APP_VERSION` | 前端展示版本号 | `dev` |
|
||||
|
||||
### Agent 核心配置
|
||||
|
||||
| 字段 | 作用 |
|
||||
| --- | --- |
|
||||
| `server_url` | 控制面地址 |
|
||||
| `agent_token` | 节点专属认证 Token |
|
||||
| `discovery_token` | 首次自动注册使用的全局 Token |
|
||||
| `data_dir` | Agent 托管数据目录 |
|
||||
| `cert_dir` | Agent 存放受管证书文件的目录 |
|
||||
| `lua_dir` | Agent 存放受管 Lua 观测脚本的目录；启动时自动覆盖释放 |
|
||||
| `openresty_observability_port` | Agent 读取 OpenResty Lua 本地观测指标的 loopback 端口 |
|
||||
| `observability_buffer_path` | Agent 本地观测补报缓冲文件路径 |
|
||||
| `observability_replay_minutes` | Agent 恢复 heartbeat 后允许自动补传的最近观测窗口分钟数 |
|
||||
| `nginx_path` | 本机 Nginx 路径，设置后走本机模式 |
|
||||
| `nginx_container_name` | Docker 模式下的 Nginx 容器名 |
|
||||
|
||||
完整配置项说明见 [docs/app-config.md](./docs/app-config.md)。
|
||||
* `openflare_server`：Gin + GORM + SQLite 单体控制面
|
||||
* `openflare_server/web`：Next.js 15 App Router 管理端前端
|
||||
* `openflare_agent`：Go 单体 Agent
|
||||
* `scripts`：安装脚本与辅助脚本
|
||||
* `docs`：设计、规范、部署与配置文档
|
||||
|
||||
## 本地开发
|
||||
|
||||
@@ -294,22 +228,4 @@ GOCACHE=/tmp/openflare-go-cache go test ./...
|
||||
|
||||
## 开源协议
|
||||
|
||||
本项目采用 [Apache License 2.0](./LICENSE) 开源，并附带仓库级 [NOTICE](./NOTICE)。
|
||||
|
||||
这意味着你可以在遵守 Apache 2.0 条款的前提下使用、修改和分发 OpenFlare；如果你分发修改版，请保留许可证、版权声明和必要的 NOTICE 信息。
|
||||
|
||||
## 贡献开发
|
||||
|
||||
参与开发前请先阅读：
|
||||
|
||||
* [docs/design.md](./docs/design.md)
|
||||
* [docs/development-guidelines.md](./docs/development-guidelines.md)
|
||||
* [docs/frontend-development-guidelines.md](./docs/frontend-development-guidelines.md)
|
||||
|
||||
约束摘要：
|
||||
|
||||
* 超出设计边界的改动，先更新设计文档再编码
|
||||
* Server 继续保持单体结构，不为简单需求引入额外基础设施
|
||||
* 前端统一位于 `openflare_server/web`，请求层统一收敛到 `lib/api/`
|
||||
* 新代码默认遵循当前正式基线，不回退到旧版 CRA / Semantic UI 结构
|
||||
* 除非贡献说明中另有明确约定，向本仓库提交的代码、文档或其他内容，默认按 Apache License 2.0 授权
|
||||
本项目采用 [Apache License 2.0](./LICENSE) 开源。
|
||||
+136
-372
@@ -1,387 +1,151 @@
|
||||
# OpenFlare 配置项说明
|
||||
|
||||
本文档汇总当前 OpenFlare Server 与 Agent 在启动、部署和运行时支持的参数、环境变量与配置文件字段，并说明其作用、默认值和示例。
|
||||
|
||||
---
|
||||
|
||||
## 1. Server 配置
|
||||
|
||||
Server 当前支持两类启动配置：
|
||||
|
||||
1. 命令行参数
|
||||
2. 环境变量
|
||||
|
||||
此外，部分运行时参数已迁入数据库 `Option` 表，可在管理端设置页中热更新，例如 Agent 运行参数与限流阈值。
|
||||
|
||||
第五版（0.5.x）继续复用 `Option` 表承载 OpenResty 性能优化参数与缓存参数，不单独引入新的配置中心。
|
||||
|
||||
### 1.1 Server 命令行参数
|
||||
|
||||
启动示例：
|
||||
|
||||
```bash
|
||||
cd openflare_server
|
||||
go run . --port 3000 --log-dir ./logs
|
||||
```
|
||||
|
||||
或在编译后二进制中使用：
|
||||
|
||||
```bash
|
||||
./openflare --port 3000 --log-dir ./logs
|
||||
```
|
||||
|
||||
支持的命令行参数：
|
||||
|
||||
| 参数 | 作用 | 默认值 | 示例 |
|
||||
| --- | --- | --- | --- |
|
||||
| `--port` | 指定 Server 监听端口 | `3000` | `--port 3000` |
|
||||
| `--log-dir` | 指定日志目录；设置后会自动创建目录并写入日志 | 空，默认输出到 stdout | `--log-dir ./logs` |
|
||||
| `--version` | 输出当前版本后退出 | `false` | `./openflare --version` |
|
||||
| `--help` | 输出帮助信息后退出 | `false` | `./openflare --help` |
|
||||
|
||||
说明：
|
||||
|
||||
* 当同时设置 `PORT` 环境变量与 `--port` 时，运行时优先使用 `PORT`
|
||||
* `--log-dir` 当前没有对应环境变量，适合源码运行或 systemd 方式部署时使用
|
||||
|
||||
### 1.2 Server 环境变量
|
||||
|
||||
源码启动示例：
|
||||
|
||||
```bash
|
||||
cd openflare_server
|
||||
export SESSION_SECRET='replace-with-random-string'
|
||||
export SQLITE_PATH='./openflare.db'
|
||||
export GIN_MODE='release'
|
||||
export LOG_LEVEL='info'
|
||||
export PORT='3000'
|
||||
go run .
|
||||
```
|
||||
|
||||
Docker Compose 示例：
|
||||
|
||||
```yaml
|
||||
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:
|
||||
```
|
||||
|
||||
支持的环境变量：
|
||||
|
||||
| 环境变量 | 作用 | 默认值 | 示例 |
|
||||
| --- | --- | --- | --- |
|
||||
| `PORT` | 指定 Server 实际监听端口 | `3000` | `PORT=3000` |
|
||||
| `GIN_MODE` | 指定 Gin 运行模式；仅当值为 `debug` 时启用 debug，其余情况按 release 运行 | 非 `debug` 默认按 release 运行 | `GIN_MODE=release` |
|
||||
| `LOG_LEVEL` | 指定系统日志等级；支持 `debug`/`info`/`warn`/`error`（`warning` 兼容为 `warn`） | `info` | `LOG_LEVEL=warn` |
|
||||
| `SESSION_SECRET` | Session 签名密钥；生产环境必须显式设置，避免重启后会话失效 | 启动时随机生成 UUID | `SESSION_SECRET=replace-with-random-string` |
|
||||
| `SQLITE_PATH` | SQLite 数据库文件路径 | `openflare.db` | `SQLITE_PATH=/data/openflare.db` |
|
||||
| `SQL_DSN` | MySQL DSN；设置后优先使用 MySQL，而不是 SQLite | 未设置时使用 SQLite | `SQL_DSN=user:pass@tcp(127.0.0.1:3306)/openflare` |
|
||||
| `REDIS_CONN_STRING` | Redis 连接串；设置后启用 Redis，用于 Session/限流相关能力 | 未设置时关闭 Redis | `REDIS_CONN_STRING=redis://default:pass@127.0.0.1:6379/0` |
|
||||
| `UPLOAD_PATH` | 上传文件目录 | `upload` | `UPLOAD_PATH=/data/upload` |
|
||||
| `AGENT_TOKEN` | 全局 Agent Token 兼容配置；当前默认部署不依赖该变量 | 空 | `AGENT_TOKEN=legacy-shared-token` |
|
||||
|
||||
说明：
|
||||
|
||||
* `SQL_DSN` 与 `SQLITE_PATH` 同时存在时，优先使用 `SQL_DSN`
|
||||
* `SESSION_SECRET` 未固定时，每次重启都会生成新的随机值，已登录用户的 Cookie 会失效
|
||||
* `LOG_LEVEL` 未设置或设置为不支持的值时，将回退为 `info`
|
||||
* `REDIS_CONN_STRING` 未配置时，相关能力将回退为进程内实现
|
||||
* `UPLOAD_PATH` 目录在启动时若不存在会自动创建
|
||||
|
||||
### 1.2.1 设置页可热更新的运行时配置
|
||||
|
||||
以下配置不依赖环境变量，保存在数据库 `Option` 表中，可在管理端设置页的「运维设置」中调整，并在保存后立即生效：
|
||||
|
||||
| 配置项 | 作用 | 默认值 |
|
||||
| --- | --- | --- |
|
||||
# OpenFlare 配置项说明
|
||||
|
||||
本文档汇总 OpenFlare `1.0.0` 当前支持的 Server 与 Agent 配置项，只保留仍然有效的启动、部署与运行参数。
|
||||
|
||||
## 1. Server 配置
|
||||
|
||||
Server 支持三类配置来源：
|
||||
|
||||
1. 命令行参数
|
||||
2. 环境变量
|
||||
3. 数据库 `Option` 表中的运行时配置
|
||||
|
||||
### 1.1 命令行参数
|
||||
|
||||
```bash
|
||||
cd openflare_server
|
||||
go run . --port 3000 --log-dir ./logs
|
||||
```
|
||||
|
||||
| 参数 | 作用 | 默认值 |
|
||||
| --- | --- | --- |
|
||||
| `--port` | 指定 Server 监听端口 | `3000` |
|
||||
| `--log-dir` | 指定日志目录 | 空 |
|
||||
| `--version` | 输出当前版本后退出 | `false` |
|
||||
| `--help` | 输出帮助信息后退出 | `false` |
|
||||
|
||||
### 1.2 环境变量
|
||||
|
||||
| 环境变量 | 作用 | 默认值 |
|
||||
| --- | --- | --- |
|
||||
| `PORT` | Server 监听端口 | `3000` |
|
||||
| `GIN_MODE` | Gin 运行模式 | 非 `debug` 时按 release |
|
||||
| `LOG_LEVEL` | 日志等级 | `info` |
|
||||
| `SESSION_SECRET` | Session 签名密钥 | 启动时随机生成 |
|
||||
| `SQLITE_PATH` | SQLite 数据库文件路径 | `openflare.db` |
|
||||
| `SQL_DSN` | MySQL DSN，设置后优先于 SQLite | 空 |
|
||||
| `REDIS_CONN_STRING` | Redis 连接串 | 空 |
|
||||
| `UPLOAD_PATH` | 上传目录 | `upload` |
|
||||
| `AGENT_TOKEN` | 兼容旧部署的全局 Agent Token | 空 |
|
||||
|
||||
说明：
|
||||
|
||||
* `SQL_DSN` 与 `SQLITE_PATH` 同时存在时优先使用 `SQL_DSN`
|
||||
* `SESSION_SECRET` 生产环境必须显式配置
|
||||
* `REDIS_CONN_STRING` 未配置时，相关能力回退为进程内实现
|
||||
|
||||
### 1.3 `Option` 表中的运行时配置
|
||||
|
||||
以下配置由管理端设置页维护，可热更新：
|
||||
|
||||
| 配置项 | 作用 | 默认值 |
|
||||
| --- | --- | --- |
|
||||
| `AgentHeartbeatInterval` | Agent 心跳间隔（毫秒） | `10000` |
|
||||
| `NodeOfflineThreshold` | 节点离线判定阈值（毫秒） | `120000` |
|
||||
| `NodeOfflineThreshold` | 节点离线阈值（毫秒） | `120000` |
|
||||
| `AgentUpdateRepo` | Agent 自更新仓库 | `Rain-kl/OpenFlare` |
|
||||
| `GeoIPProvider` | 节点/IP 归属解析方式；支持 `disabled`、`mmdb`、`ip-api`、`geojs`、`ipinfo` | `ipinfo` |
|
||||
| `GlobalApiRateLimitNum` / `GlobalApiRateLimitDuration` | 全局 API 限流次数 / 时间窗口（秒） | `300` / `180` |
|
||||
| `GlobalWebRateLimitNum` / `GlobalWebRateLimitDuration` | 全局 Web 限流次数 / 时间窗口（秒） | `300` / `180` |
|
||||
| `UploadRateLimitNum` / `UploadRateLimitDuration` | 上传接口限流次数 / 时间窗口（秒） | `50` / `60` |
|
||||
| `DownloadRateLimitNum` / `DownloadRateLimitDuration` | 下载接口限流次数 / 时间窗口（秒） | `50` / `60` |
|
||||
| `CriticalRateLimitNum` / `CriticalRateLimitDuration` | 登录、注册、验证码等敏感接口限流次数 / 时间窗口（秒） | `100` / `1200` |
|
||||
|
||||
说明：
|
||||
|
||||
* 限流窗口上限不能超过 `RateLimitKeyExpirationDuration`，当前为 20 分钟
|
||||
* 限流按来源 IP 统计，若前置了 Nginx/CDN/LB，应正确透传真实客户端 IP
|
||||
* `GeoIPProvider=mmdb` 时，Server 会按需下载并使用本地 MaxMind Country 数据库；其余非 `disabled` 选项会直接请求对应外部 GeoIP 服务
|
||||
* 管理端“日志 -> 访问记录”中的访客 IP 归属地入库固定使用 MaxMind mmdb，不跟随 `GeoIPProvider` 切换
|
||||
|
||||
### 1.2.2 第五版当前支持的 OpenResty 优化配置项
|
||||
|
||||
以下配置项当前已接入管理端「运维设置」，并统一保存在 `Option` 表中。它们会参与第五版后续的配置渲染与发布链路；当前阶段优先完成参数录入、默认值和校验能力。
|
||||
|
||||
| 配置项 | 作用 | 计划默认值 |
|
||||
| --- | --- | --- |
|
||||
| `OpenRestyWorkerProcesses` | `worker_processes` 配置；支持 `auto` 或正整数 | `auto` |
|
||||
| `OpenRestyWorkerConnections` | `events { worker_connections }` 上限 | `4096` |
|
||||
| `OpenRestyWorkerRlimitNofile` | `worker_rlimit_nofile` 上限 | `65535` |
|
||||
| `OpenRestyEventsUse` | `events { use ... }` 指令；为空表示不显式渲染 | 空 |
|
||||
| `OpenRestyEventsMultiAcceptEnabled` | 是否启用 `multi_accept on` | `false` |
|
||||
| `OpenRestyKeepaliveTimeout` | `keepalive_timeout` 秒数 | `65` |
|
||||
| `OpenRestyKeepaliveRequests` | `keepalive_requests` 上限 | `1000` |
|
||||
| `OpenRestyClientHeaderTimeout` | `client_header_timeout` 秒数 | `15` |
|
||||
| `OpenRestyClientBodyTimeout` | `client_body_timeout` 秒数 | `15` |
|
||||
| `OpenRestySendTimeout` | `send_timeout` 秒数 | `30` |
|
||||
| `OpenRestyProxyConnectTimeout` | `proxy_connect_timeout` 秒数 | `5` |
|
||||
| `OpenRestyProxySendTimeout` | `proxy_send_timeout` 秒数 | `60` |
|
||||
| `OpenRestyProxyReadTimeout` | `proxy_read_timeout` 秒数 | `60` |
|
||||
| `OpenRestyWebsocketEnabled` | 是否自动注入 WebSocket 升级所需代理头 | `true` |
|
||||
| `OpenRestyProxyRequestBufferingEnabled` | 是否启用 `proxy_request_buffering` | `false` |
|
||||
| `OpenRestyProxyBufferingEnabled` | 是否启用 `proxy_buffering` | `true` |
|
||||
| `OpenRestyProxyBuffers` | `proxy_buffers` 组合值，例如 `16 16k` | `16 16k` |
|
||||
| `OpenRestyProxyBufferSize` | `proxy_buffer_size` | `8k` |
|
||||
| `OpenRestyProxyBusyBuffersSize` | `proxy_busy_buffers_size` | `64k` |
|
||||
| `OpenRestyGzipEnabled` | 是否启用 `gzip on` | `true` |
|
||||
| `OpenRestyGzipMinLength` | `gzip_min_length` 字节数 | `1024` |
|
||||
| `OpenRestyGzipCompLevel` | `gzip_comp_level` | `5` |
|
||||
| `OpenRestyCacheEnabled` | 是否启用代理缓存 | `false` |
|
||||
| `OpenRestyCachePath` | `proxy_cache_path` 目录 | 空 |
|
||||
| `OpenRestyCacheLevels` | `proxy_cache_path levels=` 值 | `1:2` |
|
||||
| `OpenRestyCacheInactive` | `proxy_cache_path inactive=` 时长 | `30m` |
|
||||
| `OpenRestyCacheMaxSize` | `proxy_cache_path max_size=` 大小 | `1g` |
|
||||
| `OpenRestyCacheKeyTemplate` | 缓存 Key 模板 | `$scheme$proxy_host$request_uri` |
|
||||
| `OpenRestyCacheLockEnabled` | 是否启用 `proxy_cache_lock` | `true` |
|
||||
| `OpenRestyCacheLockTimeout` | `proxy_cache_lock_timeout` 时长 | `5s` |
|
||||
| `OpenRestyCacheUseStale` | `proxy_cache_use_stale` 场景列表 | `error timeout updating http_500 http_502 http_503 http_504` |
|
||||
|
||||
说明：
|
||||
|
||||
* 第五版第一批当前仅开放稳定、可校验、可回滚的常用性能项；更多指令后续按相同模式扩展
|
||||
* 所有大小、时长、布尔和整数参数都应在 Server 保存前完成校验
|
||||
* `OpenRestyCacheEnabled=false` 时，缓存目录与缓存参数应允许留空或回退到默认值
|
||||
* 任何包含路径的配置项都必须在 Agent 落盘前再次校验可写性与安全边界
|
||||
|
||||
### 1.3 前端构建环境变量
|
||||
| `GeoIPProvider` | 节点/IP 归属解析方式 | `ipinfo` |
|
||||
| `GlobalApiRateLimitNum` / `GlobalApiRateLimitDuration` | 全局 API 限流次数 / 时间窗口 | `300` / `180` |
|
||||
| `GlobalWebRateLimitNum` / `GlobalWebRateLimitDuration` | 全局 Web 限流次数 / 时间窗口 | `300` / `180` |
|
||||
| `UploadRateLimitNum` / `UploadRateLimitDuration` | 上传接口限流次数 / 时间窗口 | `50` / `60` |
|
||||
| `DownloadRateLimitNum` / `DownloadRateLimitDuration` | 下载接口限流次数 / 时间窗口 | `50` / `60` |
|
||||
| `CriticalRateLimitNum` / `CriticalRateLimitDuration` | 敏感接口限流次数 / 时间窗口 | `100` / `1200` |
|
||||
|
||||
新版管理端位于 `openflare_server/web`，构建时支持以下公开环境变量：
|
||||
|
||||
| 环境变量 | 作用 | 默认值 | 示例 |
|
||||
| --- | --- | --- | --- |
|
||||
| `NEXT_PUBLIC_API_BASE_URL` | 前端请求后端 API 的基础路径；默认走同源 `/api` | `/api` | `NEXT_PUBLIC_API_BASE_URL=https://demo.example.com/api` |
|
||||
| `NEXT_PUBLIC_APP_VERSION` | 构建时注入前端展示版本号 | `dev` | `NEXT_PUBLIC_APP_VERSION=v0.4.0` |
|
||||
| `NEXT_DEV_BACKEND_URL` | 前端开发服务器通过反向代理转发 `/api/*` 时使用的后端地址；仅开发模式使用 | `http://127.0.0.1:3000` | `NEXT_DEV_BACKEND_URL=http://127.0.0.1:3300` |
|
||||
### 1.4 OpenResty 参数
|
||||
|
||||
说明：
|
||||
OpenResty 性能参数与缓存参数继续统一保存在 `Option` 表。当前常用项包括：
|
||||
|
||||
* `NEXT_PUBLIC_*` 变量会在前端构建阶段读取，并打包进静态资源
|
||||
* `NEXT_DEV_BACKEND_URL` 仅在本地开发服务器模式下使用，不会进入静态导出产物
|
||||
* 推荐生产环境继续使用同源部署，优先保持 `NEXT_PUBLIC_API_BASE_URL=/api`
|
||||
* `pnpm start` 会以开发模式启动前端，默认监听 `3001`，并通过 `NEXT_DEV_BACKEND_URL` 将 `/api/*` 代理到后端
|
||||
|
||||
---
|
||||
|
||||
## 2. Agent 配置
|
||||
|
||||
Agent 当前支持两类启动配置：
|
||||
|
||||
1. 命令行参数
|
||||
2. `agent.json` 配置文件
|
||||
|
||||
当前 Agent 仅支持少量环境变量用于日志输出控制；核心启动行为仍由 `-config` 参数和配置文件字段决定。
|
||||
* `OpenRestyWorkerProcesses`
|
||||
* `OpenRestyWorkerConnections`
|
||||
* `OpenRestyWorkerRlimitNofile`
|
||||
* `OpenRestyKeepaliveTimeout`
|
||||
* `OpenRestyProxyConnectTimeout`
|
||||
* `OpenRestyProxySendTimeout`
|
||||
* `OpenRestyProxyReadTimeout`
|
||||
* `OpenRestyProxyBufferingEnabled`
|
||||
* `OpenRestyGzipEnabled`
|
||||
* `OpenRestyCacheEnabled`
|
||||
* `OpenRestyCachePath`
|
||||
* `OpenRestyCacheMaxSize`
|
||||
|
||||
### 2.1.1 Agent 环境变量
|
||||
这类参数必须以结构化方式校验、保存并参与版本渲染。
|
||||
|
||||
支持的环境变量：
|
||||
### 1.5 前端构建环境变量
|
||||
|
||||
| 环境变量 | 作用 | 默认值 | 示例 |
|
||||
| 环境变量 | 作用 | 默认值 |
|
||||
| --- | --- | --- |
|
||||
| `NEXT_PUBLIC_API_BASE_URL` | 前端请求 API 的基础路径 | `/api` |
|
||||
| `NEXT_PUBLIC_APP_VERSION` | 前端展示版本号 | `dev` |
|
||||
| `NEXT_DEV_BACKEND_URL` | 本地开发服务器代理的后端地址 | `http://127.0.0.1:3000` |
|
||||
|
||||
## 2. Agent 配置
|
||||
|
||||
Agent 当前支持：
|
||||
|
||||
1. `-config` 命令行参数
|
||||
2. `agent.json` 配置文件
|
||||
3. 少量日志相关环境变量
|
||||
|
||||
### 2.1 Agent 环境变量
|
||||
|
||||
| 环境变量 | 作用 | 默认值 |
|
||||
| --- | --- | --- |
|
||||
| `LOG_LEVEL` | Agent 日志等级 | `info` |
|
||||
|
||||
### 2.2 Agent 命令行参数
|
||||
|
||||
| 参数 | 作用 | 默认值 |
|
||||
| --- | --- | --- |
|
||||
| `-config` | 指定 Agent 配置文件路径 | `./agent.json` |
|
||||
|
||||
### 2.3 Agent 配置字段
|
||||
|
||||
| 字段 | 作用 | 是否必填 | 默认值/行为 |
|
||||
| --- | --- | --- | --- |
|
||||
| `LOG_LEVEL` | 指定 Agent 的 `slog` 日志等级；支持 `debug`/`info`/`warn`/`error`（`warning` 兼容为 `warn`） | `info` | `LOG_LEVEL=debug` |
|
||||
| `server_url` | 控制面地址 | 是 | 无 |
|
||||
| `agent_token` | 节点专属认证 Token | 与 `discovery_token` 二选一 | 空 |
|
||||
| `discovery_token` | 首次自动注册使用的全局 Token | 与 `agent_token` 二选一 | 空 |
|
||||
| `node_name` | 节点名称 | 否 | 自动使用主机名 |
|
||||
| `node_ip` | 节点 IP | 否 | 自动探测 |
|
||||
| `openresty_path` | 本机 OpenResty 路径 | 否 | 空，未设置时走 Docker 模式 |
|
||||
| `openresty_container_name` | Docker 模式下的容器名 | 否 | `openflare-openresty` |
|
||||
| `openresty_docker_image` | Docker 模式下的镜像 | 否 | `openresty/openresty:alpine` |
|
||||
| `openresty_observability_port` | 本地观测端口 | 否 | `18081` |
|
||||
| `docker_binary` | Docker 可执行文件名或路径 | 否 | `docker` |
|
||||
| `data_dir` | Agent 数据目录 | 否 | 配置文件所在目录下的 `data` |
|
||||
| `main_config_path` | OpenResty 主配置写入路径 | 否 | 本机模式建议显式配置 |
|
||||
| `route_config_path` | 路由配置写入路径 | 否 | `data_dir/etc/nginx/conf.d/openflare_routes.conf` |
|
||||
| `cert_dir` | 本机证书写入目录 | 否 | `data_dir/etc/nginx/certs` |
|
||||
| `openresty_cert_dir` | OpenResty 读取证书目录 | 否 | 随运行模式变化 |
|
||||
| `lua_dir` | 本机 Lua 脚本写入目录 | 否 | `data_dir/etc/nginx/lua` |
|
||||
| `openresty_lua_dir` | OpenResty 读取 Lua 目录 | 否 | 随运行模式变化 |
|
||||
| `observability_buffer_path` | 观测补报缓冲文件路径 | 否 | `data_dir/var/lib/openflare/observability-buffer.json` |
|
||||
| `observability_replay_minutes` | 自动补传最近观测窗口分钟数 | 否 | `15` |
|
||||
| `state_path` | Agent 本地状态文件路径 | 否 | `data_dir/var/lib/openflare/agent-state.json` |
|
||||
| `heartbeat_interval` | 心跳间隔 | 否 | `10000` 毫秒 |
|
||||
| `request_timeout` | HTTP 请求超时 | 否 | `10000` 毫秒 |
|
||||
|
||||
说明：
|
||||
|
||||
* `LOG_LEVEL` 只影响 Agent 本地日志输出，不改变心跳、同步或配置行为
|
||||
* 未设置或设置为不支持的值时，将回退为 `info`
|
||||
* `agent_token` 与 `discovery_token` 不能同时为空
|
||||
* `heartbeat_interval` 与 `request_timeout` 支持毫秒整数或 Go duration 字符串
|
||||
* 未配置 `openresty_path` 时默认使用 Docker OpenResty 模式
|
||||
|
||||
### 2.1 Agent 命令行参数
|
||||
|
||||
启动示例：
|
||||
|
||||
```bash
|
||||
cd openflare_agent
|
||||
go run ./cmd/agent -config ./agent.json
|
||||
```
|
||||
|
||||
或编译后二进制：
|
||||
|
||||
```bash
|
||||
./openflare-agent -config /path/to/agent.json
|
||||
```
|
||||
|
||||
支持的命令行参数：
|
||||
|
||||
| 参数 | 作用 | 默认值 | 示例 |
|
||||
| --- | --- | --- | --- |
|
||||
| `-config` | 指定 Agent 配置文件路径 | `./agent.json` | `-config /etc/openflare/agent.json` |
|
||||
|
||||
### 2.2 Agent 配置文件示例
|
||||
|
||||
推荐最小配置：
|
||||
|
||||
```json
|
||||
{
|
||||
"server_url": "http://127.0.0.1:3000",
|
||||
"discovery_token": "replace-with-global-discovery-token",
|
||||
"data_dir": "./data",
|
||||
"openresty_container_name": "openflare-openresty",
|
||||
"openresty_docker_image": "openresty/openresty:alpine",
|
||||
"openresty_observability_port": 18081,
|
||||
"observability_replay_minutes": 15,
|
||||
"heartbeat_interval": 10000,
|
||||
"request_timeout": 10000
|
||||
}
|
||||
```
|
||||
|
||||
使用节点专属 Token 的示例：
|
||||
|
||||
```json
|
||||
{
|
||||
"server_url": "http://127.0.0.1:3000",
|
||||
"agent_token": "replace-with-node-auth-token",
|
||||
"node_name": "node-01",
|
||||
"node_ip": "192.168.1.20",
|
||||
"data_dir": "./data",
|
||||
"openresty_path": "/usr/local/openresty/nginx/sbin/openresty",
|
||||
"main_config_path": "/usr/local/openresty/nginx/conf/nginx.conf",
|
||||
"route_config_path": "/usr/local/openresty/nginx/conf/conf.d/openflare_routes.conf",
|
||||
"cert_dir": "/usr/local/openresty/nginx/conf/certs",
|
||||
"openresty_cert_dir": "/usr/local/openresty/nginx/conf/certs",
|
||||
"lua_dir": "/usr/local/openresty/nginx/conf/lua",
|
||||
"openresty_lua_dir": "/usr/local/openresty/nginx/conf/lua",
|
||||
"openresty_observability_port": 18081,
|
||||
"observability_buffer_path": "./data/observability-buffer.json",
|
||||
"observability_replay_minutes": 15,
|
||||
"state_path": "./data/agent-state.json",
|
||||
"heartbeat_interval": 10000,
|
||||
"request_timeout": 10000
|
||||
}
|
||||
```
|
||||
|
||||
### 2.3 Agent 配置字段
|
||||
|
||||
| 字段 | 作用 | 是否必填 | 默认值/行为 | 示例 |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| `server_url` | 控制面地址，Agent 所有注册、心跳、同步请求都会发往这里 | 是 | 无 | `http://127.0.0.1:3000` |
|
||||
| `agent_token` | 节点专属认证 Token | 与 `discovery_token` 二选一 | 空 | `node-token-xxx` |
|
||||
| `discovery_token` | 全局发现 Token，用于节点首次自动注册 | 与 `agent_token` 二选一 | 空 | `discovery-token-xxx` |
|
||||
| `node_name` | 节点名称 | 否 | 自动使用主机名 | `node-01` |
|
||||
| `node_ip` | 节点 IP | 否 | 自动探测第一个可用 IPv4 | `192.168.1.20` |
|
||||
| `openresty_path` | 本机 OpenResty 可执行文件路径；设置后按本机 OpenResty 模式运行 | 否 | 空；未设置时按 Docker OpenResty 模式处理 | `/usr/local/openresty/nginx/sbin/openresty` |
|
||||
| `openresty_container_name` | Docker 模式下的 OpenResty 容器名 | 否 | `openflare-openresty` | `openflare-openresty` |
|
||||
| `openresty_docker_image` | Docker 模式下用于初始化/管理的 OpenResty 镜像 | 否 | `openresty/openresty:alpine` | `openresty/openresty:alpine` |
|
||||
| `openresty_observability_port` | Agent 注入的 OpenResty 本地观测端口；用于 heartbeat 前读取 Lua 窗口指标和 `stub_status`，默认仅监听 `127.0.0.1` | 否 | `18081` | `18081` |
|
||||
| `docker_binary` | Docker 可执行文件名或路径 | 否 | `docker` | `/usr/bin/docker` |
|
||||
| `data_dir` | Agent 数据目录，用于存储托管配置、证书和状态文件 | 否 | 配置文件所在目录下的 `data` 子目录 | `./data` |
|
||||
| `main_config_path` | 第五版主配置接管时 OpenResty 主配置文件写入路径 | 第五版本机模式建议必填 | Docker 模式可使用受管默认路径；本机模式建议显式设置 | `/usr/local/openresty/nginx/conf/nginx.conf` |
|
||||
| `route_config_path` | 路由配置文件写入路径 | 否 | 默认为 `data_dir` 下托管路径 | `/etc/nginx/conf.d/openflare_routes.conf` |
|
||||
| `cert_dir` | Agent 在本机写入受管证书文件的目录 | 否 | 默认为 `data_dir` 下托管 certs 目录 | `./data/etc/nginx/certs` |
|
||||
| `openresty_cert_dir` | OpenResty 实际读取受管证书文件的目录 | 否 | 本机模式默认等于 `cert_dir`；Docker 模式默认 `/etc/nginx/openflare-certs` | `/usr/local/openresty/nginx/conf/certs` |
|
||||
| `lua_dir` | Agent 在本机写入受管 Lua 观测脚本的目录；每次启动都会覆盖释放 | 否 | 默认为 `data_dir` 下托管 lua 目录 | `./data/etc/nginx/lua` |
|
||||
| `openresty_lua_dir` | OpenResty 实际读取受管 Lua 观测脚本的目录 | 否 | 本机模式默认等于 `lua_dir`；Docker 模式默认 `/etc/nginx/openflare-lua` | `/usr/local/openresty/nginx/conf/lua` |
|
||||
| `observability_buffer_path` | Agent 本地观测补报缓冲文件路径；用于在 server 短暂离线时按时间窗口落盘待补传数据 | 否 | 默认为 `data_dir` 下托管观测缓冲文件 | `./data/var/lib/openflare/observability-buffer.json` |
|
||||
| `observability_replay_minutes` | Agent 恢复心跳后允许批量补传的最近观测窗口时长（分钟） | 否 | `15` | `30` |
|
||||
| `state_path` | Agent 本地状态文件路径 | 否 | 默认为 `data_dir` 下托管状态文件 | `./data/agent-state.json` |
|
||||
| `heartbeat_interval` | 心跳间隔 | 否 | `10000` 毫秒 | `10000` |
|
||||
| `request_timeout` | HTTP 请求超时时间 | 否 | `10000` 毫秒 | `10000` |
|
||||
|
||||
说明：
|
||||
|
||||
* `agent_token` 与 `discovery_token` 不能同时为空
|
||||
* `heartbeat_interval`、`request_timeout` 支持两种写法：
|
||||
* 毫秒整数，例如 `10000`
|
||||
* Go duration 字符串，例如 `"30s"`
|
||||
* `node_name` 与 `node_ip` 未填写时会自动探测；若自动探测失败，配置校验会报错
|
||||
* 未配置 `openresty_path` 时，默认为 Docker OpenResty 模式
|
||||
* `openresty_observability_port` 默认仅绑定本地回环地址；若节点本机已有端口冲突，可改为其他未占用端口
|
||||
* `observability_replay_minutes` 只控制“允许补传最近多少分钟的窗口”；超出该窗口的历史观测会在本地自动裁剪
|
||||
* 配置保存时，`agent_version`、`nginx_version` 由程序运行时维护，不需要写入 JSON
|
||||
* 第五版主配置接管完成后，本机模式下应优先通过 `main_config_path` 由 Agent 写入受管主配置，而不是依赖节点手工维护 include 规则
|
||||
|
||||
### 2.4 Agent 托管路径默认值
|
||||
|
||||
当未显式设置以下字段时，Agent 会根据 `data_dir` 自动生成托管路径：
|
||||
|
||||
| 字段 | 默认值 |
|
||||
| --- | --- |
|
||||
| `main_config_path` | 第五版 Docker 模式默认可落在 `data_dir/etc/nginx/nginx.conf`；本机模式建议显式配置 |
|
||||
| `route_config_path` | `data_dir/etc/nginx/conf.d/openflare_routes.conf` |
|
||||
| `cert_dir` | `data_dir/etc/nginx/certs` |
|
||||
| `lua_dir` | `data_dir/etc/nginx/lua` |
|
||||
| `observability_buffer_path` | `data_dir/var/lib/openflare/observability-buffer.json` |
|
||||
| `state_path` | `data_dir/var/lib/openflare/agent-state.json` |
|
||||
|
||||
Docker OpenResty 模式下：
|
||||
|
||||
| 字段 | 默认值 |
|
||||
| --- | --- |
|
||||
| `openresty_cert_dir` | `/etc/nginx/openflare-certs` |
|
||||
| `openresty_lua_dir` | `/etc/nginx/openflare-lua` |
|
||||
## 3. 维护要求
|
||||
|
||||
补充说明：
|
||||
以下内容变化时，必须同步更新本文档：
|
||||
|
||||
* Agent 会在每次启动时把受管 Lua 观测脚本覆盖释放到 `lua_dir`，不再由 Server 随配置版本下发
|
||||
* OpenResty 通过 `openresty_lua_dir` 读取这些本地脚本，并在每次 heartbeat 前通过 `http://127.0.0.1:<openresty_observability_port>/openflare/observability` 读取最近窗口请求指标
|
||||
* 若 server 短暂离线，Agent 会把最近窗口观测先写入 `observability_buffer_path`，待 heartbeat 恢复后按时间窗口批量补传最近 `observability_replay_minutes` 分钟的数据
|
||||
* 同一端口还会暴露仅本机可访问的 `stub_status`，用于采集 OpenResty 活动连接数
|
||||
|
||||
### 2.5 Agent 启动示例
|
||||
|
||||
#### Docker OpenResty 模式
|
||||
|
||||
适用于节点本机不直接管理宿主机 OpenResty，而是通过 Docker 容器运行 OpenResty。
|
||||
|
||||
```json
|
||||
{
|
||||
"server_url": "http://127.0.0.1:3000",
|
||||
"discovery_token": "replace-with-global-discovery-token",
|
||||
"data_dir": "./data"
|
||||
}
|
||||
```
|
||||
|
||||
#### 本机 OpenResty 模式
|
||||
|
||||
适用于节点已经安装了宿主机 OpenResty，且 Agent 直接执行 `openresty -t` 与 `openresty -s reload`。
|
||||
|
||||
```json
|
||||
{
|
||||
"server_url": "http://127.0.0.1:3000",
|
||||
"agent_token": "replace-with-node-auth-token",
|
||||
"openresty_path": "/usr/local/openresty/nginx/sbin/openresty",
|
||||
"main_config_path": "/usr/local/openresty/nginx/conf/nginx.conf",
|
||||
"route_config_path": "/usr/local/openresty/nginx/conf/conf.d/openflare_routes.conf",
|
||||
"cert_dir": "/usr/local/openresty/nginx/conf/certs",
|
||||
"openresty_cert_dir": "/usr/local/openresty/nginx/conf/certs",
|
||||
"lua_dir": "/usr/local/openresty/nginx/conf/lua",
|
||||
"openresty_lua_dir": "/usr/local/openresty/nginx/conf/lua"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. 配置维护要求
|
||||
|
||||
当以下内容发生变化时，应同步更新本文档：
|
||||
|
||||
* Server 新增/删除命令行参数
|
||||
* Server 新增/删除环境变量
|
||||
* Agent 新增/删除命令行参数
|
||||
* Agent 新增/删除配置文件字段
|
||||
* 任一配置项的默认值、示例或用途发生变化
|
||||
* Server 命令行参数
|
||||
* Server 环境变量
|
||||
* Agent 命令行参数
|
||||
* Agent 配置字段
|
||||
* 任一配置项的默认值、用途或示例
|
||||
|
||||
+150
-451
@@ -1,64 +1,37 @@
|
||||
# OpenFlare 部署说明
|
||||
|
||||
本文档仅保留当前可用基线的最小部署方式，并补充第五版（0.5.x）开发期间与 OpenResty 主配置接管相关的联调约束。
|
||||
|
||||
---
|
||||
|
||||
## 1. 前置条件
|
||||
|
||||
# OpenFlare 部署说明
|
||||
|
||||
本文档只保留 OpenFlare `1.0.0` 的当前部署基线、联调入口与升级方式。
|
||||
|
||||
## 1. 前置条件
|
||||
|
||||
### 1.1 Server
|
||||
|
||||
* Go 1.24+
|
||||
* Node.js 18+
|
||||
* 可写 SQLite 文件目录
|
||||
|
||||
|
||||
### 1.2 Agent
|
||||
|
||||
* Go 1.23+
|
||||
* 对 Agent 数据目录有写权限
|
||||
* 若使用独立 OpenResty 模式：可执行 `openresty -t` 与 `openresty -s reload`
|
||||
* 若使用 Docker 模式：具备 Docker 执行权限
|
||||
* 第五版主配置接管模式下，Agent 对 OpenResty 主配置目标路径必须具备写权限
|
||||
|
||||
---
|
||||
|
||||
## 2. Server 启动
|
||||
|
||||
* 本机模式下可执行 `openresty -t` 与 `openresty -s reload`
|
||||
* Docker 模式下具备 Docker 执行权限
|
||||
|
||||
## 2. 启动 Server
|
||||
|
||||
### 2.1 构建前端
|
||||
|
||||
```bash
|
||||
cd openflare_server/web
|
||||
corepack enable
|
||||
pnpm install
|
||||
pnpm build
|
||||
```
|
||||
|
||||
说明：
|
||||
|
||||
* 前端使用 Next.js 静态导出模式构建
|
||||
* `pnpm build` 会生成供 Go Server 托管的 `openflare_server/web/build` 目录
|
||||
* 如需覆盖默认接口地址，可在构建前设置 `NEXT_PUBLIC_API_BASE_URL`
|
||||
|
||||
### 2.1.1 本地前端热更新开发
|
||||
|
||||
在本地联调时，可单独启动前端开发服务器：
|
||||
|
||||
```bash
|
||||
cd openflare_server/web
|
||||
corepack enable
|
||||
pnpm install
|
||||
pnpm dev
|
||||
pnpm build
|
||||
```
|
||||
|
||||
说明：
|
||||
`pnpm build` 会生成供 Go Server 托管的静态产物。
|
||||
|
||||
* `pnpm dev` 默认以 Next.js 开发模式启动，监听 `http://127.0.0.1:3001`
|
||||
* 开发服务器会通过同源代理把 `/api/*` 的 HTTP 与 WebSocket 请求统一转发到 `NEXT_DEV_BACKEND_URL`，默认指向 `http://127.0.0.1:3000`
|
||||
* 如需改后端地址，可在启动前设置 `NEXT_DEV_BACKEND_URL`
|
||||
* 这种模式用于本地热更新开发；正式运行和交付仍以 `pnpm build` 后由 Go Server 托管为准
|
||||
### 2.2 源码启动
|
||||
|
||||
### 2.2 启动服务
|
||||
|
||||
```bash
|
||||
cd openflare_server
|
||||
export SESSION_SECRET='replace-with-random-string'
|
||||
@@ -66,109 +39,66 @@ export SQLITE_PATH='./openflare.db'
|
||||
export LOG_LEVEL='info'
|
||||
go run .
|
||||
```
|
||||
|
||||
说明：
|
||||
|
||||
* 默认不依赖全局 `AGENT_TOKEN`
|
||||
* 节点接入凭证由数据库维护：节点专属 `agent_token` + 全局 `discovery_token`
|
||||
* 默认监听端口为 `3000`
|
||||
* `LOG_LEVEL` 支持 `debug` / `info` / `warn` / `error`
|
||||
|
||||
### 2.3 使用 docker-compose 启动 Server
|
||||
|
||||
适用于直接使用已发布的 Server 镜像部署控制面。
|
||||
|
||||
示例 `docker-compose.yml`：
|
||||
|
||||
```yaml
|
||||
services:
|
||||
openflare:
|
||||
image: ghcr.io/rain-kl/openflare:latest
|
||||
container_name: openflare
|
||||
restart: unless-stopped
|
||||
ports:
|
||||
- "3000:3000"
|
||||
environment:
|
||||
SESSION_SECRET: replace-with-random-string
|
||||
SQLITE_PATH: /data/openflare.db
|
||||
GIN_MODE: release
|
||||
volumes:
|
||||
- openflare-data:/data
|
||||
|
||||
volumes:
|
||||
openflare-data:
|
||||
```
|
||||
|
||||
启动命令：
|
||||
|
||||
```bash
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
说明：
|
||||
|
||||
* `SESSION_SECRET` 必须替换为随机字符串
|
||||
* SQLite 数据文件持久化到 Docker volume `openflare-data`
|
||||
* 镜像默认监听容器内 `3000` 端口
|
||||
* 若要固定版本，可将 `latest` 替换为具体 tag，例如 `ghcr.io/rain-kl/openflare:v0.3.0`
|
||||
|
||||
版本升级说明：
|
||||
|
||||
* Root 用户可在管理端顶栏点击「版本」默认检查正式版 GitHub Release
|
||||
* 若需尝试 preview 版本，可在同一弹窗中手动检查 preview 发布并选择是否升级
|
||||
* 当前运行的是 Release 二进制且二进制目录可写时，可直接在弹窗内触发 Server 自升级
|
||||
* Server 自升级会下载匹配当前平台的 `openflare-server-*` 资产，替换当前二进制并自动重启进程
|
||||
* 也可在同一弹窗中手动上传 Server 二进制，服务端先检测上传文件版本，前端确认后再执行替换与重启
|
||||
* 节点 Agent 默认仅跟随正式版自动更新；如需 preview 版本，可在节点详情中手动检查 preview 发布并下发更新
|
||||
|
||||
### 2.4 首次登录
|
||||
|
||||
访问 `http://localhost:3000`
|
||||
|
||||
默认账号：
|
||||
|
||||
* 用户名：`root`
|
||||
* 密码：`123456`
|
||||
|
||||
### 2.5 Swagger 文档使用
|
||||
|
||||
登录管理端后，访问：`http://localhost:3000/swagger/index.html`
|
||||
|
||||
使用说明：
|
||||
|
||||
* Swagger UI 受管理端登录态保护，未登录不可直接访问
|
||||
* 可在浏览器中查看当前 Server API 与 Agent API 定义，并直接发起调试请求
|
||||
* 当 Server API 新增或变更时，需要同步更新 Swag 注解并重新生成 `openflare_server/docs`
|
||||
|
||||
如需在本地重新生成 Swagger 文档，先安装 `swag`：
|
||||
|
||||
```bash
|
||||
go install github.com/swaggo/swag/cmd/swag@latest
|
||||
```
|
||||
|
||||
安装后请确保 Go 的二进制目录已加入 `PATH`，常见目录为：
|
||||
|
||||
* Linux / macOS：`$HOME/go/bin`
|
||||
* Windows：`%USERPROFILE%\go\bin`
|
||||
|
||||
如需在本地重新生成 Swagger 文档，可在 `openflare_server` 目录执行：
|
||||
|
||||
```bash
|
||||
swag init -g main.go -o docs
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. Agent 配置
|
||||
|
||||
当前支持两种接入模式。
|
||||
|
||||
### 3.1 节点专属 `agent_token`
|
||||
|
||||
```json
|
||||
{
|
||||
"server_url": "http://127.0.0.1:3000",
|
||||
"agent_token": "replace-with-node-auth-token",
|
||||
|
||||
默认监听 `3000` 端口。
|
||||
|
||||
### 2.3 Docker Compose 启动
|
||||
|
||||
```yaml
|
||||
services:
|
||||
openflare:
|
||||
image: ghcr.io/rain-kl/openflare:latest
|
||||
container_name: openflare
|
||||
restart: unless-stopped
|
||||
ports:
|
||||
- "3000:3000"
|
||||
environment:
|
||||
SESSION_SECRET: replace-with-random-string
|
||||
SQLITE_PATH: /data/openflare.db
|
||||
GIN_MODE: release
|
||||
LOG_LEVEL: info
|
||||
volumes:
|
||||
- openflare-data:/data
|
||||
|
||||
volumes:
|
||||
openflare-data:
|
||||
```
|
||||
|
||||
```bash
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
### 2.4 首次登录
|
||||
|
||||
访问 `http://localhost:3000`
|
||||
|
||||
默认账号：
|
||||
|
||||
* 用户名：`root`
|
||||
* 密码：`123456`
|
||||
|
||||
### 2.5 Swagger
|
||||
|
||||
登录管理端后访问：`http://localhost:3000/swagger/index.html`
|
||||
|
||||
如需在本地重新生成文档：
|
||||
|
||||
```bash
|
||||
go install github.com/swaggo/swag/cmd/swag@latest
|
||||
cd openflare_server
|
||||
swag init -g main.go -o docs
|
||||
```
|
||||
|
||||
## 3. Agent 配置
|
||||
|
||||
当前支持两种接入模式。
|
||||
|
||||
### 3.1 使用节点专属 `agent_token`
|
||||
|
||||
```json
|
||||
{
|
||||
"server_url": "http://127.0.0.1:3000",
|
||||
"agent_token": "replace-with-node-auth-token",
|
||||
"data_dir": "./data",
|
||||
"openresty_container_name": "openflare-openresty",
|
||||
"openresty_docker_image": "openresty/openresty:alpine",
|
||||
@@ -177,100 +107,9 @@ swag init -g main.go -o docs
|
||||
"heartbeat_interval": 10000,
|
||||
"request_timeout": 10000
|
||||
}
|
||||
```
|
||||
|
||||
### 3.2 全局 `discovery_token`
|
||||
|
||||
```json
|
||||
{
|
||||
"server_url": "http://127.0.0.1:3000",
|
||||
"discovery_token": "replace-with-global-discovery-token",
|
||||
"data_dir": "./data",
|
||||
"openresty_container_name": "openflare-openresty",
|
||||
"openresty_docker_image": "openresty/openresty:alpine",
|
||||
"openresty_observability_port": 18081,
|
||||
"observability_replay_minutes": 15,
|
||||
"heartbeat_interval": 10000,
|
||||
"request_timeout": 10000
|
||||
}
|
||||
```
|
||||
|
||||
说明：
|
||||
|
||||
* `agent_version` 由 Agent 代码内常量提供，升级时同步修改代码
|
||||
* 为兼容现有 Agent / Server API，运行时版本仍通过 `openresty_version` 字段上报，但其值现在表示 OpenResty 版本
|
||||
* 时间字段使用毫秒整数
|
||||
* `agent_token` 与 `discovery_token` 至少填写一个
|
||||
* 若 `agent_token` 为空且 `discovery_token` 存在，Agent 会自动注册并写回新的专属 `agent_token`
|
||||
* `node_name` 与 `node_ip` 可省略，未填写时自动探测
|
||||
* 未配置 `openresty_path` 时，默认使用 Docker OpenResty 容器
|
||||
* Agent 会在受管 OpenResty 中注入 Lua 观测脚本，并通过 `openresty_observability_port` 对本机暴露最近窗口指标与 `stub_status`
|
||||
* Agent 还会把最近 `observability_replay_minutes` 分钟内未成功上报的观测窗口落盘到本地缓冲文件，待 server 恢复后自动批量补传
|
||||
|
||||
### 3.3 第五版新增部署约束
|
||||
|
||||
第五版开发完成后，OpenResty 主配置将进入 Agent 受管范围。部署与联调时应满足：
|
||||
|
||||
* 本机 OpenResty 模式需要为 Agent 显式提供主配置文件写入路径
|
||||
* Docker OpenResty 模式需要保证主配置、路由配置和证书目录位于同一套受管挂载路径中
|
||||
* Docker OpenResty 模式会额外挂载一个仅本机可访问的 `127.0.0.1:<openresty_observability_port>` 观测端口，用于 Agent 在 heartbeat 前抓取 Lua 窗口指标
|
||||
* Docker / 本机两种模式都会在 `data_dir/var/lib/openflare/observability-buffer.json` 保留最近待补传窗口；若节点磁盘是临时盘，重启后该缓冲也会丢失
|
||||
* 节点现存手工维护的主配置如继续保留，必须先迁移为 Server 渲染模板的等价配置，再切换到受管模式
|
||||
* 主配置切换前必须预留回滚副本，并通过一次 `openresty -t` 失败演练验证回滚
|
||||
|
||||
---
|
||||
|
||||
## 4. Agent 启动
|
||||
|
||||
### 4.1 直接运行
|
||||
|
||||
```bash
|
||||
cd openflare_agent
|
||||
export LOG_LEVEL='info'
|
||||
go run ./cmd/agent -config /path/to/agent.json
|
||||
```
|
||||
|
||||
### 4.2 编译后二进制运行
|
||||
|
||||
```bash
|
||||
cd openflare_agent
|
||||
go build -o openflare-agent ./cmd/agent
|
||||
export LOG_LEVEL='info'
|
||||
./openflare-agent -config /path/to/agent.json
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. 最小联调步骤
|
||||
|
||||
### 5.1 准备节点接入
|
||||
|
||||
二选一：
|
||||
|
||||
* 在管理端预创建节点并复制专属 `agent_token`
|
||||
* 在管理端查看全局 `discovery_token` 并写入节点配置
|
||||
|
||||
### 5.2 创建规则并发布
|
||||
|
||||
1. 在管理端新增一条启用中的反代规则
|
||||
2. 在发布前查看预览或变更摘要
|
||||
3. 生成并激活新版本
|
||||
|
||||
### 5.3 验证 Agent 应用
|
||||
|
||||
预期行为：
|
||||
|
||||
1. Agent 完成心跳
|
||||
2. 自动注册模式下完成 Token 置换
|
||||
3. 心跳响应返回激活版本摘要；若版本或 checksum 不一致，则拉取激活版本
|
||||
4. 写入主配置、路由配置与必要证书文件
|
||||
5. 执行 `openresty -t`
|
||||
6. 执行 `openresty -s reload`
|
||||
7. 上报应用结果
|
||||
|
||||
### 5.3.1 Docker OpenResty 模式最小验证
|
||||
|
||||
建议使用最小 `agent.json`：
|
||||
### 3.2 使用全局 `discovery_token`
|
||||
|
||||
```json
|
||||
{
|
||||
@@ -279,242 +118,102 @@ export LOG_LEVEL='info'
|
||||
"data_dir": "./data",
|
||||
"openresty_container_name": "openflare-openresty",
|
||||
"openresty_docker_image": "openresty/openresty:alpine",
|
||||
"openresty_observability_port": 18081
|
||||
"openresty_observability_port": 18081,
|
||||
"observability_replay_minutes": 15,
|
||||
"heartbeat_interval": 10000,
|
||||
"request_timeout": 10000
|
||||
}
|
||||
```
|
||||
|
||||
验证点：
|
||||
说明：
|
||||
|
||||
1. 首次启动后确认 `data/etc/nginx/nginx.conf`、`data/etc/nginx/conf.d/openflare_routes.conf`、`data/etc/nginx/certs` 与 `data/etc/nginx/lua` 已由 Agent 创建
|
||||
2. 确认容器实际挂载了主配置、路由目录、证书目录和 Lua 目录
|
||||
3. 确认宿主机本地可访问 `http://127.0.0.1:18081/openflare/observability` 与 `http://127.0.0.1:18081/openflare/stub_status`
|
||||
3. 在管理端发布一次新版本后，确认节点 `current_version` 追平激活版本
|
||||
4. 在节点详情查看“当前目标版本”与“最近应用”，确认主配置/路由配置快照和 checksum 已可见
|
||||
* `agent_token` 与 `discovery_token` 至少填写一个
|
||||
* 未配置 `openresty_path` 时默认使用 Docker OpenResty
|
||||
* Agent 会暴露本机观测端口并在 server 恢复后补传最近窗口数据
|
||||
|
||||
推荐检查命令：
|
||||
## 4. 启动 Agent
|
||||
|
||||
### 4.1 直接运行
|
||||
|
||||
```bash
|
||||
docker inspect openflare-openresty
|
||||
docker exec openflare-openresty openresty -t
|
||||
cd openflare_agent
|
||||
export LOG_LEVEL='info'
|
||||
go run ./cmd/agent -config /path/to/agent.json
|
||||
```
|
||||
|
||||
说明：
|
||||
### 4.2 编译后二进制运行
|
||||
|
||||
* `docker inspect` 重点确认主配置文件、`conf.d` 目录、证书目录和 Lua 目录都来自 Agent 受管路径
|
||||
* 观测端口默认只绑定 `127.0.0.1`；若节点已有冲突，可在 `agent.json` 中调整 `openresty_observability_port`
|
||||
* 若容器名使用默认值，请将上述命令中的名称替换为 `openflare-openresty`
|
||||
|
||||
### 5.3.2 本机 OpenResty 模式最小验证
|
||||
|
||||
建议显式提供以下路径：
|
||||
|
||||
```json
|
||||
{
|
||||
"server_url": "http://127.0.0.1:3000",
|
||||
"agent_token": "replace-with-node-auth-token",
|
||||
"openresty_path": "/usr/local/openresty/nginx/sbin/openresty",
|
||||
"main_config_path": "/usr/local/openresty/nginx/conf/nginx.conf",
|
||||
"route_config_path": "/usr/local/openresty/nginx/conf/conf.d/openflare_routes.conf",
|
||||
"cert_dir": "/usr/local/openresty/nginx/conf/certs",
|
||||
"openresty_cert_dir": "/usr/local/openresty/nginx/conf/certs",
|
||||
"lua_dir": "/usr/local/openresty/nginx/conf/lua",
|
||||
"openresty_lua_dir": "/usr/local/openresty/nginx/conf/lua",
|
||||
"openresty_observability_port": 18081
|
||||
}
|
||||
```bash
|
||||
cd openflare_agent
|
||||
go build -o openflare-agent ./cmd/agent
|
||||
export LOG_LEVEL='info'
|
||||
./openflare-agent -config /path/to/agent.json
|
||||
```
|
||||
|
||||
验证点：
|
||||
## 5. 最小联调步骤
|
||||
|
||||
1. 发布前先备份 `main_config_path` 与 `route_config_path`
|
||||
2. 首次发布后执行 `openresty -t`，确认主配置已由 Server 模板接管且 include 指向 Agent 写入的路由文件
|
||||
3. 确认本机可访问 `http://127.0.0.1:18081/openflare/observability` 与 `http://127.0.0.1:18081/openflare/stub_status`
|
||||
4. 再次发布修改后的规则或 OpenResty 参数，确认 `openresty -s reload` 成功且节点版本更新
|
||||
5. 在节点详情与应用记录页确认主配置 checksum、路由配置 checksum 和支持文件数已上报
|
||||
|
||||
### 5.4 验证管理端状态
|
||||
|
||||
管理端应能看到：
|
||||
|
||||
* 节点在线状态
|
||||
* 节点当前版本
|
||||
* 最近一次应用结果
|
||||
* 自动注册后节点已绑定专属 `agent_token`
|
||||
|
||||
### 5.5 验证失败回滚
|
||||
|
||||
人为制造 `openresty -t` 失败后再次发布，预期：
|
||||
1. 在管理端准备 `agent_token` 或 `discovery_token`
|
||||
2. 启动 Agent 并确认节点上线
|
||||
3. 新增一条启用中的反代规则
|
||||
4. 生成并激活新版本
|
||||
5. 确认 Agent 拉取配置、执行 `openresty -t`、reload 并上报结果
|
||||
|
||||
* Agent 回滚旧配置
|
||||
* 主配置与路由配置一起回滚
|
||||
* 节点 `last_error` 更新
|
||||
* 应用记录中出现失败记录
|
||||
预期管理端可看到：
|
||||
|
||||
### 5.5.1 建议的失败演练方式
|
||||
* 节点在线状态
|
||||
* 节点当前版本
|
||||
* 最近一次应用结果
|
||||
* 自动注册后的专属 `agent_token`
|
||||
|
||||
建议只在测试节点进行，避免直接污染生产节点。
|
||||
## 6. 升级说明
|
||||
|
||||
本机 OpenResty 模式：
|
||||
* Root 用户可在管理端顶栏检查并升级 Server 正式版
|
||||
* 如需尝试 preview 版本，可手动检查对应发布
|
||||
* 节点 Agent 默认只跟随正式版自动更新；preview 升级需要手动触发
|
||||
* 也可通过上传 Server 二进制的方式执行确认升级
|
||||
|
||||
1. 先备份当前 `agent.json`
|
||||
2. 将 `openresty_path` 临时改为一个包装脚本，在收到 `-t` 时固定返回非零，其余参数转发到真实 `openresty`
|
||||
3. 触发一次新版本发布，确认应用失败、主配置与路由配置回滚、节点 `last_error` 更新
|
||||
4. 恢复真实 `openresty_path` 后再次发布，确认节点重新追平版本
|
||||
## 7. 常用验证命令
|
||||
|
||||
Docker OpenResty 模式：
|
||||
### 7.1 Server
|
||||
|
||||
1. 在测试节点上保留默认受管路径
|
||||
2. 临时将 `openresty_docker_image` 指向一个不包含 `openresty` 运行时的错误镜像标签，或在测试环境用包装镜像让 `openresty -t` 固定失败
|
||||
3. 再次发布，确认节点应用失败但 `data/etc/nginx/nginx.conf` 与 `data/etc/nginx/conf.d/openflare_routes.conf` 已回滚为旧版本
|
||||
4. 恢复正确镜像后重新发布，确认节点恢复健康
|
||||
```bash
|
||||
cd openflare_server
|
||||
GOCACHE=/tmp/openflare-go-cache go test ./...
|
||||
```
|
||||
|
||||
说明：
|
||||
### 7.2 Agent
|
||||
|
||||
* 第五版的失败演练重点不在“如何制造错误”，而在确认失败后旧主配置、旧路由配置和支持文件都会被一起恢复
|
||||
* 若不方便做真实环境演练，至少应运行 Agent 回归测试，覆盖主配置写入、Docker 挂载与失败回滚
|
||||
|
||||
---
|
||||
|
||||
## 6. 常用验证命令
|
||||
|
||||
### 6.1 Server
|
||||
|
||||
```bash
|
||||
cd openflare_server
|
||||
GOCACHE=/tmp/openflare-go-cache go test ./...
|
||||
```
|
||||
|
||||
### 6.2 Agent
|
||||
|
||||
```bash
|
||||
cd openflare_agent
|
||||
GOCACHE=/tmp/openflare-go-cache go test ./...
|
||||
```
|
||||
|
||||
### 6.3 前端
|
||||
|
||||
```bash
|
||||
cd openflare_server/web
|
||||
pnpm build
|
||||
```
|
||||
|
||||
### 6.4 发布工作流
|
||||
|
||||
当前仓库维护两套独立的 Release 工作流：
|
||||
|
||||
* GitHub 使用 [.github/workflows/release.yml](.github/workflows/release.yml)，保留制品上传/下载分阶段流程
|
||||
* Gitea 使用 [.gitea/workflows/release.yml](.gitea/workflows/release.yml)，在单个 Job 内完成前端构建、服务端/Agent 多平台编译与 Release 发布，避免依赖 Gitea 目前不兼容的 `upload-artifact@v4`、`download-artifact@v4`
|
||||
|
||||
Docker 镜像发布使用 [.github/workflows/docker-image.yml](.github/workflows/docker-image.yml)：
|
||||
|
||||
* 仅构建 `openflare_server` 服务端镜像
|
||||
* 发布到 GitHub Container Registry（`ghcr.io/<owner>/<repo>:<tag>`）
|
||||
* 单个工作流通过分架构原生构建再合并 manifest 的方式产出 `linux/amd64` 与 `linux/arm64` 多架构镜像，避免 `arm64` 长时间模拟编译
|
||||
|
||||
---
|
||||
|
||||
## 7. Agent 一键部署（V3）
|
||||
|
||||
### 7.1 curl 安装
|
||||
|
||||
在目标机器上运行：
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
支持参数：
|
||||
|
||||
| 参数 | 说明 | 默认值 |
|
||||
| ------------------- | -------------------- | --------------------- |
|
||||
| `--server-url` | Server 地址（必填） | - |
|
||||
| `--discovery-token` | 全局 Discovery Token | - |
|
||||
| `--agent-token` | 节点专属 Token | - |
|
||||
| `--install-dir` | 安装目录 | `/opt/openflare-agent` |
|
||||
| `--repo` | GitHub Release 仓库 | `Rain-kl/OpenFlare` |
|
||||
| `--no-service` | 不创建 systemd 服务 | - |
|
||||
|
||||
安装脚本会：
|
||||
```bash
|
||||
cd openflare_agent
|
||||
GOCACHE=/tmp/openflare-go-cache go test ./...
|
||||
```
|
||||
|
||||
1. 从 GitHub Releases 下载最新 Agent 二进制（`openflare-agent-{os}-{arch}`）
|
||||
2. 若检测到已存在安装目录，会先停止运行中的 `openflare-agent` 服务并删除整个安装目录
|
||||
3. 先下载到临时文件，再写入全新的安装目录，避免覆盖运行中进程导致写入失败
|
||||
4. 生成 `agent.json` 配置文件
|
||||
5. 创建 systemd 服务 `openflare-agent.service`
|
||||
6. 启动并启用自启
|
||||
### 7.3 Frontend
|
||||
|
||||
说明：
|
||||
```bash
|
||||
cd openflare_server/web
|
||||
pnpm build
|
||||
```
|
||||
|
||||
* 脚本可重复执行，用于重装或升级到最新 Release
|
||||
* 若检测到已运行的 `openflare-agent` systemd 服务，会先停止服务、清空安装目录，再重新安装
|
||||
* 重装会删除旧的 `agent.json`、本地状态、缓存数据和旧二进制，因此节点会按新的 Token 或 Discovery Token 重新接入
|
||||
|
||||
### 7.2 管理端生成部署命令
|
||||
|
||||
在管理端 **系统设置 → 运维设置** 中查看已生成的一键部署命令，直接复制到目标节点执行。
|
||||
|
||||
### 7.3 Agent 自动更新
|
||||
|
||||
Agent 自动更新默认为关闭。
|
||||
|
||||
在管理端 **节点管理** 页面中可以：
|
||||
|
||||
* 为单个节点开启「自动更新」
|
||||
* 为单个节点点击「立即更新」，下发一次性更新指令
|
||||
|
||||
节点在收到对应心跳响应后，会检查 GitHub Releases，发现新版本时自动下载并重启。
|
||||
|
||||
---
|
||||
|
||||
## 8. Agent 二进制命名规则
|
||||
|
||||
GitHub Release 中的 Agent 二进制命名格式：
|
||||
|
||||
* `openflare-agent-linux-amd64`
|
||||
* `openflare-agent-linux-arm64`
|
||||
* `openflare-agent-darwin-arm64`
|
||||
|
||||
---
|
||||
|
||||
## 9. 运维设置热更新（V3）
|
||||
|
||||
以下参数可通过管理端 **运维设置** 修改，修改后通过心跳响应下发到 Agent，无需重启：
|
||||
|
||||
| 参数 | 说明 | Agent 字段 |
|
||||
| ---------------------- | -------------------- | ------------------ |
|
||||
| AgentHeartbeatInterval | 心跳间隔（毫秒） | heartbeat_interval |
|
||||
| NodeOfflineThreshold | 节点离线阈值（毫秒） | - |
|
||||
| AgentUpdateRepo | 自动更新仓库 | update_repo |
|
||||
|
||||
节点管理页下发的字段：
|
||||
|
||||
| 参数 | 说明 | Agent 字段 |
|
||||
| ---------------------- | ------------------ | ----------- |
|
||||
| Node.AutoUpdateEnabled | 节点是否自动更新 | auto_update |
|
||||
| Node.UpdateRequested | 节点一次性更新请求 | update_now |
|
||||
|
||||
---
|
||||
|
||||
## 10. 第五版性能优化联调重点
|
||||
|
||||
第五版联调时，至少补以下验证：
|
||||
|
||||
* 调整连接类参数后，能成功生成新版本并由 Agent 应用
|
||||
* 启用或关闭代理缓存后，主配置预览、diff 与实际落盘一致
|
||||
* 缓存目录、缓存大小、失效时间等参数非法时，Server 拒绝保存
|
||||
* 主配置渲染异常或 `openresty -t` 失败时，Agent 不应留下半更新状态
|
||||
* 本机模式与 Docker 模式都要验证一次主配置接管
|
||||
|
||||
---
|
||||
|
||||
## 11. 当前已知限制
|
||||
|
||||
* Docker 模式仍是 MVP 级封装
|
||||
* 联调以手工步骤为主
|
||||
|
||||
---
|
||||
|
||||
## 12. 文档维护要求
|
||||
|
||||
当部署方式、配置字段、节点接入方式或联调流程变化时，同步更新本文档。
|
||||
## 8. Agent 一键部署
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
支持参数：
|
||||
|
||||
* `--server-url`
|
||||
* `--discovery-token`
|
||||
* `--agent-token`
|
||||
* `--install-dir`
|
||||
* `--repo`
|
||||
* `--no-service`
|
||||
|
||||
安装脚本会下载最新 Agent、生成 `agent.json`、创建 `openflare-agent.service` 并启动服务。
|
||||
|
||||
## 9. 文档维护要求
|
||||
|
||||
部署方式、升级方式、接入模式或联调流程变化时，同步更新本文档和 `README.md`。
|
||||
|
||||
+68
-198
@@ -1,108 +1,63 @@
|
||||
# OpenFlare 设计基线
|
||||
|
||||
## 1. 文档目的
|
||||
本文档定义 OpenFlare `1.0.0` 之后仍然有效的产品边界、系统结构与长期约束。第六版已经完成并并入正式版；过程性设计不再在这里维护。
|
||||
|
||||
本文档只保留 OpenFlare 当前有效的产品边界、系统结构与稳定约束。
|
||||
## 1. 产品定位
|
||||
|
||||
当前状态：
|
||||
OpenFlare 是一套自托管的 OpenResty 控制面，面向单团队或单组织内部运维场景，解决反向代理配置、节点同步、证书托管与基础观测的统一管理问题。
|
||||
|
||||
* 第一版、第二版、第三版均已完成
|
||||
* 前端改造已完成，`openflare_server/web` 新版工程已成为正式基线
|
||||
* 第五版（0.5.x）已完成，OpenResty 反代、缓存性能优化与主配置接管已落地
|
||||
* 第六版（0.6.x）已立项，目标聚焦节点流量数据采集、访问分析与数据看板升级
|
||||
* 已完成阶段的实现细节以代码与 Git 历史为准，不再在本文档中维护过程性设计
|
||||
|
||||
---
|
||||
|
||||
## 2. 产品定位
|
||||
|
||||
OpenFlare 当前定位为内部自用的反向代理控制面，不面向外部租户提供 CDN SaaS 能力。
|
||||
|
||||
当前核心能力：
|
||||
当前稳定能力包括：
|
||||
|
||||
* 反代规则管理
|
||||
* 配置预览、发布、激活与回滚
|
||||
* Agent 注册、心跳、同步、应用结果上报
|
||||
* Agent 上报 OpenResty 运行健康状态与错误摘要
|
||||
* OpenResty 配置写入、校验、reload 与失败回滚
|
||||
* Server 向 Agent 下发受限运行指令（当前仅支持 OpenResty 重启）
|
||||
* Server 统一管理 OpenResty 主配置模板与性能优化参数
|
||||
* 反向代理链路的连接、缓冲、超时、压缩与缓存性能优化
|
||||
* HTTPS/TLS 路由支持
|
||||
* 证书托管与域名管理
|
||||
* 节点侧请求数据采集、随 heartbeat 批量上报与服务端聚合分析
|
||||
* 节点系统画像采集与展示，包括操作系统、内核、架构、CPU、内存、磁盘与在线时长
|
||||
* 节点实时资源快照、网络流量快照与 24 小时趋势展示
|
||||
* 节点健康事件归并与异常摘要展示
|
||||
* 管理端总览大盘与节点详情页的数据看板升级
|
||||
* 首页总览展示整套系统的可用性、容量、流量、异常与配置追平状态
|
||||
* 节点管理、节点专属 `agent_token`、全局 `discovery_token`
|
||||
* 配置变更摘要
|
||||
* Agent 运行参数下发
|
||||
* Agent 自我更新、一键部署、正式版默认更新与手动 preview 更新
|
||||
* Server 版本检查、正式版默认自升级、手动 preview 检查升级与手动上传二进制确认升级
|
||||
* 新版管理端 UI、主题切换与统一交互框架
|
||||
* OpenResty 主配置模板、性能参数与缓存参数托管
|
||||
* HTTPS/TLS 与域名资产管理
|
||||
* 节点请求聚合、资源快照、健康事件与看板展示
|
||||
* 节点管理、令牌体系、部署与更新链路
|
||||
* 基于 Next.js 的正式管理端前端
|
||||
|
||||
默认工作方式：
|
||||
|
||||
* 所有节点消费同一份全局激活版本
|
||||
* 控制面保存配置与状态，不直接 SSH 管理机器
|
||||
* Agent 是节点侧唯一落地入口
|
||||
* Server 保存配置与状态，不直接 SSH 管理节点
|
||||
* Agent 是节点侧唯一受控落地入口
|
||||
|
||||
---
|
||||
|
||||
## 3. 范围边界
|
||||
## 2. 范围边界
|
||||
|
||||
当前明确不做：
|
||||
|
||||
* 多租户
|
||||
* WAF、限流防护平台化、Bot 管理
|
||||
* 节点分组、灰度百分比发布、按节点差异化下发
|
||||
* Redis、消息队列、对象存储、Prometheus 等新基础设施前置依赖
|
||||
* 平台化缓存产品能力、分层缓存、mid-tier
|
||||
* CDN SaaS 化能力
|
||||
* GeoDNS、全球调度、智能选路
|
||||
* WAF、Bot 管理、限流平台化
|
||||
* 灰度百分比发布、按节点差异化配置
|
||||
* 对象存储、消息队列、Prometheus、ClickHouse、Kafka 等前置基础设施
|
||||
* 通用日志检索平台、APM、调用链系统、任意 BI 报表
|
||||
* 证书自动签发与自动续期
|
||||
* 审批流、审计中台、Purge 平台化能力
|
||||
* 平台化抽象对象，如 `zone`、`origin_pool`、`policy`、`deployment`
|
||||
|
||||
第五版边界补充：
|
||||
边界补充：
|
||||
|
||||
* 允许在 OpenResty 单节点层面引入受控的代理缓存能力，但只服务于当前反代链路优化，不扩展为独立缓存产品
|
||||
* 主配置文件由 Server 统一生成并由 Agent 受控落地，不开放节点侧手改后再回传合并
|
||||
* 性能优化参数统一在 Server 配置，不支持按节点分叉不同性能模板
|
||||
* 第五版不开放任意自定义 Nginx/OpenResty 片段上传，不提供任意指令执行入口, 但是需要保留拓展能力, 为后续开放准备
|
||||
* 允许在管理端提供 OpenResty 主配置模板编辑能力，但模板必须保留 OpenFlare 预留占位符，确保性能参数、证书目录与受管路由 include 继续由 Server 统一渲染
|
||||
* OpenResty 代理缓存只作为当前反代链路优化能力存在，不扩展为独立缓存产品
|
||||
* 主配置文件由 Server 统一渲染并由 Agent 受控写入，不支持节点侧手工编辑后回传合并
|
||||
* 节点观测聚焦运营与运维排障所需的摘要、趋势和受控窗口数据，不提供长期日志托管
|
||||
|
||||
第六版边界补充：
|
||||
新增能力如果超出上述边界，先更新本文档，再进入实现。
|
||||
|
||||
* 节点通过 heartbeat 上报最近周期内的请求明细、资源占用快照和网络流量快照，Server 负责入库、聚合与看板展示
|
||||
* 第六版参考轻量探针产品的常见数据分层方式，将节点观测拆分为“静态系统画像、周期资源快照、窗口流量聚合、健康异常事件”四类数据，而不是持续向 `nodes` 主表堆叠字段
|
||||
* 第六版的数据分析目标聚焦当前反代链路的运营观测：QPS、访问次数、访问人数、访问来源分布、访问趋势、状态码分布，以及节点级 CPU、内存、存储、磁盘 IO、入站/出站流量
|
||||
* 首页总览需要能回答“系统整体是否健康、容量是否逼近阈值、流量是否异常、是否存在配置未追平节点”这四类核心问题，可借鉴 WAF/安全大屏的信息组织方式，但不扩展为安全运营平台
|
||||
* 世界地图看板仅用于展示节点分布与节点状态，不扩展为 GeoDNS、调度、路由编排或全球流量调度系统
|
||||
* 为了支持世界地图看板，允许节点维护低频地图元数据，如位置名、纬度和经度；这类字段仍属于控制面摘要信息，可保留在 `nodes`
|
||||
* 节点详情页聚焦系统信息、实时资源、网络流量、24 小时趋势和目标版本，不继续堆积低价值静态字段
|
||||
* 在不引入 Prometheus、ClickHouse、Kafka 等新基础设施前提下完成第六版；数据采集、聚合与查询继续落在现有 Server/SQLite 基线内
|
||||
* 原始请求数据不作为长期日志平台对外开放；第六版允许保留受控时间窗口内的明细，用于聚合分析、趋势计算、节点详情辅助排查，以及管理端“日志”页面查看最近时间窗口内的访问记录
|
||||
* 第六版不做完整 APM、调用链追踪、日志检索平台、任意 SQL 分析接口或自定义报表系统
|
||||
## 3. 技术基线
|
||||
|
||||
新增能力超出上述边界时，必须先更新本文档，再进入实现。
|
||||
|
||||
---
|
||||
|
||||
## 4. 技术基线
|
||||
|
||||
### 4.1 Server
|
||||
### 3.1 Server
|
||||
|
||||
`openflare_server` 继续作为单体控制面：
|
||||
|
||||
* Gin
|
||||
* GORM
|
||||
* SQLite
|
||||
* 现有 OpenFlare 登录体系
|
||||
* 现有登录与 Session 体系
|
||||
* 托管 `openflare_server/web` 静态构建产物
|
||||
* 托管 OpenResty 主配置模板、性能参数与缓存参数
|
||||
|
||||
### 4.2 Agent
|
||||
### 3.2 Agent
|
||||
|
||||
`openflare_agent` 继续作为 Go 单体程序：
|
||||
|
||||
@@ -110,22 +65,18 @@ OpenFlare 当前定位为内部自用的反向代理控制面，不面向外部
|
||||
* 节点本地执行
|
||||
* `openresty_path` 优先
|
||||
* 未配置 `openresty_path` 时默认使用 Docker OpenResty
|
||||
* 生成资源默认落在 `./data`，可由 `data_dir` 覆盖
|
||||
* 负责接管 OpenResty 主配置文件与受管 include 文件
|
||||
|
||||
### 4.3 Frontend
|
||||
### 3.3 Frontend
|
||||
|
||||
`openflare_server/web` 作为正式管理端前端基线：
|
||||
`openflare_server/web` 是正式前端基线：
|
||||
|
||||
* Next.js App Router
|
||||
* React 19
|
||||
* TypeScript
|
||||
* Tailwind CSS
|
||||
* 静态导出，继续由 Go Server 托管
|
||||
* 静态导出后由 Go Server 托管
|
||||
|
||||
---
|
||||
|
||||
## 5. 总体架构
|
||||
## 4. 总体架构
|
||||
|
||||
```text
|
||||
OpenFlare Server (Gin + SQLite + Web UI)
|
||||
@@ -135,56 +86,36 @@ OpenFlare Server (Gin + SQLite + Web UI)
|
||||
OpenFlare Agent (register / heartbeat / sync / apply / update)
|
||||
|
|
||||
v
|
||||
Local OpenResty or Docker OpenResty
|
||||
Local OpenResty or Docker OpenResty
|
||||
|
|
||||
v
|
||||
Origin
|
||||
Origin
|
||||
```
|
||||
|
||||
职责分工：
|
||||
|
||||
* Server 负责配置、版本、节点、设置、管理端 UI 以及 OpenResty 主配置模板渲染
|
||||
* Agent 负责本地落盘、校验、reload、回滚、自更新，不负责维护独立于 Server 的主配置真相
|
||||
* Agent 负责本机观测数据的轻量采集、窗口聚合与体积控制，不直接承担长期历史查询职责
|
||||
* Server 负责配置、版本、节点、设置、证书、管理端 UI 与聚合查询
|
||||
* Agent 负责本地写入、校验、reload、回滚、自更新与轻量采集
|
||||
* 发布通过“生成完整版本并激活”完成
|
||||
* 历史版本不可变
|
||||
* Agent 常规轮询以 heartbeat 为主；heartbeat 响应返回当前激活版本的 `version` 与 `checksum` 摘要，Agent 仅在发现不一致时再拉取完整配置
|
||||
* heartbeat 响应返回激活版本摘要，Agent 仅在不一致时拉取完整配置
|
||||
|
||||
第六版观测分层：
|
||||
|
||||
* `nodes` 只承担节点身份、接入凭证、配置状态、运行控制状态等控制面字段
|
||||
* `nodes` 允许附带少量低频地图展示字段，如位置名、纬度和经度，用于总览世界看板真实落点
|
||||
* `node_system_profiles` 承担低频变化的节点系统画像，如操作系统、内核、架构、CPU 型号、逻辑核数、内存总量、磁盘布局、启动时间与 Agent 能力声明
|
||||
* `node_metric_snapshots` 承担周期性运行快照，如 CPU、负载、内存、文件系统占用、磁盘 IO、OpenResty 连接数与入站/出站吞吐
|
||||
* `node_request_reports` 承担最近心跳窗口内的请求批次或受控明细，不作为长期日志平台
|
||||
* `traffic_analytics_rollups` 承担分钟级、小时级的访问聚合结果，支持总览维度、节点维度和域名维度查询
|
||||
* `node_health_events` 承担状态变化与异常事件，如节点离线、OpenResty 不健康、配置未追平、资源逼近阈值、错误率突增
|
||||
|
||||
第六版 heartbeat 扩展思路：
|
||||
|
||||
* `profile`：低频系统画像，仅在首次注册、显著变化或周期性校准时上报
|
||||
* `snapshot`：每次 heartbeat 附带的实时资源快照
|
||||
* `traffic_report`：当前窗口的请求聚合结果与必要 TopN 分布
|
||||
* `health_events`：当前窗口内新增或恢复的异常事件
|
||||
|
||||
---
|
||||
|
||||
## 6. 核心对象
|
||||
## 5. 核心对象
|
||||
|
||||
当前有效实体：
|
||||
|
||||
* `proxy_routes`：域名到源站的反向代理规则
|
||||
* `config_versions`：完整发布快照与渲染结果
|
||||
* `nodes`：节点状态、版本、凭证与 Agent 设置相关状态
|
||||
* `node_system_profiles`：节点系统画像与硬件/软件事实信息
|
||||
* `apply_logs`：节点应用版本结果
|
||||
* `tls_certificates`：托管证书与私钥
|
||||
* `managed_domains`：域名资产及默认证书关系
|
||||
* `node_request_reports`：节点通过 heartbeat 批量上报的请求明细或请求批次
|
||||
* `node_access_logs`：节点最近时间窗口内的受控访问明细，仅保留用于管理端排查的必要字段
|
||||
* `node_metric_snapshots`：节点实时资源、磁盘 IO 与网络流量快照
|
||||
* `traffic_analytics_rollups`：按时间窗口聚合后的访问指标，用于总览与节点详情看板
|
||||
* `node_health_events`：节点运行状态变化、阈值异常与配置偏差事件
|
||||
* `proxy_routes`
|
||||
* `config_versions`
|
||||
* `nodes`
|
||||
* `node_system_profiles`
|
||||
* `apply_logs`
|
||||
* `tls_certificates`
|
||||
* `managed_domains`
|
||||
* `node_request_reports`
|
||||
* `node_access_logs`
|
||||
* `node_metric_snapshots`
|
||||
* `traffic_analytics_rollups`
|
||||
* `node_health_events`
|
||||
|
||||
稳定约束：
|
||||
|
||||
@@ -194,24 +125,11 @@ OpenFlare Agent (register / heartbeat / sync / apply / update)
|
||||
* `config_versions` 必须保存完整快照、渲染结果与 `checksum`
|
||||
* 全局同时只能有一个激活版本
|
||||
* 回滚通过重新激活旧版本实现
|
||||
* 激活版本中的 OpenResty 渲染结果必须包含主配置与路由配置的统一快照
|
||||
* 域名与证书匹配同时支持精确匹配与通配符匹配
|
||||
* 节点专属 `agent_token` 必须可立即失效
|
||||
* `nodes` 不承担高频观测事实存储；高频运行时字段必须进入快照、聚合或事件表
|
||||
* OpenResty 性能优化参数与缓存参数统一由 Server 设置管理，不允许节点侧形成额外配置源
|
||||
* OpenResty 主配置模板允许编辑，但必须保留系统要求的占位符，不能绕过结构化参数校验与受管 include 注入
|
||||
* Agent 只应用受控主配置文件，不提供任意配置片段拼接入口
|
||||
* 节点请求数据必须随 heartbeat 按批次上报，Server 不主动反向拉取节点日志文件
|
||||
* 指标看板使用服务端聚合结果，不在前端重复做大规模统计计算
|
||||
* 节点资源快照与请求明细必须能按时间排序并绑定节点，保证 24 小时趋势与节点详情可回放
|
||||
* 管理端日志页只展示受控保留窗口内的必要访问字段，如原始来源 IP、来源地区、访问域名、路径、命中的节点与响应状态码，不演变为通用日志检索平台
|
||||
* 原始请求明细、聚合统计与节点基础状态必须在时间窗口上可对齐
|
||||
* 首页总览的系统状态必须基于统一服务端口径生成，不能由多个历史列表接口在前端临时拼装推导
|
||||
* 健康事件必须支持“触发中/已恢复”状态，避免首页异常永远累积
|
||||
* `nodes` 只承载控制面状态与低频摘要，不承载高频观测事实
|
||||
* 指标、趋势和访问分析优先使用服务端聚合结果，而不是前端临时统计
|
||||
* 访问明细只保留受控时间窗口，不演变成通用日志平台
|
||||
|
||||
---
|
||||
|
||||
## 7. 发布模型
|
||||
## 6. 发布模型
|
||||
|
||||
标准链路：
|
||||
|
||||
@@ -222,96 +140,48 @@ OpenFlare Agent (register / heartbeat / sync / apply / update)
|
||||
发布规则：
|
||||
|
||||
1. 读取全部启用的 `proxy_routes`
|
||||
2. 读取 Server 侧受管 OpenResty 性能参数与缓存参数
|
||||
2. 读取 Server 侧 OpenResty 主配置与结构化参数
|
||||
3. 渲染完整 OpenResty 配置
|
||||
4. 计算 `checksum`
|
||||
5. 写入 `config_versions`
|
||||
6. 切换激活版本
|
||||
7. Agent 在后续同步中发现并应用
|
||||
7. Agent 在后续 heartbeat 中发现并应用
|
||||
|
||||
版本规则：
|
||||
版本号格式固定为 `YYYYMMDD-NNN`。
|
||||
|
||||
* 版本号格式：`YYYYMMDD-NNN`
|
||||
* 版本不可变
|
||||
* 节点只拉取当前激活版本
|
||||
## 7. 模块边界
|
||||
|
||||
---
|
||||
|
||||
## 8. 模块边界
|
||||
|
||||
### 8.1 `openflare_server`
|
||||
### 7.1 `openflare_server`
|
||||
|
||||
负责：
|
||||
|
||||
* 管理端 UI 与 API
|
||||
* Agent API
|
||||
* 数据存储
|
||||
* 配置渲染
|
||||
* OpenResty 主配置模板管理
|
||||
* OpenResty 性能参数与缓存参数管理
|
||||
* 发布与激活
|
||||
* 节点状态与设置管理
|
||||
* 配置渲染与版本发布
|
||||
* 数据存储与聚合查询
|
||||
* OpenResty 主配置模板、性能参数与缓存参数管理
|
||||
|
||||
### 8.2 `openflare_agent`
|
||||
### 7.2 `openflare_agent`
|
||||
|
||||
负责：
|
||||
|
||||
* 首次注册与凭证置换
|
||||
* 周期性心跳与同步
|
||||
* 运行参数接收
|
||||
* 采集最近周期内的请求明细、资源占用和网络流量
|
||||
* 主配置文件、路由配置与必要证书文件写入
|
||||
* 主配置、路由配置、证书与 Lua 资源写入
|
||||
* 执行 `openresty -t` / `openresty -s reload`
|
||||
* 失败回滚
|
||||
* 自我更新
|
||||
* 应用结果上报
|
||||
* 节点观测采集与结果上报
|
||||
|
||||
### 8.3 `openflare_server/web`
|
||||
### 7.3 `openflare_server/web`
|
||||
|
||||
负责：
|
||||
|
||||
* 管理端页面、布局、交互与主题
|
||||
* 总览世界地图、访问分析看板与节点详情监控视图
|
||||
* 规则、版本、节点、证书、域名、用户、设置、性能等页面
|
||||
* 总览、节点详情、规则、版本、节点、证书、域名、用户与设置页面
|
||||
* 统一请求层与前端状态管理
|
||||
|
||||
---
|
||||
|
||||
## 9. 接口域
|
||||
|
||||
管理端接口当前覆盖：
|
||||
|
||||
* `proxy-routes`
|
||||
* `config-versions`
|
||||
* `nodes`
|
||||
* `apply-logs`
|
||||
* `tls-certificates`
|
||||
* `managed-domains`
|
||||
* `users`
|
||||
* `settings`
|
||||
* `update`
|
||||
|
||||
Agent 接口当前覆盖：
|
||||
|
||||
* 注册
|
||||
* 心跳
|
||||
* 获取激活版本
|
||||
* 上报应用结果
|
||||
* 通过心跳回传 OpenResty 健康状态并接收受限运行指令
|
||||
|
||||
统一约束：
|
||||
|
||||
* 管理端与 Agent API 均使用 JSON
|
||||
* Agent API 固定放在 `/api/agent/*`
|
||||
* Agent 鉴权统一使用 `X-Agent-Token`
|
||||
* OpenResty 性能优化相关配置通过现有设置域统一管理，不新增节点直连配置入口
|
||||
|
||||
---
|
||||
|
||||
## 10. 文档维护原则
|
||||
|
||||
后续只维护当前有效基线：
|
||||
## 8. 文档维护原则
|
||||
|
||||
* 产品范围或系统边界变化时更新本文档
|
||||
* 已完成阶段的步骤不再回填为长期计划
|
||||
* 已完成阶段不再以“版本计划”形式回填
|
||||
* 新阶段开始前，先补设计，再进入实现
|
||||
|
||||
+57
-228
@@ -1,24 +1,12 @@
|
||||
# OpenFlare 开发规范
|
||||
|
||||
## 1. 适用范围
|
||||
本文档描述 OpenFlare `1.0.0` 正式版之后的开发基线。
|
||||
|
||||
本规范适用于当前代码基线下的所有 Server、Agent 与管理端前端开发工作。
|
||||
超出 [docs/design.md](./design.md) 边界的需求，必须先更新设计文档。
|
||||
|
||||
当前状态：
|
||||
## 1. 技术基线
|
||||
|
||||
* 第一版、第二版、第三版已完成
|
||||
* `docs/design.md` 是当前系统边界的唯一设计基线
|
||||
* `openflare_server/web` 新版前端已完成迁移并成为正式基线
|
||||
* 第五版（0.5.x）已完成
|
||||
* 第六版（0.6.x）以节点流量数据采集、访问分析与看板升级为主线
|
||||
|
||||
超出设计边界的需求，必须先更新 [docs/design.md](./design.md)。
|
||||
|
||||
---
|
||||
|
||||
## 2. 技术基线
|
||||
|
||||
### 2.1 Server
|
||||
### 1.1 Server
|
||||
|
||||
`openflare_server` 继续作为单体控制面：
|
||||
|
||||
@@ -26,15 +14,9 @@
|
||||
* Gin
|
||||
* GORM
|
||||
* SQLite
|
||||
* 现有 OpenFlare 登录体系
|
||||
* 现有登录体系
|
||||
|
||||
约束：
|
||||
|
||||
* 默认不引入 Redis、MQ、对象存储等新基础设施
|
||||
* 不为未确认的平台化能力预埋复杂抽象
|
||||
* OpenResty 性能参数、缓存参数与主配置模板优先复用现有 `Option` 体系管理，不为单一版本额外引入配置中心
|
||||
|
||||
### 2.2 Agent
|
||||
### 1.2 Agent
|
||||
|
||||
`openflare_agent` 继续作为 Go 单体程序：
|
||||
|
||||
@@ -43,11 +25,10 @@
|
||||
* 节点本地执行
|
||||
* `openresty_path` 优先
|
||||
* 无 `openresty_path` 时默认 Docker OpenResty
|
||||
* 生成资源默认写入 `./data`，由 `data_dir` 统一覆盖
|
||||
|
||||
### 2.3 Frontend
|
||||
### 1.3 Frontend
|
||||
|
||||
新版前端基线以当前 `openflare_server/web` 实现为准：
|
||||
前端基线以 `openflare_server/web` 为准：
|
||||
|
||||
* Next.js 15 App Router
|
||||
* React 19
|
||||
@@ -55,40 +36,36 @@
|
||||
* Tailwind CSS 4
|
||||
* TanStack Query
|
||||
* React Hook Form + Zod
|
||||
* Zustand（仅限轻量客户端状态）
|
||||
* 静态导出并由 Go Server 托管
|
||||
* Zustand 仅用于轻量客户端状态
|
||||
|
||||
前端详细约束统一以 [docs/frontend-development-guidelines.md](./frontend-development-guidelines.md) 为准；本文件只保留跨项目层面的强约束。
|
||||
前端细则见 [docs/frontend-development-guidelines.md](./frontend-development-guidelines.md)。
|
||||
|
||||
---
|
||||
## 2. 分层与目录约束
|
||||
|
||||
## 3. 分层与目录约束
|
||||
|
||||
### 3.1 Server
|
||||
### 2.1 Server
|
||||
|
||||
* `controller/`：参数解析、调用 service、返回响应
|
||||
* `service/`：业务逻辑、校验、渲染、事务编排
|
||||
* `service/`：业务逻辑、校验、事务编排、渲染
|
||||
* `model/`：模型定义与持久化
|
||||
* `router/`：路由注册
|
||||
* `middleware/`：认证、鉴权、限流等横切逻辑
|
||||
* `common/`：配置、全局运行时状态与初始化入口
|
||||
* `utils/`：纯工具函数与通用 helper；按功能聚合，多个同类 helper 应拆到对应子目录
|
||||
* `common/`：配置、全局状态与初始化入口
|
||||
* `utils/`：纯工具函数与通用 helper
|
||||
|
||||
禁止：
|
||||
|
||||
* 在 `controller/` 堆积业务逻辑
|
||||
* 在 `middleware/` 中实现业务流程
|
||||
* 在 `middleware/` 实现业务流程
|
||||
* 为简单需求新增平台层抽象
|
||||
* 在 `common/` 混放不依赖全局状态的纯工具实现
|
||||
|
||||
### 3.2 Agent
|
||||
### 2.2 Agent
|
||||
|
||||
保持现有模块边界：
|
||||
|
||||
* `config`
|
||||
* `heartbeat`
|
||||
* `sync`
|
||||
* `openresty`（保留目录名，内部负责 OpenResty 运行时管理）
|
||||
* `openresty`
|
||||
* `state`
|
||||
* `httpclient`
|
||||
* `protocol`
|
||||
@@ -99,29 +76,25 @@
|
||||
* 每个模块职责单一
|
||||
* 外部命令调用集中封装
|
||||
* 状态落盘与配置落盘分离
|
||||
* 主配置文件写入、备份、校验、回滚与受管 include 写入应归并到 OpenResty 运行时管理模块
|
||||
|
||||
### 3.3 Frontend
|
||||
### 2.3 Frontend
|
||||
|
||||
前端分层与目录必须与当前工程保持一致：
|
||||
前端分层保持：
|
||||
|
||||
* `app/`：路由、布局、页面组装
|
||||
* `features/`：业务模块
|
||||
* `components/`：跨模块复用组件
|
||||
* `lib/`：请求、环境、工具、常量
|
||||
* `store/`：少量跨页面 UI 状态
|
||||
* `types/`：共享类型
|
||||
* `app/`
|
||||
* `features/`
|
||||
* `components/`
|
||||
* `lib/`
|
||||
* `store/`
|
||||
* `types/`
|
||||
|
||||
要求：
|
||||
|
||||
* 页面路由与布局放在 `app/`
|
||||
* API 请求统一收敛到 `lib/api/`
|
||||
* 业务逻辑优先放在 `features/`
|
||||
* 不重新引入旧版 CRA / Semantic UI 结构
|
||||
|
||||
---
|
||||
|
||||
## 4. 数据模型规范
|
||||
## 3. 数据模型规范
|
||||
|
||||
当前有效实体：
|
||||
|
||||
@@ -137,42 +110,30 @@
|
||||
* `node_metric_snapshots`
|
||||
* `traffic_analytics_rollups`
|
||||
* `node_health_events`
|
||||
* `options`（运行时参数与 OpenResty 调优参数继续复用现有配置表，不扩展为独立新实体）
|
||||
* `options`
|
||||
|
||||
通用约束：
|
||||
|
||||
* 不新增平台化对象，除非设计文档明确要求
|
||||
* `proxy_routes` 仍保持一条域名对应一个 `origin_url`
|
||||
* `proxy_routes` 维持一条域名对应一个 `origin_url`
|
||||
* `config_versions` 必须保存完整快照与渲染结果
|
||||
* 全局同时只能有一个激活版本
|
||||
* 回滚通过重新激活旧版本实现
|
||||
* 第五版新增的 OpenResty 性能参数必须由 Server 统一保存与校验，并参与版本渲染
|
||||
* 域名证书匹配必须同时支持精确匹配与通配符匹配
|
||||
* 节点专属 `agent_token` 必须可立即失效
|
||||
* `nodes` 只保留控制面与摘要状态，不直接承接第六版新增的高频资源字段、完整系统画像和大块统计结果
|
||||
* `nodes` 允许保留世界地图展示所需的少量低频字段，如位置名、纬度和经度；这类字段不得演变成高频观测事实承载体
|
||||
* `node_system_profiles` 负责存储低频变化的节点事实信息；只有需要列表摘要展示的极少数字段可以回写到 `nodes`
|
||||
* 第六版新增的请求明细、资源快照和聚合统计必须按节点与时间窗口关联
|
||||
* `node_metric_snapshots` 必须是追加式时间序列快照，不通过覆盖 `nodes` 当前值替代历史
|
||||
* `traffic_analytics_rollups` 必须区分时间粒度与统计范围，优先存储窗口聚合而不是无限制保留原始逐请求明细
|
||||
* `node_access_logs` 仅保留管理端排查所需的受控访问字段与短期保留窗口，不承担全文检索或长期归档职责
|
||||
* `node_health_events` 必须具备事件类型、严重级别、首次触发时间、最近触发时间和恢复时间，便于首页总览做异常归并
|
||||
* 访问分析优先复用现有 Server/SQLite 基线，不为第六版引入新的时序数据库或消息队列
|
||||
* 聚合统计与原始明细的保留策略必须明确，避免无限制累积
|
||||
* `nodes` 只保留控制面状态与低频摘要
|
||||
* 观测数据必须按节点与时间窗口关联
|
||||
* 快照与聚合结果采用追加式模型，不覆盖历史
|
||||
* 原始访问明细必须有受控保留策略
|
||||
|
||||
---
|
||||
## 4. API 与鉴权规范
|
||||
|
||||
## 5. API 与鉴权规范
|
||||
|
||||
### 5.1 API
|
||||
### 4.1 API
|
||||
|
||||
* 管理端与 Agent API 统一使用 JSON
|
||||
* 成功与失败都必须返回清晰 `message`
|
||||
* 列表接口返回稳定字段
|
||||
* Agent API 固定放在 `/api/agent/*`
|
||||
* 第六版总览页与节点详情页优先新增专用聚合接口，不继续依赖多个旧列表接口在前端拼装
|
||||
* 总览与节点详情优先使用专用聚合接口
|
||||
|
||||
统一响应结构保持现有风格：
|
||||
统一响应结构：
|
||||
|
||||
```json
|
||||
{
|
||||
@@ -182,61 +143,38 @@
|
||||
}
|
||||
```
|
||||
|
||||
### 5.2 鉴权
|
||||
### 4.2 鉴权
|
||||
|
||||
管理端：
|
||||
|
||||
* 继续复用 OpenFlare 登录、角色与 session
|
||||
* 继续复用现有登录、角色与 Session
|
||||
|
||||
Agent：
|
||||
|
||||
* 正式请求统一使用节点专属 `agent_token`
|
||||
* 首次接入可使用全局 `discovery_token`
|
||||
* 请求头统一使用 `X-Agent-Token`
|
||||
* Agent 认证逻辑不得与用户登录态混用
|
||||
|
||||
禁止：
|
||||
|
||||
* 将本地 OpenResty 操作暴露为远程执行接口
|
||||
* 用通用 shell/命令执行方式替代受限节点操作接口
|
||||
* 暴露远程 shell 或任意命令执行入口
|
||||
* 在日志中打印完整 Token
|
||||
* 为性能优化需求开放任意 OpenResty 文本片段上传或任意指令下发
|
||||
* 允许绕过系统占位符约束直接保存不可渲染的 OpenResty 主配置模板
|
||||
* 允许绕过占位符约束保存不可渲染的主配置模板
|
||||
|
||||
---
|
||||
|
||||
## 6. 发布与运行规范
|
||||
## 5. 发布与运行规范
|
||||
|
||||
发布逻辑必须保持以下事实：
|
||||
|
||||
* 发布时读取全部启用的 `proxy_routes`
|
||||
* 发布时同时读取 Server 侧 OpenResty 主配置参数、反代性能参数与缓存参数
|
||||
* 同时读取 OpenResty 主配置参数、反代性能参数与缓存参数
|
||||
* 生成完整 OpenResty 配置
|
||||
* 计算 `checksum`
|
||||
* 写入 `config_versions`
|
||||
* 通过切换 `is_active` 激活版本
|
||||
|
||||
Go 版本基线约束：
|
||||
|
||||
* 当 `go.mod` 中的 Go 主版本或次版本发生变化时，必须同步检查并更新所有相关构建入口，至少包括 Docker 构建使用的基础镜像版本以及 GitHub Actions 中的 release / docker 发布工作流
|
||||
* 版本升级后必须确保本地构建、Docker 构建与发布工作流使用一致的 Go 版本，避免因为 `go.mod`、`Dockerfile` 与 CI 工作流版本漂移导致发布失败
|
||||
|
||||
第五版新增要求：
|
||||
|
||||
* “完整 OpenResty 配置”至少包括主配置文件与路由配置文件
|
||||
* 主配置文件的真相源在 Server，Agent 只负责受控写入、校验与回滚
|
||||
* 性能优化参数必须通过结构化字段渲染，禁止直接拼接未经校验的自由文本
|
||||
* 新增参数命名统一采用 `OpenResty...` 前缀，布尔值、整数、大小单位和时间单位必须在更新入口做校验
|
||||
* 主配置模板编辑必须保留系统要求的占位符，由 Server 在发布与预览时再渲染为最终 `nginx.conf`
|
||||
|
||||
版本号格式保持：
|
||||
|
||||
```text
|
||||
YYYYMMDD-NNN
|
||||
```
|
||||
|
||||
限制：
|
||||
版本约束：
|
||||
|
||||
* 版本号格式固定为 `YYYYMMDD-NNN`
|
||||
* 不在线修改历史版本
|
||||
* 不做按节点分组的差异化版本
|
||||
* 预览与 diff 是只读能力，不产生发布记录
|
||||
@@ -244,135 +182,26 @@ YYYYMMDD-NNN
|
||||
Agent 必须满足：
|
||||
|
||||
* 启动后读取或生成本地 `node_id`
|
||||
* 未显式配置 `node_name` 时自动获取主机名
|
||||
* 未显式配置 `node_ip` 时自动探测本机 IP
|
||||
* 周期性心跳与同步
|
||||
* 常规同步判定优先通过 heartbeat 响应中的激活版本 `version` / `checksum` 摘要完成；仅在 Agent 本地状态与摘要不一致时，再请求完整激活配置
|
||||
* heartbeat 请求体允许携带最近周期内的系统画像变更、资源快照、磁盘 IO 快照、入站/出站流量快照、访问聚合批次和健康事件
|
||||
* 常规同步优先依据 heartbeat 返回的版本摘要判断
|
||||
* 发现新版本时先备份旧文件
|
||||
* 写入新的主配置、路由配置与必要证书文件
|
||||
* 写入主配置、路由配置与必要证书文件
|
||||
* 先执行 `openresty -t`
|
||||
* 成功后执行 `openresty -s reload`
|
||||
* 失败时自动回滚并上报最终结果
|
||||
* 周期性向 Server 回传 OpenResty 当前健康状态与最近运行错误摘要
|
||||
* 支持自动注册与 Token 置换
|
||||
* 支持接收 Server 下发运行参数
|
||||
* 支持接收 Server 下发的受限运行指令，当前仅允许 OpenResty 重启
|
||||
* 支持自我更新，但失败不影响心跳与同步
|
||||
* 主配置接管模式下，必须保证主配置与受管 include 一起回滚，不能只回滚其中一部分
|
||||
* 请求明细采集失败、聚合失败或单次 heartbeat 上报失败时，不得阻断后续心跳与配置同步主链路
|
||||
* 节点侧指标采集必须优先读取 OpenResty 与本机运行时状态，不允许引入任意 shell 采集脚本拼接执行
|
||||
* 大批量请求上报必须具备批次边界和体积控制，避免单次 heartbeat 无限制膨胀
|
||||
* 节点侧应优先做窗口聚合后再上报，避免把逐请求原始日志持续搬运到 Server
|
||||
* 低频系统画像应支持变更检测，避免每次 heartbeat 重复上报大块静态信息
|
||||
* UV、来源分布、状态码分布等统计应在节点侧或服务端按窗口聚合，禁止前端再对原始明细做重型计算
|
||||
|
||||
第六版新增规范：
|
||||
## 6. 测试与交付要求
|
||||
|
||||
* 总览页默认展示世界地图节点分布、核心访问指标、趋势图和关键异常，不再以多个对称摘要卡片作为唯一主结构
|
||||
* 总览页必须能直接展示系统整体运行状况，至少覆盖节点在线率、OpenResty 健康、配置追平状态、容量风险与流量异常
|
||||
* 总览页异常区优先展示可行动的问题，如离线节点、配置落后节点、资源逼近阈值节点、错误率异常节点
|
||||
* 世界地图看板如需真实落点，应优先消费节点上维护的低频位置元数据，不在前端引入不可控的临时地理解析逻辑
|
||||
* 节点详情页第一屏至少覆盖系统信息、实时资源占用、网络流量与 24 小时历史趋势
|
||||
* 系统信息卡片除现有 Agent 版本、Nginx 版本、当前配置外，新增操作系统、CPU 型号、在线时长
|
||||
* 实时资源卡片展示 CPU、内存、存储占用，优先以仪表盘或等效高密度可视化呈现
|
||||
* 网络流量卡片展示经过 OpenResty 的入站和出站流量，并按 KB/MB/GB 自动换算
|
||||
* 节点详情页保留“当前目标版本”等高价值运维信息，但应下移到趋势区之后，避免抢占首屏
|
||||
* 节点详情页需要区分“静态画像”和“实时状态”，禁止把二者混在一组无层次字段列表中
|
||||
* 关键业务逻辑必须有单元测试或等效回归测试
|
||||
* Agent 主链路修改必须验证同步、应用与回滚
|
||||
* 前端页面至少覆盖加载态、空态、错误态与成功反馈
|
||||
* Go 版本调整时，同步检查 `go.mod`、Dockerfile 与 CI 工作流
|
||||
|
||||
第六版实现约束补充：
|
||||
## 7. 文档维护要求
|
||||
|
||||
* 优先新增 `dashboard` / `node detail` 聚合 service，避免在旧 `node` service 上不断打补丁叠加查询逻辑
|
||||
* SQLite 查询应优先围绕“节点 + 时间窗口 + 粒度”建立索引与查询入口，避免首页每次全表扫描历史快照
|
||||
* TopN 榜单、来源分布、状态码分布等复杂结果允许以受控 JSON 结构写入聚合表，但必须保证字段稳定可测试
|
||||
* 异常阈值判断必须收敛在服务端统一实现，前端只负责展示，不复制阈值逻辑
|
||||
* 测试至少覆盖 heartbeat 扩展兼容性、聚合正确性、异常恢复状态切换和关键 dashboard 查询口径
|
||||
|
||||
---
|
||||
|
||||
## 7. 前端约束
|
||||
|
||||
前端新增开发必须遵循 [docs/frontend-development-guidelines.md](./frontend-development-guidelines.md)，其中以下要求属于项目级强约束：
|
||||
|
||||
* 页面与布局放在 `app/`，业务逻辑放在 `features/`
|
||||
* 请求统一通过 `lib/api/`
|
||||
* 构建产物必须保持可被 Go Server 静态托管
|
||||
* 主题能力必须覆盖布局、基础组件与业务页面
|
||||
* 不引入新的大型 UI 框架与旧式页面结构
|
||||
|
||||
---
|
||||
|
||||
## 8. 代码风格与日志
|
||||
|
||||
### 8.1 Go
|
||||
|
||||
* 错误必须显式处理
|
||||
* 函数尽量单一职责
|
||||
* 输入校验放在边界层
|
||||
* 业务枚举使用明确常量
|
||||
* 不写无意义注释
|
||||
|
||||
### 8.2 命名
|
||||
|
||||
* 统一使用 `route`、`version`、`node`、`agent`
|
||||
* 不混用 `client`、`edge`、`worker` 指代 Agent
|
||||
|
||||
### 8.3 日志
|
||||
|
||||
必须覆盖关键事件：
|
||||
|
||||
* 发布成功/失败
|
||||
* Agent 注册
|
||||
* 心跳异常
|
||||
* 配置下载失败
|
||||
* OpenResty 校验或 reload 成功/失败
|
||||
* 回滚触发
|
||||
|
||||
要求：
|
||||
|
||||
* Server 与 Agent 统一使用 `slog` 输出结构化日志
|
||||
* 日志足够定位问题
|
||||
* 不打印敏感凭证完整值
|
||||
|
||||
---
|
||||
|
||||
## 9. 测试与验收
|
||||
|
||||
基线回归至少覆盖：
|
||||
|
||||
* 路由校验与渲染
|
||||
* 激活版本切换
|
||||
* 节点在线状态判定
|
||||
* 证书导入与匹配
|
||||
* 自定义请求头渲染
|
||||
* OpenResty 主配置渲染
|
||||
* OpenResty 性能参数与缓存参数校验
|
||||
* Agent 同步、回滚、本地状态读写
|
||||
* 自动注册与 Token 置换
|
||||
* Agent 设置下发与更新链路
|
||||
* 预览与 diff 的只读行为
|
||||
|
||||
新增需求时：
|
||||
|
||||
* 先补单元测试或服务层测试
|
||||
* 再补联调验证步骤
|
||||
* 涉及发布链路、Agent 链路、鉴权链路的改动，必须补回归测试
|
||||
* 涉及 OpenResty 主配置或缓存行为的改动，必须补 `openresty -t` 校验场景与失败回滚场景
|
||||
|
||||
---
|
||||
|
||||
## 10. 文档维护
|
||||
|
||||
出现以下情况必须同步更新文档：
|
||||
当以下内容变化时，必须同步更新对应文档：
|
||||
|
||||
* 产品范围或系统边界变化：更新 `docs/design.md`
|
||||
* 开发约束、接口约定、前后端分层变化：更新本文件
|
||||
* 前端目录分层、请求层、主题体系变化：更新 `docs/frontend-development-guidelines.md`
|
||||
* 部署方式变化：更新 `docs/deployment.md` 和 `README.md`
|
||||
* 环境变量或配置项变化：更新 `docs/app-config.md`
|
||||
|
||||
## 11. Swagger 约束
|
||||
|
||||
* Server 提供 Swagger UI 入口：`/swagger/index.html`
|
||||
* Swagger UI 仅对已登录的管理端用户开放
|
||||
* 新增或修改 API 时，必须同步更新 Swag 注解并重新生成 `openflare_server/docs`
|
||||
* 开发约束、接口约定、测试基线变化：更新本文档
|
||||
* 前端工程约束变化：更新 `docs/frontend-development-guidelines.md`
|
||||
* 配置项或部署方式变化：更新 `docs/app-config.md`、`docs/deployment.md` 与 `README.md`
|
||||
|
||||
+33
-247
@@ -1,264 +1,50 @@
|
||||
# OpenFlare 开发计划
|
||||
|
||||
## 1. 当前状态
|
||||
## 1. 当前结论
|
||||
|
||||
当前结论：
|
||||
* 第一版至第六版的主线能力已经全部完成
|
||||
* `1.0.0` 是当前正式基线
|
||||
* 已完成阶段的过程性任务以代码、测试与 Git 历史为准
|
||||
* 新工作优先以缺陷修复、可维护性改进、文档与测试补强为主
|
||||
|
||||
* 第一版至第五版主线能力均已完成
|
||||
* 已完成阶段的过程性任务不再继续展开维护
|
||||
* 当前主线切换到第六版（0.6.x）
|
||||
## 2. 当前优先级
|
||||
|
||||
第六版主目标：
|
||||
当前开发应优先关注：
|
||||
|
||||
* 为节点增加请求数据采集、资源采集与 heartbeat 上报能力
|
||||
* 在 Server 侧完成访问分析、趋势计算与聚合查询
|
||||
* 改造管理端总览页与节点详情页，提升信息密度、数据层次和监控可读性
|
||||
* 建立可持续扩展的观测数据分层，避免在旧节点模型和旧首页接口上继续补丁式堆功能
|
||||
1. 稳定性
|
||||
2. 升级与回滚链路可靠性
|
||||
3. 文档准确性
|
||||
4. 测试覆盖补强
|
||||
5. 在既有边界内的小步迭代
|
||||
|
||||
第六版当前进展（按当前代码基线）：
|
||||
## 3. 变更准入原则
|
||||
|
||||
* 已完成 heartbeat 扩展协议与观测数据分层落地，节点已支持上报 `profile`、`snapshot`、`traffic_report`、`health_events`
|
||||
* 已完成 Server 侧观测模型、入库链路与查询接口，节点观测已拆分为系统画像、资源快照、窗口流量聚合、健康事件
|
||||
* 已完成 Agent 侧真实请求窗口聚合采集，当前通过受管 OpenResty Lua 观测脚本与本地指标端口输出窗口聚合结果，不再依赖访问日志增量读取
|
||||
* 已完成节点详情观测接口与页面第一轮改造，当前已支持系统画像、实时资源、运行状态、24 小时趋势、状态码分布、Top Domain 与健康事件时间线
|
||||
* 已完成首页总览专用聚合接口与首页第一轮改造，当前已支持系统运行总览、风险态势、峰值摘要、24 小时趋势、节点健康列表与活动异常
|
||||
* 已完成首页风险态势到节点页的轻量筛选联动，支持从总览跳转到节点页查看离线节点、OpenResty 异常节点与配置落后节点
|
||||
* 已完成首页总览首屏重构第一版，当前已具备全球态势板、系统健康摘要、请求/容量/网络/磁盘趋势、来源分布、状态码分布与 Top Domain 看板
|
||||
* 当前世界板已先接入全球来源信号与节点健康覆盖，节点真实地理点位仍待后续补充地域元数据后进一步完善
|
||||
* 已完成节点详情页第二轮重构，当前首屏已支持系统画像、实时资源、网络流量三块核心卡，以及 24 小时 CPU/请求/网络/磁盘 IO 趋势、请求结构分布、健康事件时间线与运维模块下移
|
||||
* 首页大盘的进一步态势化增强与告警规则联动仍处于后续阶段
|
||||
新需求进入实现前，按以下顺序判断：
|
||||
|
||||
---
|
||||
1. 是否符合 [docs/design.md](./design.md) 的产品边界
|
||||
2. 是否符合 [docs/development-guidelines.md](./development-guidelines.md) 与前端规范
|
||||
3. 是否会破坏现有发布、同步、回滚或升级主链路
|
||||
4. 是否需要同步更新部署、配置或 README 文档
|
||||
|
||||
## 2. 已完成范围压缩归档
|
||||
如果答案包含“超出边界”或“引入新基础设施”，先修改设计文档，再开始实现。
|
||||
|
||||
已完成能力统一归档为以下几类：
|
||||
## 4. 当前验收标准
|
||||
|
||||
* 反代规则、配置版本、预览、发布、激活、回滚
|
||||
* Agent 注册、心跳、同步、应用、失败回滚
|
||||
* HTTPS/TLS、证书托管、域名管理
|
||||
* 节点管理、令牌体系、部署与更新链路
|
||||
* OpenResty 性能优化、缓存配置与主配置托管
|
||||
* 新版管理端前端、主题与统一交互框架
|
||||
任何合入正式基线的改动，至少应满足：
|
||||
|
||||
归档原则：
|
||||
* 不破坏 Agent 心跳、同步、发布与回滚主链路
|
||||
* 不破坏现有 OpenResty 主配置托管模型
|
||||
* 不降低总览、节点详情与访问分析的既有可用性
|
||||
* 有与风险相称的测试或联调验证
|
||||
* 文档与代码保持一致
|
||||
|
||||
* 第一版至第五版的实施细节以代码与 Git 历史为准
|
||||
* 本文件只维护当前有效主线，不再保留已完成阶段的过程性拆分
|
||||
* `docs/improve_plan.md` 继续作为并行整理清单存在，但不覆盖第六版主线优先级
|
||||
## 5. 后续维护方式
|
||||
|
||||
---
|
||||
后续规划不再按“大版本阶段文档”维护，而采用以下方式：
|
||||
|
||||
## 3. 第六版范围
|
||||
* 产品边界变动：更新 `docs/design.md`
|
||||
* 工程约束变动：更新 `docs/development-guidelines.md`
|
||||
* 前端工程变动：更新前端相关规范文档
|
||||
* 部署与配置变动：更新 `README.md`、`docs/deployment.md`、`docs/app-config.md`
|
||||
|
||||
### 3.1 第六版要做
|
||||
|
||||
1. 节点数据采集与上报
|
||||
* Agent 在每次 heartbeat 时上报最近周期内的请求数据
|
||||
* Agent 同步上报节点系统画像、CPU/内存/存储快照、磁盘 IO、OpenResty 入站/出站流量
|
||||
* 新增在线时长、操作系统、内核、架构、CPU 型号、逻辑核数、总内存、磁盘布局等节点维度信息
|
||||
* 采集节点健康事件，覆盖离线、OpenResty 不健康、配置未追平、资源逼近阈值和错误率异常
|
||||
|
||||
2. 服务端访问分析
|
||||
* 基于请求数据计算当前节点 QPS、访问次数、访问人数
|
||||
* 统计访问来源分布、访问趋势、状态码分布等核心指标
|
||||
* 支持总览维度与节点维度两套查询视图
|
||||
* 生成系统整体健康摘要，回答“是否健康、是否有风险、问题集中在哪些节点”
|
||||
|
||||
3. 总览页改造
|
||||
* 首屏新增世界地图看板，用于展示全部节点分布与在线状态
|
||||
* 调整总览信息结构，不再以单一“四卡摘要”作为主布局
|
||||
* 增加趋势、分布、Top 榜单、容量风险和异常信号展示
|
||||
* 引入类似 WAF/安全运营面板的信息组织方式，但聚焦 OpenFlare 当前系统健康与流量状态
|
||||
|
||||
4. 节点详情页改造
|
||||
* 第一行重构为三块核心卡片：系统信息、实时资源占用、网络流量监控
|
||||
* 第二行展示最近 24 小时历史趋势，至少覆盖 CPU、网络、磁盘 IO
|
||||
* 第三行接续当前目标版本与应用记录等运维信息
|
||||
* 清理低价值、重复、信息密度低的展示模块
|
||||
|
||||
5. 架构可扩展性治理
|
||||
* 将节点观测拆分为静态画像、动态快照、窗口聚合、健康事件四类数据
|
||||
* 为总览页和节点详情页建立专用聚合接口，不继续依赖旧列表接口临时拼装
|
||||
* 控制原始数据保留窗口和聚合粒度，避免后期查询、存储和维护成本失控
|
||||
|
||||
### 3.2 第六版不做
|
||||
|
||||
* 不引入 Prometheus、ClickHouse、Kafka、ElasticSearch 等新基础设施
|
||||
* 不建设通用日志检索平台、APM 平台、调用链追踪平台
|
||||
* 不扩展为 GeoDNS、全球流量调度、节点智能选路系统
|
||||
* 不做任意自定义报表、任意维度 OLAP 查询或外部 BI 接入
|
||||
|
||||
---
|
||||
|
||||
## 4. 第六版实施顺序
|
||||
|
||||
建议按以下顺序推进：
|
||||
|
||||
1. 定义数据模型与 heartbeat 扩展协议
|
||||
* 明确系统画像结构、请求数据批次结构、资源快照结构、聚合结果结构与健康事件结构
|
||||
* 补齐保留策略、体积限制和失败回退规则
|
||||
|
||||
2. 完成 Agent 采集链路
|
||||
* 采集请求窗口聚合
|
||||
* 采集系统画像与运行时性能指标
|
||||
* 采集 OpenResty 入站/出站流量
|
||||
* 归并节点健康事件并挂入 heartbeat 上报
|
||||
|
||||
3. 完成 Server 入库与分析链路
|
||||
* 接收并校验 heartbeat 扩展数据
|
||||
* 入库存储系统画像、原始批次、资源快照和健康事件
|
||||
* 生成总览页与节点详情页所需聚合统计与系统健康摘要
|
||||
|
||||
4. 完成总览页改造
|
||||
* 世界地图看板
|
||||
* 系统健康摘要区
|
||||
* 核心访问指标区
|
||||
* 访问趋势与来源分布区
|
||||
* 节点状态、配置追平与异常摘要区
|
||||
|
||||
5. 完成节点详情页改造
|
||||
* 系统信息卡片
|
||||
* 实时仪表盘与网络流量卡片
|
||||
* 24 小时趋势图
|
||||
* 下移并重组当前目标版本、健康事件与应用记录
|
||||
|
||||
6. 补齐回归验证
|
||||
* Agent 心跳主链路
|
||||
* 聚合统计正确性
|
||||
* 健康事件触发/恢复正确性
|
||||
* 总览页与节点详情页的亮暗主题和空态/错误态
|
||||
|
||||
---
|
||||
|
||||
## 5. 第六版分阶段计划
|
||||
|
||||
### 5.1 阶段一：采集协议与存储落地
|
||||
|
||||
目标：
|
||||
|
||||
* 打通“节点采集 -> heartbeat 上报 -> Server 接收 -> 入库”主链路
|
||||
|
||||
当前状态：
|
||||
|
||||
* 已完成
|
||||
|
||||
任务：
|
||||
|
||||
* 扩展 Agent heartbeat payload
|
||||
* 新增系统画像、请求数据批次、资源快照和健康事件模型
|
||||
* 为请求明细、性能快照和聚合统计建立查询入口
|
||||
* 控制单次 heartbeat 体积，避免影响现有同步稳定性
|
||||
|
||||
验收标准：
|
||||
|
||||
* 节点可随 heartbeat 成功上报系统画像、请求数据与性能快照
|
||||
* heartbeat 扩展失败不影响配置同步主链路
|
||||
* Server 能按节点和时间窗口查询到原始上报数据与健康事件
|
||||
|
||||
### 5.2 阶段二：服务端分析与指标计算
|
||||
|
||||
目标：
|
||||
|
||||
* 形成总览页和节点详情页可直接消费的数据接口
|
||||
|
||||
当前状态：
|
||||
|
||||
* 已完成
|
||||
* 已落地总览级与节点级聚合接口、当前窗口摘要、状态码/域名/来源分布、系统健康摘要与异常节点清单
|
||||
* 已落地最近 24 小时 CPU、内存、网络、磁盘 IO 趋势聚合，并统一总览页与节点详情页的统计口径
|
||||
|
||||
任务：
|
||||
|
||||
* 计算当前节点 QPS、访问次数、访问人数
|
||||
* 计算访问来源分布、访问趋势、状态码分布
|
||||
* 生成最近 24 小时 CPU、网络、磁盘 IO 趋势数据
|
||||
* 统一总览级与节点级查询口径
|
||||
* 生成整体健康摘要与异常节点清单
|
||||
|
||||
验收标准：
|
||||
|
||||
* 同一时间窗口下总览与节点详情的数据口径一致
|
||||
* 核心统计字段可被测试覆盖，避免明显统计偏差
|
||||
* 24 小时趋势查询在现有基线上可接受，不出现明显不可用卡顿
|
||||
* 首页可直接定位离线、异常、配置落后和容量风险节点
|
||||
|
||||
### 5.3 阶段三：总览页改造
|
||||
|
||||
目标：
|
||||
|
||||
* 让总览页从“摘要入口页”升级为“运营与状态看板页”
|
||||
|
||||
当前状态：
|
||||
|
||||
* 已完成
|
||||
* 已完成全球态势板、节点真实地图落点、系统健康摘要、峰值摘要、24 小时请求/容量/网络/磁盘趋势、来源分布、状态码分布、Top Domain、Top 节点榜单、处置建议、节点健康列表、活动异常与节点页筛选联动
|
||||
* 页面已覆盖首页级加载态、错误态，以及地图/趋势/分布图自身空态，满足第六版当前总览页交付范围
|
||||
|
||||
任务：
|
||||
|
||||
* 实现世界地图节点看板
|
||||
* 重构首屏布局，减少对称摘要卡片堆叠
|
||||
* 增加系统健康摘要、趋势图、来源分布、状态码分布、节点异常摘要
|
||||
* 为地图、趋势和分布图补齐加载态、空态和错误态
|
||||
|
||||
验收标准：
|
||||
|
||||
* 总览首屏可直接看到全部节点分布
|
||||
* 总览页能展示比旧版更多的实时、趋势与健康信息
|
||||
* 页面在桌面和移动端都能稳定显示
|
||||
|
||||
### 5.4 阶段四：节点详情页改造
|
||||
|
||||
目标：
|
||||
|
||||
* 让节点详情页回到运维排障视角，提升信息密度和首屏价值
|
||||
|
||||
当前状态：
|
||||
|
||||
* 已完成
|
||||
* 已完成系统画像、实时资源、网络流量三块核心卡，以及诊断摘要、24 小时 CPU/请求/网络/磁盘 IO 趋势、请求结构分布、Top Domain、健康事件时间线与运维模块下移
|
||||
* 页面已覆盖首屏识别、资源判断、流量判断与后续排障所需的关键模块，满足第六版当前节点详情页交付范围
|
||||
|
||||
任务：
|
||||
|
||||
* 第一行实现系统信息、实时资源占用、网络流量三块核心卡片
|
||||
* 系统信息新增操作系统、内核、架构、CPU 型号、在线时长
|
||||
* 网络流量卡片展示 OpenResty 入站/出站流量，自适应单位
|
||||
* 第二行实现最近 24 小时 CPU、网络、磁盘 IO 趋势图
|
||||
* 第三行承接当前目标版本、OpenResty 健康、健康事件与应用记录等现有高价值模块
|
||||
* 移除低价值重复信息
|
||||
|
||||
验收标准：
|
||||
|
||||
* 节点详情首屏信息密度明显高于旧版
|
||||
* 第一屏即可完成系统识别、资源判断和流量判断
|
||||
* 趋势图可用于观察节点最近 24 小时性能变化
|
||||
|
||||
---
|
||||
|
||||
## 6. 第六版执行原则
|
||||
|
||||
第六版执行时遵循：
|
||||
|
||||
* 先遵守 `docs/design.md` 的系统边界
|
||||
* 再遵守 `docs/development-guidelines.md` 与 `docs/frontend-development-guidelines.md`
|
||||
* 数据采集优先走 heartbeat 批量上报，不新增独立常驻推流通道
|
||||
* 前端优先消费服务端聚合结果，不在浏览器做重型统计
|
||||
* 优先建设新的观测聚合链路，不继续在旧 `nodes` 列表接口与旧首页卡片上补丁式叠加字段
|
||||
* 总览页与节点详情页都必须同时覆盖加载态、空态、错误态和亮暗主题
|
||||
* 若第六版实现过程中需要新增基础设施或改变保留策略，必须先更新设计文档
|
||||
|
||||
---
|
||||
|
||||
## 7. 第六版总体验收标准
|
||||
|
||||
完成第六版时至少满足：
|
||||
|
||||
* Agent 能在 heartbeat 中稳定上报请求数据、系统信息和性能快照
|
||||
* Server 能基于上报数据计算 QPS、访问次数、访问人数、访问来源分布、访问趋势、状态码统计
|
||||
* Server 能稳定生成系统健康摘要、异常节点清单和配置追平状态
|
||||
* 总览页包含世界地图看板，并替换旧版以摘要卡片为主的单调结构
|
||||
* 节点详情页包含系统信息卡、实时资源占用卡、网络流量卡、健康事件区与最近 24 小时趋势图
|
||||
* 节点详情页保留当前目标版本等关键运维信息，但整体层级比旧版更清晰
|
||||
* 第六版不破坏现有 Agent 心跳、同步、发布、回滚主链路
|
||||
如果未来出现明确的新阶段目标，再单独新增专项计划文档；不要把已完成的历史计划继续堆回本文件。
|
||||
|
||||
@@ -1,56 +1,36 @@
|
||||
# OpenFlare 前端开发规范
|
||||
|
||||
## 1. 适用范围
|
||||
本文档约束 `openflare_server/web` 的正式前端工程。它描述的是 `1.0.0` 之后仍然有效的结构、请求层、组件、样式、状态管理与测试基线。
|
||||
|
||||
本文档约束 `openflare_server/web` 新版前端的工程结构、请求层、组件设计、样式体系、状态管理与测试方式。
|
||||
## 1. 技术基线
|
||||
|
||||
当前状态：
|
||||
默认技术栈：
|
||||
|
||||
* 前端改造已完成
|
||||
* 本文档描述的是现行正式基线，不再维护迁移期约束
|
||||
|
||||
---
|
||||
|
||||
## 2. 技术基线
|
||||
|
||||
前端默认技术栈：
|
||||
|
||||
* Next.js 15（App Router）
|
||||
* Next.js 15 App Router
|
||||
* React 19
|
||||
* TypeScript 5
|
||||
* Tailwind CSS 4
|
||||
* TanStack Query
|
||||
* React Hook Form + Zod
|
||||
* Zustand（仅限轻量客户端状态）
|
||||
* Zustand
|
||||
* ESLint + Prettier
|
||||
* Vitest + Testing Library + Playwright
|
||||
* pnpm
|
||||
|
||||
本地开发模式：
|
||||
|
||||
* `pnpm start`：启动独立前端开发服务器，默认监听 `3001`，支持热更新
|
||||
* 开发服务器默认把 `/api/*` 反向代理到 `http://127.0.0.1:3000`
|
||||
* 如需改后端地址，可设置 `NEXT_DEV_BACKEND_URL`
|
||||
* `pnpm build`：继续用于静态导出，产物交给 Go Server 托管
|
||||
|
||||
要求：
|
||||
|
||||
* 默认使用 TypeScript，不新增 JS 页面模块
|
||||
* 默认使用函数组件，不新增 class 组件
|
||||
* 默认使用 App Router，不新建 Pages Router 结构
|
||||
* 默认使用 Tailwind CSS 与现有设计 token 体系
|
||||
* 默认使用 TypeScript
|
||||
* 默认使用函数组件
|
||||
* 默认使用 App Router
|
||||
* 前端必须支持 `light`、`dark`、`system` 三种主题模式
|
||||
|
||||
禁止：
|
||||
|
||||
* 新增 Semantic UI 依赖
|
||||
* 新增大型 UI 框架，破坏当前组件基线
|
||||
* 在新模块中继续使用 jQuery 风格 DOM 操作
|
||||
* 将页面逻辑堆积为单个超大组件
|
||||
* 引入 Semantic UI
|
||||
* 新增大型 UI 框架破坏现有组件基线
|
||||
* 使用 jQuery 风格 DOM 操作
|
||||
|
||||
---
|
||||
|
||||
## 3. 目录与分层
|
||||
## 2. 目录与分层
|
||||
|
||||
推荐目录：
|
||||
|
||||
@@ -68,28 +48,14 @@ tests/
|
||||
|
||||
职责约束：
|
||||
|
||||
* `app/`：定义路由、组织布局、组装页面
|
||||
* `app/`：路由、布局、页面组装
|
||||
* `features/`：按业务域组织模块
|
||||
* `components/`：跨 feature 复用组件
|
||||
* `lib/`：请求客户端、环境变量、工具函数、常量
|
||||
* `store/`：少量跨页面 UI 状态
|
||||
* `types/`：共享类型定义
|
||||
|
||||
禁止：
|
||||
|
||||
* 在 `app/` 页面文件里堆积复杂请求逻辑
|
||||
* 把服务端主数据放进 Zustand
|
||||
* 将同一业务拆出多套平行结构
|
||||
|
||||
---
|
||||
|
||||
## 4. 路由与页面
|
||||
|
||||
路由命名要求：
|
||||
|
||||
* 使用英文小写
|
||||
* 资源页保持现有单数命名
|
||||
* 保持与当前路径结构一致
|
||||
## 3. 路由与页面
|
||||
|
||||
页面文件只负责：
|
||||
|
||||
@@ -103,26 +69,16 @@ tests/
|
||||
* 编写复杂表单校验逻辑
|
||||
* 维护大量彼此耦合的局部状态
|
||||
|
||||
后台页面优先采用统一结构：
|
||||
## 4. 数据请求与类型
|
||||
|
||||
1. 标题区
|
||||
2. 操作区
|
||||
3. 筛选区
|
||||
4. 内容区
|
||||
5. 详情区或弹层
|
||||
|
||||
---
|
||||
|
||||
## 5. 数据请求与类型
|
||||
|
||||
### 5.1 请求层
|
||||
### 4.1 请求层
|
||||
|
||||
所有 API 请求必须统一经过 `lib/api/`。
|
||||
|
||||
要求：
|
||||
|
||||
* 统一处理 `success/message/data` 响应结构
|
||||
* 统一处理鉴权失效、网络异常、通用错误消息
|
||||
* 统一处理鉴权失效、网络异常和通用错误消息
|
||||
* 统一维护资源接口与请求路径
|
||||
|
||||
禁止：
|
||||
@@ -130,101 +86,7 @@ tests/
|
||||
* 在页面组件中直接调用 `fetch('/api/...')`
|
||||
* 在多个组件中重复拼接同一接口路径
|
||||
|
||||
### 5.2 Query
|
||||
|
||||
适用场景：
|
||||
|
||||
* 列表查询
|
||||
* 详情查询
|
||||
* 配置读取
|
||||
* 依赖后端的分页、筛选、刷新操作
|
||||
|
||||
要求：
|
||||
|
||||
* 使用稳定的 query key
|
||||
* 变更成功后按资源粒度失效缓存
|
||||
* 列表刷新不要依赖分散的手工 `setState`
|
||||
|
||||
### 5.3 类型
|
||||
|
||||
要求：
|
||||
|
||||
* 开启 TypeScript 严格模式
|
||||
* 禁止滥用 `any`
|
||||
* API 响应、表单输入、业务实体必须有明确类型
|
||||
* 枚举、状态、日期字段建立明确类型边界
|
||||
|
||||
---
|
||||
|
||||
## 6. 表单与交互
|
||||
|
||||
统一使用：
|
||||
|
||||
* React Hook Form
|
||||
* Zod
|
||||
|
||||
交互要求：
|
||||
|
||||
* 必填项明确标识
|
||||
* 提交中不可重复点击
|
||||
* 保存成功有明确反馈
|
||||
* 服务端错误映射到表单或全局提示
|
||||
|
||||
高风险操作适用场景：
|
||||
|
||||
* 发布配置
|
||||
* 激活版本
|
||||
* 删除节点
|
||||
* 删除证书
|
||||
* 重置 Token
|
||||
* 触发更新
|
||||
|
||||
要求：
|
||||
|
||||
* 必须有二次确认
|
||||
* 必须展示操作对象名称
|
||||
* 必须明确成功与失败反馈
|
||||
|
||||
---
|
||||
|
||||
## 7. 样式与主题
|
||||
|
||||
样式原则：
|
||||
|
||||
* 统一使用 Tailwind CSS 与现有 token 体系
|
||||
* 优先复用已有基础组件与布局组件
|
||||
* 页面视觉风格统一、层级清晰、留白一致
|
||||
|
||||
主题要求：
|
||||
|
||||
* 同时支持 `light`、`dark`、`system`
|
||||
* 用户手动选择后必须持久化
|
||||
* 刷新、重新进入页面、路由切换后保持一致
|
||||
* 首屏尽量避免主题闪烁
|
||||
* 布局层、导航层、基础卡片、表单容器必须先满足双主题
|
||||
|
||||
禁止：
|
||||
|
||||
* 大量硬编码颜色值
|
||||
* 同一状态在不同页面使用不同颜色语义
|
||||
* 仅验证单一主题后直接交付
|
||||
|
||||
---
|
||||
|
||||
## 8. 组件与状态管理
|
||||
|
||||
组件分层：
|
||||
|
||||
* 基础组件：按钮、输入框、表格、对话框、标签、卡片
|
||||
* 业务组件：节点状态卡、版本激活按钮、证书上传表单
|
||||
* 页面组合组件：页面头部、筛选面板、详情弹层
|
||||
|
||||
复用原则：
|
||||
|
||||
* 先抽象稳定结构，再抽象复杂行为
|
||||
* 业务组件优先放在 feature 内，确认跨域复用后再上移
|
||||
|
||||
状态分类：
|
||||
### 4.2 状态分层
|
||||
|
||||
* 服务端状态：TanStack Query
|
||||
* 页面临时状态：组件内部 `useState`
|
||||
@@ -232,13 +94,45 @@ tests/
|
||||
|
||||
不推荐：
|
||||
|
||||
* 用 Zustand 保存服务端列表数据
|
||||
* 用 Zustand 保存服务端主数据
|
||||
* 用 Context 代替完整数据层方案
|
||||
* 页面里堆叠过多耦合本地状态
|
||||
|
||||
---
|
||||
### 4.3 类型
|
||||
|
||||
## 9. 反馈、测试与交付
|
||||
要求：
|
||||
|
||||
* 开启 TypeScript 严格模式
|
||||
* 禁止滥用 `any`
|
||||
* API 响应、表单输入、业务实体必须有明确类型
|
||||
|
||||
## 5. 表单与交互
|
||||
|
||||
统一使用：
|
||||
|
||||
* React Hook Form
|
||||
* Zod
|
||||
|
||||
高风险操作必须：
|
||||
|
||||
* 二次确认
|
||||
* 展示操作对象名称
|
||||
* 明确成功与失败反馈
|
||||
|
||||
## 6. 样式与主题
|
||||
|
||||
样式原则：
|
||||
|
||||
* 统一使用 Tailwind CSS 与现有 token 体系
|
||||
* 优先复用已有基础组件与布局组件
|
||||
* 保持视觉层级、留白与语义颜色一致
|
||||
|
||||
主题要求：
|
||||
|
||||
* 同时支持 `light`、`dark`、`system`
|
||||
* 用户选择必须持久化
|
||||
* 首屏尽量避免主题闪烁
|
||||
|
||||
## 7. 测试与交付
|
||||
|
||||
每个页面至少具备：
|
||||
|
||||
@@ -256,5 +150,5 @@ tests/
|
||||
交付要求：
|
||||
|
||||
* 构建产物保持可静态导出
|
||||
* 构建结果保持可被 Go Server 托管
|
||||
* 新页面与新组件默认同时通过亮色与暗色模式验收
|
||||
* 构建结果可被 Go Server 托管
|
||||
* 新页面默认通过亮色与暗色模式验收
|
||||
|
||||
@@ -1,68 +0,0 @@
|
||||
# OpenFlare 前端改造说明
|
||||
|
||||
## 1. 当前状态
|
||||
|
||||
前端改造已完成，`openflare_server/web` 的 Next.js 新版工程已经成为正式管理端基线。
|
||||
|
||||
当前结论：
|
||||
|
||||
* 旧版 CRA + Semantic UI 方案已退出基线
|
||||
* 新版前端继续由 Go Server 以静态资源方式托管
|
||||
* 前端改造过程中的阶段计划、迁移顺序与风险清单不再继续维护
|
||||
|
||||
---
|
||||
|
||||
## 2. 当前前端基线
|
||||
|
||||
新版管理端位于 `openflare_server/web`，当前基线为：
|
||||
|
||||
* Next.js 15 App Router
|
||||
* React 19
|
||||
* TypeScript
|
||||
* Tailwind CSS 4
|
||||
* TanStack Query
|
||||
* React Hook Form + Zod
|
||||
* Zustand（仅限轻量客户端状态）
|
||||
* Vitest + Playwright
|
||||
|
||||
工程与运行方式：
|
||||
|
||||
* `next build` 后生成静态导出产物
|
||||
* 构建后通过现有流程交由 `openflare_server` 托管
|
||||
* 登录态继续兼容现有 Session/Cookie 体系
|
||||
|
||||
---
|
||||
|
||||
## 3. 当前结构约束
|
||||
|
||||
新版前端保持以下结构：
|
||||
|
||||
* `app/`：路由与布局
|
||||
* `features/`：业务模块
|
||||
* `components/`：复用组件
|
||||
* `lib/`：请求、环境、工具、常量
|
||||
* `store/`：少量跨页面 UI 状态
|
||||
* `tests/`：前端测试
|
||||
|
||||
当前已覆盖的主要页面包括：
|
||||
|
||||
* 首页
|
||||
* 反代规则
|
||||
* 配置版本
|
||||
* 节点管理
|
||||
* 应用记录
|
||||
* 网站
|
||||
* 用户管理
|
||||
* 设置
|
||||
* 性能
|
||||
* 登录、注册、重置密码、GitHub OAuth、关于页
|
||||
|
||||
---
|
||||
|
||||
## 4. 后续维护原则
|
||||
|
||||
后续不再按“前端改造专项”推进，而按正式前端工程进行维护：
|
||||
|
||||
* 新前端开发统一遵循 [docs/frontend-development-guidelines.md](./frontend-development-guidelines.md)
|
||||
* 涉及项目级约束时，同时遵循 [docs/development-guidelines.md](./development-guidelines.md)
|
||||
* 若后续再次调整前端架构、部署模式或技术基线，再新增专项计划文档
|
||||
@@ -1,217 +0,0 @@
|
||||
# OpenFlare 整理维护期改进计划
|
||||
|
||||
## 1. 背景
|
||||
|
||||
项目当前已具备可用的 Server / Agent / OpenResty 控制链路，接下来进入整理维护期。
|
||||
这一阶段不再以新增大功能为主，而是集中处理三类问题：
|
||||
|
||||
* 架构层面的通信与存储开销
|
||||
* 代码质量、可维护性与复用度
|
||||
* 高风险安全问题与供应链风险
|
||||
|
||||
本计划遵循当前基线：
|
||||
|
||||
* 不改变 Server 统一生成配置、Agent 受控落盘的核心边界
|
||||
* 优先通过收敛实现、减少重复、补齐校验和测试来提升系统质量
|
||||
|
||||
---
|
||||
|
||||
## 2. 目标
|
||||
|
||||
### 2.1 总目标
|
||||
|
||||
在不扩大产品边界的前提下，把 OpenFlare 从“功能可用”推进到“长期可维护、风险可控、成本可预测”。
|
||||
|
||||
### 2.2 具体目标
|
||||
|
||||
* 降低 Agent 与 Server 的无效通信和无谓数据库写入
|
||||
* 降低节点列表、配置发布、日志输出等热点路径的额外开销
|
||||
* 用更明确的校验、错误处理和回归测试提升健壮性
|
||||
* 优先清除高危安全风险，特别是认证绕过、路径穿越、远程执行链路和更新链路信任问题
|
||||
|
||||
---
|
||||
|
||||
## 3. 现状评估
|
||||
|
||||
### 3.1 架构与性能现状
|
||||
|
||||
当前通信链路已经有一个正确方向：
|
||||
|
||||
* 心跳接口只返回 `version/checksum` 摘要
|
||||
* Agent 仅在版本或 checksum 不一致时才拉取完整配置
|
||||
|
||||
这意味着“全量配置频繁下发”已经被避免，基础设计没有明显错误。但仍有几个维护期值得优化的点：
|
||||
|
||||
* 心跳会持续触发数据库写入，即使多数运行字段没有变化
|
||||
* 节点列表查询存在按节点逐条读取最近应用日志的模式，节点数增大后会出现明显的 N+1 查询开销
|
||||
* Agent 与 Server 在心跳、同步、HTTP 请求等路径上存在较多 `info` 级别日志，线上节点数增多后会放大 I/O 与排障噪音
|
||||
* Active Config 仍是整包返回，后续可继续收敛为“元数据 + 必要文件”的更细粒度同步模式
|
||||
|
||||
### 3.2 代码质量现状
|
||||
|
||||
当前代码总体结构清晰，但已经出现维护期典型问题：
|
||||
|
||||
* 控制器层大量重复 `success/message/data` 响应拼装，错误返回风格不够统一
|
||||
* 部分边界校验仍分散在控制器、服务和运行时路径里，难以形成稳定约束
|
||||
* 一些实现已经接近“自造轮子”，例如日志文件处理、更新校验、静态安全检查流程，还没有引入成熟工具链
|
||||
|
||||
### 3.3 安全现状
|
||||
|
||||
维护期内优先处理以下高风险或高敏感问题：
|
||||
|
||||
* Agent 写入 `support_files` 时缺少对目标路径必须位于 `support_dir` 内的强约束，存在路径穿越风险
|
||||
* 手动上传 Server 二进制后会执行 `--version` 检测，属于高敏感执行链路，必须进一步加固
|
||||
|
||||
---
|
||||
|
||||
## 4. 优先级策略
|
||||
|
||||
### 4.1 P0：先止血
|
||||
|
||||
这部分先处理，未完成前不建议继续做中期重构。
|
||||
|
||||
1. 修复 Agent 证书/附属文件写入路径穿越风险
|
||||
2. 补齐相关回归测试，确保问题不会回归
|
||||
|
||||
### 4.2 P1：高收益优化
|
||||
|
||||
在 P0 完成后推进。
|
||||
|
||||
1. 减少心跳导致的数据库写放大
|
||||
2. 消除节点列表的 N+1 查询
|
||||
3. 降低高频路径日志噪音
|
||||
4. 收敛重复日志与响应封装实现
|
||||
|
||||
### 4.3 P2：维护性增强
|
||||
|
||||
在 P1 稳定后持续推进。
|
||||
|
||||
1. 引入静态分析、安全扫描、依赖漏洞扫描到日常流程
|
||||
2. 梳理通用校验与错误模型
|
||||
3. 评估可以替换自研实现的成熟库
|
||||
4. 补充基准测试、容量指标和回归清单
|
||||
|
||||
---
|
||||
|
||||
## 5. 分项计划
|
||||
|
||||
### 5.1 工作流一：安全治理
|
||||
|
||||
#### 5.1.1 目标
|
||||
|
||||
先解决高危风险，再补齐防线。
|
||||
|
||||
#### 5.1.2 任务
|
||||
|
||||
* 为 Agent 支持文件写入增加安全路径校验
|
||||
* 拒绝绝对路径
|
||||
* 拒绝 `..` 跳目录
|
||||
* 通过 `filepath.Rel` 或安全辅助函数确认最终路径仍位于 `support_dir` 内
|
||||
* `writeSupportFiles`、`restore`、未来新增的写文件入口全部复用同一套安全函数
|
||||
* 收紧手动上传升级链路
|
||||
* 明确只允许 root 用户
|
||||
* 增加二次确认信息和文件摘要展示
|
||||
|
||||
|
||||
#### 5.1.3 验收标准
|
||||
|
||||
* 构造 `../`、绝对路径、混合分隔符路径时，Agent 必须拒绝写入
|
||||
|
||||
### 5.2 工作流二：架构与性能优化
|
||||
|
||||
#### 5.2.1 目标
|
||||
|
||||
在不改变总体架构的前提下，减少高频开销。
|
||||
|
||||
#### 5.2.2 任务
|
||||
|
||||
* 优化心跳写库策略
|
||||
* 将“状态变化字段”与“仅 last_seen_at 更新时间”区分处理
|
||||
* 仅在 IP、版本、OpenResty 状态、错误信息变化时更新对应字段
|
||||
* 节点状态的离线判定优先在查询层或内存逻辑中计算，避免频繁写回数据库
|
||||
* 优化节点列表查询
|
||||
* 将“最近一次 apply_log”改为批量查询或子查询一次取回
|
||||
* 避免 `ListNodeViews` 中对每个节点单独查询最近日志
|
||||
* 优化配置同步链路
|
||||
* 保留当前“心跳摘要 + 版本不一致再拉全量配置”的模型
|
||||
* 为后续版本预留“支持文件 manifest/checksum”能力，避免未来证书文件较多时重复传输整包内容
|
||||
* 评估为 Agent 全量配置接口启用 gzip 压缩
|
||||
* 优化日志成本
|
||||
* 将心跳成功、HTTP 请求成功、无变更同步等高频日志降为 `debug`
|
||||
* 保留发布、应用失败、回滚、认证失败等关键事件为 `info/warn/error`
|
||||
|
||||
#### 5.2.3 验收标准
|
||||
|
||||
* 在节点数量增长时，节点列表查询不再出现明显线性附加 SQL 次数
|
||||
* 心跳高频场景下数据库写入量明显下降
|
||||
* 默认 `info` 日志聚焦关键事件，不再持续刷出无变更同步日志
|
||||
|
||||
### 5.3 工作流三：代码质量与可维护性
|
||||
|
||||
#### 5.3.1 目标
|
||||
|
||||
减少重复代码，让后续维护成本下降。
|
||||
|
||||
#### 5.3.2 任务
|
||||
|
||||
* 统一 API 响应与错误处理
|
||||
* 提供统一响应助手函数
|
||||
* 让控制器层只负责参数解析、调用 service、返回统一结构
|
||||
* 收敛校验逻辑
|
||||
* 将路径、模板占位符、OpenResty 参数、上传文件等校验集中封装
|
||||
* 避免同一规则散落在多个层级
|
||||
* 清理“功能可跑但长期难维护”的实现
|
||||
* 减少控制器内重复 JSON decode 与错误返回样板代码
|
||||
* 减少 service 中过长函数
|
||||
* 对高频路径补充更精确的单元测试和表驱动测试
|
||||
|
||||
#### 5.3.3 可优先引入的成熟开源能力
|
||||
|
||||
* `staticcheck`
|
||||
* 作为 Go 静态分析主工具
|
||||
* `govulncheck`
|
||||
* 用于 Go 依赖漏洞扫描
|
||||
* `gosec`
|
||||
* 用于高危安全模式扫描
|
||||
* `gitleaks` 或 `trufflehog`
|
||||
* 用于仓库敏感信息扫描
|
||||
|
||||
说明：
|
||||
|
||||
* 这里优先引入“工程工具”和“稳定基础库”
|
||||
* 不建议为了维护期而大规模替换 Web 框架、ORM、HTTP 框架等核心依赖
|
||||
|
||||
#### 5.3.4 验收标准
|
||||
|
||||
* 控制器响应风格统一，重复样板代码减少
|
||||
* 新增规则优先通过统一校验函数落地，而不是散落在多个入口
|
||||
|
||||
---
|
||||
|
||||
## 6. 建议实施顺序
|
||||
|
||||
### 第一阶段：安全止血
|
||||
|
||||
* 修复路径穿越风险
|
||||
* 清理敏感示例配置
|
||||
* 为更新链路加校验
|
||||
* 接入 `gosec`、`govulncheck`、密钥扫描
|
||||
|
||||
### 第二阶段：热点路径优化
|
||||
|
||||
* 优化心跳写库
|
||||
* 优化节点列表查询
|
||||
* 调整日志级别
|
||||
* 补充压力下的基线数据
|
||||
|
||||
### 第三阶段：代码收敛
|
||||
|
||||
* 统一 API 响应帮助函数
|
||||
* 收敛校验与错误模型
|
||||
* 补充回归测试模板
|
||||
|
||||
### 第四阶段：延伸优化
|
||||
|
||||
* 评估配置接口压缩与更细粒度 manifest 同步
|
||||
* 评估手动上传升级链路的更安全替代实现
|
||||
* 根据实际运行数据决定是否继续做更细的持久化优化
|
||||
@@ -1 +1 @@
|
||||
data
|
||||
/data/
|
||||
|
||||
Reference in New Issue
Block a user