vite-press init

docs/design/architecture.md

@@ -0,0 +1,54 @@
+# 系统架构
+
+OpenFlare 由 Server、Agent 与节点本地 OpenResty 组成。
+
+```text
+OpenFlare Server (Gin + SQLite/PostgreSQL + Web UI)
+        |
+        | HTTP API / Config Pull
+        v
+OpenFlare Agent (register / heartbeat / sync / apply / update)
+        |
+        v
+Local OpenResty or Docker OpenResty
+        |
+        v
+Origin
+```
+
+## Server
+
+`openflare_server` 是单体控制面：
+
+* Gin
+* GORM
+* SQLite / PostgreSQL
+* 现有登录与 Session 体系
+* 托管 `openflare_server/web` 静态构建产物
+
+Server 负责管理端 UI 与 API、Agent API、配置渲染、版本发布、数据存储与聚合查询。
+
+## Agent
+
+`openflare_agent` 是 Go 单体程序：
+
+* 单二进制
+* 节点本地执行
+* 优先使用 `openresty_path`
+* 未配置 `openresty_path` 时默认使用 Docker OpenResty
+
+Agent 负责首次注册、周期性心跳、配置同步、文件写入、`openresty -t`、reload、失败回滚、自更新与轻量采集。
+
+## Frontend
+
+`openflare_server/web` 是正式管理端前端：
+
+* Next.js App Router
+* React 19
+* TypeScript
+* Tailwind CSS
+* 静态导出后由 Go Server 托管
+
+## 核心对象
+
+当前有效实体包括 `proxy_routes`、`origins`、`config_versions`、`nodes`、`apply_logs`、`tls_certificates`、`managed_domains`、`node_request_reports`、`node_access_logs`、`node_metric_snapshots`、`traffic_analytics_rollups` 与 `node_health_events`。

docs/design/development.md

@@ -0,0 +1,35 @@
+# 开发约束
+
+OpenFlare `1.0.0` 之后的开发优先关注稳定性、升级与回滚链路可靠性、文档准确性、测试覆盖补强，以及既有边界内的小步迭代。
+
+## 变更准入
+
+新需求进入实现前，按以下顺序判断：
+
+1. 是否符合产品边界。
+2. 是否符合后端、Agent 与前端开发规范。
+3. 是否会破坏发布、同步、回滚或升级主链路。
+4. 是否需要同步更新部署、配置或 README 文档。
+
+如果需求超出边界或引入新基础设施，应先更新设计文档，再开始实现。
+
+## 数据库迁移
+
+任何涉及表结构、索引、列类型、分表规则或内部持久化元数据的修改，都必须同步提升数据库版本号，并补充从上一版本升级到新版本的显式迁移方法。
+
+迁移必须包含升级后的校验逻辑。迁移失败或校验失败时，启动流程必须中止，且不得提升数据库版本记录。
+
+## 前端约束
+
+前端以 `openflare_server/web` 为准：
+
+* 页面路由与布局放在 `app/`。
+* API 请求统一收敛到 `lib/api/`。
+* 业务逻辑优先放在 `features/`。
+* 服务端状态使用 TanStack Query。
+* 表单使用 React Hook Form 与 Zod。
+* 主题必须支持 `light`、`dark`、`system`。
+
+## 测试与交付
+
+关键业务逻辑必须有单元测试或等效回归测试。任何正式基线改动至少应保证不破坏 Agent 心跳、同步、发布与回滚主链路。

docs/design/index.md

@@ -0,0 +1,21 @@
+# 产品边界
+
+OpenFlare 是一套自托管的 OpenResty 控制面，面向单团队或单组织内部运维场景，解决反向代理配置、节点同步、证书托管与基础观测的统一管理问题。
+
+当前稳定能力包括：
+
+| 能力 | 说明 |
+| --- | --- |
+| 反代规则管理 | 以网站配置为聚合边界，支持多域名与源站配置 |
+| 配置版本 | 支持预览、发布、激活、历史回滚 |
+| Agent 同步 | 支持注册、心跳、同步、应用结果上报 |
+| OpenResty 托管 | 管理主配置模板、性能参数、缓存参数与 Lua 资源 |
+| HTTPS/TLS | 托管证书与域名资产，并按域名绑定证书 |
+| 基础观测 | 聚合节点请求、资源快照、健康事件和访问分析 |
+| 节点管理 | 节点状态、令牌体系、部署与更新链路 |
+
+默认工作方式：
+
+* 所有节点消费同一份全局激活版本。
+* Server 保存配置与状态，不直接 SSH 管理节点。
+* Agent 是节点侧唯一受控落地入口。

docs/design/release-model.md

@@ -0,0 +1,37 @@
+# 发布模型
+
+OpenFlare 的发布模型以完整配置版本为中心，而不是在线修改节点配置。
+
+标准链路：
+
+```text
+修改规则 -> 预览/查看 diff -> 发布 -> 生成完整配置版本 -> 激活版本 -> Agent 拉取 -> 本地应用 -> 上报结果
+```
+
+## 发布规则
+
+Server 发布时必须：
+
+1. 读取全部启用的 `proxy_routes`。
+2. 读取 Server 侧 OpenResty 主配置与结构化参数。
+3. 渲染完整 OpenResty 配置。
+4. 计算 `checksum`。
+5. 写入 `config_versions`。
+6. 切换激活版本。
+7. 让 Agent 在后续 heartbeat 中发现并应用。
+
+版本号格式固定为 `YYYYMMDD-NNN`。
+
+## 不可变历史
+
+历史版本不可变。回滚不是修改旧版本，而是重新激活旧版本。
+
+全局同时只能有一个激活版本，当前不做按节点分组的差异化版本。
+
+## Agent 应用策略
+
+Agent 发现新版本后会备份旧文件，写入主配置、路由配置、证书与必要 Lua 资源，再执行配置校验和 reload。
+
+如果新配置激活失败，Agent 必须尝试恢复运行；回滚成功时上报警告，回滚后仍无法恢复运行时上报失败。
+
+某个目标 `version + checksum` 一旦应用失败并回退，Agent 会在本地状态中阻断该目标重复应用。只有远端激活版本或 checksum 发生变化，才允许再次尝试。