frps-console/readme.md

<p align="center">
  <img src="static/logo.svg" alt="frps-console" width="360" />
</p>

# frps-console

> 轻量级 frps 服务端管理面板 —— 让流量中转尽在掌握

[![Release](https://img.shields.io/gitea/v/release/lxh2875931338/frps-console?gitea_url=https://git.whitetop.xyz)](https://git.whitetop.xyz/lxh2875931338/frps-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)

---

## 📖 简介

**frps-console** 是专为 [frp](https://github.com/fatedier/frp) 服务端（frps）设计的轻量级 Web 管理工具。
与 [frps-console](https://git.whitetop.xyz/lxh2875931338/frps-console)  形成姊妹篇，一个管理客户端，一个管理服务端。

本项目作为 frp-console 系列套件的项目之一，延续 frps-console 的设计哲学：**以无限接近原生占用的情况下，实现完全图形化的控制工具**。实测内存占用约 **92MB**（面板 60MB + frps 32MB），512MB 云服务器轻松跑。

### ✨ 核心特性

- 🔐 **首次启动引导** —— Web 端完成管理员注册，无需 CLI 交互
- 🖥️ **服务端配置管理** —— 通过 WebUI 管理 frps 核心参数（`bindPort` / `token` / `log` / `tcpMux`），告别手动编辑 TOML
- 📊 **客户端状态概览** —— 实时查看连接到 frps 的所有客户端列表，包含在线状态、连接时间、协议版本（v1/v2）
- 📄 **运行日志面板** —— WebUI 内实时查看 frps 运行日志，8 秒自动轮询
- 🔄 **配置热加载** —— 修改配置后一键热加载，无需重启 frps 服务
- 🖥️ **多平台支持** —— Linux AMD64 / ARM64 / ARMv7 全平台兼容
- 🐳 **容器化就绪** —— 提供 Docker 镜像与一键部署脚本，开箱即用
- 🎨 **深色磨砂玻璃 UI** —— 与 frps-console 保持统一的视觉风格

---

## 🚀 快速开始

### 🐧 二进制安装（推荐）

适用于 Linux 服务器，无需 Docker，单文件运行。

👉 详见：[二进制安装指南](./INSTALL_BINARY.md)

### 🐳 Docker 部署（一键脚本）

适用于 Linux 服务器，自动编译 + 自动部署。

```bash
curl -sSL https://git.whitetop.xyz/lxh2875931338/frps-console/raw/main/deploy.sh | sudo bash
```

👉 详见：[Docker 安装指南](./INSTALL_DOCKER.md)

### 🔧 源码编译

适合开发者或需要自定义配置的用户。

```bash
git clone https://git.whitetop.xyz/lxh2875931338/frps-console.git
cd frps-console
go mod tidy
go build -o frps-console .
./frps-console
```

首次访问 `http://localhost:9365` 注册管理员账户即可开始使用。

---

## 🗂️ 项目结构

```txt
frps-console/
├── main.go                   # 入口
├── api.go                    # HTTP 路由 & Handler
├── db.go                     # SQLite 数据库操作
├── auth.go                   # JWT 认证 & 密码管理
├── frps.go                   # frps 管理核心逻辑
├── toml_parser.go            # TOML 解析器
├── static/                   # 前端静态资源
│   ├── index.html
│   ├── app.js
│   ├── style-1.css           # 全局基础样式
│   ├── style-2.css           # 登录页样式
│   ├── style-3.css           # 主界面样式
│   └── style-4.css
├── bin/                      # 内嵌 frps 二进制 (多平台)
│   ├── frps_windows_amd64.exe
│   ├── frps_linux_amd64
│   ├── frps_linux_arm64
│   └── frps_linux_arm_hf
├── frps.tmpl                 # frps 配置模板
├── Dockerfile
└── go.mod
```

---

## ⚙️ 配置说明

### 环境变量

| 变量 | 说明 | 默认值 |
|---|---|---|
| PORT | 监听端口 | 9365 |

### 数据存储

· 数据库文件：`./frps-console.db`</br>
· frps 配置文件：`./frps.toml`</br>
· frps 日志文件：`./frps.log`</br>

---

## 🛠️ 开发指南

```bash
# 克隆项目
git clone https://git.whitetop.xyz/lxh2875931338/frps-console.git
cd frps-console

# 安装依赖
go mod tidy

# 开发模式运行
go run .

# 编译生产版本
go build -ldflags="-s -w" -o frps-console .
```

### 前端开发

前端使用 Vue 3 CDN，无需额外构建工具。修改 `static/` 目录下的文件后，刷新浏览器即可预览效果。

---

## 🔧 常见问题

#### Q: 如何修改管理员密码？

登录后，在「全局配置」页面顶部找到「账户管理」区域，输入当前密码和新密码即可。

#### Q: frps 启动失败怎么办？

首次启动的话，console会创建一个全新的、符合官方规范的toml配置文件。</br>
如果使用中出现启动失败问题，可以在console内重新配置一次服务端参数，或者导入已有的toml即可恢复</br>
如果依旧无效，请查看 ./frps.log 日志文件。

#### Q: 支持哪些 frp 版本？

目前支持情况如下：

| 系统 | 架构版本 | 版本号 |
|---|---|---|
| Linux | AMD64/x86-64 | 0.70.0 |
| Linux | ARM64/Aarch64 | 0.70.0 |
| Linux | ARM_hf/ARMv7l | 0.70.0 |

#### Q: frps-console 和 frps-console 有什么区别？

| 对比项 | frps-console | frps-console |
|---|---|---|
| 管理对象 | frps（客户端） | frps（服务端） |
| 适用场景 | 软路由、小主机、本地服务穿透 | VPS、云主机、流量中转 |
| 默认端口 | 9300 | 9365 |
| 核心功能 | 隧道增删改查 + 导入导出 TOML | 服务端配置 + 客户端状态概览 |

#### Q: 如果 frps-console 进程挂了，frps 本身会受影响吗？

**不会。**

这是 frp-console 系列工具与同类项目最核心的区别之一。我们称之为 **“阴阳模式”**。

**什么是“阴阳模式”？**

以人的观察为出发点：

- **阴**：看不见的业务流（frps 进程、toml 配置文件、隧道连接）
- **阳**：看得见的管理面板（Web 界面、API 服务）

大多数管理工具走的是 **“阳阴模式”**：面板是“大脑”，业务是“肢体”。大脑一旦停止工作，肢体也就瘫痪了。

**frps-console 走的是“阴阳模式”：业务是根基，面板是工具。**

- **阴主导阳**：业务不依赖面板存活，面板只是用来观察和调整业务状态的手段
- **阳依附于阴**：面板的存在是为了服务业务，而不是反过来

**二进制部署：**

frps-console 启动时，会以子进程的方式拉起 frps，并为它创建一个独立的进程会话（`Setsid`）。即使 SSH 断开导致 frps-console 进程退出，frps 也会被系统的 init 进程（PID 1）接管，继续在后台稳定运行。配置文件（`frps.toml`）是持久化文件，不依赖 console 进程存活。

**Docker 部署：**

容器使用 `--restart=always` 策略，frps-console 进程意外退出时，Docker 守护进程会自动重启整个容器。重启后重新拉起 frps 子进程。数据目录通过卷挂载持久化，容器重启不会丢失任何配置。

**核心原则：**

console 只做“配置的保管者”和“进程的启动者”，而不是“配置的持有者”或“进程的绑定者”。即使 console 完全离线，已经生成的 `frps.toml` 依然存在，frps 进程依然可以独立运行。

> **管理面板可以丢，业务功能打死不能停。**

#### Q: 支持 frps 的所有功能吗？

frps-console 覆盖了 frps 最核心的配置管理功能，包括 `bindPort`、`token`、`log`、`tcpMux` 等。如果你有更复杂的需求（如 Dashboard API 数据可视化、多 frps 管理），欢迎提 issue，我们会评估是否加入。

---

## 🧠 设计哲学

frps-console 遵循 **“够用就好”** 的原则：

1. **frp 是轻量工具，管理工具也应该是轻量的。**
2. **能用 SQLite 就不用 PostgreSQL，能用 Vue CDN 就不用 React 全家桶。**
3. **前端能做的事，后端不加额外复杂度。**
4. **删掉一个容器等于删掉所有垃圾，所以用 Docker 隔离是对的。**
5. **面板的存在应该是为了服务业务的，而不该是反过来主导业务的。**

---

## 📝 更新日志

### 2.0-Release（LTS，首次公开发布，与 frps-console 2.0-LTS 同步）

> 这是 frps-console 的首次正式发布。frps-console 没有 1.x 系列——在 v1.x 阶段，它尚处于内部测试形态，从未公开发布。首次公开发布直接定为 **2.0-LTS**，与 frps-console 的 LTS 版本对齐，后续版本号将与 frps-console 保持同步。

· 🚀 **服务端配置管理** —— 通过 WebUI 管理 frps 核心参数，告别手动编辑 TOML</br>
· 📊 **客户端状态概览** —— 实时查看连接到 frps 的所有客户端列表</br>
· 📄 **运行日志面板** —— WebUI 内实时查看 frps 日志，8 秒自动轮询</br>
· 🔄 **配置热加载** —— 修改配置后一键热加载，无需重启 frps</br>
· 🔐 **首次启动 Web 注册** —— 无需命令行交互即可完成管理员账户创建</br>
· 🖥️ **多平台支持** —— Linux AMD64 / ARM64 / ARMv7 全平台兼容</br>
· 🐳 **容器化就绪** —— Docker 镜像 + 一键部署脚本，开箱即用</br>
· 🎨 **深色磨砂玻璃 UI** —— 与 frps-console 保持统一的视觉风格</br>
· 🔒 **数据库自动迁移** —— 升级时自动备份 + 迁移，数据零丢失</br>
· 🧩 **frp v2 协议就绪** —— frps 已升级至 0.70.0 LTS，原生支持 v2 协议（v2 开关在 frps 侧开启）

---

## 📄 许可证

MIT License © 2026 lxh2875931338（XHLiang0）

---

## 🙏 相关项目援引

### FRP 生态互补工具

· [MoonProxy](https://github.com/MoonProxyHQ/moonproxy-desktop) —— 基于 Tauri v2 + Vue 3 + Rust 构建的跨平台 FRP 桌面客户端（frps GUI），面向 macOS 与 Windows，MIT 协议开源。

· [frps-console](https://git.whitetop.xyz/lxh2875931338/frps-console) —— 姊妹篇，管理 frps 客户端，已发布 2.0-LTS，同步 LTS 维护。

---

## 🙏 致谢

· fatedier/frp —— 强大的内网穿透工具</br>
· gin-gonic/gin —— 高性能 Go Web 框架</br>
· vuejs/vue —— 渐进式 JavaScript 框架
```