mirror of
https://github.com/Rain-kl/OpenFlare.git
synced 2026-09-28 05:46:36 +08:00
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.
This commit is contained in:
ryan
+1
-28
@@ -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://<account-id>.r2.cloudflarestorage.com
|
||||
# S3_REGION=auto
|
||||
# S3_BUCKET=<bucket-name>
|
||||
# S3_ACCESS_KEY_ID=<access-key>
|
||||
# S3_SECRET_ACCESS_KEY=<secret-key>
|
||||
# S3_PATH_STYLE=false
|
||||
# S3_CDN_URL=
|
||||
|
||||
# ─── Worker ────────────────────────────────────────────────────────────────────
|
||||
# WORKER_CONCURRENCY=20
|
||||
# WORKER_STRICT_PRIORITY=false
|
||||
|
||||
# ─── Scheduler ─────────────────────────────────────────────────────────────────
|
||||
# 未设置时默认为 @daily
|
||||
# SCHEDULER_CLEANUP_CRON=0 */2 * * *
|
||||
|
||||
@@ -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`，历史版本不可变，回滚通过重新激活旧版本完成。
|
||||
|
||||
|
||||
## 界面预览
|
||||
|
||||
### 仪表盘总览
|
||||
|
||||
+1
-1
@@ -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
|
||||
|
||||
+1
-1
@@ -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
|
||||
|
||||
+324
-88
@@ -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
|
||||
```
|
||||
|
||||
+11
-32
@@ -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
|
||||
```
|
||||
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=<OPENFLARE_SERVER_URL> \
|
||||
-e OPENFLARE_AGENT_TOKEN=<OPENFLARE_AGENT_TOKEN> \
|
||||
ghcr.io/rain-kl/openflare-agent:beta
|
||||
|
||||
注意：当前安装脚本重装时会删除整个安装目录，包括旧 `agent.json`、本地状态、缓存数据和下载的二进制。执行前请确认手头仍有可用 Token。
|
||||
|
||||
升级后确认：
|
||||
|
||||
```bash
|
||||
systemctl status openflare-agent
|
||||
journalctl -u openflare-agent -n 100 --no-pager
|
||||
```
|
||||
|
||||
## 数据维护
|
||||
|
||||
管理端设置页可以维护观测数据自动清理策略：
|
||||
|
||||
| 配置项 | 说明 |
|
||||
| --- | --- |
|
||||
| `DatabaseAutoCleanupEnabled` | 是否启用每日自动清理 |
|
||||
| `DatabaseAutoCleanupRetentionDays` | 自动清理保留天数，至少 1 天 |
|
||||
|
||||
开启后，Server 会在每天凌晨 3 点清理访问日志、指标快照与请求报告。
|
||||
+75
-23
@@ -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。
|
||||
|
||||
|
||||
Reference in New Issue
Block a user