From 05db453d70432566ec53abf30b6f0523dea0a6fb Mon Sep 17 00:00:00 2001 From: lxh2875931338 Date: Tue, 4 Aug 2026 21:20:39 +0800 Subject: [PATCH] =?UTF-8?q?=E6=8E=A8=E9=80=81readme?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- readme.md | 449 +----------------------------------------------------- 1 file changed, 7 insertions(+), 442 deletions(-) diff --git a/readme.md b/readme.md index 308a62f..592dabb 100644 --- a/readme.md +++ b/readme.md @@ -28,13 +28,13 @@ A lightweight lifecycle console built from real-world engineering practice. | [⚙ 设计决策](./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/engineering-philosophy.md) ** --- @@ -45,9 +45,10 @@ A lightweight lifecycle console built from real-world engineering practice. - [二进制安装指南](./Docs/INSTALL_BINARY.md) - [Docker 安装指南](./Docs/INSTALL_DOCKER.md) -首次访问请注册管理员账户 +首次访问： -导入你的 `frpc.toml` +1. 注册管理员账户。 +2. 导入你的 `frpc.toml`。 然后—— @@ -55,440 +56,4 @@ A lightweight lifecycle console built from real-world engineering practice. --- -**MIT License © 2026 lxh2875931338（XHLiang0）** · [GitHub](链接) · [致谢](链接) - - - - - - - -# frpc-console - -**A lightweight console for managing FRP, designed for real-world deployment.** - -[![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 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 生态同类工具（暂无互引） -
- -## 致谢 - -- [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 框架 +**MIT License © 2026 lxh2875931338（XHLiang0）** · [GitHub](https://github.com/XHLiang0) · [致谢](./Docs/acknowledgment.md)