305 lines
8.6 KiB
Markdown
305 lines
8.6 KiB
Markdown
# 工程设计哲学
|
||
|
||
> *“Every line of code is a decision. Every document is an explanation of that decision.”*
|
||
>
|
||
> *（每一行代码都是一次设计决策，而每一份文档，都是对这次决策的解释。）*
|
||
|
||
> *“Infrastructure software should disappear after deployment.”*
|
||
>
|
||
> *（基础设施软件，在部署完成以后，就应该消失。）*
|
||
|
||
很多工具追求功能。
|
||
|
||
很多工具追求界面。
|
||
|
||
很多工具追求自动化。
|
||
|
||
**但frpc-console 从来没有试图成为功能最多的 FRP 管理工具。**
|
||
|
||
**它真正想解决的问题，是让一套 FRP 基础设施，在部署完成之后，能够稳定运行很多年，而几乎不需要再次打扰使用者。**
|
||
|
||
如果一个工具每天提醒你更新，每天提醒你配置，每天提醒你维护——那么它已经失败了。
|
||
|
||
部署，只发生一次。
|
||
|
||
运行，却持续很多年。
|
||
|
||
所以整个 frpc-console 都围绕这一件事情设计：
|
||
|
||
**安装。配置。运行。然后——忘记它。**
|
||
|
||
---
|
||
|
||
## 为什么会有这个项目？
|
||
|
||
最初，这只是一个给自己 Homelab 用的小工具。
|
||
|
||
我需要一套简单、可靠的方式管理本地运行的 frpc。
|
||
|
||
后来，在不断使用、不断重构的过程中，我意识到：
|
||
|
||
真正的问题，从来不是"有没有一个管理页面"。
|
||
|
||
而是：
|
||
|
||
**如果 FRP 是一项长期运行的基础设施，它应该长什么样？**
|
||
|
||
于是，这个项目开始慢慢偏离最初的方向。
|
||
|
||
它不再只是一个 Web 面板，而是开始关注：
|
||
|
||
- 生命周期管理
|
||
- 长期维护
|
||
- 多种部署方式
|
||
- 极简运行环境
|
||
- 用户真实的使用场景
|
||
|
||
直到今天。
|
||
|
||
---
|
||
|
||
## 核心问题
|
||
|
||
**一个长期运行的基础设施工具，应该是什么样？**
|
||
|
||
这个问题的答案，驱动了 frpc-console 的所有设计。
|
||
|
||
它不是一个功能列表，而是一套判断标准：
|
||
|
||
- 功能应该增加，还是减少？
|
||
- 部署应该复杂，还是简单？
|
||
- 更新应该频繁，还是稳定？
|
||
- 工具应该显眼，还是隐身？
|
||
|
||
每个问题的答案，都指向同一个方向：
|
||
|
||
**降低长期维护的成本。**
|
||
|
||
---
|
||
|
||
## 设计目标
|
||
|
||
frpc-console 希望成为这样一种工具：
|
||
|
||
**安装。配置。运行。然后，忘记它。**
|
||
|
||
真正优秀的基础设施，不应该每天提醒用户自己的存在。
|
||
|
||
它应该像交换机、路由器、UPS 一样——平时不会想到它，但需要的时候，它一直在那里。
|
||
|
||
---
|
||
|
||
## 设计哲学
|
||
|
||
### 工具应该降低复杂度，而不是增加复杂度
|
||
|
||
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 以内的内存占用，这笔账怎么算都不亏。
|
||
|
||
---
|
||
|
||
## 稳定性与可观测性
|
||
|
||
"安装、配置、运行，然后忘记它"。
|
||
|
||
但忘记，不等于失控。
|
||
|
||
frpc-console 在设计上始终保持一个原则：
|
||
|
||
**工具自身的开销，不应该成为需要被关注的对象。**
|
||
|
||
所以：
|
||
|
||
- 主进程在 idle 状态下 CPU 占用接近 0%
|
||
- 内存占用控制在 20MB 以内
|
||
- 没有额外的后台守护进程
|
||
- 没有定期轮询的健康检查
|
||
- 不会主动写入日志文件，除非你明确开启
|
||
|
||
在真实设备上，frpc 和 frpc-console 同时运行时，两者加起来不到 30MB。
|
||
|
||
这意味着，它不会成为你需要"照顾"的对象。
|
||
|
||
---
|
||
|
||
## 关键设计决策
|
||
|
||
### 阴阳模式：面板可以挂，隧道不能停
|
||
|
||
这是 frpc-console 与同类项目最核心的区别。
|
||
|
||
**大多数管理工具走的是"阳阴模式"：**
|
||
面板是大脑，业务是肢体。大脑一旦停止工作，肢体也就瘫痪了。
|
||
|
||
**frpc-console 走的是"阴阳模式"：**
|
||
业务是根基，面板是工具。
|
||
|
||
- **阴**：看不见的业务流（frpc 进程、TOML 配置文件）
|
||
- **阳**：看得见的管理面板（Web 界面、API 服务）
|
||
|
||
二进制部署时，frpc-console 通过 `Setsid` 为 frpc 创建独立会话，使其完全脱离父进程的生命周期控制。
|
||
|
||
即使 console 退出，frpc 也会被 init 进程（PID 1）接管，继续稳定运行。
|
||
|
||
Docker 部署时，容器使用 `--restart=always`，console 退出时 Docker 自动重启并重新拉起 frpc。
|
||
|
||
两种部署方式的本质一致：
|
||
|
||
**面板是"阳"，服务于"阴"；"阴"不依赖"阳"而存在。**
|
||
|
||
> **管理面板可以丢，业务功能打死不能停。**
|
||
|
||
### 为什么叫 Console，而不是 Manager？
|
||
|
||
这个命名不是随意选的。
|
||
|
||
- **Manager** 暗示"管理权"，暗示它是一个控制中心，是大脑。
|
||
- **Console** 暗示"入口"，暗示它是一个操作界面，是工具。
|
||
|
||
这个区别，直接体现了项目的设计立场：
|
||
|
||
**frpc-console 不接管 FRP，不成为 FRP 的依赖。它只是一个入口，让你在需要的时候，通过它来操作 FRP。**
|
||
|
||
用完之后，关闭浏览器，FRP 还在跑。
|
||
|
||
这就是 Console 和 Manager 的区别。
|
||
|
||
### 为什么没有 CI/CD？
|
||
|
||
这个项目没有复杂的 CI/CD 发布流程。
|
||
|
||
不是做不到，而是选择不做。
|
||
|
||
因为：
|
||
|
||
- CI/CD 在云端跑，部署在真实环境跑。两者之间隔着一个"信任"的黑洞。
|
||
- 如果发布流程和用户安装流程是两套不同的路径，维护者永远无法保证用户侧的真实体验。
|
||
- 每一次部署，都应该在真实环境中被验证。
|
||
|
||
所以，frpc-console 的部署脚本本身就是发布流水线：
|
||
|
||
- 拉取代码 → 构建镜像 → 启动容器 → 写入版本 → 检查进程
|
||
- 支持 `--dry-run` 预览、`--check` 环境检测
|
||
- 降级前自动备份数据库
|
||
- 保留最近 3 个镜像，便于回滚
|
||
|
||
开发过程中使用的更新链路，就是最终用户使用的更新链路。
|
||
|
||
没有特权通道，没有隐藏开关。
|
||
|
||
你用的，就是我用的。
|
||
|
||
因此，每一次更新，实际上都在验证整个部署流程。
|
||
|
||
### 为什么支持 ARMHF？
|
||
|
||
因为很多时候，真正需要这种工具的，并不是性能很强的服务器。
|
||
|
||
而是一块全志 H3、RK3506，或者老旧 ARM 开发板——放在弱电箱里的边缘节点。
|
||
|
||
它们可能没有 Docker，没有 systemd，甚至只有：
|
||
|
||
- Kernel
|
||
- BusyBox
|
||
- init
|
||
|
||
但它们依然承担着网络基础设施的工作。
|
||
|
||
对于这些设备来说，图形化管理反而比高性能服务器更重要。
|
||
|
||
### 为什么采用 Preview / LTS 双线版本？
|
||
|
||
- **Preview**：用于验证新的设计与实现（test 分支）
|
||
- **LTS**：保持稳定，并持续滚动维护（main 分支）
|
||
|
||
某些修复不会等待下一个大版本。
|
||
|
||
因为对于基础设施而言，**稳定比版本号更重要**。
|
||
|
||
---
|
||
|
||
## 这个项目不是什么
|
||
|
||
这个项目：
|
||
|
||
- 不追求成为功能最多的 FRP 管理平台
|
||
- 不追求重新定义 FRP
|
||
- 不追求构建自己的生态
|
||
- 不追求让用户每天打开它
|
||
|
||
它只是希望：
|
||
|
||
**把复杂留给软件，把简单留给用户。**
|
||
|
||
---
|
||
|
||
## 最后
|
||
|
||
如果有一天，你已经忘记 frpc-console 安装在哪里，也忘记它上一次更新是什么时候。
|
||
|
||
但是：
|
||
|
||
- FRP 依然稳定运行
|
||
- 偶尔需要修改配置
|
||
- 打开浏览器
|
||
- 两分钟完成
|
||
- 关闭
|
||
- 继续忘记它
|
||
|
||
那么，它已经完成了自己的使命。
|
||
|
||
---
|
||
|
||
*这份文档会持续更新。因为 frpc-console 的设计，本身就是一个不断演化的过程。每一次真实部署中遇到的新问题，都可能成为下一版设计哲学的注脚。* |