mirror of
https://github.com/Rain-kl/OpenFlare.git
synced 2026-10-01 14:46:36 +08:00
docs: update
This commit is contained in:
ryan
+13
-151
@@ -6,7 +6,8 @@ OpenFlare Server 是 Gin + GORM 单体控制面，负责管理端 UI、管理 AP
|
||||
|
||||
> [!IMPORTANT]
|
||||
> **关于外部依赖**：
|
||||
> OpenFlare 系统内建了对后台异步任务（Asynq 框架）及海量节点日志分析与度量指标（观测面板）的支持。因此，**无论采用何种部署模式，系统都必须依赖 Redis（或 Valkey）与 ClickHouse 的运行**。各个部署方案的主要差异在于主关系型数据库的选择（SQLite vs PostgreSQL）以及是否启用链路追踪服务（Jaeger）。
|
||||
> OpenFlare 系统内建了对后台异步任务（Asynq 框架）的支持。因此，**无论采用何种部署模式，系统都必须依赖 Redis（或 Valkey）**。各个部署方案的主要差异在于主关系型数据库的选择（SQLite vs PostgreSQL）以及是否启用链路追踪服务（Jaeger）。
|
||||
> 若业务流量过大, 建议使用 ClickHouse 存储日志。
|
||||
|
||||
> [!TIP]
|
||||
> **ClickHouse 服务端性能配置（推荐挂载）**
|
||||
@@ -37,11 +38,11 @@ volumes:
|
||||
|
||||
使用 Docker 部署可以免去本地配置 Go 与 Node.js 前端构建环境的麻烦。根据你的服务器硬件配置及业务需求，你可以选择以下三种方案之一：
|
||||
|
||||
### 1. 快速启动 (SQLite + Redis + ClickHouse)
|
||||
### 1. 快速启动 (SQLite + Redis)
|
||||
|
||||
> **适用场景**：测试体验、轻量化单机部署。
|
||||
>
|
||||
> **特点**：主关系型数据库使用内建的 SQLite 文件
|
||||
> **特点**：主关系型数据库使用 SQLite
|
||||
|
||||
创建 `docker-compose.yaml` 文件：
|
||||
|
||||
@@ -70,8 +71,6 @@ services:
|
||||
depends_on:
|
||||
redis:
|
||||
condition: service_healthy
|
||||
clickhouse:
|
||||
condition: service_healthy
|
||||
|
||||
redis:
|
||||
image: valkey/valkey:8.0-alpine
|
||||
@@ -84,47 +83,13 @@ services:
|
||||
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
|
||||
ulimits:
|
||||
nofile:
|
||||
soft: 262144
|
||||
hard: 262144
|
||||
volumes:
|
||||
- ./data/clickhouse_data:/var/lib/clickhouse
|
||||
- ./config/clickhouse/performance.xml:/etc/clickhouse-server/config.d/performance.xml:ro
|
||||
healthcheck:
|
||||
test: ["CMD", "clickhouse-client", "--user", "default", "--password", "123456", "--query", "SELECT 1"]
|
||||
interval: 10s
|
||||
timeout: 5s
|
||||
retries: 5
|
||||
start_period: 15s
|
||||
```
|
||||
|
||||
运行启动命令：
|
||||
|
||||
```bash
|
||||
mkdir -p ./config/clickhouse
|
||||
curl -fsSL -o ./config/clickhouse/performance.xml \
|
||||
https://raw.githubusercontent.com/Rain-kl/OpenFlare/refs/heads/main/config/clickhouse/performance.xml
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 2. 生产推荐 (PostgreSQL + Redis + ClickHouse)
|
||||
### 2. 小流量业务场景 (PostgreSQL + Redis)
|
||||
|
||||
> **适用场景**：生产环境、多节点集群管理、高并发高可用要求。
|
||||
>
|
||||
> **特点**：完全分层架构。启用专用的 PostgreSQL 服务作为主关系数据库，Redis 负责高并发分布式锁、会话缓存与异步队列，ClickHouse 承载海量日志异步 Flush 与观测指标。
|
||||
> **适用场景**：生产环境、业务流量中小, PostgreSQL 不会成为日志记录的瓶颈。
|
||||
|
||||
创建 `docker-compose.yaml` 文件：
|
||||
|
||||
@@ -145,8 +110,6 @@ services:
|
||||
condition: service_healthy
|
||||
redis:
|
||||
condition: service_healthy
|
||||
clickhouse:
|
||||
condition: service_healthy
|
||||
|
||||
postgres:
|
||||
image: postgres:17-alpine
|
||||
@@ -176,45 +139,18 @@ services:
|
||||
retries: 5
|
||||
start_period: 5s
|
||||
|
||||
clickhouse:
|
||||
image: clickhouse/clickhouse-server:25.3-alpine
|
||||
restart: unless-stopped
|
||||
environment:
|
||||
CLICKHOUSE_DB: ${CLICKHOUSE_NAME:-openflare}
|
||||
CLICKHOUSE_USER: ${CLICKHOUSE_USERNAME:-default}
|
||||
CLICKHOUSE_PASSWORD: ${CLICKHOUSE_PASSWORD:-replace-with-clickhouse-password}
|
||||
CLICKHOUSE_DEFAULT_ACCESS_MANAGEMENT: 1
|
||||
TZ: ${TZ:-Asia/Shanghai}
|
||||
ulimits:
|
||||
nofile:
|
||||
soft: 262144
|
||||
hard: 262144
|
||||
volumes:
|
||||
- openflare_clickhouse_data:/var/lib/clickhouse
|
||||
- ./config/clickhouse/performance.xml:/etc/clickhouse-server/config.d/performance.xml:ro
|
||||
healthcheck:
|
||||
test: ["CMD", "clickhouse-client", "--user", "${CLICKHOUSE_USERNAME:-default}", "--password", "${CLICKHOUSE_PASSWORD:-replace-with-clickhouse-password}", "--query", "SELECT 1"]
|
||||
interval: 10s
|
||||
timeout: 5s
|
||||
retries: 5
|
||||
start_period: 15s
|
||||
|
||||
volumes:
|
||||
openflare_uploads:
|
||||
openflare_postgres_data:
|
||||
openflare_redis_data:
|
||||
openflare_clickhouse_data:
|
||||
```
|
||||
|
||||
创建对应的 `.env` 文件来配置系统环境变量（可复制并修改根目录下的 `.env.example`）：
|
||||
|
||||
```bash
|
||||
mkdir -p ./config/clickhouse
|
||||
curl -fsSL -o ./config/clickhouse/performance.xml \
|
||||
https://raw.githubusercontent.com/Rain-kl/OpenFlare/refs/heads/main/config/clickhouse/performance.xml
|
||||
curl -o .env.example https://raw.githubusercontent.com/Rain-kl/OpenFlare/refs/heads/main/.env.example
|
||||
cp .env.example .env
|
||||
# 编辑 .env 文件，填入对应的数据库、Redis、ClickHouse 连接地址、密码与 APP_SESSION_SECRET
|
||||
# 编辑 .env 文件，填入对应的数据库、Redis、密码与 APP_SESSION_SECRET
|
||||
|
||||
docker compose up -d
|
||||
```
|
||||
@@ -223,9 +159,9 @@ docker compose up -d
|
||||
|
||||
### 3. 进阶版 (含 Jaeger 链路追踪的完整编排)
|
||||
|
||||
> **适用场景**：开发者调试、系统深度性能诊断、高级可观测性追溯。
|
||||
> **适用场景**：大流量场景, 需要进行链路性能指标追踪。
|
||||
>
|
||||
> **特点**：在“生产推荐”全家桶的基础上，联动拉起 Jaeger 作为 OpenTelemetry (OTel) 链路追踪的后端，收集 Server 运行时各个 API 请求的 Span Trace 信息。
|
||||
> **特点**：在“生产推荐”全家桶的基础上，使用 ClickHouse 存储日志, 联动 Jaeger 作为 OpenTelemetry (OTel) 链路追踪的后端。
|
||||
|
||||
创建 `docker-compose.yaml` 文件：
|
||||
|
||||
@@ -340,64 +276,6 @@ docker compose up -d
|
||||
|
||||
---
|
||||
|
||||
## 方式二：本地部署 (源码/二进制启动)
|
||||
|
||||
如果你不希望使用 Docker，也可以直接在本地或虚拟机上从源码构建和运行 Server。由于后台异步任务和可观测指标分析为系统核心防线，**本地部署时依然需要连接外部 Redis 与 ClickHouse 实例**。
|
||||
|
||||
### 前置条件
|
||||
|
||||
| 项目 | 要求 |
|
||||
| --- | --- |
|
||||
| Go | `1.25+` |
|
||||
| Node.js | `18+` |
|
||||
| pnpm | 推荐通过 `corepack enable` 使用项目声明的 pnpm |
|
||||
| 外部服务 | 必须在本地或远端运行 Redis (Valkey) 和 ClickHouse 实例；ClickHouse 建议挂载仓库提供的 `performance.xml`（见上文「ClickHouse 服务端性能配置」） |
|
||||
|
||||
### 1. 构建管理端前端
|
||||
|
||||
Go Server 运行时需要嵌入前端静态资源。编译 Go 二进制前需要先构建前端静态产物并输出到 Go 服务目录：
|
||||
|
||||
```bash
|
||||
cd frontend
|
||||
corepack enable
|
||||
pnpm install
|
||||
pnpm build:embed
|
||||
cd ..
|
||||
```
|
||||
|
||||
> **常用前端代码检查命令**：
|
||||
> * `pnpm lint`
|
||||
> * `pnpm typecheck`
|
||||
|
||||
### 2. 使用 SQLite 启动
|
||||
|
||||
关系数据库存储在本地 SQLite 文件，但依然需要提供 Redis 和 ClickHouse 连接配置：
|
||||
|
||||
```bash
|
||||
cp config.example.yaml config.yaml
|
||||
# 编辑 config.yaml：
|
||||
# 1. 设置 app.session_secret 为一个随机的长字符串
|
||||
# 2. 将 database.enabled 设为 false 以启用内置 SQLite
|
||||
# 3. 将 redis.addrs 与 clickhouse.hosts 修改为你的本地/局域网服务连接信息
|
||||
|
||||
# 启动 Server（默认融合模式）
|
||||
go run main.go all
|
||||
```
|
||||
|
||||
### 3. 使用 PostgreSQL 启动
|
||||
|
||||
```bash
|
||||
cp config.example.yaml config.yaml
|
||||
# 编辑 config.yaml：
|
||||
# 1. 设置 app.session_secret
|
||||
# 2. 将 database.enabled 设为 true，并完整设置 database.*、redis.*、clickhouse.* 字段连接参数
|
||||
|
||||
# 启动 Server（默认融合模式）
|
||||
go run main.go all
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 首次登录
|
||||
|
||||
Server 默认监听 `3000` 端口，启动成功后可以使用浏览器访问：`http://localhost:3000`。
|
||||
@@ -413,28 +291,12 @@ Server 默认监听 `3000` 端口，启动成功后可以使用浏览器访问
|
||||
|
||||
---
|
||||
|
||||
## 常用运维指南
|
||||
|
||||
### 1. 命令行子服务分进程启动
|
||||
## 分布式部署
|
||||
|
||||
在大型生产部署中，你可以选择将 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
|
||||
go run main.go api # 仅启动管理端与节点通信的 API 服务
|
||||
go run main.go worker # 仅启动后台任务的 Worker 服务
|
||||
go run main.go scheduler # 仅启动定时任务的 Scheduler 服务
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user