Merge remote-tracking branch 'origin/test'
This commit is contained in:
@@ -0,0 +1,65 @@
|
||||
# 致谢与互引
|
||||
|
||||
> *“这个项目之所以存在，是因为有一群更早的存在，以及一个更大的生态。”*
|
||||
|
||||
---
|
||||
|
||||
## 核心依赖
|
||||
|
||||
frpc-console 站在以下项目的肩膀上：
|
||||
|
||||
- **[FRP](https://github.com/fatedier/frp)** —— 这个项目存在的理由。一个稳定、高效的内网穿透工具，是 frpc-console 管理的对象。
|
||||
- **[SQLite](https://www.sqlite.org/)** —— 嵌入式数据库的典范。它让 frpc-console 不需要额外部署数据库服务，符合“降低维护成本”的总体目标。
|
||||
- **[Go](https://go.dev/)** —— 编译为单一二进制，跨平台，低内存占用。没有 Go，就没有 frpc-console 目前的部署体验。
|
||||
|
||||
---
|
||||
|
||||
## 框架与库
|
||||
|
||||
- **[Gin](https://github.com/gin-gonic/gin)** —— 高性能 Go Web 框架，为 API Server 提供基础。
|
||||
- **[Vue 3](https://github.com/vuejs/vue)** —— 渐进式 JavaScript 框架，承载了 Web UI 的交互体验。
|
||||
|
||||
---
|
||||
|
||||
## 生态互引
|
||||
|
||||
### FRP 生态互补工具
|
||||
|
||||
- **[MoonProxy](https://github.com/MoonProxyHQ/moonproxy-desktop)** —— 基于 Tauri v2 + Vue 3 + Rust 构建的跨平台 FRP 桌面客户端（frpc GUI），面向 macOS 与 Windows，让内网穿透开箱即用。MIT 协议开源。
|
||||
|
||||
### FRP 生态同类工具
|
||||
|
||||
*暂无互引。如果您知道有同类项目愿意建立互引关系，欢迎通过 Issue 或 PR 联系我们。*
|
||||
|
||||
---
|
||||
|
||||
## 设计启发
|
||||
|
||||
这个项目的许多设计决策，受到以下内容的影响：
|
||||
|
||||
- **《The Art of Unix Programming》** —— “Do one thing and do it well.”
|
||||
- **SQLite 的设计哲学** —— 长期稳定比新功能更重要。
|
||||
- **OpenBSD 的开发理念** —— 默认安全，拒绝默认开放。
|
||||
- **Tailscale 的部署体验** —— 安装一次，忘记它。
|
||||
|
||||
---
|
||||
|
||||
## 致谢
|
||||
|
||||
感谢所有在真实环境中运行 frpc-console 的用户。你们的每一次部署，都是对这套工程方法的验证。
|
||||
|
||||
[lxh2875931338（XHLiang0）](https://git.whitetop.xyz/lxh2875931338) —— 这是项目的开发者，同时也是项目真正的第一个用户。
|
||||
|
||||
---
|
||||
|
||||
## 如何贡献
|
||||
|
||||
如果你在使用 frpc-console 的过程中有新的发现、改进建议，或者想参与互引，欢迎：
|
||||
|
||||
- 提交 [Issue](https://git.whitetop.xyz/lxh2875931338/frpc-console/issues)
|
||||
- 发起 Pull Request（请针对 `test` 分支）
|
||||
- 在相关社区分享你的部署经验
|
||||
|
||||
---
|
||||
|
||||
*frpc-console 的成长，离不开整个开源生态的滋养。感谢每一位为之贡献的人。*
|
||||
@@ -0,0 +1,287 @@
|
||||
# 架构设计
|
||||
|
||||
> *“代码定义了它如何工作，架构定义了它如何活着。”*
|
||||
|
||||
---
|
||||
|
||||
## 架构总览
|
||||
|
||||
frpc-console 是一个**轻量级生命周期管理工具**，它的架构设计围绕着三个核心目标：
|
||||
|
||||
1. **低资源占用** — 在边缘设备上也能运行
|
||||
2. **高可靠性** — 面板可挂，业务不能停
|
||||
3. **零依赖部署** — 单一二进制，开箱即用
|
||||
|
||||
|
||||
### 整体架构图
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph User["用户侧"]
|
||||
Browser["浏览器"]
|
||||
CLI["命令行"]
|
||||
end
|
||||
|
||||
subgraph Console["frpc-console"]
|
||||
WebUI["Web UI<br/>(Vue 3 + 深色磨砂玻璃)"]
|
||||
APIServer["API Server<br/>(Gin)"]
|
||||
Lifecycle["生命周期管理器"]
|
||||
ConfigMgr["配置管理器<br/>(TOML 解析/生成)"]
|
||||
ProcessMgr["进程管理器<br/>(SetSid / PID 1 接管)"]
|
||||
DB["SQLite<br/>(用户/隧道/配置)"]
|
||||
Static["静态资源<br/>(内嵌)"]
|
||||
end
|
||||
|
||||
subgraph FRP["被管理对象"]
|
||||
FRPC["frpc 进程"]
|
||||
TOML["frpc.toml"]
|
||||
end
|
||||
|
||||
Browser --> WebUI
|
||||
CLI --> APIServer
|
||||
WebUI --> APIServer
|
||||
APIServer --> DB
|
||||
APIServer --> ConfigMgr
|
||||
ConfigMgr --> TOML
|
||||
APIServer --> Lifecycle
|
||||
Lifecycle --> ProcessMgr
|
||||
ProcessMgr --> FRPC
|
||||
FRPC --> TOML
|
||||
Static -.-> WebUI
|
||||
```
|
||||
|
||||
> **说明：** `Static`（前端静态资源）在编译时通过 `embed` 直接打包进二进制，运行时无需额外加载。因此图中以虚线表示其与 WebUI 的关联，且不占用独立部署单元。
|
||||
|
||||
---
|
||||
|
||||
## 部署模型
|
||||
|
||||
frpc-console 支持两种部署模型，架构核心逻辑完全一致，只是运行环境不同。
|
||||
|
||||
### 二进制部署模型
|
||||
|
||||
```
|
||||
┌──────────────────────────────────────────┐
|
||||
│ 操作系统 (Linux/Windows) │
|
||||
│ │
|
||||
│ ┌────────────────────────────────────┐ │
|
||||
│ │ frpc-console │ │
|
||||
│ │ ┌──────────────────────────────┐ │ │
|
||||
│ │ │ Web UI │ API Server │ │ │
|
||||
│ │ ├──────────────────────────────┤ │ │
|
||||
│ │ │ 生命周期管理 / 配置管理 │ │ │
|
||||
│ │ └──────────┬───────────────────┘ │ │
|
||||
│ └─────────────┼──────────────────────┘ │
|
||||
│ │ SetSid + 独立会话 │
|
||||
│ ▼ │
|
||||
│ ┌────────────────────────────────────┐ │
|
||||
│ │ frpc 子进程 │ │
|
||||
│ │ (被 PID 1 接管，独立生命周期) │ │
|
||||
│ └────────────────────────────────────┘ │
|
||||
│ │
|
||||
│ ┌────────────────────────────────────┐ │
|
||||
│ │ 数据目录: /opt/frpc-console/data │ │
|
||||
│ │ ├── frpc-console.db │ │
|
||||
│ │ ├── frpc.toml │ │
|
||||
│ │ ├── frpc (二进制) │ │
|
||||
│ │ ├── frpc.pid │ │
|
||||
│ │ └── version.ini │ │
|
||||
│ └────────────────────────────────────┘ │
|
||||
└──────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
**关键机制：**
|
||||
|
||||
- frpc-console 启动时，通过 `SetSid` 为 frpc 创建**独立会话**
|
||||
- frpc 进程完全脱离父进程的生命周期控制
|
||||
- 即使 console 崩溃或被 kill，frpc 会被 init（PID 1）接管，继续运行
|
||||
|
||||
### Docker 部署模型
|
||||
|
||||
```
|
||||
┌──────────────────────────────────────────┐
|
||||
│ Docker Host │
|
||||
│ │
|
||||
│ ┌────────────────────────────────────┐ │
|
||||
│ │ Container: frpc-console │ │
|
||||
│ │ ┌──────────────────────────────┐ │ │
|
||||
│ │ │ Web UI │ API Server │ │ │
|
||||
│ │ ├──────────────────────────────┤ │ │
|
||||
│ │ │ 生命周期管理 / 配置管理 │ │ │
|
||||
│ │ └──────────┬───────────────────┘ │ │
|
||||
│ │ │ 启动 frpc │ │
|
||||
│ │ ▼ │ │
|
||||
│ │ ┌──────────────────────────────┐ │ │
|
||||
│ │ │ frpc 子进程 (容器内) │ │ │
|
||||
│ │ └──────────────────────────────┘ │ │
|
||||
│ └──────────────┬─────────────────────┘ │
|
||||
│ │ Volume 挂载 │
|
||||
│ ▼ │
|
||||
│ ┌────────────────────────────────────┐ │
|
||||
│ │ 数据卷: /opt/frpc-console/data │ │
|
||||
│ │ ├── frpc-console.db │ │
|
||||
│ │ ├── frpc.toml │ │
|
||||
│ │ ├── frpc.pid │ │
|
||||
│ │ └── version.ini │ │
|
||||
│ └────────────────────────────────────┘ │
|
||||
│ │
|
||||
│ 重启策略: --restart=always │
|
||||
└──────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
**关键机制：**
|
||||
|
||||
- 容器配置 `--restart=always`，console 退出时 Docker 自动重启
|
||||
- 数据目录通过 Volume 挂载持久化
|
||||
- 容器重启后自动重新拉起 frpc
|
||||
|
||||
---
|
||||
|
||||
## 核心模块
|
||||
|
||||
### 1. Web UI（前端）
|
||||
|
||||
- **框架：** Vue 3
|
||||
- **风格：** 深色磨砂玻璃视觉
|
||||
- **设计原则：** 需要时清晰易用，不需要时不打扰
|
||||
- **构建产物：** 静态资源通过 Go embed 内嵌于二进制
|
||||
|
||||
### 2. API Server
|
||||
|
||||
- **框架：** Gin
|
||||
- **认证：** Session / JWT
|
||||
- **职责：** 提供 RESTful API，处理前端请求
|
||||
|
||||
### 3. 生命周期管理器
|
||||
|
||||
负责 frpc 进程的完整生命周期：
|
||||
|
||||
| 操作 | 行为 |
|
||||
|---|---|
|
||||
| 启动 | 根据当前 frpc.toml 启动 frpc 进程 |
|
||||
| 停止 | 向 frpc 发送终止信号 |
|
||||
| 重启 | 停止 → 重新加载配置 → 启动 |
|
||||
| 状态检查 | 读取 PID 文件，验证进程是否存在 |
|
||||
| 热加载 | 修改配置后自动重启 frpc（无需手动操作） |
|
||||
|
||||
### 4. 配置管理器
|
||||
|
||||
- 解析和生成 TOML 格式的 frp 配置文件
|
||||
- 支持从现有 frpc.toml 导入
|
||||
- 修改配置后自动触发重启
|
||||
|
||||
### 5. 进程管理器
|
||||
|
||||
- 通过 `SetSid` 创建独立会话（Linux）
|
||||
- frpc 二进制内置在部署包中，无需额外下载
|
||||
- 记录 PID 到文件，用于状态检查和进程管理
|
||||
- Windows 版本使用相应的进程管理 API
|
||||
|
||||
### 6. SQLite 数据库
|
||||
|
||||
- **表结构：**
|
||||
- `users` — 管理员账户
|
||||
- `tunnels` — 隧道配置
|
||||
- `configs` — 全局配置
|
||||
- **备份机制：** 部署脚本在降级前自动备份数据库文件
|
||||
- **位置：** `data/frpc-console.db`
|
||||
|
||||
---
|
||||
|
||||
## 关键交互流程
|
||||
|
||||
### 启动流程
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant User
|
||||
participant Console
|
||||
participant FRPC
|
||||
|
||||
User->>Console: 启动 frpc-console
|
||||
Console->>Console: 读取 data/frpc.toml
|
||||
alt 配置文件存在
|
||||
Console->>FRPC: 启动 frpc (SetSid)
|
||||
FRPC-->>Console: PID 写入 frpc.pid
|
||||
Console-->>User: 服务就绪
|
||||
else 配置文件不存在
|
||||
Console-->>User: 等待 WebUI 导入配置
|
||||
User->>Console: WebUI 导入 frpc.toml
|
||||
Console->>FRPC: 启动 frpc
|
||||
end
|
||||
```
|
||||
|
||||
### 配置更新流程
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant User
|
||||
participant WebUI
|
||||
participant API
|
||||
participant ConfigMgr
|
||||
participant FRPC
|
||||
|
||||
User->>WebUI: 修改隧道配置
|
||||
WebUI->>API: PUT /api/tunnels/:id
|
||||
API->>ConfigMgr: 更新配置
|
||||
ConfigMgr->>ConfigMgr: 写入 data/frpc.toml
|
||||
ConfigMgr-->>API: 配置已更新
|
||||
API-->>WebUI: 200 OK
|
||||
API->>FRPC: 重启 frpc (热加载)
|
||||
FRPC-->>API: 启动成功
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 资源边界
|
||||
|
||||
### 运行时资源
|
||||
|
||||
| 资源 | 典型值 | 说明 |
|
||||
|---|---|---|
|
||||
| CPU（idle） | ~0% | 无后台轮询 |
|
||||
| 内存（idle） | < 20MB | 无额外守护进程 |
|
||||
| 存储（二进制） | ~15MB | 静态编译，无依赖 |
|
||||
| 存储（数据） | < 1MB | SQLite + 配置文件 |
|
||||
|
||||
> 真实设备实测数据见 [工程设计哲学 - 稳定性与可观测性](./engineering-philosophy.md#稳定性与可观测性)
|
||||
|
||||
### 文件系统布局
|
||||
|
||||
```
|
||||
/opt/frpc-console/ # 默认部署目录
|
||||
├── data/ # 数据目录（持久化）
|
||||
│ ├── frpc-console.db # SQLite 数据库
|
||||
│ ├── frpc.toml # 当前 frpc 配置
|
||||
│ ├── frpc # FRP 二进制（内置）
|
||||
│ ├── frpc.pid # frpc 进程 PID
|
||||
│ ├── frpc.log # frpc 日志（可选）
|
||||
│ └── version.ini # 当前版本标识
|
||||
├── frpc-console # 主二进制（二进制部署）
|
||||
└── .old_backup_* # 旧版本备份（迁移时生成）
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 架构演进
|
||||
|
||||
当前架构不是一次性设计完成的，而是经历了以下阶段：
|
||||
|
||||
1. **最初**：一个简单的 Web UI，通过命令行调用 frpc
|
||||
2. **发现问题**：SSH 断开后 frpc 也跟着退出 → 引入 SetSid
|
||||
3. **发现问题**：配置文件修改需要手动重启 → 引入热加载
|
||||
4. **发现问题**：ARMHF 设备跑不动 Docker → 引入二进制部署
|
||||
5. **发现问题**：边缘设备内存不足 → 优化运行时内存占用
|
||||
6. **发现问题**：更新时数据丢失 → 引入事务性部署脚本
|
||||
7. **持续演化中**：每次真实部署都可能带来新的架构调整
|
||||
|
||||
---
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [工程设计哲学](./engineering-philosophy.md) — 架构决策背后的设计原则
|
||||
- [设计决策记录](./design-decisions.md) — 每个“为什么”的详细记录
|
||||
- [边缘节点部署](./edge-node.md) — 在受限环境中的架构适配
|
||||
- [更新策略](./update-strategy.md) — 版本管理和升级机制
|
||||
- [部署指南](./INSTALL_DOCKER.md) — Docker 部署详细步骤
|
||||
- [二进制安装指南](./INSTALL_BINARY.md) — 二进制部署详细步骤
|
||||
@@ -0,0 +1,168 @@
|
||||
# 设计决策
|
||||
|
||||
> *“这不是 API 文档，这是设计记录。它回答的不是‘怎么用’，而是‘为什么会变成这样’。”*
|
||||
|
||||
---
|
||||
|
||||
## 关于这份文档
|
||||
|
||||
frpc-console 的许多设计，如果只看最终结果，可能会让人觉得“奇怪”或“不按常理出牌”。
|
||||
|
||||
这份文档记录的就是这些“奇怪”背后的原因。
|
||||
|
||||
每一个决策，都来自真实部署中遇到的问题——而不是预先的设计。
|
||||
|
||||
---
|
||||
|
||||
## 为什么叫 Console，而不是 Manager？
|
||||
|
||||
这个命名不是随意选的。
|
||||
|
||||
| | Manager | Console |
|
||||
|---|---|---|
|
||||
| 暗示 | 管理权、控制中心 | 入口、操作界面 |
|
||||
| 角色 | 大脑 | 工具 |
|
||||
| 依赖关系 | 业务依赖 Manager | Console 依赖业务 |
|
||||
|
||||
**结论：**
|
||||
|
||||
frpc-console 不接管 FRP，不成为 FRP 的依赖。它只是一个入口，让你在需要的时候操作 FRP。
|
||||
|
||||
用完之后，关闭浏览器，FRP 还在跑。
|
||||
|
||||
这就是 Console 和 Manager 的区别。
|
||||
|
||||
---
|
||||
|
||||
## 为什么没有 CI/CD？
|
||||
|
||||
这个项目没有复杂的 CI/CD 发布流程。不是做不到，而是选择不做。
|
||||
|
||||
**原因：**
|
||||
|
||||
- CI/CD 在云端跑，部署在真实环境跑。两者之间隔着一个“信任”的黑洞。
|
||||
- 如果发布流程和用户安装流程是两套不同的路径，维护者永远无法保证用户侧的真实体验。
|
||||
- 每一次部署，都应该在真实环境中被验证。
|
||||
|
||||
**所以：**
|
||||
|
||||
部署脚本就是发布流水线。开发过程中使用的更新链路，就是最终用户使用的更新链路。
|
||||
|
||||
没有特权通道，没有隐藏开关。你用的，就是我用的。
|
||||
|
||||
---
|
||||
|
||||
## 为什么没有 Patch 版本？
|
||||
|
||||
版本号格式：`2.5-LTS-260804-203825`
|
||||
|
||||
详见：[更新策略](./update-strategy.md)
|
||||
|
||||
---
|
||||
|
||||
## 为什么支持 ARMHF？
|
||||
|
||||
详见：[边缘节点部署](./edge-node.md)
|
||||
|
||||
---
|
||||
|
||||
## 为什么采用 Preview / LTS 双线版本？
|
||||
|
||||
详见：[更新策略](./update-strategy.md)
|
||||
|
||||
---
|
||||
|
||||
## 为什么“存储换内存”？
|
||||
|
||||
在边缘设备上，存储和内存的成本结构完全颠倒：
|
||||
|
||||
| | 服务器 | 边缘设备 |
|
||||
|---|---|---|
|
||||
| 存储 | 昂贵（NVMe SSD） | 便宜（SD 卡 / eMMC） |
|
||||
| 内存 | 便宜（可扩展） | 昂贵（不可扩展，BGA 焊接） |
|
||||
|
||||
**结论：**
|
||||
|
||||
镜像大几十 MB，可以接受。内存多占 10MB，不能接受。
|
||||
|
||||
牺牲存储空间，换来 50MB 以内的内存占用——这笔账在边缘设备上怎么算都不亏。
|
||||
|
||||
---
|
||||
|
||||
## 为什么用 SQLite，不用 PostgreSQL / MySQL？
|
||||
|
||||
- 边缘设备跑不动 PostgreSQL
|
||||
- 不需要网络连接
|
||||
- 单文件备份，复制即迁移
|
||||
- 零配置，零维护
|
||||
|
||||
符合“降低维护成本”的总体目标。
|
||||
|
||||
---
|
||||
|
||||
## 为什么使用 Gin 和 Vue，而不是更轻的框架？
|
||||
|
||||
这是一个有意识的选择。
|
||||
|
||||
frpc-console 的 Web 部分需要提供完整的图形化操作界面，不是一个简单的 API 服务。使用成熟的框架，换取开发效率和稳定性。
|
||||
|
||||
**但要注意：**
|
||||
|
||||
框架的选择不影响运行时资源占用。前端资源在首次加载后缓存，后端 Gin 在 idle 状态下几乎没有额外开销。
|
||||
|
||||
---
|
||||
|
||||
## 为什么默认不写日志？
|
||||
|
||||
边缘设备存储有限（SD 卡 / eMMC）。
|
||||
|
||||
默认不写日志，避免存储被写满导致设备不可用。
|
||||
|
||||
用户需要时，可以显式开启日志功能。
|
||||
|
||||
---
|
||||
|
||||
## 为什么 openSUSE 在部署脚本中排第一？
|
||||
|
||||
详见：[工程设计哲学](./engineering-philosophy.md) 中的“用户不是测试员”和“Real World First”原则。
|
||||
|
||||
---
|
||||
|
||||
## 为什么 Docker 和 Binary 都支持？
|
||||
|
||||
因为使用场景不同：
|
||||
|
||||
| 场景 | 推荐方式 |
|
||||
|---|---|
|
||||
| 现代服务器（有 Docker） | Docker |
|
||||
| 边缘设备（无 Docker） | Binary |
|
||||
| 开发者测试 | Docker |
|
||||
| 开发测试（无 Docker）| Binary |
|
||||
| 生产环境（有 Docker） | Docker |
|
||||
| 生产环境（无 Docker） | Binary |
|
||||
|
||||
**核心原则：** 无论运行在哪里，体验应该保持一致。
|
||||
|
||||
---
|
||||
|
||||
## 为什么叫“阴阳模式”？
|
||||
|
||||
详见：[工程设计哲学](./engineering-philosophy.md) 中的“阴阳模式”章节。
|
||||
|
||||
---
|
||||
|
||||
## 这些决策的共同点
|
||||
|
||||
所有设计决策，都指向同一个问题：
|
||||
|
||||
**一个长期运行的基础设施工具，应该是什么样？**
|
||||
|
||||
答案不是“功能最多”，不是“界面最美”，而是：
|
||||
|
||||
**降低长期维护的成本。**
|
||||
|
||||
每一个“为什么”的答案，最终都落在这句话上。
|
||||
|
||||
---
|
||||
|
||||
*这份文档会持续更新。每一次新的设计决策，都会被记录在这里。*
|
||||
@@ -0,0 +1,154 @@
|
||||
# 边缘节点部署
|
||||
|
||||
> *“真正需要管理工具的，往往不是机房里那台 64 核 256GB 的服务器，而是弱电箱里那块连散热片都没有的 ARM 开发板。”*
|
||||
|
||||
---
|
||||
|
||||
## 真实场景
|
||||
|
||||
frpc-console 对边缘节点的支持，不是来自“市场调研”。
|
||||
|
||||
它来自以下设备：
|
||||
|
||||
- **全志 H3**（256MB / 512MB 内存），运行社区的精简版 ARMbian 或官方剪枝版 Debian，放在弱电箱里跑 frp 穿透
|
||||
- **RK3506**（128MB / 256MB 版本共存），没有 Docker，甚至没有 systemd
|
||||
- 老旧 ARM 开发板（ARMv7l / ARM-HF），原本可能是一块电视盒子，刷上 ARMbian 之后被重新利用
|
||||
|
||||
这些设备的共同特征：
|
||||
|
||||
- 存储介质：SD 卡 / eMMC（便宜，容量大，但读写速度不敏感）
|
||||
- 内存：128MB ~ 512MB（**没有任何拓展条件**）
|
||||
- 系统环境：极简化，不常用的工具基本都被剪枝，极端情况下很可能只有 Kernel + BusyBox + init
|
||||
- 网络环境：长期在线，但带宽有限
|
||||
- 物理位置：没有理由长期触及（弱电箱、吊顶、室外机柜）
|
||||
|
||||
它们承担的工作却并不边缘：
|
||||
|
||||
- 内网穿透
|
||||
- 远程维护通道
|
||||
- IoT 设备接入
|
||||
- 边缘计算节点
|
||||
|
||||
---
|
||||
|
||||
## 边缘环境特征
|
||||
|
||||
### 存储 vs 内存：成本结构的倒挂
|
||||
|
||||
在边缘设备上，存储和内存的成本结构与服务器完全不同：
|
||||
|
||||
| | 服务器 | 边缘设备 |
|
||||
|---|---|---|
|
||||
| 存储 | 昂贵（NVMe SSD） | 便宜（SD 卡 / eMMC） |
|
||||
| 内存 | 便宜（可扩展） | 昂贵（不可扩展，BGA 焊接） |
|
||||
|
||||
这意味着：
|
||||
|
||||
**镜像大几十 MB，可以接受。内存多占 10MB，不能接受。**
|
||||
|
||||
所以 frpc-console 的 Docker 镜像虽然包含了完整的构建环境和依赖，但它不会在运行时消耗额外内存。镜像大小和运行时内存占用，在边缘场景下是两个独立且优先级完全不同的指标。
|
||||
|
||||
### 缺失的依赖
|
||||
|
||||
边缘设备可能缺失以下内容：
|
||||
|
||||
- **Docker**：很多 ARMHF 设备跑不动 Docker，或者根本没有 Docker 的预编译包
|
||||
- **systemd**：精简系统中可能只有 init 或 busybox-init
|
||||
- **glibc**：某些环境只提供 uClibc 或 musl
|
||||
- **包管理器**：内存小到一定程度的时候，它的存在堪称奢望
|
||||
|
||||
因此，**二进制部署是边缘节点的唯一可行方案**。
|
||||
|
||||
---
|
||||
|
||||
## frpc-console 对边缘节点的适配
|
||||
|
||||
### 1. 二进制静态编译
|
||||
|
||||
frpc-console 采用 Go 编写，编译时使用 `CGO_ENABLED=0`：
|
||||
|
||||
- 不依赖 glibc
|
||||
- 单一二进制文件
|
||||
- 可运行于 musl 环境（Alpine、BusyBox）
|
||||
- 不需要任何运行时依赖
|
||||
|
||||
### 2. 多架构支持
|
||||
|
||||
| 架构 | 说明 |
|
||||
|---|---|
|
||||
| x86_64 / AMD64 | 标准服务器 |
|
||||
| ARM64 / Aarch64 | 现代 ARM 设备（树莓派 3/4/5） |
|
||||
| ARMHF / ARMv7l | 老旧 ARM 设备（全志 H3、RK3506） |
|
||||
|
||||
### 3. 无 systemd 运行方式
|
||||
|
||||
在只有 init + BusyBox 的环境中：
|
||||
|
||||
```bash
|
||||
# 直接运行
|
||||
./frpc-console &
|
||||
|
||||
# 或通过 init 启动（写入 /etc/init.d/）
|
||||
```
|
||||
|
||||
frpc-console 自身会通过 `Setsid` 为 frpc 创建独立会话，确保 frpc 在 console 退出后仍被 PID 1 接管。
|
||||
|
||||
### 4. 数据目录设计
|
||||
|
||||
```
|
||||
/opt/frpc-console/data/
|
||||
├── frpc-console.db # SQLite 数据库
|
||||
├── frpc.toml # FRP 配置文件
|
||||
├── frpc # FRP 二进制（内置，无需额外下载）
|
||||
├── frpc.pid # frpc 进程 PID
|
||||
├── frpc.log # frpc 日志（可选）
|
||||
└── version.ini # 当前版本标识
|
||||
```
|
||||
|
||||
所有数据在同一个目录下，备份只需复制整个文件夹。
|
||||
|
||||
### 5. 无日志默认策略
|
||||
|
||||
边缘设备存储有限，所以：
|
||||
|
||||
- 默认不写入日志文件
|
||||
- 日志仅在用户明确开启时写入
|
||||
- 避免 SD 卡被日志写满导致设备不可用
|
||||
|
||||
---
|
||||
|
||||
## 部署注意事项
|
||||
|
||||
### 推荐的最小硬件规格
|
||||
|
||||
| 场景 | CPU | 内存 | 存储 |
|
||||
|---|---|---|---|
|
||||
| 最小运行 | ARMv7 / ARM-HF | 128MB | 50MB（二进制 + 数据库） |
|
||||
| 推荐运行 | ARMv7 / ARM64 | 256MB | 100MB |
|
||||
| 舒适运行 | ARM64 / x86_64 | 512MB | 200MB |
|
||||
|
||||
### 不建议部署的场景
|
||||
|
||||
- **内存低于 64MB**：很极限，需要系统本身有极强的剪枝水准，以保证基础内存消耗不高于20M，但这并不现实
|
||||
- **存储低于 20MB**：没有足够的空间存放二进制和数据
|
||||
- **内核版本过低**（< 3.x）：某些系统调用可能不支持
|
||||
- **刷了OpenWRT的软/硬路由**：这种建议去下opkg的源包，而不是看向我们这个项目。
|
||||
|
||||
### 网络要求
|
||||
|
||||
- 边缘节点的网络出口带宽一般有限，首次访问 WebUI 时加载的静态资源（约 1-2MB）可能需要稍长时间
|
||||
- 后续操作仅传输 JSON 数据，流量极小
|
||||
|
||||
---
|
||||
|
||||
## 为什么这件事值得单独记录？
|
||||
|
||||
因为主流开源项目在讨论 ARM 支持时，讨论的是“树莓派 4B（4GB 版本）”。
|
||||
|
||||
而真正部署在边缘的设备，可能只有 256MB 内存，甚至连 Docker 都没有。
|
||||
|
||||
frpc-console 对 ARMHF 的支持，不是“支持的架构列表里多了一项”，而是：
|
||||
|
||||
**这个工具可以跑到那些真正藏在弱电箱里、承担网络基础设施工作的小板子上。**
|
||||
|
||||
这才是边缘节点部署的意义。
|
||||
@@ -0,0 +1,305 @@
|
||||
# 工程设计哲学
|
||||
|
||||
> *“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 的设计，本身就是一个不断演化的过程。每一次真实部署中遇到的新问题，都可能成为下一版设计哲学的注脚。*
|
||||
@@ -0,0 +1,142 @@
|
||||
# 更新策略
|
||||
|
||||
一句话：
|
||||
|
||||
更新策略不是为了更新
|
||||
|
||||
而是为了让你可以几年以后</br>
|
||||
依旧知道自己运行的是哪个版本
|
||||
|
||||
---
|
||||
|
||||
## 版本号格式
|
||||
|
||||
frpc-console 的版本号遵循以下格式：
|
||||
|
||||
```
|
||||
<semver>-<channel>-<date>-<time>
|
||||
```
|
||||
|
||||
**示例：** `2.5-LTS-260804-203825`
|
||||
|
||||
| 组成部分 | 说明 | 示例 |
|
||||
|---|---|---|
|
||||
| **semver** | 语义版本号（主版本.次版本） | `2.5` |
|
||||
| **channel** | 发布通道 | `LTS` / `Preview` |
|
||||
| **date** | 构建日期（YYMMDD） | `260804` |
|
||||
| **time** | 构建时间（HHMMSS） | `203825` |
|
||||
|
||||
---
|
||||
|
||||
## 为什么没有 Patch 版本？
|
||||
|
||||
你可能已经注意到了：
|
||||
|
||||
**版本号里只有主版本和次版本（如 `2.5`），没有 patch 号。**
|
||||
|
||||
这不是疏忽，而是有意识的设计选择。
|
||||
|
||||
原因很简单：
|
||||
|
||||
- frpc-console 的发行逻辑是标准的滚动式发行逻辑，而非完全由版本号驱动
|
||||
- 因此，frpc-console 的更新粒度是基于**构建时间戳**的，每一个不同的构建时间点，对应的可能是不一样的版本
|
||||
- 每一次构建都是一个独立的版本，通过日期时间精确标识
|
||||
- `2.5-LTS-260804-203825` 和 `2.5-LTS-260805-091422` 之间，不需要、也不应该用第三个数字来区分
|
||||
|
||||
---
|
||||
|
||||
## 双通道：LTS / Preview
|
||||
|
||||
项目采用双线开发模式，对应两个不同的分支：
|
||||
|
||||
### LTS（Long-Term Support）
|
||||
|
||||
- **分支：** `main`
|
||||
- **定位：** 稳定版，生产环境推荐
|
||||
- **特征：** 低更新频率，可以在不接收任何冷热更新的情况下，长时间稳定自持
|
||||
- **适用场景：** 生产环境、Homelab 主节点、长期运行设备
|
||||
|
||||
### Preview
|
||||
|
||||
- **分支：** `test`
|
||||
- **定位：** 技术预览版，包含最新设计和实验性功能
|
||||
- **特征：** 极高更新频率，很多时候会伴随大量不稳定commit，稳定性并不佳
|
||||
- **适用场景：** 开发者用测试环境、尝鲜用户、边缘节点验证
|
||||
|
||||
---
|
||||
|
||||
## 更新机制
|
||||
|
||||
### 部署脚本中的更新逻辑
|
||||
|
||||
`deploy.sh` 脚本在每次运行时，会从远程仓库读取当前分支的最新版本：
|
||||
|
||||
```bash
|
||||
# 从远程读取 version.ini
|
||||
SEMVER=$(curl -sSL https://git.whitetop.xyz/.../version.ini)
|
||||
|
||||
# 根据通道生成完整版本号
|
||||
if [ "$channel" = "lts" ]; then
|
||||
TARGET_VERSION="${SEMVER}-lts-$(date +%Y%m%d)"
|
||||
else
|
||||
TARGET_VERSION="${SEMVER}-preview-$(date +%Y%m%d-%H%M%S)"
|
||||
fi
|
||||
```
|
||||
|
||||
每次运行部署脚本，都会生成一个新的版本号，并写入 `data/version.ini`。
|
||||
|
||||
### 版本比较
|
||||
|
||||
部署脚本在更新前会检查当前版本和目标版本：
|
||||
|
||||
```bash
|
||||
CURRENT_VERSION=$(cat /opt/frpc-console/data/version.ini)
|
||||
CUR_SEMVER=$(echo "$CURRENT_VERSION" | sed -E 's/^([0-9]+\.[0-9]+).*$/\1/')
|
||||
TGT_SEMVER=$(echo "$TARGET_VERSION" | sed -E 's/^([0-9]+\.[0-9]+).*$/\1/')
|
||||
```
|
||||
|
||||
如果检测到**语义版本降级**（例如从 `2.6` 降到 `2.5`），脚本会：
|
||||
|
||||
1. 发出警告
|
||||
2. 自动备份当前数据目录
|
||||
3. 等待用户确认后才继续
|
||||
|
||||
### 通道固定原则
|
||||
|
||||
一旦选择了一个通道（LTS 或 Preview），后续升级时**不应切换通道**：
|
||||
|
||||
- LTS → LTS：允许，正常升级
|
||||
- Preview → Preview：允许，正常升级
|
||||
- LTS → Preview：**不推荐**，可能引入未经充分验证的变更
|
||||
- Preview → LTS：**不推荐**，可能发生版本降级
|
||||
|
||||
如果确实需要切换通道，部署脚本会在抓取源码前，自动备份你的数据库到安全位置，但是脚本本身也存在可能的不稳定因素，此时请保证你的手中至少有一份可用的较新的toml文件，可供部署完成后恢复
|
||||
|
||||
---
|
||||
|
||||
## 镜像保留策略
|
||||
|
||||
Docker 部署时，脚本会自动保留最近 **3 个** 镜像：
|
||||
|
||||
```bash
|
||||
KEEP_IMAGES=3
|
||||
```
|
||||
|
||||
这 3 个镜像足够用于回滚，又不会占用过多存储空间（边缘节点存储有限）。
|
||||
|
||||
---
|
||||
|
||||
## 为什么这套策略是合理的？
|
||||
|
||||
1. **基础设施工具不需要频繁的版本号膨胀。** 一年发布一个大版本，中间用 LTS 累积修复，比每个小补丁都发一个新版本更符合长期运行环境的预期。
|
||||
|
||||
2. **构建日期比 patch 号更有信息量。** `2.5-LTS-260804` 一眼就能看出是 2026 年 8 月 4 日构建的 LTS 版本，不需要查 changelog。
|
||||
|
||||
3. **用户不需要关心 patch。** 用户只需要知道当前是 LTS 还是 Preview，以及发布日期。具体的修复内容，在更新日志里。
|
||||
|
||||
---
|
||||
|
||||
## 相关文档
|
||||
|
||||
- 部署脚本的更新逻辑详见：[部署指南 - Docker版](./install_docker.md) 和 [部署指南-二进制版](./install_binary.md)
|
||||
- 版本号的设计背景详见：[工程设计哲学](./engineering-philosophy.md)
|
||||
@@ -2,275 +2,56 @@
|
||||
<img src="static/logo.svg" alt="frpc-console" width="360" />
|
||||
</p>
|
||||
|
||||
|
||||
# frpc-console
|
||||
|
||||
> 轻量级 frpc 管理面板 —— 为你的内网穿透插上翅膀
|
||||
# frpc-console
|
||||
|
||||
[](https://git.whitetop.xyz/lxh2875931338/frpc-console/releases)
|
||||
[](https://golang.org/)
|
||||
[](LICENSE)
|
||||
|
||||
**专为超长期frpc部署而设计。**
|
||||
|
||||
一个基于实际工程实践而构建的——轻量级生命周期控制台。
|
||||
|
||||
**安装一次。配置一次。然后——忘记它。**
|
||||
|
||||
---
|
||||
|
||||
## 📖 简介
|
||||
## 📖 文档索引
|
||||
| 目录 | 简要说明 |
|
||||
|---|---|
|
||||
| [📖 工程设计哲学](./Docs/engineering-philosophy.md) | 为什么它会长成今天这样 |
|
||||
| [🔄 更新策略](./Docs/update-strategy.md) | Preview / LTS |
|
||||
| [🏗 架构设计](./Docs/architecture.md) | 整体架构设计思路 |
|
||||
| [⚙ 设计决策](./Docs/design-decisions.md) | 为什么没有 CI？为什么叫 Console？ |
|
||||
| [🌐 边缘节点](./Docs/edge-node.md) | 为什么支持 BusyBox、ARMHF |
|
||||
|
||||
**frpc-console** 是一个专为 [frp](https://github.com/fatedier/frp) 设计的轻量级管理工具。本项目旨在以无限接近原生占用的情况下，实现完全图形化的控制工具（毕竟 WebUI 也算图形化，对吧？）
|
||||
---
|
||||
|
||||
### ✨ 核心特性
|
||||
> *“The best infrastructure tool is the one you rarely notice.”*
|
||||
|
||||
- 🔐 **首次启动引导** —— Web 端完成管理员注册，无需 CLI 交互
|
||||
- 📋 **隧道全生命周期管理** —— 增删改查 + 一键启用/禁用
|
||||
- 📦 **导入/导出 TOML** —— 无缝迁移现有 frpc 配置
|
||||
- 🔄 **配置热加载** —— 修改即生效，无需重启 frpc
|
||||
- 🖥️ **多平台支持** —— Windows / Linux / ARM 全平台兼容
|
||||
- 🐳 **容器化就绪** —— 提供 Docker 镜像，开箱即用
|
||||
- 🎨 **深色磨砂玻璃 UI** —— 现代化视觉体验，日夜皆宜
|
||||
如果想了解这句话背后的设计思考：
|
||||
|
||||
📖 **阅读[《工程设计哲学》→](./Docs/engineering-philosophy.md) **
|
||||
|
||||
---
|
||||
|
||||
## 🚀 快速开始
|
||||
|
||||
### 🐧 二进制安装（推荐）
|
||||
选择适合您环境的部署方法：
|
||||
|
||||
适用于 Linux / Windows，无需 Docker，单文件运行。
|
||||
- [二进制安装指南](./Docs/INSTALL_BINARY.md)
|
||||
- [Docker 安装指南](./Docs/INSTALL_DOCKER.md)
|
||||
|
||||
👉 详见：[二进制安装指南](./INSTALL_BINARY.md)
|
||||
首次访问：
|
||||
|
||||
### 🐳 Docker 部署（一键脚本）
|
||||
1. 注册管理员账户。
|
||||
2. 导入你的 `frpc.toml`。
|
||||
|
||||
适用于 Linux 服务器，自动编译 + 自动部署。
|
||||
然后——
|
||||
|
||||
```bash
|
||||
curl -sSL https://git.whitetop.xyz/lxh2875931338/frpc-console/raw/main/deploy.sh | sudo bash
|
||||
```
|
||||
|
||||
👉 详见：[Docker 安装指南](./INSTALL_DOCKER.md)
|
||||
|
||||
### 🔧 源码编译
|
||||
|
||||
适合开发者或需要自定义配置的用户。
|
||||
|
||||
```bash
|
||||
git clone https://git.whitetop.xyz/lxh2875931338/frpc-console.git
|
||||
cd frpc-console
|
||||
go mod tidy
|
||||
go build -o frpc-console .
|
||||
./frpc-console
|
||||
```
|
||||
|
||||
首次访问 `http://localhost:9300` 注册管理员账户，然后导入你的 `frpc.toml` 即可开始使用。
|
||||
**忘记它。**
|
||||
|
||||
---
|
||||
|
||||
## 🗂️ 项目结构
|
||||
```txt
|
||||
frpc-console/
|
||||
├── main.go # 入口
|
||||
├── api.go # HTTP 路由 & Handler
|
||||
├── db.go # SQLite 数据库操作
|
||||
├── auth.go # JWT 认证 & 密码管理
|
||||
├── frp.go # frpc 管理核心逻辑
|
||||
├── toml_parser.go # TOML 解析器
|
||||
├── static/ # 前端静态资源
|
||||
│ ├── fonts
|
||||
│ │ └── HarmonyOS_Sans_SC_Regular.ttf
|
||||
│ ├── index.html
|
||||
│ ├── app.js
|
||||
│ ├── style-1.css # 全局基础样式
|
||||
│ ├── style-2.css # 登录页样式
|
||||
│ ├── style-3.css # 主界面样式
|
||||
│ └── style-4.css
|
||||
├── bin/ # 内嵌 frpc 二进制 (多平台)
|
||||
│ ├── frpc_windows_amd64.exe
|
||||
│ ├── frpc_linux_amd64
|
||||
│ ├── frpc_linux_arm64
|
||||
│ └── frpc_linux_arm_hf
|
||||
├── frpc.tmpl # frpc 配置模板
|
||||
├── Dockerfile
|
||||
└── go.mod
|
||||
```
|
||||
[**MIT License © 2026 lxh2875931338（XHLiang0）**](./License.md) · [GitHub](https://github.com/XHLiang0) · [致谢](./Docs/acknowledgment.md)
|
||||
|
||||
## ⚙️ 配置说明
|
||||
|
||||
### 环境变量
|
||||
|
||||
| 变量 | 说明 | 默认值 |
|
||||
|---|---|---|
|
||||
| PORT | 监听端口 | 9300 |
|
||||
|
||||
|
||||
### 数据存储
|
||||
|
||||
· 数据库文件：./frpc-console.db</br>
|
||||
· frpc 配置文件：./frpc.toml</br>
|
||||
· frpc 日志文件：./frpc.log</br>
|
||||
|
||||
---
|
||||
|
||||
## 🛠️ 开发指南
|
||||
|
||||
```bash
|
||||
# 克隆项目
|
||||
git clone https://github.com/lxh2875931338/frpc-console.git
|
||||
cd frpc-console
|
||||
|
||||
# 安装依赖
|
||||
go mod tidy
|
||||
|
||||
# 开发模式运行
|
||||
go run .
|
||||
|
||||
# 编译生产版本
|
||||
go build -ldflags="-s -w" -o frpc-console .
|
||||
```
|
||||
|
||||
## 前端开发
|
||||
|
||||
前端使用 Vue 3 CDN + Naive UI，无需额外构建工具。修改 static/ 目录下的文件后，刷新浏览器即可预览效果。
|
||||
|
||||
|
||||
---
|
||||
|
||||
## 🔧 常见问题
|
||||
|
||||
#### Q: 如何修改管理员密码？
|
||||
|
||||
登录后，在「全局配置」页面顶部找到「账户管理」区域，输入当前密码和新密码即可。
|
||||
|
||||
#### Q: 如何导入现有的 frpc.toml？
|
||||
|
||||
在「隧道列表」页面点击「导入 TOML」，选择你的 frpc.toml 文件即可。
|
||||
|
||||
#### Q: frpc 启动失败怎么办？
|
||||
|
||||
如果是首次启动，console 会自动生成一份符合官方规范的 `frps.toml` 配置文件，通常不需要额外操作。
|
||||
|
||||
如果在使用过程中遇到启动失败，可以按以下步骤排查：
|
||||
|
||||
1. **检查配置是否正确** —— 在「全局配置」页面重新配置一次服务端参数，或导入已有的 `frpc.toml` 配置文件，console 会自动应用并尝试重启
|
||||
2. **查看日志定位问题** —— 若上述操作后仍然失败，请查看 `./frpc.log` 日志文件，定位具体报错原因
|
||||
|
||||
> 日志文件的位置：与 `frpc-console` 二进制同级目录下的 `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 |
|
||||
|
||||
> 行了行了，Windows 版和 Linux 版版本号已同步。不用再等了。
|
||||
|
||||
#### Q: 为什么不用 / 不推荐 Podux？
|
||||
|
||||
Podux 是个好项目，理念上和我们是一致的：用 Web 界面管理 frpc</br>
|
||||
但它的设计取向和我们完全不同：
|
||||
|
||||
| 对比项 | frpc-console | Podux |
|
||||
|---|---|---|
|
||||
| 数据库 | SQLite（单文件，几 MB） | PocketBase（带 Admin UI、用户系统、全套 API） |
|
||||
| 前端 | Vue CDN | React + Webpack |
|
||||
| 实机内存占用 | **~50 MB** | **没启动成功，1GB RAM 独立分配仍 OOM（原因不明）** |
|
||||
| 镜像大小 | 封装二进制frpc后均值 173.86 MB | 76.1 MB |
|
||||
| 二进制大小 | 4平台均值93M | 12.4 MB |
|
||||
| 部署方式 | 单二进制 / Docker | 单二进制 / Docker |
|
||||
| 多平台支持 | ✅ 原生交叉编译 | ✅ 原生交叉编译 |
|
||||
|
||||
> Podux 与其说是一个 frp 控制面板，不如说是一个“一站式 frp 管理器 + 可视化数据流面板 + 通道保活监测工具”。这种一站式本身没毛病，甚至功能实现非常到位。</br>但 podux 的框架选型有点重，细节也稍显仓促，最终结果就是内存占用相当夸张——1GB 都未必够它霍霍的，而且你根本不知道这些内存都花在了哪里。PocketBase 自带 WebUI 的情况下，Podux 还要再包一层 WebUI——相当于给数据库的 UI 又套了个 UI。更费解的是，这层 WebUI 只支持导入，不支持导出。这设计确实让人有点摸不着头脑啦……</br>所以干脆换了一套轻量化工具自己上咯~
|
||||
|
||||
> 不过现在的 frpc-console，更倾向于拿存储换内存呢……</br>毕竟内存卡也好，硬盘也罢，即使是嵌入式平台，价格都不算很离谱，也就是一张大点的64G或者128G内存卡的事情</br>但是内存可就不一样了哦，这玩意在嵌入式平台是真的寸土寸金呢……</br>咱就举个例子吧，RK3506，128和256M版本共存；全志H3，256 和 512M 内存并存</br>虽然这俩都不算太极端，尤其是全志 H3，挤一挤甚至 docker 版也能装得上，但是也能说明，在一些廉价的低功耗开发板上，内存容量其实真的很稀缺……</br>所以牺牲一点存储空间（镜像大了几十 MB），换来 50MB 的内存占用，这笔账怎么算都不亏，对吧？
|
||||
|
||||
|
||||
### Q: 为什么不直接用 frp 官方提供的 web 界面？
|
||||
|
||||
frp 官方确实提供了 `dashboard` 和 `frpc-admin` 功能，但它们更多是“监控”视角，而非“管理”视角。你需要手动编辑配置文件，重启 frpc，或者依赖命令行操作。
|
||||
|
||||
frpc-console 的目标是：
|
||||
- **点一点就能新增隧道**
|
||||
- **开关一拨就能启用/禁用**
|
||||
- **导入导出无缝迁移**
|
||||
- **热加载无需重启**
|
||||
|
||||
#### Q: 如果 frpc-console 进程挂了，frpc 本身会受影响吗？
|
||||
|
||||
**不会。**
|
||||
|
||||
这是 frp-console 系列工具与同类项目最核心的区别之一。我们称之为 **“阴阳模式”**。
|
||||
|
||||
**什么是“阴阳模式”？**
|
||||
|
||||
- **阴**：看不见的业务流（frpc 进程、toml 配置文件）
|
||||
- **阳**：看得见的管理面板（Web 界面、API 服务）
|
||||
|
||||
大多数管理工具走的是 **“阳阴模式”**：面板是大脑，业务是肢体。大脑一旦停止工作，肢体也就瘫痪了。
|
||||
|
||||
**frpc-console 走的是“阴阳模式”：业务是根基，面板是工具。**
|
||||
|
||||
**二进制部署：**
|
||||
frpc-console 启动时，通过 `Setsid` 为 frpc 创建独立会话，使其完全脱离父进程的生命周期控制。即使 SSH 断开导致 console 退出，frps 也会被 init 进程（PID 1）接管，继续稳定运行。
|
||||
|
||||
**Docker 部署：**
|
||||
容器使用 `--restart=always`，console 退出时 Docker 自动重启并重新拉起 frpc。数据目录通过卷挂载持久化，配置不丢失。
|
||||
|
||||
两种部署方式的本质一致：**面板是“阳”，服务于“阴”；“阴”不依赖“阳”而存在。**
|
||||
|
||||
**为什么同类项目很少这样做？**
|
||||
|
||||
因为大多数管理工具默认“面板是前提条件”，而忽略了：**真正需要长期稳定运行的是隧道本身，而不是管理界面的进程。**
|
||||
|
||||
> **管理面板可以丢，业务功能打死不能停。**
|
||||
|
||||
### Q: 支持 frp 的所有功能吗？
|
||||
|
||||
frpc-console 覆盖了 frp 最核心的 **TCP 隧道管理** 功能，包括 `tcpMux`、负载均衡、心跳配置等。如果你有更复杂的需求（比如 STCP、XTCP、P2P），欢迎提 issue，我们会评估是否加入。
|
||||
|
||||
## 🧠 设计哲学
|
||||
|
||||
frpc-console 遵循 **“够用就好”** 的原则：
|
||||
|
||||
1. **工具应该和它所管理的对象一样轻量。** 管理面板不该成为比业务本身更重的负担。
|
||||
|
||||
2. **用最简单的技术栈，做最核心的事。** SQLite 单文件存数据，Vue CDN 写界面，Go 单二进制交付——没有多余依赖，没有构建工具链，改完就能跑。
|
||||
|
||||
3. **数据归数据，二进制归二进制。** 版本信息从编译时注入解耦为运行时读取，数据库、配置、日志统一归入 `data/` 目录，挂载点收窄到数据本身，而非整个应用。
|
||||
|
||||
4. **业务是目的，面板是手段。** 业务进程独立于管理面板存在，面板可以随时挂、随时重启、随时升级，隧道业务不能受任何干扰。
|
||||
|
||||
5. **存储换内存，在嵌入式平台上不是交易，是生存策略。** 镜像可以大几十 MB，但内存必须省——因为内存卡便宜，内存颗粒贵。
|
||||
|
||||
|
||||
---
|
||||
|
||||
## 📝 更新日志
|
||||
|
||||
#### 相关更新日志请查看[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 生态同类工具（暂无互引）
|
||||
</br>
|
||||
|
||||
---
|
||||
|
||||
## 🙏 致谢
|
||||
|
||||
· fatedier/frp —— 强大的内网穿透工具</br>
|
||||
· gin-gonic/gin —— 高性能 Go Web 框架</br>
|
||||
· vuejs/vue —— 渐进式 JavaScript 框架
|
||||
Reference in New Issue
Block a user