tcjlj/OpenFlare
1
0
Fork 0
mirror of https://github.com/Rain-kl/OpenFlare.git synced 2026-10-04 23:16:37 +08:00
Code Issues Packages Projects Releases Wiki Activity

[新增] 更新文档

Browse Source
This commit is contained in:
ryan
2026-05-28 22:50:24 +08:00
parent b69bdf838d
commit 5a0821274b
31 changed files with 2418 additions and 256 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/guide/agent.md
+89 -12
View File
@@ -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` 的重复应用；需要修正配置后重新发布，或激活旧版本回滚 |
docs/guide/deployment.md
+110 -111
View File
@@ -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
```
docs/guide/development.md
+187
View File
@@ -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. 风险较高的修改补充测试或等效联调验证。
数据库结构变更必须提升数据库版本号，并补充从上一版本到新版本的显式迁移方法和校验逻辑。
docs/guide/first-site.md
+58 -3
View File
@@ -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 应用成功。
docs/guide/index.md
+31 -10
View File
@@ -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/` 面向维护者和贡献者，描述产品边界、系统架构、发布模型和工程约束。新增能力或改变边界前，应先更新对应设计文档。
docs/guide/quick-start.md
+111 -14
View File
@@ -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)。
docs/guide/server.md
+53 -13
View File
@@ -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+` |
| 项目 | 要求 |
| --- | --- |
| 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`。
docs/guide/sso.md
+2
View File
@@ -1,5 +1,7 @@
# SSO 登录配置
你会学到：如何为 OpenFlare 配置 GitHub OAuth 或标准 OIDC 登录入口，如何填写回调地址，以及第三方账号如何绑定本地用户。
OpenFlare 支持通过认证源配置第三方登录入口。当前支持 GitHub OAuth 与标准 OIDC Provider，例如 Logto、authentik、Keycloak、Casdoor 等。
认证源配置完成并启用后，会显示在登录页的第三方账号登录区域。用户可以通过第三方账号登录，也可以在已登录状态下把第三方账号绑定到当前本地账号。
docs/guide/troubleshooting.md
+226
View File
@@ -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 文件。
docs/guide/upgrade.md
+32
View File
@@ -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
```
docs/guide/usage.md
+136
View File
@@ -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 配置文件；下次发布会覆盖这些文件。