# 工程设计哲学

> *“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 的设计，本身就是一个不断演化的过程。每一次真实部署中遇到的新问题，都可能成为下一版设计哲学的注脚。*