@@ -2,70 +2,10 @@
<img src="static/logo.svg" alt="frpc-console" width="360" />
</p>
# frpc-console
[](https://git.whitetop.xyz/lxh2875931338/frpc-console/releases)
[](https://golang.org/)
[](LICENSE)
# frpc-console
**Designed for Long-Term FRP Deployment. **
A lightweight lifecycle console built from real-world engineering practice.
**安装一次。配置一次。然后忘记它。 **
---
## 📖 Documents
| | |
|---|---|
| 📖 Engineering Philosophy | 为什么它会长成今天这样 |
| 🚀 Deployment Guide | Docker、Binary、ARMHF |
| 🔄 Update Strategy | Preview / LTS |
| 🏗 Architecture | 整体架构 |
| ⚙ Design Decisions | 为什么没有 CI？为什么叫 Console？
| 🌐 Edge Node | 为什么支持 BusyBox、ARMHF |
---
> *“The best infrastructure tool is the one you rarely notice.”*
Read the full [Engineering Philosophy → ](docs/engineering-philosophy.md )
---
## 🚀 Quick Start
选择适合您环境的部署方法
[二进制安装指南 ](./INSTALL_BINARY.md )
[Docker 安装指南 ](./INSTALL_DOCKER.md )
首次访问注册管理员账户
导入你的 `frpc.toml`
然后——
**忘记它。 **
---
**MIT License © 2026 lxh2875931338（ ） ** · [GitHub ](链接 ) · [致谢 ](链接 )
---
# frpc-console
**A lightweight console for managing FRP, designed for real-world deployment. **
> 轻量级 frpc 管理面板 —— 为你的内网穿透插上翅膀
[](https://git.whitetop.xyz/lxh2875931338/frpc-console/releases)
[](https://golang.org/)
@@ -73,169 +13,43 @@ Read the full [Engineering Philosophy →](docs/engineering-philosophy.md)
---
frpc-console 并不是另一个 FRP WebUI。
## 📖 简介
它更像是一个生命周期管理工具。
**frpc-console ** 是一个专为 [frp ](https://github.com/fatedier/frp ) 设计的轻量级管理工具。本项目旨在以无限接近原生占用的情况下，实现完全图形化的控制工具（毕竟 WebUI 也算图形化，对吧？）
它不会重新定义 FRP，也不会试图接管 FRP。
### ✨ 核心特性
它只是希望：
**让 FRP 更容易部署、更容易维护，也更容易被忘记。 **
- 🔐 **首次启动引导 ** —— Web 端完成管理员注册，无需 CLI 交互
- 📋 **隧道全生命周期管理 ** —— 增删改查 + 一键启用/禁用
- 📦 **导入/导出 TOML ** —— 无缝迁移现有 frpc 配置
- 🔄 **配置热加载 ** —— 修改即生效，无需重启 frpc
- 🖥️ **多平台支持 ** —— Windows / Linux / ARM 全平台兼容
- 🐳 **容器化就绪 ** —— 提供 Docker 镜像，开箱即用
- 🎨 **深色磨砂玻璃 UI ** —— 现代化视觉体验，日夜皆宜
---
## 为什么会有这个项目？
## 🚀 快速开始
最初，这只是一个给自己 Homelab 用的小工具。
### 🐧 二进制安装（推荐）
我需要一套简单、可靠的方式管理本地运行的 frpc 。
适用于 Linux / Windows，无需 Docker，单文件运行 。
后来，在不断使用、不断重构的过程中，我意识到：
👉 详见：[二进制安装指南 ](./INSTALL_BINARY.md )
真正的问题，从来不是"有没有一个管理页面"。
### 🐳 Docker 部署（一键脚本）
而是：
**如果 FRP 是一项长期运行的基础设施，它应该长什么样？ **
于是，这个项目开始慢慢偏离最初的方向。
它不再只是一个 Web 面板，而是开始关注：
- 生命周期管理
- 长期维护
- 多种部署方式
- 极简运行环境
- 用户真实的使用场景
直到今天。
---
## 设计目标
frpc-console 希望成为这样一种工具：
**安装。配置。运行。然后，忘记它。 **
真正优秀的基础设施，不应该每天提醒用户自己的存在。
它应该像交换机、路由器、UPS 一样——平时不会想到它，但需要的时候，它一直在那里。
---
## 稳定性与可观测性
"安装、配置、运行，然后忘记它"。
但请记住：**忘记，不等于失控。**
frpc-console 在设计上始终保持一个原则：
**工具自身的开销，不应该成为需要被关注的对象。 **
所以：
- 主进程在 idle 状态下 CPU 占用接近 0%
- 内存占用控制在 20MB 以内
- 没有额外的后台守护进程
- 没有定期轮询的健康检查
- 不会主动写入日志文件，除非你明确开启
下图是在真实设备上同时运行 frpc 和 frpc-console 的资源占用情况：
![resource-usage]()
你可以看到：
- frpc：
- frpc-console：
两者加起来不到 30MB。
这意味着：
**你可以忘记它。 **
但如果有一天，你想知道它是否还在正常工作——
打开浏览器，看一眼。
然后，继续忘记它。
如果它真的出了什么问题，它的表现也很简单：
要么进程还在，要么进程不在了。
没有中间状态。
没有僵尸进程。
没有需要手动清理的残留文件。
因为对于基础设施来说：
**确定性，比灵活性更重要。 **
---
## 界面与核心能力
frpc-console 提供的是一个**图形化的生命周期管理工具**，而不是一个功能堆砌的控制台。
它只做这几件事：
- **首次启动引导**：Web 端完成管理员注册，无需 CLI 交互
- **隧道全生命周期管理**：增删改查 + 一键启用/禁用
- **导入/导出 TOML**：无缝迁移现有 frpc 配置
- **配置热加载**：修改即生效，无需重启 frpc
- **配置备份与恢复**
- **进程管理**
- **数据库维护工具**
功能并不追求数量，而是追求：
**真正有用。 **
界面采用深色磨砂玻璃视觉风格，设计目标是：
**当你需要它的时候，它清晰易用；当你不需要它的时候，它不打扰你。 **
---
## 快速开始
### 一键部署（推荐，Linux）
适用于 Linux 服务器，自动编译 + 自动部署。
``` bash
curl -sSL https://git.whitetop.xyz/lxh2875931338/frpc-console/raw/main/run- deploy.sh | sudo bash
curl -sSL https://git.whitetop.xyz/lxh2875931338/frpc-console/raw/main/deploy.sh | sudo bash
```
脚本会引导你选择 LTS 或 Preview 通道，然后自动完成全部部署。
👉 详见：[Docker 安装指南 ](./INSTALL_DOCKER.md )
### Docker 手动部署
### 🔧 源码编译
``` bash
docker run -d \
--name frpc-console \
--restart= always \
--network host \
-v /opt/frpc-console/data:/app/data \
-e PORT = 9300 \
-e TZ = Asia/Shanghai \
frpc-console:lts
```
### 二进制部署
适用于 Linux / Windows，单文件运行，无需 Docker。
从 [Releases ](https://git.whitetop.xyz/lxh2875931338/frpc-console/releases ) 下载对应平台的二进制文件，直接运行即可。
首次访问 `http://localhost:9300` 注册管理员账户，然后导入你的 `frpc.toml` 开始使用。
### 源码编译
适合开发者或需要自定义配置的用户。
``` bash
git clone https://git.whitetop.xyz/lxh2875931338/frpc-console.git
@@ -245,224 +59,200 @@ go build -o frpc-console .
./frpc-console
```
---
## 部署哲学：
### 没有 CI/CD 的 CI/CD
这个项目没有复杂的 CI/CD 发布流程。
不是做不到，而是选择不做。
因为每一次部署，都应该在真实环境中被验证。
所以，部署脚本就是发布流水线：
- 拉取代码 → 构建镜像 → 启动容器 → 写入版本 → 检查进程
- 支持 `--dry-run` 预览、`--check` 环境检测
- 降级前自动备份数据库
- 保留最近 3 个镜像，便于回滚
开发过程中使用的更新链路，就是最终用户使用的更新链路。
没有特权通道，没有隐藏开关。
你用的，就是我用的。
因此，每一次更新，实际上都在验证整个部署流程。
这也是为什么，很多部署细节都是在真实环境中一点一点演化出来的。
### 阴阳模式：面板可以挂，隧道不能停
这是 frpc-console 与同类项目最核心的区别。
**大多数管理工具走的是"阳阴模式"： **
面板是大脑，业务是肢体。大脑一旦停止工作，肢体也就瘫痪了。
**frpc-console 走的是"阴阳模式"： **
业务是根基，面板是工具。
- **阴**：看不见的业务流（frpc 进程、TOML 配置文件）
- **阳**：看得见的管理面板（Web 界面、API 服务）
#### 二进制部署
frpc-console 启动时，通过 `Setsid` 为 frpc 创建独立会话，使其完全脱离父进程的生命周期控制。
即使 SSH 断开导致 console 退出，frpc 也会被 init 进程（PID 1）接管，继续稳定运行。
#### Docker 部署
容器使用 `--restart=always` ，
数据目录通过卷挂载持久化，配置不丢失。
两种部署方式的本质一致：
**面板是"阳"，服务于"阴"； **
> **管理面板可以丢，业务功能打死不能停。**
首次访问 `http://localhost:9300` 注册管理员账户，然后导入你的 `frpc.toml` 即可开始使用。
---
## 为什么支持 ARMHF？
## 🗂️ 项目结构
``` 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
```
因为很多时候，真正需要这种工具的，并不是性能很强的服务器。
## ⚙️ 配置说明
而是一块全志 H3、RK3506，或者老旧 ARM 开发板——放在弱电箱里的边缘节点。
### 环境变量
它们可能没有 Docker，没有 systemd，甚至只有：
| 变量 | 说明 | 默认值 |
|---|---|---|
| PORT | 监听端口 | 9300 |
- Kernel
- BusyBox
- init
但它们依然承担着网络基础设施的工作。
### 数据存储
对于这些设备来说，图形化管理反而比高性能服务器更重要。
· 数据库文件：./frpc-console.db</br>
· frpc 配置文件：./frpc.toml</br>
· frpc 日志文件：./frpc.log</br>
---
## Design Philosophy
## 🛠️ 开发指南
### 工具应该降低复杂度，而不是增加复杂度
``` bash
# 克隆项目
git clone https://github.com/lxh2875931338/frpc-console.git
cd frpc-console
GUI 的意义，并不是隐藏配置文件，而是**降低维护成本**。
# 安装依赖
go mod tidy
如果一个图形界面最终比命令行更复杂，那么它已经偏离了存在的意义。
# 开发模式运行
go run .
### 每增加一个功能，都意味着新的维护成本
# 编译生产版本
go build -ldflags= "-s -w" -o frpc-console .
```
功能不是越多越好。
## 前端开发
一个功能只有在真正改善体验时才值得存在。否则，宁可不做 。
前端使用 Vue 3 CDN + Naive UI，无需额外构建工具。修改 static/ 目录下的文件后，刷新浏览器即可预览效果 。
这也是为什么：有些别人认为"理所当然"的功能，这里没有。不是不会，而是不值得。
### 用户不是测试员
这个项目的大多数设计，都来自于真实使用。
开发者，也是第一个用户。
如果一个设计连我自己都不愿意每天面对，那么它不会进入正式版本。
### Docker 不是目标
Docker 很重要，Binary 同样重要。
真正重要的是：**无论运行在哪里，体验应该保持一致。**
Docker、x86、ARM64、ARMHF，甚至极简 Linux——都应该拥有同样的管理体验。
### Real World First
这个项目的很多设计，都来自于真实部署，而不是 Demo。
例如：
- Docker 更新顺序
- Git 拉取时机
- 编译流程
- 边缘部署
- 二进制运行
- BusyBox 环境
很多看起来"奇怪"的实现，其实都来自于**踩坑**。
不是设计出来的，而是试出来的。
### 存储换内存，在嵌入式平台上不是交易，是生存策略
镜像可以大几十 MB，但内存必须省。
因为内存卡便宜，内存颗粒贵。
对于 RK3506（ （
牺牲一点存储空间（镜像大了几十 MB），换来 50MB 以内的内存占用，这笔账怎么算都不亏。
---
## 关于版本
## 🔧 常见问题
项目采用 **Preview / LTS ** 双线开发模式：
- **Preview**：用于验证新的设计与实现（test 分支）
- **LTS**：保持稳定，并持续滚动维护（main 分支）
某些修复不会等待下一个大版本。
因为对于基础设施而言，**稳定比版本号更重要**。
---
## What This Project Is Not
这个项目：
- 不追求成为功能最多的 FRP 管理平台
- 不追求重新定义 FRP
- 不追求构建自己的生态
- 不追求让用户每天打开它
它只是希望：
**把复杂留给软件，把简单留给用户。 **
---
## 常见问题
**Q：如果 frpc-console 进程挂了，frpc 本身会受影响吗？ **
不会。这就是"阴阳模式"的意义。详见上文。
**Q：如何修改管理员密码？ **
#### Q: 如何修改管理员密码？
登录后，在「全局配置」页面顶部找到「账户管理」区域，输入当前密码和新密码即可。
**Q： 如何导入现有的 frpc.toml？ **
#### Q: 如何导入现有的 frpc.toml？
在「隧道列表」页面点击「导入 TOML」，选择你的 frpc.toml 文件即可。
**Q： frpc 启动失败怎么办？**
#### Q: frpc 启动失败怎么办？
如果是首次启动，console 会自动生成一份符合官方规范的 `frpc .toml` 配置文件，通常不需要额外操作。
如果是首次启动，console 会自动生成一份符合官方规范的 `frps .toml` 配置文件，通常不需要额外操作。
如果使用中遇到启动失败：
1. 在「全局配置」页面重新配置服务端参数，或导入已有的 `frpc.toml`
2. 查看 `frpc.log` 日志文件定位具体报错原因
如果在 使用过程 中遇到启动失败，可以按以下步骤排查 ：
日志文件位置：与二进制同级目录下的 `frpc.log` 。Docker 部署时通过 `docker logs frpc-console` 查看。
1. **检查配置是否正确 ** —— 在「全局配置」页面重新配置一次服务端参数，或导入已有的 `frpc.toml` 配置文件，console 会自动应用并尝试重启
2. **查看日志定位问题 ** —— 若上述操作后仍然失败，请查看 `./frpc.log` 日志文件，定位具体报错原因
**Q：支持哪些 frp 版本？ **
> 日志文件的位置：与 `frpc-console` 二进制同级目录下的 `frpc.log`。Docker 部署时，可通过 `docker logs frpc-console` 查看容器输出。
| 系统 | 架构 | 版本 |
#### 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） ）
| 前端 | 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 安装在哪里，也忘记它上一次更新是什么时候。
frpc-console 遵循 * * “够用就好”** 的原则：
但是：
- FRP 依然稳定运行
- 偶尔需要修改配置
- 打开浏览器
- 两分钟完成
- 关闭
- 继续忘记它
那么，它已经完成了自己的使命。
1. **frp 是轻量工具，管理工具也应该是轻量的。 **
2. **能用 SQLite 就不用 PostgreSQL，能用 Vue CDN 就不用 React 全家桶。 **
3. **前端能做的事，后端不加额外复杂度。 **
4. **删掉一个容器等于删掉所有垃圾，所以用 Docker 隔离是对的。 **
5. **面板的存在应该是为了服务业务的，而不该是反过来主导业务的。 **
---
@@ -487,12 +277,10 @@ MIT License © 2026 lxh2875931338（ ）
### FRP 生态同类工具（暂无互引）
</br>
## 致谢
- [fatedier/frp ](https://github.com/fatedier/frp ) —— 强大的内网穿透工具
- [gin-gonic/gin ](https://github.com/gin-gonic/gin ) —— 高性能 Go Web 框架
- [vuejs/vue ](https://github.com/vuejs/vue ) —— 渐进式 JavaScript 框架
---
## 🙏 致谢
· fatedier/frp —— 强大的内网穿透工具</br>
· gin-gonic/gin —— 高性能 Go Web 框架</br>
· vuejs/vue —— 渐进式 JavaScript 框架
lxh2875931338