diff --git a/.github/workflows/latest.workflow.yml b/.github/workflows/latest.workflow.yml deleted file mode 100644 index 0e0fd49..0000000 --- a/.github/workflows/latest.workflow.yml +++ /dev/null @@ -1,53 +0,0 @@ -name: Latest Release -on: - push: - branches: [main] - pull_request: - branches: [main] - workflow_dispatch: - -jobs: - build-static: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v4 - with: - fetch-depth: 0 - - name: npm setup - uses: actions/setup-node@v4 - with: - node-version: 20 - - name: Setup Go - uses: actions/setup-go@v4 - with: - go-version: "1.24.x" - - name: npm install and build - run: | - cd www - npm install && npm install -g pnpm - - name: Install dependencies - run: | - go mod tidy - go install google.golang.org/protobuf/cmd/protoc-gen-go@latest - go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest - - name: Install Protoc - uses: arduino/setup-protoc@v3 - - name: Compile server - run: bash ./build.sh - - uses: "marvinpinto/action-automatic-releases@latest" - with: - repo_token: "${{ secrets.GITHUB_TOKEN }}" - prerelease: true - automatic_release_tag: latest - files: | - dist/* - - name: Setup ko - uses: ko-build/setup-ko@v0.9 - env: - KO_DOCKER_REPO: docker.io/vaalacat/frp-panel - - env: - username: ${{ secrets.DOCKERHUB_USERNAME }} - password: ${{ secrets.DOCKERHUB_TOKEN }} - run: | - echo "${password}" | ko login docker.io --username ${username} --password-stdin - ko build ./cmd/frpp --sbom=none --bare \ No newline at end of file diff --git a/.github/workflows/master.workflow.yml b/.github/workflows/master.workflow.yml new file mode 100644 index 0000000..a93ea55 --- /dev/null +++ b/.github/workflows/master.workflow.yml @@ -0,0 +1,53 @@ +# name: Master Release +# on: +# push: +# branches: [main] +# pull_request: +# branches: [main] +# workflow_dispatch: + +# jobs: +# build-static: +# runs-on: ubuntu-latest +# steps: +# - uses: actions/checkout@v4 +# with: +# fetch-depth: 0 +# - name: npm setup +# uses: actions/setup-node@v4 +# with: +# node-version: 20 +# - name: Setup Go +# uses: actions/setup-go@v4 +# with: +# go-version: "1.24.x" +# - name: npm install and build +# run: | +# cd www +# npm install && npm install -g pnpm +# - name: Install dependencies +# run: | +# go mod tidy +# go install google.golang.org/protobuf/cmd/protoc-gen-go@latest +# go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest +# - name: Install Protoc +# uses: arduino/setup-protoc@v3 +# - name: Compile server +# run: bash ./build.sh +# - uses: "marvinpinto/action-automatic-releases@latest" +# with: +# repo_token: "${{ secrets.GITHUB_TOKEN }}" +# prerelease: true +# automatic_release_tag: latest +# files: | +# dist/* +# - name: Setup ko +# uses: ko-build/setup-ko@v0.9 +# env: +# KO_DOCKER_REPO: docker.io/vaalacat/frp-panel +# - env: +# username: ${{ secrets.DOCKERHUB_USERNAME }} +# password: ${{ secrets.DOCKERHUB_TOKEN }} +# run: | +# echo "${password}" | ko login docker.io --username ${username} --password-stdin +# ko build ./cmd/frpp --sbom=none --bare \ No newline at end of file diff --git a/.github/workflows/tag.workflow.yml b/.github/workflows/tag.workflow.yml index a5c6328..bb07f88 100644 --- a/.github/workflows/tag.workflow.yml +++ b/.github/workflows/tag.workflow.yml @@ -35,13 +35,22 @@ jobs: uses: arduino/setup-protoc@v3 - name: Compile server run: bash ./build.sh - - uses: "marvinpinto/action-automatic-releases@latest" + - name: Tag Release + uses: "marvinpinto/action-automatic-releases@latest" with: repo_token: "${{ secrets.GITHUB_TOKEN }}" prerelease: false automatic_release_tag: ${{ steps.get_version.outputs.VERSION }} files: | dist/* + - name: Latest Release + uses: "marvinpinto/action-automatic-releases@latest" + with: + repo_token: "${{ secrets.GITHUB_TOKEN }}" + prerelease: true + automatic_release_tag: latest + files: | + dist/* - name: Setup ko uses: ko-build/setup-ko@v0.9 env: @@ -52,4 +61,5 @@ jobs: password: ${{ secrets.DOCKERHUB_TOKEN }} run: | echo "${password}" | ko login docker.io --username ${username} --password-stdin - ko build ./cmd/frpp --sbom=none --bare -t ${{ steps.get_version.outputs.VERSION }} \ No newline at end of file + ko build ./cmd/frpp --sbom=none --bare -t ${{ steps.get_version.outputs.VERSION }} + ko build ./cmd/frpp --sbom=none --bare -t latest \ No newline at end of file diff --git a/README.md b/README.md index ce08fc0..f31b47a 100644 --- a/README.md +++ b/README.md @@ -1,293 +1,54 @@ -> FRP-Panel WIKI：[FRP-Panel WiKi](https://vaala.cat/frp-panel) -> -> Development blog: [https://vaala.cat/posts/frp-panel-doc/](https://vaala.cat/posts/frp-panel-doc/) -> -> You can refer to the wiki for instructions, or scroll down read simple doc. - # FRP-Panel -[English Version](README.md) | [中文文档](README_zh.md) +FRP-Panel is a visualization management dashboard for FRP, offering centralized configuration, unified credentials, dynamic scheduling, and edge Worker support—making NAT traversal and service exposure simpler, safer, and more efficient. -VaalaCat%2Ffrp-panel | Trendshift +[Detailed Documentation (Wiki)](https://vaala.cat/frp-panel/en/) · [Development Blog](https://vaala.cat/posts/frp-panel-doc/) · [Screenshots & Videos](https://vaala.cat/posts/frp-panel-doc/en/screenshots) · QQ Group: 830620423 -Our goal is to create a more powerful and comprehensive frp that provides: +English | [中文](./README_zh.md) -- Centralized management of client configurations -- Management of multiple server configurations -- Visual configuration interface -- Simplified configuration required for running -- Support Cloudflare edge computing Worker - -> Demo Video: [demo Video](./docs/public/images/frp-panel-demo.mp4) - -![](./docs/public/images/frp-panel-demo.gif) - -## Star History - -[![Star History Chart](https://api.star-history.com/svg?repos=vaalacat/frp-panel&type=Date)](https://www.star-history.com/#vaalacat/frp-panel&Date) - -## Sponsors - -frp-panel is a completely free and open source project, relying on the author's love to write code. If you are willing to support the development, please consider sponsoring VaalaCat (Email: `me#vaala.cat`, replace # with @) - -[NodeSupport](https://github.com/NodeSeekDev/NodeSupport) has sponsored this project. - -
- - +
+ + VaalaCat/frp-panel | Trendshift
-## Project Usage Instructions +## Key Advantages -frp-panel can be deployed in docker or direct run mode. For direct deployment, please download the files from the release: [release](https://github.com/VaalaCat/frp-panel/releases) +| Advantage | Description | +|:-----------------------|:----------------------------------------------------------------------------| +| Centralized Configuration | All client/server configs are managed by Master—no manual JSON editing | +| Multi-node Management | Monitor and orchestrate any number of frpc (clients) and frps (servers) | +| Visual Interface | Create, edit, and monitor tunnels and Workers via Web UI, with real-time logs and stats | +| Simplified Credential Distribution | Auto-generate and distribute startup commands—no manual parameter passing | +| Edge Worker Deployment | Deploy custom Workers on Clients, expose them via Server, and adjust configs live via Master | -Note: There are two types of binaries, one is for the client only, and the other is a full-featured executable file. The client version will have a "client" identifier in its name. +## Architecture Overview -After startup, the default access address is `http://IP:9000`. +![Architecture Diagram](./docs/public/images/arch.svg) -The first registered user is the administrator by default. User registration is not open by default. If you need it, please add the following parameter to the Master startup command or configuration file: `APP_ENABLE_REGISTER=true` +1. **Master** – Centralized management and authentication; requires access from all Servers and Clients +2. **Server** – Public-facing entry point that handles traffic for Clients +3. **Client** – Internal proxy that supports deploying Workers -After starting, there will be a "default" entry in the server list. If the status shows "Offline" in red, it indicates that your `MASTER_RPC_HOST` environment variable is not configured correctly or the port is not accessible externally. Please carefully check the configuration and redeploy. +## Community & Sponsorship -To test if the port is open, run the following command on the server: +FRP-Panel is fully open source—welcome Stars, Issues, and PRs. +If FRP-Panel brings you value, consider sponsoring the author: -```shell -python3 -m http.server 8080 -``` +- Email: me@vaala.cat -Then access in the browser: `http://IP:8080` (you can replace Port with any Port you want) +Sponsored by [NodeSupport](https://github.com/NodeSeekDev/NodeSupport) -### Docker +
+ + + +
-Note⚠️: The startup commands for client and server may change as the project is updated. Although backward compatibility will be considered during project iterations, it is still difficult to fully adapt. Therefore, the startup commands for client and server should be generated from the master. +## Project Status -- master +[![Star History](https://api.star-history.com/svg?repos=vaalacat/frp-panel&type=Date)](https://www.star-history.com/#vaalacat/frp-panel&Date) -Here's the translated guidance for running the Docker command: +--- -```bash -# Recommended -# Change MASTER_RPC_HOST to the external IP of your server -# Be careful not to leak APP_GLOBAL_SECRET, it's generated by the Master for both the client and server -docker run -d \ - --network=host \ - --restart=unless-stopped \ - -v /opt/frp-panel:/data \ - -e APP_GLOBAL_SECRET=your_secret \ - -e MASTER_RPC_HOST=0.0.0.0 \ - vaalacat/frp-panel - -# Alternatively -# Remember to remove comments when running the command -docker run -d -p 9000:9000 \ # API console port - -p 9001:9001 \ # RPC port - -p 7000:7000 \ # FRPS port - -p 20000-20050:20000-20050 \ # Reserved ports for FRPS - --restart=unless-stopped \ - -v /opt/frp-panel:/data \ # Data storage location - -e APP_GLOBAL_SECRET=your_secret \ # Be careful not to leak the Master's secret, it's generated by the Master for both the client and server - -e MASTER_RPC_HOST=0.0.0.0 \ # Change this to the external IP of your server - vaalacat/frp-panel -``` - -- client - -```bash -docker run -d \ - --network=host \ - --restart=unless-stopped \ - vaalacat/frp-panel client -s xxxx -i xxxx -a xxxx -r 127.0.0.1 -c 9001 -p 9000 -e http # Copy the parameters from the master WebUI -``` - -- server - -```bash -docker run -d \ - --network=host \ - --restart=unless-stopped \ - vaalacat/frp-panel server -s xxxx -i xxxx -a xxxx -r 127.0.0.1 -c 9001 -p 9000 -e http # Copy the parameters from the master WebUI -``` - -### Direct Run (Linux) - -- master - -Note: Modify the IP - -```bash -APP_GLOBAL_SECRET=your_secret MASTER_RPC_HOST=0.0.0.0 frp-panel master -``` - -- client - -```bash -frp-panel client -s xxxx -i xxxx -a xxxx -r 127.0.0.1 -c 9001 -p 9000 -e http # Copy the parameters from the master WebUI -``` - -- server - -```bash -frp-panel server -s xxxx -i xxxx -a xxxx -r 127.0.0.1 -c 9001 -p 9000 -e http # Copy the parameters from the master WebUI -``` - -### Direct Run (Windows) - -In the same folder as the downloaded executable, create a `.env` file (note that there should be no file extension), then enter the following content and save it before running the corresponding command. Note that the corresponding parameters for client and server need to be copied from the web page. - -- master: `frp-panel-amd64.exe master` - -``` -APP_GLOBAL_SECRET=your_secret -MASTER_RPC_HOST=IP -DB_DSN=data.db -``` - -For client and server, use the parameters copied from the master WebUI. - -- client: `frp-panel-amd64.exe client -s xxxx -i xxxx -a xxxx -r 127.0.0.1 -c 9001 -p 9000 -e http # Copy the parameters from the master WebUI` - -- server: `frp-panel-amd64.exe server -s xxxx -i xxxx -a xxxx -r 127.0.0.1 -c 9001 -p 9000 -e http # Copy the parameters from the master WebUI` - -### Tunnel Advanced Mode Configuration - -This panel is fully compatible with frp's original `json` format configuration. You only need to paste the configuration file content into the advanced mode editor for the server/client, and then update it. For detailed usage, please refer to: [frp documentation](https://gofrp.org/docs/features/common/configure/) - -### Program Startup Configuration File - -The program will read the contents of the following files in order as the configuration file: `.env`, `/etc/frpp/.env` - -### Service Management - -If you are using the installation script provided by the panel, systemd is used for Linux control, and frpp.exe is used for Windows control. - -Examples of using Linux after installation: - -```bash -systemctl stop frpp -systemctl start frpp -``` - -Examples of using Windows after installation: - -``` -C:/frpp/frpp.exe start -C:/frpp/frpp.exe stop -C:/frpp/frpp.exe uninstall -``` - -## Project Development Guide - -### Platform Architecture Design - -After choosing the tech stack, the next step is to design the program architecture. As mentioned in the background, frp itself has frpc and frps (client and server), these two roles are indispensable. Then we need to add something new to manage them, so frp-panel introduces a new master role. The master will be responsible for managing various frpc and frps, as well as centrally storing configuration files and connection information. - -Next, we have frpc and frps. The original version requires writing configuration files on both sides. Since the original version already supports this, we don't need to follow the original approach. We will directly not support configuration files, and all configurations must be obtained from the master. - -In addition, we also need to consider the compatibility with the original version. The client/server of frp-panel must be able to connect to the official frpc/frps service. In this way, both configuration file and non-configuration file modes can work perfectly. -Overall, the architecture is quite simple. - -![arch](docs/public/images/arch.png) - -### Development - -The project includes three roles: - -1. Master: The control node, accepts requests from the frontend and is responsible for managing Client and Server. -2. Server: The server side, controlled by the control node, responsible for providing services to clients, including frps and rpc (for connecting to the Master) services. -3. Client: The client side, controlled by the control node, including frpc and rpc (for connecting to the Master) services. - -Next, we will provide the functionality of each package in the project: - -``` -. -|-- biz # Main business logic -| |-- client # Client logic (here referring to the frp-panel client) -| |-- master # frp-panel control plane, responsible for handling frontend requests, and using rpc to manage frp-panel's server and client -| | |-- auth # Authentication module, including user authentication and client authentication -| | |-- client # Client module, including various APIs for the frontend to manage clients -| | |-- server # Server module, including various APIs for the frontend to manage servers -| | `-- user # User module, including user management, user information retrieval, etc. -| `-- server # Server logic -|-- cache # Cache, used to store frps authentication tokens -|-- cmd # Command line entry, where the main function is located, responsible for starting various modules as needed -|-- common -|-- conf -|-- dao # Data access object, any operations related to the database will call this library -|-- doc # Documentation -|-- idl # IDL definitions -|-- middleware # API middleware, including JWT and context-related, used to process API requests. After authentication passes, user information will be injected into the context and can be obtained through the common package. -|-- models # Database models, used to define database tables. Also includes entity definitions. -|-- pb # Generated protobuf pb files -|-- rpc # Location of various rpcs, including the logic for Client/Server to call Master, as well as the logic for Master to use Stream to call Client and Server -|-- services # Various modules that need to run persistently in memory, this package can manage the running/stopping of various services -| |-- api # API service, requires an external ginRouter to run -| |-- client # frp client, i.e., frpc, can control various configurations/start and stop of frpc -| |-- master # Master service, including the rpc server definition, after receiving an rpc request, it will call the biz package to handle the logic -| |-- rpcclient # Stateful rpc client, because the rpc clients don't have public IP addresses, the rpcclient will call the master's stream long-connection rpc when starting, and after the connection is established, the Master and Client communicate through this package -| `-- server # frp server, i.e., frps, can control various configurations/start and stop of frps -|-- tunnel # Tunnel module, used to manage tunnels, i.e., manage frpc and frps services -|-- utils -|-- watcher # Scheduled tasks, e.g., updating configuration files every 30 seconds -`-- www - |-- api - |-- components # There is an apitest component here for testing - | `-- ui - |-- lib - | `-- pb - |-- pages - |-- public - |-- store - |-- styles - `-- types -``` - -### Debugging and Startup Methods: - -- master: `go run cmd/*.go master` - > For client and server, please copy the content from the master webui -- client: `go run cmd/*.go client -i -s ` -- server: `go run cmd/*.go server -i -s ` - -The project configuration file will read the .env file in the current folder by default. The project includes a sample configuration file, which can be modified according to your needs. - -Detailed architecture call diagram: - -![structure](docs/public/images/callvis.svg) - -### Core Configuration Explanation - -[settings.go](conf/settings.go) -This file contains detailed explanations of the configuration parameters. Please refer to this file if you need to further modify the configuration. - -## Screenshots - -### Index Page -![Index Page](docs/public/images/en_index.png) - -### Server List -![Server List](docs/public/images/en_server_list.png) - -### Server Edit -![Server Edit](docs/public/images/en_server_edit.png) - -### Server Edit Advanced -![Server Edit Advanced](docs/public/images/en_server_edit_adv.png) - -### Client List -![Client List](docs/public/images/en_client_list.png) - -### Client Edit -![Client Edit](docs/public/images/en_client_edit.png) - -### Client Edit Advanced -![Client Edit Advanced](docs/public/images/en_client_edit_adv.png) - -### Client Stats -![Client Stats](docs/public/images/en_client_stats.png) - -### Realtime Log -![Realtime Log](docs/public/images/en_realtime_log.png) - -### Remote Console -![Remote Console](docs/public/images/en_remote_console.png) +For more deployment, usage, and configuration details, see the Wiki → [FRP-Panel Wiki](https://vaala.cat/frp-panel/en/) \ No newline at end of file diff --git a/README_zh.md b/README_zh.md index ff0cf58..422c66f 100644 --- a/README_zh.md +++ b/README_zh.md @@ -1,32 +1,40 @@ -> 详细使用文档：[FRP-Panel WiKi](https://vaala.cat/frp-panel) -> -> 博客开发记录: [https://vaala.cat/posts/frp-panel-doc/](https://vaala.cat/posts/frp-panel-doc/) - -QQ交流群: 830620423 - # FRP-Panel -[English Version](README.md) | [中文文档](README_zh.md) +FRP-Panel 是一款基于 FRP 的可视化管理面板，提供中心化配置、统一凭证、动态调度和边缘 Worker 支持，让内网穿透和服务暴露更简单、更安全、更高效。 +[详细使用文档 (Wiki)](https://vaala.cat/frp-panel) | [Blog 开发记录](https://vaala.cat/posts/frp-panel-doc/) | [截图/视频展示](https://vaala.cat/posts/frp-panel-doc/screenshots) | QQ 群：830620423 + +中文文档 | [English](./README.md) + +
VaalaCat%2Ffrp-panel | Trendshift +
-我们的目标就是做一个： -- 客户端配置可中心化管理 -- 多服务端配置管理 -- 可视化配置界面 -- 简化运行所需要的配置 -- 支持Cloudflare边缘计算Worker +## 核心优势 -的更强更完善的 frp！ +| 优势 | 描述 | +|:--------------------------|:------------------------------------------------------------| +| 中央化配置 | 所有客户端/服务端配置由 Master 管理，无需手动编辑 JSON 文件 | +| 多节点统一管理 | 支持任意数量的 frpc（客户端）与 frps（服务端）节点集中监控与调度 | +| 可视化界面 | Web UI 一键创建、编辑、监控隧道和Worker，实时日志与统计一目了然 | +| 简化凭证分发 | 自动生成并分发启动命令，无须手动传参 | +| 边缘 Worker 自部署 | 在 Client 上部署自定义 Worker，Server 将其暴露到公网，Master 可实时调整配置 | -> Demo Video: [demo Video](./docs/public/images/frp-panel-demo.mp4) +## 架构概览 -![](./docs/public/images/frp-panel-demo.gif) +![arch](docs/public/images/arch.png) -## 赞助者们 +1. **Master** – 集中管理与鉴权，要求所有 Server 和 Client 可访问； +2. **Server** – 承载业务流量，作为公网入口，为 Client 提供服务； +3. **Client** – 内网代理，支持部署 Worker； -frp-panel 是一个完全自由开源的项目，依赖作者用爱发电写代码。如果你愿意支持作者开发，请考虑赞助 VaalaCat (Email：`me#vaala.cat`, replace # with @) +## 社区与赞助 + +本项目完全开源，欢迎 Star、Issues、PR。 +若 FRP-Panel 为您带来价值，欢迎赞助作者： + +- 邮箱：me@vaala.cat [NodeSupport](https://github.com/NodeSeekDev/NodeSupport) 赞助了该项目 @@ -36,293 +44,10 @@ frp-panel 是一个完全自由开源的项目，依赖作者用爱发电写代
-## 项目使用说明 +## 项目状态 -frp-panel 可选 docker 和直接运行模式部署，直接部署请到 release 下载文件：[release](https://github.com/VaalaCat/frp-panel/releases) +[![Star History](https://api.star-history.com/svg?repos=vaalacat/frp-panel&type=Date)](https://www.star-history.com/#vaalacat/frp-panel&Date) -注意：二进制有两种，一种是仅客户端，一种是全功能可执行文件，客户端版只能执行 client 命令(无需 client 参数) +--- -客户端版的名字会带有 client 标识 - -启动过后默认访问地址为 `http://IP:9000` - -默认第一个注册的用户是管理员。且默认不开放注册多用户，如果需要，请在 Master 启动命令或配置文件中添加参数：`APP_ENABLE_REGISTER=true` - -启动后在服务端列表中会有一个default，如果运行信息为“不在线”且为红色，则说明您的 `MASTER_RPC_HOST` 启动环境变量没有配置正确或端口外部访问不成功，请仔细检查配置重新部署。 - -测试端口是否开放的方法，在服务器上运行： - -```shell -python3 -m http.server 8080 -``` - -然后在浏览器中访问：`http://IP:8080` (端口可以换成任意你想测试的端口)，访问成功则为端口开放 - -程序的默认存储数据路径和程序文件同目录，如需修改请参考下方的配置表格 - -## Star History - -[![Star History Chart](https://api.star-history.com/svg?repos=vaalacat/frp-panel&type=Date)](https://www.star-history.com/#vaalacat/frp-panel&Date) - -### docker - -注意 ⚠️：client 和 server 的启动指令可能会随着项目更新而改变，虽然在项目迭代时会注意前后兼容，但仍难以完全适配，因此 client 和 server 的启动指令以 master 生成为准 - -- master - -```bash -# 推荐 -# MASTER_RPC_HOST要改成你服务器的外部IP -# APP_GLOBAL_SECRET注意不要泄漏，客户端和服务端的是通过Master生成的 -docker run -d \ - --network=host \ - --restart=unless-stopped \ - -v /opt/frp-panel:/data \ - -e APP_GLOBAL_SECRET=your_secret \ - -e MASTER_RPC_HOST=0.0.0.0 \ - vaalacat/frp-panel -# 或者 -# 运行时记得删除命令中的中文 -docker run -d -p 9000:9000 \ # API控制台端口 - -p 9001:9001 \ # rpc端口 - -p 7000:7000 \ # frps 端口 - -p 20000-20050:20000-20050 \ # 给frps预留的端口 - --restart=unless-stopped \ - -v /opt/frp-panel:/data \ # 数据存储位置 - -e APP_GLOBAL_SECRET=your_secret \ # Master的secret注意不要泄漏，客户端和服务端的是通过Master生成的 - -e MASTER_RPC_HOST=0.0.0.0 \ # 这里要改成你服务器的外部IP - vaalacat/frp-panel -``` - -- client - -```bash -docker run -d \ - --network=host \ - --restart=unless-stopped \ - vaalacat/frp-panel client -s xxxx -i xxxx -a xxxx -r 127.0.0.1 -c 9001 -p 9000 -e http # 在master WebUI复制的参数 -``` - -- server - -```bash -docker run -d \ - --network=host \ - --restart=unless-stopped \ - vaalacat/frp-panel server -s xxxx -i xxxx -a xxxx -r 127.0.0.1 -c 9001 -p 9000 -e http # 在master WebUI复制的参数 -``` - -### 直接运行(Linux) - -- master - -注意修改 IP - -```bash -APP_GLOBAL_SECRET=your_secret MASTER_RPC_HOST=0.0.0.0 frp-panel master -``` - -- client - -```bash -frp-panel client -s xxxx -i xxxx -a xxxx -r 127.0.0.1 -c 9001 -p 9000 -e http # 在master WebUI复制的参数 -``` - -- server - -```bash -frp-panel server -s xxxx -i xxxx -a xxxx -r 127.0.0.1 -c 9001 -p 9000 -e http # 在master WebUI复制的参数 -``` - -### 直接运行(Windows) - -在下载的可执行文件同名文件夹下创建一个 `.env` 文件(注意不要有后缀名)，然后输入以下内容保存后运行对应命令，注意，client 和 server 的对应参数需要在 web 页面复制 - -``` -APP_GLOBAL_SECRET=your_secret -MASTER_RPC_HOST=IP -DB_DSN=data.db -``` - -- master: `frp-panel-amd64.exe master` - -client 和 server 要使用在 master WebUI 复制的参数 - -- client: `frp-panel-amd64.exe client -s xxxx -i xxxx -a xxxx -r 127.0.0.1 -c 9001 -p 9000 -e http # 在master WebUI复制的参数` - -- server: `frp-panel-amd64.exe server -s xxxx -i xxxx -a xxxx -r 127.0.0.1 -c 9001 -p 9000 -e http # 在master WebUI复制的参数` - -### 隧道高级模式配置 - -本面板完全兼容 frp 原本的`json`格式配置，仅需要将配置文件内容粘贴到服务端/客户端高级模式编辑框内，更新即可，详细的使用参考：[frp 文档](https://gofrp.org/zh-cn/docs/features/common/configure/) - -### 程序启动配置文件 - -程序会按顺序读取以下文件内容作为配置文件：`.env`,`/etc/frpp/.env` - -### 服务管理 - -如果您使用的是面板自带的安装脚本，对于 Linux 使用 systemd 控制，对于 Windows 使用 本程序 控制 - -Linux 安装后使用示例： - -```bash -systemctl stop frpp -systemctl start frpp -``` - -Windows 安装后使用示例： - -``` -C:/frpp/frpp.exe stop -C:/frpp/frpp.exe start -C:/frpp/frpp.exe uninstall -``` - -### 配置说明 - -| 类型 | 环境变量名 | 默认值 | 描述 | -|--------|-------------------------------------|--------------------|----------------------------------------------------------------| -| string | `APP_SECRET` | - | 应用密钥，用于客户端和服务器的和Master的通信加密 | -| string | `APP_GLOBAL_SECRET` | `frp-panel` | 全局密钥，用于管理生成密钥，需妥善保管 | -| int | `APP_COOKIE_AGE` | `86400` | Cookie 的有效期（秒），默认值为 1 天 | -| string | `APP_COOKIE_NAME` | `frp-panel-cookie` | Cookie 名称 | -| string | `APP_COOKIE_PATH` | `/` | Cookie 路径 | -| string | `APP_COOKIE_DOMAIN` | - | Cookie 域 | -| bool | `APP_COOKIE_SECURE` | `false` | Cookie 是否安全 | -| bool | `APP_COOKIE_HTTP_ONLY` | `true` | Cookie 是否仅限 HTTP | -| bool | `APP_ENABLE_REGISTER` | `false` | 是否启用注册，仅允许第一个管理员注册 | -| int | `MASTER_API_PORT` | `9000` | 主节点 API 端口 | -| string | `MASTER_API_HOST` | - | 主节点域名，可以在反向代理和CDN后 | -| string | `MASTER_API_SCHEME` | `http` | 主节点 API 协议（注意，这里不影响主机行为，设置为https只是为了方便复制客户端启动命令，HTTPS需要自行反向代理）| -| int | `MASTER_CACHE_SIZE` | `10` | 缓存大小（MB） | -| string | `MASTER_RPC_HOST` | `127.0.0.1` | Master节点公共 IP 或域名 | -| int | `MASTER_RPC_PORT` | `9001` | Master节点 RPC 端口 | -| bool | `MASTER_COMPATIBLE_MODE` | `false` | 兼容模式，用于官方 frp 客户端 | -| string | `MASTER_INTERNAL_FRP_SERVER_HOST` | - | Master内置 frps 服务器主机，用于客户端连接 | -| int | `MASTER_INTERNAL_FRP_SERVER_PORT` | `9002` | Master内置 frps 服务器端口，用于客户端连接 | -| string | `MASTER_INTERNAL_FRP_AUTH_SERVER_HOST` | `127.0.0.1` | Master内置 frps 认证服务器主机 | -| int | `MASTER_INTERNAL_FRP_AUTH_SERVER_PORT` | `8999` | Master内置 frps 认证服务器端口 | -| string | `MASTER_INTERNAL_FRP_AUTH_SERVER_PATH` | `/auth` | Master内置 frps 认证服务器路径 | -| int | `SERVER_API_PORT` | `8999` | 服务器 API 端口 | -| string | `DB_TYPE` | `sqlite3` | 数据库类型，如 mysql postgres 或 sqlite3 等 | -| string | `DB_DSN` | `data.db` | 数据库 DSN，默认使用sqlite3，数据默认存储在可执行文件同目录下，对于 sqlite 是路径，其他数据库为 DSN，参见 [MySQL DSN](https://github.com/go-sql-driver/mysql#dsn-data-source-name) | -| string | `CLIENT_ID` | - | 客户端 ID | -| string | `CLIENT_SECRET` | - | 客户端密钥 | - -## 项目开发指南 - -### 平台架构设计 - -技术栈选好了，下一步就是要设计程序的架构。在刚刚背景里说的那样，frp 本身有 frpc 和 frps（客户端和服务端），这两个角色肯定是必不可少了。然后我们还要新增一个东西去管理它们，所以 frp-panel 新增了一个 master 角色。master 会负责管理各种 frpc 和 frps，中心化的存储配置文件和连接信息。 - -然后是 frpc 和 frps。原版是需要在两边分别写配置文件的。那么既然原版已经支持了，就不用在走原版的路子，我们直接不支持配置文件，所有的配置都必须从 master 获取。 - -其次还要考虑到与原版的兼容问题，frp-panel 的客户端/服务端都必须要能连上官方 frpc/frps 服务。这样的话就可以做到配置文件/不要配置文件都能完美工作了。 -总的说来架构还是很简单的。 - -![arch](docs/public/images/arch.png) - -### 开发 - -项目包含三个角色 - -1. Master: 控制节点，接受来自前端的请求并负责管理 Client 和 Server -2. Server: 服务端，受控制节点控制，负责对客户端提供服务，包含 frps 和 rpc(用于连接 Master)服务 -3. Client: 客户端，受控制节点控制，包含 frpc 和 rpc(用于连接 Master)服务 - -接下来给出一个项目中各个包的功能 - -``` -. -|-- biz # 主要业务逻辑 -| |-- client # 客户端逻辑（这里指的是frp-panel的客户端） -| |-- master # frp-panel 控制平面，负责处理前端请求，并且使用rpc管理frp-panel的server和client -| | |-- auth # 认证模块，包含用户认证和客户端认证 -| | |-- client # 客户端模块，包含前端管理客户端的各种API -| | |-- server # 服务端模块，包含前端管理服务端的各种API -| | `-- user # 用户模块，包含用户管理、用户信息获取等 -| `-- server # 服务端逻辑（这里指的是frp-panel的服务端） -|-- cache # 缓存，用于存储frps的认证token -|-- cmd # 命令行入口，main函数的所在地，负责按需启动各个模块 -|-- common -|-- conf -|-- dao # data access object，任何和数据库相关的操作会调用这个库 -|-- doc # 文档 -|-- idl # idl定义 -|-- middleware # api的中间件，包含JWT和context相关，用于处理api请求，鉴权通过后会把用户信息注入到context，可以通过common包获取 -|-- models # 数据库模型，用于定义数据库表。同时包含实体定义 -|-- pb # protobuf生成的pb文件 -|-- rpc # 各种rpc的所在地，包含Client/Server调用Master的逻辑，也包含Master使用Stream调用Client和Server的逻辑 -|-- services # 各种需要在内存中持久运行的模块，这个包可以管理各个服务的运行/停止 -| |-- api # api服务，运行需要外部传入一个ginRouter -| |-- client # frp的客户端，即frpc，可以控制frpc的各种配置/开始与停止 -| |-- master # master服务，包含rpc的服务端定义，接收到rpc请求后会调用biz包处理逻辑 -| |-- rpcclient # 有状态的rpc客户端，因为rpc的client都没有公网ip，因此在rpc client启动时会调用master的stream长连接rpc，建立连接后Master和Client通过这个包通信 -| `-- server # frp的服务端，即frps，可以控制frps的各种配置/开始与停止 -|-- tunnel # tunnel模块，用于管理tunnel，也就是管理frpc和frps服务 -|-- utils -|-- watcher # 定时运行的任务，比如每30秒更新一次配置文件 -`-- www - |-- api - |-- components # 这里面有一个apitest组件用于测试 - | `-- ui - |-- lib - | `-- pb - |-- pages - |-- public - |-- store - |-- styles - `-- types - -``` - -### 调试启动方式： - -- master: `go run cmd/*.go master` - > client 和 server 的具体参数请复制 master webui 中的内容 -- client: `go run cmd/*.go client -i -s ` -- server: `go run cmd/*.go server -i -s ` - -项目配置文件会默认读取当前文件夹下的.env 文件，项目内置了样例配置文件，可以按照自己的需求进行修改 - -详细架构调用图 - -![structure](docs/public/images/callvis.svg) - -### 本体配置说明 - -[settings.go](conf/settings.go) -这里有详细的配置参数解释，需要进一步修改配置请参考该文件 - -## 截图展示 - -### 首页 -![首页](docs/public/images/cn_index.png) - -### 服务器列表 -![服务器列表](docs/public/images/cn_server_list.png) - -### 服务器编辑 -![服务器编辑](docs/public/images/cn_server_edit.png) - -### 服务器高级编辑 -![服务器高级编辑](docs/public/images/cn_server_edit_adv.png) - -### 客户端列表 -![客户端列表](docs/public/images/cn_client_list.png) - -### 客户端编辑 -![客户端编辑](docs/public/images/cn_client_edit.png) - -### 客户端高级编辑 -![客户端高级编辑](docs/public/images/cn_client_edit_adv.png) - -### 客户端统计 -![客户端统计](docs/public/images/cn_client_stats.png) - -### 实时日志 -![实时日志](docs/public/images/cn_realtime_log.png) - -### 远程控制台 -![远程控制台](docs/public/images/cn_remote_console.png) +*更多部署、使用与配置细节，请移步 Wiki → [FRP-Panel WiKi](https://vaala.cat/frp-panel)* diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts index ca3f4c3..748342a 100644 --- a/docs/.vitepress/config.mts +++ b/docs/.vitepress/config.mts @@ -1,23 +1,31 @@ -import { defineConfig } from 'vitepress' -import { zhConfig } from './config/zh' -import { enConfig } from './config/en' +import { defineConfig } from "vitepress"; +import { zhConfig } from "./config/zh"; +import { enConfig } from "./config/en"; // https://vitepress.dev/reference/site-config export default defineConfig({ - base: '/frp-panel/', - locales: { - root: { - label: '简体中文', - ...zhConfig + base: "/frp-panel/", + locales: { + root: { + label: "简体中文", + ...zhConfig, + }, + en: { + label: "English", + ...enConfig, + }, }, - en: { - label: 'English', - ...enConfig - } - }, - title: "Frp-Panel WIKI", - description: "Wiki of vaalacat's wonderful frp-panel", - themeConfig: { - // https://vitepress.dev/reference/default-theme-config - } -}) + title: "Frp-Panel WIKI", + description: "Wiki of vaalacat's wonderful frp-panel", + themeConfig: { + // https://vitepress.dev/reference/default-theme-config + }, + vite: { + server: { + port: 5467, + strictPort: true, + host: "0.0.0.0", + allowedHosts: true, + }, + }, +}); diff --git a/docs/.vitepress/config/en.ts b/docs/.vitepress/config/en.ts index 671dab7..b38913d 100644 --- a/docs/.vitepress/config/en.ts +++ b/docs/.vitepress/config/en.ts @@ -1,25 +1,40 @@ -import type { DefaultTheme, LocaleSpecificConfig } from 'vitepress' +import type { DefaultTheme, LocaleSpecificConfig } from "vitepress"; export const enConfig: LocaleSpecificConfig = { themeConfig: { nav: [ - { text: 'Home', link: '/en/' }, - { text: 'Source Code', link: 'https://github.com/vaalacat/frp-panel' } + { text: "Home", link: "/en/" }, + { text: "Source Code", link: "https://github.com/vaalacat/frp-panel" }, ], sidebar: [ { - text: 'Quick Start', + text: "Quick Start", collapsed: true, - link: '/en/quick-start', + link: "/en/quick-start", items: [ - { text: 'Master Deployment', link: '/en/deploy-master' }, - { text: 'Server Deployment', link: '/en/deploy-server' }, - { text: 'Client Deployment', link: '/en/deploy-client' }, - ] - } + { text: "Master Deployment", link: "/en/deploy-master" }, + { text: "Server Deployment", link: "/en/deploy-server" }, + { text: "Client Deployment", link: "/en/deploy-client" }, + ], + }, + { + text: "Configuration", + collapsed: false, + link: "/en/all-configs", + }, + { + text: "Contribution Guide", + collapsed: false, + link: "/en/contribute", + }, + { + text: "Screenshots", + collapsed: false, + link: "/en/screenshots", + }, ], socialLinks: [ - { icon: 'github', link: 'https://github.com/vaalacat/frp-panel' } - ] - } -} \ No newline at end of file + { icon: "github", link: "https://github.com/vaalacat/frp-panel" }, + ], + }, +}; diff --git a/docs/.vitepress/config/zh.ts b/docs/.vitepress/config/zh.ts index 5bf13c3..3b7895c 100644 --- a/docs/.vitepress/config/zh.ts +++ b/docs/.vitepress/config/zh.ts @@ -1,27 +1,42 @@ -import type { DefaultTheme, LocaleSpecificConfig } from 'vitepress' +import type { DefaultTheme, LocaleSpecificConfig } from "vitepress"; export const zhConfig: LocaleSpecificConfig = { themeConfig: { nav: [ - { text: '首页', link: '/' }, - { text: '源码', link: 'https://github.com/vaalacat/frp-panel' } + { text: "首页", link: "/" }, + { text: "源码", link: "https://github.com/vaalacat/frp-panel" }, ], sidebar: [ { - text: '快速开始', - collapsed: true, - link: '/quick-start', + text: "快速开始", + collapsed: false, + link: "/quick-start", items: [ - { text: 'Master 部署', link: '/deploy-master' }, - { text: 'Server 部署', link: '/deploy-server' }, - { text: 'Client 部署', link: '/deploy-client' }, - ] - } + { text: "Master 部署", link: "/deploy-master" }, + { text: "Server 部署", link: "/deploy-server" }, + { text: "Client 部署", link: "/deploy-client" }, + ], + }, + { + text: "配置说明", + collapsed: false, + link: "/all-configs", + }, + { + text: "贡献指南", + collapsed: false, + link: "/contribute", + }, + { + text: "截图展示", + collapsed: false, + link: "/screenshots", + }, ], socialLinks: [ - { icon: 'github', link: 'https://github.com/vaalacat/frp-panel' } - ] - } -} \ No newline at end of file + { icon: "github", link: "https://github.com/vaalacat/frp-panel" }, + ], + }, +}; diff --git a/docs/all-configs.md b/docs/all-configs.md new file mode 100644 index 0000000..55ef3ff --- /dev/null +++ b/docs/all-configs.md @@ -0,0 +1,44 @@ +# 配置说明 + +## frp隧道高级模式配置 + +本面板完全兼容 frp 原本的`json`格式配置，仅需要将配置文件内容粘贴到服务端/客户端高级模式编辑框内，更新即可，详细的使用参考：[frp 文档](https://gofrp.org/zh-cn/docs/features/common/configure/) + +## 程序启动配置文件 + +程序会按顺序读取以下文件内容作为配置文件：`.env`,`/etc/frpp/.env` + +## 程序配置说明 + +> 文档可能有点老。。。 +> +> 完整的最新配置参考这个文件：[settings.go](https://github.com/VaalaCat/frp-panel/blob/main/conf/settings.go) + +| 类型 | 环境变量名 | 默认值 | 描述 | +|--------|-------------------------------------|--------------------|----------------------------------------------------------------| +| string | `APP_SECRET` | - | 应用密钥，用于客户端和服务器的和Master的通信加密 | +| string | `APP_GLOBAL_SECRET` | `frp-panel` | 全局密钥，用于管理生成密钥，需妥善保管 | +| int | `APP_COOKIE_AGE` | `86400` | Cookie 的有效期（秒），默认值为 1 天 | +| string | `APP_COOKIE_NAME` | `frp-panel-cookie` | Cookie 名称 | +| string | `APP_COOKIE_PATH` | `/` | Cookie 路径 | +| string | `APP_COOKIE_DOMAIN` | - | Cookie 域 | +| bool | `APP_COOKIE_SECURE` | `false` | Cookie 是否安全 | +| bool | `APP_COOKIE_HTTP_ONLY` | `true` | Cookie 是否仅限 HTTP | +| bool | `APP_ENABLE_REGISTER` | `false` | 是否启用注册，仅允许第一个管理员注册 | +| int | `MASTER_API_PORT` | `9000` | 主节点 API 端口 | +| string | `MASTER_API_HOST` | - | 主节点域名，可以在反向代理和CDN后 | +| string | `MASTER_API_SCHEME` | `http` | 主节点 API 协议（注意，这里不影响主机行为，设置为https只是为了方便复制客户端启动命令，HTTPS需要自行反向代理）| +| int | `MASTER_CACHE_SIZE` | `10` | 缓存大小（MB） | +| string | `MASTER_RPC_HOST` | `127.0.0.1` | Master节点公共 IP 或域名 | +| int | `MASTER_RPC_PORT` | `9001` | Master节点 RPC 端口 | +| bool | `MASTER_COMPATIBLE_MODE` | `false` | 兼容模式，用于官方 frp 客户端 | +| string | `MASTER_INTERNAL_FRP_SERVER_HOST` | - | Master内置 frps 服务器主机，用于客户端连接 | +| int | `MASTER_INTERNAL_FRP_SERVER_PORT` | `9002` | Master内置 frps 服务器端口，用于客户端连接 | +| string | `MASTER_INTERNAL_FRP_AUTH_SERVER_HOST` | `127.0.0.1` | Master内置 frps 认证服务器主机 | +| int | `MASTER_INTERNAL_FRP_AUTH_SERVER_PORT` | `8999` | Master内置 frps 认证服务器端口 | +| string | `MASTER_INTERNAL_FRP_AUTH_SERVER_PATH` | `/auth` | Master内置 frps 认证服务器路径 | +| int | `SERVER_API_PORT` | `8999` | 服务器 API 端口 | +| string | `DB_TYPE` | `sqlite3` | 数据库类型，如 mysql postgres 或 sqlite3 等 | +| string | `DB_DSN` | `data.db` | 数据库 DSN，默认使用sqlite3，数据默认存储在可执行文件同目录下，对于 sqlite 是路径，其他数据库为 DSN，参见 [MySQL DSN](https://github.com/go-sql-driver/mysql#dsn-data-source-name) | +| string | `CLIENT_ID` | - | 客户端 ID | +| string | `CLIENT_SECRET` | - | 客户端密钥 | diff --git a/docs/contribute.md b/docs/contribute.md new file mode 100644 index 0000000..cdcdd8d --- /dev/null +++ b/docs/contribute.md @@ -0,0 +1,90 @@ +# 贡献指南 + +## 文档贡献指南 + +请fork本仓库，修改仓库目录下 `docs` 文件夹中的内容 + +## 项目开发指南 + +### 平台架构设计 + +技术栈选好了，下一步就是要设计程序的架构。在刚刚背景里说的那样，frp 本身有 frpc 和 frps（客户端和服务端），这两个角色肯定是必不可少了。然后我们还要新增一个东西去管理它们，所以 frp-panel 新增了一个 master 角色。master 会负责管理各种 frpc 和 frps，中心化的存储配置文件和连接信息。 + +然后是 frpc 和 frps。原版是需要在两边分别写配置文件的。那么既然原版已经支持了，就不用在走原版的路子，我们直接不支持配置文件，所有的配置都必须从 master 获取。 + +其次还要考虑到与原版的兼容问题，frp-panel 的客户端/服务端都必须要能连上官方 frpc/frps 服务。这样的话就可以做到配置文件/不要配置文件都能完美工作了。 +总的说来架构还是很简单的。 + +![arch](public/images/arch.png) + +### 开发 + +项目包含三个角色 + +1. Master: 控制节点，接受来自前端的请求并负责管理 Client 和 Server +2. Server: 服务端，受控制节点控制，负责对客户端提供服务，包含 frps 和 rpc(用于连接 Master)服务 +3. Client: 客户端，受控制节点控制，包含 frpc 和 rpc(用于连接 Master)服务 + +接下来给出一个项目中各个包的功能 + +``` +. +|-- biz # 主要业务逻辑 +| |-- client # 客户端逻辑（这里指的是frp-panel的客户端） +| |-- master # frp-panel 控制平面，负责处理前端请求，并且使用rpc管理frp-panel的server和client +| | |-- auth # 认证模块，包含用户认证和客户端认证 +| | |-- client # 客户端模块，包含前端管理客户端的各种API +| | |-- server # 服务端模块，包含前端管理服务端的各种API +| | `-- user # 用户模块，包含用户管理、用户信息获取等 +| `-- server # 服务端逻辑（这里指的是frp-panel的服务端） +|-- cache # 缓存，用于存储frps的认证token +|-- cmd # 命令行入口，main函数的所在地，负责按需启动各个模块 +|-- common +|-- conf +|-- dao # data access object，任何和数据库相关的操作会调用这个库 +|-- doc # 文档 +|-- idl # idl定义 +|-- middleware # api的中间件，包含JWT和context相关，用于处理api请求，鉴权通过后会把用户信息注入到context，可以通过common包获取 +|-- models # 数据库模型，用于定义数据库表。同时包含实体定义 +|-- pb # protobuf生成的pb文件 +|-- rpc # 各种rpc的所在地，包含Client/Server调用Master的逻辑，也包含Master使用Stream调用Client和Server的逻辑 +|-- services # 各种需要在内存中持久运行的模块，这个包可以管理各个服务的运行/停止 +| |-- api # api服务，运行需要外部传入一个ginRouter +| |-- client # frp的客户端，即frpc，可以控制frpc的各种配置/开始与停止 +| |-- master # master服务，包含rpc的服务端定义，接收到rpc请求后会调用biz包处理逻辑 +| |-- rpcclient # 有状态的rpc客户端，因为rpc的client都没有公网ip，因此在rpc client启动时会调用master的stream长连接rpc，建立连接后Master和Client通过这个包通信 +| `-- server # frp的服务端，即frps，可以控制frps的各种配置/开始与停止 +|-- tunnel # tunnel模块，用于管理tunnel，也就是管理frpc和frps服务 +|-- utils +|-- watcher # 定时运行的任务，比如每30秒更新一次配置文件 +`-- www + |-- api + |-- components # 这里面有一个apitest组件用于测试 + | `-- ui + |-- lib + | `-- pb + |-- pages + |-- public + |-- store + |-- styles + `-- types + +``` + +### 调试启动方式： + +- master: `go run cmd/*.go master` + > client 和 server 的具体参数请复制 master webui 中的内容 +- client: `go run cmd/*.go client -i -s ` +- server: `go run cmd/*.go server -i -s ` + +项目配置文件会默认读取当前文件夹下的.env 文件，项目内置了样例配置文件，可以按照自己的需求进行修改 + +详细架构调用图 + +![structure](public/images/callvis.svg) + +### 本体配置说明 + +[settings.go](https://github.com/VaalaCat/frp-panel/blob/main/conf/settings.go) +这里有详细的配置参数解释，需要进一步修改配置请参考该文件 diff --git a/docs/deploy-client.md b/docs/deploy-client.md index 5ec8c71..2cb4aca 100644 --- a/docs/deploy-client.md +++ b/docs/deploy-client.md @@ -4,6 +4,8 @@ Client 推荐使用 docker 部署 但直接部署在客户机中，可以通过远程终端直接在客户机以 root 权限执行命令，方便升级和管理。 +注意 ⚠️：client 和 server 的启动指令可能会随着项目更新而改变，虽然在项目迭代时会注意前后兼容，但仍难以完全适配，因此 client 和 server 的启动指令以 master 生成为准 + ## 准备 打开 Master 的 webui 并登录，如果没有账号，请直接注册，第一个用户即为管理员 @@ -16,38 +18,42 @@ Client 推荐使用 docker 部署 部署client之前，需要修改服务端的配置，否则客户端无法正常连接 -## 直接部署 +## 在 Linux 上部署 + +### 直接运行 + +首先在系统上创建一个专用目录 点击对应客户端的 `ID (点击查看安装命令)` 一列，弹出不同系统的安装命令，粘贴到对应终端即可安装，这里以 Linux 为例 ``` -curl -fSL https://raw.githubusercontent.com/VaalaCat/frp-panel/main/install.sh | bash -s -- client -s abc -i user.s.client1 -a 123123 -r frpp-rpc.example.com -c 9001 -p 9000 -e http +curl -fSL https://raw.githubusercontent.com/VaalaCat/frp-panel/main/install.sh | bash -s -- client -s abc -i user.c.client1 --api-url http://frpp.example.com:9000 --rpc-url grpc://frpp-rpc.example.com:9001 ``` -如果你在国内，可以增加github加速到安装脚本前 - -``` -curl -fSL https://ghfast.top/https://raw.githubusercontent.com/VaalaCat/frp-panel/main/install.sh | bash -s -- client -s abc -i user.s.client1 -a 123123 -r frpp-rpc.example.com -c 9001 -p 9000 -e http -``` - -注意，如果你使用 反向代理 TLS，需要修改这行命令类似如下： +如果你在国内，可以在WebUI中配置增加github加速到安装脚本前，以ghfast为例，配置后复制的内容可能类似下方： ```bash -curl -fSL https://ghfast.top/https://raw.githubusercontent.com/VaalaCat/frp-panel/main/install.sh | bash -s -- frp-panel client -s abc -i user.s.client1 -a 123123 -t frpp.example.com -r frpp-rpc.example.com -c 443 -p 443 -e https +curl -fSL https://ghfast.top/https://raw.githubusercontent.com/VaalaCat/frp-panel/main/install.sh | bash -s -- --github-proxy https://ghfast.top/ client -s abc -i user.c.client1 --api-url http://frpp.example.com:9000 --rpc-url grpc://frpp-rpc.example.com:9001 ``` -## Docker Compose 部署 +注意，如果你使用 反向代理 TLS，需要以 http 上游的形式，外部 443 端口代理 `master` 的 9000(API) 端口，且修改启动/安装命令类似如下： + +```bash +curl -fSL https://ghfast.top/https://raw.githubusercontent.com/VaalaCat/frp-panel/main/install.sh | bash -s -- --github-proxy https://ghfast.top/ client -s abc -i user.c.client1 --api-url https://frpp.example.com:443 --rpc-url wss://frpp.example.com:443 +``` + +### Docker Compose 部署 点击对应客户端的 `密钥 (点击查看启动命令)` 一列中的隐藏字段，复制类似的启动命令如下备用： ```bash -frp-panel client -s abc -i user.s.client1 -a 123123 -r frpp-rpc.example.com -c 9001 -p 9000 -e http +./frp-panel client -s abc -i user.c.client1 --api-url http://frpp.example.com:9000 --rpc-url grpc://frpp-rpc.example.com:9001 ``` 注意，如果你使用 反向代理 TLS，需要修改这行命令类似如下： ```bash -frp-panel client -s abc -i user.s.client1 -a 123123 -t frpp.example.com -r frpp-rpc.example.com -c 443 -p 443 -e https +./frp-panel client -s abc -i user.c.client1 --api-url https://frpp.example.com:443 --rpc-url wss://frpp.example.com:443 ``` docker-compose.yaml @@ -60,5 +66,57 @@ services: container_name: frp-panel-client network_mode: host restart: unless-stopped - command: client -s abc -i user.s.client1 -a 123123 -t frpp.example.com -r frpp-rpc.example.com -c 443 -p 443 -e https + command: client -s abc -i user.c.client1 --api-url https://frpp.example.com:443 --rpc-url wss://frpp.example.com:443 +``` + +### 安装为 systemd 服务 + +frp-panel 拥有管理 systemd 服务的能力，服务名为 `frpp`，内置了很多命令，请使用 `frp-panel --help` 查看支持的命令。这里给出一些例子： + +- 安装特定参数的 client 到 systemd （支持任意的参数，包括server） +```bash +sudo ./frp-panel install [client 参数] +# eg. frp-panel install client -s abc -i user.c.client1 --api-url https://frpp.example.com:443 --rpc-url wss://frpp.example.com:443 +``` + +- 卸载 frpp 服务 +```bash +sudo ./frp-panel uninstall +``` + +- 启动 frpp 服务 +```bash +sudo ./frp-panel start +``` + +- 停止 frpp 服务 +```bash +sudo ./frp-panel stop +``` + +- 重启 frpp 服务 +```bash +sudo ./frp-panel restart +``` + +## 在 Windows 上部署 + +### 直接运行 + +在 powershell 中，可执行文件的同目录下运行 WebUI 中复制的启动命令 + +```powershell +.\frp-panel.exe client -s abc -i user.c.client1 --api-url https://frpp.example.com:443 --rpc-url wss://frpp.example.com:443 +``` + +### 安装为服务 + +与上方 Linux 的命令一致，修改文件名，去掉sudo执行即可 + +Windows 安装后使用示例： + +``` +C:/frpp/frpp.exe stop +C:/frpp/frpp.exe start +C:/frpp/frpp.exe uninstall ``` diff --git a/docs/deploy-master.md b/docs/deploy-master.md index 0d34ea0..eef6a59 100644 --- a/docs/deploy-master.md +++ b/docs/deploy-master.md @@ -6,6 +6,10 @@ Master 推荐使用 docker 部署！不推荐直接安装到服务器中 部署后没有默认用户，注册的第一个用户即为管理员，为了安全，默认不开启多用户注册 +程序的默认存储数据路径和程序文件同目录，如需修改请参考配置表格 + +重要！：如果你想只部署 master，同时作为 server 运行，请不要忘记启动 master 后，在 webui 的配置服务端中修改 default 的配置 + ## 前期准备 ### 服务器开放公网端口： @@ -48,7 +52,9 @@ RPC 端口也可以处理自签名 HTTPS 的 API 连接 > Content-Length: 8225 > ``` -## 方式一：Docker Compose 部署 +## 在 Linux 上部署 + +### 方式一：Docker Compose 部署 服务器需要安装docker和docker compose @@ -69,12 +75,12 @@ services: MASTER_API_PORT: 9000 MASTER_API_SCHEME: http volumes: - - ./data:/data + - ./data:/data # 数据存储位置 restart: unless-stopped command: master ``` -## 方式二：Docker 命令部署 +### 方式二：Docker 命令部署 服务器需要安装 docker，我们推荐使用 host 网络模式部署 `Master` @@ -107,7 +113,7 @@ docker run -d -p 9000:9000 \ # API控制台端口 vaalacat/frp-panel ``` -## 方式三：使用 docker 反向代理 TLS 加密部署 +### 方式三：使用 docker 反向代理 TLS 加密部署 这里我们以 [Traefik](https://traefik.io/traefik/) 为例 @@ -225,3 +231,17 @@ networks: | 代理监听地址 | 0.0.0.0 | | HTTP 监听端口 | 26999 | | 域名后缀 | frpp.example.com | + +## 在 Windows 上部署 + +### 直接运行 + +在下载的可执行文件同名文件夹下创建一个 `.env` 文件(注意不要有后缀名)，然后输入以下内容保存后运行对应命令 + +``` +APP_GLOBAL_SECRET=your_secret +MASTER_RPC_HOST=IP +DB_DSN=data.db +``` + +- master: `frp-panel-amd64.exe master` diff --git a/docs/deploy-server.md b/docs/deploy-server.md index 523db09..17fd4bb 100644 --- a/docs/deploy-server.md +++ b/docs/deploy-server.md @@ -2,9 +2,13 @@ Server 推荐使用 docker 部署！不推荐直接安装到服务器中 -> 如果只有一台公网服务器需要管理，那么使用 `master` 自带的 `default server` 即可，无需单独部署 `server` +注意 ⚠️：client 和 server 的启动指令可能会随着项目更新而改变，虽然在项目迭代时会注意前后兼容，但仍难以完全适配，因此 client 和 server 的启动指令以 master 生成为准 -## 1. 准备 +> 如果只有一台公网服务器需要管理，那么使用 `master` 自带的 `default` 服务端即可，无需单独部署 `server`，但要注意在 `master` 启动后要配置 `default` 服务端 + +## 在 Linux 上部署 + +### 1. 准备 打开 Master 的 webui 并登录，如果没有账号，请直接注册，第一个用户即为管理员 @@ -15,18 +19,18 @@ Server 推荐使用 docker 部署！不推荐直接安装到服务器中 刷新后，新的服务端会出现在列表中。点击对应服务端的`密钥 (点击查看启动命令)`一列中的隐藏字段，复制类似的启动命令如下备用： ```bash -frp-panel server -s abc -i user.s.server1 -a 123123 -r frpp-rpc.example.com -c 9001 -p 9000 -e http +frp-panel server -s abc -i user.s.server1 --api-url http://frpp.example.com:9000 --rpc-url grpc://frpp-rpc.example.com:9001 ``` -注意，如果你使用 反向代理 TLS，需要修改这行命令类似如下： +注意，如果你使用 反向代理 TLS，需要以 http 上游的形式，外部 443 端口代理 `master` 的 9000(API) 端口，且修改启动/安装命令类似如下： ```bash -frp-panel server -s abc -i user.s.server1 -a 123123 -t frpp.example.com -r frpp-rpc.example.com -c 443 -p 443 -e https +frp-panel server -s abc -i user.s.server1 --api-url https://frpp.example.com:443 --rpc-url wss://frpp.example.com:443 ``` -## 2. 程序安装 +### 2. 程序安装 -### Docker Compose 部署 +#### Docker Compose 部署 docker-compose.yaml @@ -38,13 +42,21 @@ services: container_name: frp-panel-server network_mode: host restart: unless-stopped - command: server -s abc -i user.s.server1 -a 123123 -t frpp.example.com -r frpp-rpc.example.com -c 443 -p 443 -e https + command: server -s abc -i user.s.server1 --api-url http://frpp.example.com:9000 --rpc-url grpc://frpp-rpc.example.com:9001 ``` -### 直接部署 +#### 直接运行 -如果你想要直接部署，请参考 client 部署的步骤 +如果你想要直接运行，不使用服务管理工具，请参考 client 直接运行的步骤 -## 3. 服务端配置 +#### 安装为 systemd 服务 + +请参考 client 部署 systemd 的步骤 + +### 3. 服务端配置 安装完后需要按你的网络和需求，修改服务端的配置，否则客户端无法正常连接 + +## 在 Windows 上部署 + +请参考 client 部署的步骤 diff --git a/docs/en/all-configs.md b/docs/en/all-configs.md new file mode 100644 index 0000000..3355dbf --- /dev/null +++ b/docs/en/all-configs.md @@ -0,0 +1,47 @@ +# Configuration Reference + +## Advanced frp Tunnel Configuration + +This panel fully supports frp’s original JSON configuration format. Simply paste your configuration JSON into the Server/Client **Advanced Mode** editor and save. For detailed usage, see the [frp documentation](https://gofrp.org/zh-cn/docs/features/common/configure/). + +## Startup Configuration Files + +The application loads configuration in the following order: + +1. `.env` in the working directory +2. `/etc/frpp/.env` + +## Environment Variable Reference + +> Documentation may be somewhat outdated… +> +> For the complete and latest configuration reference, see: [settings.go](https://github.com/VaalaCat/frp-panel/blob/main/conf/settings.go) + +| Type | Environment Variable | Default | Description | +|:-------|:---------------------------------------|:--------------------|:---------------------------------------------------------------------------------------------------------------| +| string | `APP_SECRET` | – | Application secret used to encrypt communication between Client, Server, and Master | +| string | `APP_GLOBAL_SECRET` | `frp-panel` | Global secret used to generate keys. Keep this value secure. | +| int | `APP_COOKIE_AGE` | `86400` | Cookie lifetime in seconds (default: 1 day) | +| string | `APP_COOKIE_NAME` | `frp-panel-cookie` | Cookie name | +| string | `APP_COOKIE_PATH` | `/` | Cookie path | +| string | `APP_COOKIE_DOMAIN` | – | Cookie domain | +| bool | `APP_COOKIE_SECURE` | `false` | Whether the cookie is marked Secure | +| bool | `APP_COOKIE_HTTP_ONLY` | `true` | Whether the cookie is HTTP-only | +| bool | `APP_ENABLE_REGISTER` | `false` | Enable user registration. Only the first user can register (administrator). | +| int | `MASTER_API_PORT` | `9000` | Master API port | +| string | `MASTER_API_HOST` | – | Master API host (can be behind a reverse proxy or CDN) | +| string | `MASTER_API_SCHEME` | `http` | Master API scheme (for client command generation; HTTPS must be handled via reverse proxy) | +| int | `MASTER_CACHE_SIZE` | `10` | Cache size in MB | +| string | `MASTER_RPC_HOST` | `127.0.0.1` | Master RPC host or public IP | +| int | `MASTER_RPC_PORT` | `9001` | Master RPC port | +| bool | `MASTER_COMPATIBLE_MODE` | `false` | Compatibility mode for official frp clients | +| string | `MASTER_INTERNAL_FRP_SERVER_HOST` | – | Host for Master’s built-in frps instance (for client connections) | +| int | `MASTER_INTERNAL_FRP_SERVER_PORT` | `9002` | Port for Master’s built-in frps instance (for client connections) | +| string | `MASTER_INTERNAL_FRP_AUTH_SERVER_HOST` | `127.0.0.1` | Host for Master’s built-in frps authentication service | +| int | `MASTER_INTERNAL_FRP_AUTH_SERVER_PORT` | `8999` | Port for Master’s built-in frps authentication service | +| string | `MASTER_INTERNAL_FRP_AUTH_SERVER_PATH` | `/auth` | Path for Master’s built-in frps authentication service | +| int | `SERVER_API_PORT` | `8999` | Server API port | +| string | `DB_TYPE` | `sqlite3` | Database type (e.g., `mysql`, `postgres`, `sqlite3`) | +| string | `DB_DSN` | `data.db` | Database DSN. For `sqlite3`, this is a file path (default in working directory). For other databases, use DSN. | +| string | `CLIENT_ID` | – | Client ID | +| string | `CLIENT_SECRET` | – | Client secret | \ No newline at end of file diff --git a/docs/en/contribute.md b/docs/en/contribute.md new file mode 100644 index 0000000..29e3801 --- /dev/null +++ b/docs/en/contribute.md @@ -0,0 +1,83 @@ +## Project Development Guide + +### Platform Architecture Design + +After choosing the tech stack, the next step is to design the program architecture. As mentioned in the background, frp itself has frpc and frps (client and server), these two roles are indispensable. Then we need to add something new to manage them, so frp-panel introduces a new master role. The master will be responsible for managing various frpc and frps, as well as centrally storing configuration files and connection information. + +Next, we have frpc and frps. The original version requires writing configuration files on both sides. Since the original version already supports this, we don't need to follow the original approach. We will directly not support configuration files, and all configurations must be obtained from the master. + +In addition, we also need to consider the compatibility with the original version. The client/server of frp-panel must be able to connect to the official frpc/frps service. In this way, both configuration file and non-configuration file modes can work perfectly. +Overall, the architecture is quite simple. + +![arch](../public/images/arch.png) + +### Development + +The project includes three roles: + +1. Master: The control node, accepts requests from the frontend and is responsible for managing Client and Server. +2. Server: The server side, controlled by the control node, responsible for providing services to clients, including frps and rpc (for connecting to the Master) services. +3. Client: The client side, controlled by the control node, including frpc and rpc (for connecting to the Master) services. + +Next, we will provide the functionality of each package in the project: + +``` +. +|-- biz # Main business logic +| |-- client # Client logic (here referring to the frp-panel client) +| |-- master # frp-panel control plane, responsible for handling frontend requests, and using rpc to manage frp-panel's server and client +| | |-- auth # Authentication module, including user authentication and client authentication +| | |-- client # Client module, including various APIs for the frontend to manage clients +| | |-- server # Server module, including various APIs for the frontend to manage servers +| | `-- user # User module, including user management, user information retrieval, etc. +| `-- server # Server logic +|-- cache # Cache, used to store frps authentication tokens +|-- cmd # Command line entry, where the main function is located, responsible for starting various modules as needed +|-- common +|-- conf +|-- dao # Data access object, any operations related to the database will call this library +|-- doc # Documentation +|-- idl # IDL definitions +|-- middleware # API middleware, including JWT and context-related, used to process API requests. After authentication passes, user information will be injected into the context and can be obtained through the common package. +|-- models # Database models, used to define database tables. Also includes entity definitions. +|-- pb # Generated protobuf pb files +|-- rpc # Location of various rpcs, including the logic for Client/Server to call Master, as well as the logic for Master to use Stream to call Client and Server +|-- services # Various modules that need to run persistently in memory, this package can manage the running/stopping of various services +| |-- api # API service, requires an external ginRouter to run +| |-- client # frp client, i.e., frpc, can control various configurations/start and stop of frpc +| |-- master # Master service, including the rpc server definition, after receiving an rpc request, it will call the biz package to handle the logic +| |-- rpcclient # Stateful rpc client, because the rpc clients don't have public IP addresses, the rpcclient will call the master's stream long-connection rpc when starting, and after the connection is established, the Master and Client communicate through this package +| `-- server # frp server, i.e., frps, can control various configurations/start and stop of frps +|-- tunnel # Tunnel module, used to manage tunnels, i.e., manage frpc and frps services +|-- utils +|-- watcher # Scheduled tasks, e.g., updating configuration files every 30 seconds +`-- www + |-- api + |-- components # There is an apitest component here for testing + | `-- ui + |-- lib + | `-- pb + |-- pages + |-- public + |-- store + |-- styles + `-- types +``` + +### Debugging and Startup Methods: + +- master: `go run cmd/*.go master` + > For client and server, please copy the content from the master webui +- client: `go run cmd/*.go client -i -s ` +- server: `go run cmd/*.go server -i -s ` + +The project configuration file will read the .env file in the current folder by default. The project includes a sample configuration file, which can be modified according to your needs. + +Detailed architecture call diagram: + +![structure](../public/images/callvis.svg) + +### Core Configuration Explanation + +[settings.go](https://github.com/VaalaCat/frp-panel/blob/main/conf/settings.go) +This file contains detailed explanations of the configuration parameters. Please refer to this file if you need to further modify the configuration. diff --git a/docs/en/deploy-client.md b/docs/en/deploy-client.md index 550a210..baff1fb 100644 --- a/docs/en/deploy-client.md +++ b/docs/en/deploy-client.md @@ -1,62 +1,149 @@ # Client Deployment -Client is recommended to be deployed using docker, directly on the client machine. You can execute commands with root privileges directly on the client machine through a remote terminal, which makes upgrading and management convenient. +We recommend deploying the Client via Docker. However, installing directly on the target machine allows you to run commands as root via a remote terminal, which can simplify upgrades and management. + +**Note ⚠️:** The startup commands for `client` and `server` may change as the project evolves. Although we strive for backward compatibility, always use the commands generated by the Master’s Web UI. ## Preparation -Open the Master's webui and log in. If you don't have an account, register directly - the first user will be the administrator. +Open the Master’s Web UI and log in. If you don’t have an account, register—the first user becomes the administrator. -Navigate to `Clients` in the sidebar, click `New` at the top and enter a unique identifier for the client, then click save. +In the sidebar, navigate to **Client**, click **New**, enter a unique Client ID, and click **Save**. -![](../public/images/en_client_list.png) +![](../public/images/cn_client_list.png) -After refreshing, the new client will appear in the list. +After refreshing, your new Client appears in the list. -Before deploying the client, you need to modify the server configuration, otherwise the client cannot connect properly. +Before deploying the Client, ensure the corresponding Server’s configuration is correct; otherwise, the Client cannot connect. -## Direct Deployment +--- -Click on the `ID (click to view installation command)` column of the corresponding client. A popup will show installation commands for different systems. Copy the appropriate command to the corresponding terminal to install. Here's an example for Linux: +## Deploying on Linux -``` -curl -fSL https://raw.githubusercontent.com/VaalaCat/frp-panel/main/install.sh | bash -s -- client -s abc -i user.s.client1 -a 123123 -r frpp-rpc.example.com -c 9001 -p 9000 -e http +### Direct Execution + +1. Create a dedicated directory on your system. +2. In the Master’s Web UI, click the **ID (show install command)** field for your Client. Copy the Linux install command, for example: + + ```bash + curl -fSL https://raw.githubusercontent.com/VaalaCat/frp-panel/main/install.sh \ + | bash -s -- client -s abc -i user.c.client1 \ + --api-url http://frpp.example.com:9000 \ + --rpc-url grpc://frpp-rpc.example.com:9001 + ``` + +3. If you’re in mainland China, you may want to use a GitHub proxy. For example, with `ghfast`: + + ```bash + curl -fSL https://ghfast.top/https://raw.githubusercontent.com/VaalaCat/frp-panel/main/install.sh \ + | bash -s -- --github-proxy https://ghfast.top/ client -s abc -i user.c.client1 \ + --api-url http://frpp.example.com:9000 \ + --rpc-url grpc://frpp-rpc.example.com:9001 + ``` + +4. If you use a reverse-proxy with TLS (443 → Master 9000/API), adjust the command: + + ```bash + curl -fSL https://ghfast.top/https://raw.githubusercontent.com/VaalaCat/frp-panel/main/install.sh \ + | bash -s -- --github-proxy https://ghfast.top/ client -s abc -i user.c.client1 \ + --api-url https://frpp.example.com:443 \ + --rpc-url wss://frpp.example.com:443 + ``` + +### Docker Compose Deployment + +1. In the Master’s Web UI, click **Key (show startup command)** for your Client. Copy the command: + + ```bash + ./frp-panel client -s abc -i user.c.client1 \ + --api-url http://frpp.example.com:9000 \ + --rpc-url grpc://frpp-rpc.example.com:9001 + ``` + +2. If using TLS proxy, modify: + + ```bash + ./frp-panel client -s abc -i user.c.client1 \ + --api-url https://frpp.example.com:443 \ + --rpc-url wss://frpp.example.com:443 + ``` + +3. Create `docker-compose.yaml`: + + ```yaml + version: '3' + services: + frp-panel-client: + image: vaalacat/frp-panel + container_name: frp-panel-client + network_mode: host + restart: unless-stopped + command: client -s abc -i user.c.client1 \ + --api-url https://frpp.example.com:443 \ + --rpc-url wss://frpp.example.com:443 + ``` + +### Install as a systemd Service + +The `frp-panel` binary can manage a systemd service named `frpp`. Use `frp-panel --help` to view available commands. Examples: + +- Install Client (or Server) with specific parameters: + + ```bash + sudo ./frp-panel install client -s abc -i user.c.client1 \ + --api-url https://frpp.example.com:443 \ + --rpc-url wss://frpp.example.com:443 + ``` + +- Uninstall the `frpp` service: + + ```bash + sudo ./frp-panel uninstall + ``` + +- Start the `frpp` service: + + ```bash + sudo ./frp-panel start + ``` + +- Stop the `frpp` service: + + ```bash + sudo ./frp-panel stop + ``` + +- Restart the `frpp` service: + + ```bash + sudo ./frp-panel restart + ``` + +--- + +## Deploying on Windows + +### Direct Execution + +In PowerShell, in the directory containing the executable, run the startup command copied from the Web UI: + +```powershell +.\frp-panel.exe client -s abc -i user.c.client1 \ + --api-url https://frpp.example.com:443 \ + --rpc-url wss://frpp.example.com:443 ``` -If you're in China, you can add a GitHub accelerator to the installation script: +### Install as a Windows Service -``` -curl -fSL https://ghfast.top/https://raw.githubusercontent.com/VaalaCat/frp-panel/main/install.sh | bash -s -- client -s abc -i user.s.client1 -a 123123 -r frpp-rpc.example.com -c 9001 -p 9000 -e http -``` +Use the same commands as on Linux without `sudo` and adjust the executable path: -Note, if you use a reverse proxy with TLS, you need to modify this command to something like: +```powershell +C:\frpp\frp-panel.exe install client -s abc -i user.c.client1 \ + --api-url https://frpp.example.com:443 \ + --rpc-url wss://frpp.example.com:443 -```bash -curl -fSL https://ghfast.top/https://raw.githubusercontent.com/VaalaCat/frp-panel/main/install.sh | bash -s -- frp-panel client -s abc -i user.s.client1 -a 123123 -t frpp.example.com -r frpp-rpc.example.com -c 443 -p 443 -e https -``` - -## Docker Compose Deployment - -Click on the hidden field in the `Secret (click to view startup command)` column of the corresponding client, and copy a startup command similar to the following for later use: - -```bash -frp-panel client -s abc -i user.s.client1 -a 123123 -r frpp-rpc.example.com -c 9001 -p 9000 -e http -``` - -Note, if you use a reverse proxy with TLS, you need to modify this command to something like: - -```bash -frp-panel client -s abc -i user.s.client1 -a 123123 -t frpp.example.com -r frpp-rpc.example.com -c 443 -p 443 -e https -``` - -docker-compose.yaml - -```yaml -version: '3' -services: - frp-panel-client: - image: vaalacat/frp-panel - container_name: frp-panel-client - network_mode: host - restart: unless-stopped - command: client -s abc -i user.s.client1 -a 123123 -t frpp.example.com -r frpp-rpc.example.com -c 443 -p 443 -e https -``` +# Then manage the service: +C:\frpp\frp-panel.exe start +C:\frpp\frp-panel.exe stop +C:\frpp\frp-panel.exe uninstall +``` \ No newline at end of file diff --git a/docs/en/deploy-master.md b/docs/en/deploy-master.md index 27e6b56..06d9394 100644 --- a/docs/en/deploy-master.md +++ b/docs/en/deploy-master.md @@ -1,45 +1,42 @@ # Master Deployment -Master is recommended to be deployed using docker! Direct installation on the server is not recommended. +We recommend deploying the Master via Docker! Direct installation on the host is not recommended. -Three deployment methods will be provided, choose any one of them. +You have three deployment options—choose one. -After deployment, there is no default user. The first registered user will be the administrator. For security reasons, multi-user registration is disabled by default. +After deployment, there is no default user. The first registered user becomes the administrator. For security, multi-user registration is disabled by default. -## Preparation +By default, the program stores data in its working directory. To change this, see the configuration reference. -### Open public network ports on the server: +**Important:** If you want to deploy the Master and have it also act as a Server, remember to configure the `default` server in the Web UI after starting the Master. -- **WEBUI port**: Default `TCP 9000` -- **RPC port**: Default `TCP 9001` -- **frps API port**: No default, please reserve as needed, example uses `TCP/UDP 7000` -- **frps public service ports**: No default, please reserve as needed, example uses `TCP/UDP 26999-27050` +## Prerequisites -If using a reverse proxy, ignore the WEBUI and RPC ports, and open ports 80/443 instead. +Open the following ports on your server: -The WEBUI port can also handle h2c format RPC connections. +- **WEB UI port**: TCP 9000 +- **RPC port**: TCP 9001 +- **frps API port**: any free port (example uses TCP/UDP 7000) +- **frps service ports**: any port range (example uses TCP/UDP 26999–27050) -The RPC port can also handle self-signed HTTPS API connections. +If you use a reverse proxy, you can ignore WEB UI and RPC ports—just open 80/443. +- The WEB UI port can also accept h2c RPC connections. +- The RPC port can also accept self-signed HTTPS API connections. +- Both can be fronted by a TLS-terminating reverse proxy. -Both can use a reverse proxy server for connection and TLS provision. - -If you want to use a safe method, please refer to the figure below to set the environment variables "`CLIENT_RPC_URL` and `CLIENT_API_URL`". - -Note⚠️: Please deploy successfully using the normal deployment method first! Then adjust these two variables! ! ! ! - -Orange is unsafe, green is safe. You need to ensure that both environment variables are set to work properly +To secure communication, set the environment variables `CLIENT_RPC_URL` and `CLIENT_API_URL`. First deploy normally, then adjust these variables. ![](../public/images/frp-panel-platform-connection-env.svg) -> Method to test if a port is open (using 8080 as an example), run on the server: +> To test if a port (e.g. 8080) is open, run on the server: > ```shell > python3 -m http.server 8080 -> ``` -> Then execute on another computer/server: +> ``` +> Then from another host: > ```shell -> curl http://server-public-IP/domain:8080 -I -> ``` -> If successful, the output will be similar to: +> curl http://SERVER_IP:8080 -I +> ``` +> A successful response looks like: > ``` > HTTP/1.0 200 OK > Server: SimpleHTTP/0.6 Python/3.11.0 @@ -48,11 +45,13 @@ Orange is unsafe, green is safe. You need to ensure that both environment variab > Content-Length: 8225 > ``` -## Method 1: Docker Compose Deployment +--- -The server needs to have docker and docker compose installed. +## Deploying on Linux -First, create a `docker-compose.yaml` file with the following content: +### Option 1: Docker Compose + +Install Docker and Docker Compose, then create `docker-compose.yaml`: ```yaml version: "3" @@ -63,68 +62,61 @@ services: network_mode: host environment: APP_GLOBAL_SECRET: your_secret - MASTER_RPC_HOST: 1.2.3.4 #Server's external IP or domain name + MASTER_RPC_HOST: 1.2.3.4 # external IP or domain MASTER_RPC_PORT: 9001 - MASTER_API_HOST: 1.2.3.4 #Server's external IP or domain name + MASTER_API_HOST: 1.2.3.4 # external IP or domain MASTER_API_PORT: 9000 MASTER_API_SCHEME: http volumes: - - ./data:/data + - ./data:/data # data directory restart: unless-stopped command: master ``` -## Method 2: Docker Command Deployment +### Option 2: Docker CLI -The server needs to have docker installed. We recommend deploying `Master` using host network mode. +Install Docker. We recommend `host` network mode: ```bash -# Recommended -# Change MASTER_RPC_HOST to your server's external IP -# Be careful not to leak APP_GLOBAL_SECRET, client and server are generated through Master docker run -d \ - --network=host \ - --restart=unless-stopped \ - -v /opt/frp-panel:/data \ - -e APP_GLOBAL_SECRET=your_secret \ - -e MASTER_RPC_HOST=0.0.0.0 \ - vaalacat/frp-panel + --network=host \ + --restart=unless-stopped \ + -v /opt/frp-panel:/data \ + -e APP_GLOBAL_SECRET=your_secret \ + -e MASTER_RPC_HOST=0.0.0.0 \ + vaalacat/frp-panel ``` -If you don't want to use host network mode, please refer to the modified command below: +If you cannot use `host` network mode: ```bash -# Or -# Remember to delete the Chinese comments in the command when running -docker run -d -p 9000:9000 \ # API console port - -p 9001:9001 \ # rpc port - -p 7000:7000 \ # frps port - -p 27000-27050:27000-27050 \ # reserved ports for frps - --restart=unless-stopped \ - -v /opt/frp-panel:/data \ # data storage location - -e APP_GLOBAL_SECRET=your_secret \ # Be careful not to leak Master's secret, client and server are generated through Master - -e MASTER_RPC_HOST=0.0.0.0 \ # Change this to your server's external IP - vaalacat/frp-panel +docker run -d \ + -p 9000:9000 \ # API + -p 9001:9001 \ # RPC + -p 7000:7000 \ # frps API + -p 27000-27050:27000-27050 \ # frps service ports + --restart=unless-stopped \ + -v /opt/frp-panel:/data \ + -e APP_GLOBAL_SECRET=your_secret \ + -e MASTER_RPC_HOST=0.0.0.0 \ + vaalacat/frp-panel ``` -## Method 3: Deployment with Docker Reverse Proxy TLS Encryption +### Option 3: Docker + Reverse-Proxy TLS (Traefik Example) -Here we use [Traefik](https://traefik.io/traefik/) as an example. +Create a Docker network for Traefik: -> `Traefik` can automatically identify Docker container ports in real-time and hot update configurations, making it very suitable for Docker service reverse proxying. - -First, create a dedicated network for the reverse proxy named `traefik`. ```bash docker network create traefik ``` -Then start the reverse proxy and Master service: -- `docker-compose.yaml` + +Create `docker-compose.yaml`: ```yaml version: '3' services: - traefk-reverse-proxy: + traefik: image: traefik:v3.3 restart: unless-stopped networks: @@ -132,96 +124,99 @@ services: command: - --entryPoints.web.address=:80 - --entryPoints.websecure.address=:443 - - --entryPoints.websecure.http2.maxConcurrentStreams=250 + - --entryPoints.websecure.http2.maxConcurrentStreams=250 - --providers.docker - --providers.docker.network=traefik - - --api.insecure # Delete this line in production environment - # Below uses port 80 for ACME HTTP DNS certificate validation - --certificatesresolvers.le.acme.email=me@example.com - --certificatesresolvers.le.acme.storage=/etc/traefik/conf/acme.json - --certificatesresolvers.le.acme.httpchallenge=true ports: - # Reverse proxy HTTP port - "80:80" - # Reverse proxy HTTPS port - - "443:443" - # Traefik Web UI (--api.insecure=true will use this port) - # Delete this port in production environment - - "8080:8080" + - "443:443" + - "8080:8080" # Traefik dashboard (remove in production) volumes: - # Mount docker.sock so Traefik can automatically identify all docker container reverse proxy configurations on the host - /var/run/docker.sock:/var/run/docker.sock - # Save certificates requested by Traefik - - ./conf:/etc/traefik/conf + - ./conf:/etc/traefik/conf frpp-master: - image: vaalacat/frp-panel:latest # Change to the version you want to use - environment: - APP_GLOBAL_SECRET: your_secret - # Because api and rpc use different protocols - # We need to use two domains for api and rpc - # So the reverse proxy can correctly identify the protocol to forward - MASTER_RPC_HOST: frpp.example.com - MASTER_API_PORT: 443 - MASTER_API_HOST: frpp-rpc.example.com - MASTER_API_SCHEME: https + image: vaalacat/frp-panel:latest networks: - traefik volumes: - ./data:/data - ports: - # No need to reserve api and rpc ports for master - # Reserve frps api port - - 7000:7000 - - 7000:7000/udp - # Reserve business ports for frps - # Port 26999 is reserved for frps http proxy - - 26999-27050:26999-27050 - - 26999-27050:26999-27050/udp restart: unless-stopped command: master + environment: + APP_GLOBAL_SECRET: your_secret + MASTER_RPC_HOST: frpp-rpc.example.com + MASTER_API_HOST: frpp.example.com + MASTER_API_PORT: 443 + MASTER_API_SCHEME: https + ports: + - 7000:7000 + - 7000:7000/udp + - 26999-27050:26999-27050 + - 26999-27050:26999-27050/udp labels: - # API + # API router - traefik.http.routers.frp-panel-api.rule=Host(`frpp.example.com`) - traefik.http.routers.frp-panel-api.tls=true - traefik.http.routers.frp-panel-api.tls.certresolver=le - traefik.http.routers.frp-panel-api.entrypoints=websecure - - traefik.http.routers.frp-panel-api.service=frp-panel-api - traefik.http.services.frp-panel-api.loadbalancer.server.port=9000 - traefik.http.services.frp-panel-api.loadbalancer.server.scheme=http - # RPC + + # RPC router - traefik.http.routers.frp-panel-rpc.rule=Host(`frpp-rpc.example.com`) - traefik.http.routers.frp-panel-rpc.tls=true - traefik.http.routers.frp-panel-rpc.tls.certresolver=le - traefik.http.routers.frp-panel-rpc.entrypoints=websecure - - traefik.http.routers.frp-panel-rpc.service=frp-panel-rpc - traefik.http.services.frp-panel-rpc.loadbalancer.server.port=9000 - traefik.http.services.frp-panel-rpc.loadbalancer.server.scheme=h2c - # If you don't need frps http proxy, you can omit the following - # You need to configure wildcard domain *.frpp.example.com to resolve to your server's public IP - # This allows you to use domains ending with .frpp.example.com on port 443 to forward multiple services to multiple frpc instances + + # Tunnel router (optional HTTP proxy for frpc) - traefik.http.routers.frp-panel-tunnel.rule=HostRegexp(`.*.frpp.example.com`) - traefik.http.routers.frp-panel-tunnel.tls.domains[0].sans=*.frpp.example.com - traefik.http.routers.frp-panel-tunnel.tls=true - traefik.http.routers.frp-panel-tunnel.tls.certresolver=le - traefik.http.routers.frp-panel-tunnel.entrypoints=websecure - - traefik.http.routers.frp-panel-tunnel.service=frp-panel-tunnel - traefik.http.services.frp-panel-tunnel.loadbalancer.server.port=26999 - traefik.http.services.frp-panel-tunnel.loadbalancer.server.scheme=http + networks: traefik: external: true name: traefik ``` -After deploying the above `docker-compose.yaml`, you can access `server-public-IP/domain:8080` to view the reverse proxy status. +After starting, visit `SERVER_IP:8080` to view Traefik’s dashboard. -Then configure the default server to implement frp subdomain forwarding: +Then configure the `default` server in the Master Web UI: -| Configuration Item | Value | -|----|-----| -| FRPs Listen Port | 7000 | -| FRPs Listen Address | 0.0.0.0 | -| Proxy Listen Address | 0.0.0.0 | -| HTTP Listen Port | 26999 | -| Domain Suffix | frpp.example.com | +| Setting | Value | +|-----------------------|------------------------| +| FRPs listen port | 7000 | +| FRPs listen address | 0.0.0.0 | +| Proxy listen address | 0.0.0.0 | +| HTTP listen port | 26999 | +| Domain suffix | frpp.example.com | + +--- + +## Deploying on Windows + +### Direct Execution + +In the folder containing the executable, create a `.env` file (no extension) with: + +``` +APP_GLOBAL_SECRET=your_secret +MASTER_RPC_HOST=IP +DB_DSN=data.db +``` + +Then run: + +``` +frp-panel-amd64.exe master +``` \ No newline at end of file diff --git a/docs/en/deploy-server.md b/docs/en/deploy-server.md index a33971a..93dfb2a 100644 --- a/docs/en/deploy-server.md +++ b/docs/en/deploy-server.md @@ -1,34 +1,42 @@ # Server Deployment -Server is recommended to be deployed using docker! Direct installation on the server is not recommended. +We recommend deploying the Server via Docker! Direct installation on the host is not recommended. -> If you only have one public network server to manage, you can use the `default server` that comes with `master`, no need to deploy a separate `server`. +**Note ⚠️:** The startup commands for `client` and `server` may change as the project evolves. Although we strive for backward compatibility, the commands generated by the Master’s web UI should be treated as authoritative. -## 1. Preparation +> If you only have one public-facing server to manage, you can use the Master’s built-in `default` server without deploying a separate Server. Remember to configure the `default` server after starting the Master. -Open the Master's webui and log in. If you don't have an account, register directly - the first user will be the administrator. +## Deploying on Linux -Navigate to `Servers` in the sidebar, click `New` at the top and enter a unique identifier for the server and the IP/domain name that can be accessed from the public network, then click save. +### 1. Preparation -![](../public/images/en_server_list.png) +Open the Master’s web UI and log in. If you don’t have an account, register—your first user will be the administrator. -After refreshing, the new server will appear in the list. Click on the hidden field in the `Secret (click to view startup command)` column of the corresponding server, and copy a startup command similar to the following for later use: +In the sidebar, navigate to **Server**, click **New**, and enter: +- A unique Server ID +- The public IP or domain name where the Server can be accessed + +Then click **Save**. + +![](../public/images/cn_server_list.png) + +After refreshing, your new Server appears in the list. Click the **Key (show startup command)** field for that Server and copy the generated command, e.g.: ```bash -frp-panel server -s abc -i user.s.server1 -a 123123 -r frpp-rpc.example.com -c 9001 -p 9000 -e http +frp-panel server -s abc -i user.s.server1 --api-url http://frpp.example.com:9000 --rpc-url grpc://frpp-rpc.example.com:9001 ``` -Note, if you use a reverse proxy with TLS, you need to modify this command to something like: +If you are using a reverse-proxy with TLS, proxy external port 443 to the Master’s port 9000 (API) over HTTP upstream, and adjust the command accordingly: ```bash -frp-panel server -s abc -i user.s.server1 -a 123123 -t frpp.example.com -r frpp-rpc.example.com -c 443 -p 443 -e https +frp-panel server -s abc -i user.s.server1 --api-url https://frpp.example.com:443 --rpc-url wss://frpp.example.com:443 ``` -## 2. Program Installation +### 2. Installation -### Docker Compose Deployment +#### Docker Compose -docker-compose.yaml +Create a `docker-compose.yaml`: ```yaml version: '3' @@ -38,13 +46,21 @@ services: container_name: frp-panel-server network_mode: host restart: unless-stopped - command: server -s abc -i user.s.server1 -a 123123 -t frpp.example.com -r frpp-rpc.example.com -c 443 -p 443 -e https + command: server -s abc -i user.s.server1 --api-url http://frpp.example.com:9000 --rpc-url grpc://frpp-rpc.example.com:9001 ``` -### Direct Deployment +#### Direct Execution -If you want to deploy directly, please refer to the client deployment steps. +If you prefer to run directly (without a service manager), follow the steps in the Client direct-run section. -## 3. Server Configuration +#### systemd Service -After installation, you need to modify the server configuration according to your network and requirements, otherwise the client cannot connect properly. \ No newline at end of file +To install as a systemd service, refer to the Client systemd deployment instructions. + +### 3. Server Configuration + +After installation, modify the Server configuration according to your network and requirements; otherwise, Clients cannot connect. + +## Deploying on Windows + +Please refer to the Client deployment steps for Windows. \ No newline at end of file diff --git a/docs/en/quick-start.md b/docs/en/quick-start.md index d19eb58..70d0524 100644 --- a/docs/en/quick-start.md +++ b/docs/en/quick-start.md @@ -1,18 +1,33 @@ # Quick Start -## Important Pre-Start Reading +## Before You Begin `frp-panel` consists of three modules: -1. `master`: The central control module, responsible for distributing configuration files and controlling all other modules -2. `server`: Corresponds to `frps`, responsible for providing traffic entry points -3. `client`: Corresponds to `frpc`, can expose local services to an entry point on the `server` +1. `master`: the central control module, responsible for distributing configuration files and managing all other modules +2. `server`: corresponds to `frps`, responsible for providing traffic entry points +3. `client`: corresponds to `frpc`, which exposes local services to a specific entry point on the `server` -> When deploying `master`, it will start a default `default server` for `client` connections. Therefore, `master` generally doesn't exist independently, but you can choose not to use it +> When you deploy the `master`, it will automatically start a default “default server” for clients to connect to. Therefore, the `master` is normally not used on its own, though you can choose to disable this feature. -When deploying, we typically start with the `master`. The `server` and `client` managed by the `master` require automatically generated content from the successfully deployed `master` control page. +In a typical deployment, we start with the `master`. When deploying `server` and `client` instances managed by the `master`, you will need the information automatically generated in the `master`’s web console after it has been successfully deployed. -For `frp-panel`, we **recommend deploying all components using `docker`** and **using `host` network mode**, unless you need remote terminal control of remote machines, in which case install the service on the client machine. +For `frp-panel`, **we recommend deploying all components via Docker** and **using the `host` network mode**, unless you need remote terminal access to the target machine, in which case you may install the services directly on the host. + +## Download Instructions + +frp-panel supports deployment via Docker or direct execution. To deploy directly, download the release files here: [release](https://github.com/VaalaCat/frp-panel/releases) + +Note: There are two binary versions—one is client-only, and the other is a full-featured executable. We recommend using the full-featured executable. + +The client-only version can only execute the `client` command (no client parameters required) and its filename includes the “client” identifier. + +After starting, the default example can be accessed at `http://IP:9000` + +The first registered user is the administrator by default. Registration of additional users is disabled by default. To enable it, add the parameter `APP_ENABLE_REGISTER=true` in the Master’s startup command or configuration file. + +> If you have questions about the configuration during deployment, please refer to the [Configuration Guide](./all-configs.md) +> We recommend keeping this page open for reference. ## Architecture Diagram diff --git a/docs/en/screenshots.md b/docs/en/screenshots.md new file mode 100644 index 0000000..1dfec55 --- /dev/null +++ b/docs/en/screenshots.md @@ -0,0 +1,37 @@ +## Video Showcase + +> Demo Video: [Demo Video](../public/images/frp-panel-demo.mp4) + +![](../public/images/frp-panel-demo.gif) + +## Screenshots + +### Home Page +![Home Page](../public/images/en_index.png) + +### Server List +![Server List](../public/images/en_server_list.png) + +### Server Edit +![Server Edit](../public/images/en_server_edit.png) + +### Server Advanced Edit +![Server Advanced Edit](../public/images/en_server_edit_adv.png) + +### Client List +![Client List](../public/images/en_client_list.png) + +### Client Edit +![Client Edit](../public/images/en_client_edit.png) + +### Client Advanced Edit +![Client Advanced Edit](../public/images/en_client_edit_adv.png) + +### Client Statistics +![Client Statistics](../public/images/en_client_stats.png) + +### Realtime Logs +![Realtime Logs](../public/images/en_realtime_log.png) + +### Remote Console +![Remote Console](../public/images/en_remote_console.png) \ No newline at end of file diff --git a/docs/quick-start.md b/docs/quick-start.md index 0c146f3..0687fdf 100644 --- a/docs/quick-start.md +++ b/docs/quick-start.md @@ -12,7 +12,23 @@ 部署时，我们一般从 `master` 开始。`master` 负责管理的 `server` 和 `client` 部署时，需要用到成功部署后的 `master` 控制页面中自动生成的内容。 -对于 `frp-panel` 我们**推荐所有的组件都使用 `docker` 部署**，并且**使用 `host` 网络**模式，除非你需要远程终端控制远端的机器时才使用服务安装到客户机 +对于 `frp-panel` 我们**推荐所有的组件都使用 `docker` 部署**，并且**使用 `host` 网络**模式，除非你需要远程终端控制远端的机器时，才使用服务安装到客户机 + +## 文件下载说明 + +frp-panel 可选 docker 和直接运行模式部署，直接部署请到 release 下载文件：[release](https://github.com/VaalaCat/frp-panel/releases) + +注意：二进制有两种，一种是仅客户端，一种是全功能可执行文件，推荐使用全功能可执行文件。 + +客户端版只能执行 client 命令(无需 client 参数)，仅客户端版的名字会带有 client 标识 + +启动过后默认例子的访问地址为 `http://IP:9000` + +默认第一个注册的用户是管理员。且默认不开放注册多用户，如果需要，请在 Master 启动命令或配置文件中添加参数：`APP_ENABLE_REGISTER=true` + +> 如果在部署过程中，对配置有疑问，请参考 [配置说明](./all-configs.md) +> +> 推荐单独打开一个页面随时参考 ## 架构图 diff --git a/docs/screenshots.md b/docs/screenshots.md new file mode 100644 index 0000000..eb08684 --- /dev/null +++ b/docs/screenshots.md @@ -0,0 +1,37 @@ +## 视频展示 + +> Demo Video: [Demo Video](public/images/frp-panel-demo.mp4) + +![](public/images/frp-panel-demo.gif) + +## 截图展示 + +### 首页 +![首页](public/images/cn_index.png) + +### 服务器列表 +![服务器列表](public/images/cn_server_list.png) + +### 服务器编辑 +![服务器编辑](public/images/cn_server_edit.png) + +### 服务器高级编辑 +![服务器高级编辑](public/images/cn_server_edit_adv.png) + +### 客户端列表 +![客户端列表](public/images/cn_client_list.png) + +### 客户端编辑 +![客户端编辑](public/images/cn_client_edit.png) + +### 客户端高级编辑 +![客户端高级编辑](public/images/cn_client_edit_adv.png) + +### 客户端统计 +![客户端统计](public/images/cn_client_stats.png) + +### 实时日志 +![实时日志](public/images/cn_realtime_log.png) + +### 远程控制台 +![远程控制台](public/images/cn_remote_console.png)