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 ca1c147dfe [文档] 文档更新

2026-03-11 22:31:12 +08:00

5.3 KiB

Raw Blame History

ATSFlare 设计基线

1. 文档目的

本文档只保留 ATSFlare 当前有效的产品边界、系统结构与稳定约束。

当前状态：

第一版、第二版、第三版均已完成
前端改造已完成，atsf_server/web 新版工程已成为正式基线
已完成阶段的实现细节以代码与 Git 历史为准，不再在本文档中维护过程性设计

2. 产品定位

ATSFlare 当前定位为内部自用的反向代理控制面，不面向外部租户提供 CDN SaaS 能力。

当前核心能力：

反代规则管理
配置预览、发布、激活与回滚
Agent 注册、心跳、同步、应用结果上报
Nginx 配置写入、校验、reload 与失败回滚
HTTPS/TLS 路由支持
证书托管与域名管理
节点管理、节点专属 agent_token、全局 discovery_token
配置变更摘要
Agent 运行参数下发
Agent 自我更新与一键部署
Server 版本检查与自升级
新版管理端 UI、主题切换与统一交互框架

默认工作方式：

所有节点消费同一份全局激活版本
控制面保存配置与状态，不直接 SSH 管理机器
Agent 是节点侧唯一落地入口

3. 范围边界

当前明确不做：

多租户
WAF、限流防护平台化、Bot 管理
节点分组、灰度百分比发布、按节点差异化下发
Redis、消息队列、对象存储、Prometheus 等新基础设施前置依赖
复杂缓存策略、分层缓存、mid-tier
证书自动签发与自动续期
审批流、审计中台、Purge 平台化能力
平台化抽象对象，如 zone、origin_pool、policy、deployment

新增能力超出上述边界时，必须先更新本文档，再进入实现。

4. 技术基线

4.1 Server

atsf_server 继续作为单体控制面：

Gin
GORM
SQLite
现有 ATSFlare 登录体系
托管 atsf_server/web 静态构建产物

4.2 Agent

atsf_agent 继续作为 Go 单体程序：

单二进制
节点本地执行
nginx_path 优先
未配置 nginx_path 时默认使用 Docker Nginx
生成资源默认落在 ./data，可由 data_dir 覆盖

4.3 Frontend

atsf_server/web 作为正式管理端前端基线：

Next.js App Router
React 19
TypeScript
Tailwind CSS
静态导出，继续由 Go Server 托管

5. 总体架构

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

职责分工：

Server 负责配置、版本、节点、设置与管理端 UI
Agent 负责本地落盘、校验、reload、回滚、自更新
发布通过“生成完整版本并激活”完成
历史版本不可变

6. 核心对象

当前有效实体：

proxy_routes：域名到源站的反向代理规则
config_versions：完整发布快照与渲染结果
nodes：节点状态、版本、凭证与 Agent 设置相关状态
apply_logs：节点应用版本结果
tls_certificates：托管证书与私钥
managed_domains：域名资产及默认证书关系

稳定约束：

一个域名只对应一个 origin_url
proxy_routes.domain 必须唯一
origin_url 必须为合法 http:// 或 https://
config_versions 必须保存完整快照、渲染结果与 checksum
全局同时只能有一个激活版本
回滚通过重新激活旧版本实现
域名与证书匹配同时支持精确匹配与通配符匹配
节点专属 agent_token 必须可立即失效

7. 发布模型

标准链路：

修改规则 -> 预览/查看 diff -> 发布 -> 生成完整配置版本 -> 激活版本 -> Agent 拉取 -> 本地应用 -> 上报结果

发布规则：

读取全部启用的 proxy_routes
渲染完整 Nginx 配置
计算 checksum
写入 config_versions
切换激活版本
Agent 在后续同步中发现并应用

版本规则：

版本号格式：YYYYMMDD-NNN
版本不可变
节点只拉取当前激活版本

8. 模块边界

8.1 `atsf_server`

负责：

管理端 UI 与 API
Agent API
数据存储
配置渲染
发布与激活
节点状态与设置管理

8.2 `atsf_agent`

负责：

首次注册与凭证置换
周期性心跳与同步
运行参数接收
本地路由与证书文件写入
nginx -t / nginx -s reload
失败回滚
自我更新
应用结果上报

8.3 `atsf_server/web`

负责：

管理端页面、布局、交互与主题
规则、版本、节点、证书、域名、用户、设置等页面
统一请求层与前端状态管理

9. 接口域

管理端接口当前覆盖：

proxy-routes
config-versions
nodes
apply-logs
tls-certificates
managed-domains
users
settings
update

Agent 接口当前覆盖：

注册
心跳
获取激活版本
上报应用结果

统一约束：

管理端与 Agent API 均使用 JSON
Agent API 固定放在 /api/agent/*
Agent 鉴权统一使用 X-Agent-Token

10. 文档维护原则

后续只维护当前有效基线：

产品范围或系统边界变化时更新本文档
已完成阶段的步骤不再回填为长期计划
新阶段开始前，先补设计，再进入实现

5.3 KiB Raw Blame History