更新日志调整

Docs/install_docker.md

@@ -1,73 +1,116 @@
 ## 🐳 Docker 版安装指南
 
-> 推荐方式：一键脚本自动部署，无需手动编译，无需安装 Go 环境。</br>
+> 推荐方式：一键脚本自动部署，无需手动安装 Go 环境，无需预先配置 Docker 镜像源。
 
-> ⚠️ **注意**：Docker 版直接从源码构建，使用的是当前 `main` 分支的最新代码，更新进度会远快于 Release 版本。⚠️</br>
+> ⚠️ **注意**：Docker 版直接从源码构建，使用的是当前所选分支（LTS / Preview）的最新代码。如需使用特定 Release 版本，请查看 [Releases](https://git.whitetop.xyz/lxh2875931338/frpc-console/releases) 并通过二进制方式部署。
-> 如需使用特定版本（如 LTS），请查看 [Releases](https://git.whitetop.xyz/lxh2875931338/frpc-console/releases) 确认版本号，并通过二进制方式部署指定版本。
+
+---
 
 ### 一、📥 前置条件
 
-- 已安装 Docker（必须）
+- **已安装 Docker**（必须，版本不限）
-- 已安装 curl / wget（脚本会自动检查并安装）
+- **curl**（其余依赖脚本会自动检查并安装）
-- 操作系统：Linux（x86_64 / ARM64 / ARMv7 均可）
+- **操作系统**：Linux（x86_64 / ARM64 / ARMv7 / ARMHF 均可）
+- **网络**：需能访问 Gitea 仓库（git.whitetop.xyz）
 
+> 💡 脚本会自动检测并配置 Docker 镜像加速，无需手动设置。
+
+---
 
 ### 二、🚀 一键部署（推荐）
 
 在目标 Linux 服务器上执行：
 
 ```bash
-curl -sSL https://git.whitetop.xyz/lxh2875931338/frpc-console/raw/main/deploy.sh | sudo bash
+curl -sSL https://git.whitetop.xyz/lxh2875931338/frpc-console/raw/main/run-deploy.sh | sudo bash
 ```
 
-或手动下载执行：
+部署过程中会提示选择通道：
 
-```bash
+· LTS（稳定版） → main 分支，生产环境推荐
-wget https://git.whitetop.xyz/lxh2875931338/frpc-console/raw/main/deploy.sh
+· Preview（技术预览版） → test 分支，尝鲜和新特性验证
-chmod +x deploy.sh
+
-sudo bash deploy.sh
+脚本会完整执行整个部署流程，包括镜像源自动检测与配置。
+
+---
+
+三、⚙️ 部署引擎自动完成内容
+
+deploy.sh 是一个完整的状态机驱动部署引擎，按时间顺序执行以下操作：
+
+```mermaid
+flowchart TD
+    subgraph 检测阶段
+        A[检测操作系统] --> B[检测CPU架构]
+        B --> C[检测必要工具]
+        C --> D[检测Docker环境]
+        D --> E[检测镜像源配置]
+    end
+
+    subgraph 决策阶段
+        E --> F[状态机计算]
+        F --> G[生成部署计划]
+        G --> H[用户确认]
+    end
+
+    subgraph 执行阶段
+        H --> I[拉取源码]
+        I --> J[配置镜像源]
+        J --> K[重启Docker]
+        K --> L[构建镜像]
+        L --> M[清理旧容器]
+        M --> N[启动容器]
+        N --> O[写入版本]
+    end
+
+    subgraph 验证阶段
+        O --> P[验证镜像内容]
+        P --> Q[验证数据库]
+        Q --> R[验证版本]
+    end
+
+    subgraph 清理阶段
+        R --> S[清理旧镜像]
+        S --> T[清理临时文件]
+    end
+
+    T --> U[部署完成]
 ```
 
+---
 
-### 三、⚙️ 脚本自动完成内容
+四、📂 数据持久化
 
-| 步骤 | 说明 |
+脚本默认将数据存储在 /opt/frpc-console/data/：
-|---|---|
-| 检测系统 | 自动识别 OpenSUSE（猫猫特有的夹带私货） / Ubuntu / Debian / CentOS / Alpine |
-| 检测 CPU 架构 | 自动适配 x86_64 / ARM64 / ARMv7 |
-| 安装依赖 | git / curl / wget（如未安装） |
-| 安装 Go | 从国内镜像下载，自动配置代理 |
-| 拉取源码 | 从 Gitea 仓库克隆最新代码 |
-| 编译二进制 | 根据当前架构编译 Linux 版 |
-| 构建 Docker 镜像 | 使用源码中的 Dockerfile 构建 |
-| 启动容器 | 挂载数据卷，开机自启 |
 
-
+文件 说明
-### 四、📂 数据持久化
+frpc-console.db SQLite 数据库（用户、隧道、配置）
-
+frpc.toml 当前 frpc 配置文件
-脚本默认将数据存储在 `/opt/frpc-console/data/`：
+frpc.log frpc 运行日志
-
+frpc.pid frpc 进程 PID
-| 文件 | 说明 |
+version.ini 当前版本标识
-|---|---|
-| `frpc-console.db` | SQLite 数据库（用户、隧道、配置） |
-| `frpc.toml` | 生成的 frpc 配置文件 |
-| `frpc.log` | frpc 运行日志 |
-| `frpc.pid` | frpc 进程 PID |
 
 升级或重建容器时，数据自动保留，不会丢失。
 
+---
 
-### 五、🔄 升级
+五、🔄 升级
 
-**方式一：重新运行脚本**
+方式一：重新运行部署脚本（推荐）
 
 ```bash
-sudo bash deploy.sh
+curl -sSL https://git.whitetop.xyz/lxh2875931338/frpc-console/raw/main/run-deploy.sh | sudo bash
 ```
 
-脚本会自动停止旧容器、拉取最新代码、重新编译并启动新容器，数据卷保持不变。
+脚本会自动：
 
-**方式二：手动更新**
+1. 拉取最新代码
+2. 构建新镜像
+3. 停止并删除旧容器
+4. 启动新容器
+5. 数据卷保持不变
+
+方式二：手动更新
 
 ```bash
 # 停止旧容器
@@ -75,11 +118,14 @@ docker stop frpc-console
 docker rm frpc-console
 
 # 重新运行 deploy.sh
-sudo bash deploy.sh
+curl -sSL https://git.whitetop.xyz/lxh2875931338/frpc-console/raw/main/run-deploy.sh | sudo bash
 ```
 
+💡 升级时如检测到语义版本降级（如 2.6 → 2.5），脚本会自动备份数据目录，并等待用户确认后再执行。
 
-### 六、🧹 常用命令
+---
+
+六、🧹 常用命令
 
 ```bash
 # 查看日志
@@ -96,10 +142,14 @@ docker stop frpc-console
 
 # 启动容器
 docker start frpc-console
+
+# 查看当前版本
+cat /opt/frpc-console/data/version.ini
 ```
 
+---
 
-### 七、🌐 访问地址
+七、🌐 访问地址
 
 部署完成后，浏览器打开：
 
@@ -109,12 +159,13 @@ http://你的服务器IP:9300
 
 首次访问会自动跳转到注册页面，填写用户名和密码，完成管理员账户创建。
 
-登录后，在「隧道列表」页面点击「导入 TOML」，即可将现有的 `frpc.toml` 迁移到 WebUI 中管理。
+登录后，在「隧道列表」页面点击「导入 TOML」，即可将现有的 frpc.toml 迁移到 WebUI 中管理。
 
+---
 
-### 八、📌 手动部署（不使用脚本）
+八、📌 手动部署（不使用脚本）
 
-如果你已有源码，或想自行定制：
+如果你已有源码，或想完全手动控制：
 
 ```bash
 # 1. 克隆代码
@@ -132,8 +183,18 @@ docker run -d \
   --name frpc-console \
   --restart=always \
   --network host \
-  -v /opt/frpc-console/data:/app\
+  -v /opt/frpc-console/data:/app/data \
   -e PORT=9300 \
   -e TZ=Asia/Shanghai \
   frpc-console:latest
 ```
+
+⚠️ 手动部署不会自动处理镜像源配置、版本管理、容器冲突检测和镜像清理。建议优先使用一键部署脚本。
+
+---
+
+### 九、📖 相关文档
+
+- [部署引擎设计详解](./deployment-engine-design.md) — 了解 `deploy.sh` 的状态机设计与工程决策
+- [工程设计哲学](./engineering-philosophy.md) — 理解部署脚本背后的设计理念
+- [二进制安装指南](./install_binary.md) — 适用于无 Docker 或边缘设备场景

readme.md

@@ -12,6 +12,8 @@
 
 一个基于实际工程实践而构建的——轻量级生命周期控制台。
 
+同时也是一个为边缘环境设计的、自包含的、具备发行版级更新策略的 frp 运维基础设施
+
 **安装一次。配置一次。然后——忘记它。**
 
 ---
@@ -20,11 +22,11 @@
 | 目录 | 简要说明 |
 |---|---|
 | [📖 工程设计哲学](./Docs/engineering-philosophy.md) | 为什么它会长成今天这样 |
-| [🔄 更新策略](./Docs/update-strategy.md)  | Preview / LTS |
-| [🚀 部署引擎设计](./Docs/deployment-engine-design.md)  | deploy 的完整架构设计 |
 | [🏗 架构设计](./Docs/architecture.md)  | 整体架构设计思路 |
-| [⚙ 设计决策](./Docs/design-decisions.md)  | 为什么没有 CI？为什么叫 Console？ |
+| [🚀 部署引擎设计](./Docs/deployment-engine-design.md)  | deploy 的完整架构设计 |
 | [🌐 边缘节点](./Docs/edge-node.md)  | 为什么支持 BusyBox、ARMHF |
+| [🔄 更新策略](./Docs/update-strategy.md)  | Preview / LTS |
+| [⚙ 设计决策](./Docs/design-decisions.md)  | 为什么没有 CI？为什么叫 Console？ |
 
 ---
 
@@ -54,5 +56,5 @@
 
 ---
 
-[**MIT License © 2026 lxh2875931338（XHLiang0）**](./License.md) · [GitHub](https://github.com/XHLiang0) · [致谢](./Docs/acknowledgment.md)
+[**MIT License © 2026 lxh2875931338（XHLiang0）**](./License.md) · [GitHub](https://github.com/XHLiang0) · [致谢](./Docs/acknowledgment.md) · [更新日志](update-logs.md)
 

update-logs.md

@@ -5,6 +5,84 @@
 | 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"`，与后端状态机对齐
+
+### 部署变更
+
+- **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 级问题已修复，但建议在测试环境中充分验证后再考虑生产部署。
+
 ---
 
 ## 2.5-lts (2026-08-03)
@@ -34,7 +112,9 @@
 
 > **紧急修复版 —— 架构升级与部署流程重构**
 >
-> 本次版本为 **非正统 LTS 版本**（2.4 在语义版本中不属于 LTS 序列），因 `main` 分支在新架构迁移过程中出现编译阻塞，为快速恢复 LTS 通道可用性而发布。**2.5-lts 将回归正常语义版本规则。**
+> 本次版本为 **非正统 LTS 版本**（2.4 在语义版本中不属于 LTS 序列），因 `main` 分支在新架构迁移过程中出现编译阻塞，为快速恢复 LTS 通道可用性而发布。
+>
+> **2.5-lts 将回归正常语义版本规则。**
 
 ### 🔧 核心变更