[新增] 更新文档

2026-09-28 05:46:36 +08:00 · 2026-05-28 22:50:24 +08:00
parent b69bdf838d
commit 5a0821274b
31 changed files with 2418 additions and 256 deletions
@@ -20,6 +20,13 @@
 6. [docs/reference/configuration.md](./docs/reference/configuration.md)
   作用：理解系统启动时支持的环境变量、命令行参数、运行时配置项和 Agent 配置字段。

+如任务涉及用户文档、贡献者入口或排障体验，还应阅读：
+
+* [docs/guide/quick-start.md](./docs/guide/quick-start.md)：理解新用户从 0 到运行的最短路径。
+* [docs/guide/usage.md](./docs/guide/usage.md)：理解网站配置、证书、发布、回滚和观测的基础用法。
+* [docs/guide/development.md](./docs/guide/development.md)：理解本地开发、测试和构建命令。
+* [docs/guide/troubleshooting.md](./docs/guide/troubleshooting.md)：理解常见失败症状与排查路径。
+
 线上文档入口：https://open-flare.pages.dev

 ## 执行要求
@@ -37,5 +44,8 @@
 * 系统结构、模块职责变化：更新 `docs/design/architecture.md`
 * 发布、同步、回滚模型变化：更新 `docs/design/release-model.md`
 * 开发约束、代码规范、接口约定、阶段原则、测试基线变化：更新 `docs/design/development.md`
-* 产品启动、部署、升级、联调方式变化：更新 `docs/guide/deployment.md` 和 `README.md`
+* 产品启动、部署、升级、联调方式变化：更新 `docs/guide/quick-start.md`、`docs/guide/deployment.md` 和 `README.md`
+* 用户操作路径、常见场景变化：更新 `docs/guide/usage.md`
+* 本地开发、测试、构建方式变化：更新 `docs/guide/development.md`
+* 常见故障、排查路径变化：更新 `docs/guide/troubleshooting.md`
 * 环境变量、命令行参数、运行时配置、Agent 配置变化：更新 `docs/reference/configuration.md`
@@ -68,12 +68,15 @@ function sidebarGuide(): DefaultTheme.SidebarItem[] {
      items: [
        { text: '概览', link: '' },
        { text: '快速开始', link: 'quick-start' },
+        { text: '基础使用', link: 'usage' },
        { text: '部署说明', link: 'deployment' },
        { text: 'SSO 登录配置', link: 'sso' },
        { text: '启动 Server', link: 'server' },
        { text: '接入 Agent', link: 'agent' },
        { text: '发布第一份配置', link: 'first-site' },
-        { text: '升级与维护', link: 'upgrade' }
+        { text: '升级与维护', link: 'upgrade' },
+        { text: '本地开发', link: 'development' },
+        { text: '故障排查', link: 'troubleshooting' }
      ]
    }
  ]
@@ -1,57 +1,137 @@
 # 系统架构

-OpenFlare 由 Server、Agent 与节点本地 OpenResty 组成。
+你会学到：OpenFlare 的整体架构、Server、Agent、OpenResty 与管理端前端的职责边界，以及一次配置发布从管理端到节点生效的请求流。
+
+OpenFlare 由 Server、Agent、节点本地 OpenResty 和管理端前端组成。Server 是控制面，Agent 是节点侧唯一受控落地入口，OpenResty 是实际数据面。

 ```text
-OpenFlare Server (Gin + SQLite/PostgreSQL + Web UI)
+Browser
  |
-        | HTTP API / Config Pull
+  | Management UI / API
  v
-OpenFlare Agent (register / heartbeat / sync / apply / update)
+OpenFlare Server (Gin + GORM + SQLite/PostgreSQL)
  |
+  | Agent API / heartbeat / config pull
  v
-Local OpenResty or Docker OpenResty
+OpenFlare Agent
  |
+  | write config / openresty -t / reload / rollback
+  v
+OpenResty binary
+  |
+  | reverse proxy
  v
 Origin
 ```

+## 组件职责
+
+| 组件 | 职责 |
+| --- | --- |
+| Server | 管理端 UI、管理 API、Agent API、配置渲染、版本发布、数据存储与聚合查询 |
+| Agent | 注册、心跳、同步、写入文件、校验、reload、失败回滚、自更新与轻量采集 |
+| OpenResty | 接收真实流量，按 OpenFlare 渲染的配置执行反向代理 |
+| Frontend | 管理网站配置、源站、证书、节点、版本、用户、设置与观测页面 |
+
 ## Server

 `openflare_server` 是单体控制面：

-* Gin
-* GORM
-* SQLite / PostgreSQL
-* 现有登录与 Session 体系
-* 认证源与外部账号绑定
-* 托管 `openflare_server/web` 静态构建产物
+* Gin 提供 HTTP 服务。
+* GORM 访问 SQLite 或 PostgreSQL。
+* 现有登录体系提供管理端 Session。
+* 认证源与外部账号绑定支持 GitHub OAuth 和标准 OIDC。
+* Go Server 托管 `openflare_server/web` 静态构建产物。

-Server 负责管理端 UI 与 API、Agent API、配置渲染、版本发布、数据存储与聚合查询。
-
-认证源登录由 Server 统一处理。管理端配置 `github` 或 `oidc` 认证源后，登录页从 `/api/status` 获取已启用认证源列表；OAuth/OIDC callback 仍回到管理端前端页面，再由前端调用 Server API 完成 code 交换、账号绑定与 Session 建立。
+Server 不直接 SSH 到节点，也不在线修改节点文件。它只保存控制面状态、生成完整配置版本，并通过 Agent API 让节点主动拉取。

 ## Agent

 `openflare_agent` 是 Go 单体程序：

-* 单二进制
-* 节点本地执行
-* 优先使用 `openresty_path`
-* 未配置 `openresty_path` 时默认使用 Docker OpenResty
+* 单二进制运行在节点侧。
+* 启动后读取或生成本地节点信息。
+* 周期性 heartbeat，上报状态并获取激活版本摘要。
+* 发现新版本后拉取配置、备份旧文件、写入新文件、校验并 reload。
+* 应用失败时尝试恢复运行并回滚。

-Agent 负责首次注册、周期性心跳、配置同步、文件写入、`openresty -t`、reload、失败回滚、自更新与轻量采集。
+Agent 通过 `openresty_path` 指向的 OpenResty 二进制统一执行校验、reload、启动与重启；未配置时默认调用 `openresty`。Docker 部署时，Agent 镜像内置 OpenResty 二进制，仍走同一套二进制控制逻辑。

 ## Frontend

 `openflare_server/web` 是正式管理端前端：

-* Next.js App Router
-* React 19
-* TypeScript
-* Tailwind CSS
-* 静态导出后由 Go Server 托管
+* Next.js App Router。
+* React 19。
+* TypeScript。
+* Tailwind CSS。
+* TanStack Query 管理服务端状态。
+
+前端静态导出后由 Go Server 托管。所有 API 请求应统一经过 `lib/api/`，并处理 `success/message/data` 响应结构。
+
+## 数据与请求流
+
+### 管理端请求流
+
+```text
+Browser -> Frontend -> /api/* -> controller -> service -> model -> database
+```
+
+管理端变更类接口使用 `POST`，只读接口使用 `GET`。成功与失败都返回清晰的 `message`。
+
+### Agent 同步流
+
+```text
+Agent heartbeat -> Server 返回激活版本摘要
+Agent 发现新版本 -> 拉取配置详情
+Agent 写入主配置 / 路由配置 / 证书 / Lua 资源
+Agent 执行 OpenResty 校验与 reload
+Agent 上报应用结果
+```
+
+### 反向代理流
+
+```text
+Client -> OpenResty server block -> named upstream -> Origin
+```
+
+网站配置是反向代理聚合边界。一条网站配置可绑定多个域名，并共享站点级流量限制、反向代理和缓存配置。

 ## 核心对象

-当前有效实体包括 `proxy_routes`、`origins`、`config_versions`、`nodes`、`auth_sources`、`external_accounts`、`apply_logs`、`tls_certificates`、`managed_domains`、`node_request_reports`、`node_access_logs`、`node_metric_snapshots`、`traffic_analytics_rollups` 与 `node_health_events`。
+当前有效实体包括：
+
+* `proxy_routes`
+* `origins`
+* `config_versions`
+* `nodes`
+* `auth_sources`
+* `external_accounts`
+* `node_system_profiles`
+* `apply_logs`
+* `tls_certificates`
+* `managed_domains`
+* `node_request_reports`
+* `node_access_logs`
+* `node_metric_snapshots`
+* `traffic_analytics_rollups`
+* `node_health_events`
+
+## 关键设计决策
+
+| 决策 | 原因 |
+| --- | --- |
+| 完整配置版本，而不是在线 patch | 让预览、激活、历史和回滚有稳定边界 |
+| Agent 主动拉取 | Server 不需要 SSH 权限，也不暴露远程命令入口 |
+| 全局单激活版本 | 降低 MVP 复杂度，保证所有节点默认一致 |
+| 网站配置聚合多域名 | 支持一个业务站点共享站点级策略，同时允许按域名绑定证书 |
+| 观测数据服务端聚合 | 避免前端临时统计造成口径不一致 |
+
+## 贡献者阅读建议
+
+如果要修改架构相关代码，先阅读：
+
+1. [产品边界](./index.md)
+2. [发布模型](./release-model.md)
+3. [开发约束](./development.md)
+4. [仓库结构](../reference/repository.md)
@@ -1,5 +1,7 @@
 # 开发约束

+你会学到：OpenFlare 代码修改的准入标准、后端/Agent/前端分层约束、数据模型边界、API 约定、数据库迁移要求和测试交付基线。
+
 本文档融合原开发规范、前端规范与开发计划，是 OpenFlare `1.0.0` 之后的工程约束入口。

 ## 当前结论
@@ -47,7 +49,7 @@ Server：
 * 现有登录体系

 Agent：
-* 
+
 * 单二进制
 * 节点本地执行
 * `openresty_path` 优先
@@ -1,8 +1,30 @@
 # 产品边界

-OpenFlare 是一套自托管的 OpenResty 控制面，面向单团队或单组织内部运维场景，解决反向代理配置、节点同步、证书托管与基础观测的统一管理问题。
+你会学到：OpenFlare 是什么、解决什么问题、目标用户是谁、当前稳定能力有哪些，以及哪些设计边界在实现时不能被绕过。

-当前稳定能力包括：
+OpenFlare 是一套自托管的 OpenResty 控制面，面向单团队或单组织内部运维场景。它解决反向代理配置、节点同步、证书托管、配置发布回滚与基础观测分散管理的问题。
+
+## 项目定位
+
+OpenFlare 适合需要统一管理多台 OpenResty 代理节点的团队：
+
+* 希望用管理端维护反向代理网站配置。
+* 希望每次配置变更都有完整版本、预览、激活与回滚。
+* 希望节点主动同步配置，而不是由控制面 SSH 到节点执行命令。
+* 希望在同一系统中管理 TLS 证书、域名资产、节点状态和基础访问分析。
+
+OpenFlare 当前不定位为通用日志平台、服务网格、Kubernetes Ingress Controller 或多租户云平台。
+
+## 目标用户
+
+| 用户 | 需求 |
+| --- | --- |
+| 自托管用户 | 快速部署一个可视化 OpenResty 控制面 |
+| 内部运维团队 | 管理多个反向代理节点、证书和配置版本 |
+| 开发团队 | 为内部服务提供统一入口和基础访问分析 |
+| 贡献者 | 在明确边界内修复缺陷、补强测试和改进文档 |
+
+## 当前稳定能力

 | 能力 | 说明 |
 | --- | --- |
@@ -24,6 +46,17 @@ OpenFlare 是一套自托管的 OpenResty 控制面，面向单团队或单组
 * Server 保存配置与状态，不直接 SSH 管理节点。
 * Agent 是节点侧唯一受控落地入口。

+## 典型使用场景
+
+| 场景 | 说明 |
+| --- | --- |
+| 内部服务统一入口 | 把多个内部 HTTP 服务通过统一域名和证书暴露 |
+| 多节点反代配置同步 | 多台 OpenResty 节点消费同一份激活配置 |
+| 配置变更审查 | 发布前查看预览或 diff，发布后保留不可变历史 |
+| 快速回滚 | 重新激活旧版本，让 Agent 拉取并应用 |
+| 证书托管 | 为不同域名绑定 TLS 证书 |
+| 基础观测 | 查看节点状态、请求聚合、访问分析和健康事件 |
+
 ## 核心对象

 当前有效实体：
@@ -108,6 +141,8 @@ OpenFlare 是一套自托管的 OpenResty 控制面，面向单团队或单组
 ## 文档维护原则

 * 产品范围或系统边界变化时更新本文档。
+* 系统结构或模块职责变化时更新 [系统架构](./architecture.md)。
+* 发布、同步、回滚模型变化时更新 [发布模型](./release-model.md)。
 * 开发约束、代码规范、接口约定变化时更新 [开发约束](./development.md)。
 * 部署方式变化时更新 [部署说明](../guide/deployment.md) 与 README。
 * 配置项变化时更新 [配置项参考](../reference/configuration.md)。
@@ -1,11 +1,13 @@
 # 发布模型

+你会学到：OpenFlare 为什么以完整配置版本为发布单位，发布、激活、Agent 应用和回滚分别如何工作。
+
 OpenFlare 的发布模型以完整配置版本为中心，而不是在线修改节点配置。

 标准链路：

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

 ## 发布规则
@@ -13,25 +15,57 @@ OpenFlare 的发布模型以完整配置版本为中心，而不是在线修改
 Server 发布时必须：

 1. 读取全部启用的 `proxy_routes`。
-2. 读取 Server 侧 OpenResty 主配置与结构化参数。
-3. 渲染完整 OpenResty 配置。
-4. 计算 `checksum`。
-5. 写入 `config_versions`。
-6. 切换激活版本。
-7. 让 Agent 在后续 heartbeat 中发现并应用。
+2. 读取 Server 侧 OpenResty 主配置、性能参数、缓存参数和必要 Lua 资源。
+3. 读取域名与证书绑定关系。
+4. 渲染完整 OpenResty 配置。
+5. 计算 `checksum`。
+6. 写入 `config_versions`。
+7. 切换激活版本。
+8. 让 Agent 在后续 heartbeat 中发现并应用。

 版本号格式固定为 `YYYYMMDD-NNN`。

+## 预览与发布
+
+预览和 diff 是只读能力，不产生发布记录。
+
+发布会生成新的完整配置版本。版本必须包含足够信息，让未来回滚时可以基于历史快照重新应用，而不依赖当前可变配置。
+
+## 激活版本
+
+全局同时只能有一个激活版本。当前不做按节点分组的差异化版本。
+
+Agent 通过 heartbeat 获取激活版本摘要；当远端版本或 checksum 与本地状态不一致时，Agent 才进入同步流程。
+
 ## 不可变历史

 历史版本不可变。回滚不是修改旧版本，而是重新激活旧版本。

-全局同时只能有一个激活版本，当前不做按节点分组的差异化版本。
+这样做的结果是：
+
+* 每个版本都可以追溯。
+* 回滚链路与普通发布应用链路一致。
+* Agent 不需要理解“反向 patch”，只需要应用一个目标版本。

 ## Agent 应用策略

-Agent 发现新版本后会备份旧文件，写入主配置、路由配置、证书与必要 Lua 资源，再执行配置校验和 reload。
+Agent 发现新版本后会：
+
+1. 拉取目标版本详情。
+2. 备份旧文件。
+3. 写入主配置、路由配置、证书与必要 Lua 资源。
+4. 执行 OpenResty 配置校验。
+5. reload 或重建 Docker OpenResty。
+6. 上报成功、警告或失败。

 如果新配置激活失败，Agent 必须尝试恢复运行；回滚成功时上报警告，回滚后仍无法恢复运行时上报失败。

 某个目标 `version + checksum` 一旦应用失败并回退，Agent 会在本地状态中阻断该目标重复应用。只有远端激活版本或 checksum 发生变化，才允许再次尝试。
+
+## 设计约束
+
+* 发布必须读取全部启用的网站配置，而不是只渲染本次修改对象。
+* 回滚通过重新激活旧版本实现，不修改历史版本。
+* Agent API 固定使用节点专属 `agent_token`，首次接入可使用 `discovery_token`。
+* Server 不提供远程 shell 或任意命令执行入口。
+* 配置版本必须保存完整快照、渲染结果和 `checksum`。
@@ -40,11 +40,15 @@ function sidebarGuide(): DefaultTheme.SidebarItem[] {
      items: [
        { text: 'Overview', link: '' },
        { text: 'Quick Start', link: 'quick-start' },
+        { text: 'Usage', link: 'usage' },
        { text: 'Deployment', link: 'deployment' },
+        { text: 'SSO Login', link: 'sso' },
        { text: 'Run Server', link: 'server' },
        { text: 'Connect Agent', link: 'agent' },
        { text: 'Publish First Site', link: 'first-site' },
-        { text: 'Upgrade and Maintenance', link: 'upgrade' }
+        { text: 'Upgrade and Maintenance', link: 'upgrade' },
+        { text: 'Local Development', link: 'development' },
+        { text: 'Troubleshooting', link: 'troubleshooting' }
      ]
    }
  ]
@@ -1,25 +1,54 @@
 # Deployment

-This page summarizes the OpenFlare deployment baseline, integration flow, upgrade entry points, and Agent install scripts.
+You will learn the recommended OpenFlare deployment model, Server and Agent requirements, source startup workflow, integration steps, upgrade paths, and uninstall entry points.
+
+For production, use PostgreSQL for the Server database and set `SESSION_SECRET` explicitly. Agent nodes use Docker OpenResty by default; local OpenResty mode requires `openresty_path` and write paths.
+
+## Topology
+
+```text
+Browser
+  |
+  v
+OpenFlare Server :3000
+  |
+  | Agent API / heartbeat / config pull
+  v
+OpenFlare Agent
+  |
+  v
+Local OpenResty or Docker OpenResty
+  |
+  v
+Origin service
+```

 ## Requirements

 Server:

-* Go 1.25+
-* Node.js 18+
-* Writable SQLite directory or reachable PostgreSQL instance
+| Item | Requirement |
+| --- | --- |
+| Go | `1.25+`, source run only |
+| Node.js | `18+`, frontend source build only |
+| Database | Writable SQLite directory or reachable PostgreSQL instance |
+| Port | `3000` by default |

 Agent:

-* Go 1.25+
-* Writable Agent data directory
-* Local mode requires `openresty -t` and `openresty -s reload`
-* Docker mode requires Docker access
+| Item | Requirement |
+| --- | --- |
+| OS | Install script supports Linux and macOS. systemd service is created only on Linux + systemd. |
+| Architecture | `amd64` or `arm64` |
+| Docker | Required by the default Docker OpenResty mode |
+| Local OpenResty | Required only when `openresty_path` is configured |
+| Network | Agent node must reach the Server URL |

-## Docker Compose
+[Needs confirmation: recommended production CPU, memory, and disk size]

-PostgreSQL is recommended for production:
+## Docker Compose Server
+
+Create `docker-compose.yml`:

 ```yaml
 services:
@@ -48,8 +77,7 @@ services:
    ports:
      - "3000:3000"
    environment:
-      SESSION_SECRET: replace-with-random-string
-      SQLITE_PATH: /data/openflare.db
+      SESSION_SECRET: replace-with-a-long-random-string
      DSN: postgres://openflare:replace-with-strong-password@postgres:5432/openflare?sslmode=disable
      GIN_MODE: release
      LOG_LEVEL: info
@@ -61,15 +89,48 @@ volumes:
  openflare-data:
 ```

+Start:
+
 ```bash
 docker compose up -d
+docker compose ps
+docker compose logs -f openflare
 ```

-Open `http://localhost:3000`. The default account is `root` / `123456`; change the password immediately.
+Open `http://localhost:3000`. The default account is `root` / `123456`; change it immediately.

-## Agent Install
+## Run Server from Source

-Using `discovery_token`:
+Build the management UI first:
+
+```bash
+cd openflare_server/web
+corepack enable
+pnpm install
+pnpm build
+```
+
+Then start Server:
+
+```bash
+cd openflare_server
+export SESSION_SECRET='replace-with-a-long-random-string'
+export SQLITE_PATH='./openflare.db'
+export LOG_LEVEL='info'
+# Optional: PostgreSQL takes precedence when set.
+# export DSN='postgres://openflare:secret@127.0.0.1:5432/openflare?sslmode=disable'
+go run .
+```
+
+Default port is `3000`. You can also set it explicitly:
+
+```bash
+go run . --port 3000 --log-dir ./logs
+```
+
+## Connect Agent
+
+With `discovery_token`:

 ```bash
 curl -fsSL https://raw.githubusercontent.com/Rain-kl/OpenFlare/main/scripts/install-agent.sh | bash -s -- \
@@ -77,7 +138,7 @@ curl -fsSL https://raw.githubusercontent.com/Rain-kl/OpenFlare/main/scripts/inst
  --discovery-token YOUR_DISCOVERY_TOKEN
 ```

-Using node-specific `agent_token`:
+With node-specific `agent_token`:

 ```bash
 curl -fsSL https://raw.githubusercontent.com/Rain-kl/OpenFlare/main/scripts/install-agent.sh | bash -s -- \
@@ -85,18 +146,116 @@ curl -fsSL https://raw.githubusercontent.com/Rain-kl/OpenFlare/main/scripts/inst
  --agent-token YOUR_AGENT_TOKEN
 ```

-Supported options include `--server-url`, `--discovery-token`, `--agent-token`, `--install-dir`, `--repo`, and `--no-service`.
+Supported options:

-## Validation
+| Option | Description |
+| --- | --- |
+| `--server-url` | Server URL, required |
+| `--discovery-token` | First-registration token, mutually exclusive with `--agent-token` |
+| `--agent-token` | Node-specific token, mutually exclusive with `--discovery-token` |
+| `--install-dir` | Install directory, default `/opt/openflare-agent` |
+| `--repo` | GitHub repository for Agent downloads, default `Rain-kl/OpenFlare` |
+| `--no-service` | Do not create a systemd service |

-1. Prepare `agent_token` or `discovery_token` in the console.
-2. Start Agent and confirm the node is online.
-3. Add an enabled reverse proxy site.
-4. Publish and activate a new version.
-5. Confirm Agent pulls, validates, reloads, and reports the result.
+Check status:

-## Uninstall Agent
+```bash
+systemctl status openflare-agent
+journalctl -u openflare-agent -f
+```
+
+## Run Agent Manually
+
+From source:
+
+```bash
+cd openflare_agent
+export LOG_LEVEL='info'
+go run ./cmd/agent -config /path/to/agent.json
+```
+
+Build and run:
+
+```bash
+cd openflare_agent
+go build -o openflare-agent ./cmd/agent
+export LOG_LEVEL='info'
+./openflare-agent -config /path/to/agent.json
+```
+
+Minimal `agent.json`:
+
+```json
+{
+  "server_url": "http://127.0.0.1:3000",
+  "agent_token": "replace-with-node-auth-token",
+  "data_dir": "./data",
+  "heartbeat_interval": 10000,
+  "request_timeout": 10000
+}
+```
+
+When `openresty_path` is not configured, Agent uses Docker OpenResty.
+
+## Minimal Integration Flow
+
+1. Start Server and sign in.
+2. Prepare `agent_token` or `discovery_token`.
+3. Start Agent and confirm the node is online.
+4. Create an enabled site configuration.
+5. Publish and activate a new version.
+6. Check node detail and apply logs.
+7. Visit the domain or verify with `curl`.
+
+## Upgrade and Uninstall
+
+Server:
+
+* Root users can check and upgrade stable Server releases from the top bar.
+* Preview releases can be checked manually.
+* Binary upload upgrades are also supported.
+
+Agent:
+
+* Agents follow stable releases by default.
+* The install script can be rerun to reinstall or upgrade.
+* Preview upgrades require manual action.
+
+Uninstall Agent:

 ```bash
 curl -fsSL https://raw.githubusercontent.com/Rain-kl/OpenFlare/main/scripts/uninstall-agent.sh | bash
 ```
+
+The uninstall script stops Agent, removes the systemd service and install directory, and attempts to remove the Docker OpenResty container/image when Docker mode is detected. Local `openresty_path` mode does not remove the local OpenResty installation.
+
+## Validation Commands
+
+Server:
+
+```bash
+cd openflare_server
+GOCACHE=/tmp/openflare-go-cache go test ./...
+```
+
+Agent:
+
+```bash
+cd openflare_agent
+GOCACHE=/tmp/openflare-go-cache go test ./...
+```
+
+Frontend:
+
+```bash
+cd openflare_server/web
+pnpm build
+```
+
+Swagger:
+
+```bash
+go install github.com/swaggo/swag/cmd/swag@v1.16.4
+cd openflare_server
+swag init -g main.go -o docs
+```
@@ -0,0 +1,187 @@
+# Local Development
+
+You will learn how to set up a local OpenFlare development environment, run the Server, Agent, and frontend, execute tests and builds, and understand the boundaries contributors must follow.
+
+This page is for contributors. Product boundaries, data model constraints, API conventions, and frontend layering are defined in [Development Constraints](../design/development.md). This page focuses on executable local workflows.
+
+## Repository Layout
+
+| Path | Responsibility |
+| --- | --- |
+| `openflare_server` | Gin + GORM + SQLite/PostgreSQL monolithic control plane |
+| `openflare_server/web` | Next.js management UI, statically exported and served by the Go Server |
+| `openflare_agent` | Go Agent binary running on nodes |
+| `scripts` | Agent install and uninstall scripts |
+| `docs` | VitePress documentation site |
+
+## Requirements
+
+| Tool | Requirement |
+| --- | --- |
+| Go | `1.25+` |
+| Node.js | `18+` |
+| pnpm | Use `corepack enable` to follow the project-declared version |
+| Docker | Needed for the default Docker OpenResty Agent mode and local integration |
+| PostgreSQL | Optional. The Server uses SQLite when PostgreSQL is not configured. |
+
+## Install Frontend Dependencies
+
+```bash
+cd openflare_server/web
+corepack enable
+pnpm install
+```
+
+Build static assets served by the Go Server:
+
+```bash
+pnpm build
+```
+
+## Run the Server
+
+SQLite:
+
+```bash
+cd openflare_server
+export SESSION_SECRET='dev-session-secret'
+export SQLITE_PATH='./openflare-dev.db'
+export LOG_LEVEL='debug'
+go run .
+```
+
+PostgreSQL:
+
+```bash
+cd openflare_server
+export SESSION_SECRET='dev-session-secret'
+export DSN='postgres://openflare:secret@127.0.0.1:5432/openflare?sslmode=disable'
+export LOG_LEVEL='debug'
+go run .
+```
+
+Default URL:
+
+```text
+http://localhost:3000
+```
+
+Default account: `root` / `123456`.
+
+## Run the Frontend Dev Server
+
+The frontend dev server listens on `3001` by default and proxies API requests through `NEXT_DEV_BACKEND_URL`:
+
+```bash
+cd openflare_server/web
+export NEXT_DEV_BACKEND_URL='http://127.0.0.1:3000'
+pnpm dev
+```
+
+Open:
+
+```text
+http://localhost:3001
+```
+
+## Run the Agent
+
+Create a local `agent.json`:
+
+```json
+{
+  "server_url": "http://127.0.0.1:3000",
+  "agent_token": "replace-with-node-auth-token",
+  "data_dir": "./data",
+  "heartbeat_interval": 10000,
+  "request_timeout": 10000
+}
+```
+
+Run:
+
+```bash
+cd openflare_agent
+export LOG_LEVEL='debug'
+go run ./cmd/agent -config ./agent.json
+```
+
+When `openresty_path` is not configured, the Agent uses Docker OpenResty. To debug local OpenResty, set `openresty_path`, `main_config_path`, `route_config_path`, `cert_dir`, and `lua_dir`.
+
+## Tests
+
+Server:
+
+```bash
+cd openflare_server
+GOCACHE=/tmp/openflare-go-cache go test ./...
+```
+
+Agent:
+
+```bash
+cd openflare_agent
+GOCACHE=/tmp/openflare-go-cache go test ./...
+```
+
+Frontend:
+
+```bash
+cd openflare_server/web
+pnpm lint
+pnpm typecheck
+pnpm test
+pnpm test:e2e
+```
+
+Docs:
+
+```bash
+cd docs
+pnpm build
+```
+
+## Builds
+
+Frontend static assets:
+
+```bash
+cd openflare_server/web
+pnpm build
+```
+
+Server binary:
+
+```bash
+cd openflare_server
+go build -o openflare-server .
+```
+
+Agent binary:
+
+```bash
+cd openflare_agent
+go build -o openflare-agent ./cmd/agent
+```
+
+## Debugging Entrypoints
+
+| Scenario | Command or Location |
+| --- | --- |
+| Server logs | `LOG_LEVEL=debug go run .` |
+| Agent logs | `LOG_LEVEL=debug go run ./cmd/agent -config ./agent.json` |
+| Swagger | `http://localhost:3000/swagger/index.html` |
+| Frontend API proxy | `NEXT_DEV_BACKEND_URL=http://127.0.0.1:3000 pnpm dev` |
+| Docker OpenResty container | `docker ps --filter name=openflare-openresty` |
+
+## Change Acceptance
+
+Before contributing, confirm that:
+
+1. The change fits [Product Boundary](../design/index.md).
+2. The implementation follows [Development Constraints](../design/development.md).
+3. It does not break release, sync, rollback, or upgrade flows.
+4. Documentation is updated when configuration, deployment, API, or product boundaries change.
+5. Risky changes include tests or equivalent integration verification.
+
+Database schema changes must bump the database version and include explicit migration and validation logic from the previous version.
@@ -1,12 +1,36 @@
 # Guide

-This section helps operators take OpenFlare from first boot to the first working reverse proxy configuration.
+You will learn how the OpenFlare documentation is organized, which pages to read for a first run, and where to find deployment, usage, troubleshooting, and development information.

-Suggested order:
+OpenFlare is a self-hosted OpenResty control plane. It brings reverse proxy site configuration, immutable releases, Agent-based node sync, TLS certificates, and basic observability into one management UI for a single team or organization.

-1. [Quick Start](./quick-start.md): run Server with Docker Compose and complete the first login.
-2. [Deployment](./deployment.md): review production deployment, Agent install, validation, and upgrade.
-3. [Run Server](./server.md): learn source startup, frontend build, and Swagger access.
-4. [Connect Agent](./agent.md): use `agent_token` or `discovery_token` to bring a node online.
-5. [Publish First Site](./first-site.md): create a site configuration, publish it, and verify node application.
-6. [Upgrade and Maintenance](./upgrade.md): understand upgrade, uninstall, validation, and maintenance entry points.
+## Recommended Path
+
+If you are new to OpenFlare, read these pages in order:
+
+1. [Quick Start](./quick-start.md): start the Server with Docker Compose, sign in, and connect the first Agent.
+2. [Usage](./usage.md): learn common operations for sites, origins, certificates, releases, rollbacks, and observability.
+3. [Deployment](./deployment.md): run the Server and Agent in an environment closer to production.
+4. [Configuration](../reference/configuration.md): look up Server environment variables, runtime options, and Agent configuration fields.
+5. [Troubleshooting](./troubleshooting.md): debug login, database, node sync, OpenResty apply, and frontend build issues.
+
+## Find by Role
+
+| Goal | Start Here |
+| --- | --- |
+| Run the management UI in a few minutes | [Quick Start](./quick-start.md) |
+| Publish the first reverse proxy site | [Publish First Site](./first-site.md) |
+| Connect or reinstall a node Agent | [Connect Agent](./agent.md) |
+| Start the Server from source | [Run Server](./server.md) |
+| Configure GitHub or OIDC login | [SSO Login](./sso.md) |
+| Upgrade the Server or Agent | [Upgrade and Maintenance](./upgrade.md) |
+| Contribute code or fix issues | [Local Development](./development.md) and [Development Constraints](../design/development.md) |
+| Understand architecture and releases | [Architecture](../design/architecture.md) and [Release Model](../design/release-model.md) |
+
+## Documentation Areas
+
+`guide/` is for users and operators. It provides executable steps from installation to daily operations.
+
+`reference/` collects stable facts, such as configuration fields, commands, API conventions, and repository layout.
+
+`design/` is for maintainers and contributors. It describes product boundaries, architecture, release model, and engineering constraints. Update the related design page before implementing changes that alter those boundaries.
@@ -1,10 +1,30 @@
 # Quick Start

-The minimal OpenFlare setup contains one Server and at least one Agent. Server owns the web console, release versions, and node state. Agent runs on proxy nodes and applies OpenResty configuration.
+You will learn how to start OpenFlare Server with Docker Compose, sign in for the first time, connect the first Agent, and verify that a configuration was published to a node.

-## Run Server
+The minimal OpenFlare setup contains:

-Docker Compose with PostgreSQL is recommended:
+| Component | Responsibility |
+| --- | --- |
+| Server | Management UI, management API, Agent API, configuration rendering, release publishing, and state storage |
+| Agent | Runs on proxy nodes, pulls configuration, writes OpenResty files, validates, and reloads |
+| OpenResty | Receives traffic and proxies requests to origins |
+
+By default, the Agent uses Docker OpenResty when `openresty_path` is not configured. Prepare Docker on Agent nodes for this quick start.
+
+## Requirements
+
+| Item | Requirement |
+| --- | --- |
+| Docker / Docker Compose | Used to start Server and PostgreSQL, and used by the default Agent Docker OpenResty mode |
+| Reachable ports | Server listens on `3000` by default. Agent nodes must reach the Server URL. |
+| Browser | Used to open the management UI |
+
+[Needs confirmation: minimum recommended Docker and Docker Compose versions]
+
+## 1. Start Server
+
+Create `docker-compose.yml` in an empty directory:

 ```yaml
 services:
@@ -32,7 +52,7 @@ services:
    ports:
      - "3000:3000"
    environment:
-      SESSION_SECRET: replace-with-random-string
+      SESSION_SECRET: replace-with-a-long-random-string
      DSN: postgres://openflare:replace-with-strong-password@postgres:5432/openflare?sslmode=disable
      GIN_MODE: release
      LOG_LEVEL: info
@@ -41,13 +61,26 @@ volumes:
  postgres-data:
 ```

+Start:
+
 ```bash
 docker compose up -d
 ```

-Open `http://localhost:3000`.
+Verify:

-Default credentials:
+```bash
+docker compose ps
+docker compose logs -f openflare
+```
+
+When the `openflare` container is running and logs show `server listening`, open:
+
+```text
+http://localhost:3000
+```
+
+Default account:

 | Username | Password |
 | --- | --- |
@@ -55,9 +88,32 @@ Default credentials:

 Change the default password immediately after first login.

-## Connect a Node
+## 2. Prepare an Agent Token

-Prepare a `discovery_token` or node-specific `agent_token` in the console, then run the install script on the node.
+Agents can connect with either:
+
+| Credential | Use Case |
+| --- | --- |
+| `discovery_token` | First-time automatic node registration. Server exchanges it for a node-specific token. |
+| `agent_token` | A node-specific token created or assigned in the management UI. |
+
+Prepare one of them in the management UI before continuing.
+
+[Needs confirmation: exact UI menu path for creating or viewing `discovery_token` and node `agent_token`]
+
+## 3. Install Agent
+
+Run the install script on the proxy node.
+
+With `discovery_token`:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/Rain-kl/OpenFlare/main/scripts/install-agent.sh | bash -s -- \
+  --server-url http://your-server:3000 \
+  --discovery-token YOUR_DISCOVERY_TOKEN
+```
+
+With node-specific `agent_token`:

 ```bash
 curl -fsSL https://raw.githubusercontent.com/Rain-kl/OpenFlare/main/scripts/install-agent.sh | bash -s -- \
@@ -65,13 +121,64 @@ curl -fsSL https://raw.githubusercontent.com/Rain-kl/OpenFlare/main/scripts/inst
  --agent-token YOUR_AGENT_TOKEN
 ```

-The script installs Agent under `/opt/openflare-agent`, creates `openflare-agent.service`, and uses Docker OpenResty unless a local `openresty_path` is configured.
+The script defaults to:

-## Publish the First Configuration
+| Item | Default |
+| --- | --- |
+| Install directory | `/opt/openflare-agent` |
+| Config file | `/opt/openflare-agent/agent.json` |
+| systemd service | `openflare-agent.service` |
+| OpenResty mode | Docker OpenResty when `openresty_path` is not configured |

-1. Create a site configuration with a domain and origin URL.
-2. Preview the release or check the diff before publishing.
-3. Activate the new version.
-4. Wait for Agent to discover and apply it through heartbeat.
+Check status:
+
+```bash
+systemctl status openflare-agent
+journalctl -u openflare-agent -f
+```
+
+If systemd is unavailable, the script prints a manual start command.
+
+## 4. Publish the First Configuration
+
+In the management UI:
+
+1. Create a site configuration with a site name, domain, and origin URL.
+2. Ensure the site is enabled.
+3. Preview the rendered configuration or review the diff.
+4. Publish and activate a new version.
+5. Wait for the Agent to discover and apply the version through heartbeat.

 Version numbers use `YYYYMMDD-NNN`. Historical versions are immutable; rollback reactivates an old version.
+
+## 5. Verify Success
+
+In the UI:
+
+| Location | Expected Result |
+| --- | --- |
+| Node list | Agent node is online |
+| Node detail | Current version matches the active version |
+| Apply logs | Latest apply succeeded |
+| Versions page | New version is active |
+
+On the Agent node:
+
+```bash
+journalctl -u openflare-agent -n 100 --no-pager
+docker ps --filter name=openflare-openresty
+```
+
+If Docker OpenResty is used, the default container name is `openflare-openresty`.
+
+## Common Failures
+
+| Symptom | What to Check |
+| --- | --- |
+| Cannot open the UI | Confirm `docker compose ps` shows Server running and host port `3000` is free |
+| Login works but data cannot be saved | Check PostgreSQL health and the username/password/database in `DSN` |
+| Agent cannot register | Confirm the Agent node can reach `--server-url`, and check whether the token is wrong or expired |
+| Agent is online but does not apply | Confirm the site is enabled and a version was published and activated |
+| OpenResty apply fails | Check apply logs and `journalctl -u openflare-agent`, especially domains, certificates, upstream URLs, and port conflicts |
+
+See [Troubleshooting](./troubleshooting.md) for deeper diagnostics.
@@ -0,0 +1,104 @@
+# SSO Login
+
+You will learn how to configure GitHub OAuth or a standard OIDC login source for OpenFlare, how to set callback URLs, and how third-party accounts bind to local users.
+
+OpenFlare supports third-party login through authentication sources. The current supported source types are GitHub OAuth and standard OIDC providers, such as Logto, authentik, Keycloak, and Casdoor.
+
+After an authentication source is configured and enabled, it appears on the login page. Users can sign in with the third-party account or bind it to the current local account while already signed in.
+
+## Before You Start
+
+Prepare:
+
+| Item | Description |
+| --- | --- |
+| OpenFlare public URL | The URL users open in their browser, such as `https://openflare.example.com` |
+| Source name | Internal unique name, such as `github` or `company-oidc` |
+| Client ID | Provided by the third-party application |
+| Client Secret | Provided by the third-party application |
+| OIDC Discovery URL | Required only for OIDC, such as `https://idp.example.com/.well-known/openid-configuration` |
+
+Confirm that the server address in system settings matches the domain users access.
+
+The source name can contain letters, numbers, hyphens, and underscores, and must start with a letter or number. The source name is part of the callback URL. If you rename it later, update the callback URL in the third-party platform too.
+
+## Callback URL
+
+Set the Redirect URI / Callback URL in the third-party platform to:
+
+```text
+<OpenFlare public URL>/oauth/<source name>
+```
+
+Examples:
+
+```text
+https://openflare.example.com/oauth/github
+https://openflare.example.com/oauth/company-oidc
+```
+
+When creating or editing an authentication source, the UI shows the callback URL based on the current browser URL and source name.
+
+## Configure GitHub Login
+
+1. Create an OAuth App in GitHub.
+2. Set `Homepage URL` to the OpenFlare public URL.
+3. Set `Authorization callback URL` to the callback shown by OpenFlare, such as `https://openflare.example.com/oauth/github`.
+4. Copy the Client ID and Client Secret.
+5. Sign in to OpenFlare and open Settings -> System Settings -> Authentication Sources.
+6. Add a source and select `GitHub`.
+7. Fill in source name, display name, Client ID, and Client Secret.
+8. Keep the default scope `user:email` unless your GitHub app requires a different value.
+9. Save and enable the source.
+
+The login page will show the GitHub button after the source is enabled.
+
+## Configure OIDC Login
+
+1. Create an application or client in the OIDC provider.
+2. Choose a Web / Confidential Client type.
+3. Set Redirect URI / Callback URL to the value shown by OpenFlare, such as `https://openflare.example.com/oauth/company-oidc`.
+4. Copy the Client ID and Client Secret.
+5. Get the provider Discovery URL, usually ending in `/.well-known/openid-configuration`.
+6. Sign in to OpenFlare and open Settings -> System Settings -> Authentication Sources.
+7. Add a source and select `OIDC`.
+8. Fill in source name, display name, Client ID, Client Secret, and OIDC Discovery URL.
+9. Keep the default scope `openid profile email` unless the provider restricts scopes.
+10. Save and enable the source.
+
+The login page will show the OIDC button after the source is enabled.
+
+## Login and Binding Behavior
+
+| Scenario | Behavior |
+| --- | --- |
+| Third-party account already bound to a local user | Sign in directly |
+| User is already signed in and starts third-party authorization | Bind the third-party account to the current local user |
+| Third-party account is unbound and registration is allowed | Create a normal local user and bind it |
+| Third-party account is unbound and registration is disabled | Ask the user to enter existing local credentials to bind |
+
+If you only want existing users to use SSO, disable registration. Unbound third-party accounts will enter the existing-account binding flow.
+
+## Update a Source
+
+When editing an authentication source, leave Client Secret empty to keep the existing secret. Entering a new value overwrites it.
+
+If you change the source name, the callback URL changes too. Update Redirect URI / Callback URL in the third-party platform, or the provider will reject the callback.
+
+## FAQ
+
+### `invalid_scope`
+
+The provider does not allow the configured scope. The OIDC default is `openid profile email`; the GitHub default is `user:email`. Adjust the scope in OpenFlare or allow it in the provider.
+
+### Callback URL Mismatch
+
+Check that the Redirect URI / Callback URL in the provider exactly matches the URL shown by OpenFlare. Protocol, domain, port, and path must all match.
+
+### No Third-Party Login Button
+
+Check that the source is enabled and that Client ID and Client Secret are saved. OpenFlare validates these fields before enabling a source.
+
+### Client Secret Is Not Shown in the List
+
+This is expected. OpenFlare does not return Client Secret through the API; it only shows whether the secret is configured.
@@ -0,0 +1,224 @@
+# Troubleshooting
+
+You will learn how to debug OpenFlare Server, database, login, Agent, OpenResty, release, and frontend build issues by symptom.
+
+Start by locating the failing layer: browser, Server, database, Agent, OpenResty, origin, or DNS. OpenFlare applies configuration only after a version is activated and the Agent discovers it through heartbeat.
+
+## Quick Triage
+
+| Symptom | Check First |
+| --- | --- |
+| Management UI does not open | Server process/container logs and port binding |
+| Login fails | Default account, `SESSION_SECRET`, browser request, Server logs |
+| Data cannot be saved | Database connection, SQLite permissions, PostgreSQL health |
+| Agent is offline | Agent logs, token, Server URL, network reachability |
+| Node does not update after release | Active version, node heartbeat, apply logs |
+| OpenResty apply fails | Apply logs, Agent logs, certificates, upstream URL, port conflicts |
+| No access analytics | OpenResty status, observability port, Agent replay logs |
+
+## Server Does Not Start
+
+1. Check logs:
+
+```bash
+docker compose logs -n 200 openflare
+```
+
+For source runs, check terminal output.
+
+2. Check port usage:
+
+```bash
+lsof -i :3000
+```
+
+3. If PostgreSQL is used, check database health:
+
+```bash
+docker compose ps postgres
+docker compose logs -n 100 postgres
+```
+
+4. If SQLite is used, check that the database directory is writable:
+
+```bash
+ls -ld "$(dirname /path/to/openflare.db)"
+```
+
+Common causes:
+
+| Log or Symptom | Fix |
+| --- | --- |
+| Database connection failed | Check username, password, host, port, database, and `sslmode` in `DSN` |
+| SQLite cannot create file | Check that the `SQLITE_PATH` directory exists and is writable |
+| Port is already in use | Change `PORT` or `--port`, or stop the process using the port |
+
+## UI Does Not Open or Is Blank
+
+1. Confirm that the Server responds:
+
+```bash
+curl -I http://127.0.0.1:3000
+```
+
+2. For source runs, confirm frontend static assets were built:
+
+```bash
+cd openflare_server/web
+pnpm build
+```
+
+3. Check whether the browser URL matches your reverse proxy setup.
+
+4. If using the frontend dev server, confirm backend proxy configuration:
+
+```bash
+cd openflare_server/web
+NEXT_DEV_BACKEND_URL=http://127.0.0.1:3000 pnpm dev
+```
+
+## Default Account Cannot Sign In
+
+The default account is `root` / `123456`. If the password was changed after first login, use the updated password.
+
+Steps:
+
+1. Confirm the Server is connected to the expected database, not another `SQLITE_PATH` or `DSN`.
+2. Check Server logs to see whether it uses `sqlite` or `postgres`.
+3. If deployed behind replicas or a reverse proxy, ensure `SESSION_SECRET` is fixed and consistent across instances.
+4. Clear browser cookies and try again.
+
+[Needs confirmation: whether the project provides a safe root password reset command or procedure]
+
+## Agent Cannot Register or Stays Offline
+
+On the Agent node:
+
+```bash
+curl -I http://your-server:3000
+```
+
+Check Agent logs:
+
+```bash
+journalctl -u openflare-agent -n 200 --no-pager
+```
+
+Check config:
+
+```bash
+sed -n '1,160p' /opt/openflare-agent/agent.json
+```
+
+Confirm:
+
+| Config | Notes |
+| --- | --- |
+| `server_url` | Must be reachable from the Agent node |
+| `agent_token` / `discovery_token` | At least one is required |
+| `heartbeat_interval` | Supports millisecond integers or Go duration strings |
+| `request_timeout` | Increase it for slow networks |
+
+If the log says the token is invalid, prepare a new token in the UI, update `agent.json`, and restart:
+
+```bash
+systemctl restart openflare-agent
+```
+
+## Node Does Not Apply a New Version
+
+Check in order:
+
+1. The target version is active on the versions page.
+2. The node is online and heartbeat time is updating.
+3. Apply logs contain a success, warning, or failure for the target version.
+4. The site configuration is enabled.
+5. Agent logs show pull, validation, reload, or rollback messages.
+
+Follow Agent logs:
+
+```bash
+journalctl -u openflare-agent -f
+```
+
+After a target `version + checksum` fails and rolls back, the Agent blocks repeated attempts for that same target locally. Fix the configuration and publish a new checksum, or activate an old version to roll back.
+
+## OpenResty Apply Fails
+
+Common causes:
+
+| Cause | Check |
+| --- | --- |
+| Domain or server block conflict | Ensure the same domain is not used by multiple sites |
+| Invalid upstream URL | Every upstream must be `http://` or `https://` |
+| Invalid multi-upstream format | Multiple upstreams must be plain `scheme://host[:port]` |
+| Missing certificate or wrong path | Check domain certificate binding and Agent certificate directory permissions |
+| Port conflict | Check local or Docker `80` and `443` usage |
+
+Docker OpenResty mode:
+
+```bash
+docker ps --filter name=openflare-openresty
+docker logs --tail 100 openflare-openresty
+```
+
+Local OpenResty mode:
+
+```bash
+/usr/local/openresty/nginx/sbin/nginx -t
+```
+
+Use the actual path from `openresty_path` in `agent.json`.
+
+## HTTPS Does Not Work
+
+1. Confirm the certificate exists.
+2. Confirm the domain is bound to that certificate in the site configuration.
+3. Confirm a new version was published and activated.
+4. Check apply logs for success.
+5. Inspect with `curl`:
+
+```bash
+curl -Iv https://your-domain
+```
+
+Domains without a bound certificate are not automatically added to HTTPS configuration.
+
+## No Access Analytics
+
+1. Confirm the node applied a configuration that includes observability Lua assets.
+2. Confirm Docker OpenResty or local OpenResty is running.
+3. Check Agent logs for collection or replay failures.
+4. Check whether `openresty_observability_port` is occupied. The default is `18081`.
+5. Confirm Server cleanup policy did not remove data for that time window.
+
+## Frontend Build Fails
+
+```bash
+cd openflare_server/web
+corepack enable
+pnpm install
+pnpm lint
+pnpm typecheck
+pnpm test
+pnpm build
+```
+
+Common causes:
+
+| Symptom | Fix |
+| --- | --- |
+| pnpm version mismatch | Run `corepack enable` and reinstall |
+| Type errors | Run `pnpm typecheck` to locate files |
+| API type mismatch | Check `lib/api/` and `types/` response structures |
+| E2E fails | Ensure both the Server and frontend dev server are running |
+
+## Docs Build Fails
+
+```bash
+cd docs
+pnpm install
+pnpm build
+```
+
+If the failure is a link error, check that new pages are added to `docs/en/config.ts` and that relative links point to existing Markdown files.
@@ -0,0 +1,134 @@
+# Usage
+
+You will learn what sites, origins, certificates, versions, nodes, and observability mean in OpenFlare, and which order to follow for daily operations.
+
+OpenFlare does not patch OpenResty configuration files online. You edit control-plane data in the UI; Agents pull and apply a full configuration only after you publish and activate a new version.
+
+## Core Concepts
+
+| Concept | Description |
+| --- | --- |
+| Site configuration | The reverse proxy aggregation object. One site can bind one or more domains. |
+| Primary domain | The first item in the `domains` list. |
+| Origin | The upstream service address, such as `http://10.0.0.10:8080`. |
+| Configuration version | A full OpenResty configuration snapshot generated by a release. Historical versions are immutable. |
+| Active version | The globally effective version. By default, all nodes consume the same active version. |
+| Agent | The node-side process that registers, heartbeats, syncs, validates, reloads, and rolls back on failure. |
+
+## Recommended Workflow
+
+For a normal reverse proxy change:
+
+1. Confirm that at least one Agent node is online.
+2. Create or select an origin.
+3. Create a site configuration with domains, upstreams, and site-level settings.
+4. If HTTPS is needed, upload or select certificates and bind them per domain.
+5. Preview the rendered configuration or review the diff.
+6. Publish and activate a new version.
+7. Check node details and apply logs.
+
+## Create a Site
+
+A site requires at least:
+
+| Field | Requirement |
+| --- | --- |
+| Site name | Business-unique identifier. The primary domain is a common default. |
+| Domains | At least one domain. The first domain is the primary domain. Each domain must be globally unique. |
+| Origin URL | A valid `http://` or `https://` upstream address. |
+| Enabled state | Only enabled sites are included in release rendering. |
+
+Example:
+
+| Field | Example |
+| --- | --- |
+| Site name | `docs` |
+| Domain | `docs.example.com` |
+| Origin URL | `http://10.0.0.10:8080` |
+| Origin Host | `docs.internal.example.com` |
+
+Upstream rules:
+
+* A single upstream may include a base path or query string, such as `https://app.example.com/base?from=openflare`.
+* Multiple upstreams are used for load balancing and must be plain `scheme://host[:port]`.
+* Multiple upstreams in the same site should use the same protocol.
+
+## Manage Origins
+
+Origins are a lightweight reusable address directory. When a site references an origin, the site still stores a renderable `origin_url` snapshot so historical versions can be replayed independently.
+
+Recommended practices:
+
+* Store frequently reused internal service addresses as origins.
+* After changing an origin entry, check whether site snapshots need to be updated.
+* Use preview or diff before publishing.
+
+## Enable HTTPS
+
+HTTPS is bound per domain, not forced for the whole site.
+
+1. Upload or create a certificate record.
+2. Open the site configuration and select a certificate for each domain that needs HTTPS.
+3. Domains without a certificate stay HTTP-only and are not automatically added to `443 ssl` server blocks.
+4. Publish and activate a new version.
+
+If a site contains multiple domains, the Server groups HTTPS output by certificate while keeping all domains in the same site snapshot.
+
+## Release, Activate, and Roll Back
+
+Standard flow:
+
+```text
+Edit configuration -> Preview / diff -> Release -> Generate full version -> Activate version -> Agent pulls -> Agent applies locally -> Agent reports result
+```
+
+During release, the Server reads all enabled site configurations, OpenResty main template, performance options, cache options, and certificate assets. It renders a full configuration and calculates a `checksum`.
+
+Rollback means reactivating an old version. The Agent then applies that version through the normal sync flow.
+
+## Nodes and Observability
+
+Node pages answer three questions:
+
+| Question | Where to Check |
+| --- | --- |
+| Is the node online? | Node list or node detail |
+| Which version is running? | Current version on the node detail page |
+| Did the last apply succeed? | Apply logs |
+
+Access analytics and resource snapshots provide basic observability. OpenFlare only keeps access details for a controlled time window; it is not a general-purpose log platform. Use a dedicated logging system for long-term log search.
+
+## Common Scenarios
+
+### Add a Reverse Proxy for an Internal Service
+
+1. Confirm the Agent node can reach the origin service.
+2. Create a site configuration.
+3. Add a domain, such as `app.example.com`.
+4. Add an origin, such as `http://10.0.0.20:8080`.
+5. Publish and activate the version.
+6. Verify the domain from a browser or with `curl`.
+
+### Enable HTTPS for an Existing Domain
+
+1. Prepare a certificate that covers the domain.
+2. Upload or create the certificate record.
+3. Bind the certificate to the domain in the site configuration.
+4. Publish and activate a new version.
+5. Verify with `curl -I https://your-domain`.
+
+### Roll Back a Failed Release
+
+1. Open the configuration versions page.
+2. Find the last known good version.
+3. Activate that version again.
+4. Check apply logs until the Agent reports success.
+5. Fix the configuration and publish a new version.
+
+## Recommended Practices
+
+* Set `SESSION_SECRET` explicitly in production and prefer PostgreSQL.
+* Preview or diff changes before release.
+* Check node details and apply logs after each release.
+* Keep the network path from Agents to the Server stable.
+* Do not manually edit OpenFlare-managed OpenResty files on nodes; the next release will overwrite them.
@@ -1,19 +1,21 @@
 # 接入 Agent

-OpenFlare Agent 运行在节点侧，负责注册、心跳、同步配置、写入 OpenResty 文件、校验、reload、失败回滚与自更新。
+你会学到：Agent 的职责、两种接入 Token 的区别、安装脚本参数、`agent.json` 配置方式，以及如何确认节点已经上线。
+
+OpenFlare Agent 运行在代理节点侧。它不会接收远程 shell 指令，而是通过 Agent API 拉取控制面发布的配置版本，在本地写入 OpenResty 文件、执行配置校验、reload，并在失败时尝试回滚到可运行配置。

 ## 接入方式

-Agent 支持两种认证入口：
-
 | 方式 | 适用场景 |
 | --- | --- |
-| `agent_token` | 已在管理端创建或分配节点，使用节点专属凭证接入 |
 | `discovery_token` | 首次自动注册节点，由 Server 置换为节点专属凭证 |
+| `agent_token` | 已在管理端创建或分配节点，直接使用节点专属凭证接入 |

-二者至少填写一个。
+`agent_token` 与 `discovery_token` 至少填写一个。

-## 安装脚本
+[需要确认：当前管理端中创建或查看 `discovery_token` 与节点 `agent_token` 的准确菜单路径]
+
+## 一键安装

 使用 `discovery_token`：

@@ -31,9 +33,28 @@ curl -fsSL https://raw.githubusercontent.com/Rain-kl/OpenFlare/main/scripts/inst
  --agent-token YOUR_AGENT_TOKEN
 ```

-安装脚本会写入 `/opt/openflare-agent`，创建 `openflare-agent.service`，并可重复执行以重装或升级 Agent。
+安装脚本会下载最新 Agent，默认写入 `/opt/openflare-agent`，生成 `agent.json`，并在 Linux + systemd 环境创建 `openflare-agent.service`。

-## 配置文件示例
+支持参数：
+
+| 参数 | 说明 |
+| --- | --- |
+| `--server-url` | Server 地址，必填 |
+| `--discovery-token` | 首次自动注册 Token |
+| `--agent-token` | 节点专属 Token |
+| `--install-dir` | 安装目录，默认 `/opt/openflare-agent` |
+| `--repo` | 下载 Agent 的 GitHub 仓库，默认 `Rain-kl/OpenFlare` |
+| `--no-service` | 不创建 systemd 服务 |
+
+## 配置文件
+
+默认配置文件路径：
+
+```text
+/opt/openflare-agent/agent.json
+```
+
+Docker OpenResty 模式示例：

 ```json
 {
@@ -49,9 +70,41 @@ curl -fsSL https://raw.githubusercontent.com/Rain-kl/OpenFlare/main/scripts/inst
 }
 ```

-未配置 `openresty_path` 时，Agent 默认使用 Docker OpenResty。裸 OpenResty 模式需要显式配置本机路径和必要的配置写入目录。
+本机 OpenResty 模式示例：

-## 源码运行
+```json
+{
+  "server_url": "http://127.0.0.1:3000",
+  "agent_token": "replace-with-node-auth-token",
+  "data_dir": "/var/lib/openflare-agent",
+  "openresty_path": "/usr/local/openresty/nginx/sbin/nginx",
+  "main_config_path": "/usr/local/openresty/nginx/conf/nginx.conf",
+  "route_config_path": "/usr/local/openresty/nginx/conf/conf.d/openflare_routes.conf",
+  "cert_dir": "/usr/local/openresty/nginx/conf/openflare-certs",
+  "lua_dir": "/usr/local/openresty/nginx/conf/openflare-lua",
+  "heartbeat_interval": 10000,
+  "request_timeout": 10000
+}
+```
+
+如果不配置 `openresty_path`，Agent 默认使用 Docker OpenResty。完整字段见 [配置项参考](../reference/configuration.md#agent-配置字段)。
+
+## 启动与验证
+
+systemd 环境：
+
+```bash
+systemctl status openflare-agent
+journalctl -u openflare-agent -f
+```
+
+手动启动：
+
+```bash
+/opt/openflare-agent/openflare-agent -config /opt/openflare-agent/agent.json
+```
+
+源码运行：

 ```bash
 cd openflare_agent
@@ -59,7 +112,7 @@ export LOG_LEVEL='info'
 go run ./cmd/agent -config /path/to/agent.json
 ```

-## 编译后二进制运行
+编译后二进制运行：

 ```bash
 cd openflare_agent
@@ -68,6 +121,14 @@ export LOG_LEVEL='info'
 ./openflare-agent -config /path/to/agent.json
 ```

+在管理端确认：
+
+| 位置 | 期望结果 |
+| --- | --- |
+| 节点列表 | 节点在线 |
+| 节点详情 | 能看到心跳时间、当前版本和基础资源信息 |
+| 应用记录 | 发布配置后出现应用结果 |
+
 ## 卸载

 如需彻底卸载 Agent 并清空本地数据：
@@ -76,4 +137,20 @@ export LOG_LEVEL='info'
 curl -fsSL https://raw.githubusercontent.com/Rain-kl/OpenFlare/main/scripts/uninstall-agent.sh | bash
 ```

-卸载脚本会停止并移除 `openflare-agent.service`，删除 `/opt/openflare-agent`，并根据配置尝试清理 Docker OpenResty 容器。
+支持参数：
+
+| 参数 | 说明 |
+| --- | --- |
+| `--install-dir` | 安装目录，默认 `/opt/openflare-agent` |
+| `--service-name` | systemd 服务名，默认 `openflare-agent` |
+
+卸载脚本会先读取卸载前的 `agent.json` 判断 OpenResty 模式。Docker 模式会尝试删除对应容器和镜像；本机 `openresty_path` 模式不会删除本机 OpenResty。
+
+## 常见问题
+
+| 现象 | 处理步骤 |
+| --- | --- |
+| `agent_token 和 discovery_token 不能同时为空` | 检查 `agent.json` 至少配置了一个 Token |
+| 节点一直离线 | 在 Agent 节点执行 `curl -I http://your-server:3000`，确认 Server 地址可达 |
+| Docker OpenResty 没有启动 | 查看 `journalctl -u openflare-agent`，并确认当前用户有 Docker 执行权限 |
+| 发布后重复失败 | Agent 会阻断同一 `version + checksum` 的重复应用；需要修正配置后重新发布，或激活旧版本回滚 |
@@ -1,25 +1,54 @@
 # 部署说明

-本文档说明 OpenFlare `1.0.0` 之后的部署基线、联调入口、升级方式与 Agent 一键部署流程。
+你会学到：OpenFlare 的推荐部署方式、Server 与 Agent 的运行要求、源码启动方式、联调步骤、升级与卸载入口。
+
+生产环境建议使用 PostgreSQL 作为 Server 数据库，并为 Server 显式配置 `SESSION_SECRET`。Agent 节点默认使用 Docker OpenResty；如果要使用本机 OpenResty，需要额外配置 `openresty_path` 和写入目录。
+
+## 部署拓扑
+
+```text
+Browser
+  |
+  v
+OpenFlare Server :3000
+  |
+  | Agent API / heartbeat / config pull
+  v
+OpenFlare Agent
+  |
+  v
+Local OpenResty or Docker OpenResty
+  |
+  v
+Origin service
+```

 ## 前置条件

 Server：

-* Go 1.25+
-* Node.js 18+
-* 可写 SQLite 文件目录，或可访问的 PostgreSQL 实例
+| 项目 | 要求 |
+| --- | --- |
+| Go | `1.25+`，仅源码运行需要 |
+| Node.js | `18+`，仅源码构建管理端需要 |
+| 数据库 | 可写 SQLite 文件目录，或可访问的 PostgreSQL 实例 |
+| 端口 | 默认监听 `3000` |

 Agent：

-* Go 1.25+
-* 对 Agent 数据目录有写权限
-* 本机模式下可执行 `openresty -t` 与 `openresty -s reload`
-* Docker 模式下具备 Docker 执行权限
+| 项目 | 要求 |
+| --- | --- |
+| 系统 | 安装脚本支持 Linux 和 macOS；systemd 服务仅在 Linux + systemd 环境创建 |
+| 架构 | `amd64` 或 `arm64` |
+| Docker | 默认 Docker OpenResty 模式需要 |
+| 本机 OpenResty | 仅在显式配置 `openresty_path` 时需要 |
+| 网络 | Agent 节点必须能访问 Server 地址 |

-## Docker Compose 启动 Server
+[需要确认：生产环境推荐的最低 CPU、内存与磁盘容量]

-推荐生产部署使用 PostgreSQL：
+## Docker Compose 部署 Server
+
+创建 `docker-compose.yml`：

 ```yaml
 services:
@@ -48,8 +77,7 @@ services:
    ports:
      - "3000:3000"
    environment:
-      SESSION_SECRET: replace-with-random-string
-      SQLITE_PATH: /data/openflare.db
+      SESSION_SECRET: replace-with-a-long-random-string
      DSN: postgres://openflare:replace-with-strong-password@postgres:5432/openflare?sslmode=disable
      GIN_MODE: release
      LOG_LEVEL: info
@@ -61,8 +89,12 @@ volumes:
  openflare-data:
 ```

+启动：
+
 ```bash
 docker compose up -d
+docker compose ps
+docker compose logs -f openflare
 ```

 首次访问 `http://localhost:3000`，默认账号为 `root` / `123456`。登录后请立即修改默认密码。
@@ -82,78 +114,23 @@ pnpm build

 ```bash
 cd openflare_server
-export SESSION_SECRET='replace-with-random-string'
+export SESSION_SECRET='replace-with-a-long-random-string'
 export SQLITE_PATH='./openflare.db'
 export LOG_LEVEL='info'
 # 可选：设置后优先使用 PostgreSQL。
-# 如果 PostgreSQL 为空且本地 SQLite 文件存在，启动时会自动迁移数据。
 # export DSN='postgres://openflare:secret@127.0.0.1:5432/openflare?sslmode=disable'
 go run .
 ```

-默认监听 `3000` 端口。
-
-## Swagger
-
-登录管理端后访问：
-
-```text
-http://localhost:3000/swagger/index.html
-```
-
-本地重新生成 Swagger：
+默认监听 `3000` 端口。也可以显式指定：

 ```bash
-go install github.com/swaggo/swag/cmd/swag@v1.16.4
-cd openflare_server
-swag init -g main.go -o docs
+go run . --port 3000 --log-dir ./logs
 ```

-## Agent 接入模式
+## Agent 接入

-Agent 支持两种接入模式。
-
-使用节点专属 `agent_token`：
-
-```json
-{
-  "server_url": "http://127.0.0.1:3000",
-  "agent_token": "replace-with-node-auth-token",
-  "data_dir": "./data",
-  "openresty_container_name": "openflare-openresty",
-  "openresty_docker_image": "openresty/openresty:alpine",
-  "openresty_observability_port": 18081,
-  "observability_replay_minutes": 15,
-  "heartbeat_interval": 10000,
-  "request_timeout": 10000
-}
-```
-
-使用全局 `discovery_token`：
-
-```json
-{
-  "server_url": "http://127.0.0.1:3000",
-  "discovery_token": "replace-with-global-discovery-token",
-  "data_dir": "./data",
-  "openresty_container_name": "openflare-openresty",
-  "openresty_docker_image": "openresty/openresty:alpine",
-  "openresty_observability_port": 18081,
-  "observability_replay_minutes": 15,
-  "heartbeat_interval": 10000,
-  "request_timeout": 10000
-}
-```
-
-说明：
-
-* `agent_token` 与 `discovery_token` 至少填写一个。
-* 未配置 `openresty_path` 时默认使用 Docker OpenResty。
-* Agent 会暴露本机观测端口并在 Server 恢复后补传最近窗口数据。
-
-## 一键部署 Agent
-
-使用 `discovery_token`：
+使用 `discovery_token` 自动注册：

 ```bash
 curl -fsSL https://raw.githubusercontent.com/Rain-kl/OpenFlare/main/scripts/install-agent.sh | bash -s -- \
@@ -169,20 +146,25 @@ curl -fsSL https://raw.githubusercontent.com/Rain-kl/OpenFlare/main/scripts/inst
  --agent-token YOUR_AGENT_TOKEN
 ```

-支持参数：
+安装脚本支持参数：

 | 参数 | 说明 |
 | --- | --- |
-| `--server-url` | Server 地址 |
-| `--discovery-token` | 首次自动注册 Token |
-| `--agent-token` | 节点专属 Token |
-| `--install-dir` | 安装目录 |
-| `--repo` | 下载 Agent 的仓库 |
-| `--no-service` | 不创建系统服务 |
+| `--server-url` | Server 地址，必填 |
+| `--discovery-token` | 首次自动注册 Token，与 `--agent-token` 二选一 |
+| `--agent-token` | 节点专属 Token，与 `--discovery-token` 二选一 |
+| `--install-dir` | 安装目录，默认 `/opt/openflare-agent` |
+| `--repo` | 下载 Agent 的 GitHub 仓库，默认 `Rain-kl/OpenFlare` |
+| `--no-service` | 不创建 systemd 服务 |

-安装脚本会下载最新 Agent、生成 `agent.json`、创建 `openflare-agent.service` 并启动服务。
+确认状态：

-## 手动启动 Agent
+```bash
+systemctl status openflare-agent
+journalctl -u openflare-agent -f
+```
+
+## 手动运行 Agent

 源码运行：

@@ -201,42 +183,51 @@ export LOG_LEVEL='info'
 ./openflare-agent -config /path/to/agent.json
 ```

-## 卸载 Agent
+最小 `agent.json` 示例：

-如需彻底卸载 Agent 并清空本地数据：
+```json
+{
+  "server_url": "http://127.0.0.1:3000",
+  "agent_token": "replace-with-node-auth-token",
+  "data_dir": "./data",
+  "heartbeat_interval": 10000,
+  "request_timeout": 10000
+}
+```
+
+未配置 `openresty_path` 时，Agent 会使用 Docker OpenResty。
+
+## 最小联调步骤
+
+1. 启动 Server 并完成首次登录。
+2. 在管理端准备 `agent_token` 或 `discovery_token`。
+3. 启动 Agent，并确认节点在线。
+4. 新增一条启用的网站配置。
+5. 发布并激活新版本。
+6. 查看节点详情和应用记录，确认版本应用成功。
+7. 访问绑定域名或用 `curl` 验证反代结果。
+
+## 升级与卸载
+
+Server：
+
+* Root 用户可在管理端顶栏检查并升级正式版。
+* 如需尝试 preview 版本，可手动检查对应发布。
+* 也可通过上传 Server 二进制的方式执行确认升级。
+
+Agent：
+
+* Agent 默认只跟随正式版自动更新。
+* 安装脚本可重复执行，用于重装或升级 Agent。
+* preview 升级需要手动触发。
+
+卸载 Agent：

 ```bash
 curl -fsSL https://raw.githubusercontent.com/Rain-kl/OpenFlare/main/scripts/uninstall-agent.sh | bash
 ```

-支持参数：
-
-| 参数 | 说明 |
-| --- | --- |
-| `--install-dir` | Agent 安装目录 |
-| `--service-name` | systemd 服务名 |
-
-卸载脚本会先停止 Agent、移除 `openflare-agent.service`、删除整个安装目录，再根据卸载前保存的 `agent.json` 判断 OpenResty 安装方式：
-
-* Docker 模式：删除对应容器，并尝试移除 OpenResty 镜像。
-* 本机 `openresty_path` 模式：不改动本机 OpenResty，仅提示用户手动卸载。
-
-## 最小联调步骤
-
-1. 在管理端准备 `agent_token` 或 `discovery_token`。
-2. 启动 Agent 并确认节点上线。
-3. 新增一条启用中的反代规则。
-4. 生成并激活新版本。
-5. 确认 Agent 拉取配置、执行 `openresty -t`、reload 并上报结果。
-
-预期管理端可看到节点在线状态、节点当前版本、最近一次应用结果，以及自动注册后的专属 `agent_token`。
-
-## 升级说明
-
-* Root 用户可在管理端顶栏检查并升级 Server 正式版。
-* 如需尝试 preview 版本，可手动检查对应发布。
-* 节点 Agent 默认只跟随正式版自动更新；preview 升级需要手动触发。
-* 也可通过上传 Server 二进制的方式执行确认升级。
+卸载脚本会停止 Agent、删除 systemd 服务和安装目录；如果检测到 Docker OpenResty 模式，会尝试移除对应容器和镜像。本机 `openresty_path` 模式不会删除本机 OpenResty。

 ## 常用验证命令

@@ -260,3 +251,11 @@ Frontend：
 cd openflare_server/web
 pnpm build
 ```
+
+Swagger：
+
+```bash
+go install github.com/swaggo/swag/cmd/swag@v1.16.4
+cd openflare_server
+swag init -g main.go -o docs
+```
@@ -0,0 +1,187 @@
+# 本地开发
+
+你会学到：如何搭建 OpenFlare 的本地开发环境、启动 Server、Agent 和管理端前端，运行测试与构建命令，并理解贡献代码前需要遵守的边界。
+
+本页面向贡献者。产品边界、数据模型约束、API 约定和前端分层规范以 [开发约束](../design/development.md) 为准；本页只提供可执行的本地开发流程。
+
+## 仓库结构
+
+| 路径 | 职责 |
+| --- | --- |
+| `openflare_server` | Gin + GORM + SQLite/PostgreSQL 单体控制面 |
+| `openflare_server/web` | Next.js 管理端前端，静态导出后由 Go Server 托管 |
+| `openflare_agent` | Go 单体 Agent，运行在节点侧 |
+| `scripts` | Agent 安装与卸载脚本 |
+| `docs` | VitePress 文档站 |
+
+## 环境要求
+
+| 项目 | 要求 |
+| --- | --- |
+| Go | `1.25+` |
+| Node.js | `18+` |
+| pnpm | 推荐通过 `corepack enable` 使用项目声明版本 |
+| Docker | Agent 默认 Docker OpenResty 模式和本地联调需要 |
+| PostgreSQL | 可选；未配置时 Server 使用 SQLite |
+
+## 初始化前端依赖
+
+```bash
+cd openflare_server/web
+corepack enable
+pnpm install
+```
+
+构建供 Go Server 托管的静态产物：
+
+```bash
+pnpm build
+```
+
+## 启动 Server
+
+SQLite 模式：
+
+```bash
+cd openflare_server
+export SESSION_SECRET='dev-session-secret'
+export SQLITE_PATH='./openflare-dev.db'
+export LOG_LEVEL='debug'
+go run .
+```
+
+PostgreSQL 模式：
+
+```bash
+cd openflare_server
+export SESSION_SECRET='dev-session-secret'
+export DSN='postgres://openflare:secret@127.0.0.1:5432/openflare?sslmode=disable'
+export LOG_LEVEL='debug'
+go run .
+```
+
+默认访问地址：
+
+```text
+http://localhost:3000
+```
+
+默认账号是 `root` / `123456`。
+
+## 启动前端开发服务器
+
+前端开发服务器默认监听 `3001`，并通过 `NEXT_DEV_BACKEND_URL` 代理到后端：
+
+```bash
+cd openflare_server/web
+export NEXT_DEV_BACKEND_URL='http://127.0.0.1:3000'
+pnpm dev
+```
+
+访问：
+
+```text
+http://localhost:3001
+```
+
+## 启动 Agent
+
+创建本地 `agent.json`：
+
+```json
+{
+  "server_url": "http://127.0.0.1:3000",
+  "agent_token": "replace-with-node-auth-token",
+  "data_dir": "./data",
+  "heartbeat_interval": 10000,
+  "request_timeout": 10000
+}
+```
+
+运行：
+
+```bash
+cd openflare_agent
+export LOG_LEVEL='debug'
+go run ./cmd/agent -config ./agent.json
+```
+
+未配置 `openresty_path` 时，Agent 会使用 Docker OpenResty。调试本机 OpenResty 时，显式配置 `openresty_path`、`main_config_path`、`route_config_path`、`cert_dir` 和 `lua_dir`。
+
+## 测试
+
+Server：
+
+```bash
+cd openflare_server
+GOCACHE=/tmp/openflare-go-cache go test ./...
+```
+
+Agent：
+
+```bash
+cd openflare_agent
+GOCACHE=/tmp/openflare-go-cache go test ./...
+```
+
+Frontend：
+
+```bash
+cd openflare_server/web
+pnpm lint
+pnpm typecheck
+pnpm test
+pnpm test:e2e
+```
+
+Docs：
+
+```bash
+cd docs
+pnpm build
+```
+
+## 构建
+
+管理端静态产物：
+
+```bash
+cd openflare_server/web
+pnpm build
+```
+
+Server 二进制：
+
+```bash
+cd openflare_server
+go build -o openflare-server .
+```
+
+Agent 二进制：
+
+```bash
+cd openflare_agent
+go build -o openflare-agent ./cmd/agent
+```
+
+## 调试入口
+
+| 场景 | 命令或位置 |
+| --- | --- |
+| Server 日志 | `LOG_LEVEL=debug go run .` |
+| Agent 日志 | `LOG_LEVEL=debug go run ./cmd/agent -config ./agent.json` |
+| Swagger | `http://localhost:3000/swagger/index.html` |
+| 前端 API 代理 | `NEXT_DEV_BACKEND_URL=http://127.0.0.1:3000 pnpm dev` |
+| Docker OpenResty 容器 | `docker ps --filter name=openflare-openresty` |
+
+## 代码风格与变更准入
+
+贡献前先确认：
+
+1. 需求符合 [产品边界](../design/index.md)。
+2. 实现符合 [开发约束](../design/development.md)。
+3. 不破坏发布、同步、回滚或升级主链路。
+4. 涉及配置、部署、API 或产品边界时同步更新文档。
+5. 风险较高的修改补充测试或等效联调验证。
+
+数据库结构变更必须提升数据库版本号，并补充从上一版本到新版本的显式迁移方法和校验逻辑。
@@ -1,6 +1,20 @@
 # 发布第一份配置

-OpenFlare 的发布链路以完整配置版本为中心。你修改网站配置后，需要生成新版本并激活，Agent 才会在后续 heartbeat 中拉取并应用。
+你会学到：如何创建第一条网站配置、绑定源站与证书、发布配置版本，并确认 Agent 已经应用。
+
+OpenFlare 的发布链路以完整配置版本为中心。你在管理端修改网站配置后，需要发布并激活新版本，Agent 才会在后续 heartbeat 中拉取并应用。
+
+## 发布前检查
+
+确认以下条件已经满足：
+
+| 项目 | 期望 |
+| --- | --- |
+| Server | 可以登录管理端 |
+| Agent | 至少一个节点在线 |
+| 源站 | Agent 节点可以访问源站地址 |
+| 域名 | 域名已经解析到 OpenResty 节点，或准备通过本地 hosts / curl Host 头验证 |
+| HTTPS | 如需 HTTPS，证书已上传或托管 |

 ## 创建网站配置

@@ -8,11 +22,19 @@ OpenFlare 的发布链路以完整配置版本为中心。你修改网站配置

 | 字段 | 说明 |
 | --- | --- |
-| 网站名称 | 业务唯一标识；未显式填写时默认使用主域名 |
+| 网站名称 | 业务唯一标识；未显式填写时可使用主域名 |
 | 域名 | 至少一个域名，第一项视为主域名 |
 | 源站地址 | 合法的 `http://` 或 `https://` 上游地址 |
 | 启用状态 | 只有启用的网站配置会参与发布渲染 |

+示例：
+
+| 字段 | 示例 |
+| --- | --- |
+| 网站名称 | `app` |
+| 域名 | `app.example.com` |
+| 源站地址 | `http://10.0.0.20:8080` |
+
 同一个域名只能属于一个网站配置。同一网站内的流量限制、反向代理和缓存配置按站点共享。

 ## 绑定证书
@@ -26,7 +48,7 @@ HTTPS 证书按域名绑定。没有绑定证书的域名不会被自动放入 `
 标准链路：

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

 发布时 Server 会读取全部启用的网站配置、OpenResty 主配置模板、性能参数与缓存参数，渲染完整 OpenResty 配置，计算 `checksum`，写入 `config_versions`，再切换激活版本。
@@ -42,4 +64,37 @@ HTTPS 证书按域名绑定。没有绑定证书的域名不会被自动放入 `
 | 应用记录 | 最近一次应用成功 |
 | 版本页面 | 新版本处于激活状态 |

+在节点上确认 Agent 日志：
+
+```bash
+journalctl -u openflare-agent -n 100 --no-pager
+```
+
+用域名访问：
+
+```bash
+curl -I http://app.example.com
+```
+
+如果域名还没有正式解析，可以临时指定 Host 头访问节点 IP：
+
+```bash
+curl -I -H 'Host: app.example.com' http://NODE_IP
+```
+
+HTTPS 验证：
+
+```bash
+curl -I https://app.example.com
+```
+
+## 回滚
+
 如果目标版本应用失败并回滚，Agent 会在本地阻断同一 `version + checksum` 的重复应用，直到控制面激活版本或 checksum 发生变化。
+
+回滚到旧版本：
+
+1. 打开配置版本页面。
+2. 找到上一个确认可用的历史版本。
+3. 重新激活该版本。
+4. 查看节点应用记录，确认 Agent 应用成功。
@@ -1,15 +1,36 @@
 # 指南

-本部分面向使用者和部署者，帮助你把 OpenFlare 从首次启动推进到第一份可运行的代理配置。
+你会学到：OpenFlare 文档如何组织、首次运行应该读哪些页面，以及部署、使用、排查和开发分别从哪里开始。

-推荐阅读顺序：
+OpenFlare 是一套自托管的 OpenResty 控制面。它把反向代理网站配置、配置版本发布、Agent 节点同步、TLS 证书和基础观测放到一个管理端中，适合单团队或单组织管理多台代理节点。

-1. [快速开始](./quick-start.md)：用 Docker Compose 启动 Server，并完成首次登录。
-2. [部署说明](./deployment.md)：查看生产部署、Agent 一键安装、联调与升级。
-3. [SSO 登录配置](./sso.md)：配置 GitHub OAuth 或标准 OIDC 登录入口。
-4. [启动 Server](./server.md)：了解源码启动、前端构建和 Swagger 入口。
-5. [接入 Agent](./agent.md)：选择 `agent_token` 或 `discovery_token`，让节点上线。
-6. [发布第一份配置](./first-site.md)：创建网站配置，发布并确认节点应用。
-7. [升级与维护](./upgrade.md)：了解升级、卸载、验证和日常维护入口。
+## 推荐阅读路径

-如果你要参与开发，先阅读 [设计](../design/) 与 [开发约束](../design/development.md)，再进入代码修改。
+如果你第一次接触 OpenFlare，按下面顺序阅读：
+
+1. [快速开始](./quick-start.md)：用 Docker Compose 启动 Server，登录管理端，并接入第一个 Agent。
+2. [基础使用](./usage.md)：了解网站配置、源站、证书、发布、回滚和观测的常见操作。
+3. [部署说明](./deployment.md)：把 Server 和 Agent 放到更接近生产的环境中运行。
+4. [配置项参考](../reference/configuration.md)：查 Server 环境变量、运行时 Option 和 Agent 配置字段。
+5. [故障排查](./troubleshooting.md)：按症状排查登录、数据库、节点同步、OpenResty 应用和前端构建问题。
+
+## 按角色查找
+
+| 你想做什么 | 推荐入口 |
+| --- | --- |
+| 5 分钟内跑起管理端 | [快速开始](./quick-start.md) |
+| 发布第一条反向代理配置 | [发布第一份配置](./first-site.md) |
+| 接入或重装节点 Agent | [接入 Agent](./agent.md) |
+| 从源码启动 Server | [启动 Server](./server.md) |
+| 配置 GitHub 或 OIDC 登录 | [SSO 登录配置](./sso.md) |
+| 升级 Server 或 Agent | [升级与维护](./upgrade.md) |
+| 参与开发或修复问题 | [本地开发](./development.md) 与 [开发约束](../design/development.md) |
+| 理解架构和发布模型 | [系统架构](../design/architecture.md) 与 [发布模型](../design/release-model.md) |
+
+## 文档分区
+
+`guide/` 面向使用者和部署者，提供从安装到日常操作的可执行步骤。
+
+`reference/` 收敛稳定事实，例如配置字段、命令、API 响应约定和仓库结构。
+
+`design/` 面向维护者和贡献者，描述产品边界、系统架构、发布模型和工程约束。新增能力或改变边界前，应先更新对应设计文档。
@@ -1,10 +1,30 @@
 # 快速开始

-OpenFlare 的最小运行单元包含一个 Server 和至少一个 Agent。Server 负责管理端、配置版本与节点状态，Agent 运行在代理节点上，负责写入 OpenResty 配置并 reload。
+你会学到：如何用 Docker Compose 启动 OpenFlare Server、完成首次登录、接入第一个 Agent，并验证一份配置是否已经发布到节点。

-## 启动 Server
+OpenFlare 的最小运行单元包含：

-推荐使用 PostgreSQL 与 Docker Compose：
+| 组件 | 职责 |
+| --- | --- |
+| Server | 管理端 UI、管理 API、Agent API、配置渲染、版本发布与状态存储 |
+| Agent | 运行在代理节点上，拉取配置、写入 OpenResty、执行校验与 reload |
+| OpenResty | 实际接收流量并反向代理到源站 |
+
+默认情况下，Agent 未配置 `openresty_path` 时会使用 Docker OpenResty。因此快速开始建议在 Agent 节点准备 Docker。
+
+## 环境要求
+
+| 项目 | 要求 |
+| --- | --- |
+| Docker / Docker Compose | 用于启动 Server 和 PostgreSQL，也用于 Agent 默认的 Docker OpenResty 模式 |
+| 可访问端口 | Server 默认监听 `3000`，Agent 节点需要能访问 Server 地址 |
+| 浏览器 | 用于访问管理端 |
+
+[需要确认：项目建议的最低 Docker 与 Docker Compose 版本]
+
+## 1. 启动 Server
+
+在空目录中创建 `docker-compose.yml`：

 ```yaml
 services:
@@ -32,7 +52,7 @@ services:
    ports:
      - "3000:3000"
    environment:
-      SESSION_SECRET: replace-with-random-string
+      SESSION_SECRET: replace-with-a-long-random-string
      DSN: postgres://openflare:replace-with-strong-password@postgres:5432/openflare?sslmode=disable
      GIN_MODE: release
      LOG_LEVEL: info
@@ -41,11 +61,24 @@ volumes:
  postgres-data:
 ```

+启动服务：
+
 ```bash
 docker compose up -d
 ```

-访问 `http://localhost:3000`。
+确认容器已经运行：
+
+```bash
+docker compose ps
+docker compose logs -f openflare
+```
+
+看到 `server listening` 且 `openflare` 容器状态为 running 后，访问：
+
+```text
+http://localhost:3000
+```

 默认账号：

@@ -53,11 +86,24 @@ docker compose up -d
 | --- | --- |
 | `root` | `123456` |

-首次登录后请立即修改默认密码，并按需关闭新用户注册。
+首次登录后请立即修改默认密码。

-## 接入第一个节点
+## 2. 准备 Agent Token

-在管理端准备 `discovery_token` 或节点专属 `agent_token`，然后在节点上执行安装脚本。
+Agent 可以用两类凭证接入：
+
+| 凭证 | 适用场景 |
+| --- | --- |
+| `discovery_token` | 首次自动注册节点，由 Server 换成节点专属 Token |
+| `agent_token` | 已经在管理端创建或分配节点，直接使用节点专属 Token |
+
+在管理端准备其中一种凭证后，进入下一步。
+
+[需要确认：当前管理端中创建或查看 `discovery_token` 与节点 `agent_token` 的准确菜单路径]
+
+## 3. 安装 Agent
+
+在代理节点上执行安装脚本。

 使用 `discovery_token`：

@@ -75,13 +121,64 @@ curl -fsSL https://raw.githubusercontent.com/Rain-kl/OpenFlare/main/scripts/inst
  --agent-token YOUR_AGENT_TOKEN
 ```

-安装脚本默认把 Agent 放在 `/opt/openflare-agent`，创建 `openflare-agent.service`，并在未显式配置本机 OpenResty 时使用 Docker OpenResty。
+脚本默认会：

-## 发布第一份配置
+| 项目 | 默认值 |
+| --- | --- |
+| 安装目录 | `/opt/openflare-agent` |
+| 配置文件 | `/opt/openflare-agent/agent.json` |
+| systemd 服务 | `openflare-agent.service` |
+| OpenResty 模式 | 未配置 `openresty_path` 时使用 Docker OpenResty |

-1. 在管理端新增网站配置，填写域名与源站地址。
-2. 发布前查看预览或变更摘要。
-3. 激活新版本。
-4. 等待 Agent 通过 heartbeat 发现版本变更并应用。
+确认 Agent 服务状态：
+
+```bash
+systemctl status openflare-agent
+journalctl -u openflare-agent -f
+```
+
+如果没有 systemd，脚本会输出手动启动命令。
+
+## 4. 发布第一份配置
+
+在管理端完成以下操作：
+
+1. 新增网站配置，填写网站名称、域名和源站地址。
+2. 确认网站配置处于启用状态。
+3. 发布前查看预览或变更摘要。
+4. 发布并激活新版本。
+5. 等待 Agent 在后续 heartbeat 中发现版本并应用。

 版本号格式为 `YYYYMMDD-NNN`。历史版本不可变，回滚通过重新激活旧版本完成。
+
+## 5. 验证是否成功
+
+在管理端确认：
+
+| 位置 | 期望结果 |
+| --- | --- |
+| 节点列表 | Agent 节点在线 |
+| 节点详情 | 当前版本与激活版本一致 |
+| 应用记录 | 最近一次应用成功 |
+| 版本页面 | 新版本处于激活状态 |
+
+在 Agent 节点确认：
+
+```bash
+journalctl -u openflare-agent -n 100 --no-pager
+docker ps --filter name=openflare-openresty
+```
+
+如果使用 Docker OpenResty，默认容器名是 `openflare-openresty`。
+
+## 常见失败原因
+
+| 现象 | 排查方向 |
+| --- | --- |
+| 浏览器打不开管理端 | 确认 `docker compose ps` 中 Server 正在运行，宿主机 `3000` 端口没有被占用 |
+| 登录后数据无法保存 | 检查 PostgreSQL 容器健康状态，以及 `DSN` 中的用户名、密码、库名是否一致 |
+| Agent 无法注册 | 确认 Agent 节点能访问 `--server-url`，并检查 Token 是否填错或已失效 |
+| Agent 在线但没有应用配置 | 确认网站配置已启用，并且已经发布并激活版本 |
+| OpenResty 应用失败 | 查看节点应用记录和 `journalctl -u openflare-agent`，重点检查域名、证书、上游地址和端口占用 |
+
+更多排查路径见 [故障排查](./troubleshooting.md)。
@@ -1,19 +1,24 @@
 # 启动 Server

-OpenFlare Server 是 Gin + GORM 单体控制面，负责管理端 UI、管理 API、Agent API、配置渲染、版本发布与状态存储。
+你会学到：如何从源码构建管理端前端、启动 OpenFlare Server、选择 SQLite 或 PostgreSQL，并访问 Swagger。
+
+OpenFlare Server 是 Gin + GORM 单体控制面，负责管理端 UI、管理 API、Agent API、配置渲染、版本发布、数据存储与聚合查询。

 ## 前置条件

 | 项目 | 要求 |
-| --- |-----------------------------------|
+| --- | --- |
 | Go | `1.25+` |
 | Node.js | `18+` |
+| pnpm | 推荐通过 `corepack enable` 使用项目声明的 pnpm |
 | 数据库 | SQLite 文件目录可写，或可访问的 PostgreSQL 实例 |

 生产环境建议显式配置 `SESSION_SECRET`，并优先使用 PostgreSQL。

 ## 构建管理端前端

+Go Server 会托管 `openflare_server/web/build` 中的静态产物。源码启动前先构建前端：
+
 ```bash
 cd openflare_server/web
 corepack enable
@@ -21,34 +26,67 @@ pnpm install
 pnpm build
 ```

-`pnpm build` 会生成供 Go Server 托管的静态产物。
+常用前端检查：

-## 源码启动
+```bash
+pnpm lint
+pnpm typecheck
+pnpm test
+```
+
+## 使用 SQLite 启动

 ```bash
 cd openflare_server
-export SESSION_SECRET='replace-with-random-string'
+export SESSION_SECRET='replace-with-a-long-random-string'
 export SQLITE_PATH='./openflare.db'
 export LOG_LEVEL='info'
-# 可选：设置后优先使用 PostgreSQL。
-# export DSN='postgres://openflare:secret@127.0.0.1:5432/openflare?sslmode=disable'
 go run .
 ```

-默认监听 `3000` 端口。也可以通过命令行指定：
+默认监听 `3000` 端口，访问：
+
+```text
+http://localhost:3000
+```
+
+## 使用 PostgreSQL 启动
+
+```bash
+cd openflare_server
+export SESSION_SECRET='replace-with-a-long-random-string'
+export DSN='postgres://openflare:secret@127.0.0.1:5432/openflare?sslmode=disable'
+export LOG_LEVEL='info'
+go run .
+```
+
+`DSN` 设置后优先于 SQLite。`DSN` 与兼容旧命名的 `SQL_DSN` 同时存在时，优先使用 `DSN`。
+
+如果目标 PostgreSQL 数据库为空且本地 `SQLITE_PATH` 文件存在，Server 启动阶段会尝试把 SQLite 数据迁移到 PostgreSQL，并在日志中输出迁移进度。
+
+## 命令行参数

 ```bash
 go run . --port 3000 --log-dir ./logs
 ```

+| 参数 | 作用 | 默认值 |
+| --- | --- | --- |
+| `--port` | 指定 Server 监听端口 | `3000` |
+| `--log-dir` | 指定日志目录 | 空，输出到标准输出 |
+| `--version` | 输出版本后退出 | `false` |
+| `--help` | 输出帮助后退出 | `false` |
+
 ## 首次登录

-访问 `http://localhost:3000`。
+默认账号：

 | 用户名 | 密码 |
 | --- | --- |
 | `root` | `123456` |

+首次登录后请立即修改默认密码。
+
 ## Swagger

 登录管理端后访问：
@@ -57,10 +95,12 @@ go run . --port 3000 --log-dir ./logs
 http://localhost:3000/swagger/index.html
 ```

-如需在本地重新生成 Swagger 文档：
+本地重新生成 Swagger：

 ```bash
 go install github.com/swaggo/swag/cmd/swag@v1.16.4
 cd openflare_server
 swag init -g main.go -o docs
 ```
+
+Swagger 生成文件位于 `openflare_server/docs`。
@@ -1,5 +1,7 @@
 # SSO 登录配置

+你会学到：如何为 OpenFlare 配置 GitHub OAuth 或标准 OIDC 登录入口，如何填写回调地址，以及第三方账号如何绑定本地用户。
+
 OpenFlare 支持通过认证源配置第三方登录入口。当前支持 GitHub OAuth 与标准 OIDC Provider，例如 Logto、authentik、Keycloak、Casdoor 等。

 认证源配置完成并启用后，会显示在登录页的第三方账号登录区域。用户可以通过第三方账号登录，也可以在已登录状态下把第三方账号绑定到当前本地账号。
@@ -0,0 +1,226 @@
+# 故障排查
+
+你会学到：如何按症状排查 OpenFlare Server、数据库、登录、Agent、OpenResty、配置发布和前端构建问题。
+
+排查时先确认问题发生在哪一层：浏览器、Server、数据库、Agent、OpenResty、源站或 DNS。OpenFlare 的配置不会直接在线写入所有节点，只有激活版本变化后，Agent 才会在 heartbeat 中发现并应用。
+
+## 快速定位
+
+| 现象 | 先看哪里 |
+| --- | --- |
+| 管理端打不开 | Server 容器或进程日志、端口监听 |
+| 登录异常 | 默认账号、Session Secret、浏览器请求、Server 日志 |
+| 数据无法保存 | 数据库连接、SQLite 文件权限、PostgreSQL 健康状态 |
+| Agent 离线 | Agent 日志、Token、Server 地址、网络连通性 |
+| 发布后节点未更新 | 激活版本、节点 heartbeat、应用记录 |
+| OpenResty 应用失败 | 应用记录、Agent 日志、证书、上游地址、端口占用 |
+| 访问分析无数据 | OpenResty 容器状态、观测端口、Agent 补报日志 |
+
+## Server 无法启动
+
+1. 查看日志：
+
+```bash
+docker compose logs -n 200 openflare
+```
+
+源码运行时查看终端输出。
+
+2. 检查端口占用：
+
+```bash
+lsof -i :3000
+```
+
+3. 如果使用 PostgreSQL，确认数据库健康：
+
+```bash
+docker compose ps postgres
+docker compose logs -n 100 postgres
+```
+
+4. 如果使用 SQLite，确认数据库文件目录可写：
+
+```bash
+ls -ld "$(dirname /path/to/openflare.db)"
+```
+
+常见原因：
+
+| 日志或现象 | 处理 |
+| --- | --- |
+| 数据库连接失败 | 检查 `DSN` 中用户名、密码、主机、端口、库名和 `sslmode` |
+| SQLite 无法创建文件 | 检查 `SQLITE_PATH` 所在目录是否存在且可写 |
+| 端口被占用 | 修改 `PORT` 或 `--port`，或停止占用端口的进程 |
+
+## 管理端打不开或空白
+
+1. 确认 Server 正在监听：
+
+```bash
+curl -I http://127.0.0.1:3000
+```
+
+2. 如果是源码运行，确认已经构建前端静态产物：
+
+```bash
+cd openflare_server/web
+pnpm build
+```
+
+3. 检查浏览器访问地址是否与反向代理配置一致。
+
+4. 如果通过前端开发服务器访问，确认后端代理地址：
+
+```bash
+cd openflare_server/web
+NEXT_DEV_BACKEND_URL=http://127.0.0.1:3000 pnpm dev
+```
+
+## 默认账号无法登录
+
+默认账号是 `root` / `123456`。首次登录后如果已经修改密码，应使用修改后的密码。
+
+排查步骤：
+
+1. 确认连接的是预期数据库，避免 `SQLITE_PATH` 或 `DSN` 指向了另一个环境。
+2. 查看 Server 日志中使用的是 `sqlite` 还是 `postgres`。
+3. 如果部署在多副本或反向代理后，确认 `SESSION_SECRET` 固定且各实例一致。
+4. 清理浏览器 Cookie 后重新登录。
+
+[需要确认：当前项目是否提供安全的 root 密码重置命令或流程]
+
+## Agent 无法注册或一直离线
+
+在 Agent 节点执行：
+
+```bash
+curl -I http://your-server:3000
+```
+
+查看 Agent 日志：
+
+```bash
+journalctl -u openflare-agent -n 200 --no-pager
+```
+
+检查配置文件：
+
+```bash
+sed -n '1,160p' /opt/openflare-agent/agent.json
+```
+
+重点确认：
+
+| 配置 | 说明 |
+| --- | --- |
+| `server_url` | 必须是 Agent 节点能访问的 Server 地址 |
+| `agent_token` / `discovery_token` | 至少填写一个 |
+| `heartbeat_interval` | 支持毫秒整数或 Go duration 字符串 |
+| `request_timeout` | 网络较慢时可适当增大 |
+
+如果日志提示 Token 无效，重新在管理端准备 Token 并更新 `agent.json`，然后重启：
+
+```bash
+systemctl restart openflare-agent
+```
+
+## 发布后节点没有应用新版本
+
+按顺序检查：
+
+1. 版本页面中是否已经激活目标版本。
+2. 节点是否在线，最近心跳时间是否更新。
+3. 应用记录中是否有目标版本的成功、警告或失败记录。
+4. 网站配置是否启用；未启用的网站不会参与发布渲染。
+5. Agent 日志是否出现拉取、校验、reload 或回滚信息。
+
+查看 Agent 日志：
+
+```bash
+journalctl -u openflare-agent -f
+```
+
+注意：某个目标 `version + checksum` 一旦应用失败并回退，Agent 会在本地状态中阻断该目标重复应用。修正配置后需要重新发布生成新的 checksum，或激活旧版本回滚。
+
+## OpenResty 应用失败
+
+常见原因：
+
+| 原因 | 排查 |
+| --- | --- |
+| 域名或 server 块冲突 | 检查同一域名是否被多个网站配置使用 |
+| 上游地址不合法 | 确认所有上游都是 `http://` 或 `https://` |
+| 多上游格式不符合约束 | 多上游必须是纯 `scheme://host[:port]` |
+| 证书缺失或路径错误 | 检查域名是否绑定证书，以及 Agent 证书目录是否可写 |
+| 端口被占用 | 检查本机或 Docker 容器的 `80`、`443` 端口 |
+
+Docker OpenResty 模式：
+
+```bash
+docker ps --filter name=openflare-openresty
+docker logs --tail 100 openflare-openresty
+```
+
+本机 OpenResty 模式：
+
+```bash
+/usr/local/openresty/nginx/sbin/nginx -t
+```
+
+实际路径以 `agent.json` 中的 `openresty_path` 为准。
+
+## HTTPS 不生效
+
+1. 确认证书已经上传或托管。
+2. 确认网站配置中对应域名已经绑定证书。
+3. 确认发布并激活了新版本。
+4. 查看应用记录是否成功。
+5. 用 `curl` 查看证书和状态码：
+
+```bash
+curl -Iv https://your-domain
+```
+
+没有绑定证书的域名不会被自动加入 HTTPS 配置，这是预期行为。
+
+## 访问分析没有数据
+
+1. 确认节点已经成功应用包含观测 Lua 资源的配置。
+2. 确认 Docker OpenResty 容器或本机 OpenResty 正在运行。
+3. 查看 Agent 日志是否有观测采集或补报失败信息。
+4. 检查 `openresty_observability_port` 是否被占用，默认是 `18081`。
+5. 确认 Server 侧没有因数据库清理策略删除对应时间窗口数据。
+
+## 前端构建失败
+
+执行：
+
+```bash
+cd openflare_server/web
+corepack enable
+pnpm install
+pnpm lint
+pnpm typecheck
+pnpm test
+pnpm build
+```
+
+常见原因：
+
+| 现象 | 处理 |
+| --- | --- |
+| pnpm 版本不一致 | 使用 `corepack enable` 后重新安装 |
+| 类型错误 | 先运行 `pnpm typecheck` 定位具体文件 |
+| API 类型不一致 | 检查 `lib/api/` 和 `types/` 中的响应结构 |
+| E2E 失败 | 确认 Server 和前端开发服务器都已启动 |
+
+## 文档站构建失败
+
+```bash
+cd docs
+pnpm install
+pnpm build
+```
+
+如果是链接错误，检查新增页面是否已经加入 `docs/config.ts` 侧边栏，或者相对链接是否指向存在的 Markdown 文件。
@@ -1,11 +1,24 @@
 # 升级与维护

+你会学到：如何升级 Server 与 Agent、如何清理观测数据，以及维护前后应该执行哪些验证命令。
+
+升级前建议先确认当前激活版本、最近一次 Agent 应用结果和数据库备份策略。生产环境不要在发布配置、Agent 大规模重连或数据库迁移进行中同时升级。
+
 ## Server 升级

 Root 用户可以在管理端顶栏检查并升级 Server 正式版。也可以通过上传 Server 二进制的方式执行确认升级。

 如需尝试 preview 版本，可手动检查对应发布。生产环境建议优先使用正式版。

+升级后确认：
+
+```bash
+docker compose ps
+docker compose logs -n 100 openflare
+```
+
+如果是源码部署，重新启动 Server 后确认日志中没有数据库迁移或启动错误。
+
 ## Agent 升级

 节点 Agent 默认只跟随正式版自动更新。preview 升级需要手动触发。
@@ -18,6 +31,15 @@ curl -fsSL https://raw.githubusercontent.com/Rain-kl/OpenFlare/main/scripts/inst
  --agent-token YOUR_AGENT_TOKEN
 ```

+注意：当前安装脚本重装时会删除整个安装目录，包括旧 `agent.json`、本地状态、缓存数据和下载的二进制。执行前请确认手头仍有可用 Token。
+
+升级后确认：
+
+```bash
+systemctl status openflare-agent
+journalctl -u openflare-agent -n 100 --no-pager
+```
+
 ## 数据维护

 管理端设置页可以维护观测数据自动清理策略：
@@ -49,5 +71,15 @@ Frontend：

 ```bash
 cd openflare_server/web
+pnpm lint
+pnpm typecheck
+pnpm test
+pnpm build
+```
+
+Docs：
+
+```bash
+cd docs
 pnpm build
 ```
@@ -0,0 +1,136 @@
+# 基础使用
+
+你会学到：OpenFlare 中网站配置、源站、证书、版本、节点和观测分别是什么，以及日常使用时应按什么顺序操作。
+
+OpenFlare 不直接在线修改节点上的 Nginx/OpenResty 配置。你在管理端修改的是控制面数据；只有发布并激活新版本后，Agent 才会拉取完整配置并应用到节点。
+
+## 核心概念
+
+| 概念 | 说明 |
+| --- | --- |
+| 网站配置 | 反向代理配置的聚合对象，一条网站配置可以绑定一个或多个域名 |
+| 主域名 | `domains` 列表中的第一个域名，用作该网站的主要展示域名 |
+| 源站 | 被反向代理访问的上游地址，例如 `http://10.0.0.10:8080` |
+| 配置版本 | 一次发布生成的完整 OpenResty 配置快照，历史版本不可变 |
+| 激活版本 | 当前全局生效的配置版本，所有节点默认消费同一份激活版本 |
+| Agent | 节点侧进程，负责注册、心跳、同步、校验、reload 和失败回滚 |
+
+## 推荐操作顺序
+
+日常发布一条反向代理配置时，推荐按这个顺序：
+
+1. 确认至少有一个 Agent 节点在线。
+2. 新增或选择源站地址。
+3. 新增网站配置，填写域名、源站和站点级配置。
+4. 如需 HTTPS，上传或选择证书，并按域名绑定。
+5. 预览配置或查看变更摘要。
+6. 发布并激活新版本。
+7. 在节点详情和应用记录中确认应用结果。
+
+## 创建网站配置
+
+网站配置至少需要：
+
+| 字段 | 要求 |
+| --- | --- |
+| 网站名称 | 业务唯一标识；未显式填写时通常可使用主域名 |
+| 域名 | 至少一个域名，第一项为主域名；任一域名全局只能属于一个网站 |
+| 源站地址 | 合法的 `http://` 或 `https://` 地址 |
+| 启用状态 | 只有启用的网站配置会参与发布渲染 |
+
+示例：
+
+| 字段 | 示例 |
+| --- | --- |
+| 网站名称 | `docs` |
+| 域名 | `docs.example.com` |
+| 源站地址 | `http://10.0.0.10:8080` |
+| 回源 Host | `docs.internal.example.com` |
+
+上游地址规则：
+
+* 单上游可以携带 base path 或 query，例如 `https://app.example.com/base?from=openflare`。
+* 多上游用于负载均衡时，每个上游必须是纯 `scheme://host[:port]`。
+* 多上游在同一规则内应使用一致协议。
+
+## 管理源站
+
+源站是轻量目录，用来复用常见上游地址。网站配置关联源站后，仍会保存可渲染的 `origin_url` 快照，确保历史配置版本可以独立回放。
+
+推荐做法：
+
+* 把经常复用的内部服务地址维护为源站。
+* 修改源站目录后，检查已发布的网站配置是否需要同步更新源站快照。
+* 发布前使用预览或 diff 确认渲染结果。
+
+## 启用 HTTPS
+
+HTTPS 按域名绑定证书，而不是按整个网站统一强制启用。
+
+操作顺序：
+
+1. 在证书管理中上传或托管证书。
+2. 进入网站配置，为需要 HTTPS 的域名选择证书。
+3. 未绑定证书的域名会保留 HTTP，不会被自动放入 `443 ssl` server 块。
+4. 发布并激活新版本。
+
+如果一个网站包含多个域名，Server 发布时会按证书分组渲染 HTTPS 配置，同时保持这些域名属于同一份网站快照。
+
+## 发布、激活与回滚
+
+标准链路：
+
+```text
+修改配置 -> 预览 / diff -> 发布 -> 生成完整版本 -> 激活版本 -> Agent 拉取 -> 本地应用 -> 上报结果
+```
+
+发布时 Server 会读取全部启用的网站配置、OpenResty 主配置模板、性能参数、缓存参数和证书资源，生成完整配置并计算 `checksum`。
+
+回滚不是修改历史版本，而是重新激活旧版本。Agent 发现激活版本变化后，会按普通同步流程拉取并应用。
+
+## 查看节点与观测
+
+节点页面适合回答三个问题：
+
+| 问题 | 查看位置 |
+| --- | --- |
+| 节点是否在线 | 节点列表或节点详情 |
+| 当前运行哪个版本 | 节点详情中的当前版本 |
+| 最近一次应用是否成功 | 应用记录 |
+
+访问分析和资源快照用于基础观测。OpenFlare 只保留受控时间窗口内的访问明细，不定位为通用日志平台。如果需要长期日志检索，应接入独立日志系统。
+
+## 常见场景
+
+### 新增一个内部服务反代
+
+1. 确认源站服务可从 Agent 节点访问。
+2. 在管理端新增网站配置。
+3. 填写域名，例如 `app.example.com`。
+4. 填写源站，例如 `http://10.0.0.20:8080`。
+5. 发布并激活版本。
+6. 在 Agent 节点或浏览器访问域名验证。
+
+### 给已有域名启用 HTTPS
+
+1. 准备覆盖该域名的证书。
+2. 在证书管理中上传或创建证书记录。
+3. 回到网站配置，为对应域名选择证书。
+4. 发布并激活版本。
+5. 用浏览器或 `curl -I https://your-domain` 验证证书链和状态码。
+
+### 回滚一次失败发布
+
+1. 打开配置版本页面。
+2. 找到上一个已知可用版本。
+3. 重新激活该版本。
+4. 查看节点应用记录，确认 Agent 已应用旧版本。
+5. 修正配置后再发布新版本。
+
+## 推荐实践
+
+* 生产环境显式配置 `SESSION_SECRET`，并优先使用 PostgreSQL。
+* 修改网站配置后先看预览或 diff，再发布。
+* 每次发布后检查节点详情与应用记录。
+* 多节点部署时保持 Agent 到 Server 的网络路径稳定。
+* 不在节点上手动修改 OpenFlare 托管的 OpenResty 配置文件；下次发布会覆盖这些文件。
@@ -0,0 +1,86 @@
+# Agent Unified OpenResty Binary Control Scheme
+
+# Agent 统一 OpenResty 二进制控制方案
+
+## Summary
+
+将 Agent 运行模型统一为“写入受管配置文件，然后调用 `openresty` 二进制执行 `-t`、reload、start/restart”。Docker 部署不再由 Agent 控制另一个 OpenResty 容器，而是提供独立的 `ghcr.io/rain-kl/openflare-agent` 镜像；该镜像基于 `openresty/openresty`，内置 Agent 控制器和 OpenResty 二进制。
+
+## Key Changes
+
+- Agent runtime：
+    - 移除生产路径中的 DockerExecutor / Docker 容器管理逻辑。
+    - `openresty_path` 未配置时默认使用 `openresty`。
+    - 二进制执行统一带 `-c <main_config_path>`，避免误读 OpenResty 默认配置。
+    - apply 流程为：备份 -> 写入文件 -> `openresty -t -c ...` -> reload；若 reload 表明未运行，则 start。
+    - restart 使用 `openresty -c ... -s quit` 后再 `openresty -c ...` 启动，保留缺失 PID 的容错。
+
+- 配置与文件职责：
+    - 保留旧字段 `openresty_container_name`、`openresty_docker_image`、`docker_binary` 的解析兼容，但标记废弃且不再参与控制逻辑。
+    - 新增 `access_log_path`，默认 `data_dir/var/log/openflare/access.log`，不再把访问日志放进 `conf.d`。
+    - 新增 `runtime_config_dir`，默认 `data_dir/etc/openflare`，`pow_config.json` 写入这里。
+    - `cert_dir` 只写证书/密钥文件；`lua_dir` 只写 Lua 代码与静态资源。
+    - 支持文件写入前先拆分：证书文件进入 `cert_dir`，`pow_config.json` 进入 `runtime_config_dir`。
+
+- Docker Agent 镜像：
+    - 新增 `openflare_agent/Dockerfile`，运行镜像基于 `openresty/openresty:alpine`。
+    - 默认 `OPENFLARE_OPENRESTY_PATH=openresty`、`OPENFLARE_DATA_DIR=/data`。
+    - 暴露 `80`、`443`、`18081`。
+    - 支持挂载 `/etc/openflare/agent.json`，也支持环境变量配置。
+    - CI 发布独立多架构镜像：`ghcr.io/rain-kl/openflare-agent:<version>` 和 `latest`。
+
+- Agent 配置入口：
+    - 保留 `-config` + `agent.json`。
+    - 新增环境变量覆盖/兜底：`OPENFLARE_SERVER_URL`、`OPENFLARE_AGENT_TOKEN`、`OPENFLARE_DISCOVERY_TOKEN`、`OPENFLARE_NODE_NAME`、`OPENFLARE_NODE_IP`、`OPENFLARE_DATA_DIR`、`OPENFLARE_OPENRESTY_PATH`、`OPENFLARE_HEARTBEAT_INTERVAL`、`OPENFLARE_REQUEST_TIMEOUT`、`OPENFLARE_OPENRESTY_OBSERVABILITY_PORT`。
+    - 若配置文件不存在但环境变量足够，Agent 可直接启动；若两者都存在，环境变量覆盖文件值。
+
+- 脚本与文档：
+    - `install-agent.sh` 转为本地 OpenResty 部署脚本，增加 `--openresty-path`，未传时自动查找 `openresty`。
+    - `uninstall-agent.sh` 只卸载 Agent 本身，不再删除 Docker OpenResty 容器或镜像。
+    - 更新架构、开发约束、部署说明、Agent 指南、配置项参考、README，以及英文镜像文档中的旧 Docker 控制说明。
+
+## Public Interfaces
+
+- 新增 Agent 配置字段：
+    - `access_log_path`
+    - `runtime_config_dir`
+
+- 废弃但兼容读取：
+    - `openresty_container_name`
+    - `openresty_docker_image`
+    - `docker_binary`
+
+- 新增 Docker 镜像：
+    - `ghcr.io/rain-kl/openflare-agent`
+
+- Docker 运行方式示例目标：
+    - 挂载配置文件：`-v ./agent.json:/etc/openflare/agent.json`
+    - 或环境变量：`-e OPENFLARE_SERVER_URL=... -e OPENFLARE_AGENT_TOKEN=...`
+
+## Test Plan
+
+- `openflare_agent/internal/config`：
+    - 默认 `openresty_path` 为 `openresty`。
+    - 旧 Docker 字段可读取但不影响 executor。
+    - 环境变量可在无配置文件时启动，并可覆盖配置文件。
+    - 新默认路径符合职责边界。
+
+- `openflare_agent/internal/nginx`：
+    - 二进制命令都包含 `-c <main_config_path>`。
+    - apply 成功、reload 失败后回滚、未运行时 start fallback。
+    - `pow_config.json` 不再写入 `cert_dir` 或 `lua_dir`。
+    - stale `cert_dir/pow_config.json` 与 `lua_dir/pow_config.json` 会被清理。
+    - access log 渲染到 `access_log_path`。
+    - checksum 仍能把主配置、路由配置、证书和 PoW 配置统一纳入比较。
+
+- 集成回归：
+    - `cd openflare_agent && GOCACHE=/tmp/openflare-go-cache go test ./...`
+    - `cd openflare_server && GOCACHE=/tmp/openflare-go-cache go test ./...`
+    - Dockerfile 构建 smoke test：构建 Agent 镜像并用 env-only 配置启动到可执行阶段。
+
+## Assumptions
+
+- Docker Agent 镜像名固定为 `ghcr.io/rain-kl/openflare-agent`。
+- 旧 Docker 控制字段保留兼容，但不再作为受支持行为。
+- 本次不改 Server API、不改数据库模型、不引入远程命令能力。
+- OpenResty 主配置模板继续由 Server 生成；Agent 只负责本地路径替换、文件落盘和二进制控制。
@@ -1,5 +1,7 @@
 # API 约定

+你会学到：OpenFlare 管理端 API 与 Agent API 的响应结构、路径约定、鉴权方式和 Swagger 入口。
+
 OpenFlare 的管理端 API 与 Agent API 都使用 JSON。

 ## 响应结构
@@ -1,5 +1,7 @@
 # 命令与脚本

+你会学到：OpenFlare Server、管理端前端、Agent、Swagger 和文档站的常用启动、构建、测试、安装与卸载命令。
+
 ## Server

 源码启动：
@@ -42,6 +44,15 @@ cd openflare_server/web
 pnpm build
 ```

+检查：
+
+```bash
+cd openflare_server/web
+pnpm lint
+pnpm typecheck
+pnpm test
+```
+
 ## Agent

 源码运行：
@@ -88,3 +99,19 @@ go install github.com/swaggo/swag/cmd/swag@v1.16.4
 cd openflare_server
 swag init -g main.go -o docs
 ```
+
+## Docs
+
+本地预览：
+
+```bash
+cd docs
+pnpm dev
+```
+
+构建：
+
+```bash
+cd docs
+pnpm build
+```
@@ -1,5 +1,7 @@
 # 配置项

+你会学到：OpenFlare Server、前端构建和 Agent 支持哪些配置来源、配置项默认值是什么，以及常见部署组合应该如何配置。
+
 本文档汇总 OpenFlare `1.0.0` 当前支持的 Server 与 Agent 配置项，只保留仍然有效的启动、部署与运行参数。

 ## 配置来源
@@ -16,6 +18,16 @@ Agent 支持：
 2. `agent.json` 配置文件。
 3. 少量日志相关环境变量。

+## 配置文件位置
+
+| 组件 | 默认位置 | 说明 |
+| --- | --- | --- |
+| Server SQLite | `openflare.db` | 可通过 `SQLITE_PATH` 修改 |
+| Server 上传目录 | `upload` | 可通过 `UPLOAD_PATH` 修改 |
+| Agent 配置文件 | `./agent.json` | 可通过 `-config` 指定 |
+| 一键安装 Agent 配置 | `/opt/openflare-agent/agent.json` | 安装脚本默认生成 |
+| Agent 数据目录 | 配置文件所在目录下的 `data` | 可通过 `data_dir` 修改 |
+
 ## Server 命令行参数

 ```bash
@@ -78,7 +90,7 @@ go run . --port 3000 --log-dir ./logs
 * 管理端支持手动清理时留空保留天数，以直接删除对应数据集的全部历史记录。
 * 第三方登录不再通过 `GitHubOAuthEnabled`、`GitHubClientId`、`GitHubClientSecret` 作为主配置入口；这些旧 Option 仅用于升级时迁移默认 GitHub 认证源。
 * 微信登录旧 Option 保留为兼容字段，但管理端不再提供微信登录配置入口。
-* Turnstile 旧 Option 与后端校验能力保留，已有配置仍会生效；
+* Turnstile 旧 Option 与后端校验能力保留，已有配置仍会生效。

 ## OpenResty 参数

@@ -164,6 +176,58 @@ OpenResty 性能参数与缓存参数继续统一保存在 `Option` 表。当前
 * `heartbeat_interval` 与 `request_timeout` 支持毫秒整数或 Go duration 字符串。
 * 未配置 `openresty_path` 时默认使用 Docker OpenResty 模式。
 * Agent 自动探测到私网 `node_ip` 时，Server 会在注册/心跳阶段优先保留 Agent 直连来源的公网地址，避免 NAT/多网卡场景误登记内网网卡地址。
+* [需要确认：安装脚本当前生成的 `sync_interval` 是否仍应保留；当前 Agent 配置结构未使用该字段。]
+
+## 常见配置组合
+
+### 生产 Server + PostgreSQL
+
+```bash
+export SESSION_SECRET='replace-with-a-long-random-string'
+export DSN='postgres://openflare:replace-with-strong-password@postgres:5432/openflare?sslmode=disable'
+export GIN_MODE='release'
+export LOG_LEVEL='info'
+```
+
+### 本地 Server + SQLite
+
+```bash
+export SESSION_SECRET='dev-session-secret'
+export SQLITE_PATH='./openflare-dev.db'
+export LOG_LEVEL='debug'
+go run .
+```
+
+### Agent + Docker OpenResty
+
+```json
+{
+  "server_url": "http://your-server:3000",
+  "agent_token": "replace-with-node-auth-token",
+  "data_dir": "/opt/openflare-agent/data",
+  "openresty_container_name": "openflare-openresty",
+  "openresty_docker_image": "openresty/openresty:alpine",
+  "heartbeat_interval": 10000,
+  "request_timeout": 10000
+}
+```
+
+### Agent + 本机 OpenResty
+
+```json
+{
+  "server_url": "http://your-server:3000",
+  "agent_token": "replace-with-node-auth-token",
+  "data_dir": "/var/lib/openflare-agent",
+  "openresty_path": "/usr/local/openresty/nginx/sbin/nginx",
+  "main_config_path": "/usr/local/openresty/nginx/conf/nginx.conf",
+  "route_config_path": "/usr/local/openresty/nginx/conf/conf.d/openflare_routes.conf",
+  "cert_dir": "/usr/local/openresty/nginx/conf/openflare-certs",
+  "lua_dir": "/usr/local/openresty/nginx/conf/openflare-lua",
+  "heartbeat_interval": 10000,
+  "request_timeout": 10000
+}
+```

 ## 维护要求

@@ -1,5 +1,7 @@
 # 参考

+你会学到：哪些信息属于稳定参考资料，以及配置、命令、API 和仓库结构应该从哪里查。
+
 本部分收敛运行、接口与仓库层面的稳定信息，适合部署、联调和排查时快速查阅。

 | 页面 | 内容 |
@@ -1,5 +1,7 @@
 # 仓库结构

+你会学到：OpenFlare 仓库中 Server、Agent、前端、脚本和文档目录分别负责什么，以及贡献代码时应把逻辑放到哪一层。
+
 | 路径 | 职责 |
 | --- | --- |
 | `openflare_server` | Gin + GORM + SQLite/PostgreSQL 单体控制面 |