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 = 7

1.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.target

1.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 frpc

2.2 创建配置文件

配置文件路径按包管理器不同而不同:

安装方式配置文件路径
macOS Homebrew/opt/homebrew/etc/frp/frpc.toml
Linux 包管理器/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 = 22002

2.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:LISTEN

paseo 无需额外鉴权配置,只要端口能连通,通过隧道即可访问。


五、端到端验证

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 节。

公网访问超时或连接被拒

按以下顺序排查:

  1. 服务器 ufw 是否放行:ufw status | grep -E "7000|220"
  2. 云厂商安全组是否放行(需在控制台手动确认)
  3. 本机服务是否在监听:lsof -nP -iTCP:3425 -sTCP:LISTEN
  4. frpc 是否成功注册代理:curl -s http://127.0.0.1:7500/api/proxys
  5. 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 不匹配。

修改配置后不生效

依次确认:

  1. 配置文件路径与启动时加载的路径一致
  2. 配置中已设置 webServer.addr 与 webServer.port
  3. 使用 reload 后仍无效则重启服务
  4. 检查是否有两个 frpc 进程在同时运行、各加载一份不同配置,可通过 ps aux | grep frpc 确认

多个设备同时使用 frp

若其他设备(如另一台电脑)也在连接同一台 frps 且登录失败,通常是其配置中的 Token 是旧值。处理方式:

  1. 将该设备的 Token 更新为服务器当前的值
  2. 或停止该设备不再使用的 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 / 图形化工具

  1. 请求方法选 POST
  2. URL 填 http://<服务器公网IP>:22002/v1/chat/completions
  3. Headers 添加 Authorization: Bearer <你的 SK>
  4. Body 选 raw + JSON,填入请求体

九、安全建议

  1. Token 从文件读取 — frps 侧将 Token 放在 /etc/frp/token 并限制权限为 600,避免明文写进配置文件或出现在进程参数中
  2. 限定端口范围 — allowPorts 限制在 22000-22010,防止客户端申请任意端口扩大暴露面
  3. 鉴权必须生效 — magpie 类服务务必通过 localIP 走局域网地址触发 SK 校验,不要用回环地址绕过
  4. 缩窄 SSH 来源 — 云服务器 22 端口建议在安全组中限制为固定来源 IP,不要用 0.0.0.0/0
  5. paseo 端口评估 — 22001 无额外鉴权,取决于 paseo 自身是否有认证机制。若没有,建议仅在可信网络使用,或叠加 VPN
  6. 定期更换 Token 与 SK — 更换后同步更新所有客户端配置,避免长期沿用同一凭证
  7. 避免多份配置并存 — 本机只保留一份 frpc 配置并由包管理器托管,避免多个进程加载不同配置导致排查困难

十、配置速查表

项目位置关键值
frps 配置/etc/frp/frps.tomlbindPort = 7000、allowPorts = 22000-22010
frps Token/etc/frp/token权限 600,需与 frpc 一致
frpc 配置/opt/homebrew/etc/frp/frpc.toml(macOS)<br>/etc/frp/frpc.toml(Linux)serverAddr、auth.token
代理一 paseofrpc 配置内localIP = 127.0.0.1、localPort = 6767、remotePort = 22001
代理二 magpiefrpc 配置内localIP = <本机局域网IP>、localPort = 3425、remotePort = 22002
magpie 鉴权~/.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 本地端口—
主楼