diff --git a/License.md b/License.md new file mode 100644 index 0000000..5bf32f6 --- /dev/null +++ b/License.md @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 lxh2875931338(XHLiang0) + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. \ No newline at end of file diff --git a/readme.md b/readme.md index d7ff3fb..d94ca02 100644 --- a/readme.md +++ b/readme.md @@ -1,177 +1,260 @@ -好的,我先去看了你 frpc-console 的 README 风格——**冷峻、务实、带点极客式骄傲,把“哲学”和“代码”焊在一起**。我按这个调性帮你写 frps-console 的 README,直接可粘贴。 - ---- +

+ frps-console +

# frps-console -> 🚀 轻量级 frps 服务端管理面板 | 管理面与控制面分离 | 内存 < 100MB +> 轻量级 frps 服务端管理面板 —— 让流量中转尽在掌握 -**frps-console** 是专为 **frps(服务端)** 设计的轻量 Web 管理工具。内嵌多平台 frps 二进制文件(v0.70.0),提供极简 Web UI 进行配置管理、客户端监控、日志查看。 - -与同类工具最本质的区别是:**frps 业务进程与 Web 管理进程完全解耦**。即使面板意外崩溃、升级重启,已建立的穿透隧道也绝不中断。 +[![Release](https://img.shields.io/gitea/v/release/lxh2875931338/frps-console?gitea_url=https://git.whitetop.xyz)](https://git.whitetop.xyz/lxh2875931338/frps-console/releases) +[![Go Version](https://img.shields.io/badge/Go-1.21+-00ADD8?style=flat&logo=go)](https://golang.org/) +[![License](https://img.shields.io/badge/License-MIT-blue.svg)](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`
+· frps 配置文件:`./frps.toml`
+· frps 日志文件:`./frps.log`
+--- + +## 🛠️ 开发指南 + +```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配置文件。
+如果使用中出现启动失败问题,可以在console内重新配置一次服务端参数,或者导入已有的toml即可恢复
+如果依旧无效,请查看 ./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
+· 📊 **客户端状态概览** —— 实时查看连接到 frps 的所有客户端列表
+· 📄 **运行日志面板** —— WebUI 内实时查看 frps 日志,8 秒自动轮询
+· 🔄 **配置热加载** —— 修改配置后一键热加载,无需重启 frps
+· 🔐 **首次启动 Web 注册** —— 无需命令行交互即可完成管理员账户创建
+· 🖥️ **多平台支持** —— Linux AMD64 / ARM64 / ARMv7 全平台兼容
+· 🐳 **容器化就绪** —— Docker 镜像 + 一键部署脚本,开箱即用
+· 🎨 **深色磨砂玻璃 UI** —— 与 frpc-console 保持统一的视觉风格
+· 🔒 **数据库自动迁移** —— 升级时自动备份 + 迁移,数据零丢失
+· 🧩 **frp v2 协议就绪** —— frps 已升级至 0.70.0 LTS,原生支持 v2 协议(v2 开关在 frpc 侧开启) --- ## 📄 许可证 -MIT License +MIT License © 2026 lxh2875931338(XHLiang0) --- -**如果这个项目对你有用,欢迎给它点个 Star ⭐** -**问题反馈**:Git Issues(仓库链接) \ No newline at end of file +## 🙏 相关项目援引 + +### 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 —— 强大的内网穿透工具
+· gin-gonic/gin —— 高性能 Go Web 框架
+· vuejs/vue —— 渐进式 JavaScript 框架 +```