[返回首页](../README.md)

# 故障排查

按链路顺序排查：先确认本机串口后端和 RFC 2217 监听器正常，再检查 FRP 注册与公网端口，最后检查远程客户端。不要以 TCP 端口可达代替 RFC 2217 功能测试。

## 一、串口后端

### ser2net 报告 `permission denied`

检查服务账户、TTY 所有权和 `dialout` 组成员关系：

```bash
systemctl show ser2net -p User -p Group
ls -lL /dev/serial/by-id/REPLACE_WITH_YOUR_DEVICE
id ser2net
```

### 重启后设备路径消失

不要依赖会动态变化的 `/dev/ttyUSB*`、`/dev/ttyACM*` 或 `/dev/ttyCH*`。优先在配置中使用稳定的 `/dev/serial/by-id/*` 或 `/dev/serial/by-path/*` 路径。

如果转换器没有唯一序列号，使用 `by-path`，或安装匹配条件经过谨慎限定的 udev 规则。

### WCH 转换器没有可用 TTY

检查 `lsusb`、`dmesg`，并检查所有可能的设备名：

```text
/dev/ttyACM*
/dev/ttyUSB*
/dev/ttyCH*
```

CH342/CH344 板卡可能暴露 CDC ACM 接口，也可能因具体产品和固件而需要 WCH 多端口驱动。安装更新的通用 `ch341` 驱动并不是通用解决方案。应使用发行版支持或硬件厂商提供、且与具体设备匹配的驱动；如果不希望维护定制驱动，可选择 FTDI 方案。

### 客户端能连接但不能修改波特率

确认 accepter 明确启用了 RFC 2217：

```yaml
accepter: telnet(rfc2217),tcp,127.0.0.1,2217
```

普通 `tcp` 或普通 `telnet` accepter 不等价。客户端也必须支持 RFC 2217，而不是仅打开裸 TCP socket。

### 有连接但没有串口数据

先从 Linux 服务器本机测试 ser2net 的回环监听器：

- 本机 RFC 2217 正常而公网端点异常：转到 FRP 排查。
- 本机 RFC 2217 也异常：检查设备权限、RS-485 A/B 极性、终端电阻、偏置、初始波特率、校验位，以及转换器是否正确处理 RS-485 发送方向。

## 二、FRP

### FRP 公网端口拒绝连接

先在运行 `frpc` 的 Linux 主机检查服务状态和日志：

```bash
sudo systemctl status frpc --no-pager
sudo journalctl -u frpc -n 100 --no-pager
```

然后在 `frps` 主机确认：

- 所选 `remotePort` 已被 FRP 允许；
- 没有其他代理占用同一端口；
- 主机防火墙允许预期客户端连接该端口。

### FRP 已注册，但客户端连接失败

确认本地串口服务器确实监听 `frpc` 配置所指向的 `127.0.0.1:localPort`。Windows PowerShell 可使用：

```powershell
Get-NetTCPConnection -State Listen |
  Where-Object LocalPort -In 2217,7001 |
  Format-Table LocalAddress, LocalPort, OwningProcess
```

随后检查 WinSW 日志、`sc.exe query` 输出、`frpc` 日志、`frps` 端口限制及服务端防火墙。

### TCP 可达但 RFC 2217 仍不可用

Windows 上：

```powershell
Test-NetConnection FRPS_HOST -Port 2217
```

该命令成功只表示 TCP 可达，不验证 RFC 2217 协商、双向串口数据或远程串口参数控制。应改用 pySerial/miniterm 和波特率修改脚本进行端到端测试。

## 三、Windows 特定问题

### COM 端口忙或拒绝访问

Windows 通常以独占方式打开串口句柄。先关闭终端软件、厂商工具、监控程序以及先前启动的串口服务器进程，再判断是否为服务账户权限问题。

### 转换器重新出现后 COM 编号改变

不要只依赖旧 COM 编号。应结合 VID、PID、序列号、实例 ID 和物理位置识别设备。必要时在设备管理器中分配首选 COM 编号，然后更新服务器配置并重启服务。

### 服务启动时 USB 转换器尚不存在

使用延迟自动启动和失败后重启。测试以下场景：

- 冷启动；
- 系统重启；
- 拔出并重新插入；
- USB 集线器断开；
- 挂起与恢复。

设备意外移除后，已有串口句柄不会自动恢复有效；服务器可能需要重新打开设备或重启。

### hub4com 本地工作正常，但意外监听 LAN

确认命令包含：

```text
--interface 127.0.0.1
```

缺少该选项时，其上游实现会绑定所有 IPv4 接口。

### 原生 ser2net 无法加载 DLL

先安装匹配的官方 gensio 软件包，再安装 ser2net；确认两个安装程序的 `bin` 目录均已加入系统 `PATH`，并避免混用不同代的预编译发行包。