优化文档

2026-10-03 23:06:36 +08:00 · 2026-05-09 18:07:35 +08:00
parent 797a15ae70
commit 2d6cc908f5
17 changed files with 763 additions and 1078 deletions
@@ -0,0 +1,262 @@
+# 部署说明
+
+本文档说明 OpenFlare `1.0.0` 之后的部署基线、联调入口、升级方式与 Agent 一键部署流程。
+
+## 前置条件
+
+Server：
+
+* Go 1.24+
+* Node.js 18+
+* 可写 SQLite 文件目录，或可访问的 PostgreSQL 实例
+
+Agent：
+
+* Go 1.24+
+* 对 Agent 数据目录有写权限
+* 本机模式下可执行 `openresty -t` 与 `openresty -s reload`
+* Docker 模式下具备 Docker 执行权限
+
+## Docker Compose 启动 Server
+
+推荐生产部署使用 PostgreSQL：
+
+```yaml
+services:
+  postgres:
+    image: postgres:17-alpine
+    restart: unless-stopped
+    environment:
+      POSTGRES_DB: openflare
+      POSTGRES_USER: openflare
+      POSTGRES_PASSWORD: replace-with-strong-password
+    volumes:
+      - postgres-data:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U openflare -d openflare"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+
+  openflare:
+    image: ghcr.io/rain-kl/openflare:latest
+    container_name: openflare
+    restart: unless-stopped
+    depends_on:
+      postgres:
+        condition: service_healthy
+    ports:
+      - "3000:3000"
+    environment:
+      SESSION_SECRET: replace-with-random-string
+      SQLITE_PATH: /data/openflare.db
+      DSN: postgres://openflare:replace-with-strong-password@postgres:5432/openflare?sslmode=disable
+      GIN_MODE: release
+      LOG_LEVEL: info
+    volumes:
+      - openflare-data:/data
+
+volumes:
+  postgres-data:
+  openflare-data:
+```
+
+```bash
+docker compose up -d
+```
+
+首次访问 `http://localhost:3000`，默认账号为 `root` / `123456`。登录后请立即修改默认密码。
+
+## 源码启动 Server
+
+先构建管理端前端：
+
+```bash
+cd openflare_server/web
+corepack enable
+pnpm install
+pnpm build
+```
+
+再启动 Server：
+
+```bash
+cd openflare_server
+export SESSION_SECRET='replace-with-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：
+
+```bash
+go install github.com/swaggo/swag/cmd/swag@v1.16.4
+cd openflare_server
+swag init -g main.go -o docs
+```
+
+## 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`：
+
+```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
+```
+
+使用节点专属 `agent_token`：
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/Rain-kl/OpenFlare/main/scripts/install-agent.sh | bash -s -- \
+  --server-url http://your-server:3000 \
+  --agent-token YOUR_AGENT_TOKEN
+```
+
+支持参数：
+
+| 参数 | 说明 |
+| --- | --- |
+| `--server-url` | Server 地址 |
+| `--discovery-token` | 首次自动注册 Token |
+| `--agent-token` | 节点专属 Token |
+| `--install-dir` | 安装目录 |
+| `--repo` | 下载 Agent 的仓库 |
+| `--no-service` | 不创建系统服务 |
+
+安装脚本会下载最新 Agent、生成 `agent.json`、创建 `openflare-agent.service` 并启动服务。
+
+## 手动启动 Agent
+
+源码运行：
+
+```bash
+cd openflare_agent
+export LOG_LEVEL='info'
+go run ./cmd/agent -config /path/to/agent.json
+```
+
+编译后二进制运行：
+
+```bash
+cd openflare_agent
+go build -o openflare-agent ./cmd/agent
+export LOG_LEVEL='info'
+./openflare-agent -config /path/to/agent.json
+```
+
+## 卸载 Agent
+
+如需彻底卸载 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 二进制的方式执行确认升级。
+
+## 常用验证命令
+
+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
+```
@@ -5,9 +5,10 @@
 推荐阅读顺序：

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

 如果你要参与开发，先阅读 [设计](../design/) 与 [开发约束](../design/development.md)，再进入代码修改。