frpc-console/readme.md

frpc-console

A lightweight console for managing FRP, designed for real-world deployment.

---

frpc-console 并不是另一个 FRP WebUI。

它更像是一个生命周期管理工具。

它不会重新定义 FRP，也不会试图接管 FRP。

它只是希望：

让 FRP 更容易部署、更容易维护，也更容易被忘记。

---

为什么会有这个项目？

最初，这只是一个给自己 Homelab 用的小工具。

我需要一套简单、可靠的方式管理本地运行的 frpc。

后来，在不断使用、不断重构的过程中，我意识到：

真正的问题，从来不是"有没有一个管理页面"。

而是：

如果 FRP 是一项长期运行的基础设施，它应该长什么样？

于是，这个项目开始慢慢偏离最初的方向。

它不再只是一个 Web 面板，而是开始关注：

• 生命周期管理
• 长期维护
• 多种部署方式
• 极简运行环境
• 用户真实的使用场景

直到今天。

---

设计目标

frpc-console 希望成为这样一种工具：

安装。配置。运行。然后，忘记它。

真正优秀的基础设施，不应该每天提醒用户自己的存在。

它应该像交换机、路由器、UPS 一样——平时不会想到它，但需要的时候，它一直在那里。

---

稳定性与可观测性

"安装、配置、运行，然后忘记它"。

但请记住：忘记，不等于失控。

frpc-console 在设计上始终保持一个原则：

工具自身的开销，不应该成为需要被关注的对象。

所以：

• 主进程在 idle 状态下 CPU 占用接近 0%
• 内存占用控制在 20MB 以内
• 没有额外的后台守护进程
• 没有定期轮询的健康检查
• 不会主动写入日志文件，除非你明确开启

下图是在真实设备上同时运行 frpc 和 frpc-console 的资源占用情况：

你可以看到：

• frpc：CPU 0.45%，内存 13.25MB
• frpc-console：CPU 0.00%，内存 15.64MB

两者加起来不到 30MB。

这意味着：

你可以忘记它。

但如果有一天，你想知道它是否还在正常工作——

打开浏览器，看一眼。

然后，继续忘记它。

如果它真的出了什么问题，它的表现也很简单：

要么进程还在，要么进程不在了。

没有中间状态。

没有僵尸进程。

没有需要手动清理的残留文件。

因为对于基础设施来说：

确定性，比灵活性更重要。

---

界面与核心能力

frpc-console 提供的是一个图形化的生命周期管理工具，而不是一个功能堆砌的控制台。

它只做这几件事：

• 首次启动引导：Web 端完成管理员注册，无需 CLI 交互
• 隧道全生命周期管理：增删改查 + 一键启用/禁用
• 导入/导出 TOML：无缝迁移现有 frpc 配置
• 配置热加载：修改即生效，无需重启 frpc
• 配置备份与恢复
• 进程管理
• 数据库维护工具

功能并不追求数量，而是追求：

真正有用。

界面采用深色磨砂玻璃视觉风格，设计目标是：

当你需要它的时候，它清晰易用；当你不需要它的时候，它不打扰你。

---

快速开始

一键部署（推荐，Linux）

curl -sSL https://git.whitetop.xyz/lxh2875931338/frpc-console/raw/main/run-deploy.sh | sudo bash

脚本会引导你选择 LTS 或 Preview 通道，然后自动完成全部部署。

Docker 手动部署

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 下载对应平台的二进制文件，直接运行即可。

首次访问 http://localhost:9300 注册管理员账户，然后导入你的 frpc.toml 开始使用。

源码编译

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 依然稳定运行
• 偶尔需要修改配置
• 打开浏览器
• 两分钟完成
• 关闭
• 继续忘记它

那么，它已经完成了自己的使命。

---

许可证

MIT License © 2026 lxh2875931338（XHLiang0）

---

致谢

• fatedier/frp —— 强大的内网穿透工具
• gin-gonic/gin —— 高性能 Go Web 框架
• vuejs/vue —— 渐进式 JavaScript 框架

---

Thanks · Star