[优化] 更新文档

docs/design/architecture.md

@@ -26,12 +26,12 @@ Origin
 
 ## 组件职责
 
-| 组件 | 职责 |
-| --- | --- |
-| Server | 管理端 UI、管理 API、Agent API、配置渲染、版本发布、数据存储与聚合查询 |
-| Agent | 注册、心跳、同步、写入文件、校验、reload、失败回滚、自更新与轻量采集 |
-| OpenResty | 接收真实流量，按 OpenFlare 渲染的配置执行 WAF、PoW、认证与反向代理 |
-| Frontend | 管理网站配置、WAF、源站、证书、节点、版本、用户、设置与观测页面 |
+| 组件      | 职责                                                                   |
+| --------- | ---------------------------------------------------------------------- |
+| Server    | 管理端 UI、管理 API、Agent API、配置渲染、版本发布、数据存储与聚合查询 |
+| Agent     | 注册、心跳、同步、写入文件、校验、reload、失败回滚、自更新与轻量采集   |
+| OpenResty | 接收真实流量，按 OpenFlare 渲染的配置执行 WAF、PoW、认证与反向代理     |
+| Frontend  | 管理网站配置、WAF、源站、证书、节点、版本、用户、设置与观测页面        |
 
 ## Server
 
@@ -64,13 +64,18 @@ Agent 通过 `openresty_path` 指向的 OpenResty 二进制统一执行校验、
 
 `openflare_server/web` 是正式管理端前端：
 
-* Next.js App Router。
+* Next.js 15 App Router。
 * React 19。
 * TypeScript。
 * Tailwind CSS。
 * TanStack Query 管理服务端状态。
 
-前端静态导出后由 Go Server 托管。所有 API 请求应统一经过 `lib/api/`，并处理 `success/message/data` 响应结构。
+前端采用静态导出模式（`output: 'export'`），导出后由 Go Server 通过 `embed.FS` 托管。所有 API 请求应统一经过 `lib/api/`，并处理 `success/message/data` 响应结构。
+
+Server 集成以下安全特性：
+* CORS 中间件：跨域请求保护。
+* 速率限制：全局与关键接口限流。
+* 会话管理：基于 Cookie/Redis 的会话存储。
 
 ## 数据与请求流
 
@@ -85,14 +90,23 @@ Browser -> Frontend -> /api/* -> controller -> service -> model -> database
 ### Agent 同步流
 
 ```text
-Agent heartbeat -> Server 返回激活版本摘要
+Agent HTTP heartbeat -> Server 返回激活版本摘要
 Agent 发现新版本 -> 拉取配置详情
 Agent 写入主配置 / 路由配置 / 证书 / Lua 资源 / WAF 运行时配置
 Agent 执行 OpenResty 校验与 reload
 Agent 上报应用结果
 ```
 
-默认启用 WS 连接升级时，Agent 会先通过 HTTP heartbeat 获取设置，随后尝试连接 Agent WebSocket。WS 成功后，周期性状态上报改由 WS 承载；Server 发布或激活版本后会向已连接 Agent 广播激活版本摘要，使 Agent 立即进入既有同步流程。WS 断开或建立失败时，Agent 自动退回 HTTP heartbeat。
+**WebSocket 升级流程**（可选，通过 `AgentWebsocketUpgradeEnabled` 选项控制）：
+
+当启用 WebSocket 升级时：
+1. Agent 通过 HTTP heartbeat 获取运行配置与设置。
+2. Agent 尝试升级连接到 `GET /api/agent/ws`（WebSocket）。
+3. WS 连接成功后，周期性状态上报和实时消息由 WebSocket 承载，降低延迟。
+4. Server 发布或激活版本后，可向已连接 Agent 立即广播激活版本摘要，使 Agent 立即进入同步流程。
+5. 若 WebSocket 断开或建立失败，Agent 自动降级回 HTTP heartbeat，保证可用性。
+
+通过 `OpenRestyWebsocketEnabled` 选项，可在 OpenResty 层面启用或禁用 WebSocket 反向代理支持。
 
 ### 反向代理流
 
@@ -125,16 +139,19 @@ WAF 在 OpenResty `access_by_lua_file` 阶段执行。规则来自当前激活
 * `node_health_events`
 * `waf_rule_groups`
 * `waf_rule_group_bindings`
+* `acme_accounts`
+* `dns_accounts`
+* `geoip_update_configs`
 
 ## 关键设计决策
 
-| 决策 | 原因 |
-| --- | --- |
-| 完整配置版本，而不是在线 patch | 让预览、激活、历史和回滚有稳定边界 |
-| Agent 主动拉取 | Server 不需要 SSH 权限，也不暴露远程命令入口 |
-| 全局单激活版本 | 降低 MVP 复杂度，保证所有节点默认一致 |
-| 网站配置聚合多域名 | 支持一个业务站点共享站点级策略，同时允许按域名绑定证书 |
-| 观测数据服务端聚合 | 避免前端临时统计造成口径不一致 |
+| 决策                           | 原因                                                                        |
+| ------------------------------ | --------------------------------------------------------------------------- |
+| 完整配置版本，而不是在线 patch | 让预览、激活、历史和回滚有稳定边界                                          |
+| Agent 主动拉取                 | Server 不需要 SSH 权限，也不暴露远程命令入口；支持 HTTP 与 WebSocket 双协议 |
+| 全局单激活版本                 | 降低 MVP 复杂度，保证所有节点默认一致；支持版本预览、历史查询与一键回滚     |
+| 网站配置聚合多域名             | 支持一个业务站点共享站点级策略，同时允许按域名绑定证书                      |
+| 观测数据服务端聚合             | 避免前端临时统计造成口径不一致                                              |
 
 ## 贡献者阅读建议