Magpie + frp + Paseo 远程访问部署教程
通过 frp 反向隧道,将本机的 LLM 服务和终端控制端口映射到公网服务器,实现从手机或外部网络远程访问本机。
架构概览
手机 / 外部客户端 ↓ 云服务器(frps) ↓ 7000 控制端口 本机(frpc + magpie + paseo) ├─ magpie:3425 → 公网 :22002(LLM API,需 SK 鉴权) └─ paseo:6767 → 公网 :22001(远程终端控制)frps 部署在一台具备公网 IP 的云服务器上,本机运行 frpc 主动连入,把本地服务映射为公网可访问的端口。
组件说明
组件 部署位置 作用 端口 frps 云服务器 frp 服务端,接收 frpc 连接,映射公网端口 7000 控制 / 22000-22010 隧道 frpc 本机 frp 客户端,连入 frps 并注册代理 — magpie 本机 LLM 路由代理,自带 SK 鉴权 3425 本地 / 22002 公网 paseo 本机 远程终端控制 6767 本地 / 22001 公网 前置条件
云服务器
- Linux(本文以 Debian 13 为例,CentOS/Ubuntu 命令略有差异)
- 公网 IP
- root 或 sudo 权限
- 安全组 / 防火墙放行 22、7000、22000-22010
本机
- macOS 或 Linux
- 包管理器(macOS 用 Homebrew,Linux 用 apt/yum)
- 已安装并运行 magpie、paseo
- 已确认本机局域网 IP(下文用
<本机局域网IP>表示)
本机局域网 IP 查询
# macOS ipconfig getifaddr en0 # Linux ip addr show | grep inet一、配置云服务器(frps)
1.1 下载并安装 frps
国内服务器直连 GitHub 较慢,可使用镜像加速:
cd /tmp curl -fsSL -o frp.tar.gz https://github.com/fatedier/frp/releases/download/v0.72.0/frp_0.72.0_linux_amd64.tar.gz tar xzf frp.tar.gz install -m 755 frp_0.72.0_linux_amd64/frps /usr/local/bin/frps frps -v若下载缓慢,替换下载地址前缀为任一可用的加速镜像。
1.2 生成认证 Token
mkdir -p /etc/frp TOKEN=$(head -c 24 /dev/urandom | base64 | tr -d "/+=" | cut -c1-32) printf "%s" "$TOKEN" > /etc/frp/token chmod 600 /etc/frp/token务必记录该 Token,本机 frpc 需要配置相同的值。建议不在聊天、截图、文档中明文传递,本机直接从服务器读取。
1.3 创建配置文件
写入
/etc/frp/frps.toml:# frps 服务端配置 bindAddr = "0.0.0.0" bindPort = 7000 # 认证:Token 从文件读取,避免明文出现在配置文件和进程参数中 auth.method = "token" auth.additionalScopes = ["HeartBeats"] auth.tokenSource.type = "file" auth.tokenSource.file.path = "/etc/frp/token" # 限定客户端可申请的端口范围,防止随意占用端口 allowPorts = [ { start = 22000, end = 22010 } ] # 传输参数 transport.maxPoolCount = 10 transport.tcpMux = true transport.heartbeatTimeout = 90 # 日志 log.to = "console" log.level = "info" log.maxDays = 71.4 创建 systemd 服务
写入
/etc/systemd/system/frps.service:[Unit] Description=frp server (frps) After=network-online.target Wants=network-online.target [Service] Type=simple ExecStart=/usr/local/bin/frps -c /etc/frp/frps.toml Restart=always RestartSec=5s [Install] WantedBy=multi-user.target1.5 启动并验证
systemctl daemon-reload systemctl enable --now frps systemctl is-active frps ss -tlnp | grep 7000看到
*:7000在监听即成功。1.6 配置防火墙
ufw allow 22/tcp ufw allow 7000/tcp ufw allow 22000:22010/tcp ufw status注意:云服务器通常有两层防火墙。
ufw/iptables只是服务器内部一层,云厂商的安全组是独立的另一层。若客户端连不上,需在云厂商控制台的安全组中同样放行上述端口,两者缺一不可。二、配置本机(frpc)
2.1 安装 frpc
# macOS brew install frpc # Debian / Ubuntu sudo apt install frpc # CentOS / Rocky sudo dnf install frpc2.2 创建配置文件
配置文件路径按包管理器不同而不同:
安装方式 配置文件路径 macOS Homebrew /opt/homebrew/etc/frp/frpc.tomlLinux 包管理器 /etc/frp/frpc.toml写入配置:
serverAddr = "<服务器公网IP或域名>" serverPort = 7000 auth.method = "token" auth.token = "<与服务器 /etc/frp/token 一致>" # 本地管理接口,用于热加载配置,仅监听本机 webServer.addr = "127.0.0.1" webServer.port = 7500 # 代理一:paseo 远程控制,走本机回环,无需鉴权 [[proxies]] name = "paseo-tcp" type = "tcp" localIP = "127.0.0.1" localPort = 6767 remotePort = 22001 # 代理二:magpie LLM 服务,走局域网地址以触发 SK 鉴权 [[proxies]] name = "web-3425" type = "tcp" localIP = "<本机局域网IP>" localPort = 3425 remotePort = 220022.3 关于 localIP 的关键说明
localIP决定 frpc 以什么地址连接本地服务,也决定本地服务如何看待这个请求,两个代理的取值不能混用:127.0.0.1(回环地址)- frpc 从本机回环发起连接
- 本地服务看到的是回环来源
- 适合不需要鉴权的服务,如 paseo
<本机局域网IP>(局域网地址)- frpc 从本机局域网 IP 发起连接
- 本地服务看到的是非回环来源
- magpie 对非回环来源会强制校验 SK,因此需要鉴权的场景必须用这个值
如果 magpie 的端口被误配为
127.0.0.1,隧道虽能打通,但 magpie 会把请求视为回环来源并豁免鉴权,公网侧将无需 SK 即可访问——这通常不是想要的效果。2.4 启动服务
# macOS brew services start frpc brew services list | grep frpc # Linux(systemd) sudo systemctl enable --now frpc sudo systemctl status frpc查看已注册的代理:
curl -s http://127.0.0.1:7500/api/proxys返回 JSON 中应包含
paseo-tcp和web-3425两个代理。2.5 验证隧道连通性
从本机直连服务器的隧道端口,确认端口已被 frps 打开:
nc -z -v <服务器公网IP> 22001 # paseo nc -z -v <服务器公网IP> 22002 # magpie均返回
succeeded即隧道已建立。三、配置 magpie
3.1 确认 SK 已启用
magpie 的 SK 鉴权由配置项
lan和lanKey控制,配置文件位于:~/.config/magpie/settings.json关键字段:
{ "lan": true, "lanKey": "<你的 SK>", "lanKeyId": "<标识>" }lan: true表示启用局域网访问鉴权。lanKey即客户端需要携带的 SK。3.2 验证 magpie 监听
lsof -nP -iTCP:3425 -sTCP:LISTEN应能看到 magpie 进程在监听
*:3425(监听所有网卡,才能接受局域网来源的连接)。3.3 本地验证鉴权行为
同一接口,两种来源的鉴权要求不同:
# 回环访问:无需 SK,返回 200 curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:3425/v1/models # 局域网访问:无 SK 返回 401,有 SK 返回 200 curl -s -o /dev/null -w "%{http_code}\n" http://<本机局域网IP>:3425/v1/models第二步返回 401 说明 SK 校验已生效。加入 SK 后应返回 200:
curl -s -o /dev/null -w "%{http_code}\n" \ -H "Authorization: Bearer <你的 SK>" \ http://<本机局域网IP>:3425/v1/models建议自行取用 SK,避免在聊天或文档中明文暴露。
四、配置 paseo
启动 paseo 并确认其监听在本地 6767 端口:
lsof -nP -iTCP:6767 -sTCP:LISTENpaseo 无需额外鉴权配置,只要端口能连通,通过隧道即可访问。
五、端到端验证
5.1 验证 paseo(无需 SK)
从外部网络访问:
http://<服务器公网IP>:22001能正常建立连接即成功。
5.2 验证 magpie(需 SK)
先验证无 SK 时被拒绝:
curl -s -o /dev/null -w "%{http_code}\n" http://<服务器公网IP>:22002/v1/models返回 401 说明公网侧鉴权生效。
再带 SK 访问,应返回 200:
curl -s -o /dev/null -w "%{http_code}\n" \ -H "Authorization: Bearer <你的 SK>" \ http://<服务器公网IP>:22002/v1/models调用对话接口(注意该接口只接受 POST,浏览器直接打开会返回 404,属正常现象):
curl -X POST http://<服务器公网IP>:22002/v1/chat/completions \ -H "Content-Type: application/json" \ -H "Authorization: Bearer <你的 SK>" \ -d '{ "model": "codearts/deepseek-v4.1-flash", "messages": [{"role": "user", "content": "你好"}] }'返回模型输出即完整链路打通。模型名可通过
GET /v1/models查询后选择。六、日常运维
修改配置后热加载
frpc 0.72+ 支持不中断连接的热加载:
# macOS /opt/homebrew/opt/frpc/bin/frpc reload -c /opt/homebrew/etc/frp/frpc.toml # Linux frpc reload -c /etc/frp/frpc.toml前提是配置中已启用
webServer,否则 reload 会报错提示需先设置 web server 端口。若 reload 不生效,重启服务:
brew services restart frpc # macOS sudo systemctl restart frpc # Linux查看日志
# frps(服务器) journalctl -u frps -f # frpc(本机) tail -f /opt/homebrew/var/log/frpc.log # macOS Homebrew tail -f /var/log/frp/frpc.log # Linux检查隧道状态
# 本机:查看 frpc 注册的代理 curl -s http://127.0.0.1:7500/api/proxys # 服务器:查看已打开的隧道端口 ss -tlnp | grep 220确认 Token 是否匹配
frpc 连不上时,最常见的原因是 Token 不一致:
# 服务器侧查看 Token 长度(不打印内容) wc -c /etc/frp/token对比本机配置中
auth.token是否为同一值。七、常见问题
公网访问 magpie 端口返回 200 但不需要 SK
原因:frpc 中该代理的
localIP配置为127.0.0.1,magpie 将请求视为回环来源并豁免鉴权。解决:将该代理的
localIP改为本机局域网 IP,重新 reload 或重启 frpc。详见 2.3 节。公网访问超时或连接被拒
按以下顺序排查:
- 服务器 ufw 是否放行:
ufw status | grep -E "7000|220" - 云厂商安全组是否放行(需在控制台手动确认)
- 本机服务是否在监听:
lsof -nP -iTCP:3425 -sTCP:LISTEN - frpc 是否成功注册代理:
curl -s http://127.0.0.1:7500/api/proxys - frpc 是否连上服务器:查看 frpc 日志中有无
login to server success
frpc 日志出现 connect to server error
常见原因:
- Token 不匹配 — 对比服务器
/etc/frp/token与本机配置的auth.token - 7000 端口未放行 — 检查安全组与 ufw
- 网络不通 —
nc -z -v <服务器公网IP> 7000
日志中若出现
token in login doesn't match token from configuration,即为 Token 不匹配。修改配置后不生效
依次确认:
- 配置文件路径与启动时加载的路径一致
- 配置中已设置
webServer.addr与webServer.port - 使用
reload后仍无效则重启服务 - 检查是否有两个 frpc 进程在同时运行、各加载一份不同配置,可通过
ps aux | grep frpc确认
多个设备同时使用 frp
若其他设备(如另一台电脑)也在连接同一台 frps 且登录失败,通常是其配置中的 Token 是旧值。处理方式:
- 将该设备的 Token 更新为服务器当前的值
- 或停止该设备不再使用的 frpc,避免反复重试刷日志
服务器日志中可通过
hostname字段区分不同客户端。/v1/chat/completions 浏览器打开返回 404
该接口只接受 POST 请求,浏览器地址栏访问默认发送 GET,服务端会返回 404。这不是故障,需通过 curl、Postman 或代码以 POST 方式调用。
/v1/models支持 GET,浏览器可直接打开。八、客户端调用示例
curl
# 查询模型列表 curl -H "Authorization: Bearer <你的 SK>" \ http://<服务器公网IP>:22002/v1/models # 对话补全 curl -X POST http://<服务器公网IP>:22002/v1/chat/completions \ -H "Authorization: Bearer <你的 SK>" \ -H "Content-Type: application/json" \ -d '{"model":"codearts/deepseek-v4.1-flash","messages":[{"role":"user","content":"你好"}]}'Python
import requests url = "http://<服务器公网IP>:22002/v1/chat/completions" headers = { "Authorization": "Bearer <你的 SK>", "Content-Type": "application/json", } payload = { "model": "codearts/deepseek-v4.1-flash", "messages": [{"role": "user", "content": "你好"}], } resp = requests.post(url, headers=headers, json=payload) print(resp.json())Postman / 图形化工具
- 请求方法选 POST
- URL 填
http://<服务器公网IP>:22002/v1/chat/completions - Headers 添加
Authorization: Bearer <你的 SK> - Body 选 raw + JSON,填入请求体
九、安全建议
- Token 从文件读取 — frps 侧将 Token 放在
/etc/frp/token并限制权限为 600,避免明文写进配置文件或出现在进程参数中 - 限定端口范围 —
allowPorts限制在 22000-22010,防止客户端申请任意端口扩大暴露面 - 鉴权必须生效 — magpie 类服务务必通过
localIP走局域网地址触发 SK 校验,不要用回环地址绕过 - 缩窄 SSH 来源 — 云服务器 22 端口建议在安全组中限制为固定来源 IP,不要用
0.0.0.0/0 - paseo 端口评估 — 22001 无额外鉴权,取决于 paseo 自身是否有认证机制。若没有,建议仅在可信网络使用,或叠加 VPN
- 定期更换 Token 与 SK — 更换后同步更新所有客户端配置,避免长期沿用同一凭证
- 避免多份配置并存 — 本机只保留一份 frpc 配置并由包管理器托管,避免多个进程加载不同配置导致排查困难
十、配置速查表
项目 位置 关键值 frps 配置 /etc/frp/frps.tomlbindPort = 7000、allowPorts = 22000-22010frps Token /etc/frp/token权限 600,需与 frpc 一致 frpc 配置 /opt/homebrew/etc/frp/frpc.toml(macOS)<br>/etc/frp/frpc.toml(Linux)serverAddr、auth.token代理一 paseo frpc 配置内 localIP = 127.0.0.1、localPort = 6767、remotePort = 22001代理二 magpie frpc 配置内 localIP = <本机局域网IP>、localPort = 3425、remotePort = 22002magpie 鉴权 ~/.config/magpie/settings.jsonlan = true、lanKey服务器 ufw — 放行 22、7000、22000:22010 云安全组 云厂商控制台 同上,需单独配置 关键端口汇总
端口 位置 用途 鉴权 7000 服务器 frps 控制端口,frpc 连入 frp Token 22001 服务器 paseo 公网入口 无 22002 服务器 magpie 公网入口 SK(Authorization: Bearer) 7500 本机 frpc 管理接口 仅本机可访问 3425 本机 magpie 本地端口 回环免鉴权,局域网需 SK 6767 本机 paseo 本地端口 — 主楼