diff --git a/update-logs.md b/update-logs.md index c44a197..5a3c970 100644 --- a/update-logs.md +++ b/update-logs.md @@ -5,6 +5,80 @@ | LTS 正式版 | `-lts` | 生产环境,长期维护 | | 技术预览版 | `-preview` | 功能前瞻,建议测试环境验证 | +## 2.7-preview (2026-08-11) + +本次预览版的核心是 **ProcessManager 进程管理模块重构**,将 frpc 的管理方式从“基于 PID 文件的简单函数集”升级为“带状态机、冲突检测、健康检查、自动恢复的完整生命周期控制器”。这是 frpc-console 从“frpc 启动器”向“frpc 生命周期控制器”演进的关键版本。 + +### 核心变更 + +- **进程管理模块独立** —— 新增 `internal/process` 包,将进程管理逻辑从 `frp.go` 中抽离为独立模块,包含状态机、互斥锁、进程属性、实例归属检测等子模块,为长期维护和扩展奠定基础 + +- **状态机驱动生命周期管理** —— 从“PID 文件存在即运行”的隐式状态升级为 8 种显式状态(UNKNOWN / STARTING / RUNNING / DEGRADED / CONFLICT / FAILED / STOPPING / STOPPED),状态转换由检测结果驱动,状态语义清晰可追溯 + +- **三级健康检查体系** —— 建立 Process Health(PID 存活)+ Admin Health(端口可访问 + 归属验证)+ Service Health(代理 running)的递进式健康检查,不同层级失败对应不同恢复策略 + +- **FRPReady 绑定 PID** —— `FRPReady` 检测从全局状态改为绑定具体 PID,通过 admin API 读取代理状态确认服务就绪,避免旧实例状态干扰新实例判断 + +- **实例归属检测与 CONFLICT 状态** —— `DetectFrpcInstances()` 通过 PID + ExecPath + CmdLine 三重确认识别系统内所有 frpc 进程,区分 Owned/Unknown 实例,冲突时保留 Owned 实例、清理 Unknown 实例,新增 CONFLICT 状态承载冲突场景 + +- **RELOADING 中间态** —— Reload 操作期间状态机进入 RELOADING 中间态,看门狗和健康检查在此期间跳过恢复动作,彻底解决 reload 导致旧 PID 消失被误判为 FAILED 的竞态问题 + +- **启动超时逻辑修正** —— 超时判断仅对 STARTING 状态生效,已进入 RUNNING 的进程不再受超时影响,解决了长期运行后每 30 秒触发一次超时误判的问题 + +- **端口检测升级为归属验证** —— `CheckPort()` 从仅返回 bool 升级为返回 PortCheckResult(Ready + Err + PID + Process),支持端口归属验证,端口被占用但 PID 不一致时触发 CONFLICT 状态 + +- **孤儿进程与僵尸进程防护** —— 启动前自动清理孤儿进程(端口被占用但无有效 PID);启动后通过 goroutine 调用 `cmd.Wait()` 回收子进程,防止 frpc 退出后变成僵尸进程堆积 + +- **进程互斥锁** —— Linux 使用 `flock` 实现进程间互斥锁,Windows 使用内存锁,防止并发启动/停止操作产生竞态条件 + +- **看门狗升级为智能恢复** —— 每 30 秒检查完整状态,根据 Phase 执行差异化恢复策略(CONFLICT → 清理 Unknown 实例;DEGRADED → 重启;FAILED → 自动重启;RELOADING → 跳过检查) + +### 模块化重构 + +- **代码结构模块化** —— 将单体结构拆分为 `internal/process`、`internal/frp`、`internal/db`、`internal/auth`、`internal/api` 等独立模块,模块边界清晰,为后续 3.0 控制器架构铺路 + +- **frp 模块拆分** —— 原 `frp.go` 拆分为 `binary.go`(二进制提取)、`config.go`(模板渲染)、`legacy.go`(兼容层)、`toml.go`(TOML 解析),职责单一,便于维护 + +- **数据库 Schema v3 升级** —— 新增 `admin_port` 字段,默认 7400,采用重型迁移策略(建新表 → 迁移数据 → 交换表名)替代 ALTER TABLE,确保数据一致性;v2→v3 迁移自动完成,无需用户干预 + +### UI 优化 + +- **配置页面新增 admin_port 输入框** —— 用户可自定义 frpc admin 端口,默认 7400,保存后自动写入 `frpc.toml` 的 `[webServer]` 段 + +- **前端状态适配** —— 前端 `getFrpcStatus()` 从检查 `state` 字段升级为检查 `phase === "RUNNING"`,与后端状态机对齐 + +- **版本号结构化** —— `version.ini` 从单行版本号升级为 INI 格式,包含 `[build]`(version / channel / commit / build_time)和 `[environment]`(builder / go_version / platform),为“关于”页面提供完整数据源 + +### 部署变更 + +- **Docker 镜像加速自动配置** —— `deploy.sh` 自动检测 Docker daemon 的 registry-mirrors 配置,检测用户配置和默认地址连通性,按需写入可用镜像源,自动重启 Docker 应用配置 + +- **frpc 二进制提取路径统一** —— 从 embed 提取的 frpc 二进制统一放到程序同层目录(`./frpc`),不再写入 `./data/` 持久化目录,避免污染数据目录 + +- **日志路径统一** —— frpc 日志从根目录 `./frpc.log` 迁移至 `./data/frpc.log`,与数据库、配置文件、PID 文件统一存放,前后端路径一致 + +### 修复 + +- 修复 reload 触发 `STARTING → FAILED` 导致旧实例被误杀的问题 +- 修复 `startTime` 长期运行后每 30 秒触发启动超时误判的问题 +- 修复 `FRPReady` 检测到旧实例状态导致新实例误判为 RUNNING 的问题 +- 修复 `CheckPort()` 在容器环境下返回 PID=0 导致端口归属验证失效的问题 +- 修复 2.5-lts 升级到 2.7-preview 时 `admin_port` 字段缺失导致热加载失败的问题 +- 修复 Windows 编译后 `./data/frpc` 路径与 `frpc_windows_amd64.exe` 不一致的问题 + +### 已知问题 + +- `work connection pool is full` 在瞬时并发高峰时偶发,已通过 `poolCount` 从 8 调整为 10 缓解,持续观察中 +- Preview 通道尚未经过长期稳定性测试,生产环境请使用 LTS 通道 + +### 升级说明 + +- 从 2.5-lts 升级时,数据库 Schema 自动从 v2 迁移至 v3,`admin_port` 默认值为 7400,无需手动操作 +- `frpc.toml` 中 `[webServer]` 段格式需从 `addr = "127.0.0.1:7400"` 调整为 `addr = "127.0.0.1"` + `port = 7400`,新部署自动适配,旧部署升级时模板自动覆盖 +- 建议升级前备份 `./data/` 目录,确保回退路径可用 + +**版本定位:** 2.7-preview 是一个技术预览版,核心目标是验证 ProcessManager 状态机在真实环境中的稳定性和准确性。虽然 P0 级问题已修复,但建议在测试环境中充分验证后再考虑生产部署。LTS 通道用户请继续使用 2.5-lts。 + --- ## 2.5-lts (2026-08-03)