From bf17622660d5845c87fac443ad92cccf24e8f6ac Mon Sep 17 00:00:00 2001
From: lxh2875931338 <lxh2875931338@outlook.com>
Date: Mon, 27 Jul 2026 23:31:57 +0800
Subject: [PATCH] =?UTF-8?q?=E9=A6=96=E4=BB=BD=E5=AE=8C=E6=95=B42.0-LTS?=
 =?UTF-8?q?=E7=89=88=E6=9C=AC=E5=AE=9A=E7=A8=BF?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 readme.md | 177 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 177 insertions(+)
 create mode 100644 readme.md

diff --git a/readme.md b/readme.md
new file mode 100644
index 0000000..d7ff3fb
--- /dev/null
+++ b/readme.md
@@ -0,0 +1,177 @@
+好的，我先去看了你 frpc-console 的 README 风格——**冷峻、务实、带点极客式骄傲，把“哲学”和“代码”焊在一起**。我按这个调性帮你写 frps-console 的 README，直接可粘贴。
+
+---
+
+# frps-console
+
+> 🚀 轻量级 frps 服务端管理面板 | 管理面与控制面分离 | 内存 < 100MB
+
+**frps-console** 是专为 **frps（服务端）** 设计的轻量 Web 管理工具。内嵌多平台 frps 二进制文件（v0.70.0），提供极简 Web UI 进行配置管理、客户端监控、日志查看。
+
+与同类工具最本质的区别是：**frps 业务进程与 Web 管理进程完全解耦**。即使面板意外崩溃、升级重启，已建立的穿透隧道也绝不中断。
+
+---
+
+## 🧘 设计哲学：“阴主导阳”
+
+这是整个项目的底层逻辑：
+
+- **阴（frps 业务）**：内网穿透的核心业务，独立运行，不依赖任何管理进程存活。
+- **阳（frps-console 面板）**：观察和调整业务的辅助工具，它的存在是为了更好地服务业务，而非成为业务的负担。
+
+**代码层面的保障**：
+- 启动 frps 时使用 `Setsid` 创建独立会话，父进程退出后 frps 被 init（PID 1）接管。
+- 内置 Watchdog（看门狗），每 30 秒探测一次 frps 存活状态，异常时自动拉起。
+- 配置修改采用“先写文件，再热加载/重启”策略，确保配置操作的原子性。
+
+用一句话概括：**业务是目的，面板是手段。面板存在的意义，是让业务运行得更清晰、更可控。**
+
+
+## 📌 版本状态
+
+**当前稳定版：v2.0.0-LTS** (2026-07-27)
+
+- 基于 frp **v0.70.0**
+- 数据库 Schema **v2.0.0**（支持未来平滑升级）
+- 已通过实际生产环境验证（内存 92MB，无僵尸堆积）
+- 承诺长期维护，**跟随上游 frp 官方 LTS 版本同步更新**
+
+**计划路线图**：
+- [x] 内嵌多平台 frps 二进制
+- [x] WebUI 配置热加载
+- [x] Watchdog 自动保活
+- [x] 数据库迁移引擎（1.0.0 → 2.0.0）
+- [ ] 工具的关于信息独立页面
+- [ ] 7500 dashboard 的数据解析（客户端列表、代理列表、流量统计）
+
+---
+
+## ✨ 核心特性
+
+- 📦 **单二进制交付**：内嵌 frps 0.70.0 多平台二进制（Linux x86_64/ARM64/ARMv7 + Windows），无需额外下载。
+- 🖥️ **极简 Web UI**：Vue 3 CDN 开发，无构建工具，修改 `static/` 下文件即生效。
+- 🗄️ **SQLite 存储**：零外部依赖，数据即文件，备份迁移只需复制 `.db` 文件。
+- 🔄 **一键部署**：`deploy.sh` 自动识别 OS（openSUSE/Ubuntu/Debian/CentOS），自动安装 Go/Docker，自动降级 `go.mod` 兼容老系统。
+- 📉 **资源极度克制**：实测总内存占用约 **92MB**（面板 60MB + frps 32MB），512MB 云服务器轻松跑。
+- 🛡️ **数据库迁移引擎**：Schema v2.0.0，版本升级时自动备份（`*.pre-v2.0.0.*`），失败可回滚。
+- 🐳 **Docker 优先**：部署产物为容器，`--restart=always` + 数据卷持久化，升级不丢数据。
+
+---
+
+## 🚀 快速开始（一键部署）
+
+在全新 Linux 服务器（Debian/Ubuntu/CentOS）上，以 root 权限执行：
+
+```bash
+curl -sSL https://git.whitetop.xyz/lxh2875931338/frps-console/raw/main/deploy.sh | sudo bash
+```
+
+**脚本做了什么？**
+
+1. 检测 CPU 架构（x86_64/ARM64/ARMv7）和发行版（甚至优先适配 openSUSE，因为作者用它）。
+2. 自动安装依赖（Git、Curl、Wget、Go 1.25.0）。
+3. 若 `go.mod` 中 Go 版本过高（如 1.25），自动降级为 `go 1.21` 以兼容老旧系统。
+4. 编译静态二进制，构建 Docker 镜像，以 `--network host` 启动容器。
+5. 数据目录 `/opt/frps-console/data` 持久化挂载，容器删除重建数据不丢。
+6. 编译时已加 `-p 1` 限制并发，避免低内存机器 OOM Killer。
+
+> **内存不足？** 脚本已内置防 OOM 措施，如果云服务器内存是在过小，建议配合 4GB Swap（`fallocate -l 4G /swapfile`）食用更佳。
+
+---
+
+## ⚙️ 配置与访问
+
+部署成功后，浏览器访问：
+
+```
+http://你的服务器IP:9365
+```
+
+- **首次启动**：检测到无管理员账户，自动进入注册页（用户名 ≥5 位，密码需含大小写/数字/特殊字符）。
+- **全局配置**：修改 `bindPort`、`Token`、日志级别，保存即热加载 frps（若热加载失败则自动降级为重启）。
+- **客户端列表**：通过 frps 内置 Dashboard API（`127.0.0.1:7500`）实时读取连接状态，无需额外配置。
+
+**环境变量（Docker）**
+
+| 变量 | 默认值 | 说明 |
+| :--- | :--- | :--- |
+| `PORT` | 9365 | Web 服务监听端口 |
+| `TZ` | Asia/Shanghai | 时区设置 |
+
+---
+
+## 🧬 进程模型与高可用
+
+```text
+┌─────────────────┐     Setsid      ┌─────────────┐
+│ frps-console    │ ──────────────▶ │   frps      │
+│ (Web 面板)      │    独立会话      │  (业务进程)  │
+│                 │                  │             │
+│  Watchdog       │ ◀── 每 30s ──── │  隧道保持   │
+│  自动保活       │    探测存活      │  永不中断   │
+└─────────────────┘                  └─────────────┘
+```
+
+- **场景一**：`docker restart frps-console` → frps 被 init 接管，隧道零中断。
+- **场景二**：frps 异常崩溃 → Watchdog 自动执行 `StartFrps()` 拉起。
+- **场景三**：修改配置保存 → 优先执行 `frps reload`，若失败则降级为 `stop && start`。
+
+**为什么能做到业务不中断？**
+
+因为 frps 启动时通过 `Setsid` 脱离了父进程的进程组。当父进程（frps-console）退出时，frps 不会被 SIGHUP 信号杀死，而是被 PID 1（init 或 Docker 的 tini）接管。这是 Unix 进程管理的经典设计，我只是把它用在了 frp 管理上。
+
+---
+
+## 📌 版本状态
+
+**当前稳定版：v2.0.0-LTS** (2026-07-27)
+
+- 基于 frp **v0.70.0**
+- 数据库 Schema **v2.0.0**（支持未来平滑升级）
+- 已通过实际生产环境验证（内存 92MB，无僵尸堆积）
+- 适用于长期支持场景（LTS）
+
+**计划路线图**：
+- [x] 内嵌多平台 frps 二进制
+- [x] WebUI 配置热加载
+- [x] Watchdog 自动保活
+- [x] 数据库迁移引擎（1.0.0 → 2.0.0）
+- [ ] 工具的关于信息独立页面
+- [ ] dashboard的数据解析（通过 frps 7500 端口的 /api/v2/* 数据，展示隧道流量、连接时长、带宽等指标）
+
+---
+
+## 📂 目录结构（Docker 容器内）
+
+```
+/app/
+├── frps-console          # 主二进制
+├── frps.toml             # 生成的 frps 配置文件
+├── frps.log              # frps 运行日志（尾部 200 行展示在 WebUI）
+├── frps.pid              # frps 进程 PID 文件
+├── data/
+│   └── frps-console.db   # SQLite 数据库（持久化）
+└── static/               # 前端静态资源（内嵌）
+```
+
+---
+
+## 🙏 致谢 & 生态定位
+
+- 核心引擎：[fatedier/frp](https://github.com/fatedier/frp)
+
+
+- 同系项目：[frpc-console](https://git.whitetop.xyz/lxh2875931338/frpc-console)（客户端管理面板，形成“云端 + 客户端”双星架构）
+
+
+
+---
+
+## 📄 许可证
+
+MIT License
+
+---
+
+**如果这个项目对你有用，欢迎给它点个 Star ⭐**  
+**问题反馈**：Git Issues（仓库链接）
\ No newline at end of file