From 4ff8c19196363cbb4a032c5ef1564508f7b9d108 Mon Sep 17 00:00:00 2001 From: lxh2875931338 Date: Tue, 4 Aug 2026 12:36:43 +0800 Subject: [PATCH] =?UTF-8?q?readme=E9=87=8D=E5=86=99?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- readme.md | 427 ++++++++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 353 insertions(+), 74 deletions(-) diff --git a/readme.md b/readme.md index ecb8c9a..0e69512 100644 --- a/readme.md +++ b/readme.md @@ -1,143 +1,422 @@ -frpc-console +

+ frpc-console +

-让 FRP 回归工具本身，而不是变成一个需要持续维护的系统。 +# frpc-console -📌 定位 +**A lightweight console for managing FRP, designed for real-world deployment.** -frpc-console 并不是一个“管理平台”。 +[![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) -它更像一个控制台——部署一次，配置一次，然后尽可能忘记它。 +--- -它不会接管 FRP 的运行方式，不会改变 FRP 的行为逻辑，也不会在系统中增加一个需要持续关注的组件。 +frpc-console 并不是另一个 FRP WebUI。 -它只是在 FRP 原本的工作方式之上，提供一个更自然、更符合直觉的入口： +它更像是一个生命周期管理工具。 -· 不需要记忆命令行参数 -· 不需要手动编辑 TOML -· 不需要在配置变更后手动重启 +它不会重新定义 FRP，也不会试图接管 FRP。 -控制应该存在，但不应该成为负担。 +它只是希望： -🎨 设计哲学 +**让 FRP 更容易部署、更容易维护，也更容易被忘记。** -frpc-console 遵循几条简单的原则： +--- -1. 工具服务于用户，而不是要求用户适应工具。 +## 为什么会有这个项目？ -功能的存在是为了解决问题，而不是为了证明工具的能力。一个功能如果带来了新的维护成本，那它就值得被重新审视。 +最初，这只是一个给自己 Homelab 用的小工具。 -2. 能自动完成的事情，不应该要求用户手动操作。 +我需要一套简单、可靠的方式管理本地运行的 frpc。 -配置迁移、Schema 升级、进程保活——这些应该由工具自己处理，而不是交给用户去操心。 +后来，在不断使用、不断重构的过程中，我意识到： -3. 功能越多，不代表体验越好。 +真正的问题，从来不是"有没有一个管理页面"。 -每增加一个功能，都是在增加用户的认知负担。frpc-console 只在必要的时候增加功能，并且确保新增功能不会制造新的复杂性。 +而是： -4. 当用户逐渐忘记 frpc-console 的存在时，它就是成功的。 +**如果 FRP 是一项长期运行的基础设施，它应该长什么样？** -一个工具最好的状态，是用户不需要记住它的存在。它应该在自己该在的地方待着，在需要的时候出现，在不需要的时候不打扰。 +于是，这个项目开始慢慢偏离最初的方向。 -✨ 为什么叫 Console，而不是 Manager？ +它不再只是一个 Web 面板，而是开始关注： -Manager 暗示的是：有一个“管理者”和一个“被管理者”的层级关系。它会让人天然认为这个工具是系统的一部分，是需要一直在线、持续监控的核心组件。 +- 生命周期管理 +- 长期维护 +- 多种部署方式 +- 极简运行环境 +- 用户真实的使用场景 -但 frpc-console 不是这样的角色。 +直到今天。 -Console 更准确地描述了它的定位： +--- -· 一个控制台，用户需要的时候走上去看一眼，调一下参数，然后离开 -· 它不需要被持续感知 -· 它的价值在于“当你需要的时候，它就在那里”，而不是“它一直在那里运转” +## 设计目标 -它只是一个入口，而不是一个中心。 +frpc-console 希望成为这样一种工具： -🖥️ UI 设计 +**安装。配置。运行。然后，忘记它。** -UI 没有采用功能繁重的复杂框架，而是选择了磨砂玻璃风格的轻量设计。 +真正优秀的基础设施，不应该每天提醒用户自己的存在。 -它的目标不是“看起来花哨”，而是“看起来舒服”——让界面在视觉上不喧宾夺主，让用户能够专注于需要完成的操作，而不是被界面本身分散注意力。 +它应该像交换机、路由器、UPS 一样——平时不会想到它，但需要的时候，它一直在那里。 -🚀 核心能力 +--- -首次启动引导 +## 稳定性与可观测性 -浏览器完成管理员注册，无需命令行交互，开箱即用。 +"安装、配置、运行，然后忘记它"。 -隧道全生命周期管理 +但请记住：**忘记，不等于失控。** -增删改查 + 一键启用/禁用。所有操作可视化，不需要手动编辑 TOML。 +frpc-console 在设计上始终保持一个原则： -TOML 导入/导出 +**工具自身的开销，不应该成为需要被关注的对象。** -无缝迁移现有的 frpc 配置。你原来怎么配置的，现在依然可以用同样的方式配置。 +所以： -配置热加载 +- 主进程在 idle 状态下 CPU 占用接近 0% +- 内存占用控制在 20MB 以内 +- 没有额外的后台守护进程 +- 没有定期轮询的健康检查 +- 不会主动写入日志文件，除非你明确开启 -修改配置后自动生效，不需要手动重启 frpc。 +下图是在真实设备上同时运行 frpc 和 frpc-console 的资源占用情况： -运行日志面板 +![resource-usage]() -WebUI 内实时查看 frpc 日志，不需要 SSH 进入服务器。 +你可以看到： -Ping 延迟检测 +- frpc：CPU 0.45%，内存 13.25MB +- frpc-console：CPU 0.00%，内存 15.64MB -顶部导航实时显示 frpc 到 frps 的延迟，一目了然。 +两者加起来不到 30MB。 -多平台支持 +这意味着： -Windows / Linux / ARM 全平台兼容，单二进制交付。 +**你可以忘记它。** -Docker 容器化 +但如果有一天，你想知道它是否还在正常工作—— -提供 Docker 镜像，一键部署，数据持久化。 +打开浏览器，看一眼。 -🧠 设计原则 +然后，继续忘记它。 -frpc-console 始终遵循几条底层原则： +如果它真的出了什么问题，它的表现也很简单： -· 工具服务于用户，而不是要求用户适应工具。 -· 功能越多，不代表体验越好。 -· 能自动完成的事情，不应该要求用户手动操作。 -· 当用户逐渐忘记 frpc-console 的存在时，它就是成功的。 +要么进程还在，要么进程不在了。 -📦 快速开始 +没有中间状态。 -Docker 部署（推荐） +没有僵尸进程。 + +没有需要手动清理的残留文件。 + +因为对于基础设施来说： + +**确定性，比灵活性更重要。** + +--- + +## 界面与核心能力 + +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 通道，然后自动完成全部部署。 -INSTALL_BINARY.md +### Docker 手动部署 -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 +``` -INSTALL_DOCKER.md +### 二进制部署 -📄 License +适用于 Linux / Windows，单文件运行，无需 Docker。 -MIT License © 2026 lxh2875931338 +从 [Releases](https://git.whitetop.xyz/lxh2875931338/frpc-console/releases) 下载对应平台的二进制文件，直接运行即可。 +首次访问 `http://localhost:9300` 注册管理员账户，然后导入你的 `frpc.toml` 开始使用。 -## 🙏 相关项目援引 +### 源码编译 -### FRP 生态互补工具 - -· [MoonProxy](https://github.com/MoonProxyHQ/moonproxy-desktop) —— 基于 Tauri v2 + Vue 3 + Rust 构建的跨平台 FRP 桌面客户端（frpc GUI），面向 macOS 与 Windows，让内网穿透开箱即用，MIT协议开源。 - -### FRP 生态同类工具（暂无互引） -
+```bash +git clone https://git.whitetop.xyz/lxh2875931338/frpc-console.git +cd frpc-console +go mod tidy +go build -o frpc-console . +./frpc-console +``` --- -🙏 相关项目 +## 部署哲学： -· MoonProxy —— 跨平台 FRP 桌面客户端 -· fatedier/frp —— 内网穿透工具的核心引擎 +### 没有 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。 + +数据目录通过卷挂载持久化，配置不丢失。 + +两种部署方式的本质一致： + +**面板是"阳"，服务于"阴"；"阴"不依赖"阳"而存在。** + +> **管理面板可以丢，业务功能打死不能停。** --- -如果这个项目对你有用，欢迎给它点个 Star ⭐ \ No newline at end of file +## 为什么支持 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](https://github.com/fatedier/frp) —— 强大的内网穿透工具 +- [gin-gonic/gin](https://github.com/gin-gonic/gin) —— 高性能 Go Web 框架 +- [vuejs/vue](https://github.com/vuejs/vue) —— 渐进式 JavaScript 框架 + +--- + +**Thanks · Star** \ No newline at end of file