crosstyanandClaude Opus 4.8
74905def9a
Split the manual into a README index plus docs/ sections covering hardware selection, Linux and Windows serial servers, shared frpc configuration via env templating, client testing, security, and troubleshooting. Store real frpc credentials in an ignored .env and track images with Git LFS. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
128 lines
4.2 KiB
Markdown
128 lines
4.2 KiB
Markdown
[返回首页](../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`，并避免混用不同代的预编译发行包。
|