完整版frps下readme内容
This commit is contained in:
@@ -1,177 +1,260 @@
|
||||
好的，我先去看了你 frpc-console 的 README 风格——**冷峻、务实、带点极客式骄傲，把“哲学”和“代码”焊在一起**。我按这个调性帮你写 frps-console 的 README，直接可粘贴。
|
||||
|
||||
---
|
||||
<p align="center">
|
||||
<img src="static/logo.svg" alt="frps-console" width="360" />
|
||||
</p>
|
||||
|
||||
# frps-console
|
||||
|
||||
> 🚀 轻量级 frps 服务端管理面板 | 管理面与控制面分离 | 内存 < 100MB
|
||||
> 轻量级 frps 服务端管理面板 —— 让流量中转尽在掌握
|
||||
|
||||
**frps-console** 是专为 **frps（服务端）** 设计的轻量 Web 管理工具。内嵌多平台 frps 二进制文件（v0.70.0），提供极简 Web UI 进行配置管理、客户端监控、日志查看。
|
||||
|
||||
与同类工具最本质的区别是：**frps 业务进程与 Web 管理进程完全解耦**。即使面板意外崩溃、升级重启，已建立的穿透隧道也绝不中断。
|
||||
[](https://git.whitetop.xyz/lxh2875931338/frps-console/releases)
|
||||
[](https://golang.org/)
|
||||
[](LICENSE)
|
||||
|
||||
---
|
||||
|
||||
## 🧘 设计哲学：“阴主导阳”
|
||||
## 📖 简介
|
||||
|
||||
这是整个项目的底层逻辑：
|
||||
**frps-console** 是专为 [frp](https://github.com/fatedier/frp) 服务端（frps）设计的轻量级 Web 管理工具。
|
||||
与 [frpc-console](https://git.whitetop.xyz/lxh2875931338/frpc-console) 形成姊妹篇，一个管理客户端，一个管理服务端。
|
||||
|
||||
- **阴（frps 业务）**：内网穿透的核心业务，独立运行，不依赖任何管理进程存活。
|
||||
- **阳（frps-console 面板）**：观察和调整业务的辅助工具，它的存在是为了更好地服务业务，而非成为业务的负担。
|
||||
本项目作为 frp-console 系列套件的项目之一，延续 frpc-console 的设计哲学：**以无限接近原生占用的情况下，实现完全图形化的控制工具**。实测内存占用约 **92MB**（面板 60MB + frps 32MB），512MB 云服务器轻松跑。
|
||||
|
||||
**代码层面的保障**：
|
||||
- 启动 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 的数据解析（客户端列表、代理列表、流量统计）
|
||||
- 🔐 **首次启动引导** —— Web 端完成管理员注册，无需 CLI 交互
|
||||
- 🖥️ **服务端配置管理** —— 通过 WebUI 管理 frps 核心参数（`bindPort` / `token` / `log` / `tcpMux`），告别手动编辑 TOML
|
||||
- 📊 **客户端状态概览** —— 实时查看连接到 frps 的所有客户端列表，包含在线状态、连接时间、协议版本（v1/v2）
|
||||
- 📄 **运行日志面板** —— WebUI 内实时查看 frps 运行日志，8 秒自动轮询
|
||||
- 🔄 **配置热加载** —— 修改配置后一键热加载，无需重启 frps 服务
|
||||
- 🖥️ **多平台支持** —— Linux AMD64 / ARM64 / ARMv7 全平台兼容
|
||||
- 🐳 **容器化就绪** —— 提供 Docker 镜像与一键部署脚本，开箱即用
|
||||
- 🎨 **深色磨砂玻璃 UI** —— 与 frpc-console 保持统一的视觉风格
|
||||
|
||||
---
|
||||
|
||||
## ✨ 核心特性
|
||||
## 🚀 快速开始
|
||||
|
||||
- 📦 **单二进制交付**：内嵌 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 服务器，无需 Docker，单文件运行。
|
||||
|
||||
## 🚀 快速开始（一键部署）
|
||||
👉 详见：[二进制安装指南](./INSTALL_BINARY.md)
|
||||
|
||||
在全新 Linux 服务器（Debian/Ubuntu/CentOS）上，以 root 权限执行：
|
||||
### 🐳 Docker 部署（一键脚本）
|
||||
|
||||
适用于 Linux 服务器，自动编译 + 自动部署。
|
||||
|
||||
```bash
|
||||
curl -sSL https://git.whitetop.xyz/lxh2875931338/frps-console/raw/main/deploy.sh | sudo bash
|
||||
```
|
||||
|
||||
**脚本做了什么？**
|
||||
👉 详见：[Docker 安装指南](./INSTALL_DOCKER.md)
|
||||
|
||||
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`）食用更佳。
|
||||
适合开发者或需要自定义配置的用户。
|
||||
|
||||
```bash
|
||||
git clone https://git.whitetop.xyz/lxh2875931338/frps-console.git
|
||||
cd frps-console
|
||||
go mod tidy
|
||||
go build -o frps-console .
|
||||
./frps-console
|
||||
```
|
||||
|
||||
首次访问 `http://localhost:9365` 注册管理员账户即可开始使用。
|
||||
|
||||
---
|
||||
|
||||
## ⚙️ 配置与访问
|
||||
## 🗂️ 项目结构
|
||||
|
||||
部署成功后，浏览器访问：
|
||||
|
||||
```
|
||||
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/ # 前端静态资源（内嵌）
|
||||
```txt
|
||||
frps-console/
|
||||
├── main.go # 入口
|
||||
├── api.go # HTTP 路由 & Handler
|
||||
├── db.go # SQLite 数据库操作
|
||||
├── auth.go # JWT 认证 & 密码管理
|
||||
├── frps.go # frps 管理核心逻辑
|
||||
├── toml_parser.go # TOML 解析器
|
||||
├── static/ # 前端静态资源
|
||||
│ ├── index.html
|
||||
│ ├── app.js
|
||||
│ ├── style-1.css # 全局基础样式
|
||||
│ ├── style-2.css # 登录页样式
|
||||
│ ├── style-3.css # 主界面样式
|
||||
│ └── style-4.css
|
||||
├── bin/ # 内嵌 frps 二进制 (多平台)
|
||||
│ ├── frps_windows_amd64.exe
|
||||
│ ├── frps_linux_amd64
|
||||
│ ├── frps_linux_arm64
|
||||
│ └── frps_linux_arm_hf
|
||||
├── frps.tmpl # frps 配置模板
|
||||
├── Dockerfile
|
||||
└── go.mod
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🙏 致谢 & 生态定位
|
||||
## ⚙️ 配置说明
|
||||
|
||||
- 核心引擎：[fatedier/frp](https://github.com/fatedier/frp)
|
||||
### 环境变量
|
||||
|
||||
| 变量 | 说明 | 默认值 |
|
||||
|---|---|---|
|
||||
| PORT | 监听端口 | 9365 |
|
||||
|
||||
- 同系项目：[frpc-console](https://git.whitetop.xyz/lxh2875931338/frpc-console)（客户端管理面板，形成“云端 + 客户端”双星架构）
|
||||
### 数据存储
|
||||
|
||||
· 数据库文件：`./frps-console.db`</br>
|
||||
· frps 配置文件：`./frps.toml`</br>
|
||||
· frps 日志文件：`./frps.log`</br>
|
||||
|
||||
---
|
||||
|
||||
## 🛠️ 开发指南
|
||||
|
||||
```bash
|
||||
# 克隆项目
|
||||
git clone https://git.whitetop.xyz/lxh2875931338/frps-console.git
|
||||
cd frps-console
|
||||
|
||||
# 安装依赖
|
||||
go mod tidy
|
||||
|
||||
# 开发模式运行
|
||||
go run .
|
||||
|
||||
# 编译生产版本
|
||||
go build -ldflags="-s -w" -o frps-console .
|
||||
```
|
||||
|
||||
### 前端开发
|
||||
|
||||
前端使用 Vue 3 CDN，无需额外构建工具。修改 `static/` 目录下的文件后，刷新浏览器即可预览效果。
|
||||
|
||||
---
|
||||
|
||||
## 🔧 常见问题
|
||||
|
||||
#### Q: 如何修改管理员密码？
|
||||
|
||||
登录后，在「全局配置」页面顶部找到「账户管理」区域，输入当前密码和新密码即可。
|
||||
|
||||
#### Q: frps 启动失败怎么办？
|
||||
|
||||
首次启动的话，console会创建一个全新的、符合官方规范的toml配置文件。</br>
|
||||
如果使用中出现启动失败问题，可以在console内重新配置一次服务端参数，或者导入已有的toml即可恢复</br>
|
||||
如果依旧无效，请查看 ./frpc.log 日志文件。
|
||||
|
||||
#### Q: 支持哪些 frp 版本？
|
||||
|
||||
目前支持情况如下：
|
||||
|
||||
| 系统 | 架构版本 | 版本号 |
|
||||
|---|---|---|
|
||||
| Linux | AMD64/x86-64 | 0.70.0 |
|
||||
| Linux | ARM64/Aarch64 | 0.70.0 |
|
||||
| Linux | ARM_hf/ARMv7l | 0.70.0 |
|
||||
|
||||
#### Q: frps-console 和 frpc-console 有什么区别？
|
||||
|
||||
| 对比项 | frpc-console | frps-console |
|
||||
|---|---|---|
|
||||
| 管理对象 | frpc（客户端） | frps（服务端） |
|
||||
| 适用场景 | 软路由、小主机、本地服务穿透 | VPS、云主机、流量中转 |
|
||||
| 默认端口 | 9300 | 9365 |
|
||||
| 核心功能 | 隧道增删改查 + 导入导出 TOML | 服务端配置 + 客户端状态概览 |
|
||||
|
||||
#### Q: 如果 frps-console 进程挂了，frps 本身会受影响吗？
|
||||
|
||||
**不会。**
|
||||
|
||||
这是 frp-console 系列工具与同类项目最核心的区别之一。我们称之为 **“阴阳模式”**。
|
||||
|
||||
**什么是“阴阳模式”？**
|
||||
|
||||
以人的观察为出发点：
|
||||
|
||||
- **阴**：看不见的业务流（frps 进程、toml 配置文件、隧道连接）
|
||||
- **阳**：看得见的管理面板（Web 界面、API 服务）
|
||||
|
||||
大多数管理工具走的是 **“阳阴模式”**：面板是“大脑”，业务是“肢体”。大脑一旦停止工作，肢体也就瘫痪了。
|
||||
|
||||
**frps-console 走的是“阴阳模式”：业务是根基，面板是工具。**
|
||||
|
||||
- **阴主导阳**：业务不依赖面板存活，面板只是用来观察和调整业务状态的手段
|
||||
- **阳依附于阴**：面板的存在是为了服务业务，而不是反过来
|
||||
|
||||
**二进制部署：**
|
||||
|
||||
frps-console 启动时，会以子进程的方式拉起 frps，并为它创建一个独立的进程会话（`Setsid`）。即使 SSH 断开导致 frps-console 进程退出，frps 也会被系统的 init 进程（PID 1）接管，继续在后台稳定运行。配置文件（`frps.toml`）是持久化文件，不依赖 console 进程存活。
|
||||
|
||||
**Docker 部署：**
|
||||
|
||||
容器使用 `--restart=always` 策略，frps-console 进程意外退出时，Docker 守护进程会自动重启整个容器。重启后重新拉起 frps 子进程。数据目录通过卷挂载持久化，容器重启不会丢失任何配置。
|
||||
|
||||
**核心原则：**
|
||||
|
||||
console 只做“配置的保管者”和“进程的启动者”，而不是“配置的持有者”或“进程的绑定者”。即使 console 完全离线，已经生成的 `frps.toml` 依然存在，frps 进程依然可以独立运行。
|
||||
|
||||
> **管理面板可以丢，业务功能打死不能停。**
|
||||
|
||||
#### Q: 支持 frps 的所有功能吗？
|
||||
|
||||
frps-console 覆盖了 frps 最核心的配置管理功能，包括 `bindPort`、`token`、`log`、`tcpMux` 等。如果你有更复杂的需求（如 Dashboard API 数据可视化、多 frps 管理），欢迎提 issue，我们会评估是否加入。
|
||||
|
||||
---
|
||||
|
||||
## 🧠 设计哲学
|
||||
|
||||
frps-console 遵循 **“够用就好”** 的原则：
|
||||
|
||||
1. **frp 是轻量工具，管理工具也应该是轻量的。**
|
||||
2. **能用 SQLite 就不用 PostgreSQL，能用 Vue CDN 就不用 React 全家桶。**
|
||||
3. **前端能做的事，后端不加额外复杂度。**
|
||||
4. **删掉一个容器等于删掉所有垃圾，所以用 Docker 隔离是对的。**
|
||||
5. **面板的存在应该是为了服务业务的，而不该是反过来主导业务的。**
|
||||
|
||||
---
|
||||
|
||||
## 📝 更新日志
|
||||
|
||||
### 2.0-Release（LTS，首次公开发布，与 frpc-console 2.0-LTS 同步）
|
||||
|
||||
> 这是 frps-console 的首次正式发布。frps-console 没有 1.x 系列——在 v1.x 阶段，它尚处于内部测试形态，从未公开发布。首次公开发布直接定为 **2.0-LTS**，与 frpc-console 的 LTS 版本对齐，后续版本号将与 frpc-console 保持同步。
|
||||
|
||||
· 🚀 **服务端配置管理** —— 通过 WebUI 管理 frps 核心参数，告别手动编辑 TOML</br>
|
||||
· 📊 **客户端状态概览** —— 实时查看连接到 frps 的所有客户端列表</br>
|
||||
· 📄 **运行日志面板** —— WebUI 内实时查看 frps 日志，8 秒自动轮询</br>
|
||||
· 🔄 **配置热加载** —— 修改配置后一键热加载，无需重启 frps</br>
|
||||
· 🔐 **首次启动 Web 注册** —— 无需命令行交互即可完成管理员账户创建</br>
|
||||
· 🖥️ **多平台支持** —— Linux AMD64 / ARM64 / ARMv7 全平台兼容</br>
|
||||
· 🐳 **容器化就绪** —— Docker 镜像 + 一键部署脚本，开箱即用</br>
|
||||
· 🎨 **深色磨砂玻璃 UI** —— 与 frpc-console 保持统一的视觉风格</br>
|
||||
· 🔒 **数据库自动迁移** —— 升级时自动备份 + 迁移，数据零丢失</br>
|
||||
· 🧩 **frp v2 协议就绪** —— frps 已升级至 0.70.0 LTS，原生支持 v2 协议（v2 开关在 frpc 侧开启）
|
||||
|
||||
---
|
||||
|
||||
## 📄 许可证
|
||||
|
||||
MIT License
|
||||
MIT License © 2026 lxh2875931338（XHLiang0）
|
||||
|
||||
---
|
||||
|
||||
**如果这个项目对你有用，欢迎给它点个 Star ⭐**
|
||||
**问题反馈**：Git Issues（仓库链接）
|
||||
## 🙏 相关项目援引
|
||||
|
||||
### FRP 生态互补工具
|
||||
|
||||
· [MoonProxy](https://github.com/MoonProxyHQ/moonproxy-desktop) —— 基于 Tauri v2 + Vue 3 + Rust 构建的跨平台 FRP 桌面客户端（frpc GUI），面向 macOS 与 Windows，MIT 协议开源。
|
||||
|
||||
· [frpc-console](https://git.whitetop.xyz/lxh2875931338/frpc-console) —— 姊妹篇，管理 frpc 客户端，已发布 2.0-LTS，同步 LTS 维护。
|
||||
|
||||
---
|
||||
|
||||
## 🙏 致谢
|
||||
|
||||
· fatedier/frp —— 强大的内网穿透工具</br>
|
||||
· gin-gonic/gin —— 高性能 Go Web 框架</br>
|
||||
· vuejs/vue —— 渐进式 JavaScript 框架
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user