495 lines
13 KiB
Markdown
495 lines
13 KiB
Markdown
<p align="center">
|
||
<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.
|
||
|
||
**安装一次。配置一次。然后忘记它。**
|
||
|
||
---
|
||
|
||
## 📖 文档索引
|
||
|
||
| | |
|
||
|---|---|
|
||
| [📖 工程设计哲学](./Docs/engineering-philosophy.md) | 为什么它会长成今天这样 |
|
||
| [🔄 更新策略](./Docs/update-strategy.md) | Preview / LTS |
|
||
| [🏗 架构设计](./Docs/architecture.md) | 整体架构设计思路 |
|
||
| [⚙ 设计决策](./Docs/design-decisions.md) | 为什么没有 CI？为什么叫 Console？ |
|
||
| [🌐 边缘节点](./Docs/edge-node.md) | 为什么支持 BusyBox、ARMHF |
|
||
|
||
|
||
[🌐 边缘节点](./Docs/edge-node.md)
|
||
---
|
||
|
||
> *“The best infrastructure tool is the one you rarely notice.”*
|
||
|
||
阅读完整版 [工程设计哲学 →](./Docs/engineering-philosophy.md)
|
||
|
||
---
|
||
|
||
## 🚀 快速开始
|
||
|
||
选择适合您环境的部署方法：
|
||
|
||
- [二进制安装指南](./Docs/INSTALL_BINARY.md)
|
||
- [Docker 安装指南](./Docs/INSTALL_DOCKER.md)
|
||
|
||
首次访问请注册管理员账户
|
||
|
||
导入你的 `frpc.toml`
|
||
|
||
然后——
|
||
|
||
**忘记它。**
|
||
|
||
---
|
||
|
||
**MIT License © 2026 lxh2875931338（XHLiang0）** · [GitHub](链接) · [致谢](链接)
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
# frpc-console
|
||
|
||
**A lightweight console for managing FRP, designed for real-world deployment.**
|
||
|
||
[](https://git.whitetop.xyz/lxh2875931338/frpc-console/releases)
|
||
[](https://golang.org/)
|
||
[](LICENSE)
|
||
|
||
---
|
||
|
||
frpc-console 并不是另一个 FRP WebUI。
|
||
|
||
它更像是一个生命周期管理工具。
|
||
|
||
它不会重新定义 FRP，也不会试图接管 FRP。
|
||
|
||
它只是希望：
|
||
|
||
**让 FRP 更容易部署、更容易维护，也更容易被忘记。**
|
||
|
||
---
|
||
|
||
## 为什么会有这个项目？
|
||
|
||
最初，这只是一个给自己 Homelab 用的小工具。
|
||
|
||
我需要一套简单、可靠的方式管理本地运行的 frpc。
|
||
|
||
后来，在不断使用、不断重构的过程中，我意识到：
|
||
|
||
真正的问题，从来不是"有没有一个管理页面"。
|
||
|
||
而是：
|
||
|
||
**如果 FRP 是一项长期运行的基础设施，它应该长什么样？**
|
||
|
||
于是，这个项目开始慢慢偏离最初的方向。
|
||
|
||
它不再只是一个 Web 面板，而是开始关注：
|
||
|
||
- 生命周期管理
|
||
- 长期维护
|
||
- 多种部署方式
|
||
- 极简运行环境
|
||
- 用户真实的使用场景
|
||
|
||
直到今天。
|
||
|
||
---
|
||
|
||
## 设计目标
|
||
|
||
frpc-console 希望成为这样一种工具：
|
||
|
||
**安装。配置。运行。然后，忘记它。**
|
||
|
||
真正优秀的基础设施，不应该每天提醒用户自己的存在。
|
||
|
||
它应该像交换机、路由器、UPS 一样——平时不会想到它，但需要的时候，它一直在那里。
|
||
|
||
---
|
||
|
||
## 稳定性与可观测性
|
||
|
||
"安装、配置、运行，然后忘记它"。
|
||
|
||
但请记住：**忘记，不等于失控。**
|
||
|
||
frpc-console 在设计上始终保持一个原则：
|
||
|
||
**工具自身的开销，不应该成为需要被关注的对象。**
|
||
|
||
所以：
|
||
|
||
- 主进程在 idle 状态下 CPU 占用接近 0%
|
||
- 内存占用控制在 20MB 以内
|
||
- 没有额外的后台守护进程
|
||
- 没有定期轮询的健康检查
|
||
- 不会主动写入日志文件，除非你明确开启
|
||
|
||
下图是在真实设备上同时运行 frpc 和 frpc-console 的资源占用情况：
|
||
|
||
![resource-usage]()
|
||
|
||
你可以看到：
|
||
|
||
- frpc：CPU 0.45%，内存 13.25MB
|
||
- frpc-console：CPU 0.00%，内存 15.64MB
|
||
|
||
两者加起来不到 30MB。
|
||
|
||
这意味着：
|
||
|
||
**你可以忘记它。**
|
||
|
||
但如果有一天，你想知道它是否还在正常工作——
|
||
|
||
打开浏览器，看一眼。
|
||
|
||
然后，继续忘记它。
|
||
|
||
如果它真的出了什么问题，它的表现也很简单：
|
||
|
||
要么进程还在，要么进程不在了。
|
||
|
||
没有中间状态。
|
||
|
||
没有僵尸进程。
|
||
|
||
没有需要手动清理的残留文件。
|
||
|
||
因为对于基础设施来说：
|
||
|
||
**确定性，比灵活性更重要。**
|
||
|
||
---
|
||
|
||
## 界面与核心能力
|
||
|
||
frpc-console 提供的是一个**图形化的生命周期管理工具**，而不是一个功能堆砌的控制台。
|
||
|
||
它只做这几件事：
|
||
|
||
- **首次启动引导**：Web 端完成管理员注册，无需 CLI 交互
|
||
- **隧道全生命周期管理**：增删改查 + 一键启用/禁用
|
||
- **导入/导出 TOML**：无缝迁移现有 frpc 配置
|
||
- **配置热加载**：修改即生效，无需重启 frpc
|
||
- **配置备份与恢复**
|
||
- **进程管理**
|
||
- **数据库维护工具**
|
||
|
||
功能并不追求数量，而是追求：
|
||
|
||
**真正有用。**
|
||
|
||
界面采用深色磨砂玻璃视觉风格，设计目标是：
|
||
|
||
**当你需要它的时候，它清晰易用；当你不需要它的时候，它不打扰你。**
|
||
|
||
---
|
||
|
||
## 快速开始
|
||
|
||
### 一键部署（推荐，Linux）
|
||
|
||
```bash
|
||
curl -sSL https://git.whitetop.xyz/lxh2875931338/frpc-console/raw/main/run-deploy.sh | sudo bash
|
||
```
|
||
|
||
脚本会引导你选择 LTS 或 Preview 通道，然后自动完成全部部署。
|
||
|
||
### 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
|
||
cd frpc-console
|
||
go mod tidy
|
||
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`，console 退出时 Docker 自动重启并重新拉起 frpc。
|
||
|
||
数据目录通过卷挂载持久化，配置不丢失。
|
||
|
||
两种部署方式的本质一致：
|
||
|
||
**面板是"阳"，服务于"阴"；"阴"不依赖"阳"而存在。**
|
||
|
||
> **管理面板可以丢，业务功能打死不能停。**
|
||
|
||
---
|
||
|
||
## 为什么支持 ARMHF？
|
||
|
||
因为很多时候，真正需要这种工具的，并不是性能很强的服务器。
|
||
|
||
而是一块全志 H3、RK3506，或者老旧 ARM 开发板——放在弱电箱里的边缘节点。
|
||
|
||
它们可能没有 Docker，没有 systemd，甚至只有：
|
||
|
||
- Kernel
|
||
- BusyBox
|
||
- init
|
||
|
||
但它们依然承担着网络基础设施的工作。
|
||
|
||
对于这些设备来说，图形化管理反而比高性能服务器更重要。
|
||
|
||
---
|
||
|
||
## Design Philosophy
|
||
|
||
### 工具应该降低复杂度，而不是增加复杂度
|
||
|
||
GUI 的意义，并不是隐藏配置文件，而是**降低维护成本**。
|
||
|
||
如果一个图形界面最终比命令行更复杂，那么它已经偏离了存在的意义。
|
||
|
||
### 每增加一个功能，都意味着新的维护成本
|
||
|
||
功能不是越多越好。
|
||
|
||
一个功能只有在真正改善体验时才值得存在。否则，宁可不做。
|
||
|
||
这也是为什么：有些别人认为"理所当然"的功能，这里没有。不是不会，而是不值得。
|
||
|
||
### 用户不是测试员
|
||
|
||
这个项目的大多数设计，都来自于真实使用。
|
||
|
||
开发者，也是第一个用户。
|
||
|
||
如果一个设计连我自己都不愿意每天面对，那么它不会进入正式版本。
|
||
|
||
### Docker 不是目标
|
||
|
||
Docker 很重要，Binary 同样重要。
|
||
|
||
真正重要的是：**无论运行在哪里，体验应该保持一致。**
|
||
|
||
Docker、x86、ARM64、ARMHF，甚至极简 Linux——都应该拥有同样的管理体验。
|
||
|
||
### Real World First
|
||
|
||
这个项目的很多设计，都来自于真实部署，而不是 Demo。
|
||
|
||
例如：
|
||
|
||
- Docker 更新顺序
|
||
- Git 拉取时机
|
||
- 编译流程
|
||
- 边缘部署
|
||
- 二进制运行
|
||
- BusyBox 环境
|
||
|
||
很多看起来"奇怪"的实现，其实都来自于**踩坑**。
|
||
|
||
不是设计出来的，而是试出来的。
|
||
|
||
### 存储换内存，在嵌入式平台上不是交易，是生存策略
|
||
|
||
镜像可以大几十 MB，但内存必须省。
|
||
|
||
因为内存卡便宜，内存颗粒贵。
|
||
|
||
对于 RK3506（128/256MB 版本共存）或全志 H3（256/512MB 并存）这类平台——
|
||
|
||
牺牲一点存储空间（镜像大了几十 MB），换来 50MB 以内的内存占用，这笔账怎么算都不亏。
|
||
|
||
---
|
||
|
||
## 关于版本
|
||
|
||
项目采用 **Preview / LTS** 双线开发模式：
|
||
|
||
- **Preview**：用于验证新的设计与实现（test 分支）
|
||
- **LTS**：保持稳定，并持续滚动维护（main 分支）
|
||
|
||
某些修复不会等待下一个大版本。
|
||
|
||
因为对于基础设施而言，**稳定比版本号更重要**。
|
||
|
||
---
|
||
|
||
## What This Project Is Not
|
||
|
||
这个项目：
|
||
|
||
- 不追求成为功能最多的 FRP 管理平台
|
||
- 不追求重新定义 FRP
|
||
- 不追求构建自己的生态
|
||
- 不追求让用户每天打开它
|
||
|
||
它只是希望：
|
||
|
||
**把复杂留给软件，把简单留给用户。**
|
||
|
||
---
|
||
|
||
## 常见问题
|
||
|
||
**Q：如果 frpc-console 进程挂了，frpc 本身会受影响吗？**
|
||
|
||
不会。这就是"阴阳模式"的意义。详见上文。
|
||
|
||
**Q：如何修改管理员密码？**
|
||
|
||
登录后，在「全局配置」页面顶部找到「账户管理」区域，输入当前密码和新密码即可。
|
||
|
||
**Q：如何导入现有的 frpc.toml？**
|
||
|
||
在「隧道列表」页面点击「导入 TOML」，选择你的 frpc.toml 文件即可。
|
||
|
||
**Q：frpc 启动失败怎么办？**
|
||
|
||
如果是首次启动，console 会自动生成一份符合官方规范的 `frpc.toml` 配置文件，通常不需要额外操作。
|
||
|
||
如果使用中遇到启动失败：
|
||
1. 在「全局配置」页面重新配置服务端参数，或导入已有的 `frpc.toml`
|
||
2. 查看 `frpc.log` 日志文件定位具体报错原因
|
||
|
||
日志文件位置：与二进制同级目录下的 `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 |
|
||
|
||
---
|
||
|
||
## 最后
|
||
|
||
如果有一天，你已经忘记 frpc-console 安装在哪里，也忘记它上一次更新是什么时候。
|
||
|
||
但是：
|
||
|
||
- FRP 依然稳定运行
|
||
- 偶尔需要修改配置
|
||
- 打开浏览器
|
||
- 两分钟完成
|
||
- 关闭
|
||
- 继续忘记它
|
||
|
||
那么，它已经完成了自己的使命。
|
||
|
||
---
|
||
|
||
## 📝 更新日志
|
||
|
||
#### 相关更新日志请查看[update-logs.md](./update-logs.md)
|
||
|
||
---
|
||
|
||
## 📄 许可证
|
||
|
||
MIT License © 2026 lxh2875931338（XHLiang0）
|
||
|
||
---
|
||
|
||
## 🙏 相关项目援引
|
||
|
||
### FRP 生态互补工具
|
||
|
||
· [MoonProxy](https://github.com/MoonProxyHQ/moonproxy-desktop) —— 基于 Tauri v2 + Vue 3 + Rust 构建的跨平台 FRP 桌面客户端（frpc GUI），面向 macOS 与 Windows，让内网穿透开箱即用，MIT协议开源。
|
||
|
||
### 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 框架
|