踩坑日记, 由Ai总结 ---- 踩过的坑才印象深刻, 才能真正记住

坑 1：localhost 能通，127.0.0.1 却连不上（导致公网 502）

1. 现象与排查

本地 Vite 服务运行在 3200 端口，浏览器访问 http://localhost:3200 正常，但执行 curl.exe http://127.0.0.1:3200 却报错 Failed to connect: Could not connect to server。

检查端口监听状态：

powershellnetstat -ano | findstr :3200
# 输出：TCP    [::1]:3200    LISTENING

2. 根因分析

• localhost：现代系统与 Node.js 17+ 默认优先解析为 IPv6 的 [::1]。
• 127.0.0.1：是 IPv4 回环地址。Vite 默认只绑定了 IPv6 [::1]，IPv4 根本没有服务监听。
• 连锁反应：frpc.toml 中配置了 localIP = "127.0.0.1"，FRP 转发公网请求到本地 127.0.0.1:3200 被拒，对外直接表现为 HTTP 502。

3. 解决办法

修改 vite.config.ts，显式配置 host: '0.0.0.0'（监听全网卡双栈）：

tsexport default defineConfig({
  server: {
    host: '0.0.0.0',
    port: 3200,
  },
})

坑 2：修改了 frps.toml，端口却未生效

1. 现象与根因

服务端修改配置 bindPort = 7100 后执行了 systemctl start frps，客户端仍报错 session shutdown。

• 原因：systemctl start 只负责启动未运行的服务。frps 已经在后台常驻运行了数月，执行 start 不会重新加载配置。

2. 解决办法

bashsudo systemctl restart frps       # 重启以加载新配置
ss -lntp | grep 7100              # 确认 7100 端口已处于 LISTEN 状态

坑 3：[[proxies]] 代理配置名称重复

1. 现象与根因

frpc.toml 中配置了多个代理节，但 name 字段使用了相同名称：

toml# ❌ 错误：两处代理 name 重复
[[proxies]]
name = "mqtt_remote"
localPort = 1883
remotePort = 6183
[[proxies]]
name = "mqtt_remote"
localPort = 3200
remotePort = 6001

客户端日志报错：start error: proxy [mqtt_remote] already exists。在 FRP 中，name 是每个 Proxy 唯一的标识 ID。

2. 解决办法

确保每个代理条目的 name 全局唯一：

toml# ✅ 正确配置
[[proxies]]
name = "mqtt_remote"
type = "tcp"
localIP = "127.0.0.1"
localPort = 1883
remotePort = 6183
[[proxies]]
name = "web_3200"
type = "tcp"
localIP = "127.0.0.1"
localPort = 3200
remotePort = 6001

🛠️ 标准排查链路速查

text公网请求 (38.95.74.213:6001) ──> frps 服务端 ──> frpc 客户端 ──> 本地服务 (127.0.0.1:3200)

遇到穿透异常，建议按 “服务端 -> 本地服务 -> 网络连通 -> 日志” 的四步链路排查：

1. 检查服务端监听：ss -lntp | grep frps（确认 7100 通信端口与映射端口处于 LISTEN 状态）。
2. 测试本地服务可用性：powershellTest-NetConnection 127.0.0.1 -Port 3200 Test-NetConnection 127.0.0.1 -Port 1883(如果本地 IPv4 都不通，FRP 必定返回 502，先改 Vite 0.0.0.0)
3. 测试公网端口连通：powershellTest-NetConnection 38.95.74.213 -Port 6001
4. 定位客户端/服务端日志：查看 frpc.log 或 frps.log 是否存在 proxy already exists 或认证报错。

📌 核心经验总结

1. localhost ≠ 127.0.0.1：遇连接异常先跑 netstat -ano | findstr :端口 确认是 [::1] 还是 127.0.0.1 / 0.0.0.0。
2. 改配置务必 restart：systemctl start 不会重载正在运行的进程。
3. [[proxies]] 必须命名唯一：name 是 FRP 的唯一代理 ID。