tcjlj/OpenFlare

Fork 0

mirror of https://github.com/Rain-kl/OpenFlare.git synced 2026-09-28 05:46:36 +08:00

Files

T

ryan b2eb4befba [文档] 文档更新

2026-03-15 17:11:17 +08:00

4.8 KiB

Raw Blame History

OpenFlare 开发规范

本文档描述 OpenFlare 1.0.0 正式版之后的开发基线。

超出 docs/design.md 边界的需求，必须先更新设计文档。

1. 技术基线

1.1 Server

openflare_server 继续作为单体控制面：

Go 1.24+
Gin
GORM
SQLite
现有登录体系

1.2 Agent

openflare_agent 继续作为 Go 单体程序：

Go 1.23+
单二进制
节点本地执行
openresty_path 优先
无 openresty_path 时默认 Docker OpenResty

1.3 Frontend

前端基线以 openflare_server/web 为准：

Next.js 15 App Router
React 19
TypeScript
Tailwind CSS 4
TanStack Query
React Hook Form + Zod
Zustand 仅用于轻量客户端状态

前端细则见 docs/frontend-development-guidelines.md。

2. 分层与目录约束

2.1 Server

controller/：参数解析、调用 service、返回响应
service/：业务逻辑、校验、事务编排、渲染
model/：模型定义与持久化
router/：路由注册
middleware/：认证、鉴权、限流等横切逻辑
common/：配置、全局状态与初始化入口
utils/：纯工具函数与通用 helper

禁止：

在 controller/ 堆积业务逻辑
在 middleware/ 实现业务流程
为简单需求新增平台层抽象

2.2 Agent

保持现有模块边界：

config
heartbeat
sync
openresty
state
httpclient
protocol
internal/updater

要求：

每个模块职责单一
外部命令调用集中封装
状态落盘与配置落盘分离

2.3 Frontend

前端分层保持：

app/
features/
components/
lib/
store/
types/

要求：

页面路由与布局放在 app/
API 请求统一收敛到 lib/api/
业务逻辑优先放在 features/

3. 数据模型规范

当前有效实体：

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
options

通用约束：

不新增平台化对象，除非设计文档明确要求
proxy_routes 维持一条域名对应一个 origin_url
config_versions 必须保存完整快照与渲染结果
全局同时只能有一个激活版本
回滚通过重新激活旧版本实现
nodes 只保留控制面状态与低频摘要
观测数据必须按节点与时间窗口关联
快照与聚合结果采用追加式模型，不覆盖历史
原始访问明细必须有受控保留策略

4. API 与鉴权规范

4.1 API

管理端与 Agent API 统一使用 JSON
成功与失败都必须返回清晰 message
Agent API 固定放在 /api/agent/*
总览与节点详情优先使用专用聚合接口

统一响应结构：

{
  "success": true,
  "message": "",
  "data": {}
}

4.2 鉴权

管理端：

继续复用现有登录、角色与 Session

Agent：

正式请求统一使用节点专属 agent_token
首次接入可使用全局 discovery_token
请求头统一使用 X-Agent-Token

禁止：

暴露远程 shell 或任意命令执行入口
在日志中打印完整 Token
允许绕过占位符约束保存不可渲染的主配置模板

5. 发布与运行规范

发布逻辑必须保持以下事实：

发布时读取全部启用的 proxy_routes
同时读取 OpenResty 主配置参数、反代性能参数与缓存参数
生成完整 OpenResty 配置
计算 checksum
写入 config_versions
通过切换 is_active 激活版本

版本约束：

版本号格式固定为 YYYYMMDD-NNN
不在线修改历史版本
不做按节点分组的差异化版本
预览与 diff 是只读能力，不产生发布记录

Agent 必须满足：

启动后读取或生成本地 node_id
周期性心跳与同步
常规同步优先依据 heartbeat 返回的版本摘要判断
发现新版本时先备份旧文件
写入主配置、路由配置与必要证书文件
先执行 openresty -t
成功后执行 openresty -s reload
失败时自动回滚并上报最终结果

6. 测试与交付要求

关键业务逻辑必须有单元测试或等效回归测试
Agent 主链路修改必须验证同步、应用与回滚
前端页面至少覆盖加载态、空态、错误态与成功反馈
Go 版本调整时，同步检查 go.mod、Dockerfile 与 CI 工作流

7. 文档维护要求

当以下内容变化时，必须同步更新对应文档：

产品范围或系统边界变化：更新 docs/design.md
开发约束、接口约定、测试基线变化：更新本文档
前端工程约束变化：更新 docs/frontend-development-guidelines.md
配置项或部署方式变化：更新 docs/app-config.md、docs/deployment.md 与 README.md

4.8 KiB Raw Blame History Unescape Escape