部署服务端 frps_helper
frps_helper 是 xfrpc_loader 的云端配套服务端,在一个进程中提供三组隔离的 HTTP 服务。本页介绍编译、配置、运行以及与 frps 的对接。
1. 编译
要求 Go 1.21+:
git clone https://github.com/monkfish-iot/frps_helper.git
cd frps_helper
go build -o frps_helper .
2. 配置
编辑 configs/config.yaml(或参考 config.example.yaml):
frpc:
enable: true # 必须为 true 才启动三个服务
auto_register: true # 是否允许设备首次 join 自动注册
port: 8089 # FRPS 认证 HTTP 端口
device_port: 6999 # 设备对接 HTTPS 端口
manage_port: 7443 # 独立管理 HTTPS 端口
xfrpc_server_addr: "127.0.0.1" # 下发给设备的 xfrpc(frps) 地址
xfrpc_server_port: 7000 # 下发给设备的 xfrpc(frps) 端口
credential_query: false # 是否开放明文凭证查询接口(默认关闭)
# credential_token: "xxxx" # 可选,设置后查询接口需带 Bearer 令牌
xfrpc_server_addr:该值会下发给客户端设备,作为设备侧 xfrpc 连接 frps 的地址,因此必须填写设备可达的 frps 服务器公网 IP 或域名(例如 "frps.example.com" 或 "203.0.113.10");默认的 127.0.0.1 只适用于服务端本机联调。同时确认 xfrpc_server_port(默认 7000)已放行、外网可达。
3. 证书
设备/管理服务器共用自签证书 certs/device-server.{crt,key},SANs 需覆盖访问 IP/域名:
./scripts/gen-device-cert.sh <你的服务器IP或域名>
也可以删除证书文件,让服务启动时自动生成。若启用 CA 相关功能,先用 ./scripts/gen-ca-cert.sh 生成 CA(详见仓库 ca/readme.md)。
4. 运行
./frps_helper
# 或指定配置文件
./frps_helper -config path/to/config.yaml
启动成功后日志应出现:
[FRPC] auth server starting on :8089 (HTTP)
[FRPC] device server starting on :6999 (HTTPS)
[FRPC] manage server starting on :7443 (HTTPS)
默认使用 SQLite,数据库文件位于启动目录的 data/ 下;也可配置 PostgreSQL。
5. frps 侧对接(第三方认证)
在 frps 配置(frps.toml)中配置 vhost 端口与本地域名后缀,并启用 HTTP 插件,指向 frps_helper 的 8089 端口:
vhostHTTPPort = 20001
vhostHTTPSPort = 20000
subdomainHost = "frpclient.local"
[[httpPlugins]]
name = "my-auth"
addr = "127.0.0.1:8089"
path = "/handler"
ops = ["Login", "Ping"]
设备的会话域名 <会话ID>.frpclient.local 默认经 vhostHTTPPort(20001)以 HTTP 提供访问(HTTPS 为 20000);同时需在服务器上对 *.frpclient.local 做 dnsmasq 泛解析到本机,见下文安装配置本地 DNS。frps 收到设备接入请求后,会向 frps_helper 校验设备会话。详细鉴权规则见FRPS 认证对接。
6. 安装配置本地 DNS(*.frpclient.local 泛解析)
每台设备的会话域名 <会话ID>.frpclient.local 只有先解析到 frps 所在服务器(本机 127.0.0.1),才能经 vhostHTTPPort 的隧道访问到对应设备。这里在服务器本机用 dnsmasq 提供本地 DNS:
sudo apt -y install dnsmasq
① 配置泛解析:新建 /etc/dnsmasq.d/frpclient.conf:
# 将 *.frpclient.local 全部泛解析到本机(frps 所在服务器)
address=/frpclient.local/127.0.0.1
address=/frpclient.local/127.0.0.1 匹配 frpclient.local 及其所有子域(即 *.frpclient.local),任意会话 ID 主机名都解析到 127.0.0.1,无需为每台设备单独添加记录;实际路由由 frps 按 HTTP Host 头完成。
② dnsmasq 指向上级 DNS(不影响本机解析其他域名):显式指定上游 DNS,其余域名照常走公网/内网解析。为避免与 systemd-resolved 冲突,建议在配置中关闭读取 /etc/resolv.conf 并手动指定上游(请按需替换为你的内网 DNS):
# 追加到 /etc/dnsmasq.d/frpclient.conf
no-resolv
server=223.5.5.5 # 上级 DNS,可换成内网 DNS
server=8.8.8.8
③ 将本机 DNS 指向 dnsmasq:把 /etc/resolv.conf 的 nameserver 指向 127.0.0.1,让本机查询先走 dnsmasq:
echo "nameserver 127.0.0.1" | sudo tee /etc/resolv.conf
sudo systemctl restart dnsmasq
/etc/resolv.conf 若由 NetworkManager/systemd-resolved 托管,直接改会被覆盖,可改用持久化方式,例如让 NetworkManager 使用 dnsmasq 作为本地 DNS:
sudo tee /etc/NetworkManager/conf.d/dns.conf <<'EOF'
[main]
dns=dnsmasq
EOF
sudo systemctl restart NetworkManager
④ 验证:
dig +short test123.frpclient.local # 期望输出 127.0.0.1
dig +short www.baidu.com # 期望正常返回公网结果(上级 DNS 生效)
*.frpclient.local 指向 127.0.0.1,具体落到哪台设备由 frps 依据 Host 头选择。
7. 安装 WrtHub-UI(图形化管理界面)
WrtHub-UI 是运行在服务器上的图形化管理面板,用于可视化查看已接入设备、远程配置无线网络与审计操作日志。它通过 frps_helper 北向接口(7443)获取设备与会话数据,因此需在本页服务端部署完成后安装:
git clone https://github.com/monkfish-iot/WrtHub-UI.git
cd WrtHub-UI
go build -o wrthub-ui .
按需编辑 config.yaml(会话密钥 SessionSecret、监听地址、frps_helper 北向接口地址 https://127.0.0.1:7443、SQLite 数据文件 dist/data),然后启动:
./wrthub-ui
启动后默认跳转 /devices,登录进入「设备管理」即可看到已接入设备并进入单台设备的无线与配置管理;未登录访问受保护路由会被重定向到登录页。详见WrtHub-UI 文档。
8. 验证
用 curl 调用北向接口确认服务可用:
curl -k https://127.0.0.1:7443/api/v1/devices?page=1&page_size=10
下一步:安装设备端