tcjlj/OpenFlare
1
0
Fork 0
mirror of https://github.com/Rain-kl/OpenFlare.git synced 2026-09-30 14:26:36 +08:00
Code Issues Packages Projects Releases Wiki Activity

文档更新

Browse Source
This commit is contained in:
ryan
2026-06-19 14:43:22 +08:00
parent 9eeeb09d2f
commit cc5e53c51e
48 changed files with 226 additions and 4612 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/deployment/agent.md
+2 -2
View File
@@ -149,7 +149,7 @@ journalctl -u openflare-agent -f
源码运行：
```bash
cd openflare-agent
export LOG_LEVEL='info'
go run ./cmd/agent -config /path/to/agent.json
```
@@ -157,7 +157,7 @@ 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
docs/deployment/deployment.md
+16 -61
View File
@@ -2,7 +2,7 @@
你会学到：OpenFlare 的推荐部署方式、Server 与 Agent 的运行要求、源码启动方式、联调步骤、升级与卸载入口。
生产环境建议使用 PostgreSQL 作为 Server 数据库，并为 Server 显式配置 `JWT_SECRET`。Agent 部署方式推荐为 Docker 部署（即直接使用内置 OpenResty 的 Agent 镜像）；亦支持通过安装脚本或手动本地运行。
生产环境建议使用 PostgreSQL 作为 Server 数据库，并通过 `config.yaml` 或环境变量配置 `APP_SESSION_SECRET` 等参数。完整 Docker Compose 部署还需 Redis 与 ClickHouse（见仓库根目录 `docker-compose.yaml`）。Agent 部署方式推荐为 Docker 部署（即直接使用内置 OpenResty 的 Agent 镜像）；亦支持通过安装脚本或手动本地运行。
## 部署拓扑
@@ -78,53 +78,14 @@ Agent：
## Docker Compose 部署 Server
创建 `docker-compose.yml`：
```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:
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
volumes:
- openflare-data:/data
volumes:
postgres-data:
openflare-data:
```
启动：
仓库根目录已提供完整 `docker-compose.yaml`（含 PostgreSQL、Redis、ClickHouse、Jaeger）。
```bash
cp .env.example .env
# 编辑 .env，至少修改 APP_SESSION_SECRET 与数据库密码
docker compose up -d
docker compose ps
docker compose logs -f openflare
docker compose logs -f wavelet
```
首次访问 `http://localhost:3000`，默认账号为 `root` / `123456`。登录后请立即修改默认密码。
@@ -134,29 +95,23 @@ docker compose logs -f openflare
先构建管理端前端：
```bash
cd openflare-server/web
cd frontend
corepack enable
pnpm install
pnpm build
pnpm build:embed
```
再启动 Server：
再启动 Server（仓库根目录）：
```bash
cd openflare-server
export JWT_SECRET='replace-with-a-long-random-string'
export SQLITE_PATH='./openflare.db'
export LOG_LEVEL='info'
# 可选：设置后优先使用 PostgreSQL。
# export DSN='postgres://openflare:secret@127.0.0.1:5432/openflare?sslmode=disable'
go run .
cp config.example.yaml config.yaml
export APP_SESSION_SECRET='replace-with-a-long-random-string'
# 可选：使用 PostgreSQL
# export DB_HOST=127.0.0.1 DB_USERNAME=postgres DB_PASSWORD=postgres DB_NAME=openflare
go run main.go all
```
默认监听 `3000` 端口。也可以显式指定：
```bash
go run . --port 3000 --log-dir ./logs
```
默认监听 `:3000`（由 `config.yaml` 的 `app.addr` 或 `APP_ADDR` 控制）。
## Docker 运行 Agent（推荐）
@@ -230,7 +185,7 @@ journalctl -u openflare-agent -f
源码运行：
```bash
cd openflare-agent
export LOG_LEVEL='info'
go run ./cmd/agent -config /path/to/agent.json
```
@@ -238,7 +193,7 @@ 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
docs/deployment/openflared.md
+2 -3
View File
@@ -58,8 +58,7 @@ docker run -d --name openflared --restart unless-stopped \
### 1. 编译二进制
```bash
cd openflared
go build -o flared ./cmd/flared
go build -o bin/flared ./cmd/flared
```
### 2. 准备 `flared.json`
@@ -91,7 +90,7 @@ export LOG_LEVEL='info'
### 1. 自动同步逻辑
启动成功后，OpenFlared 将执行以下工作流：
- **心跳与配置获取**：周期性向 Server 的 `/api/flared/heartbeat` 和 `/api/flared/config` 接口发起同步，验证 Token 并检测配置版本。
- **心跳与配置获取**：周期性向 Server 的 `/api/v1/tunnel/heartbeat` 和 `/api/v1/tunnel/config/active` 接口发起同步，验证 Token 并检测配置版本。
- **文件渲染**：当检测到配置版本（或校验和 Checksum）变化时，会自动拉取该隧道的完整路由规则。如果绑定了多个中继 Relay，将为每个 Relay 分别在 `data_dir` 下渲染出 `frpc_{relayNodeID}.toml`。
- **热重载或重启**：拉起对应的 `frpc` 子进程，或在配置文件发生改变时执行 `frpc reload` / 重启动作，以确保流量映射保持最新。
- **异常自恢复**：如果本地 `frpc` 隧道进程异常退出，主控程序会在 5 秒的退避惩罚后自动尝试重新启动。
docs/deployment/relay.md
+1 -2
View File
@@ -68,8 +68,7 @@ docker run -d --name openflare-relay --restart unless-stopped \
### 1. 编译二进制
```bash
cd openflare-relay
go build -o openflare-relay ./cmd/relay
go build -o bin/openflare-relay ./cmd/relay
```
### 2. 准备 `relay.json`
docs/deployment/server.md
+22 -71
View File
@@ -13,14 +13,14 @@ OpenFlare Server 是 Gin + GORM 单体控制面，负责管理端 UI、管理 AP
| pnpm | 推荐通过 `corepack enable` 使用项目声明的 pnpm |
| 数据库 | SQLite 文件目录可写，或可访问的 PostgreSQL 实例 |
生产环境必须配置 `session_secret`（或 `SESSION_SECRET`），并优先使用 PostgreSQL 与 Redis。
生产环境必须配置 `app.session_secret`（或 `APP_SESSION_SECRET`），并优先使用 PostgreSQL、Redis 与 ClickHouse。
## 构建管理端前端
Go Server 会嵌入 `openflare-server/frontend/out` 静态产物。源码启动前先构建前端：
Go Server 会嵌入 `frontend/out` 静态产物（构建后复制到 `internal/router/root/dist`）。源码启动前先构建前端：
```bash
cd openflare-server/frontend
cd frontend
corepack enable
pnpm install
pnpm build:embed
@@ -37,10 +37,9 @@ pnpm test
## 使用 SQLite 启动
```bash
cd openflare-server
cp config.example.yaml config.yaml
# 编辑 config.yaml：设置 session_secret，并将 database.enabled 设为 false
go run . all
go run main.go all
```
默认监听 `3000` 端口，访问：
@@ -52,13 +51,12 @@ http://localhost:3000
## 使用 PostgreSQL 启动
```bash
cd openflare-server
cp config.example.yaml config.yaml
# 编辑 config.yaml：设置 session_secret、database.* 与 redis.*
go run . all
go run main.go all
```
生产环境推荐分进程部署：`go run . api`、`go run . worker`、`go run . scheduler`。
生产环境推荐分进程部署：`go run main.go api`、`go run main.go worker`、`go run main.go scheduler`。
## 使用 Docker 启动
@@ -77,85 +75,39 @@ docker run -d \
--name openflare-server \
-p 3000:3000 \
-v $(pwd)/openflare-data:/data \
-e JWT_SECRET='replace-with-a-long-random-string' \
-e APP_SESSION_SECRET='replace-with-a-long-random-string' \
-e DB_ENABLED=false \
-e SQLITE_PATH='/data/openflare.db' \
-e GIN_MODE='release' \
-e LOG_LEVEL='info' \
openflare-server:latest
ghcr.io/rain-kl/openflare:latest
```
启动参数说明：
* **`-p 3000:3000`**：映射宿主机 `3000` 端口到容器内 `3000` 端口。
* **`-v $(pwd)/openflare-data:/data`**：挂载本地目录到容器的 `/data`，确保数据库文件 `openflare.db` 在重启或重建容器时不丢失。
* **`JWT_SECRET`**：管理端 API 登录令牌的 JWT 签名密钥，生产环境必须配置，避免重启后已登录令牌全部失效。
* **`-v $(pwd)/openflare-data:/data`**：挂载本地目录到容器的 `/data`，确保数据库文件在重启或重建容器时不丢失。
* **`APP_SESSION_SECRET`**：Session Cookie 签名密钥，生产环境必须配置。
---
### 2. 使用 Docker Compose 一键启动（集成 PostgreSQL）
### 2. 使用 Docker Compose 一键启动
推荐在生产环境使用 Docker Compose，自动编排独立的 PostgreSQL 数据库并建立服务间的高可用关联。
在项目控制面目录下使用 `docker-compose.yaml` 进行编排：
```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: openflare-server:latest
restart: unless-stopped
depends_on:
postgres:
condition: service_healthy
ports:
- "3000:3000"
environment:
JWT_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
```
启动命令：
推荐在生产环境使用仓库根目录的 `docker-compose.yaml`，自动编排 PostgreSQL、Redis、ClickHouse 与 Jaeger：
```bash
# 启动编排服务
cp .env.example .env
docker compose up -d
```
Compose 参数说明：
* **`depends_on` 与 `healthcheck`**：通过 PostgreSQL 的健康度检查（pg_isready），确保数据库初始化完成并完全准备就绪后，再自动拉起 OpenFlare 控制面服务，避免首次连接数据库失败抛出 panic。
* **数据目录分离挂载**：`postgres` 数据挂载在 `./postgres-data`，`openflare` 数据与本地备份挂载在 `./openflare-data`，结构清晰，便于日常备份和维护。
## 命令行参数
```bash
go run . --port 3000 --log-dir ./logs
go run main.go api # 仅 API
go run main.go worker # 仅 Worker
go run main.go scheduler # 仅 Scheduler
go run main.go all # 融合模式（默认）
```
| 参数 | 作用 | 默认值 |
| --- | --- | --- |
| `--port` | 指定 Server 监听端口 | `3000` |
| `--log-dir` | 指定日志目录 | 空，输出到标准输出 |
| `--version` | 输出版本后退出 | `false` |
| `--help` | 输出帮助后退出 | `false` |
监听地址与日志由 `config.yaml`（`app.addr`、`log.*`）或 `APP_ADDR`、`LOG_*` 环境变量控制。
## 首次登录
@@ -169,7 +121,7 @@ go run . --port 3000 --log-dir ./logs
## 配置要点
复制 `openflare-server/config.example.yaml` 为 `config.yaml`，或使用 `openflare-server/.env.example` 中的环境变量。关键默认值：
复制 `config.example.yaml` 为 `config.yaml`，或使用 `.env.example` 中的环境变量。关键默认值：
| 项 | 值 |
| --- | --- |
@@ -179,14 +131,13 @@ go run . --port 3000 --log-dir ./logs
| `application_name` | `openflare-server` |
| Redis 键前缀 | `openflare:` |
也可使用 `docker compose up`（见 `openflare-server/docker-compose.yml`）拉起 PostgreSQL、Redis 与 Server。
也可使用 `docker compose up`（见根目录 `docker-compose.yaml`）拉起完整依赖栈。
### 验证
```bash
cd openflare-server
go build ./...
go test ./internal/apps/openflare/... -count=1
curl http://127.0.0.1:3000/api/status
curl http://127.0.0.1:3000/api/v1/d/status
```