frpc-console/update-logs.md

📌 版本说明

版本类型	标记	适用场景
LTS 正式版	-lts	生产环境，长期维护
技术预览版	-preview	功能前瞻，建议测试环境验证

2.7-Preview (2026-08-11)（main下前置技术预览版）

重大功能更新修复版 —— 架构升级与部署流程重构

本次版本为 非正统 LTS 版本（2.7 在语义版本中不属于 LTS 序列），因 main 分支在部分场景下存在功能异常与进程管理问题而发布。

此版本已进行长时间测试，暂无重大功能异常。 3.0-lts 将回归正常语义版本规则。

本次LTS的核心是 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)

稳定加固版 —— 架构升级与部署流程闭环

核心变更

• 数据目录规范化 —— 所有运行时文件统一迁移至 /app/data，挂载点从 /app 收窄至 /app/data，彻底解决挂载覆盖二进制文件的问题
• 版本管理解耦 —— 二进制不再注入版本信息，由 deploy.sh 在部署时写入 version.ini
• 入口脚本分离 —— 引入 run-deploy.sh 独立入口，用户只需记住一个命令
• 僵尸进程回收 —— 子进程退出时自动回收资源，防止僵尸进程积累

UI 优化

• 字体全系 HarmonyOS Sans SC，视觉风格统一
• 「用户配置」Tab 移至导航栏最右侧
• 弹窗居中修复，顶部导航字号优化

🐛 修复

• 修复挂载覆盖导致二进制不可用的问题
• 修复 ps | grep 进程检测在容器环境不可靠的问题
• 修复旧版本升级时数据库路径不兼容的问题

🚀 2.4-lts (2026-07-30)

紧急修复版 —— 架构升级与部署流程重构

本次版本为 非正统 LTS 版本（2.4 在语义版本中不属于 LTS 序列），因 main 分支在新架构迁移过程中出现编译阻塞，为快速恢复 LTS 通道可用性而发布。

2.5-lts 将回归正常语义版本规则。

🔧 核心变更

• 部署架构重构 —— 引入 run-deploy.sh 独立入口，实现部署脚本与项目分支解耦
• 数据目录规范化 —— 所有运行时文件（数据库、配置、日志、PID）统一迁移至 /app/data 子目录，挂载点从 /app 收窄至 /app/data，彻底解决挂载覆盖二进制文件的问题
• 版本管理解耦 —— 二进制不再注入版本信息，版本由 deploy.sh 在部署时写入 version.ini 文件
• PID 文件进程检测 —— frpc 状态检测从 ps | grep 改为基于 PID 文件，更加可靠
• 旧版本自动迁移 —— 检测到根目录存在旧数据文件时，自动迁移至 data/ 子目录，并保留备份

✨ 功能完整

• Ping 延迟检测（顶部导航实时显示）
• 用户配置页独立（账户管理与全局配置分离）
• 401 统一拦截（认证过期自动跳转登录）
• 声明式数据库迁移引擎（基于 db-history.go）
• frp v2 协议正式启用（wireProtocol = "v2"）

📦 部署变更

变更项	旧方案	新方案
挂载点	-v ${DEPLOY_DIR}:/app	-v ${DEPLOY_DIR}/data:/app/data
数据库路径	/app/frpc-console.db	/app/data/frpc-console.db
配置文件	/app/frpc.toml	/app/data/frpc.toml
版本文件	编译时注入 -ldflags	部署时写入 version.ini

🐛 修复

• 修复 main 分支因挂载覆盖导致二进制文件不可用的问题
• 修复 ps | grep 进程检测在容器环境不可靠的问题
• 修复旧版本升级时数据库路径不兼容的问题

---

🚀 2.3-preview (2026-07-28)

技术预览版 —— 在 LTS 稳定核心（2.0）基础上，集成 2.1 与 2.2 的新特性，并完成基础设施层的全面加固。

✨ 新增特性

• Ping 延迟检测 —— 顶部导航实时显示 frpc 到 frps 的延迟，状态图标 + ms 值，直观反映网络质量（2.1）
• 用户配置页独立 —— 账户管理与全局配置分离，用户信息与 frpc 配置各自独立管理（2.1）
• 声明式数据库迁移引擎 —— 基于 db-history.go 的 Schema 版本声明，对比新旧差异自动决定迁移路径（2.2）

🔧 改进与优化

• 401 统一拦截 —— API 请求返回 401 时自动清除认证状态并跳转登录页，避免页面卡死（2.1）
• 数据库路径统一 —— 数据库文件固定为 ./frpc-console.db，Docker 部署时挂载整个 /app 目录，所有运行时文件（db / toml / log / pid）完整持久化
• deploy.sh 部署逻辑重构 —— 备份 → 拉代码 → 停容器 → 构建 → 启动，顺序闭环；移除宿主机编译，全部交由 Docker 多阶段构建处理
• Dockerfile 多阶段构建 —— 自动处理 go.mod 降级兼容，安装 sqlite 辅助工具，便于部署脚本验证数据库状态
• 前端加载状态管理 —— 新增 authLoading 状态，首次访问时先完成用户检查再渲染页面，彻底解决刷新后登录/注册页状态错乱的竞态问题
• schema_version 兜底写入 —— InitDB() 末尾强制补写 Schema 版本，确保每次启动都能识别已有数据，彻底解决升级后反复跳转注册页的问题
• docker-compose.yml 配套工具 —— 简化开发调试流程，支持快速重建容器

🐛 修复

• 修复 ExportTomlHandler 模板渲染时缺少 WireProtocolLine 字段的问题
• 修复 deploy.sh 升级时用空文件覆盖旧数据库的问题
• 修复 Docker 镜像中 sqlite3 包名错误导致 deploy.sh 无法验证数据库的问题
• 修复首次访问刷新时登录/注册页显示异常的前端竞态问题

📦 部署变更

• 挂载方式：-v ${DEPLOY_DIR}:/app（整个 /app 目录）
• 数据库位置：/opt/frpc-console/frpc-console.db
• 备份目录：/tmp/frpc-console/db-backups
• 容器内工具：sqlite 已预装，便于调试

---

✅ 2.0-lts (2026-07-27)

首个 LTS 正式版 —— 与 frps-console 2.0-lts 同步发布，共享版本号与 LTS 维护周期。

• 🚀 frp v2 协议正式启用 —— wireProtocol = "v2" 配置项可用，实测稳定
• 🔒 数据库迁移引擎完整实现 —— 版本驱动的增量迁移 + 迁移前自动全量备份 + 失败可回滚
• 🧩 frps-console 同步发布 —— 同一套设计哲学，一个管理 frpc，一个管理 frps

---

🧪 1.5-release (2026-07-25) (non-LTS)

非长期支持版本，建议用于尝鲜测试，生产环境请使用 2.0-lts 及后续 LTS 版本。

• ✨ 全局配置页面卡片式重构（服务器连接 / 传输配置 / 日志配置）
• ✨ 新增运行日志面板（8 秒轮询，最大 200 行）
• ✨ frp v2 配置占位（UI 灰标禁用，为 2.0 铺路）
• 🔩 数据库 Schema 迁移框架（启动时自动补全缺失列）
• 🔐 默认配置脱敏（通用占位符，避免开箱即连他人服务器）
• 🎨 样式拆分与优化（style-3.css / style-4.css）

---

🎉 1.0-release (2026-07-24) (non-LTS)

首次公开发布，核心功能全部就绪。

• 🎉 首次发布
• 📋 隧道全生命周期管理（增删改查 + 启用/禁用）
• 📦 TOML 导入/导出（无缝迁移现有 frpc 配置）
• 🔄 配置热加载（修改即生效，无需重启 frpc）
• 🔐 首次启动 Web 注册（无需命令行交互）
• 🖥️ 多平台支持（Windows / Linux / ARM 全平台）
• 🐳 容器化就绪（Docker 镜像，开箱即用）
• 🎨 深色磨砂玻璃 UI