frpctl

一个通用的 frp 隧道管理 CLI。可配合 Claude skill，通过自然语言完成开/关/查隧道。

安装

npm install -g frpctl

前置条件

• 一台运行 frps 的 VPS
• 本地可执行 frpc（放在 $PATH，或设置环境变量 FRPCTL_FRPC=/path/to/frpc）

VPS 端配置（frps.toml）

bindPort = 7000
auth.method = "token"
auth.token = "替换为强密码"
transport.tcpMux = false

# 限制可用端口范围（可选，建议配置）
allowPorts = [
  { start = 20000, end = 20100 },
]

注意：如需 HTTP/HTTPS 隧道，还需额外配置：

vhostHTTPPort = 80
vhostHTTPSPort = 443
subdomainHost = "example.com"   # 需要有 *.example.com 的泛域名解析

没有域名则只能使用 TCP/UDP 隧道。

防火墙放行端口：

# 控制端口 + 隧道端口范围
ufw allow 7000/tcp
ufw allow 20000:20100/tcp

用 systemd 管理 frps：

# /etc/systemd/system/frps.service
[Unit]
Description=frp server
After=network.target

[Service]
ExecStart=/usr/local/bin/frps -c /etc/frp/frps.toml
Restart=always

[Install]
WantedBy=multi-user.target

systemctl enable --now frps

本地端配置（首次使用）

frpctl server add main \
    --addr 你的VPS_IP:7000 \
    --token '替换为强密码' \
    --port-pool 20000-20100

关键：如果 frps.toml 中设置了 transport.tcpMux = false，需要在 frpctl 的服务器配置里同步设置，否则连接会报 EOF。

直接编辑 ~/.config/frpctl/config.toml，在对应服务器下加一行：

[servers.main]
addr = "你的VPS_IP:7000"
token = "替换为强密码"
port_pool = "20000-20100"
tcp_mux = false          # ← frps 关闭了 tcpMux 时必须加这行

使用

快速开隧道（推荐）

frpctl quick -l 8080              # TCP，端口自动分配，名称自动生成
frpctl quick -l 8080 --ttl 2h    # 2 小时后自动关闭
frpctl quick -l 5353 -t udp      # UDP 隧道
frpctl quick -l 8080 -t http --subdomain myapp   # HTTP（需要域名）

持久隧道

frpctl tunnel add ssh   -l 22   -t tcp
frpctl tunnel add dns   -l 5353 -t udp
frpctl tunnel add web   -l 8080 -t http  --subdomain myapp
frpctl tunnel add web   -l 8080 -t http  --custom-domains app.example.com
frpctl tunnel add api   -l 7001 -t stcp  --secret-key 'CHANGE_ME'

守护进程管理

frpctl up          # 启动 frpc（加载所有隧道）
frpctl down        # 停止 frpc
frpctl status      # 查看状态
frpctl logs -f     # 实时查看日志

隧道管理

frpctl tunnel list          # 列出所有隧道
frpctl tunnel rm <name>     # 删除隧道
frpctl tunnel url <name>    # 打印公网地址

隧道类型说明

| 类型 | 需要 | 不支持 | 备注 | |------|------|--------|------| | tcp（默认） | --local-port | — | 远端端口自动分配，可用 --remote-port 指定 | | udp | --local-port | — | 同 tcp | | http | --local-port + --subdomain 或 --custom-domains | — | frps 需配置 vhostHTTPPort 和域名 | | https | 同 http | — | frps 需配置 vhostHTTPSPort 和域名 | | stcp | --local-port + --secret-key | — | 需要访问端也运行 frpc visitor |

配置文件

| 路径 | 说明 | |------|------| | ~/.config/frpctl/config.toml | 服务器和隧道配置（含 token，权限 600） | | ~/.cache/frpctl/frpc.toml | 运行时自动生成，不要手动修改 | | ~/.cache/frpctl/frpc.log | frpc 日志 | | ~/.cache/frpctl/frpc.pid | frpc 进程 PID |

安装 Claude skill

将 skill/SKILL.md 复制到 Claude 的 skill 目录，文件夹命名为 frpctl：

/mnt/skills/user/frpctl/SKILL.md

本地开发

npm install
npm link
frpctl --help

npm version patch   # or minor / major
npm publish