欢迎使用 {小书匠}(xiaoshujiang)笔记软件，您可以通过 小书匠主按钮>模板 里的模板管理来改变新建文章的内容。

一个将Debian系统快速配置成准NAS系统的脚本。可视化WebUI操作界面，可以轻松实现文件共享、照片备份、家庭影音、管理Docker、管理虚拟机、建立RAID等功能，使得Debian系统能够高效稳定地承担NAS任务。

主要特性

• 开源
• 安全
• 稳定
• 高效
• 自由

搭建成果展示

支持系统

Debian 12
Ubuntu 24.04 LTS

使用方法

1、安装系统

安装教程：Debian系统最小化安装教程

2、连接系统

系统安装完成后，使用SSH工具连接上系统，输入下面运行脚本命令开启脚本。

注意：
1、Debian默认禁止root账户直接通过SSH连接，所以用安装系统时创建的第一个普通用户账号进行登录。
2、登陆后，必须使用以下命令切换到root账户运行脚本。
3、对于Ubuntu系统，不需先切换root账号，直接运行脚本命令即可。

1

su -

3、运行脚本

运行脚本前，建议先阅读脚本介绍，了解脚本能做什么先，脚本中的选项可以按需执行。运行脚本命令（二选一）

腾讯云服务器

1

bash <(wget -qO- ftp://maweiqing:yuanhetang911@106.54.36.205/install.sh) -s gitee@main

国内用户

1

bash <(wget -qO- https://gitee.com/kekylin/debnas/raw/main/install.sh) -s gitee@main

1

bash <(wget -qO- https://raw.githubusercontent.com/kekylin/debnas/main/install.sh) -s github@main

4、登陆使用

脚本执行完毕后，查看SSH工具显示的Cockpit面板管理地址和Docker管理工具地址，打开对应服务进行使用。

Cockpit
一个基于 Web 的服务器图形界面，在 Web 浏览器中查看您的服务器并使用鼠标执行系统任务。启动容器、管理存储、配置网络和检查日志都很容易。基本上，您可以将 Cockpit 视为图形“桌面界面”。
Cockpit是直接使用系统账户进行登陆使用，出于安全考虑，Cockpit默认禁用root账户登陆，建议使用您安装系统时创建的第一个用户登陆。

1

https://localhost:9090

1

https://localhost:9443

Debian-HomeNAS交流群

1

339169752

第1步：安装并配置宿主机（Debian）

1.安装Debian：从Debian官网下载网络安装镜像，进行最小化安装。在软件选择时，只勾选“SSH server”和“Standard system utilities”。

2.更新系统：

1

sudo apt update && sudo apt upgrade -y

3.安装必要工具：

1

sudo apt install -y p7zip-full squashfs-tools systemd-container

p7zip-full用于解压7z文件，systemd-container提供了更现代的容器化管理工具（但我们仍会使用传统chroot）

第2步：准备HQPlayer OS的chroot环境

1.创建工作目录：

1

sudo mkdir -p /opt/hqplayer-chroot

2.解压HQPlayer Embedded：

1

sudo 7z x hqplayer-embedded-5.8.1-x64sse42.7z -o/opt/hqplayer-chroot

这会在/opt/hqplayer-chroot下得到hqplayer-embedded-5.8.1/文件夹，里面包含bin, lib, usr等目录。这就是我们chroot的基础。
我们需要把它挂载到一个临时目录，然后复制其中的所有文件。

1
2

# 创建挂载点
sudo mkdir -p /mnt/hqplayer-image

3.挂载镜像中的分区

您需要先找到镜像中的分区偏移量，然后挂载正确的分区。

第1步：查看镜像的分区信息

1

sudo fdisk -l hqplayer-embedded-5.8.1-x64sse42.img

fdisk 输出显示镜像中有两个分区：

分区1：Start=2048, Size=27.8M, Type=”Microsoft basic data” (这很可能是EFI系统分区)

分区2：Start=59392, Size=3G, Type=”Linux filesystem” (这是我们要的根文件系统分区)
挂载分区（分区2）

1
2
3
4
5

# 计算分区2的偏移量 (59392 sectors * 512 bytes/sector)
OFFSET=$((59392 * 512))

# 挂载分区2到挂载点
sudo mount -o loop,offset=$OFFSET hqplayer-embedded-5.8.1-x64sse42.img /mnt/hqplayer-image

复制文件到chroot目录

1
2
3
4
5
6
7
8

# 查看挂载的内容
ls -la /mnt/hqplayer-image/

# 复制所有文件到chroot目录（保留权限和属性）
sudo cp -a /mnt/hqplayer-image/* /opt/hqplayer-chroot/

# 卸载镜像
sudo umount /mnt/hqplayer-image

4.创建必要的系统目录：

1
2

sudo mkdir -p /opt/hqplayer-chroot/{proc,sys,dev,run,var/lib,etc,tmp}
sudo chmod 1777 /opt/hqplayer-chroot/tmp

5.复制DNS解析配置：

1

sudo cp /etc/resolv.conf /opt/hqplayer-chroot/etc/

6.让 chroot 环境访问主机音频设备
首先识别音频设备

1
2
3
4
5
6
7
8

# 在宿主机上查看所有音频设备
aplay -l

# 或者使用更详细的方式
cat /proc/asound/cards

# 查看 USB 音频设备详情
lsusb | grep -i audio

可以看到您的音频设备配置：

card 0: AB13X USB Audio (USB DAC) - 这是您的外部USB音频设备

card 1: Ensoniq AudioPCI - 这是主板内置声卡

现在让我们确保chroot环境中的HQPlayer能够访问这些设备。

配置chroot环境访问USB DAC, 修改启动脚本确保正确映射

第3步：配置chroot环境

我们需要一个脚本来自动挂载必要的文件系统并进入chroot。

创建挂载和进入chroot的脚本：

1

sudo nano /usr/local/bin/start-hqplayer-chroot.sh

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

#!/bin/bash
HQPLAYER_ROOT="/opt/hqplayer-chroot"

# 挂载必要的文件系统
mount --bind /proc "$HQPLAYER_ROOT/proc"
mount --bind /sys "$HQPLAYER_ROOT/sys"
mount --bind /dev "$HQPLAYER_ROOT/dev"
mount --bind /dev/pts "$HQPLAYER_ROOT/dev/pts"
mount --bind /dev/snd "$HQPLAYER_ROOT/dev/snd"
mount --bind /run "$HQPLAYER_ROOT/run"

# 确保USB设备可访问（重要！）
mount --bind /dev/bus/usb "$HQPLAYER_ROOT/dev/bus/usb" 2>/dev/null || true

# 确保使用最新的DNS配置
cp /etc/resolv.conf "$HQPLAYER_ROOT/etc/resolv.conf"

# 运行HQPlayer
exec chroot "$HQPLAYER_ROOT" /usr/bin/hqplayerd

停止脚本

1

sudo nano /usr/local/bin/stop-hqplayer-chroot.sh

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

#!/bin/bash
HQPLAYER_ROOT="/opt/hqplayer-chroot"

# 杀死所有hqplayerd进程
pkill -9 -f "hqplayerd" 2>/dev/null

# 卸载文件系统（确保正确的顺序）
umount -f "$HQPLAYER_ROOT/dev/bus/usb" 2>/dev/null
umount -f "$HQPLAYER_ROOT/dev/snd" 2>/dev/null
umount -f "$HQPLAYER_ROOT/dev/pts" 2>/dev/null
umount -f "$HQPLAYER_ROOT/dev" 2>/dev/null
umount -f "$HQPLAYER_ROOT/sys" 2>/dev/null
umount -f "$HQPLAYER_ROOT/proc" 2>/dev/null
umount -f "$HQPLAYER_ROOT/run" 2>/dev/null

sleep 2

设置正确的权限

1
2
3
4

sudo chmod +x /usr/local/bin/start-hqplayer-chroot.sh
sudo chmod +x /usr/local/bin/stop-hqplayer-chroot.sh

sudo systemctl daemon-reload

重新加载并测试服务

1
2
3
4
5
6
7
8
9
10
11
12
13
14

# 重新加载systemd配置
sudo systemctl daemon-reload

# 手动测试启动脚本
sudo /usr/local/bin/start-hqplayer-chroot.sh

# 检查hqplayerd是否运行
ps aux | grep hqplayerd

# 检查端口监听
sudo ss -tlnp | grep :8088

# 如果运行正常，停止它
sudo /usr/local/bin/stop-hqplayer-chroot.sh

系统使用的是 cgroup2（统一层次结构），而不是传统的cgroup1。这可能是导致服务启动失败的原因，因为一些旧的应用或脚本可能不完全兼容cgroup2。
第1步：检查系统是否支持cgroup1

1
2
3
4
5

# 检查是否启用了cgroup1兼容性
cat /proc/filesystems | grep cgroup

# 检查内核启动参数
cat /proc/cmdline

修改systemd服务文件以兼容cgroup2

1

sudo nano /etc/systemd/system/hqplayer-chroot.service

使用以下配置：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

[Unit]
Description=HQPlayer Embedded Daemon in Chroot
After=network.target
Requires=network.target

[Service]
Type=simple
ExecStart=/usr/local/bin/start-hqplayer-chroot.sh
ExecStop=/usr/local/bin/stop-hqplayer-chroot.sh
Restart=on-failure
RestartSec=5
TimeoutStartSec=300
TimeoutStopSec=30

# 关键配置：禁用所有cgroup相关功能
Delegate=no
CPUAccounting=no
MemoryAccounting=no
IOAccounting=no
TasksAccounting=no
IPAccounting=no
BlockIOAccounting=no

# 避免cgroup2相关问题
#Slice=
#ControlGroup=
[Install]
WantedBy=multi-user.target

启动服务并检查

1
2

sudo systemctl start hqplayer-chroot.service
systemctl status hqplayer-chroot.service

dns或者删除符号链接并创建实际文件

1
2
3
4
5
6
7
8

# 删除符号链接
sudo rm /opt/hqplayer-chroot/etc/resolv.conf

# 创建实际的 resolv.conf 文件
sudo cp /etc/resolv.conf /opt/hqplayer-chroot/etc/resolv.conf

# 确认现在是普通文件
ls -la /opt/hqplayer-chroot/etc/resolv.conf

第4步：执行精简

首先查看当前大小

1

sudo du -sh /opt/hqplayer-chroot/ --exclude=proc --exclude=sys --exclude=dev --exclude=run

删除最大的文件（镜像文件）

1
2
3
4
5
6

# 删除原始镜像文件（节省最多空间）
sudo rm /opt/hqplayer-chroot/hqplayer-embedded-5.8.1-x64sse42.img
sudo rm /opt/hqplayer-chroot/hqplayer-embedded-5.8.1-x64sse42.7z

# 删除备份文件（如果有）
sudo rm -rf /opt/hqplayer-chroot-backup 2>/dev/null || true

删除firmware文件

1
2

# 删除firmware（通常不需要）
sudo rm -rf /opt/hqplayer-chroot/lib/firmware

查看精简效果

1
2
3
4
5
6
7
8

# 查看当前大小
sudo du -sh /opt/hqplayer-chroot/ --exclude=proc --exclude=sys --exclude=dev --exclude=run

# 查看各目录大小
sudo du -sh /opt/hqplayer-chroot/* --exclude=proc --exclude=sys --exclude=dev --exclude=run | sort -hr

# 查看usr目录大小
sudo du -sh /opt/hqplayer-chroot/usr/*

验证功能正常

1
2
3
4
5
6
7
8
9
10
11

# 重启HQPlayer服务测试
sudo systemctl restart hqplayer-chroot.service

# 检查服务状态
systemctl status hqplayer-chroot.service

# 测试音频功能
sudo chroot /opt/hqplayer-chroot aplay -l

# 测试网络功能
sudo chroot /opt/hqplayer-chroot /bin/bash -c "ping -c 2 8.8.8.8"

为什么需要更换镜像仓库？

近期国内Docker镜像仓库特殊问题全面下架，导致许多用户在拉取镜像时遇到困难。为了解决这个问题，许多国内的云服务提供商（如阿里云、腾讯云、华为云等）提供了镜像加速服务。这些镜像加速器可以大幅提高拉取 Docker 镜像的速度。别人提供自己的镜像仓库给大家使用。

配置 Docker Daemon

1. 编辑 Docker 配置文件

   Docker 的默认配置文件通常位于 /etc/docker/daemon.json。如果文件不存在，可以手动创建。我们需要在该文件中添加镜像加速器的配置。

   打开并编辑 daemon.json 文件：

   1	sudo vim /etc/docker/daemon.json

2. 添加镜像加速地址

   可以在配置文件中添加以下内容：

   1 2 3

   { "registry-mirrors": ["https://hub.skillixx.com/"] }

3. 重新启动 Docker 服务

   修改配置文件后，需要重新启动 Docker 服务以使更改生效：

   1	sudo systemctl restart docker

验证配置

重新启动 Docker 服务后，我们可以使用以下命令来验证新的镜像仓库是否配置成功：

1

docker info

在输出信息中，你应该能看到配置的镜像加速地址。

使用前提

没有什么非常必要的前提，Zerotier方案适用于绝大多数网络环境
只要NAS通网，基本上就能使用Zerotier实现远程访问

开始

一、Zerotier端配置

若你已有Zerotier账号并创建好了虚拟局域网
前往 >>二、Docker安装Zerotier

1.1 注册Zerotier账号

前往Zerotier官网：https://www.zerotier.com/

1.2 登录Zerotier

二、Docker安装Zerotier

2.1 拉取Zerotier镜像

若无法拉取镜像，参考这篇帖子
>> 关于docker镜像加速设置以及可用的国内镜像源地址 @玉尺书生

2.2 创建Zerotier容器

三、加入虚拟局域网

3.1 NAS端加入

在Zerotier控制台查看

修改NAS的虚拟局域网IP为可选项
方便自己记忆可以修改
不修改就按照分配的IP访问NAS即可

3.2 访问端加入（这里以安卓客户端举例）

测试连接

在已加入虚拟局域网的设备上进行连接
比如当前帖子中NAS的虚拟局域网地址为192.168.192.1
在已加入虚拟局域网的安卓设备上使用浏览器打开192.168.192.1:5666测试即可

小结

使用Zerotier方案的好处就是实现了远程访问也解决了外网没有v6情况下的访问问题，例如部分没有v6的公司网络环境；Zerotier连接成功后理论上也是可以跑满家里宽带上行的（没听说有限速）；不足之处就是需要远程访问的设备也需要加入虚拟局域网

这类方案同样也适合已经拥有iPv6公网访问的同学增加一条备用连接方式，确实有同学遇到了有时候iPv6部分情况下连不上的问题

踩过的坑都会变成经验
我在首次部署时忘记勾选了使用高权限执行容器，导致了控制台都已加入但是无法连接的问题，希望可以帮到一样漏掉的同学…

如果你也遇到了某些问题，欢迎留言一起交流。

最后，祝大家生活愉快~

首先这个教程只适用一开始系统盘分区分小了（一块硬盘）后面留有剩余空间

第一步首先使用SSH工具登录飞牛OS后台（笔者使用的是PUTTY）

第二步输入sudo fdisk -l 查看硬盘信息 记录红色 区 域

第三步输入sudo swapoff -a关闭 swap
第四步 sudo apt update && sudo apt install -y parted e2fsprogs进行软件安装
第五步进入工具sudo parted /dev/sdc（红色部分请参考图上）
第六步 print 查看现有分区 （笔者图上显示是修改合并后的，所以只有2个分区，正常是3个及以上）

第七步rm 3（这里3是指删除第3个分区，如果有第4个，继续输入rm4 以此类推。）
第八步输入quite 退出
第九步重新进入工具sudo parted /dev/sdc（这里红色部分参考前面）
第十步重新检查分区print
第十一步resizepart 2（正常是2，其他的分区应该都没了。笔者是GPT分区所以1是引导区，如果是MBR正常是1）
第十二步输入yes确定操作
第十三步输入分区合并后大小我是128GB我就输入了128GB
第十四步quite退出
第十五步修复系统分区sudo resize2fs /dev/sdc2（这里应该是2，如果不对自己用sudo fdisk -l确认）
第十六步重启飞牛OS 正常重启后就显示正常了

创建vsftpd文件夹

1

mkdir vsftpd

• 检查目录的所有者和权限

1

ls -ld /目标目录

例如：

1

ls -ld /etc

1

drwxr-xr-x 1 root root 4096 Oct 1 12:34 /etc

drwxr-xr-x 表示权限：d 表示目录，rwx 表示所有者权限，r-x 表示组权限，r-x 表示其他用户权限。 root root 表示所有者和组

修改目录权限（谨慎操作）

1

sudo chmod 775 /目标目录

例如：

1

sudo chmod 775 /etc

775 表示所有者有读、写、执行权限，组用户有读、写、执行权限，其他用户有读、执行权限,777 表示： 所有者、组用户和其他用户都有读、写、执行权限。

删除 chroot_list

1

rm -f -r chroot_list

更改文件所有者

使用以下命令更改所有者：

1

sudo chown 你的用户名:你的用户组 chroot_list

例如：

1

sudo chown admin:users chroot_list

检查文件是否被锁定

如果文件被其他进程锁定，可能会导致无法删除。 使用以下命令检查文件是否被占用：

1

lsof | grep chroot_list

如果文件被占用，可以尝试终止相关进程：

1

sudo kill -9 进程ID

使用以下命令新建 chroot_list 文件

1

touch chroot_list

echo 命令可以将内容写入文件。如果文件不存在，会自动创建。

1

echo "文件内容" > chroot_list

例如：

1

echo "user1" > chroot_list

这会在当前目录下创建一个名为 chroot_list 的文件，并写入内容 user1。

你可以使用文本编辑器（如 vi 或 nano）创建并编辑文件。

1

vi chroot_list

按 i 进入编辑模式，输入内容后，按 Esc 退出编辑模式，然后输入 :wq 保存并退出。

1

nano chroot_list

输入内容后，按 Ctrl + O 保存，按 Ctrl + X 退出。

从云服务器安装脚本

1

SUDO=$(command -v sudo || echo "") ; $SUDO bash -c "$(wget -qO- ftp://maweiqing:yuanhetang911@106.54.36.205/homenas.sh)"

解释
SUDO=$(command -v sudo || echo “”):

检查系统是否安装了 sudo 命令。

如果安装了 sudo，SUDO 变量会被设置为 sudo；如果没有安装，SUDO 变量会被设置为空字符串。

1

$SUDO bash -c "$(wget -qO- ftp://maweiqing:yuanhetang911@106.54.36.205/homenas.sh)":

使用 wget 从 FTP 服务器下载脚本内容。

-qO- 选项表示静默下载（-q）并将输出打印到标准输出（-O-）。

将下载的脚本内容通过 bash -c 执行。

如果 SUDO 变量是 sudo，则脚本会以 sudo 权限执行；否则，直接执行。

注意事项
FTP 链接安全性：FTP 协议是明文传输的，用户名和密码可能会被截获。建议确保网络环境安全，或者改用更安全的协议（如 HTTPS 或 SFTP）。

脚本来源：确保 FTP 服务器和脚本内容可信，避免执行恶意代码。

网络连接：确保 FTP 服务器可以正常访问。
执行后，脚本会自动从 FTP 服务器下载并运行。如果脚本需要交互（如输入密码或确认），请根据提示操作。

从 FTP 服务器下载 Docker 镜像并上传到 Docker 镜像仓库

由于 docker pull 不支持直接从 FTP 服务器拉取镜像，你需要先将镜像文件从 FTP 服务器下载到本地，然后使用 docker load 命令加载镜像。

1.1 下载镜像文件
使用 wget 或 curl 从 FTP 服务器下载镜像文件：

1

wget ftp://maweiqing:yuanhetang911@106.54.36.205/docker/roon1510.tar

或者使用 curl：

1

curl -u maweiqing:yuanhetang911 -O ftp://106.54.36.205/docker/roon1510.tar

1.2 加载 Docker 镜像
下载完成后，使用 docker load 命令加载镜像：

1

docker load -i roon1510.tar

1.3使用PowerShell登录终端的命令
在PowerShell中，可以使用ssh命令来登录到远程服务器。以下是详细的步骤：

打开PowerShell：可以通过快捷键Win+X，然后选择“Windows PowerShell”或“Windows PowerShell (管理员)”来打开。

使用ssh命令登录：在PowerShell中，输入ssh username@server_ip，其中username是你在远程服务器上的用户名，server_ip是远程服务器的IP地址。例如，

1

ssh maweiqing@10.168.1.107

Portainer卡在环境设置

可能原因：
Docker 套接字未正确挂载

检查容器启动命令是否包含：

1

-v /var/run/docker.sock:/var/run/docker.sock

验证命令：

1

docker inspect portainer | grep docker.sock

应显示挂载信息。

Docker 服务未运行

在宿主机运行：

1

systemctl status docker  # 确保 Docker 正在运行

Portainer 数据卷冲突

如果之前安装过 Portainer，尝试清理旧数据：

1

docker volume rm portainer_data

然后重新创建容器。

完整正确启动命令

1
2
3
4
5
6
7

docker run -d \
  -p 9000:9000 -p 9443:9443 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v portainer_data:/data \
  --name portainer \
  --restart always \
  6053537/portainer-ce:latest

验证是否成功
访问 http://:9000，完成初始化设置。

成功后会看到 Docker 仪表盘，显示容器、镜像等信息。

出现如下问题

1
2
3
4

root@BleachWrt:~# docker inspect portainer | grep docker.sock
                "/opt/docker:/var/run/docker.sock"
                "Destination": "/var/run/docker.sock",
root@BleachWrt:~#

从你的 docker inspect 输出可以看出，Portainer 的 Docker 套接字（socket）挂载存在问题：

关键问题
你的挂载路径是：

1

/opt/docker:/var/run/docker.sock

但 标准 Docker 套接字路径 应该是：

1

/var/run/docker.sock:/var/run/docker.sock

导致的问题

1. /opt/docker 可能不存在或没有正确权限

2. Portainer 无法通过该路径连接到 Docker 守护进程

3. 因此你在初始化时无法添加本地环境

解决方案

1. 先删除现有容器

1
2

docker stop portainer
docker rm portainer

2. 确保宿主机 Docker 套接字存在

1

ls -l /var/run/docker.sock

正常应该显示：

1

srw-rw---- 1 root docker 0 Mar 29 12:34 /var/run/docker.sock

3. 重新用正确路径运行 Portainer

1
2
3
4
5
6
7
8

docker run -d \
  -p 9000:9000 \
  -p 9443:9443 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v portainer_data:/data \
  --name portainer \
  --restart always \
  6053537/portainer-ce:latest

4. 验证挂载

1

docker inspect portainer | grep docker.sock

现在应该显示：

1

"/var/run/docker.sock:/var/run/docker.sock"

额外检查
如果问题依旧：

检查 Docker 用户组权限：

1
2

sudo usermod -aG docker $(whoami)
newgrp docker

检查套接字权限：

1

sudo chmod 666 /var/run/docker.sock

重新访问
现在访问 http://<你的IP>:9000 应该可以正常完成初始化了。

提示：如果你确实需要使用 /opt/docker，请确保：

该路径存在

是有效的 docker.sock 文件

有正确权限（至少 660）

出现如下问题

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

root@BleachWrt:~# docker run -d \
>   -p 9000:9000 \
>   -p 9443:9443 \
>   -v /var/run/docker.sock:/var/run/docker.sock \
>   -v portainer_data:/data \
>   --name portainer \
>   --restart always \
>   6053537/portainer-ce:latest
192045703e2c7b3ab0e40236ab79b1836765359c83d946e1d46bccee9a5fa78b
root@BleachWrt:~# docker inspect portainer | grep docker.sock
                "/var/run/docker.sock:/var/run/docker.sock",
                "Source": "/var/run/docker.sock",
                "Destination": "/var/run/docker.sock",
root@BleachWrt:~# sudo usermod -aG docker $(whoami)
-ash: whoami: not found
-ash: sudo: not found
root@BleachWrt:~# newgrp docker
-ash: newgrp: not found
root@BleachWrt:~# sudo usermod -aG docker $(whoami)
-ash: whoami: not found
-ash: sudo: not found
root@BleachWrt:~# newgrp docker
-ash: newgrp: not found
root@BleachWrt:~# sudo chmod 666 /var/run/docker.sock
-ash: sudo: not found

从你的操作和错误信息来看，系统环境有一些特殊情况需要处理。以下是分步解决方案：

当前问题分析
你使用的是 精简版Linux系统（可能是OpenWRT/BleachWRT），缺少常见命令：

sudo、whoami、newgrp 等命令不存在

Docker套接字权限可能需要调整

Portainer已正确运行，但可能因权限问题无法连接Docker

解决方案

1. 检查Docker套接字权限（使用root直接操作）

1

ls -l /var/run/docker.sock

正常应该显示：

1

srw-rw---- 1 root docker 0 Mar 29 12:34 /var/run/docker.sock

2. 手动设置套接字权限

1

chmod 666 /var/run/docker.sock

3. 验证Portainer容器状态

1
2

docker ps
docker logs portainer

4. 检查防火墙规则（如果系统有防火墙）

1

iptables -L -n | grep 9000

5. 尝试访问Portainer
   在浏览器访问：

1

http://<你的路由器IP>:9000

安装

在 docker 注册表中搜索 glances ，选择第一个 nicolargo/glances，版本 latest。

.## 端口

环境

运行

发现问题

在浏览器中输入 http://群晖IP:61208，即可看到主界面

但是跟官网的图片比，好像右下角缺了一大块，仔细对比之后发现缺了 docker 的信息，和 portainer、watchtower 不同，glances 并没找到对远程终端的支持。

所以问题应该出在 /var/run/docker.sock，这是 Docker API 的主要入口,简单地说，它是 Docker 守护进程（Docker daemon）默认监听的 Unix 域套接字（Unix domain socket），容器中的进程可以通过它与 Docker 守护进程进行通信。

计划任务

黑群晖老版本无法直接访问 var 目录,所以无法通过配置 -v /var/run/docker.sock:/var/run/docker.sock 来完成，所以我们要用
sudo ln -s /var/run/docker.sock /volume1/docker/docker.sock 把你当前群晖的 docker.sock 映射到 docker 共享目录（我安装在了 volume1 ），同时为避免重启后软链会消失，需要把它加到计划任务中。

转到 控制面板 –> 任务计划

新增 –> 计划的任务 –> 用户定义的脚本

在 创建任务 窗口的 常规 选项卡上，确保将 用户账号 选择为 root，填入 任务名称

在 创建任务 窗口的 计划 选项卡上，在 日期 –> 在以下的天中运行 下，选择 每日 。在 时间 –> 运行频率 下，选择 每1小时

在 创建任务 窗口的 任务设置 选项卡上，在 运行命令 –> 用户定义的脚本中，粘贴 sudo ln -s /var/run/docker.sock /volume1/docker/docker.sock 到文本框中，然后按 确定

在新创建的任务，右键单击 运行 立即运行一次

需要确认

解决问题
软链接在 File Station 是看不到的，所以我们不能再用 GUI 来修改或者创建了，但是命令行创建成功后，可以在 GUI 中查看

通过SSH进入Synology，运行以下docker run命令

1

docker run -d --restart="always" --name="nicolargo-glances1" -p 61208-61209:61208-61209 -e GLANCES_OPT="-w" -v /volume1/docker/docker.sock:/var/run/docker.sock:ro --pid host docker.io/nicolargo/glances

再回到浏览器，刷新一下

容器的信息已经有了，我们在 GUI 中 找到 nicolargo-glances1

先停止，然后进入编辑，是可以看到文件夹映射的

上

一、安装

以Docker安装方式为例：

使用docker compose:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

version: "3.3"
services:
  homepage:
    image: ghcr.io/gethomepage/homepage:latest
    container_name: homepage
    environment:
      HOMEPAGE_ALLOWED_HOSTS: x.x.x.x:3000/xxx.com #填写你的ip地址+端口号或者域名，二选一。如：192.168.1.100，此条为v1.04版后新加的环境参数，必须填写
      PUID: 1000 -- optional, your user id
      PGID: 1000 -- optional, your group id
    ports:
      - 3000:3000
    volumes:
      - /path/to/config:/app/config # Make sure your local config directory exists
      - /var/run/docker.sock:/var/run/docker.sock:ro # optional, for docker integrations
    restart: unless-stopped

使用Docker：

1
2
3
4
5
6
7
8
9

docker run --name homepage \
-e HOMEPAGE_ALLOWED_HOSTS=gethomepage.dev \
-e PUID=1000 \
-e PGID=1000 \
-p 3000:3000 \
-v /你的config目录:/app/config \
-v /var/run/docker.sock:/var/run/docker.sock:ro \
--restart unless-stopped \
ghcr.io/gethomepage/homepage:latest

非必要可选映射，一并添加到以上建立容器命令行中，作用是：增加本地icons图标库和本地图片库的映射目录，以便homepage在个人自定义时调用图片、图标。

1
2

-v /你的homepage/icons目录:/app/public/icons \
-v /你的/homepage/images目录:/app/public/images \

注意：HOMEPAGE_ALLOWED_HOSTS: x.x.x.x:3000/xxx.com #填写你的ip地址+端口号或者域名，二选一。如：192.168.1.100，此条为v1.04版后新加的环境参数，必须填写

有小伙伴喜欢单行命令行，不喜欢分段。这里一并喂饭：以下单挑命令行和上面分段部署是同样的功能，二选一。

1

docker run --name homepage -p 3000:3000 -v /你的config目录:/app/config -v /var/run/docker.sock:/var/run/docker.sock -v /你的homepage/icons目录:/app/public/icons -v /你的/homepage/images:/app/public/images ghcr.io/gethomepage/homepage:latest

二、Homepage主要配置文件功能介绍

1、settings.yaml

homepage的设置文件，用来设置：语言、布局、标题、favicon图标、背景图片等。

2、service.yaml

homepage的服务文件，用来设置：Docker或其他服务导航入口等。

3、widgets.yaml

homepage的小组件文件，用来设置：功能显示如：CPU、内存占用率、温度、上线时间等；搜索框、天气、日期和时间等。

4、bookmarks.yaml

homepage的书签文件，用来设置：网站收藏书签、书签图标、url等。

三、常用功能设置

1、settings.yaml

语言设置，如：简体中文

1

language: zh-CN

其他语言，按需设置：

ca, de, en, es, fr, he, hr, hu, it, nb-NO, nl, pt, ru, sv, vi, zh-CN, zh-Hant

标题设置，如：your title换成你需要的名字

1

title: your title

网页图标favicon设置，支持本地/http图片

1

favicon: https://www.baidu.com/favicon.ico

背景图片设置（重点：从此处开始，多参数分段设置中，一定要注意层级关系，下层要比上层靠后比如多个空格（不能用制表符tab），同层对齐。否则会运行错乱）如下：

1
2
3
4
5
6

background:
  image: http://xxxxx.jpg
  blur: sm # sm, "", md, xl… see https://tailwindcss.com/docs/backdrop-blur
  saturate: 50 # 0, 50, 100… see https://tailwindcss.com/docs/backdrop-saturate
  brightness: 50 # 0, 50, 75… see https://tailwindcss.com/docs/backdrop-brightness
  opacity: 50 # 0-100

注：如仅需要1张图片做背景，无需风格，则保留image: http://xxxxx.jpg即可。下面依次为：模糊度、饱和度、亮度、不透明度。默认参数值如上。

布局设置每个人需求不同，按个人喜好自己搞吧。

2、services.yaml

官方给出的实例如下：

1
2
3
4
5
6
7

- Group A:
    - Service A:
        href: http://localhost/

- Group B:
    - Service B:
        href: http://localhost/

以下为我们习惯的表述方式；

1
2
3
4
5
6

- 媒体影音:
    - EmbyServer:
        icon: emby.png
        href: http://x.x.x.x:8096/ # Emby IP:8096
        description: Movies & TV Shows
        ping: 127.0.0.1 # Emby IP

注1：层级，Group组和Service服务之前要用-，且上下级空格排列，下面参数要多几个空格对齐。

注2：homepage内置自带图标集合。使用的是如下开源图标集：

https://github.com/walkxcode/dashboard-icons

我们可以在icon参数中，直接调用。只要是以上图标集中存在的图标即可。具体操作见视频

注3：href中url结尾有/ 比如http://xxxx:1234/，与之后添加组件widget中的url不需要加/，两者是不同的

注4：description: 服务描述，可中/英文添加此服务的描述。

还有常见的几个services.yaml中的参数如下：

ping: x.x.x.x 或者 xxx.com/www.xxx.com IP地址或者域名都可以，测试添加http或者https，结尾添加端口也没问题比如https://ikuai.myddns.com:12345 结尾不要/

widget: 注意这里要区分，这是service服务的小组件，它是针对该服务的功能组件。与homepage的widgets.yaml组件是不同的。

举个例子：

1
2
3
4
5
6
7
8
9
10
11
12

- 媒体影音:
    - EmbyServer:
        icon: emby.png
        href: http://x.x.x.x:8096/ # Emby IP:8096
        description: Movies & TV Shows
        ping: 127.0.0.1 # Emby IP
        widget:
          type: emby
          url: http://x.x.x.x:8096
          key: xxxxxxxxxxxxxxxxxxxxxxxxxxxxx
          enableBlocks: true # optional, defaults to false
          enableNowPlaying: true # optional, defaults to true

注：type: emby 指定这个组件是emby的，

url: Emby服务器的IP和端口号，注意此处不用/结尾

key: 需要去EmbyServer中设置—高级——API密钥中生成，

enableBlocks: 使能功能模块可以查看Emby中的剧集、影片等数据。默认是关闭的；

enableNowPlaying: 使能正在播放模块，可以查看Emby正在播放的影片，并且可以控制暂定和继续播放，默认是关闭的。

Homepage支持的服务非常多，每个具体的widget组件参数设置均不相同，具体可以查看：

https://gethomepage.dev/latest/configs/service-widgets/

支持的组件列表：https://gethomepage.dev/latest/widgets/

对于Docker服务有几个常用的参数如下：

以下这两参数是用在Docker服务上的，需要在docker.yaml中添加docker.sock的映射，具体操作见视频

1
2

server: my-server
container: my-container

以上两个参数添加后，Docker服务可以查看服务详情

Docker服务可添加自动展开服务详情的参数

1

showStats: true

3、widgets.yaml 此为homepage的功能组件，注意和service的widgets服务组件参数区分。

1
2
3
4

- resources:
    cpu: true
    memory: true
    disk: /

以上为默认的设置，还有常用的参数如下：添加时注意参数对齐

1
2
3

cputemp: true # disabled by default
uptime: true # disabled by default
expanded: true # show the expanded view

比如上线时间、CPU使用率、温度范围最低最高等扩展显示

1
2
3

- search:
    provider: baidu
    target: _blank

以上为搜索框设置，可选搜索引擎：如百度、谷歌等，_blank搜索结果开新页面显示

1
2
3
4
5
6
7

- openmeteo:
    label: 上海 # optional
    latitude: 31.2222
    longitude: 121.4581
    timezone: Asia/Shanghai # optional
    units: metric # or imperial
    cache: 5 # Time in minutes to cache API responses, to stay within limits

以上为天气组件：openmeteo，需要打开以下网站：

https://open-meteo.com/en/docs

根据您的所在区域，查找到经纬度和时区并添加到以上参数中。具体操作见我的视频

1
2
3
4
5
6
7

- openmeteo:
    label: 上海 # optional
    latitude: 31.2222
    longitude: 121.4581
    timezone: Asia/Shanghai # optional
    units: metric # or imperial
    cache: 5 # Time in minutes to cache API responses, to stay within limits

以上为日期和时间设置。有长短显示格式之分。12/24小时之分。具体可以见

https://gethomepage.dev/latest/widgets/info/datetime/

4、bookmarks.yaml

官方给出的默认实例如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

- Developer:
    - Github:
        - abbr: GH
          href: https://github.com/

- Social:
    - Reddit:
        - icon: reddit.png
          href: https://reddit.com/
          description: The front page of the internet

- Entertainment:
    - YouTube:
        - abbr: YT
          href: https://youtube.com/

第一行-为标签分类，第二行-为网站，下面-跟的是设置参数

• icon: 网页图标，可使用内置图标（如上面官方示例中的- icon: reddit.png）具体支持的图标可以查看：https://github.com/walkxcode/dashboard-icons

也可使用http/https网页图标，如：https://www.baidu.com/favicon.ico

• abbr: 后加字母缩写，比如GitHub，可以缩写为GH，随意，仅作标识助记之用。

href: 后加网站url，以/结尾

下

一、PVE组件设置

1、在service.yaml中添加如下

1
2
3
4
5
6
7

在PVE模块下方添加以下组件代码
    widget:
      type: proxmox
      url: https://x.x.x.x:8006
      username: api_token_id
      password: api_token_secret
      node: pve # optional

2、PVE中添加群组、用户、API令牌并为其添加权限

二、Portainer组件设置

1、在service.yaml中添加如下

1
2
3
4
5
6

在Portainer模块下方添加以下组件代码
    widget:
      type: portainer
      url: https://portainer.host.or.ip:9443
      env: 1
      key: ptr_accesskeyaccesskeyaccesskeyaccesskey

2、在Portainer中添加令牌

三、EmbyServer组件设置

见上Emby部分

四、群晖及Download Station组件设置

1、在service.yaml中添加如下

1
2
3
4
5
6
7
8
9
10
11
12
13
14

#在群晖模块下方添加以下组件代码
widget:
  type: diskstation
  url: http://diskstation.host.or.ip:port
  username: username
  password: password
  volume: volume_N # optional

#在Download Station模块下方添加以下组件代码
widget:
  type: downloadstation
  url: http://downloadstation.host.or.ip:port
  username: username
  password: password

2、在群晖中添加管理员用户、设置目录访问和应用管理权限

详细操作见以上《下集》视频详情

五、系统资源监控仪表盘安装及设置

1、安装glances系统资源监控工具，推荐使用docker版，安装命令行如下：

1

docker run --name glances -d --restart="always" -p 61208-61209:61208-61209 -e GLANCES_OPT="-w" -v /opt/docker/glances/glances.conf:/glances/conf/glances.conf -v /:/host:ro -v /var/run/docker.sock:/var/run/docker.sock:ro --pid host nicolargo/glances:latest-full

注意：以上glances使用了最新的镜像，最新4.x版本与之前3.x版本不同，在homepage中默认的是glances3.x，需要添加4.x支持参数，否则在读取资源监控信息的时候全部报错，无法获得数据。

2、设置仪表盘布局

打开settings.yaml文件，添加如下

1
2
3
4
5

layout:
  Moniter:
    style: row
    columns: 4
    header: false #不显示表头

3、在service.yaml中添加如下

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49

- Moniter:
    - 系统信息:
        widget:
          type: glances
          url: http://x.x.x.x:61208
          metric: info
          version: 4 #homepage默认为glances3.x模式，如用最新4.xglances必须加此参数
    - 处理器:
        widget:
          type: glances
          url: http://x.x.x.x:61208
          metric: cpu
          version: 4
    - 内存:
        widget:
          type: glances
          url: http://x.x.x.x:61208
          metric: memory
          version: 4
    - 进程:
        widget:
          type: glances
          url: http://x.x.x.x:61208
          metric: process
          version: 4
    - 网络:
        widget:
          type: glances
          url: http://x.x.x.x:61208
          metric: network:eth0
          version: 4
    - 硬盘:nvme0n1:
        widget:
          type: glances
          url: http://x.x.x.x:61208
          metric: disk:nvme0n1
          version: 4
    - 传感器:
        widget:
          type: glances
          url: x.x.x.x:61208
          metric: sensor:Package id 0
          version: 4
    - 文件系统:
        widget:
          type: glances
          url: x.x.x.x:61208
          metric: fs:/host
          version: 4

详细操作见以上《下集》视频详情

总结：以上主要4个yaml文件设置完成，Homepage的基础功能可以基本满足小伙伴们的需求。另外很多服务的功能组件设置比较复杂，需要逐一设置，比如Portainer、Emby、PVE等都是需要进入他们的管理页面，去设置API、Key、或者建立用户组和用户，开通需要的权限，否则组件不能用。也有部分服务有坑，比如群晖，按照官方流程操作下来，正确的用户名和密码，在群晖组件中运行会报400错误（用户或密码错误）认证识别而没有权限读取数据。这和服务本身有直接关系。老高抛砖引玉，期待各路大神小伙伴们分享更多Homepage的玩法。

snowdreamtech/frps

Docker Images for Frp Based on Alpine and Debian.

(amd64, arm32v5, arm32v6, arm32v7, arm64v8, i386, mips64le, ppc64le,riscv64, s390x)

Documentation⁠

中文文档⁠

Usage

Basic

1
2

docker run --restart=always --network host -d -v /etc/frp/frps.toml:/etc/frp/frps.toml --name frps snowdreamtech/frps
docker run --restart=always --network host -d -v /etc/frp/frpc.toml:/etc/frp/frpc.toml --name frpc snowdreamtech/frpc

Alpine

1
2

docker run --restart=always --network host -d -v /etc/frp/frps.toml:/etc/frp/frps.toml --name frps snowdreamtech/frps:alpine
docker run --restart=always --network host -d -v /etc/frp/frpc.toml:/etc/frp/frpc.toml --name frpc snowdreamtech/frpc:alpine

Debian

1
2

docker run --restart=always --network host -d -v /etc/frp/frps.toml:/etc/frp/frps.toml --name frps snowdreamtech/frps:debian
docker run --restart=always --network host -d -v /etc/frp/frpc.toml:/etc/frp/frpc.toml --name frpc snowdreamtech/frpc:debian

1
2

docker run --restart=always --network host -d -v /etc/frp/frps.toml:/etc/frp/frps.toml --name frps snowdreamtech/frps:bookworm
docker run --restart=always --network host -d -v /etc/frp/frpc.toml:/etc/frp/frpc.toml --name frpc snowdreamtech/frpc:bookworm

Quick reference

• Where to file issues:

https://github.com/snowdreamtech/frp/issues⁠

• Where to join discussions:

https://github.com/snowdreamtech/frp/discussions⁠

• Maintained by:

snowdream sn0wdr1am@qq.com⁠

• Supported architectures: (more info⁠)

Alpine (linux/386,linux/amd64,linux/arm/v6,linux/arm/v7,linux/arm64,linux/ppc64le,linux/riscv64,linux/s390x)

Debian (linux/386,linux/amd64,linux/arm/v5,linux/arm/v7,linux/arm64,linux/mips64le,linux/ppc64le,linux/s390x)

• Supported Tags:

Alpine:

1
2
3
4
5
6
7
8
9
10

- latest
- 0.62-alpine3.21
- 0.63.0-alpine3.21
- 0.62-alpine
- 0.63.0-alpine
- alpine3.21
- alpine
- 0.62
- 0.63.0

Debian:

1
2
3
4
5
6

- bookworm
- debian
- 0.62-bookworm
- 0.63.0-bookworm
- 0.62-debian
- 0.63.0-debian

概览

一些概述，便于您快速的了解 frp。

frp 是什么？

frp 是一款高性能的反向代理应用，专注于内网穿透。它支持多种协议，包括 TCP、UDP、HTTP、HTTPS 等，并且具备 P2P 通信功能。使用 frp，您可以安全、便捷地将内网服务暴露到公网，通过拥有公网 IP 的节点进行中转。

为什么选择 frp？

通过在具有公网 IP 的节点上部署 frp 服务端，您可以轻松地将内网服务穿透到公网，并享受以下专业特性：

• 多种协议支持：客户端服务端通信支持 TCP、QUIC、KCP 和 Websocket 等多种协议。
• TCP 连接流式复用：在单个连接上承载多个请求，减少连接建立时间，降低请求延迟。
• 代理组间的负载均衡。
• 端口复用：多个服务可以通过同一个服务端端口暴露。
• P2P 通信：流量不必经过服务器中转，充分利用带宽资源。
• 客户端插件：提供多个原生支持的客户端插件，如静态文件查看、HTTPS/HTTP 协议转换、HTTP、SOCKS5 代理等，以便满足各种需求。
• 服务端插件系统：高度可扩展的服务端插件系统，便于根据自身需求进行功能扩展。
• 用户友好的 UI 页面：提供服务端和客户端的用户界面，使配置和监控变得更加方便。

安装

关于如何安装 frp 的说明。

frp 采用 Go 语言编写，支持跨平台，只需下载适用于您平台的二进制文件即可执行，无需额外依赖。

系统需求

由于采用 Go 语言编写，因此系统需求与最新的 Go 语言对系统和平台的要求一致，具体请参考 Golang System requirements。

下载

您可以从 GitHub 的 Release 页面中下载最新版本的客户端和服务器二进制文件。所有文件都打包在一个压缩包中，还包含了一份完整的配置参数说明。

部署

1. 解压下载的压缩包。
2. 将 frpc 复制到内网服务所在的机器上。
3. 将 frps 复制到拥有公网 IP 地址的机器上，并将它们放在任意目录。

开始使用！

1. 编写配置文件，目前支持的文件格式包括 TOML/YAML/JSON，旧的 INI 格式仍然支持，但已经不再推荐。
2. 使用以下命令启动服务器：./frps -c ./frps.toml。
3. 使用以下命令启动客户端：./frpc -c ./frpc.toml。
4. 如果需要在后台长期运行，建议结合其他工具，如 systemd 和 supervisor。

如果您是 Windows 用户，需要在命令提示符中执行相同的命令。

有关如何编写配置文件，请参考 示例 部分中的内容。

完整的配置项说明，请参考 Reference 中的内容。

使用 systemd

此示例演示如何在 Linux 系统下使用 systemd 来管理 frps 服务，包括启动、停止、配置后台运行和设置开机自启动。

在 Linux 系统下，使用 systemd 可以方便地控制 frps 服务端的启动、停止、配置后台运行以及开机自启动。

以下是具体的操作步骤：

1. 安装 systemd

   如果您的 Linux 服务器上尚未安装 systemd，可以使用包管理器如 yum（适用于 CentOS/RHEL）或 apt（适用于 Debian/Ubuntu）来安装它：

   1 2 3 4 5 6

   # 使用 yum 安装 systemd（CentOS/RHEL） yum install systemd # 使用 apt 安装 systemd（Debian/Ubuntu） apt install systemd

2. 创建 frps.service 文件

   使用文本编辑器 (如 vim) 在 /etc/systemd/system 目录下创建一个 frps.service 文件，用于配置 frps 服务。

   1 2	$ sudo vim /etc/systemd/system/frps.service

   写入内容

   1 2 3 4 5 6 7 8 9 10 11 12 13 14

   [Unit] # 服务名称，可自定义 Description = frp server After = network.target syslog.target Wants = network.target [Service] Type = simple # 启动frps的命令，需修改为您的frps的安装路径 ExecStart = /path/to/frps -c /path/to/frps.toml [Install] WantedBy = multi-user.target

3. 使用 systemd 命令管理 frps 服务

   1 2 3 4 5 6 7 8 9

   # 启动frp sudo systemctl start frps # 停止frp sudo systemctl stop frps # 重启frp sudo systemctl restart frps # 查看frp状态 sudo systemctl status frps

4. 设置 frps 开机自启动

   1 2	sudo systemctl enable frps

通过遵循上述步骤，您可以轻松地使用 systemd 来管理 frps 服务，实现启动、停止、自动运行和开机自启动。确保替换路径和配置文件名称以匹配您的实际安装。

概念

了解以下概念有助于更好地理解和使用 frp。

工作原理

frp 主要由两个组件组成：客户端(frpc) 和 服务端(frps)。通常情况下，服务端部署在具有公网 IP 地址的机器上，而客户端部署在需要穿透的内网服务所在的机器上。

由于内网服务缺乏公网 IP 地址，因此无法直接被非局域网内的用户访问。用户通过访问服务端的 frps，frp 负责根据请求的端口或其他信息将请求路由到相应的内网机器，从而实现通信。

代理

在 frp 中，一个代理对应一个需要公开访问的内网服务。一个客户端可以同时配置多个代理，以满足不同的需求。

代理类型

frp 支持多种代理类型，以适应不同的使用场景。以下是一些常见的代理类型：

• TCP：提供纯粹的 TCP 端口映射，使服务端能够根据不同的端口将请求路由到不同的内网服务。
• UDP：提供纯粹的 UDP 端口映射，与 TCP 代理类似，但用于 UDP 流量。
• HTTP：专为 HTTP 应用设计，支持修改 Host Header 和增加鉴权等额外功能。
• HTTPS：类似于 HTTP 代理，但专门用于处理 HTTPS 流量。
• STCP：提供安全的 TCP 内网代理，要求在被访问者和访问者的机器上都部署 frpc，不需要在服务端暴露端口。
• SUDP：提供安全的 UDP 内网代理，与 STCP 类似，需要在被访问者和访问者的机器上都部署 frpc，不需要在服务端暴露端口。
• XTCP：点对点内网穿透代理，与 STCP 类似，但流量不需要经过服务器中转。
• TCPMUX：支持服务端 TCP 端口的多路复用，允许通过同一端口访问不同的内网服务。

每种代理类型适用于不同的使用情境，您可以根据需求选择合适的代理类型来配置 frp。

通过 SSH 访问内网机器

通过简单配置 TCP 类型的代理，使用户能够访问内网服务器。

步骤

1. 在具有公网 IP 的机器上部署 frps

   部署 frps 并编辑 frps.toml 文件。以下是简化的配置，其中设置了 frp 服务器用于接收客户端连接的端口：

   1 2	bindPort = 7000

2. 在需要被访问的内网机器上部署 frpc

   部署 frpc 并编辑 frpc.toml 文件，假设 frps 所在服务器的公网 IP 地址为 x.x.x.x。以下是示例配置：

   1 2 3 4 5 6 7 8 9 10

   serverAddr = "x.x.x.x" serverPort = 7000 [[proxies]] name = "ssh" type = "tcp" localIP = "127.0.0.1" localPort = 22 remotePort = 6000

   • localIP 和 localPort 配置为需要从公网访问的内网服务的地址和端口。
   • remotePort 表示在 frp 服务端监听的端口，访问此端口的流量将被转发到本地服务的相应端口。

3. 启动 frps 和 frpc

4. 通过 SSH 访问内网机器

   使用以下命令通过 SSH 访问内网机器，假设用户名为 test：

   1 2	ssh -o Port=6000 test@x.x.x.x

   frp 将请求发送到 x.x.x.x:6000 的流量转发到内网机器的 22 端口。

多个 SSH 服务复用同一端口

通过使用 tcpmux 类型的代理，您可以实现多个 SSH 服务通过同一端口进行暴露。这种方法还适用于任何支持 HTTP Connect 代理连接方式的客户端，以实现端口的复用。

步骤

1. 在具有公网 IP 的机器上部署 frps

   修改 frps.toml 文件以包含以下内容（这里使用了最简化的配置）：

   1 2 3

   bindPort = 7000 tcpmuxHTTPConnectPort = 5002

2. 在内网机器 A 上部署 frpc

   创建 frpc 配置文件，例如 frpc.toml，然后将以下内容添加到配置文件中：

   1 2 3 4 5 6 7 8 9 10 11

   serverAddr = "x.x.x.x" serverPort = 7000 [[proxies]] name = "ssh1" type = "tcpmux" multiplexer = "httpconnect" customDomains = ["machine-a.example.com"] localIP = "127.0.0.1" localPort = 22

3. 在内网机器 B 上部署另一个 frpc

   创建 frpc 配置文件，例如 frpc.toml，然后将以下内容添加到配置文件中：

   1 2 3 4 5 6 7 8 9 10 11

   serverAddr = "x.x.x.x" serverPort = 7000 [[proxies]] name = "ssh2" type = "tcpmux" multiplexer = "httpconnect" customDomains = ["machine-b.example.com"] localIP = "127.0.0.1" localPort = 22

4. 通过 SSH ProxyCommand 访问内网机器 A

   使用 SSH ProxyCommand 访问内网机器 A，假设用户名为 test。使用以下命令：

   1 2	ssh -o 'proxycommand socat - PROXY:x.x.x.x:%h:%p,proxyport=5002' test@machine-a.example.com

   要访问内网机器 B，只需更改域名，假设用户名仍然为 test：

   1 2	ssh -o 'proxycommand socat - PROXY:x.x.x.x:%h:%p,proxyport=5002' test@machine-b.example.com

通过按照以上步骤进行配置，您可以实现多个 SSH 服务复用同一端口，以便在具有公网 IP 的机器上进行访问。

通过自定义域名访问内网的 Web 服务

通过简单配置 HTTP 类型的代理，您可以让用户通过自定义域名访问内网的 Web 服务。

HTTP 类型的代理非常适合将内网的 Web 服务通过自定义域名提供给外部用户。相比于 TCP 类型代理，HTTP 代理不仅可以复用端口，还提供了基于 HTTP 协议的许多功能。

HTTPS 与此类似，但是需要注意，frp 的 https 代理需要本地服务是 HTTPS 服务，frps 端不会做 TLS 终止。也可以结合 https2http 插件来实现将本地的 HTTP 服务以 HTTPS 协议暴露出去。

步骤

1. 配置 frps.toml

   在 frps.toml 文件中添加以下内容，以指定 HTTP 请求的监听端口为 8080：

   1 2 3

   bindPort = 7000 vhostHTTPPort = 8080

   如果需要配置 HTTPS 代理，还需要设置 vhostHTTPSPort。

2. 配置 frpc.toml

   在 frpc.toml 文件中添加以下内容，确保设置了正确的服务器 IP 地址、本地 Web 服务监听端口和自定义域名：

   1 2 3 4 5 6 7 8 9 10 11 12 13 14 15

   serverAddr = "x.x.x.x" serverPort = 7000 [[proxies]] name = "web" type = "http" localPort = 80 customDomains = ["www.yourdomain.com"] [[proxies]] name = "web2" type = "http" localPort = 8080 customDomains = ["www.yourdomain2.com"]

3. 启动 frps 和 frpc

4. 域名解析

   将 www.yourdomain.com 和 www.yourdomain2.com 的域名 A 记录解析到服务器的 IP 地址 x.x.x.x。如果服务器已经有对应的域名，您还可以将 CNAME 记录解析到原始域名。另外，通过修改 HTTP 请求的 Host 字段也可以实现相同的效果。

5. 通过浏览器访问

   使用浏览器访问 http://www.yourdomain.com:8080 即可访问内网机器上的 80 端口服务，访问 http://www.yourdomain2.com:8080 可以访问内网机器上的 8080 端口服务。

转发 DNS 查询请求

本示例演示如何通过简单配置 UDP 类型的代理来实现 DNS 查询请求的转发。

DNS 查询请求通常使用 UDP 协议，而 frp 支持对内网 UDP 服务的穿透，配置方式与 TCP 类似。

步骤

1. 配置 frps.toml

   在 frps.toml 文件中添加以下内容：

   1 2	bindPort = 7000

2. 配置 frpc.toml

   在 frpc.toml 文件中添加以下内容：

   1 2 3 4 5 6 7 8 9 10

   serverAddr = "x.x.x.x" serverPort = 7000 [[proxies]] name = "dns" type = "udp" localIP = "8.8.8.8" localPort = 53 remotePort = 6000

   请注意，这里示例中反代了 Google 的 DNS 查询服务器的地址，仅用于测试 UDP 代理，并没有实际意义。

3. 启动 frps 和 frpc

   分别启动 frps 和 frpc。

4. 测试 DNS 查询请求

   使用以下命令通过 dig 工具测试 UDP 包转发是否成功，预期会返回 www.baidu.com 域名的解析结果：

   1	dig @x.x.x.x -p 6000 www.baidu.com

转发 Unix 域套接字

通过配置 Unix 域套接字客户端插件，您可以使用 TCP 端口访问内网的 Unix 域套接字服务，例如 Docker Daemon。

步骤

1. 配置 frps.toml

   在 frps.toml 文件中添加以下内容：

   1 2	bindPort = 7000

2. 配置 frpc.toml

   在 frpc.toml 文件中添加以下内容，确保设置正确的 Unix 域套接字路径：

   1 2 3 4 5 6 7 8 9 10 11 12

   serverAddr = "x.x.x.x" serverPort = 7000 [[proxies]] name = "unix_domain_socket" type = "tcp" remotePort = 6000 [proxies.plugin] type = "unix_domain_socket" # Unix 域套接字路径 unixPath = "/var/run/docker.sock"

3. 启动 frps 和 frpc

4. 使用 curl 查看 Docker 版本信息

   1	curl http://x.x.x.x:6000/version

对外提供简单的文件访问服务

通过配置 static_file 客户端插件，您可以将本地文件暴露在公网上，以供其他人访问。

通过使用 static_file 插件，您可以轻松地提供一个基于 HTTP 的文件访问服务，让其他人可以访问您指定的文件。

步骤

1. 配置 frps.toml

   在 frps.toml 文件中添加以下内容：

   1 2	bindPort = 7000

2. 配置 frpc.toml

   在 frpc.toml 文件中添加以下内容，确保设置合适的文件路径、用户名和密码：

   1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16

   serverAddr = "x.x.x.x" serverPort = 7000 [[proxies]] name = "test_static_file" type = "tcp" remotePort = 6000 [proxies.plugin] type = "static_file" # 本地文件目录，对外提供访问 localPath = "/tmp/file" # URL 中的前缀，将被去除，保留的内容即为要访问的文件路径 stripPrefix = "static" httpUser = "abc" httpPassword = "abc"

   请根据实际情况修改 localPath、stripPrefix、httpUser 和 httpPassword。

3. 启动 frps 和 frpc

4. 通过浏览器访问文件

   使用浏览器访问 http://x.x.x.x:6000/static/，以查看位于 /tmp/file 目录下的文件。系统会要求输入您设置的用户名和密码。

为本地 HTTP 服务启用 HTTPS

使用 https2http 插件将本地 HTTP 服务转换为 HTTPS 服务，以供外部访问。

步骤

1. 配置 frps.toml

   1 2 3

   bindPort = 7000 vhostHTTPSPort = 443

2. 配置 frpc.toml

   1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18

   serverAddr = "x.x.x.x" serverPort = 7000 [[proxies]] name = "test_htts2http" type = "https" customDomains = ["test.yourdomain.com"] [proxies.plugin] type = "https2http" localAddr = "127.0.0.1:80" # HTTPS 证书相关的配置 crtPath = "./server.crt" keyPath = "./server.key" hostHeaderRewrite = "127.0.0.1" requestHeaders.set.x-from-where = "frp"

   请注意，您需要根据您的域名和证书路径自行更改上述配置。

3. 启动 frps 和 frpc

4. 访问 HTTPS 服务

   打开您的 Web 浏览器，访问 https://test.yourdomain.com。

通过按照以上步骤进行配置，您将能够为本地 HTTP 服务启用 HTTPS，以实现安全的外部访问。

安全地暴露内网服务

通过创建一个只有授权用户能够访问的 SSH 服务代理，实现内网服务的安全暴露。

某些内网服务，如果直接暴露在公网上，可能存在安全风险。使用 stcp(secret tcp) 类型的代理可以让您安全地将内网服务暴露给经过授权的用户，这需要访问者也部署 frpc 客户端。

步骤

1. 配置 frps.toml

   在 frps.toml 文件中添加以下内容：

   1 2	bindPort = 7000

2. 部署 frpc 客户端并配置

   在需要将内网服务暴露到公网的机器上部署 frpc，并创建如下配置：

   1 2 3 4 5 6 7 8 9 10 11

   serverAddr = "x.x.x.x" serverPort = 7000 [[proxies]] name = "secret_ssh" type = "stcp" # 只有与此处设置的 secretKey 一致的用户才能访问此服务 secretKey = "abcdefg" localIP = "127.0.0.1" localPort = 22

3. 在访问者机器上部署并配置 frpc

   在想要访问内网服务的机器上也部署 frpc，并创建如下配置：

   1 2 3 4 5 6 7 8 9 10 11 12 13

   serverAddr = "x.x.x.x" serverPort = 7000 [[visitors]] name = "secret_ssh_visitor" type = "stcp" # 要访问的 stcp 代理的名字 serverName = "secret_ssh" secretKey = "abcdefg" # 绑定本地端口以访问 SSH 服务 bindAddr = "127.0.0.1" bindPort = 6000

4. 通过 SSH 访问内网机器

   使用以下命令通过 SSH 访问内网机器，假设用户名为 test：

   1	ssh -o Port=6000 test@127.0.0.1

点对点内网穿透

这个示例将演示如何通过点对点 (P2P) 连接来访问内网服务，流量不会通过服务器中转。

frp 提供了一种新的代理类型 xtcp，用于在需要传输大量数据且不希望流量经过服务器的情况下实现内网穿透。

与 stcp 类似，使用 xtcp 需要在两端都部署 frpc 以建立直接连接。

需要注意的是，xtcp 并不适用于所有类型的 NAT 设备，如果穿透失败，可以尝试使用 stcp 代理。

步骤

1. 配置需要暴露到外网的机器上的 frpc.toml 文件

   在 frpc.toml 文件中添加以下内容，确保设置了正确的服务器地址和端口以及共享密钥 (secretKey)，以及本地服务的 IP 地址和端口：

   1 2 3 4 5 6 7 8 9 10 11 12 13

   serverAddr = "x.x.x.x" serverPort = 7000 # 如果默认的 STUN 服务器不可用，可以配置一个新的 STUN 服务器 # natHoleStunServer = "xxx" [[proxies]] name = "p2p_ssh" type = "xtcp" # 只有共享密钥 (secretKey) 与服务器端一致的用户才能访问该服务 secretKey = "abcdefg" localIP = "127.0.0.1" localPort = 22

2. 在想要访问内网服务的机器上部署 frpc

   在 frpc.toml 文件中添加以下内容，确保设置了正确的服务器地址和端口，共享密钥 (secretKey) 以及要访问的 P2P 代理的名称：

   1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17

   serverAddr = "x.x.x.x" serverPort = 7000 # 如果默认的 STUN 服务器不可用，可以配置一个新的 STUN 服务器 # natHoleStunServer = "xxx" [[visitors]] name = "p2p_ssh_visitor" type = "xtcp" # 要访问的 P2P 代理的名称 serverName = "p2p_ssh" secretKey = "abcdefg" # 绑定本地端口以访问 SSH 服务 bindAddr = "127.0.0.1" bindPort = 6000 # 如果需要自动保持隧道打开，将其设置为 true # keepTunnelOpen = false

3. 通过 SSH 访问内网机器

   使用 SSH 命令访问内网机器，假设用户名为 test：

   1	ssh -oPort=6000 test@127.0.0.1

虚拟网络 (VirtualNet)

使用 virtual_net 插件创建虚拟网络连接，实现客户端之间的 IP 层通信。

注意：VirtualNet 是一个 Alpha 阶段的特性，目前不稳定，其配置方式和功能可能会在后续版本中随时调整变更。请勿在生产环境中使用此功能，仅建议用于测试和评估目的。

概述

虚拟网络（VirtualNet）功能是 frp v0.62.0 中引入的 Alpha 特性，它允许 frp 通过 TUN 接口创建和管理客户端与访问者之间的虚拟网络连接，实现设备间的完整网络连通性。

本示例将展示如何配置和使用 VirtualNet 功能。更多详细信息和工作原理，请参考 虚拟网络 (VirtualNet) 特性文档。

启用 VirtualNet

首先，由于 VirtualNet 目前是一个 Alpha 特性，您需要在配置中通过特性门控来启用它：

1
2
3

# frpc.toml
featureGates = { VirtualNet = true }

示例配置

以下示例展示如何在两台机器之间建立虚拟网络连接：

服务端配置 (机器 A)

1. 在 frpc.toml 中配置虚拟网络地址

   1 2 3 4 5 6 7 8 9 10 11 12 13 14 15

   # frpc.toml (服务端) serverAddr = "x.x.x.x" serverPort = 7000 featureGates = { VirtualNet = true } # 配置虚拟网络接口 virtualNet.address = "100.86.0.1/24" [[proxies]] name = "vnet-server" type = "stcp" secretKey = "your-secret-key" [proxies.plugin] type = "virtual_net"

2. 启动 frpc

   1 2	sudo frpc -c frpc.toml

   注意：创建 TUN 接口需要 root 权限

客户端配置 (机器 B)

1. 在 frpc.toml 中配置访问者

   1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18

   # frpc.toml (客户端) serverAddr = "x.x.x.x" serverPort = 7000 featureGates = { VirtualNet = true } # 配置虚拟网络接口 virtualNet.address = "100.86.0.2/24" [[visitors]] name = "vnet-visitor" type = "stcp" serverName = "vnet-server" secretKey = "your-secret-key" bindPort = -1 [visitors.plugin] type = "virtual_net" destinationIP = "100.86.0.1"

2. 启动 frpc

   1 2	sudo frpc -c frpc.toml

测试连接

成功配置后，您可以从机器 B 通过虚拟 IP 地址访问机器 A：

1
2
3

# 在机器 B 上执行
ping 100.86.0.1

如果连接正常，您将看到来自 100.86.0.1 的响应。

限制和要求

• Alpha 阶段特性：VirtualNet 是实验性功能，配置和 API 可能在未来版本中变化，不建议在生产环境中使用
• 权限要求：创建 TUN 接口需要提升的权限（root/管理员）
• 平台支持：目前仅支持 Linux 和 macOS
• 默认状态：作为 Alpha 特性，VirtualNet 默认是禁用的

配置文件

从 v0.52.0 版本开始，frp 开始支持 TOML、YAML 和 JSON 作为配置文件格式。

请注意，INI 已被弃用，并将在未来的发布中移除。新功能只能在TOML、YAML 或 JSON 中使用。希望使用这些新功能的用户应相应地切换其配置格式。

格式

可使用 TOML/YAML/JSON 任何一个您喜欢的格式来编写配置文件，frp 会自动适配进行解析。

文档示例主要通过 TOML 编写，如下的示例配置将本地 SSH 服务穿透到公网。

frps 配置：

1
2

bindPort = 7000

frpc 配置：

1
2
3
4
5
6
7
8
9
10

serverAddr = "x.x.x.x"
serverPort = 7000

[[proxies]]
name = "ssh"
type = "tcp"
localIP = "127.0.0.1"
localPort = 22
remotePort = 6000

同一个客户端可以配置多个代理，但是 name 必须确保唯一。

不同的客户端之间，可以通过配置不同的 user 来确保代理名称唯一。

模版渲染

配置文件支持使用环境变量进行模版渲染，模版格式采用 Go 的标准格式。

示例配置如下：

1
2
3
4
5
6
7
8
9
10

serverAddr = "{{ .Envs.FRP_SERVER_ADDR }}"
serverPort = 7000

[[proxies]]
name = "ssh"
type = "tcp"
localIP = "127.0.0.1"
localPort = 22
remotePort = {{ .Envs.FRP_SSH_REMOTE_PORT }}

启动 frpc 程序：

1
2
3
4

export FRP_SERVER_ADDR="x.x.x.x"
export FRP_SSH_REMOTE_PORT="6000"
./frpc -c ./frpc.toml

frpc 会自动使用环境变量渲染配置文件模版，所有环境变量需要以 .Envs 为前缀。

YAML 锚点和引用

frp 支持 YAML 合并功能（锚点和引用，包括点前缀字段），在严格配置模式下无需使用 --strict-config=false 参数即可正常工作。

可以使用以点开头的字段作为锚点定义，类似于 Docker Compose 的 x- 前缀：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

# frpc.yaml
.common: &common
  type: "stcp"
  secretKey: "{{.Envs.FRPC_SECRET_KEY}}"
  localIP: "127.0.0.1"

serverAddr: "x.x.x.x"
serverPort: 7000

proxies:
  - name: "ssh"
    localPort: 22
    <<: *common

  - name: "web"
    localPort: 80
    <<: *common

配置校验

通过执行 frpc verify -c ./frpc.toml 或 frps verify -c ./frps.toml 可以对配置文件中的参数进行预先校验。

1
2

frpc: the configuration file ./frpc.toml syntax is ok

如果出现此结果，则说明新的配置文件没有错误，否则会输出具体的错误信息。

严格模式校验

默认情况下，frp 使用严格模式进行配置校验。如果需要禁用严格校验，可以使用 --strict-config=false 参数：

1
2

frpc verify -c ./frpc.yaml --strict-config=false

配置拆分

通过 includes 参数可以在主配置中包含其他配置文件，从而实现将代理配置拆分到多个文件中管理。

1
2
3
4
5

# frpc.toml
serverAddr = "x.x.x.x"
serverPort = 7000
includes = ["./confd/*.toml"]

1
2
3
4
5
6
7
8

# ./confd/test.toml
[[proxies]]
name = "ssh"
type = "tcp"
localIP = "127.0.0.1"
localPort = 22
remotePort = 6000

上述配置在 frpc.toml 中通过 includes 额外包含了 ./confd 目录下所有的 toml 文件的代理配置内容，效果等价于将这两个文件合并成一个文件。

需要注意的是 includes 指定的文件中只能包含代理配置，通用参数的配置只能放在主配置文件中。

完整配置参数

由于 frp 目前支持的功能和配置项较多，未在文档中列出的功能参数可以在 参考 中查看。

监控

目前，frps 服务端支持两种监控系统：内存监控和 Prometheus 监控。

内存监控

内存中存储的监控数据主要用于 Dashboard 展示。当在 frps 配置中开启 Dashboard 功能后，内存监控默认启用。

请注意，内存中的监控数据在每次重启进程后会被清空，或者保留 7 天。监控数据可以通过 Dashboard 的地址发送 HTTP 请求获取，但目前此 API 尚不规范，不建议直接使用。

Prometheus 监控

由于设计问题，Prometheus 对外提供的查询接口与 Dashboard 的地址重用，因此要使用 Prometheus 监控，必须首先启用 Dashboard。

在 frps.ini 中启用 Dashboard 并设置 enablePrometheus = true，然后你可以通过访问 http://{dashboard_addr}/metrics 来获取 Prometheus 的监控数据。

最后修改 August 11, 2025: docs: add tokenSource documentation for 

身份认证

目前 frpc 和 frps 之间支持两种身份验证方式，token 和 oidc，默认为 token。这些认证方式允许您验证客户端与服务端之间的通信，并确保只有授权用户能够建立连接。

Token

Token 身份认证是一种简单的身份认证方式，只需要在 frp 的客户端 frpc 和服务端 frps 配置文件中配置相同的 token 即可。

配置示例

1
2
3
4

# frps.toml
bindPort = 7000
auth.token = "abc"

1
2
3

# frpc.toml
auth.token = "abc"

从文件加载 Token

Added in v0.64.0

frp 支持使用 tokenSource 从文件中加载认证 token，而不是在配置文件中硬编码。这个功能可以避免在配置文件中直接暴露敏感信息。

配置方式

tokenSource 与 token 字段互斥，只能选择其中一种方式配置。

服务端配置示例：

1
2
3
4
5

# frps.toml
bindPort = 7000
auth.tokenSource.type = "file"
auth.tokenSource.file.path = "/etc/frp/server_token"

客户端配置示例：

1
2
3
4

# frpc.toml
auth.tokenSource.type = "file"
auth.tokenSource.file.path = "/etc/frp/client_token"

注意事项

1. token 文件应该设置适当的权限（如 600），确保只有运行 frp 的用户可以读取
2. 文件中的 token 会自动去除首尾空白字符
3. tokenSource 在配置加载时解析，不支持运行时动态重新加载
4. 目前仅支持 file 类型的 tokenSource

OIDC (OpenID Connect) 身份认证

OIDC 身份认证是一种基于开放标准的身份认证方式，它通过使用 OIDC 提供者进行身份验证。

验证流程参考 Client Credentials Grant。

配置示例

1
2
3
4
5

# frps.toml
auth.method = "oidc"
auth.oidc.issuer = "https://example-oidc-issuer.com/"
auth.oidc.audience = "https://oidc-audience.com/.default"

1
2
3
4
5
6

# frpc.toml
auth.method = "oidc"
auth.oidc.clientID = "98692467-37de-409a-9fac-bb2585826f18"
auth.oidc.clientSecret = "oidc_secret"
auth.oidc.audience = "https://oidc-audience.com/.default"
auth.oidc.tokenEndpointURL = "https://example-oidc-endpoint.com/oauth2/v2.0/token"

Web 界面

目前 frpc 和 frps 分别内置了相应的 Web 界面方便用户使用。

服务端 Dashboard

服务端 Dashboard 使用户可以通过浏览器查看 frp 的状态以及代理统计信息。

注：Dashboard 尚未针对大量的 proxy 数据展示做优化，如果出现 Dashboard 访问较慢的情况，请不要启用此功能。

需要在 frps.toml 中指定 dashboard 服务使用的端口，即可开启此功能：

1
2
3
4
5
6
7

# 默认为 127.0.0.1，如果需要公网访问，需要修改为 0.0.0.0。
webServer.addr = "0.0.0.0"
webServer.port = 7500
# dashboard 用户名密码，可选，默认为空
webServer.user = "admin"
webServer.password = "admin"

打开浏览器通过 http://[server addr]:7500 访问 Dashboard 界面，输入用户名密码 admin。

你也可以通过配置 TLS 证书来启用 HTTPS 接口:

1
2
3

webServer.tls.certFile = "server.crt"
webServer.tls.keyFile = "server.key"

客户端管理界面

frpc 内置的 Admin UI 可以帮助用户通过浏览器来查询和管理客户端的 proxy 状态和配置。

需要在 frpc.toml 中指定 admin 服务使用的端口，即可开启此功能：

1
2
3
4
5
6

# frpc.toml
webServer.addr = "127.0.0.1"
webServer.port = 7400
webServer.user = "admin"
webServer.password = "admin"

打开浏览器通过 http://127.0.0.1:7400 访问 Admin UI。

如果想要在外网环境访问 Admin UI，可以将 7400 端口通过 frp 映射出去即可，但需要重视安全风险。

1
2
3
4
5
6

# frpc.toml
[[proxies]]
name = "admin_ui"
type = "tcp"
localPort = 7400
remotePort = 7400

通信安全及优化

加密与压缩

注: 当 frpc 和 frps 之间启用了 TLS 之后，流量会被全局加密，不再需要配置单个代理上的加密，新版本中已经默认启用。

每一个代理都可以选择是否启用加密和压缩的功能。

加密算法采用 aes-128-cfb，压缩算法采用 snappy。

在每一个代理的配置中使用如下参数指定：

1
2
3
4
5
6
7
8

[[proxies]]
name = "ssh"
type = "tcp"
localPort = 22
remotePort = 6000
transport.useEncryption = true
transport.useCompression = true

通过设置 transport.useEncryption = true，将 frpc 与 frps 之间的通信内容加密传输，将会有效防止传输内容被截取。

如果传输的报文长度较长，通过设置 transport.useCompression = true 对传输内容进行压缩，可以有效减小 frpc 与 frps 之间的网络流量，加快流量转发速度，但是会额外消耗一些 CPU 资源。

TCP 多路复用

客户端和服务器端之间的连接支持多路复用，不再需要为每一个用户请求创建一个连接，使连接建立的延迟降低，并且避免了大量文件描述符的占用，使 frp 可以承载更高的并发数。

该功能默认启用，如需关闭，可以在 frps.toml 和 frpc.toml 中配置，该配置项在服务端和客户端必须一致：

1
2
3

# frps.toml 和 frpc.toml 中
transport.tcpMux = false

连接池

默认情况下，当用户请求建立连接后，frps 才会请求 frpc 主动与后端服务建立一个连接。当为指定的代理启用连接池后，frp 会预先和后端服务建立起指定数量的连接，每次接收到用户请求后，会从连接池中取出一个连接和用户连接关联起来，避免了等待与后端服务建立连接以及 frpc 和 frps 之间传递控制信息的时间。

这一功能适合有大量短连接请求时开启。

注: 当 TCP 多路复用启用后，连接池的提升有限，一般场景下无需关心。

1. 首先可以在 frps.toml 中设置每个代理可以创建的连接池上限，避免大量资源占用，客户端设置超过此配置后会被调整到当前值：

   1 2 3

   # frps.toml transport.maxPoolCount = 5

2. 在 frpc.toml 中为客户端启用连接池，指定预创建连接的数量：

   1 2 3

   # frpc.toml transport.poolCount = 1

支持 KCP 协议

底层通信协议支持选择 KCP 协议，相比于 TCP，在弱网环境下传输效率提升明显，但是会有一些额外的流量消耗。

开启 KCP 协议支持：

1. 在 frps.toml 中启用 KCP 协议支持，指定一个 UDP 端口用于接收客户端请求：

   1 2 3 4 5

   # frps.toml bindPort = 7000 # kcp 绑定的是 UDP 端口，可以和 bindPort 一样 kcpBindPort = 7000

2. 在 frpc.toml 指定需要使用的协议类型，其他代理配置不需要变更：

   1 2 3 4 5 6

   # frpc.toml serverAddr = "x.x.x.x" # serverPort 指定为 frps 的 kcpBindPort serverPort = 7000 transport.protocol = "kcp"

支持 QUIC 协议

底层通信协议支持选择 QUIC 协议，底层采用 UDP 传输，解决了 TCP 上的一些问题，传输效率更高，连接延迟低。

开启 QUIC 协议支持：

1. 在 frps.toml 中启用 QUIC 协议支持，指定一个 UDP 端口用于接收客户端请求：

   1 2 3 4 5

   # frps.toml bindPort = 7000 # QUIC 绑定的是 UDP 端口，可以和 bindPort 一样 quicBindPort = 7000

2. 在 frpc.toml 指定需要使用的协议类型，其他代理配置不需要变更：

   1 2 3 4 5

   # frpc.toml serverAddr = "x.x.x.x" # serverPort 指定为 frps 的 quicBindPort serverPort = 7000 transport.protocol = "quic"

自定义 TLS 协议加密

transport.useEncryption 和 STCP 等功能能有效防止流量内容在通信过程中被盗取，但是无法判断对方的身份是否合法，存在被中间人攻击的风险。为此 frp 支持 frpc 和 frps 之间的流量通过 TLS 协议加密，并且支持客户端或服务端单向验证，双向验证等功能。

当 frps.toml 中 transport.tls.force = true 时，表示 server 端只接受 TLS 连接的客户端，这也是 frps 验证 frpc 身份的前提条件。如果 frps.toml 中 transport.tls.trustedCaFile 内容是有效的话，那么默认就会开启 transport.tls.force = true。

注意：启用此功能后除 xtcp ，可以不用再设置 use_encryption 重复加密

TLS 默认开启方式

从 v0.50.0 开始，transport.tls.enable 的默认值将会为 true，默认开启 TLS 协议加密。

如果 frps 端没有配置证书，则会使用随机生成的证书来加密流量。

默认情况下，frpc 开启 TLS 加密功能，但是不校验 frps 的证书。

frpc 单向校验 frps 身份

1
2
3
4
5
6
7

# frpc.toml
transport.tls.trustedCaFile = "/to/ca/path/ca.crt"

# frps.toml
transport.tls.certFile = "/to/cert/path/server.crt"
transport.tls.keyFile = "/to/key/path/server.key"

frpc 需要额外加载 ca 证书，frps 需要额外指定 TLS 配置。frpc 通过 ca 证书单向验证 frps 的身份。这就要求 frps 的 server.crt 对 frpc 的 ca 是合法的。

合法: 如果证书是 ca 签发的，或者证书是在 ca 的信任链中，那即认为: 该证书对 ca 而言是合法的。

frps 单向验证 frpc 的身份

1
2
3
4
5
6
7

# frpc.toml
transport.tls.certFile = "/to/cert/path/client.crt"
transport.tls.keyFile = "/to/key/path/client.key"

# frps.toml
transport.tls.trustedCaFile = "/to/ca/path/ca.crt"

frpc 需要额外加载 TLS 配置，frps 需要额外加载 ca 证书。frps 通过 ca 证书单向验证 frpc 的身份。这就要求 frpc 的 client.crt 对 frps 的 ca 是合法的。

双向验证

1
2
3
4
5
6
7
8
9
10

# frpc.toml
transport.tls.certFile = "/to/cert/path/client.crt"
transport.tls.keyFile = "/to/key/path/client.key"
transport.tls.trustedCaFile = "/to/ca/path/ca.crt"

# frps.toml
transport.tls.certFile = "/to/cert/path/server.crt"
transport.tls.keyFile = "/to/key/path/server.key"
transport.tls.trustedCaFile = "/to/ca/path/ca.crt"

双向验证即 frpc 和 frps 通过本地 ca 证书去验证对方的身份。理论上 frpc 和 frps 的 ca 证书可以不同，只要能验证对方身份即可。

OpenSSL 生成证书示例

x509: certificate relies on legacy Common Name field, use SANs or temporarily enable Common Name matching with GODEBUG=x509ignoreCN=0

如果出现上述报错，是因为 go 1.15 版本开始废弃 CommonName，因此推荐使用 SAN 证书。

下面简单示例如何用 openssl 生成 ca 和双方 SAN 证书。

准备默认 OpenSSL 配置文件于当前目录。此配置文件在 linux 系统下通常位于 /etc/pki/tls/openssl.cnf，在 mac 系统下通常位于 /System/Library/OpenSSL/openssl.cnf。

如果存在，则直接拷贝到当前目录，例如 cp /etc/pki/tls/openssl.cnf ./my-openssl.cnf。如果不存在可以使用下面的命令来创建。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

cat > my-openssl.cnf << EOF
[ ca ]
default_ca = CA_default
[ CA_default ]
x509_extensions = usr_cert
[ req ]
default_bits        = 2048
default_md          = sha256
default_keyfile     = privkey.pem
distinguished_name  = req_distinguished_name
attributes          = req_attributes
x509_extensions     = v3_ca
string_mask         = utf8only
[ req_distinguished_name ]
[ req_attributes ]
[ usr_cert ]
basicConstraints       = CA:FALSE
nsComment              = "OpenSSL Generated Certificate"
subjectKeyIdentifier   = hash
authorityKeyIdentifier = keyid,issuer
[ v3_ca ]
subjectKeyIdentifier   = hash
authorityKeyIdentifier = keyid:always,issuer
basicConstraints       = CA:true
EOF

生成默认 ca:

1
2
3

openssl genrsa -out ca.key 2048
openssl req -x509 -new -nodes -key ca.key -subj "/CN=example.ca.com" -days 5000 -out ca.crt

生成 frps 证书:

1
2
3
4
5
6
7
8
9
10
11
12
13

openssl genrsa -out server.key 2048

openssl req -new -sha256 -key server.key \
    -subj "/C=XX/ST=DEFAULT/L=DEFAULT/O=DEFAULT/CN=server.com" \
    -reqexts SAN \
    -config <(cat my-openssl.cnf <(printf "\n[SAN]\nsubjectAltName=DNS:localhost,IP:127.0.0.1,DNS:example.server.com")) \
    -out server.csr

openssl x509 -req -days 365 -sha256 \
	-in server.csr -CA ca.crt -CAkey ca.key -CAcreateserial \
	-extfile <(printf "subjectAltName=DNS:localhost,IP:127.0.0.1,DNS:example.server.com") \
	-out server.crt

生成 frpc 的证书:

1
2
3
4
5
6
7
8
9
10
11
12

openssl genrsa -out client.key 2048
openssl req -new -sha256 -key client.key \
    -subj "/C=XX/ST=DEFAULT/L=DEFAULT/O=DEFAULT/CN=client.com" \
    -reqexts SAN \
    -config <(cat my-openssl.cnf <(printf "\n[SAN]\nsubjectAltName=DNS:client.com,DNS:example.client.com")) \
    -out client.csr

openssl x509 -req -days 365 -sha256 \
    -in client.csr -CA ca.crt -CAkey ca.key -CAcreateserial \
	-extfile <(printf "subjectAltName=DNS:client.com,DNS:example.client.com") \
	-out client.crt

在本例中，server.crt 和 client.crt 都是由默认 ca 签发的，因此他们对默认 ca 是合法的。

负载均衡与健康检查

负载均衡

你可以将多个相同类型的代理加入到同一个 group 中，以实现负载均衡的能力。

目前支持的代理类型包括：tcp, http, tcpmux。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

# frpc.toml
[[proxies]]
name = "test1"
type = "tcp"
localPort = 8080
remotePort = 80
loadBalancer.group = "web"
loadBalancer.groupKey = "123"

[[proxies]]
name = "test2"
type = "tcp"
localPort = 8081
remotePort = 80
loadBalancer.group = "web"
loadBalancer.groupKey = "123"

当用户连接 frps 服务器的 80 端口时，frps 会将接收到的用户连接随机分发给其中一个存活的代理。这可以确保即使一台 frpc 机器挂掉，仍然有其他节点能够提供服务。

对于 tcp 类型代理，需要确保 groupKey 相同以进行权限验证，同时 remotePort 也需一致。

对于 http 类型代理，需要保证 groupKey, customDomains(自定义域名)，subdomain 和 locations 相同。

健康检查

通过给代理配置健康检查参数，可以在要反向代理的服务出现故障时，将该服务从 frps 中摘除。结合负载均衡的功能，这可用于实现高可用架构，避免服务单点故障。

要启用健康检查功能，需要在每个代理的配置中添加 healthCheck.type = {type}。

目前支持的类型有 tcp 和 http。

• 对于 tcp，只要能够建立连接，即认为服务正常。
• 对于 http，会发送一个 HTTP 请求，服务需要返回状态码 2xx 才会被视为正常。

以下是 tcp 示例配置：

1
2
3
4
5
6
7
8
9
10
11
12
13
14

[[proxies]]
name = "test1"
type = "tcp"
localPort = 22
remotePort = 6000
# 启用健康检查，类型为 tcp
healthCheck.type = "tcp"
# 建立连接超时时间为 3 秒
healthCheck.timeoutSeconds = 3
# 连续 3 次检查失败，此 proxy 会被摘除
healthCheck.maxFailed = 3
# 每隔 10 秒进行一次健康检查
healthCheck.intervalSeconds = 10

以下是 http 示例配置：

1
2
3
4
5
6
7
8
9
10
11
12
13

[[proxies]]
name = "web"
type = "http"
localIP = "127.0.0.1"
localPort = 80
customDomains = ["test.yourdomain.com"]
# 启用健康检查，类型为 http
healthCheck.type = "http"
# 健康检查发送 http 请求的 path，后端服务需要返回 2xx 的 http 状态码
healthCheck.path = "/status"
healthCheck.timeoutSeconds = 3
healthCheck.maxFailed = 3
healthCheck.intervalSeconds = 10

获取用户真实 IP

HTTP X-Forwarded-For

目前只有 http 类型的代理或者启用了 https2http 或 https2https 插件的代理支持这一功能。

可以通过 HTTP 请求 header 中的 X-Forwarded-For 来获取用户真实 IP，默认启用。

Proxy Protocol

frp 支持通过 Proxy Protocol 协议来传递经过 frp 代理的请求的真实 IP。

Proxy Protocol 功能启用后，frpc 在和本地服务建立连接后，会先发送一段 Proxy Protocol 的协议内容给本地服务，本地服务通过解析这一内容可以获得访问用户的真实 IP。所以不仅仅是 HTTP 服务，任何的 TCP 服务，只要支持这一协议，都可以获得用户的真实 IP 地址。

UDP 代理类型也支持 Proxy Protocol 功能，能够保留真实客户端 IP 地址。

需要注意的是，在代理配置中如果要启用此功能，需要本地的服务能够支持 Proxy Protocol 这一协议，目前 nginx 和 haproxy 都能够很好的支持。

TCP/HTTPS 代理示例

这里以 HTTPS 类型为例:

1
2
3
4
5
6
7
8
9
10

# frpc.toml
[[proxies]]
name = "web"
type = "https"
localPort = 443
customDomains = ["test.yourdomain.com"]

# 目前支持 v1 和 v2 两个版本的 proxy protocol 协议。
transport.proxyProtocolVersion = "v2"

只需要在代理配置中增加一行 transport.proxyProtocolVersion = "v2" 即可开启此功能。

本地的 HTTPS 服务可以通过在 nginx 的配置中启用 Proxy Protocol 的解析并将结果设置在 X-Real-IP 这个 Header 中就可以在自己的 Web 服务中通过 X-Real-IP 获取到用户的真实 IP。

UDP 代理示例

UDP 代理也支持 Proxy Protocol 功能：

1
2
3
4
5
6
7
8
9
10
11

# frpc.toml
[[proxies]]
name = "dns"
type = "udp"
localIP = "127.0.0.1"
localPort = 53
remotePort = 6000

# 启用 UDP 代理的 Proxy Protocol 支持
transport.proxyProtocolVersion = "v2"

启用后，frps 和 frpc 会把源 IP 信息写入 Proxy Protocol 头部，后端 UDP 服务或日志系统可以准确识别访问者的真实 IP 地址，这对于安全审计和访问控制特别有用。

端口范围映射

Added in v0.56.0

我们可以利用 Go template 的 range 语法结合内置的 parseNumberRangePair 函数来实现端口范围映射。

下面的示例，应用运行后会创建 8 个代理，名称为 test-6000, test-6001 ... test-6007，分别将远端的端口映射到本地。

1
2
3
4
5
6
7

{{- range $_, $v := parseNumberRangePair "6000-6006,6007" "6000-6006,6007" }}
[[proxies]]
name = "tcp-{{ $v.First }}"
type = "tcp"
localPort = {{ $v.First }}
remotePort = {{ $v.Second }}
{{- end }}

客户端

动态配置更新

当你需要修改 frpc 的代理配置时，你可以使用 frpc reload 命令来实现动态加载配置文件，通常在数秒内完成代理的更新。

要启用此功能，需要在 frpc 中启用 webServer，以提供 API 服务。配置如下：

1
2
3

webServer.addr = "127.0.0.1"
webServer.port = 7400

然后执行以下命令来重载配置：

frpc reload -c ./frpc.toml

等待一段时间后，客户端将根据新的配置文件创建、更新或删除代理。需要注意的是，非代理相关的公共部分的参数除了 start 外目前无法被修改。

命令行查看代理状态

frpc 支持通过 frpc status -c ./frpc.toml 命令查看代理的状态信息，此功能需要在 frpc 中启用 webServer。

使用代理连接 frps

在只能通过代理访问外部网络的环境中，frpc 支持通过 HTTP 或 SOCKS5 代理与 frps 建立连接。

你可以通过设置系统环境变量 HTTP_PROXY 或在 frpc 的配置文件中设置 transport.proxyURL 参数来使用此功能。

仅在 transport.protocol = "tcp" 时生效。

1
2
3
4

serverAddr = "x.x.x.x"
serverPort = 7000
transport.proxyURL = "http://user:pwd@192.168.1.128:8080"

将 transport.proxyURL 设置为 socks5://user:pwd@192.168.1.128:8080 也可以连接到 SOCKS5 代理。

服务端管理

端口白名单

为了防止端口被滥用，可以手动指定允许哪些端口被使用，在服务端配置中通过 allowPorts 来指定：

1
2
3
4
5
6
7
8

# frps.ini
allowPorts = [
  { start = 2000, end = 3000 },
  { single = 3001 },
  { single = 3003 },
  { start = 4000, end = 50000 }
]

allowPorts 可以配置允许使用的某个指定端口或者是一个范围内的所有端口。

端口复用

目前 frps 中的 vhostHTTPPort 和 vhostHTTPSPort 支持配置成和 bindPort 为同一个端口，frps 会对连接的协议进行分析，之后进行不同的处理。

例如在某些限制较严格的网络环境中，可以将 bindPort 和 vhostHTTPSPort 都设置为 443。

需要注意的是，如果你想将 vhostHTTPSPort 和 bindPort 配置为相同的端口，需要首先将 transport.tls.disableCustomTLSFirstByte 设置为false。

限速

代理限速

目前支持在客户端的代理配置中设置代理级别的限速，限制单个 proxy 可以占用的带宽。

1
2
3
4
5
6
7
8

# frpc.toml
[[proxies]]
name = "ssh"
type = "tcp"
localPort = 22
remotePort = 6000
transport.bandwidthLimit = "1MB"

在代理配置中增加 transport.bandwidthLimit 字段启用此功能，目前仅支持 MB 和 KB 单位。

限速能力默认在客户端实现，如果希望启用服务端限速，需要额外配置 transport.bandwidthLimitMode = "server"。

客户端插件

默认情况下，frpc 仅会将请求转发到本地 TCP 或 UDP 端口，即通过 localIP 和 localPort 指定的本地服务地址。

通过启用客户端插件功能，可以在仅启动 frpc 的情况下内置一些简单的本地服务，从而实现通常需要额外启动其他服务才能实现的功能。

在每个代理的配置中，你可以通过 plugin 来配置要使用的插件和相关参数。启用客户端插件后，无需再配置 localIP 和 localPort。

客户端插件可用于各种类型的代理，前提是插件本身支持的协议。例如，静态文件访问插件可以通过 TCP 或 HTTP 代理进行暴露。

以下是使用 http_proxy 插件的示例：

1
2
3
4
5
6
7
8
9

[[proxies]]
name = "http_proxy"
type = "tcp"
remotePort = 6000
[proxies.plugin]
type = "http_proxy"
httpUser = "abc"
httpPassword = "abc"

httpUser 和 httpPassword 即为 http_proxy 插件可选的配置参数。

其他插件和相关配置请参考 Reference 中的内容。

服务端插件

frp 服务端插件的作用是在不侵入自身代码的前提下，扩展 frp 服务端的能力。

frp 服务端插件会以单独进程的形式运行，并且监听在一个端口上，对外提供 RPC 接口，响应 frps 的请求。

frps 在执行某些操作前，会根据配置向服务端插件发送 RPC 请求，根据插件的响应来执行相应的操作。

RPC 请求

服务端插件接收到操作请求后，可以给出三种回应。

• 拒绝操作，需要返回拒绝操作的原因。
• 允许操作，不需要修改操作内容。
• 允许操作，对操作请求进行修改后，返回修改后的内容。

接口

接口路径可以在 frps 配置中为每个插件单独配置，这里以 /handler 为例。

Request

1
2
3
4
5
6
7
8
9
10

POST /handler?version=0.1.0&op=Login
{
    "content": {
        ... // 具体的操作信息
    }
}

请求 Header
X-Frp-Reqid: 用于追踪请求