From c856faca50e8d2d6154c9f290f4fac86f4257fc0 Mon Sep 17 00:00:00 2001
From: ryan <ryan@arctel.net>
Date: Thu, 28 May 2026 22:56:39 +0800
Subject: [PATCH] =?UTF-8?q?[=E6=96=B0=E5=A2=9E]=20=E6=9B=B4=E6=96=B0?=
 =?UTF-8?q?=E6=96=87=E6=A1=A3?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 README.md                          | 20 +++++++----
 docs/design/development.md         |  6 ++--
 docs/design/release-model.md       |  2 +-
 docs/en/design/architecture.md     |  4 +--
 docs/en/guide/agent.md             | 16 +++++++--
 docs/en/guide/deployment.md        | 14 ++++----
 docs/en/guide/development.md       |  7 ++--
 docs/en/guide/quick-start.md       | 10 +++---
 docs/en/guide/troubleshooting.md   | 15 ++++-----
 docs/en/reference/configuration.md | 10 +++---
 docs/guide/agent.md                | 39 +++++++++++++++-------
 docs/guide/deployment.md           | 39 ++++++++++++++++++----
 docs/guide/development.md          |  7 ++--
 docs/guide/quick-start.md          | 10 +++---
 docs/guide/troubleshooting.md      | 15 ++++-----
 docs/reference/configuration.md    | 53 +++++++++++++++++++-----------
 docs/reference/repository.md       |  2 +-
 17 files changed, 171 insertions(+), 98 deletions(-)

diff --git a/README.md b/README.md
index 95caa057..75f580f2 100644
--- a/README.md
+++ b/README.md
@@ -93,7 +93,7 @@ docker compose up -d
 
 ### 2. 安装 Agent
 
-**注意:** 安装agent前需确保存已经安装了Docker, 虽然支持裸Openresty,但未得到充分验证,可能存在未知问题.
+安装 Agent 前请先在节点上安装 OpenResty，或改用内置 OpenResty 的 Agent Docker 镜像。
 
 使用 `discovery_token` 接入：
 
@@ -111,7 +111,18 @@ curl -fsSL https://raw.githubusercontent.com/Rain-kl/OpenFlare/main/scripts/inst
   --agent-token YOUR_AGENT_TOKEN
 ```
 
-安装脚本默认写入 `/opt/openflare-agent`，创建 `openflare-agent.service`，并可重复执行以重装或升级 Agent。
+安装脚本默认写入 `/opt/openflare-agent`，创建 `openflare-agent.service`，自动查找 `openresty`，并可重复执行以重装或升级 Agent。
+
+Docker 部署可直接运行 Agent 镜像：
+
+```bash
+docker run -d --name openflare-agent --restart unless-stopped \
+  -p 80:80 -p 443:443 -p 127.0.0.1:18081:18081 \
+  -v openflare-agent-data:/data \
+  -e OPENFLARE_SERVER_URL=http://your-server:3000 \
+  -e OPENFLARE_AGENT_TOKEN=YOUR_AGENT_TOKEN \
+  ghcr.io/rain-kl/openflare-agent:latest
+```
 
 ### 3. 卸载 Agent
 
@@ -121,10 +132,7 @@ curl -fsSL https://raw.githubusercontent.com/Rain-kl/OpenFlare/main/scripts/inst
 curl -fsSL https://raw.githubusercontent.com/Rain-kl/OpenFlare/main/scripts/uninstall-agent.sh | bash
 ```
 
-卸载脚本会先停止并移除 `openflare-agent.service`、删除整个 `/opt/openflare-agent` 目录，然后根据卸载前保存的 `agent.json` 判断 OpenResty 安装方式：
-
-* Docker 模式：删除对应 OpenResty 容器，并尝试移除镜像
-* 本机 `openresty_path` 模式：不改动本机 OpenResty，只提示用户手动卸载
+卸载脚本会先停止并移除 `openflare-agent.service`、删除整个 `/opt/openflare-agent` 目录，不会删除本机 OpenResty。
 
 ### 4. 发布第一份配置
 
diff --git a/docs/design/development.md b/docs/design/development.md
index 985246d7..923d8be0 100644
--- a/docs/design/development.md
+++ b/docs/design/development.md
@@ -52,8 +52,8 @@ Agent：
 
 * 单二进制
 * 节点本地执行
-* `openresty_path` 优先
-* 无 `openresty_path` 时默认 Docker OpenResty
+* 通过 `openresty_path` 或默认 `openresty` 控制 OpenResty 二进制
+* Docker 部署使用内置 OpenResty 的 Agent 镜像，不由 Agent 再控制独立 OpenResty 容器
 
 Frontend：
 
@@ -236,7 +236,7 @@ Agent 必须满足：
 * 常规同步优先依据 heartbeat 返回的版本摘要判断。
 * 发现新版本时先备份旧文件。
 * 写入主配置、路由配置与必要证书文件。
-* 写入新配置后以运行态恢复为目标执行激活，Docker 模式优先重建容器并确认容器保持运行。
+* 写入新配置后执行 `openresty -t -c <main_config_path>`，再 reload；reload 发现运行时未启动时允许直接启动 OpenResty。
 * 新配置激活失败时必须先尝试用目标配置恢复运行，再回滚到旧配置并重新拉起 OpenResty。
 * 回滚后 OpenResty 恢复正常时上报警告；回滚后仍无法恢复运行时上报失败。
 * 某个目标 `version + checksum` 一旦应用失败并回退，Agent 必须在本地状态中阻断该目标的重复应用。
diff --git a/docs/design/release-model.md b/docs/design/release-model.md
index 6822bc7c..834c100b 100644
--- a/docs/design/release-model.md
+++ b/docs/design/release-model.md
@@ -55,7 +55,7 @@ Agent 发现新版本后会：
 2. 备份旧文件。
 3. 写入主配置、路由配置、证书与必要 Lua 资源。
 4. 执行 OpenResty 配置校验。
-5. reload 或重建 Docker OpenResty。
+5. reload；如果运行时未启动，则尝试用当前配置启动 OpenResty。
 6. 上报成功、警告或失败。
 
 如果新配置激活失败，Agent 必须尝试恢复运行；回滚成功时上报警告，回滚后仍无法恢复运行时上报失败。
diff --git a/docs/en/design/architecture.md b/docs/en/design/architecture.md
index 55d8f95f..70b296a0 100644
--- a/docs/en/design/architecture.md
+++ b/docs/en/design/architecture.md
@@ -10,7 +10,7 @@ OpenFlare Server (Gin + SQLite/PostgreSQL + Web UI)
 OpenFlare Agent (register / heartbeat / sync / apply / update)
         |
         v
-Local OpenResty or Docker OpenResty
+OpenResty binary
         |
         v
 Origin
@@ -24,7 +24,7 @@ It owns the admin UI and API, Agent API, configuration rendering, version publis
 
 ## Agent
 
-`openflare_agent` is a single Go binary that runs locally on each node. It prefers `openresty_path` when configured and uses Docker OpenResty by default otherwise.
+`openflare_agent` is a single Go binary that runs on each node. It controls OpenResty through `openresty_path`, or `openresty` by default. Docker deployments use an Agent image that already includes OpenResty and follows the same binary-control flow.
 
 It handles registration, heartbeat, sync, file writes, `openresty -t`, reload, rollback, self-update, and lightweight collection.
 
diff --git a/docs/en/guide/agent.md b/docs/en/guide/agent.md
index d96ef6a4..d25afe6f 100644
--- a/docs/en/guide/agent.md
+++ b/docs/en/guide/agent.md
@@ -34,8 +34,7 @@ curl -fsSL https://raw.githubusercontent.com/Rain-kl/OpenFlare/main/scripts/inst
   "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_path": "openresty",
   "openresty_observability_port": 18081,
   "observability_replay_minutes": 15,
   "heartbeat_interval": 10000,
@@ -43,7 +42,18 @@ curl -fsSL https://raw.githubusercontent.com/Rain-kl/OpenFlare/main/scripts/inst
 }
 ```
 
-Without `openresty_path`, Agent uses Docker OpenResty by default.
+Without `openresty_path`, Agent runs `openresty` by default.
+
+## Docker
+
+```bash
+docker run -d --name openflare-agent --restart unless-stopped \
+  -p 80:80 -p 443:443 -p 127.0.0.1:18081:18081 \
+  -v openflare-agent-data:/data \
+  -e OPENFLARE_SERVER_URL=http://your-server:3000 \
+  -e OPENFLARE_AGENT_TOKEN=YOUR_AGENT_TOKEN \
+  ghcr.io/rain-kl/openflare-agent:latest
+```
 
 ## Run from Source
 
diff --git a/docs/en/guide/deployment.md b/docs/en/guide/deployment.md
index c7bd9d57..ca0d4abc 100644
--- a/docs/en/guide/deployment.md
+++ b/docs/en/guide/deployment.md
@@ -2,7 +2,7 @@
 
 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.
+For production, use PostgreSQL for the Server database and set `SESSION_SECRET` explicitly. Agent controls OpenResty through the OpenResty binary; Docker deployments run the Agent image that already includes OpenResty.
 
 ## Topology
 
@@ -17,7 +17,7 @@ OpenFlare Server :3000
 OpenFlare Agent
   |
   v
-Local OpenResty or Docker OpenResty
+OpenResty binary
   |
   v
 Origin service
@@ -40,8 +40,8 @@ Agent:
 | --- | --- |
 | 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 |
+| OpenResty | Required for local Agent installs |
+| Docker | Required only when running the Agent Docker image |
 | Network | Agent node must reach the Server URL |
 
 [Needs confirmation: recommended production CPU, memory, and disk size]
@@ -154,6 +154,7 @@ Supported options:
 | `--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` |
+| `--openresty-path` | OpenResty binary path, auto-detected when omitted |
 | `--repo` | GitHub repository for Agent downloads, default `Rain-kl/OpenFlare` |
 | `--no-service` | Do not create a systemd service |
 
@@ -190,12 +191,13 @@ Minimal `agent.json`:
   "server_url": "http://127.0.0.1:3000",
   "agent_token": "replace-with-node-auth-token",
   "data_dir": "./data",
+  "openresty_path": "openresty",
   "heartbeat_interval": 10000,
   "request_timeout": 10000
 }
 ```
 
-When `openresty_path` is not configured, Agent uses Docker OpenResty.
+When `openresty_path` is not configured, Agent runs `openresty`.
 
 ## Minimal Integration Flow
 
@@ -227,7 +229,7 @@ Uninstall Agent:
 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.
+The uninstall script stops Agent and removes the systemd service and install directory. It does not remove the local OpenResty installation.
 
 ## Validation Commands
 
diff --git a/docs/en/guide/development.md b/docs/en/guide/development.md
index 1ed51e7e..dd70c21e 100644
--- a/docs/en/guide/development.md
+++ b/docs/en/guide/development.md
@@ -21,7 +21,8 @@ This page is for contributors. Product boundaries, data model constraints, API c
 | 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 |
+| Docker | Needed for Server containers, local integration, and the Agent Docker image |
+| OpenResty | Needed when running Agent locally |
 | PostgreSQL | Optional. The Server uses SQLite when PostgreSQL is not configured. |
 
 ## Install Frontend Dependencies
@@ -106,7 +107,7 @@ 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`.
+When `openresty_path` is not configured, the Agent runs `openresty`. For debugging, set `openresty_path`, `main_config_path`, `route_config_path`, `access_log_path`, `cert_dir`, `lua_dir`, and `runtime_config_dir` as needed.
 
 ## Tests
 
@@ -172,7 +173,7 @@ go build -o openflare-agent ./cmd/agent
 | 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` |
+| OpenResty config test | `openresty -t -c ./data/etc/nginx/nginx.conf` |
 
 ## Change Acceptance
 
diff --git a/docs/en/guide/quick-start.md b/docs/en/guide/quick-start.md
index 958ca2d9..4858e2c5 100644
--- a/docs/en/guide/quick-start.md
+++ b/docs/en/guide/quick-start.md
@@ -10,13 +10,14 @@ The minimal OpenFlare setup contains:
 | 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.
+Agent controls OpenResty through the OpenResty binary. Local installs need an `openresty` executable on the node; Docker installs can run the Agent image that already includes OpenResty.
 
 ## Requirements
 
 | Item | Requirement |
 | --- | --- |
-| Docker / Docker Compose | Used to start Server and PostgreSQL, and used by the default Agent Docker OpenResty mode |
+| Docker / Docker Compose | Used to start Server and PostgreSQL; also used if you run the Agent Docker image |
+| OpenResty | Required for local Agent installs unless `--openresty-path` points to a custom binary |
 | Reachable ports | Server listens on `3000` by default. Agent nodes must reach the Server URL. |
 | Browser | Used to open the management UI |
 
@@ -128,7 +129,7 @@ The script defaults to:
 | 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 |
+| OpenResty path | Auto-detects `openresty` unless `--openresty-path` is provided |
 
 Check status:
 
@@ -166,11 +167,8 @@ 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 |
diff --git a/docs/en/guide/troubleshooting.md b/docs/en/guide/troubleshooting.md
index e4348b8a..77c86677 100644
--- a/docs/en/guide/troubleshooting.md
+++ b/docs/en/guide/troubleshooting.md
@@ -153,22 +153,21 @@ Common causes:
 | 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 |
+| Port conflict | Check local `80` and `443` usage |
 
-Docker OpenResty mode:
+OpenResty config test:
 
 ```bash
-docker ps --filter name=openflare-openresty
-docker logs --tail 100 openflare-openresty
+openresty -t -c /path/to/openflare/data/etc/nginx/nginx.conf
 ```
 
-Local OpenResty mode:
+OpenResty runtime:
 
 ```bash
-/usr/local/openresty/nginx/sbin/nginx -t
+ps aux | grep openresty
 ```
 
-Use the actual path from `openresty_path` in `agent.json`.
+Use the actual `openresty_path` and `main_config_path` from `agent.json`.
 
 ## HTTPS Does Not Work
 
@@ -187,7 +186,7 @@ Domains without a bound certificate are not automatically added to HTTPS configu
 ## No Access Analytics
 
 1. Confirm the node applied a configuration that includes observability Lua assets.
-2. Confirm Docker OpenResty or local OpenResty is running.
+2. Confirm 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.
diff --git a/docs/en/reference/configuration.md b/docs/en/reference/configuration.md
index 9df1e4fb..98d90b79 100644
--- a/docs/en/reference/configuration.md
+++ b/docs/en/reference/configuration.md
@@ -60,12 +60,14 @@ Agent supports the `-config` CLI flag, an `agent.json` file, and the `LOG_LEVEL`
 | `discovery_token` | Global token for first registration | one of `agent_token` / `discovery_token` | empty |
 | `node_name` | Node name | no | host name |
 | `node_ip` | Node IP | no | auto-detected |
-| `openresty_path` | Local OpenResty path | no | empty; Docker mode |
-| `openresty_container_name` | Docker container name | no | `openflare-openresty` |
-| `openresty_docker_image` | Docker image | no | `openresty/openresty:alpine` |
+| `openresty_path` | OpenResty binary path | no | `openresty` |
+| `openresty_container_name` | Deprecated Docker-control field, read for compatibility only | no | empty |
+| `openresty_docker_image` | Deprecated Docker-control field, read for compatibility only | no | empty |
 | `openresty_observability_port` | Local observability port | no | `18081` |
-| `docker_binary` | Docker binary name or path | no | `docker` |
+| `docker_binary` | Deprecated Docker-control field, read for compatibility only | no | empty |
 | `data_dir` | Agent data directory | no | `data` under config directory |
+| `access_log_path` | OpenResty access log path | no | `data_dir/var/log/openflare/access.log` |
+| `runtime_config_dir` | Runtime config directory, including `pow_config.json` | no | `data_dir/etc/openflare` |
 | `heartbeat_interval` | Heartbeat interval | no | `10000` ms |
 | `request_timeout` | HTTP timeout | no | `10000` ms |
 
diff --git a/docs/guide/agent.md b/docs/guide/agent.md
index c3c1cfd4..bc37f12b 100644
--- a/docs/guide/agent.md
+++ b/docs/guide/agent.md
@@ -43,6 +43,7 @@ curl -fsSL https://raw.githubusercontent.com/Rain-kl/OpenFlare/main/scripts/inst
 | `--discovery-token` | 首次自动注册 Token |
 | `--agent-token` | 节点专属 Token |
 | `--install-dir` | 安装目录，默认 `/opt/openflare-agent` |
+| `--openresty-path` | OpenResty 二进制路径，未传时自动查找 `openresty` |
 | `--repo` | 下载 Agent 的 GitHub 仓库，默认 `Rain-kl/OpenFlare` |
 | `--no-service` | 不创建 systemd 服务 |
 
@@ -54,15 +55,14 @@ curl -fsSL https://raw.githubusercontent.com/Rain-kl/OpenFlare/main/scripts/inst
 /opt/openflare-agent/agent.json
 ```
 
-Docker OpenResty 模式示例：
+本地配置示例：
 
 ```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_path": "openresty",
   "openresty_observability_port": 18081,
   "observability_replay_minutes": 15,
   "heartbeat_interval": 10000,
@@ -70,24 +70,39 @@ 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",
+  "openresty_path": "/usr/local/openresty/nginx/sbin/openresty",
+  "main_config_path": "/var/lib/openflare-agent/etc/nginx/nginx.conf",
+  "route_config_path": "/var/lib/openflare-agent/etc/nginx/conf.d/openflare_routes.conf",
+  "access_log_path": "/var/lib/openflare-agent/var/log/openflare/access.log",
+  "cert_dir": "/var/lib/openflare-agent/etc/nginx/certs",
+  "lua_dir": "/var/lib/openflare-agent/etc/nginx/lua",
+  "runtime_config_dir": "/var/lib/openflare-agent/etc/openflare",
   "heartbeat_interval": 10000,
   "request_timeout": 10000
 }
 ```
 
-如果不配置 `openresty_path`，Agent 默认使用 Docker OpenResty。完整字段见 [配置项参考](../reference/configuration.md#agent-配置字段)。
+如果不配置 `openresty_path`，Agent 默认调用 `openresty`。完整字段见 [配置项参考](../reference/configuration.md#agent-配置字段)。
+
+## Docker 运行
+
+Docker 部署时直接运行内置 OpenResty 的 Agent 镜像：
+
+```bash
+docker run -d --name openflare-agent --restart unless-stopped \
+  -p 80:80 -p 443:443 -p 127.0.0.1:18081:18081 \
+  -v openflare-agent-data:/data \
+  -e OPENFLARE_SERVER_URL=http://your-server:3000 \
+  -e OPENFLARE_AGENT_TOKEN=YOUR_AGENT_TOKEN \
+  ghcr.io/rain-kl/openflare-agent:latest
+```
 
 ## 启动与验证
 
@@ -144,7 +159,7 @@ curl -fsSL https://raw.githubusercontent.com/Rain-kl/OpenFlare/main/scripts/unin
 | `--install-dir` | 安装目录，默认 `/opt/openflare-agent` |
 | `--service-name` | systemd 服务名，默认 `openflare-agent` |
 
-卸载脚本会先读取卸载前的 `agent.json` 判断 OpenResty 模式。Docker 模式会尝试删除对应容器和镜像；本机 `openresty_path` 模式不会删除本机 OpenResty。
+卸载脚本只移除 Agent 服务、进程和安装目录，不会删除本机 OpenResty。
 
 ## 常见问题
 
@@ -152,5 +167,5 @@ curl -fsSL https://raw.githubusercontent.com/Rain-kl/OpenFlare/main/scripts/unin
 | --- | --- |
 | `agent_token 和 discovery_token 不能同时为空` | 检查 `agent.json` 至少配置了一个 Token |
 | 节点一直离线 | 在 Agent 节点执行 `curl -I http://your-server:3000`，确认 Server 地址可达 |
-| Docker OpenResty 没有启动 | 查看 `journalctl -u openflare-agent`，并确认当前用户有 Docker 执行权限 |
+| OpenResty 没有启动 | 查看 `journalctl -u openflare-agent`，确认 `openresty_path` 可执行且 80/443 端口未被占用 |
 | 发布后重复失败 | Agent 会阻断同一 `version + checksum` 的重复应用；需要修正配置后重新发布，或激活旧版本回滚 |
diff --git a/docs/guide/deployment.md b/docs/guide/deployment.md
index 7e0a21f8..998847a8 100644
--- a/docs/guide/deployment.md
+++ b/docs/guide/deployment.md
@@ -2,7 +2,7 @@
 
 你会学到：OpenFlare 的推荐部署方式、Server 与 Agent 的运行要求、源码启动方式、联调步骤、升级与卸载入口。
 
-生产环境建议使用 PostgreSQL 作为 Server 数据库，并为 Server 显式配置 `SESSION_SECRET`。Agent 节点默认使用 Docker OpenResty；如果要使用本机 OpenResty，需要额外配置 `openresty_path` 和写入目录。
+生产环境建议使用 PostgreSQL 作为 Server 数据库，并为 Server 显式配置 `SESSION_SECRET`。Agent 统一通过 OpenResty 二进制控制运行时；Docker 部署请直接使用内置 OpenResty 的 Agent 镜像。
 
 ## 部署拓扑
 
@@ -17,7 +17,7 @@ OpenFlare Server :3000
 OpenFlare Agent
   |
   v
-Local OpenResty or Docker OpenResty
+OpenResty binary
   |
   v
 Origin service
@@ -40,8 +40,8 @@ Agent：
 | --- | --- |
 | 系统 | 安装脚本支持 Linux 和 macOS；systemd 服务仅在 Linux + systemd 环境创建 |
 | 架构 | `amd64` 或 `arm64` |
-| Docker | 默认 Docker OpenResty 模式需要 |
-| 本机 OpenResty | 仅在显式配置 `openresty_path` 时需要 |
+| OpenResty | 本地部署需要可执行 `openresty`，或通过 `--openresty-path` 指定路径 |
+| Docker | 仅 Docker 部署 Agent 镜像时需要 |
 | 网络 | Agent 节点必须能访问 Server 地址 |
 
 [需要确认：生产环境推荐的最低 CPU、内存与磁盘容量]
@@ -154,6 +154,7 @@ curl -fsSL https://raw.githubusercontent.com/Rain-kl/OpenFlare/main/scripts/inst
 | `--discovery-token` | 首次自动注册 Token，与 `--agent-token` 二选一 |
 | `--agent-token` | 节点专属 Token，与 `--discovery-token` 二选一 |
 | `--install-dir` | 安装目录，默认 `/opt/openflare-agent` |
+| `--openresty-path` | OpenResty 二进制路径，未传时自动查找 `openresty` |
 | `--repo` | 下载 Agent 的 GitHub 仓库，默认 `Rain-kl/OpenFlare` |
 | `--no-service` | 不创建 systemd 服务 |
 
@@ -164,6 +165,31 @@ systemctl status openflare-agent
 journalctl -u openflare-agent -f
 ```
 
+## Docker 运行 Agent
+
+Docker 部署时直接运行 Agent 镜像。该镜像基于 OpenResty 镜像制作，内置 Agent 控制器与 OpenResty 二进制。
+
+挂载配置文件：
+
+```bash
+docker run -d --name openflare-agent --restart unless-stopped \
+  -p 80:80 -p 443:443 -p 127.0.0.1:18081:18081 \
+  -v openflare-agent-data:/data \
+  -v ./agent.json:/etc/openflare/agent.json:ro \
+  ghcr.io/rain-kl/openflare-agent:latest
+```
+
+使用环境变量：
+
+```bash
+docker run -d --name openflare-agent --restart unless-stopped \
+  -p 80:80 -p 443:443 -p 127.0.0.1:18081:18081 \
+  -v openflare-agent-data:/data \
+  -e OPENFLARE_SERVER_URL=http://your-server:3000 \
+  -e OPENFLARE_AGENT_TOKEN=YOUR_AGENT_TOKEN \
+  ghcr.io/rain-kl/openflare-agent:latest
+```
+
 ## 手动运行 Agent
 
 源码运行：
@@ -190,12 +216,13 @@ export LOG_LEVEL='info'
   "server_url": "http://127.0.0.1:3000",
   "agent_token": "replace-with-node-auth-token",
   "data_dir": "./data",
+  "openresty_path": "openresty",
   "heartbeat_interval": 10000,
   "request_timeout": 10000
 }
 ```
 
-未配置 `openresty_path` 时，Agent 会使用 Docker OpenResty。
+未配置 `openresty_path` 时，Agent 默认调用 `openresty`。
 
 ## 最小联调步骤
 
@@ -227,7 +254,7 @@ Agent：
 curl -fsSL https://raw.githubusercontent.com/Rain-kl/OpenFlare/main/scripts/uninstall-agent.sh | bash
 ```
 
-卸载脚本会停止 Agent、删除 systemd 服务和安装目录；如果检测到 Docker OpenResty 模式，会尝试移除对应容器和镜像。本机 `openresty_path` 模式不会删除本机 OpenResty。
+卸载脚本会停止 Agent、删除 systemd 服务和安装目录，不会删除本机 OpenResty。
 
 ## 常用验证命令
 
diff --git a/docs/guide/development.md b/docs/guide/development.md
index 249b5a7c..03136fd8 100644
--- a/docs/guide/development.md
+++ b/docs/guide/development.md
@@ -21,7 +21,8 @@
 | Go | `1.25+` |
 | Node.js | `18+` |
 | pnpm | 推荐通过 `corepack enable` 使用项目声明版本 |
-| Docker | Agent 默认 Docker OpenResty 模式和本地联调需要 |
+| Docker | Server 容器、本地联调和 Agent Docker 镜像需要 |
+| OpenResty | 本地运行 Agent 时需要可执行 `openresty` |
 | PostgreSQL | 可选；未配置时 Server 使用 SQLite |
 
 ## 初始化前端依赖
@@ -106,7 +107,7 @@ 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`。
+未配置 `openresty_path` 时，Agent 默认调用 `openresty`。调试时可显式配置 `openresty_path`、`main_config_path`、`route_config_path`、`access_log_path`、`cert_dir`、`lua_dir` 和 `runtime_config_dir`。
 
 ## 测试
 
@@ -172,7 +173,7 @@ go build -o openflare-agent ./cmd/agent
 | 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` |
+| OpenResty 配置校验 | `openresty -t -c ./data/etc/nginx/nginx.conf` |
 
 ## 代码风格与变更准入
 
diff --git a/docs/guide/quick-start.md b/docs/guide/quick-start.md
index d973408f..ed949654 100644
--- a/docs/guide/quick-start.md
+++ b/docs/guide/quick-start.md
@@ -10,13 +10,14 @@ OpenFlare 的最小运行单元包含：
 | Agent | 运行在代理节点上，拉取配置、写入 OpenResty、执行校验与 reload |
 | OpenResty | 实际接收流量并反向代理到源站 |
 
-默认情况下，Agent 未配置 `openresty_path` 时会使用 Docker OpenResty。因此快速开始建议在 Agent 节点准备 Docker。
+Agent 统一通过 OpenResty 二进制控制运行时。本地部署需要节点上已有 `openresty` 可执行文件；Docker 部署可直接运行内置 OpenResty 的 Agent 镜像。
 
 ## 环境要求
 
 | 项目 | 要求 |
 | --- | --- |
-| Docker / Docker Compose | 用于启动 Server 和 PostgreSQL，也用于 Agent 默认的 Docker OpenResty 模式 |
+| Docker / Docker Compose | 用于启动 Server 和 PostgreSQL；如果采用 Docker Agent 镜像，也用于运行 Agent |
+| OpenResty | 本地安装 Agent 时需要可执行 `openresty`，或在安装脚本中指定路径 |
 | 可访问端口 | Server 默认监听 `3000`，Agent 节点需要能访问 Server 地址 |
 | 浏览器 | 用于访问管理端 |
 
@@ -128,7 +129,7 @@ curl -fsSL https://raw.githubusercontent.com/Rain-kl/OpenFlare/main/scripts/inst
 | 安装目录 | `/opt/openflare-agent` |
 | 配置文件 | `/opt/openflare-agent/agent.json` |
 | systemd 服务 | `openflare-agent.service` |
-| OpenResty 模式 | 未配置 `openresty_path` 时使用 Docker OpenResty |
+| OpenResty 路径 | 未指定时自动查找 `openresty` |
 
 确认 Agent 服务状态：
 
@@ -166,11 +167,8 @@ journalctl -u openflare-agent -f
 
 ```bash
 journalctl -u openflare-agent -n 100 --no-pager
-docker ps --filter name=openflare-openresty
 ```
 
-如果使用 Docker OpenResty，默认容器名是 `openflare-openresty`。
-
 ## 常见失败原因
 
 | 现象 | 排查方向 |
diff --git a/docs/guide/troubleshooting.md b/docs/guide/troubleshooting.md
index f51768fc..42b65d4e 100644
--- a/docs/guide/troubleshooting.md
+++ b/docs/guide/troubleshooting.md
@@ -153,22 +153,21 @@ journalctl -u openflare-agent -f
 | 上游地址不合法 | 确认所有上游都是 `http://` 或 `https://` |
 | 多上游格式不符合约束 | 多上游必须是纯 `scheme://host[:port]` |
 | 证书缺失或路径错误 | 检查域名是否绑定证书，以及 Agent 证书目录是否可写 |
-| 端口被占用 | 检查本机或 Docker 容器的 `80`、`443` 端口 |
+| 端口被占用 | 检查本机 `80`、`443` 端口 |
 
-Docker OpenResty 模式：
+OpenResty 配置校验：
 
 ```bash
-docker ps --filter name=openflare-openresty
-docker logs --tail 100 openflare-openresty
+openresty -t -c /path/to/openflare/data/etc/nginx/nginx.conf
 ```
 
-本机 OpenResty 模式：
+OpenResty 运行状态：
 
 ```bash
-/usr/local/openresty/nginx/sbin/nginx -t
+ps aux | grep openresty
 ```
 
-实际路径以 `agent.json` 中的 `openresty_path` 为准。
+实际二进制路径和主配置路径以 `agent.json` 中的 `openresty_path` 与 `main_config_path` 为准。
 
 ## HTTPS 不生效
 
@@ -187,7 +186,7 @@ curl -Iv https://your-domain
 ## 访问分析没有数据
 
 1. 确认节点已经成功应用包含观测 Lua 资源的配置。
-2. 确认 Docker OpenResty 容器或本机 OpenResty 正在运行。
+2. 确认 OpenResty 正在运行。
 3. 查看 Agent 日志是否有观测采集或补报失败信息。
 4. 检查 `openresty_observability_port` 是否被占用，默认是 `18081`。
 5. 确认 Server 侧没有因数据库清理策略删除对应时间窗口数据。
diff --git a/docs/reference/configuration.md b/docs/reference/configuration.md
index 283483a5..ab1824a4 100644
--- a/docs/reference/configuration.md
+++ b/docs/reference/configuration.md
@@ -136,6 +136,16 @@ OpenResty 性能参数与缓存参数继续统一保存在 `Option` 表。当前
 | 环境变量 | 作用 | 默认值 |
 | --- | --- | --- |
 | `LOG_LEVEL` | Agent 日志等级 | `info` |
+| `OPENFLARE_SERVER_URL` | 控制面地址，可覆盖 `agent.json` | 空 |
+| `OPENFLARE_AGENT_TOKEN` | 节点专属认证 Token，可覆盖 `agent.json` | 空 |
+| `OPENFLARE_DISCOVERY_TOKEN` | 首次自动注册 Token，可覆盖 `agent.json` | 空 |
+| `OPENFLARE_NODE_NAME` | 节点名称，可覆盖 `agent.json` | 空 |
+| `OPENFLARE_NODE_IP` | 节点 IP，可覆盖 `agent.json` | 空 |
+| `OPENFLARE_DATA_DIR` | Agent 数据目录，可覆盖 `agent.json` | 空 |
+| `OPENFLARE_OPENRESTY_PATH` | OpenResty 二进制路径，可覆盖 `agent.json` | 空 |
+| `OPENFLARE_HEARTBEAT_INTERVAL` | 心跳间隔，可覆盖 `agent.json` | 空 |
+| `OPENFLARE_REQUEST_TIMEOUT` | 请求超时，可覆盖 `agent.json` | 空 |
+| `OPENFLARE_OPENRESTY_OBSERVABILITY_PORT` | 本地观测端口，可覆盖 `agent.json` | 空 |
 
 ## Agent 命令行参数
 
@@ -152,18 +162,20 @@ OpenResty 性能参数与缓存参数继续统一保存在 `Option` 表。当前
 | `discovery_token` | 首次自动注册使用的全局 Token | 与 `agent_token` 二选一 | 空 |
 | `node_name` | 节点名称 | 否 | 自动使用主机名 |
 | `node_ip` | 节点 IP | 否 | 自动探测，优先选择公网 IPv4；仅无公网地址时退回可用内网地址 |
-| `openresty_path` | 本机 OpenResty 路径 | 否 | 空，未设置时走 Docker 模式 |
-| `openresty_container_name` | Docker 模式下的容器名 | 否 | `openflare-openresty` |
-| `openresty_docker_image` | Docker 模式下的镜像 | 否 | `openresty/openresty:alpine` |
+| `openresty_path` | OpenResty 二进制路径 | 否 | `openresty` |
+| `openresty_container_name` | 旧 Docker 控制字段，仅兼容读取 | 否 | 空 |
+| `openresty_docker_image` | 旧 Docker 控制字段，仅兼容读取 | 否 | 空 |
 | `openresty_observability_port` | 本地观测端口 | 否 | `18081` |
-| `docker_binary` | Docker 可执行文件名或路径 | 否 | `docker` |
+| `docker_binary` | 旧 Docker 控制字段，仅兼容读取 | 否 | 空 |
 | `data_dir` | Agent 数据目录 | 否 | 配置文件所在目录下的 `data` |
-| `main_config_path` | OpenResty 主配置写入路径 | 否 | 本机模式建议显式配置 |
+| `main_config_path` | OpenResty 主配置写入路径 | 否 | `data_dir/etc/nginx/nginx.conf` |
 | `route_config_path` | 路由配置写入路径 | 否 | `data_dir/etc/nginx/conf.d/openflare_routes.conf` |
-| `cert_dir` | 本机证书写入目录 | 否 | `data_dir/etc/nginx/certs` |
-| `openresty_cert_dir` | OpenResty 读取证书目录 | 否 | 随运行模式变化 |
-| `lua_dir` | 本机 Lua 脚本写入目录 | 否 | `data_dir/etc/nginx/lua` |
-| `openresty_lua_dir` | OpenResty 读取 Lua 目录 | 否 | 随运行模式变化 |
+| `access_log_path` | OpenResty 访问日志路径 | 否 | `data_dir/var/log/openflare/access.log` |
+| `cert_dir` | 证书写入目录 | 否 | `data_dir/etc/nginx/certs` |
+| `openresty_cert_dir` | OpenResty 配置中读取证书的目录 | 否 | 同 `cert_dir` |
+| `lua_dir` | Lua 脚本与静态资源写入目录 | 否 | `data_dir/etc/nginx/lua` |
+| `openresty_lua_dir` | OpenResty 配置中读取 Lua 的目录 | 否 | 同 `lua_dir` |
+| `runtime_config_dir` | Agent 运行时配置写入目录，如 `pow_config.json` | 否 | `data_dir/etc/openflare` |
 | `observability_buffer_path` | 观测补报缓冲文件路径 | 否 | `data_dir/var/lib/openflare/observability-buffer.json` |
 | `observability_replay_minutes` | 自动补传最近观测窗口分钟数 | 否 | `15` |
 | `state_path` | Agent 本地状态文件路径 | 否 | `data_dir/var/lib/openflare/agent-state.json` |
@@ -174,9 +186,9 @@ OpenResty 性能参数与缓存参数继续统一保存在 `Option` 表。当前
 
 * `agent_token` 与 `discovery_token` 不能同时为空。
 * `heartbeat_interval` 与 `request_timeout` 支持毫秒整数或 Go duration 字符串。
-* 未配置 `openresty_path` 时默认使用 Docker OpenResty 模式。
+* 未配置 `openresty_path` 时默认调用 `openresty`。
+* 如果 `agent.json` 不存在，但 `OPENFLARE_SERVER_URL` 与 Token 等环境变量足够，Agent 可以直接启动；两者同时存在时环境变量优先。
 * Agent 自动探测到私网 `node_ip` 时，Server 会在注册/心跳阶段优先保留 Agent 直连来源的公网地址，避免 NAT/多网卡场景误登记内网网卡地址。
-* [需要确认：安装脚本当前生成的 `sync_interval` 是否仍应保留；当前 Agent 配置结构未使用该字段。]
 
 ## 常见配置组合
 
@@ -198,32 +210,33 @@ export LOG_LEVEL='debug'
 go run .
 ```
 
-### Agent + Docker OpenResty
+### Agent + 默认 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",
+  "openresty_path": "openresty",
   "heartbeat_interval": 10000,
   "request_timeout": 10000
 }
 ```
 
-### Agent + 本机 OpenResty
+### 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",
+  "openresty_path": "/usr/local/openresty/nginx/sbin/openresty",
+  "main_config_path": "/var/lib/openflare-agent/etc/nginx/nginx.conf",
+  "route_config_path": "/var/lib/openflare-agent/etc/nginx/conf.d/openflare_routes.conf",
+  "access_log_path": "/var/lib/openflare-agent/var/log/openflare/access.log",
+  "cert_dir": "/var/lib/openflare-agent/etc/nginx/certs",
+  "lua_dir": "/var/lib/openflare-agent/etc/nginx/lua",
+  "runtime_config_dir": "/var/lib/openflare-agent/etc/openflare",
   "heartbeat_interval": 10000,
   "request_timeout": 10000
 }
diff --git a/docs/reference/repository.md b/docs/reference/repository.md
index f243270f..d903cb3c 100644
--- a/docs/reference/repository.md
+++ b/docs/reference/repository.md
@@ -29,7 +29,7 @@
 | `config` | 配置读取与默认值 |
 | `heartbeat` | 心跳与版本摘要判断 |
 | `sync` | 配置拉取与应用编排 |
-| `nginx` / `openresty` | OpenResty 文件写入、校验、reload 与 Docker 模式管理 |
+| `nginx` / `openresty` | OpenResty 文件写入、校验、reload、启动与回滚 |
 | `state` | 本地状态与观测补报缓冲 |
 | `httpclient` | Server 通信 |
 | `protocol` | Agent API 协议类型 |