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

@@ -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 * * *

README.md

@@ -52,12 +52,73 @@ OpenFlare 是开源 CDN 编排与边缘安全平台。它支持反向代理、
 
 ### 1. 启动 Server
 
-仓库根目录提供完整 `docker-compose.yaml`（PostgreSQL、Redis、ClickHouse、Jaeger）：
+使用 docker-compose
 
-```bash
+```yaml
-cp .env.example .env
+services:
-# 编辑 .env，至少修改 APP_SESSION_SECRET
+  openflare:
-docker compose up -d
+    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`，历史版本不可变，回滚通过重新激活旧版本完成。
-
-
 ## 界面预览
 
 ### 仪表盘总览

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

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

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 运行时需要嵌入前端静态资源。编译 Go 二进制前需要先构建前端静态产物并输出到 Go 服务目录：
-
-Go Server 会嵌入 `frontend/out` 静态产物（构建后复制到 `internal/router/root/dist`）。源码启动前先构建前端：
 
 ```bash
 cd frontend
 corepack enable
 pnpm install
 pnpm build:embed
+cd ..
 ```
 
-常用前端检查：
+> **常用前端代码检查命令**：
+> * `pnpm lint`
+> * `pnpm typecheck`
 
-```bash
+### 2. 使用 SQLite 启动
-pnpm lint
-pnpm typecheck
-pnpm test
-```
 
-## 使用 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` 端口，访问：
+### 3. 使用 PostgreSQL 启动
-
-```text
-http://localhost:3000
-```
-
-## 使用 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` 中的环境变量。关键默认值：
+## 常用运维指南
 
-| 项 | 值 |
+### 1. 命令行子服务分进程启动
-| --- | --- |
-| 监听地址 | `:3000` |
-| PostgreSQL 库名 | `openflare` |
-| SQLite 后备 | `openflare.db` |
-| `application_name` | `openflare-server` |
-| Redis 键前缀 | `openflare:` |
 
-也可使用 `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
 ```

docs/deployment/upgrade.md

@@ -6,47 +6,26 @@
 
 ## Server 升级
 
-Root 用户可以在管理端顶栏检查并升级 Server 正式版。也可以通过上传 Server 二进制的方式执行确认升级。
+拉取最新镜像升级
-
-如需尝试 preview 版本，可手动检查对应发布。生产环境建议优先使用正式版。
-
-升级后确认：
 
 ```bash
-docker compose ps
+docker compose pull
-docker compose logs -n 100 openflare
+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 点清理访问日志、指标快照与请求报告。

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:
+  redis:
-    image: ghcr.io/rain-kl/openflare:latest
+    image: valkey/valkey:8.0-alpine
     restart: unless-stopped
-    depends_on:
+    command: ["valkey-server", "--appendonly", "yes"]
-      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
+      - ./data/valkey:/data
+    healthcheck:
+      test: ["CMD", "valkey-cli", "ping"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
 
-volumes:
+  clickhouse:
-  postgres-data:
+    image: clickhouse/clickhouse-server:25.3-alpine
-  openflare-data:
+    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。
-