From 632c455229bca27683a8e22fb208d5aef57e1704 Mon Sep 17 00:00:00 2001 From: ryan Date: Sun, 31 May 2026 13:13:52 +0800 Subject: [PATCH] docs: update deployment instructions for Agent to recommend Docker method --- docs/en/guide/deployment.md | 62 +++++++++++++++++++----------------- docs/en/guide/quick-start.md | 21 +++++++++++- docs/guide/deployment.md | 62 +++++++++++++++++++----------------- docs/guide/quick-start.md | 21 +++++++++++- 4 files changed, 104 insertions(+), 62 deletions(-) diff --git a/docs/en/guide/deployment.md b/docs/en/guide/deployment.md index dd7dde99..583e0710 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 controls OpenResty through the OpenResty binary; Docker deployments run the Agent image that already includes OpenResty. +For production, use PostgreSQL for the Server database and set `SESSION_SECRET` explicitly. The recommended deployment method for the Agent is Docker deployment (i.e., running the Agent image that already includes OpenResty); it also supports shell-script installation or running manually. ## Topology @@ -129,7 +129,37 @@ Default port is `3000`. You can also set it explicitly: go run . --port 3000 --log-dir ./logs ``` -## Connect Agent +## Run Agent in Docker (Recommended) + +Docker deployment is the recommended deployment method for the Agent. In Docker deployments, directly run the Agent image. This image is built on top of the OpenResty image and includes both the Agent controller and the OpenResty binary. When `node_ip` is not explicitly configured, the Agent prioritizes obtaining the real public egress IP via a third-party API, avoiding registering the Docker bridge address as the node IP. + +Mounting the configuration file: + +```bash +docker pull ghcr.io/rain-kl/openflare-agent:latest +docker rm -f openflare-agent 2>/dev/null || true +docker run -d --name openflare-agent --restart unless-stopped \ + -p 80:80 -p 443:443 \ + -v openflare-agent-data:/data \ + -v ./agent.json:/etc/openflare/agent.json:ro \ + ghcr.io/rain-kl/openflare-agent:latest +``` + +Using environment variables: + +```bash +docker pull ghcr.io/rain-kl/openflare-agent:latest +docker rm -f openflare-agent 2>/dev/null || true +docker run -d --name openflare-agent --restart unless-stopped \ + -p 80:80 -p 443:443 \ + -e OPENFLARE_SERVER_URL=http://your-server:3000 \ + -e OPENFLARE_AGENT_TOKEN=YOUR_AGENT_TOKEN \ + ghcr.io/rain-kl/openflare-agent:latest +``` + +## Connect Agent (Script Installation) + +In addition to Docker deployment, you can also deploy the Agent on the local host using our installation script. With `discovery_token`: @@ -166,34 +196,6 @@ systemctl status openflare-agent journalctl -u openflare-agent -f ``` -## Run Agent in Docker - -In Docker deployments, directly run the Agent image. This image is built on top of the OpenResty image and includes both the Agent controller and the OpenResty binary. When `node_ip` is not explicitly configured, the Agent prioritizes obtaining the real public egress IP via a third-party API, avoiding registering the Docker bridge address as the node IP. - -Mounting the configuration file: - -```bash -docker pull ghcr.io/rain-kl/openflare-agent:latest -docker rm -f openflare-agent 2>/dev/null || true -docker run -d --name openflare-agent --restart unless-stopped \ - -p 80:80 -p 443:443 \ - -v openflare-agent-data:/data \ - -v ./agent.json:/etc/openflare/agent.json:ro \ - ghcr.io/rain-kl/openflare-agent:latest -``` - -Using environment variables: - -```bash -docker pull ghcr.io/rain-kl/openflare-agent:latest -docker rm -f openflare-agent 2>/dev/null || true -docker run -d --name openflare-agent --restart unless-stopped \ - -p 80:80 -p 443:443 \ - -e OPENFLARE_SERVER_URL=http://your-server:3000 \ - -e OPENFLARE_AGENT_TOKEN=YOUR_AGENT_TOKEN \ - ghcr.io/rain-kl/openflare-agent:latest -``` - ## Run Agent Manually From source: diff --git a/docs/en/guide/quick-start.md b/docs/en/guide/quick-start.md index 4858e2c5..70b38dff 100644 --- a/docs/en/guide/quick-start.md +++ b/docs/en/guide/quick-start.md @@ -102,7 +102,26 @@ 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 +## 3. Install/Run Agent + +The recommended deployment method for the Agent is Docker deployment (i.e., running the Agent image that already includes OpenResty); it also supports shell-script installation on the local host. + +### Option A: Run Agent in Docker (Recommended) + +Run the Agent Docker image on the proxy node: + +```bash +docker pull ghcr.io/rain-kl/openflare-agent:latest +docker rm -f openflare-agent 2>/dev/null || true +docker run -d --name openflare-agent --restart unless-stopped \ + -p 80:80 -p 443:443 \ + -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 +``` + +### Option B: Run the Installation Script (Local Host) Run the install script on the proxy node. diff --git a/docs/guide/deployment.md b/docs/guide/deployment.md index 1c13bad2..7dce3ee1 100644 --- a/docs/guide/deployment.md +++ b/docs/guide/deployment.md @@ -2,7 +2,7 @@ 你会学到：OpenFlare 的推荐部署方式、Server 与 Agent 的运行要求、源码启动方式、联调步骤、升级与卸载入口。 -生产环境建议使用 PostgreSQL 作为 Server 数据库，并为 Server 显式配置 `SESSION_SECRET`。Agent 统一通过 OpenResty 二进制控制运行时；Docker 部署请直接使用内置 OpenResty 的 Agent 镜像。 +生产环境建议使用 PostgreSQL 作为 Server 数据库，并为 Server 显式配置 `SESSION_SECRET`。Agent 部署方式推荐为 Docker 部署（即直接使用内置 OpenResty 的 Agent 镜像）；亦支持通过安装脚本或手动本地运行。 ## 部署拓扑 @@ -129,7 +129,37 @@ go run . go run . --port 3000 --log-dir ./logs ``` -## Agent 接入 +## Docker 运行 Agent（推荐） + +Docker 部署是 Agent 推荐的部署方式。Docker 部署时直接运行 Agent 镜像，该镜像基于 OpenResty 镜像制作，内置 Agent 控制器与 OpenResty 二进制。未显式配置 `node_ip` 时，Agent 会优先通过第三方 API 获取真实出口 IP，避免把 Docker 网桥地址登记为节点 IP。 + +挂载配置文件： + +```bash +docker pull ghcr.io/rain-kl/openflare-agent:latest +docker rm -f openflare-agent 2>/dev/null || true +docker run -d --name openflare-agent --restart unless-stopped \ + -p 80:80 -p 443:443 \ + -v openflare-agent-data:/data \ + -v ./agent.json:/etc/openflare/agent.json:ro \ + ghcr.io/rain-kl/openflare-agent:latest +``` + +使用环境变量： + +```bash +docker pull ghcr.io/rain-kl/openflare-agent:latest +docker rm -f openflare-agent 2>/dev/null || true +docker run -d --name openflare-agent --restart unless-stopped \ + -p 80:80 -p 443:443 \ + -e OPENFLARE_SERVER_URL=http://your-server:3000 \ + -e OPENFLARE_AGENT_TOKEN=YOUR_AGENT_TOKEN \ + ghcr.io/rain-kl/openflare-agent:latest +``` + +## Agent 接入（脚本安装） + +除了 Docker 部署外，也支持通过安装脚本将 Agent 部署在本地宿主机上。 使用 `discovery_token` 自动注册： @@ -166,34 +196,6 @@ systemctl status openflare-agent journalctl -u openflare-agent -f ``` -## Docker 运行 Agent - -Docker 部署时直接运行 Agent 镜像。该镜像基于 OpenResty 镜像制作，内置 Agent 控制器与 OpenResty 二进制。未显式配置 `node_ip` 时，Agent 会优先通过第三方 API 获取真实出口 IP，避免把 Docker 网桥地址登记为节点 IP。 - -挂载配置文件： - -```bash -docker pull ghcr.io/rain-kl/openflare-agent:latest -docker rm -f openflare-agent 2>/dev/null || true -docker run -d --name openflare-agent --restart unless-stopped \ - -p 80:80 -p 443:443 \ - -v openflare-agent-data:/data \ - -v ./agent.json:/etc/openflare/agent.json:ro \ - ghcr.io/rain-kl/openflare-agent:latest -``` - -使用环境变量： - -```bash -docker pull ghcr.io/rain-kl/openflare-agent:latest -docker rm -f openflare-agent 2>/dev/null || true -docker run -d --name openflare-agent --restart unless-stopped \ - -p 80:80 -p 443:443 \ - -e OPENFLARE_SERVER_URL=http://your-server:3000 \ - -e OPENFLARE_AGENT_TOKEN=YOUR_AGENT_TOKEN \ - ghcr.io/rain-kl/openflare-agent:latest -``` - ## 手动运行 Agent 源码运行： diff --git a/docs/guide/quick-start.md b/docs/guide/quick-start.md index ed949654..a1135126 100644 --- a/docs/guide/quick-start.md +++ b/docs/guide/quick-start.md @@ -102,7 +102,26 @@ Agent 可以用两类凭证接入： [需要确认：当前管理端中创建或查看 `discovery_token` 与节点 `agent_token` 的准确菜单路径] -## 3. 安装 Agent +## 3. 安装/运行 Agent + +Agent 部署方式推荐使用 Docker 部署（即直接运行内置 OpenResty 的 Agent 镜像）；亦支持通过安装脚本将 Agent 部署在本地宿主机上。 + +### 方式 A：Docker 运行 Agent（推荐） + +在代理节点上直接运行 Agent 镜像： + +```bash +docker pull ghcr.io/rain-kl/openflare-agent:latest +docker rm -f openflare-agent 2>/dev/null || true +docker run -d --name openflare-agent --restart unless-stopped \ + -p 80:80 -p 443:443 \ + -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 +``` + +### 方式 B：执行安装脚本（本地部署） 在代理节点上执行安装脚本。