tcjlj/OpenFlare

Fork 0

mirror of https://github.com/Rain-kl/OpenFlare.git synced 2026-09-29 22:06:38 +08:00

Files

T

ryan 34f317fe6f init

2026-03-09 22:43:14 +08:00

12 KiB

Raw Blame History

ATSFlare MVP 设计文档

1. 目标

先做一个能用的版本，不做平台化过度设计。第一版只解决 3 件事：

配置发布与同步
节点心跳检测
Nginx 反向代理配置下发

系统定位是内部自用的控制面，不是面向外部租户的 CDN SaaS。

2. 第一版范围

要做

Web 管理端维护反代规则
配置发布生成版本
Agent 定时同步并应用配置
Agent 控制本机 Nginx 校验与 reload
节点注册、心跳、在线状态展示
展示每个节点当前生效版本和最近一次应用结果

不做

多租户
WAF、限流、Bot、防刷
灰度发布、节点分组、分批发布
对象存储、消息队列、Redis、Prometheus
复杂缓存策略管理
证书托管与自动签发
Purge、中台审计、审批流
mid-tier / 分层缓存

第一版默认所有节点消费同一份全量配置，不做差异化下发。

3. 技术约束

Server

控制中心直接基于现有 atsf_server 的 gin-template 工程开发：

Web 框架：Gin
ORM：GORM
前端：沿用现有 web 管理端
鉴权：沿用 gin-template 登录体系

数据库

只使用 SQLite，不引入其他中间件：

不配置 SQL_DSN，直接走项目现有 SQLite 初始化逻辑
不配置 REDIS_CONN_STRING，会退化为 cookie session

Agent

Agent 使用 Go 单体程序：

单二进制
systemd 管理
本地调用 nginx
管理本机 Nginx 路由配置文件和 reload

Nginx 管理边界

第一版只管理最核心的反代映射：

重点生成独立的 Nginx 路由配置文件，例如 /etc/nginx/conf.d/atsflare_routes.conf
nginx.conf、TLS 证书、缓存细节、upstream 高级配置先保持节点本地静态配置

也就是说，MVP 先把 Nginx 当成“可集中配置的反向代理”，不是完整网关平台。

4. 总体架构

                ┌────────────────────────────┐
                │       ATSFlare Server      │
                │  gin-template + SQLite     │
                │  Admin UI + Admin API      │
                └──────────────┬─────────────┘
                               │
                     HTTP API / Config Pull
                               │
            ┌──────────────────┴──────────────────┐
            │                                     │
   ┌────────▼────────┐                   ┌────────▼────────┐
   │ Nginx Agent 1   │                   │ Nginx Agent N   │
   │ heartbeat/sync  │                   │ heartbeat/sync  │
   │ nginx reload    │                   │ nginx reload    │
   └────────┬────────┘                   └────────┬────────┘
            │                                     │
      ┌─────▼─────┐                         ┌─────▼─────┐
      │   Nginx   │                         │   Nginx   │
      │ reverse   │                         │ reverse   │
      │  proxy    │                         │  proxy    │
      └─────┬─────┘                         └─────┬─────┘
            │                                     │
            └──────────────► Origin ◄────────────┘

设计原则只有 3 条：

Server 只保存配置和节点状态，不直接 SSH 改机器
Agent 是唯一的落地入口
所有发布都是“新版本生效”，不是在线修改当前文件

5. 核心对象

第一版只保留最少的数据模型。

5.1 proxy_routes

反代规则表，控制 Host -> Origin 映射。

建议字段：

id
domain
origin_url
enabled
remark
created_at
updated_at

约束：

domain 唯一
origin_url 必须是合法的 http:// 或 https://
第一版一条域名只对应一个源站，不做源站池

5.2 config_versions

发布版本表，保存不可变快照。

建议字段：

id
version
snapshot_json
rendered_config
checksum
is_active
created_by
created_at

说明：

snapshot_json 保存发布时的完整规则快照
rendered_config 保存渲染后的 Nginx 路由配置
第一版直接存 SQLite，不单独上对象存储

5.3 nodes

节点表，保存当前状态。

建议字段：

id
node_id
name
ip
agent_version
nginx_version
status
current_version
last_seen_at
last_error
created_at
updated_at

5.4 apply_logs

节点应用记录。

建议字段：

id
node_id
version
result
message
created_at

6. 配置发布模型

第一版不做增量发布，也不做 bundle 文件仓库。

发布逻辑：

管理员在后台修改 proxy_routes
点击“发布”
Server 校验规则
Server 根据当前全部启用规则渲染出完整 Nginx 路由配置
生成新 config_versions 记录
将该版本标记为当前激活版本
Agent 下一次心跳或轮询时发现新版本并拉取

版本原则

一个版本就是一份完整快照
版本不可变
节点只拉取当前激活版本
回滚本质上是重新激活旧版本

版本号建议

20260309-001
20260309-002

发布校验

发布前至少做以下检查：

domain 不能为空
origin_url 合法
不允许重复域名
至少存在 1 条启用规则

7. Nginx 配置策略

第一版只生成独立的 Nginx 路由配置文件，这样最简单，也最容易验证。

规则映射

server {
    listen 80;
    server_name www.example.com;

    location / {
        proxy_pass http://10.0.0.10:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

server {
    listen 80;
    server_name api.example.com;

    location / {
        proxy_pass http://10.0.0.20:9000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

HTTPS 处理

第一版不在控制中心管理证书。

约定如下：

Nginx 的监听端口、证书、TLS 相关配置由节点本地预先准备
控制中心只负责反代映射
如果节点已经具备 HTTPS 接入能力，后续可以扩展生成 HTTPS server 块

缓存处理

第一版不开放缓存策略配置：

是否开启缓存由节点静态配置决定
控制中心不管理 TTL、Header 改写、缓存规则

8. Server 模块设计

控制中心仍然是单体应用，不拆服务。

8.1 管理端模块

登录鉴权
反代规则 CRUD
发布版本管理
节点状态页面
应用日志查看

8.2 Agent API 模块

节点注册
心跳上报
获取当前激活版本
下载指定版本配置
上报应用结果

8.3 渲染模块

职责很简单：

从 proxy_routes 读取全部启用规则
按固定模板拼出 Nginx 路由配置
计算 checksum
写入 config_versions

这层不要引入复杂 DSL，第一版直接围绕 domain -> origin_url 即可。

9. Agent 模块设计

Agent 做成一个 Go 单体进程即可。

9.1 本地职责

读取本地配置
定时心跳
拉取新版本
覆盖 Nginx 路由配置文件
执行 nginx -t 和 nginx -s reload
上报应用结果
保存本地最近成功版本

9.2 建议的本地文件

/etc/atsf-agent/config.yaml
/var/lib/atsf-agent/state.json
/etc/nginx/conf.d/atsflare_routes.conf
/etc/nginx/conf.d/atsflare_routes.conf.bak

9.3 最小工作流

1. Agent 启动
2. 读取或生成 node_id
3. 上报 heartbeat
4. 获取当前激活版本元数据
5. 若版本变更，则下载 rendered_config
6. 备份旧路由配置文件
7. 写入新路由配置文件
8. 调用 `nginx -t`
9. 校验通过后执行 `nginx -s reload`
10. 记录结果并上报
11. 进入下一轮

9.4 失败处理

第一版只做最基本的容错：

拉取失败：继续使用本地旧配置
配置校验或 reload 失败：恢复备份文件并再次校验后 reload
Server 不可用：不影响 Nginx 继续转发

10. 心跳与在线状态

心跳不单独搞复杂监控系统，直接走业务表。

心跳内容

Agent 每次上报：

node_id
name
ip
agent_version
nginx_version
current_version
last_apply_result
timestamp

状态判定

建议规则：

15 秒一次心跳
超过 45 秒未上报记为 offline
最近一次应用失败但仍有心跳，记为 warning
正常心跳且版本一致，记为 online

11. API 设计

11.1 管理端 API

GET /api/routes
POST /api/routes
PUT /api/routes/:id
DELETE /api/routes/:id
GET /api/versions
POST /api/versions/publish
POST /api/versions/:id/activate
GET /api/nodes
GET /api/apply-logs

11.2 Agent API

POST /api/agent/register
POST /api/agent/heartbeat
GET /api/agent/version/active
GET /api/agent/versions/:version
POST /api/agent/apply-result

11.3 鉴权方案

管理端：

直接沿用 gin-template 的登录态

Agent：

第一版使用预共享 Token
例如请求头 X-Agent-Token
后续再升级 mTLS

12. 页面设计

第一版只保留最少页面。

12.1 登录页

沿用 gin-template 现有登录。

12.2 反代规则页

展示和编辑：

域名
源站地址
是否启用
备注

12.3 发布版本页

展示：

版本号
发布时间
发布人
是否当前激活

动作：

立即发布
激活旧版本

12.4 节点页

展示：

节点名
IP
在线状态
当前版本
最后心跳时间
最近错误

12.5 应用记录页

展示：

节点
版本
成功/失败
错误信息
时间

13. 代码组织建议

Server

建议直接在现有 atsf_server 下新增以下内容：

atsf_server/
  controller/
    route.go
    version.go
    node.go
    agent.go
  model/
    proxy_route.go
    config_version.go
    node.go
    apply_log.go
  router/
    api-router.go
  service/
    publisher.go
    renderer.go

Agent

建议新建独立目录：

atsf_agent/
  cmd/agent/main.go
  internal/config/config.go
  internal/heartbeat/heartbeat.go
  internal/sync/sync.go
  internal/nginx/nginx.go
  internal/state/state.go

14. 开发顺序

按下面的顺序最稳。

第一阶段

先把 Server 跑通：

建表
反代规则 CRUD
发布版本表
版本渲染逻辑

第二阶段

做 Agent 最小闭环：

注册
心跳
拉取激活版本
写入 Nginx 路由配置
nginx -t && nginx -s reload
应用结果上报

第三阶段

补管理端页面：

规则页
版本页
节点页
应用日志页

15. 关键取舍

第一版故意做这些取舍：

不抽象 zone、origin pool、policy 这些平台概念
不做复杂发布编排，所有节点统一拉当前版本
不管理 Nginx 全部配置，只先管独立生成的路由配置文件
不引入 Redis、MQ、对象存储，先把单机 SQLite 跑起来
不为了“以后可能会用到”提前把系统拆复杂

只要这版能稳定完成下面这条链路，就算成功：

后台改规则 -> 点击发布 -> Agent 拉到新版本 -> Nginx reload -> 节点状态可见

这就是当前阶段最需要的 MVP。

12 KiB Raw Blame History Unescape Escape

ATSFlare MVP 设计文档

1. 目标

2. 第一版范围

要做

不做

3. 技术约束

Server

数据库

Agent

Nginx 管理边界

4. 总体架构

5. 核心对象

5.1 proxy_routes

5.2 config_versions

5.3 nodes

5.4 apply_logs

6. 配置发布模型

版本原则

版本号建议

发布校验

7. Nginx 配置策略

规则映射

HTTPS 处理

缓存处理

8. Server 模块设计

8.1 管理端模块

8.2 Agent API 模块

8.3 渲染模块

9. Agent 模块设计

9.1 本地职责

9.2 建议的本地文件

9.3 最小工作流

9.4 失败处理

10. 心跳与在线状态

心跳内容

状态判定

11. API 设计

11.1 管理端 API

11.2 Agent API

11.3 鉴权方案

12. 页面设计

12.1 登录页

12.2 反代规则页

12.3 发布版本页

12.4 节点页

12.5 应用记录页

13. 代码组织建议

Server

Agent

14. 开发顺序

第一阶段

第二阶段

第三阶段

15. 关键取舍

12 KiB

Raw Blame History