From 196bdabc800634e2302c24379add02944a6e4690 Mon Sep 17 00:00:00 2001 From: ryan Date: Sat, 27 Jun 2026 15:57:55 +0800 Subject: [PATCH] docs(docs): update server start and quick-start docs to require PG/SQLite, Redis, and ClickHouse - Restructure docs/deployment/server.md into Docker (Quick Start, Production Recommended, Advanced with Jaeger) and Local deployment. - Update docs/guide/quick-start.md default docker-compose to use PostgreSQL, Redis, and ClickHouse as default. --- .env.example | 29 +-- README.md | 111 ++++++---- config.example.yaml | 2 +- docker-compose.yaml | 2 +- docs/deployment/server.md | 412 +++++++++++++++++++++++++++++-------- docs/deployment/upgrade.md | 45 ++-- docs/guide/quick-start.md | 98 ++++++--- 7 files changed, 480 insertions(+), 219 deletions(-) diff --git a/.env.example b/.env.example index fd1ec9fc..4dfe6367 100644 --- a/.env.example +++ b/.env.example @@ -4,19 +4,6 @@ # 环境变量优先级高于 config.yaml / config.docker.yaml # ────────────────────────────────────────────────────────────────────────────── -# ─── Docker Compose 服务端口映射 ─────────────────────────────────────────────── -APP_PORT=3000 -POSTGRES_PORT=5432 -REDIS_PORT=6379 -JAEGER_UI_PORT=16686 -JAEGER_OTLP_GRPC_PORT=4317 -JAEGER_OTLP_HTTP_PORT=4318 - -# ─── PostgreSQL 容器配置（仅 docker-compose 使用）──────────────────────────── -POSTGRES_DB=openflare -POSTGRES_USER=postgres -POSTGRES_PASSWORD=postgres - # ─── 时区 ───────────────────────────────────────────────────────────────────── TZ=Asia/Shanghai @@ -77,24 +64,10 @@ LOG_OUTPUT=stdout OTEL_EXPORTER_OTLP_ENDPOINT=http://jaeger:4317 OTEL_EXPORTER_OTLP_INSECURE=true # 设为 0 关闭 tracing；本地 Jaeger 调试建议设为 1.0 -OTEL_SAMPLING_RATE=1.0 +OTEL_SAMPLING_RATE=0.0 # 全局 Tracer 命名空间，默认为 github.com/Rain-kl/OpenFlare # OTEL_TRACER_NAME=github.com/Rain-kl/OpenFlare -# ─── S3 兼容存储（可选，默认关闭）────────────────────────────────────────── -# S3_ENABLED=false -# S3_ENDPOINT=https://.r2.cloudflarestorage.com -# S3_REGION=auto -# S3_BUCKET= -# S3_ACCESS_KEY_ID= -# S3_SECRET_ACCESS_KEY= -# S3_PATH_STYLE=false -# S3_CDN_URL= - # ─── Worker ──────────────────────────────────────────────────────────────────── # WORKER_CONCURRENCY=20 # WORKER_STRICT_PRIORITY=false - -# ─── Scheduler ───────────────────────────────────────────────────────────────── -# 未设置时默认为 @daily -# SCHEDULER_CLEANUP_CRON=0 */2 * * * diff --git a/README.md b/README.md index f23cc2ee..ee8f949b 100644 --- a/README.md +++ b/README.md @@ -52,12 +52,73 @@ OpenFlare 是开源 CDN 编排与边缘安全平台。它支持反向代理、 ### 1. 启动 Server -仓库根目录提供完整 `docker-compose.yaml`（PostgreSQL、Redis、ClickHouse、Jaeger）： +使用 docker-compose -```bash -cp .env.example .env -# 编辑 .env，至少修改 APP_SESSION_SECRET -docker compose up -d +```yaml +services: + openflare: + image: ghcr.io/rain-kl/openflare-server:latest + restart: unless-stopped + env_file: .env + environment: + TZ: ${TZ:-Asia/Shanghai} + ports: + - "3000:3000" + volumes: + - ./uploads:/app/uploads + depends_on: + postgres: + condition: service_healthy + redis: + condition: service_healthy + clickhouse: + condition: service_healthy + + postgres: + image: postgres:17-alpine + restart: unless-stopped + environment: + POSTGRES_DB: openflare + POSTGRES_USER: openflare + POSTGRES_PASSWORD: replace-with-strong-password + volumes: + - ./data/postgres_data:/var/lib/postgresql/data + healthcheck: + test: ["CMD-SHELL", "pg_isready -U openflare -d openflare"] + interval: 10s + timeout: 5s + retries: 5 + + redis: + image: valkey/valkey:8.0-alpine + restart: unless-stopped + command: ["valkey-server", "--appendonly", "yes"] + volumes: + - ./data/valkey:/data + healthcheck: + test: ["CMD", "valkey-cli", "ping"] + interval: 10s + timeout: 5s + retries: 5 + start_period: 5s + + clickhouse: + image: clickhouse/clickhouse-server:25.3-alpine + restart: unless-stopped + environment: + CLICKHOUSE_DB: openflare + CLICKHOUSE_USER: default + CLICKHOUSE_PASSWORD: 123456 + CLICKHOUSE_DEFAULT_ACCESS_MANAGEMENT: 1 + TZ: ${TZ:-Asia/Shanghai} + volumes: + - ./data/clickhouse_data:/var/lib/clickhouse + healthcheck: + test: ["CMD", "clickhouse-client", "--query", "SELECT 1"] + interval: 10s + timeout: 5s + retries: 5 + start_period: 15s ``` 详细部署说明见 [部署文档](https://open-flare.pages.dev/deployment/deployment)。 @@ -89,46 +150,6 @@ docker run -d --name openflare-agent --restart unless-stopped \ ghcr.io/rain-kl/openflare-agent:latest ``` -#### 本地部署 - -使用 `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 -``` - -安装脚本默认写入 `/opt/openflare-agent`，创建 `openflare-agent.service`，自动查找 `openresty`，并可重复执行以重装或升级 Agent。 - -### 3. 卸载 Agent - -如需彻底卸载 Agent 并清空本地数据，可执行： - -```bash -curl -fsSL https://raw.githubusercontent.com/Rain-kl/OpenFlare/main/scripts/uninstall-agent.sh | bash -``` - -卸载脚本会先停止并移除 `openflare-agent.service`、删除整个 `/opt/openflare-agent` 目录，不会删除本机 OpenResty。 - -### 4. 发布第一份配置 - -1. 登录管理端并新增反代规则 -2. 在发布前查看预览或变更摘要 -3. 激活新版本 -4. Agent 通过 WebSocket 通知或后续 heartbeat 拉取并应用配置 - -版本号格式固定为 `YYYYMMDD-NNN`，历史版本不可变，回滚通过重新激活旧版本完成。 - - ## 界面预览 ### 仪表盘总览 diff --git a/config.example.yaml b/config.example.yaml index 6d6ea579..ed696648 100644 --- a/config.example.yaml +++ b/config.example.yaml @@ -5,7 +5,7 @@ # ─── Application ──────────────────────────────────────────────────────────────── app: app_name: "openflare" - env: "development" # development | testing | production + env: "production" # development | testing | production addr: ":3000" node_id: 1 # Snowflake node ID (0-1023). Must be unique per instance. graceful_shutdown_timeout: 30 diff --git a/docker-compose.yaml b/docker-compose.yaml index 1f695df7..0833a23c 100644 --- a/docker-compose.yaml +++ b/docker-compose.yaml @@ -14,7 +14,7 @@ services: OTEL_EXPORTER_OTLP_INSECURE: ${OTEL_EXPORTER_OTLP_INSECURE:-true} OTEL_SAMPLING_RATE: ${OTEL_SAMPLING_RATE:-1.0} ports: - - "${APP_PORT:-3000}:3000" + - "3000:3000" volumes: - ./uploads:/app/uploads - ./data/sqlite:/app/data diff --git a/docs/deployment/server.md b/docs/deployment/server.md index f8cb47de..b3c8f7de 100644 --- a/docs/deployment/server.md +++ b/docs/deployment/server.md @@ -1,143 +1,379 @@ # 启动 Server -你会学到：如何从源码构建管理端前端、启动 OpenFlare Server、选择 SQLite 或 PostgreSQL，并访问 Swagger。 +你会学到：如何使用 Docker（分为快速启动、生产推荐、进阶版）部署，以及如何从源码本地部署 OpenFlare Server。 OpenFlare Server 是 Gin + GORM 单体控制面，负责管理端 UI、管理 API、Agent API、配置渲染、版本发布、数据存储与聚合查询。 -## 前置条件 +> [!IMPORTANT] +> **关于外部依赖**： +> OpenFlare 系统内建了对后台异步任务（Asynq 框架）及海量节点日志分析与度量指标（观测面板）的支持。因此，**无论采用何种部署模式，系统都必须依赖 Redis（或 Valkey）与 ClickHouse 的运行**。各个部署方案的主要差异在于主关系型数据库的选择（SQLite vs PostgreSQL）以及是否启用链路追踪服务（Jaeger）。 + +--- + +## 方式一：Docker 部署 (推荐) + +使用 Docker 部署可以免去本地配置 Go 与 Node.js 前端构建环境的麻烦。根据你的服务器硬件配置及业务需求，你可以选择以下三种方案之一： + +### 1. 快速启动 (SQLite + Redis + ClickHouse) + +> **适用场景**：测试体验、轻量化单机部署。 +> +> **特点**：主关系型数据库使用内建的 SQLite 文件 + +创建 `docker-compose.yaml` 文件： + +```yaml +version: '3.8' + +services: + openflare: + image: ghcr.io/rain-kl/openflare-server:latest + container_name: openflare-server + restart: unless-stopped + ports: + - "3000:3000" + volumes: + - ./openflare-data:/data + - ./uploads:/app/uploads + environment: + TZ: Asia/Shanghai + APP_SESSION_SECRET: 'replace-with-a-long-random-string' # 生产环境请替换为长随机字符串 + DB_ENABLED: "false" # 禁用 PostgreSQL，自动启用内置 SQLite 后备 + SQLITE_PATH: "/data/openflare.db" + REDIS_ENABLED: "true" + REDIS_ADDRS: "redis:6379" + CLICKHOUSE_ENABLED: "true" + CLICKHOUSE_HOSTS: "clickhouse:9000" + depends_on: + redis: + condition: service_healthy + clickhouse: + condition: service_healthy + + redis: + image: valkey/valkey:8.0-alpine + restart: unless-stopped + command: ["valkey-server", "--appendonly", "yes"] + volumes: + - ./data/valkey:/data + healthcheck: + test: ["CMD", "valkey-cli", "ping"] + interval: 10s + timeout: 5s + retries: 5 + + clickhouse: + image: clickhouse/clickhouse-server:25.3-alpine + restart: unless-stopped + environment: + CLICKHOUSE_DB: openflare + CLICKHOUSE_USER: default + CLICKHOUSE_PASSWORD: 123456 + CLICKHOUSE_DEFAULT_ACCESS_MANAGEMENT: 1 + TZ: Asia/Shanghai + volumes: + - ./data/clickhouse_data:/var/lib/clickhouse + healthcheck: + test: ["CMD", "clickhouse-client", "--query", "SELECT 1"] + interval: 10s + timeout: 5s + retries: 5 + start_period: 15s +``` + +运行启动命令： + +```bash +docker compose up -d +``` + +--- + +### 2. 生产推荐 (PostgreSQL + Redis + ClickHouse) + +> **适用场景**：生产环境、多节点集群管理、高并发高可用要求。 +> +> **特点**：完全分层架构。启用专用的 PostgreSQL 服务作为主关系数据库，Redis 负责高并发分布式锁、会话缓存与异步队列，ClickHouse 承载海量日志异步 Flush 与观测指标。 + +创建 `docker-compose.yaml` 文件： + +```yaml +services: + openflare: + image: ghcr.io/rain-kl/openflare-server:latest + restart: unless-stopped + env_file: .env + environment: + TZ: ${TZ:-Asia/Shanghai} + ports: + - "3000:3000" + volumes: + - ./uploads:/app/uploads + depends_on: + postgres: + condition: service_healthy + redis: + condition: service_healthy + clickhouse: + condition: service_healthy + + postgres: + image: postgres:17-alpine + restart: unless-stopped + environment: + POSTGRES_DB: openflare + POSTGRES_USER: openflare + POSTGRES_PASSWORD: replace-with-strong-password + volumes: + - ./data/postgres_data:/var/lib/postgresql/data + healthcheck: + test: ["CMD-SHELL", "pg_isready -U openflare -d openflare"] + interval: 10s + timeout: 5s + retries: 5 + + redis: + image: valkey/valkey:8.0-alpine + restart: unless-stopped + command: ["valkey-server", "--appendonly", "yes"] + volumes: + - ./data/valkey:/data + healthcheck: + test: ["CMD", "valkey-cli", "ping"] + interval: 10s + timeout: 5s + retries: 5 + start_period: 5s + + clickhouse: + image: clickhouse/clickhouse-server:25.3-alpine + restart: unless-stopped + environment: + CLICKHOUSE_DB: openflare + CLICKHOUSE_USER: default + CLICKHOUSE_PASSWORD: replace-with-clickhouse-password + CLICKHOUSE_DEFAULT_ACCESS_MANAGEMENT: 1 + TZ: ${TZ:-Asia/Shanghai} + volumes: + - ./data/clickhouse_data:/var/lib/clickhouse + healthcheck: + test: ["CMD", "clickhouse-client", "--query", "SELECT 1"] + interval: 10s + timeout: 5s + retries: 5 + start_period: 15s +``` + +创建对应的 `.env` 文件来配置系统环境变量（可复制并修改根目录下的 `.env.example`）： + +```bash +cp .env.example .env +# 编辑 .env 文件，填入对应的数据库、Redis、ClickHouse 连接地址、密码与 APP_SESSION_SECRET + +docker compose up -d +``` + +--- + +### 3. 进阶版 (含 Jaeger 链路追踪的完整编排) + +> **适用场景**：开发者调试、系统深度性能诊断、高级可观测性追溯。 +> +> **特点**：在“生产推荐”全家桶的基础上，联动拉起 Jaeger 作为 OpenTelemetry (OTel) 链路追踪的后端，收集 Server 运行时各个 API 请求的 Span Trace 信息。 + +创建 `docker-compose.yaml` 文件： + +```yaml +version: '3.8' + +services: + openflare: + image: ghcr.io/rain-kl/openflare-server:latest + restart: unless-stopped + env_file: .env + environment: + TZ: ${TZ:-Asia/Shanghai} + OTEL_EXPORTER_OTLP_ENDPOINT: "http://jaeger:4317" + OTEL_EXPORTER_OTLP_INSECURE: "true" + OTEL_SAMPLING_RATE: "1.0" # 本地调试建议设为 1.0 以采样所有 Trace + ports: + - "3000:3000" + volumes: + - ./uploads:/app/uploads + depends_on: + postgres: + condition: service_healthy + redis: + condition: service_healthy + clickhouse: + condition: service_healthy + jaeger: + condition: service_started + + postgres: + image: postgres:17-alpine + restart: unless-stopped + environment: + POSTGRES_DB: openflare + POSTGRES_USER: openflare + POSTGRES_PASSWORD: replace-with-strong-password + volumes: + - ./data/postgres_data:/var/lib/postgresql/data + healthcheck: + test: ["CMD-SHELL", "pg_isready -U openflare -d openflare"] + interval: 10s + timeout: 5s + retries: 5 + + redis: + image: valkey/valkey:8.0-alpine + restart: unless-stopped + command: ["valkey-server", "--appendonly", "yes"] + volumes: + - ./data/valkey:/data + healthcheck: + test: ["CMD", "valkey-cli", "ping"] + interval: 10s + timeout: 5s + retries: 5 + start_period: 5s + + jaeger: + image: jaegertracing/jaeger:2.19.0 + restart: unless-stopped + environment: + TZ: ${TZ:-Asia/Shanghai} + ports: + - "16686:16686" # Web UI 端口 + - "4317:4317" # OTLP gRPC 接收端口 + - "4318:4318" # OTLP HTTP 接收端口 + + clickhouse: + image: clickhouse/clickhouse-server:25.3-alpine + restart: unless-stopped + environment: + CLICKHOUSE_DB: openflare + CLICKHOUSE_USER: default + CLICKHOUSE_PASSWORD: replace-with-clickhouse-password + CLICKHOUSE_DEFAULT_ACCESS_MANAGEMENT: 1 + TZ: ${TZ:-Asia/Shanghai} + volumes: + - ./data/clickhouse_data:/var/lib/clickhouse + healthcheck: + test: ["CMD", "clickhouse-client", "--query", "SELECT 1"] + interval: 10s + timeout: 5s + retries: 5 + start_period: 15s +``` + +启动并验证： + +```bash +cp .env.example .env +# 编辑 .env 文件并确保设置好 APP_SESSION_SECRET 密码 + +docker compose up -d +``` +启动后可以通过访问 `http://localhost:16686` 打开 Jaeger 监控端查看系统 Span 链路。 + +--- + +## 方式二：本地部署 (源码/二进制启动) + +如果你不希望使用 Docker，也可以直接在本地或虚拟机上从源码构建和运行 Server。由于后台异步任务和可观测指标分析为系统核心防线，**本地部署时依然需要连接外部 Redis 与 ClickHouse 实例**。 + +### 前置条件 | 项目 | 要求 | | --- | --- | | Go | `1.25+` | | Node.js | `18+` | | pnpm | 推荐通过 `corepack enable` 使用项目声明的 pnpm | -| 数据库 | SQLite 文件目录可写，或可访问的 PostgreSQL 实例 | +| 外部服务 | 必须在本地或远端运行 Redis (Valkey) 和 ClickHouse 实例 | -生产环境必须配置 `app.session_secret`（或 `APP_SESSION_SECRET`），并优先使用 PostgreSQL、Redis 与 ClickHouse。 +### 1. 构建管理端前端 -## 构建管理端前端 - -Go Server 会嵌入 `frontend/out` 静态产物（构建后复制到 `internal/router/root/dist`）。源码启动前先构建前端： +Go Server 运行时需要嵌入前端静态资源。编译 Go 二进制前需要先构建前端静态产物并输出到 Go 服务目录： ```bash cd frontend corepack enable pnpm install pnpm build:embed +cd .. ``` -常用前端检查： +> **常用前端代码检查命令**： +> * `pnpm lint` +> * `pnpm typecheck` -```bash -pnpm lint -pnpm typecheck -pnpm test -``` +### 2. 使用 SQLite 启动 -## 使用 SQLite 启动 +关系数据库存储在本地 SQLite 文件，但依然需要提供 Redis 和 ClickHouse 连接配置： ```bash cp config.example.yaml config.yaml -# 编辑 config.yaml：设置 session_secret，并将 database.enabled 设为 false +# 编辑 config.yaml： +# 1. 设置 app.session_secret 为一个随机的长字符串 +# 2. 将 database.enabled 设为 false 以启用内置 SQLite +# 3. 将 redis.addrs 与 clickhouse.hosts 修改为你的本地/局域网服务连接信息 + +# 启动 Server（默认融合模式） go run main.go all ``` -默认监听 `3000` 端口，访问： - -```text -http://localhost:3000 -``` - -## 使用 PostgreSQL 启动 +### 3. 使用 PostgreSQL 启动 ```bash cp config.example.yaml config.yaml -# 编辑 config.yaml：设置 session_secret、database.* 与 redis.* +# 编辑 config.yaml： +# 1. 设置 app.session_secret +# 2. 将 database.enabled 设为 true，并完整设置 database.*、redis.*、clickhouse.* 字段连接参数 + +# 启动 Server（默认融合模式） go run main.go all ``` -生产环境推荐分进程部署：`go run main.go api`、`go run main.go worker`、`go run main.go scheduler`。 - -## 使用 Docker 启动 - -使用 Docker 部署可以免去本地配置 Go 与 Node.js 前端构建环境的麻烦。OpenFlare 官方提供了完整的 Dockerfile 与 Compose 配置，支持独立容器启动及多服务联动部署。 - -### 1. 使用 Docker Run 极速启动（以 SQLite 为例） - -确保当前目录下已创建用于持久化数据库和日志的数据卷目录。运行以下命令启动 Server： - -```bash -# 创建本地挂载目录 -mkdir -p ./openflare-data - -# 启动容器 -docker run -d \ - --name openflare-server \ - -p 3000:3000 \ - -v $(pwd)/openflare-data:/data \ - -e APP_SESSION_SECRET='replace-with-a-long-random-string' \ - -e DB_ENABLED=false \ - -e SQLITE_PATH='/data/openflare.db' \ - -e LOG_LEVEL='info' \ - ghcr.io/rain-kl/openflare-server:latest -``` - -启动参数说明： -* **`-p 3000:3000`**：映射宿主机 `3000` 端口到容器内 `3000` 端口。 -* **`-v $(pwd)/openflare-data:/data`**：挂载本地目录到容器的 `/data`，确保数据库文件在重启或重建容器时不丢失。 -* **`APP_SESSION_SECRET`**：Session Cookie 签名密钥，生产环境必须配置。 - --- -### 2. 使用 Docker Compose 一键启动 - -推荐在生产环境使用仓库根目录的 `docker-compose.yaml`，自动编排 PostgreSQL、Redis、ClickHouse 与 Jaeger： - -```bash -cp .env.example .env -docker compose up -d -``` - -## 命令行参数 - -```bash -go run main.go api # 仅 API -go run main.go worker # 仅 Worker -go run main.go scheduler # 仅 Scheduler -go run main.go all # 融合模式（默认） -``` - -监听地址与日志由 `config.yaml`（`app.addr`、`log.*`）或 `APP_ADDR`、`LOG_*` 环境变量控制。 - ## 首次登录 -默认账号： +Server 默认监听 `3000` 端口，启动成功后可以使用浏览器访问：`http://localhost:3000`。 + +默认管理员账户信息如下： | 用户名 | 密码 | | --- | --- | | `root` | `123456` | -首次登录后请立即修改默认密码。 +> [!WARNING] +> 为了你的系统安全，首次登录后请立即前往个人设置页面修改默认密码。 -## 配置要点 +--- -复制 `config.example.yaml` 为 `config.yaml`，或使用 `.env.example` 中的环境变量。关键默认值： +## 常用运维指南 -| 项 | 值 | -| --- | --- | -| 监听地址 | `:3000` | -| PostgreSQL 库名 | `openflare` | -| SQLite 后备 | `openflare.db` | -| `application_name` | `openflare-server` | -| Redis 键前缀 | `openflare:` | +### 1. 命令行子服务分进程启动 -也可使用 `docker compose up`（见根目录 `docker-compose.yaml`）拉起完整依赖栈。 - -### 验证 +在大型生产部署中，你可以选择将 Server 按职责拆分为多个进程运行： ```bash +go run main.go api # 仅启动管理端与节点通信的 API 服务 +go run main.go worker # 仅启动后台任务的 Worker 服务 +go run main.go scheduler # 仅启动定时任务的 Scheduler 服务 +go run main.go all # 融合模式（在一进程内运行上述所有服务，默认） +``` + +### 2. 状态验证 + +```bash +# 验证编译是否通过 go build ./... + +# 运行内部单元测试 go test ./internal/apps/openflare/... -count=1 +# 检查服务健康状态 curl http://127.0.0.1:3000/api/v1/d/status ``` diff --git a/docs/deployment/upgrade.md b/docs/deployment/upgrade.md index fc3bbcc7..acae5ad3 100644 --- a/docs/deployment/upgrade.md +++ b/docs/deployment/upgrade.md @@ -6,47 +6,26 @@ ## Server 升级 -Root 用户可以在管理端顶栏检查并升级 Server 正式版。也可以通过上传 Server 二进制的方式执行确认升级。 - -如需尝试 preview 版本，可手动检查对应发布。生产环境建议优先使用正式版。 - -升级后确认： +拉取最新镜像升级 ```bash -docker compose ps -docker compose logs -n 100 openflare +docker compose pull +docker compose up ``` 如果是源码部署，重新启动 Server 后确认日志中没有数据库迁移或启动错误。 ## Agent 升级 -节点 Agent 默认只跟随正式版自动更新。preview 升级需要手动触发。 +Agent 可以随意升级，升级后会在下次心跳时自动拉取最新配置。升级方式： -安装脚本可重复执行，用于重装或升级 Agent： - -```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 ``` - -注意：当前安装脚本重装时会删除整个安装目录，包括旧 `agent.json`、本地状态、缓存数据和下载的二进制。执行前请确认手头仍有可用 Token。 - -升级后确认： - -```bash -systemctl status openflare-agent -journalctl -u openflare-agent -n 100 --no-pager +docker pull ghcr.io/rain-kl/openflare-agent:beta +docker rm -f openflare-agent 2>/dev/null || true +docker run -d --name openflare-agent --restart unless-stopped \ + -p 80:80 -p 443:443/tcp -p 443:443/udp \ + -e OPENFLARE_SERVER_URL= \ + -e OPENFLARE_AGENT_TOKEN= \ + ghcr.io/rain-kl/openflare-agent:beta + ``` - -## 数据维护 - -管理端设置页可以维护观测数据自动清理策略： - -| 配置项 | 说明 | -| --- | --- | -| `DatabaseAutoCleanupEnabled` | 是否启用每日自动清理 | -| `DatabaseAutoCleanupRetentionDays` | 自动清理保留天数，至少 1 天 | - -开启后，Server 会在每天凌晨 3 点清理访问日志、指标快照与请求报告。 \ No newline at end of file diff --git a/docs/guide/quick-start.md b/docs/guide/quick-start.md index a67bd983..096103a9 100644 --- a/docs/guide/quick-start.md +++ b/docs/guide/quick-start.md @@ -16,7 +16,7 @@ Agent 统一通过 OpenResty 二进制控制运行时。本地部署需要节点 | 项目 | 要求 | | --- | --- | -| Docker / Docker Compose | 用于启动 Server 和 PostgreSQL；如果采用 Docker Agent 镜像，也用于运行 Agent | +| Docker / Docker Compose | 用于启动 Server 及其依赖的 PostgreSQL、Redis 和 ClickHouse 容器；如采用 Docker Agent，也用于运行 Agent | | OpenResty | 本地安装 Agent 时需要可执行 `openresty`，或在安装脚本中指定路径 | | 可访问端口 | Server 默认监听 `3000`，Agent 节点需要能访问 Server 地址 | | 浏览器 | 用于访问管理端 | @@ -24,12 +24,47 @@ Agent 统一通过 OpenResty 二进制控制运行时。本地部署需要节点 - **Docker**：`20.10.0+` - **Docker Compose**：`2.0.0+` +--- + ## 1. 启动 Server -在空目录中创建 `docker-compose.yml`： +为了保证异步任务队列（Asynq 框架）及可观测流量看板功能完整运行，快速开始推荐采用 **PostgreSQL + Redis + ClickHouse** 经典单机版编排。 + +在空目录中创建 `docker-compose.yaml`： ```yaml +version: '3.8' + services: + openflare: + image: ghcr.io/rain-kl/openflare-server:latest + container_name: openflare-server + restart: unless-stopped + ports: + - "3000:3000" + volumes: + - ./uploads:/app/uploads + environment: + TZ: Asia/Shanghai + APP_SESSION_SECRET: 'replace-with-a-long-random-string' # 生产环境请替换为长随机字符串 + DB_ENABLED: "true" + DB_HOST: "postgres" + DB_PORT: "5432" + DB_USERNAME: "openflare" + DB_PASSWORD: "replace-with-strong-password" + DB_NAME: "openflare" + REDIS_ENABLED: "true" + REDIS_ADDRS: "redis:6379" + CLICKHOUSE_ENABLED: "true" + CLICKHOUSE_HOSTS: "clickhouse:9000" + depends_on: + postgres: + condition: service_healthy + redis: + condition: service_healthy + clickhouse: + condition: service_healthy + postgres: image: postgres:17-alpine restart: unless-stopped @@ -38,32 +73,42 @@ services: POSTGRES_USER: openflare POSTGRES_PASSWORD: replace-with-strong-password volumes: - - postgres-data:/var/lib/postgresql/data + - ./data/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 + redis: + image: valkey/valkey:8.0-alpine restart: unless-stopped - depends_on: - postgres: - condition: service_healthy - ports: - - "3000:3000" - environment: - JWT_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 + command: ["valkey-server", "--appendonly", "yes"] volumes: - - openflare-data:/data + - ./data/valkey:/data + healthcheck: + test: ["CMD", "valkey-cli", "ping"] + interval: 10s + timeout: 5s + retries: 5 -volumes: - postgres-data: - openflare-data: + clickhouse: + image: clickhouse/clickhouse-server:25.3-alpine + restart: unless-stopped + environment: + CLICKHOUSE_DB: openflare + CLICKHOUSE_USER: default + CLICKHOUSE_PASSWORD: 123456 + CLICKHOUSE_DEFAULT_ACCESS_MANAGEMENT: 1 + TZ: Asia/Shanghai + volumes: + - ./data/clickhouse_data:/var/lib/clickhouse + healthcheck: + test: ["CMD", "clickhouse-client", "--query", "SELECT 1"] + interval: 10s + timeout: 5s + retries: 5 + start_period: 15s ``` 启动服务： @@ -79,7 +124,7 @@ docker compose ps docker compose logs -f openflare ``` -看到 `server listening` 且 `openflare` 容器状态为 running 后，访问： +看到 `server listening` 且 `openflare-server` 容器状态为 running 后，使用浏览器打开： ```text http://localhost:3000 @@ -91,7 +136,10 @@ http://localhost:3000 | --- | --- | | `root` | `123456` | -首次登录后请立即修改默认密码。 +> [!WARNING] +> 为了你的系统安全，首次登录后请立即修改默认密码。 + +--- ## 2. 准备 Agent Token @@ -107,6 +155,8 @@ Agent 可以用两类凭证接入： - **`discovery_token`** 获取菜单路径：「系统设置」->「自动注册」 - **`agent_token`** 获取菜单路径：「节点管理」->「新增节点」 +--- + ## 3. 安装/运行 Agent Agent 部署方式推荐使用 Docker 部署（即直接运行内置 OpenResty 的 Agent 镜像）；亦支持通过安装脚本将 Agent 部署在本地宿主机上。 @@ -164,6 +214,8 @@ journalctl -u openflare-agent -f 如果没有 systemd，脚本会输出手动启动命令。 +--- + ## 4. 后续步骤 完成控制面板启动和 Agent 节点接入后，你已经成功搭建好了 OpenFlare 网关的基础运行环境。接下来你可以按顺序继续阅读以下两份指南，开始部署你的第一个反代站点： @@ -173,13 +225,14 @@ journalctl -u openflare-agent -f 2. **完整配置反向代理（HTTPS 与源站管理）**： * 请参阅 [新建反代配置](./proxy-config.md)。它将指导你从证书导入与申请开始，配置域名 HTTPS 证书绑定、源站管理并预览发布。 +--- ## 常见失败原因 | 现象 | 排查方向 | | --- | --- | | 浏览器打不开管理端 | 确认 `docker compose ps` 中 Server 正在运行，宿主机 `3000` 端口没有被占用 | -| 登录后数据无法保存 | 检查 PostgreSQL 容器健康状态，以及 `DSN` 中的用户名、密码、库名是否一致 | +| 登录后数据无法保存/提示报错 | 检查 PostgreSQL 容器健康状态，以及 `DB_PASSWORD` / 密码等连接参数是否一致 | | Agent 无法注册 | 确认 Agent 节点能访问 `--server-url`，并检查 Token 是否填错或已失效 | | Agent 在线但没有应用配置 | 确认网站配置已启用，并且已经发布并激活版本 | | OpenResty 应用失败 | 查看节点应用记录和 `journalctl -u openflare-agent`，重点检查域名、证书、上游地址和端口占用 | @@ -198,4 +251,3 @@ journalctl -u openflare-agent -f * **内网穿透客户端部署**：阅读 [部署 OpenFlared](../deployment/openflared.md) 了解如何在内网服务器侧运行穿透守护客户端（frpc）。 * **生产部署拓扑参考**：阅读 [部署说明](../deployment/deployment.md) 了解生产高可用拓扑和整体网络规划。 * **系统升级与日常维护**：阅读 [升级与维护](../deployment/upgrade.md) 了解如何平滑升级 Server 和各代理节点 Agent。 -