OpenFlare/docs/changelog/index.md

---
sidebar: false
---

# 更新日志

本文件记录 OpenFlare 每个版本的重要变更。

格式基于 [Keep a Changelog](http://keepachangelog.com/)，版本号遵循 [语义化版本](http://semver.org/)。

## 重大变更

> [!IMPORTANT]
> 
> 3.1.2 版本更新了 CLickHouse 部署配置。
> 
> 3.0.0 版本为 Wavelet 平台迁移与架构重构版本，涉及数据库表结构、环境变量以及前后端底层架构的重大变更。请务必在升级前备份数据库，并且更新到 V2.3.4。
> 目前已知的兼容性问题：
> - Pages 无法迁移, 升级前请先手动下载并备份 Pages 静态站点的 ZIP 包，升级后重新创建。
> - 性能调优参数重置, 升级后请重新配置

## [unreleased]

## [v3.3.0] - 2026-07-14

### 新增

- WAF 规则现支持可视化编排、版本冲突保护和按顺序绑定路由，便于创建和维护复杂的防护策略。
- WAF IP 组现支持按城市匹配来源地址，帮助更精细地控制访问范围。

### 变更

- 优化了 WAF 规则编辑器的初始视图和操作方式，编辑规则时可看到更多上下文并可直接管理节点、连线和启用状态。
- WAF 地域匹配编辑器改用完整国家与一级行政区数据，国家选项同时显示中文名称和 ISO 代码，行政区支持按名称或代码搜索。
- Agent 现内置国家和城市地址库，首次启动无需下载即可使用地区匹配功能，并会在后续自动更新数据。
- 默认关闭 Redis maintenance notifications 自动协商，减少不支持该功能的 Redis 服务产生兼容性警告。

### 移除

- 移除了 WAF 旧版固定名单与人机验证配置；升级后请在发布前使用新的可视化规则重新编排防护策略。


## [v3.2.0] - 2026-07-12

### 新增

- 新增网站和域名管理能力，并提供 24 小时、7 天和 30 天的流量概览，便于集中查看访问趋势和已提供的数据量。

### 变更

- 网站管理入口调整为网站详情中的概览、域名、路由、证书和设置页面，域名与证书的关联方式更加统一。
- 配置发布、边缘代理和监控现统一从网站域名读取域名与证书，减少配置不一致导致的运行问题。
- 自动清理说明明确了分析数据的最短保留期限，便于管理员预期数据保存时间。

### 移除

- 移除了旧版托管域名管理入口，请改用网站及网站域名管理功能。
- 移除了网站、域名、路由和 WAF 相关对象的备注字段；证书和源站备注仍可继续使用。

### 修复

- 修复了网站概览中已提供的数据量无法统计的问题，使流量数据更加准确。
- 修复了嵌入式前端打开网站详情时可能错误跳回首页的问题。
- 修复了 Docker 部署中 ClickHouse 可能无法从宿主机访问的问题。

## [v3.1.2] - 2026-07-10

### 修复

- 修复了节点和仪表盘在 24 小时范围内容量、网络与磁盘趋势数据不完整的问题。
- 优化了 ClickHouse 的写入、查询和后台处理方式，降低节点空闲时的资源占用并提升高负载下的稳定性。
- 修复了数据保留清理和写入失败重试的统计问题，使清理结果和运行状态更可信。
- 改进了小规格环境下的 ClickHouse 部署配置，减少启动和连接争用问题。

## [v3.1.1] - 2026-07-06

### 修改

- 默认关闭登录页面的人机验证，减少普通登录流程的额外操作；管理员仍可按需启用。

## [v3.1.0] - 2026-07-04

### 变更

- 优化了分析数据的写入、查询、缓存和自动过期策略，降低高频心跳和访问日志对系统资源的影响。
- 调整了 ClickHouse 的连接、批处理和 Docker 部署配置，提升小规格环境下的运行稳定性。
- 收紧了审计访问日志的请求头记录范围并进行脱敏，减少敏感数据暴露风险。
- 更新了管理后台的文档入口和全局搜索范围，使常用功能更容易查找。

### 修复

- 修复了数据库迁移、系统自更新和设置页跳转可能失败的问题。

## [v3.0.2] - 2026-06-30

### 修复

- 修复了历史数据迁移后 PostgreSQL 自增编号可能与现有数据冲突的问题，避免后续创建记录失败。

## [v3.0.1] - 2026-06-30

### 新增

- 新增用户资料编辑、密码重置和按邮箱搜索功能，便于管理员维护用户账号。
- 新增命令行密码重置工具，方便无法登录管理后台时恢复账号访问。

### 修复

- 修复了创建 DNS 账号可能失败的问题。
- 修复了主题切换后侧边栏和危险操作按钮颜色异常的问题，提升界面可读性。
- 修复了部分服务运行模式无法正确启动的问题。

## [v3.0.0] - 2026-06-27

### 升级与迁移注意事项

> [!WARNING]
> 本次重构涉及数据库表结构以及环境变量的重大变更，老版本务必从 v2.3.4 最新版本升级迁移，否则可能导致数据库结构不兼容或管理端 API 无法访问。
> 升级前务必备份数据库

### 重大重构说明

本版本完成了控制面的重大升级：

- 管理后台重构为统一的用户、登录验证和系统设置体验，配置管理更加集中。
- 网站管理拆分为域名、路由、静态托管、WAF 和缓存等独立能力，更适合维护复杂站点配置。
- Tunnel 节点统一纳入节点管理，配置发布和运行状态查看更加一致。


## [v2.3.4] - 2026-06-17

### 变更

- 访问日志列表查询将分页与计数下推到数据库执行，避免百万级数据全量加载到内存。
- 访问日志 `total_ip` 统计改为 SQL `UNION` + `COUNT(*)` 下推执行，分片计数与分页查询并行化。
- 访问日志折叠视图、IP 汇总与趋势改为 SQL `GROUP BY` 聚合；过滤条件改为 `node_id` 精确匹配及其他字段前缀匹配以利用索引。
- 标准化 Server Go 目录结构，引入 `cmd/server`、`openflare-server/internal` 与根级 `pkg` 分层，并拆分原 `utils` 公共能力包。

## [v2.3.3] - 2026-06-06

### 新增

- 新增密码登录人机验证（基于 Proof-of-Work 和无感浏览器检测的 Cap 验证码防护）
- 新增后端 PoW 校验服务，实现 FNV-1a/XORShift PRNG 难题生成、验证及 JWT 难题校验算法，支持基于路由路径参数 `scope` 进行验证流的强校验与安全隔离
- 新增线程安全的内存 TTL 核销缓存，支持高并发与 Single-use 难题令牌防重放
- 新增 Gin 拦截中间件与参数化路由 `/api/cap/:scope/challenge` 和 `/api/cap/:scope/redeem`，登录接口 `POST /api/user/login` 自动从 HTTP 请求头校验 `X-Cap-Token` 并放行
- 前端登录页集成 cap-widget 组件，配置 `/api/cap/login/` 隔离端点按需加载 CDN 脚本，实现静默 PoW 求解与令牌提交
- 管理后台系统设置页“登录与注册开关”中新增“启用登录人机验证”开关，支持热更新全局防护状态
- 新增 Agent 交互式安装向导，支持选择本地安装和 Docker 运行模式；未传参数时自动进入交互菜单
- 新增 Docker 运行模式的智能环境检查，检测到未安装 Docker 时支持一键在线安装，中国大陆环境支持多镜像源自动测速优选与加速器配置
- 新增 Agent 交互式卸载向导，支持选择本地卸载和 Docker 容器卸载模式；未传参数时自动进入交互菜单

### 变更

- 重构 `install-agent.sh` 安装脚本与 `uninstall-agent.sh` 卸载脚本以兼容交互式导引、非交互式命令行参数及 Docker 部署/卸载参数（`--docker`/`--method docker`）
- 重构 Go 包依赖结构为统一模块（Monorepo），模块命名为 `github.com/rain-kl/openflare`
- 移除各子目录下独立的 `go.mod`/`go.sum` 文件，统一由根目录 `go.mod` 进行全局依赖管理与依赖版本锁定
- 替换全仓库 Go源文件中的内部引用路径，由本地相对路径迁移为标准 GitHub 绝对导入路径
- 适配 Docker 镜像构建，所有组件镜像的 Dockerfile 调整为基于根目录的上下文编译
- 更新 GitHub release 自动化发布流水线，适配全新 monorepo 包结构与符号信息注入路径
- 简化并重构数据库历史迁移校验逻辑，将版本 2 至 6 的中间校验函数合并到基线校验函数 `validateDatabaseSchemaV7` 中，消除冗余代码
- 重构数据库历史迁移校验架构，引入基于 GORM 反射解析（`schema.Parse`）的通用自动表结构校验，彻底废弃老版本中大量手动编写的 `HasTable`/`HasColumn` 结构字段存在性检测代码

---

## [v2.3.2] - 2026-06-04

### 说明

> [!IMPORTANT]
> 2.3.2 开始使用 JWT_SECRET 环境变量替代 SESSION_SECRET 进行管理端 API 的 JWT 签名密钥管理。SESSION_SECRET 将会在之后的版本中逐步废弃，请务必尽快迁移到 JWT_SECRET。

### 新增

- 新增 `JWT_SECRET` 环境变量，专用于管理端 API JWT 签名密钥；生产环境必须显式配置
- 新增 VitePress 更新日志页面（`docs/changelog/index.md`），记录所有版本变更历史

### 变更

- 管理端 API 鉴权框架迁移至 `gin-jwt`
- 认证方式变更为 Headers 认证.
- `JWT_SECRET` 优先于 `SESSION_SECRET` 用于 JWT 签名；未配置时回退到 `SESSION_SECRET`，向下兼容
- 屏蔽手动升级入口（`/api/update/manual-upload`、`/api/update/manual-upgrade`），前端隐藏对应 UI 组件

---

## [v2.3.1] - 2026-06-03

### 变更

- 屏蔽手动升级入口，前端隐藏对应 UI 组件
- POW 与 WAF 规则合并, 统一逻辑处理

---

## [v2.3.0] - 2026-06-03

### 新增

- WAF IP 组支持订阅模式，可从远程文本或 JSON 源定时同步
- 新增 Pages 静态站点托管，支持 SPA fallback 路由配置
- Agent 实现 WebSocket 实时推送，Server 发布配置后立即通知在线 Agent

### 变更

- Agent 数据面与 OpenResty 合并为集成镜像部署方式
- 访问日志与观测数据支持数据库分片，按 ID 分片替代原有逻辑

---

## [v2.2.8] - 2026-06-03

### 修复

- 修复多域名部署场景下跨域认证绕过安全漏洞

---

## [v2.2.6] - 2026-06-02

### 新增

- 新增 Uptime Kuma 集成，支持自动同步监控任务
- WAF 新增 PoW（工作量证明）防护能力，可配置有效期

### 变更

- 内网穿透支持 TunnelRelay 中继节点（frps），新增 OpenFlared 客户端（frpc）

---

## [v2.2.5] - 2026-06-02

### 新增

- 新增 WAF 自动 IP 组，支持基于 Expr 规则定时聚合请求日志更新名单
- WAF IP 组黑白名单支持直接引用 IP 组对象

### 变更

- WAF 规则组与网站解耦，支持全局规则组和自定义规则组独立管理

---

## [v2.2.4] - 2026-06-02

### 新增

- WAF 规则组新增拦截返回配置 Tab

### 修复

- 修复 WAF 配置发布后部分规则不生效的问题

---

## [v2.2.3] - 2026-06-02

### 新增

- 新增 WAF 安全防护模块，支持 IP 黑白名单和地域拦截规则

---

## [v2.2.2] - 2026-06-01

### 变更

- 观测数据支持按时间窗口自动清理，新增数据库自动清理调度器

---

## [v2.2.1] - 2026-06-01

### 修复

- 修复仪表板概览数据压缩与规范化问题

---

## [v2.2.0] - 2026-06-01

### 新增

- 新增 TLS 证书转换为 ACME 托管证书的接口（`/convert-acme`）
- 新增 ACME 账号与 DNS 账号管理页面
- 支持 Let's Encrypt 自动申请与续期

---

## [v2.1.1] - 2026-06-01

### 变更

- Agent 架构调整，采用集成镜像方式内置 OpenResty

---

## [v2.0.3] - 2026-05-31

### 修复

- 修复版本号生成逻辑，确保使用当日最大序列号

---

## [v2.0.1] - 2026-05-30

### 修复

- 修复 GitHub 登录逻辑异常

---

## [v2.0.0] - 2026-05-30

### 新增

- 全面重构发布模型，引入配置版本不可变快照机制
- 支持配置版本回滚（重新激活旧版本）
- 新增 `source_config_json` 与 `support_files` 供 Agent 获取完整配置包
- 新增节点专属 Agent Token 与 Discovery Token 双轨鉴权

### 变更

- 数据库迁移框架切换至 goose，统一管理版本升级步骤
- Agent API 与管理端 API 鉴权完全分离

---

## [v1.9.3] - 2026-05-30

### 修复

- 修复节点 IP 自动探测逻辑，优先使用公网地址

---

## [v1.9.2] - 2026-05-29

### 变更

- Agent 心跳超时后自动退回 HTTP 轮询模式

---

## [v1.9.1] - 2026-05-29

### 修复

- 修复 Agent WebSocket 升级失败时的重连逻辑

---

## [v1.9.0] - 2026-05-29

### 新增

- Agent 支持 WebSocket 长连接，Server 发布后实时推送配置变更

---

## [v1.8.0] - 2026-05-26

### 新增

- 支持自定义 DNS 解析器（`OpenRestyResolvers`）
- 新增历史配置快照清理功能

### 变更

- CORS 配置支持动态源与凭证
- 上游统一渲染为命名 `upstream` 并启用 keepalive

---

## [v1.7.0] - 2026-05-25

### 新增

- 新增 ACME 和 DNS 账号管理功能，支持证书申请与续期

### 变更

- 移除新用户注册功能
- 更新 Go 版本要求至 1.25+

---

## [v1.6.1] - 2026-05-13

### 修复

- 修复个人设置页无法查看第三方认证源及解绑功能

---

## [v1.6.0] - 2026-05-13

### 新增

- 支持 OIDC 单点登录（SSO）

---

## [v1.5.0] - 2026-04-25

### 新增

- 集成 PoW（Anubis）防护，支持有效期配置

---

## [v1.4.0] - 2026-04-01

### 新增

- 支持域名级别独立绑定 TLS 证书，每个域名可单独选择证书
- 新增批量更新配置项接口
- 新增 Agent 卸载脚本

### 变更

- 禁用新用户自助注册
- 默认服务器块新增 HTTPS 握手拒绝支持

---

## [v1.3.2] - 2026-03-30

### 新增

- 网站配置支持多域名绑定与共享设置
- 新增抽屉式规则创建组件

---

## [v1.3.1] - 2026-03-20

### 新增

- 新增源站管理功能，支持源站创建、更新与删除

### 变更

- 重构代理路由页面，优化输入组件与样式

---

## [v1.3.0] - 2026-03-19

### 新增

- 新增数据库观测数据手动和自动清理策略
- 节点访问日志支持数据库分片，按 ID 分片

### 变更

- 数据库版本管理与迁移逻辑重构

---

## [v1.2.0] - 2026-03-19

### 新增

- 支持多上游地址负载均衡
- 新增缓存策略配置（路径前缀、精确路径）
- 节点健康事件清理功能

### 变更

- 上游渲染改为命名 upstream 并启用 keepalive
- 更新 HTTPS 配置，启用 reuseport 与 epoll 事件模型

---

## [v1.1.2] - 2026-03-18

### 变更

- HTTPS 启用 HTTP/2 支持

---

## [v1.1.1] - 2026-03-18

### 新增

- 新增获取配置版本详情 API

### 变更

- 仪表板概览数据结构优化，添加压缩与规范化

---

## [v1.1.0] - 2026-03-18

### 新增

- 新增应用日志分页查询与清理功能
- 新增访问日志 IP 汇总与趋势查询
- 新增 OpenResty DNS 解析器指令支持
- Docker 部署支持在运行中容器内执行 reload

### 修复

- 修复应用结果警告逻辑
- Lua 和证书文件管理重构，优化文件同步与清理机制

---

## [v1.0.2] - 2026-03-17

### 新增

- 支持 PostgreSQL 数据库，添加数据库迁移逻辑
- 新增 Docker Compose 配置，支持 PostgreSQL 联动部署

### 变更

- 多个管理端 API 请求方法从 PUT/DELETE 统一改为 POST

---

## [v1.0.1] - 2026-03-16

### 新增

- 新增 `origin_host` 字段，支持覆盖回源请求的 Host 头

### 修复

- 修复代理配置中 SSL 服务器名称和主机头覆盖逻辑

---

## [v1.0.0] - 2026-03-15

OpenFlare 首个正式版本发布。

### 新增

- 管理端 UI、管理 API、Agent API 基础功能
- 反向代理配置管理与 OpenResty 配置渲染
- 配置版本发布与 Agent 同步
- TLS 证书导入与管理
- 节点注册、心跳与状态观测
- SQLite 数据库支持