177 lines
7.3 KiB
Markdown
177 lines
7.3 KiB
Markdown
好的，我先去看了你 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（仓库链接） |