lxh2875931338/frpc-console
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 5 Wiki Activity
Files
2.0-LTS
frpc-console/readme.md
T

311 lines
13 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
<p align="center">
<img src="static/logo.svg" alt="frpc-console" width="360" />
</p>
# frpc-console
> 轻量级 frpc 管理面板 —— 为你的内网穿透插上翅膀
[![Release](https://img.shields.io/gitea/v/release/lxh2875931338/frpc-console?gitea_url=https://git.whitetop.xyz)](https://git.whitetop.xyz/lxh2875931338/frpc-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)
---
## 📖 简介
**frpc-console** 是一个专为 [frp](https://github.com/fatedier/frp) 设计的轻量级管理工具。本项目旨在以无限接近原生占用的情况下，实现完全图形化的控制工具（毕竟 WebUI 也算图形化，对吧？）
### ✨ 核心特性
- 🔐 **首次启动引导** —— Web 端完成管理员注册，无需 CLI 交互
- 📋 **隧道全生命周期管理** —— 增删改查 + 一键启用/禁用
- 📦 **导入/导出 TOML** —— 无缝迁移现有 frpc 配置
- 🔄 **配置热加载** —— 修改即生效，无需重启 frpc
- 🖥️ **多平台支持** —— Windows / Linux / ARM 全平台兼容
- 🐳 **容器化就绪** —— 提供 Docker 镜像，开箱即用
- 🎨 **深色磨砂玻璃 UI** —— 现代化视觉体验，日夜皆宜
---
## 🚀 快速开始
### 🐧 二进制安装（推荐）
适用于 Linux / Windows，无需 Docker，单文件运行。
👉 详见：[二进制安装指南](./INSTALL_BINARY.md)
### 🐳 Docker 部署（一键脚本）
适用于 Linux 服务器，自动编译 + 自动部署。
```bash
curl -sSL https://git.whitetop.xyz/lxh2875931338/frpc-console/raw/main/deploy.sh | sudo bash
```
👉 详见：[Docker 安装指南](./INSTALL_DOCKER.md)
### 🔧 源码编译
适合开发者或需要自定义配置的用户。
```bash
git clone https://git.whitetop.xyz/lxh2875931338/frpc-console.git
cd frpc-console
go mod tidy
go build -o frpc-console .
./frpc-console
```
首次访问 `http://localhost:9300` 注册管理员账户，然后导入你的 `frpc.toml` 即可开始使用。
---
## 🗂️ 项目结构
```txt
frpc-console/
├── main.go # 入口
├── api.go # HTTP 路由 & Handler
├── db.go # SQLite 数据库操作
├── auth.go # JWT 认证 & 密码管理
├── frp.go # frpc 管理核心逻辑
├── toml_parser.go # TOML 解析器
├── static/ # 前端静态资源
│ ├── index.html
│ ├── app.js
│ ├── style-1.css # 全局基础样式
│ ├── style-2.css # 登录页样式
│ ├── style-3.css # 主界面样式
└── style-4.css
├── bin/ # 内嵌 frpc 二进制 (多平台)
│ ├── frpc_windows_amd64.exe
│ ├── frpc_linux_amd64
│ ├── frpc_linux_arm64
│ └── frpc_linux_arm_hf
├── frpc.tmpl # frpc 配置模板
├── Dockerfile
└── go.mod
```
## ⚙️ 配置说明
### 环境变量
| 变量 | 说明 | 默认值 |
|---|---|---|
| PORT | 监听端口 | 9300 |
### 数据存储
· 数据库文件：./frpc-console.db</br>
· frpc 配置文件：./frpc.toml</br>
· frpc 日志文件：./frpc.log</br>
---
## 🛠️ 开发指南
```bash
# 克隆项目
git clone https://github.com/lxh2875931338/frpc-console.git
cd frpc-console
# 安装依赖
go mod tidy
# 开发模式运行
go run .
# 编译生产版本
go build -ldflags="-s -w" -o frpc-console .
```
## 前端开发
前端使用 Vue 3 CDN + Naive UI，无需额外构建工具。修改 static/ 目录下的文件后，刷新浏览器即可预览效果。
---
## 🔧 常见问题
#### Q: 如何修改管理员密码？
登录后，在「全局配置」页面顶部找到「账户管理」区域，输入当前密码和新密码即可。
#### Q: 如何导入现有的 frpc.toml？
在「隧道列表」页面点击「导入 TOML」，选择你的 frpc.toml 文件即可。
#### Q: frpc 启动失败怎么办？
检查 frpc.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 |
| Windows | AMD64/x86-64 | 0.70.0 |
> 行了行了，Windows 版和 Linux 版版本号已同步。不用再等了。
#### Q: 为什么不用 / 不推荐 Podux？
Podux 是个好项目，理念上和我们是一致的：用 Web 界面管理 frpc</br>
但它的设计取向和我们完全不同：
| 对比项 | frpc-console | Podux |
|---|---|---|
| 数据库 | SQLite（单文件，几 MB） | PocketBase（带 Admin UI、用户系统、全套 API） |
| 前端 | Vue CDN | React + Webpack |
| 实机内存占用 | **~50 MB** | **没启动成功，1GB RAM 独立分配仍 OOM（原因不明）** |
| 镜像大小 | 封装多平台二进制frpc后 120.28 MB | 76.1 MB |
| 部署方式 | 单二进制 / Docker | 单二进制 / Docker |
| 多平台支持 | ✅ 原生交叉编译 | ✅ 原生交叉编译 |
> Podux 与其说是一个 frp 控制面板，不如说是一个“一站式 frp 管理器 + 可视化数据流面板 + 通道保活监测工具”。这种一站式本身没毛病，甚至功能实现非常到位。</br>但 podux的框架选型有点重，而且很明显细节稍显仓促。PocketBase 自带 WebUI 的情况下，Podux 还要再包一层 WebUI——相当于给数据库的 UI 又套了个 UI。更费解的是，这层 WebUI 只支持导入，不支持导出。这设计确实让人有点摸不着头脑啦……</br>所以干脆换了一套轻量化工具自己上咯~
### Q: 为什么不直接用 frp 官方提供的 web 界面？
frp 官方确实提供了 `dashboard` 和 `frpc-admin` 功能，但它们更多是“监控”视角，而非“管理”视角。你需要手动编辑配置文件，重启 frpc，或者依赖命令行操作。
frpc-console 的目标是：
- **点一点就能新增隧道**
- **开关一拨就能启用/禁用**
- **导入导出无缝迁移**
- **热加载无需重启**
### Q: 如果 frpc-console 进程挂了，frpc 本身会受影响吗？
**不会。**
这是 frp-console 系列工具与同类项目最核心的区别之一。我们称之为 **“阴阳模式”**。</br>
接下来，我们将结合中式哲学思想，阐述这个名称的由来：
#### 什么是“阴阳模式”？
以人的观察为出发点：
- **阴**：看不见的业务流（frpc 进程、toml 配置文件、隧道连接）
- **阳**：看得见的管理面板（Web 界面、API 服务）
大多数管理工具走的是 **“阳阴模式”**：面板是“大脑”，业务是“肢体”。大脑一旦停止工作，肢体也就瘫痪了。</br>
在这种模式下，管理面板与业务进程深度绑定，面板退出时业务进程也会随之终止。
**frpc-console 走的是“阴阳模式”：业务是根基，面板是工具。**
- **阴主导阳**：业务不依赖面板存活，面板只是用来观察和调整业务状态的手段
- **阳依附于阴**：面板的存在是为了服务业务，而不是反过来
#### 不同部署方式下的行为
**二进制部署：**
frpc-console 启动时，会以子进程的方式拉起 frpc，并为它创建一个独立的进程会话（`Setsid`）。这意味着 frpc 完全脱离父进程的生命周期控制。即使 SSH 断开导致 frpc-console 进程退出，frpc 也会被系统的 init 进程（PID 1）接管，继续在后台稳定运行。配置文件（`frpc.toml`）是持久化文件，不依赖 console 进程存活。面板可以随时挂、随时重启、随时升级，但隧道业务不受任何干扰。
**Docker 部署：**
容器使用 `--restart=always` 策略，frpc-console 进程意外退出时，Docker 守护进程会自动重启整个容器。重启后，console 重新读取持久化的 `frpc.toml`，重新拉起 frpc 子进程。数据目录（`/opt/frpc-console/data`）通过卷挂载持久化，容器重启不会丢失任何配置。Docker 模式的本质依然是“阳辅助阴”——`restart:always` 的目的是确保阴（业务）持续运行，而不是为了保住阳（面板）本身。
#### 为什么同类项目里很少见到这种设计？
因为大多数管理工具把“面板”和“业务”耦合在一起，认为面板是前提条件，业务是附属品。当然了，这确实是正向的、符合直觉的设计方向。但是有一个被很多人忽略的事实：**真正需要长期稳定运行的是隧道本身，而不是管理界面的进程。**
界面是用来观察和调整的，不是用来维持业务存活的。这是运维集群常用的“管理面与控制面分离”——只不过通常只在几千台服务器的集群管理里才会出现，很少有人会把它用在一个人用的 frp 管理工具上。
#### 核心原则
console 只做“配置的保管者”和“进程的启动者”，而不是“配置的持有者”或“进程的绑定者”。即使 console 完全离线，已经生成的 `frpc.toml` 依然存在，frpc 进程依然可以独立运行。这是 frp 本身的容灾能力在管理工具层面的自然延伸——**可视化框架只是工具，业务本身才是核心。**
> **管理面板可以丢，业务功能打死不能停。**
### Q: 支持 frp 的所有功能吗？
frpc-console 覆盖了 frp 最核心的 **TCP 隧道管理** 功能，包括 `tcpMux`、负载均衡、心跳配置等。如果你有更复杂的需求（比如 STCP、XTCP、P2P），欢迎提 issue，我们会评估是否加入。
---
## 🧠 设计哲学
frpc-console 遵循 **“够用就好”** 的原则：
1. **frp 是轻量工具，管理工具也应该是轻量的。**
2. **能用 SQLite 就不用 PostgreSQL，能用 Vue CDN 就不用 React 全家桶。**
3. **前端能做的事，后端不加额外复杂度。**
4. **删掉一个容器等于删掉所有垃圾，所以用 Docker 隔离是对的。**
5. **面板的存在应该是为了服务业务的，而不该是反过来主导业务的。**
---
## 📝 更新日志
### 2.0-Release（LTS，跟随上游提供支持，frps 端现已正式发布，frpc 端测试中，敬请期待……）
> 本次 LTS 版本聚焦于**稳定性兜底与协议能力对齐**，是 frp 0.70.0 LTS 的下游管理工具。
· 🚀 **frp v2 协议正式启用** —— `wireProtocol = "v2"` 配置项可用，灰标状态解除，实测稳定</br>
· 🔒 **数据库迁移引擎完整实现** —— 版本驱动的增量迁移 + 迁移前自动全量备份 + 失败可回滚，升级不再提心吊胆</br>
· 🧩 **配套工具 frps-console 同步发布** —— 同一套设计哲学，一个管理 frpc，一个管理 frps，版本号同步，LTS 同步
### 1.5-Release (2026-07-25)（non-LTS）
> 本次更新聚焦于**WebUI 交互体验与基础工程能力**，为 2.0 LTS 铺路。
· ✨ **全局配置页面卡片式重构** —— 按“服务器连接 / 传输配置 / 日志配置”分组，告别折叠面板</br>
· ✨ **新增运行日志面板** —— WebUI 内实时查看 frpc 日志，8 秒自动轮询，最大 200 行，调试方便不少</br>
· ✨ **frp v2 配置占位** —— UI 开关已就绪（灰标禁用），为 2.0 的正式启用做好铺垫</br>
· 🔩 **数据库 Schema 迁移框架** —— 启动时自动检测并补全缺失列，升级不再依赖手动改表（2.0 在此基础上升级为完整备份 + 回滚）</br>
· 🔐 **默认配置脱敏** —— 移除个人服务端地址与令牌，改为通用占位符，避免开箱即连别人的服务器</br>
· 🎨 **样式拆分与优化** —— 按职责拆分为多个 CSS 文件，维护更清晰
### 1.0-Release (2026-07-24)（non-LTS）
> 首次发布，核心功能全部就绪。
· 🎉 **首次发布**</br>
· 📋 **隧道全生命周期管理** —— 增删改查 + 一键启用/禁用</br>
· 📦 **TOML 导入/导出** —— 无缝迁移现有 frpc 配置</br>
· 🔄 **配置热加载** —— 修改即生效，无需重启 frpc</br>
· 🔐 **首次启动 Web 注册** —— 无需命令行交互</br>
· 🖥️ **多平台支持** —— Windows / Linux / ARM 全平台兼容</br>
· 🐳 **容器化就绪** —— Docker 镜像，开箱即用</br>
· 🎨 **深色磨砂玻璃 UI** —— 现代化视觉体验</br>
---
## 📄 许可证
MIT License © 2026 Gitea:lxh2875931338/Github:XHLiang0
---
## 🙏 相关项目援引
### FRP 生态互补工具
· [MoonProxy](https://github.com/MoonProxyHQ/moonproxy-desktop) —— 基于 Tauri v2 + Vue 3 + Rust 构建的跨平台 FRP 桌面客户端（frpc GUI），面向 macOS 与 Windows，让内网穿透开箱即用，MIT协议开源。
### FRP 生态同类工具（暂无互引）
</br>
---
## 🙏 致谢
· fatedier/frp —— 强大的内网穿透工具</br>
· gin-gonic/gin —— 高性能 Go Web 框架</br>
· vuejs/vue —— 渐进式 JavaScript 框架
Reference in New Issue View Git Blame Copy Permalink