commit 74905def9a7ab7fe87091d91cd19bec17875fe90
Author: crosstyan <crosstyan@outlook.com>
Date:   Fri Jul 17 15:04:52 2026 +0800

    Add Chinese RFC 2217 serial-over-frp deployment guide
    
    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>

diff --git a/.env.example b/.env.example
new file mode 100644
index 0000000..ea802dd
--- /dev/null
+++ b/.env.example
@@ -0,0 +1,5 @@
+# 复制为 .env 并填入真实值；.env 已被 .gitignore 忽略，不会进入版本库。
+# frpc.toml 用 {{ .Envs.FRP_SERVER_ADDR }} 等模板引用这些变量，启动时从进程环境渲染。
+FRP_SERVER_ADDR=your-frps-host.example.com
+FRP_SERVER_PORT=21315
+FRP_AUTH_TOKEN=your-frps-token
diff --git a/.gitattributes b/.gitattributes
new file mode 100644
index 0000000..c9a2b47
--- /dev/null
+++ b/.gitattributes
@@ -0,0 +1,5 @@
+*.gif filter=lfs diff=lfs merge=lfs -text
+*.webp filter=lfs diff=lfs merge=lfs -text
+*.jpg filter=lfs diff=lfs merge=lfs -text
+*.jpeg filter=lfs diff=lfs merge=lfs -text
+*.png filter=lfs diff=lfs merge=lfs -text
diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..6d00846
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,5 @@
+# 本地真实凭据，切勿提交
+.env
+
+# macOS 元数据
+.DS_Store
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..13617a9
--- /dev/null
+++ b/README.md
@@ -0,0 +1,58 @@
+# 用 ser2net + frpc 部署 RFC 2217 串口服务器
+
+本手册介绍如何把一个 USB 转 RS-485 转换器接到主机上，以 **RFC 2217 模式**把每个串口发布为 TCP 服务，再通过已有的 FRP 服务器用 `frpc` 对外暴露。串口服务器一侧同时给出 Linux（`ser2net`）与 Windows（原生 `ser2net`、`hub4com`、商业方案）两种实现；FRP 客户端配置两端基本一致，已合并为单独一章。
+
+RFC 2217 是关键：与裸 TCP 串口透传不同，它允许兼容的远端客户端修改串口的波特率、数据位、校验位、停止位以及控制线。
+
+## 拓扑
+
+```text
+RFC 2217 客户端
+    |
+    | TCP 连接 FRPS_HOST:2217
+    v
+frps（公网 / 可达主机）
+    |
+    | FRP 隧道
+    v
+串口服务器上的 frpc
+    |
+    | TCP 连接 127.0.0.1:2217
+    v
+RFC 2217 模式的 ser2net（或 hub4com 等）
+    |
+    v
+USB 转 RS-485 转换器
+```
+
+前提假设：
+
+- `frps` 已在运行。
+- 串口服务器可以主动向该 `frps` 发起出站连接。
+- 只部署服务器一侧；客户端测试仅在末尾用于验证。
+
+## 部署流程
+
+1. **选型** — 根据端口数与驱动情况选择转换器。参见 [转换器选型](docs/hardware.md)。
+2. **搭建串口服务器** — 在目标机上以 RFC 2217 模式暴露串口，仅监听回环地址：
+   - Linux：[用 ser2net 提供 RFC 2217](docs/serial-server-linux.md)
+   - Windows：[原生 ser2net / hub4com / 商业方案](docs/serial-server-windows.md)
+3. **配置 FRP 客户端** — 复用现有 `frps` 的地址、端口与令牌，把本地回环监听对外发布，并做成系统服务。真实值集中在仓库根目录 `.env`，`frpc.toml` 用 `{{ .Envs.* }}` 模板引用；`frpc` 不会自动加载该 `.env`，部署时经 systemd `EnvironmentFile` 或 WinSW `<env>` 注入。Linux 与 Windows 的 `frpc.toml` 代理配置一致。参见 [FRP 客户端配置](docs/frpc.md)。
+4. **验证** — 从远端用支持 RFC 2217 的客户端做端到端测试。参见 [客户端测试](docs/client-testing.md)。
+
+## 目录
+
+| 文档 | 内容 |
+|---|---|
+| [转换器选型](docs/hardware.md) | FTDI 与 WCH 对比、隔离建议、Linux 下的设备识别与稳定路径 |
+| [Linux 串口服务器](docs/serial-server-linux.md) | 安装配置 `ser2net`、RFC 2217 YAML、权限、systemd |
+| [Windows 串口服务器](docs/serial-server-windows.md) | 原生 `ser2net`、`hub4com`、HHD / FabulaTech、WinSW 服务 |
+| [FRP 客户端配置](docs/frpc.md) | 共用的 `frpc.toml`、systemd 与 WinSW 服务化、暴露范围 |
+| [客户端测试](docs/client-testing.md) | pySerial / miniterm 端到端测试与波特率验证 |
+| [安全说明](docs/security.md) | 明文风险、令牌与 TLS 的作用范围、访问控制 |
+| [故障排查](docs/troubleshooting.md) | 串口、FRP 与 Windows 常见问题 |
+| [参考资料](docs/references.md) | 上游源与官方文档 |
+
+## 安全要点
+
+RFC 2217 本身既不加密也不认证；普通的 FRP TCP 代理会把 `remotePort` 变成 `frps` 主机上的一个明文 TCP 服务。请务必用源地址白名单、VPN 或其它经认证的加密传输加以保护，切勿把不受限的 RFC 2217 端口直接暴露到公网。详见 [安全说明](docs/security.md)。
diff --git a/assets/converter.jpg b/assets/converter.jpg
new file mode 100644
index 0000000..e9d7a64
--- /dev/null
+++ b/assets/converter.jpg
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:821a2c1c1d4d7345ae8041db5e37c35c06a23471b70c07d3ef25d419796554f0
+size 121436
diff --git a/docs/client-testing.md b/docs/client-testing.md
new file mode 100644
index 0000000..84af59e
--- /dev/null
+++ b/docs/client-testing.md
@@ -0,0 +1,102 @@
+[返回首页](../README.md)
+
+# RFC 2217 客户端端到端测试
+
+本文用于从远程客户端验证完整的 RFC 2217 链路：客户端通过 FRP 公网端点连接串口服务，完成 RFC 2217 协商、双向数据传输和远程串口参数修改。
+
+## 准备 pySerial
+
+Linux 或其他通常以 `python3` 启动 Python 的环境：
+
+```bash
+python3 -m pip install pyserial
+```
+
+Windows PowerShell：
+
+```powershell
+py -m pip install pyserial
+```
+
+## 使用 miniterm 连接
+
+Linux：
+
+```bash
+python3 -m serial.tools.miniterm \
+  rfc2217://FRPS_HOST:2217 \
+  9600
+```
+
+Windows PowerShell：
+
+```powershell
+py -m serial.tools.miniterm "rfc2217://FRPS_HOST:2217" 9600
+```
+
+将 `FRPS_HOST`、端口 `2217` 和初始波特率 `9600` 替换为实际部署值。
+
+对于需要轮询调制解调器状态的设备，pySerial URL 可使用：
+
+```text
+rfc2217://FRPS_HOST:2217?poll_modem
+```
+
+## 显式测试远程波特率修改
+
+保存并运行以下 Python 脚本：
+
+```python
+import serial
+
+port = serial.serial_for_url(
+    "rfc2217://FRPS_HOST:2217",
+    baudrate=9600,
+    timeout=1,
+)
+
+print("Initial baud rate:", port.baudrate)
+port.baudrate = 19200
+print("Changed baud rate:", port.baudrate)
+
+port.write(b"test\r\n")
+print(port.read(100))
+port.close()
+```
+
+Linux 运行方式：
+
+```bash
+python3 baud_test.py
+```
+
+Windows PowerShell 运行方式：
+
+```powershell
+py .\baud_test.py
+```
+
+执行 `port.baudrate = 19200` 时，pySerial 会发送 RFC 2217 控制命令。该命令经 FRP 转发后，应由串口服务器应用到 Linux 串口设备或 Windows COM 端口。不要只检查脚本中的属性值；还应确认物理串口确实切换到对应波特率。
+
+## 端到端验收项目
+
+至少验证以下项目：
+
+1. RFC 2217 协商成功。
+2. 串口数据可以双向传输。
+3. 客户端修改波特率时，物理串口参数随之改变。
+4. 断开后可以重新连接。
+5. USB 串口转换器拔出并重新插入后，服务能够恢复。
+6. 重启后，设备与串口服务的映射仍然正确。
+
+## 为什么 TCP 可达不等于 RFC 2217 可用
+
+普通 `telnet`、裸 TCP 客户端或端口探测只能证明 TCP 连接能够建立，不能验证 RFC 2217 协商，也不能验证远程波特率等串口控制功能。测试客户端必须实现 RFC 2217。
+
+例如，Windows 上的下列命令只验证 TCP 可达性：
+
+```powershell
+Test-NetConnection FRPS_HOST -Port 2217
+```
+
+即使该命令成功，仍必须使用 pySerial/miniterm 和波特率修改脚本完成上述端到端测试。
diff --git a/docs/frpc.md b/docs/frpc.md
new file mode 100644
index 0000000..99729a5
--- /dev/null
+++ b/docs/frpc.md
@@ -0,0 +1,333 @@
+[返回首页](../README.md)
+
+# FRP 客户端部署指南
+
+本文统一说明 Linux 与 Windows 串口服务器上的 `frpc` 部署。两种系统使用相同的 TOML 代理配置语义；差异只在安装目录、文件权限和服务管理方式。
+
+## 一、共用概念与配置
+
+### 1. 版本与连接参数
+
+先确认现有 `frps` 的版本，再从 [FRP 官方发布页](https://github.com/fatedier/frp/releases) 下载版本匹配、架构正确的客户端。精确匹配服务端版本是最简单稳妥的部署策略。本文使用 TOML；FRP 从 v0.52.0 开始支持 TOML 配置。
+
+从现有 `frpc` 配置或 `frps` 管理信息中取得以下值：
+
+- `serverAddr`：`frps` 地址；
+- `serverPort`：`frpc` 连接 `frps` 的控制/隧道端口，本部署为 `21315`；
+- `auth.token`：用于认证代理注册的共享令牌。
+
+### 2. 用 `.env` 保存真实地址与令牌
+
+真实地址和令牌不应写死进 `frpc.toml`，也不应提交到版本库。frpc 支持在配置里用 Go 模板读取环境变量，因此本手册把真实值集中放在仓库根目录的 `.env`，配置文件只引用变量名。
+
+`.env`（真实值，已被 `.gitignore` 忽略，仅保存在本地）：
+
+```dotenv
+FRP_SERVER_ADDR=your-frps-host.example.com
+FRP_SERVER_PORT=21315
+FRP_AUTH_TOKEN=your-frps-token
+```
+
+仓库另附可提交的占位模板 `.env.example`；将其复制为 `.env` 后填入真实值即可。配置文件中对应写成 `{{ .Envs.FRP_SERVER_ADDR }}` 等模板，frpc 启动时用**进程环境**里的同名变量渲染。
+
+注意：frpc 不会自动读取仓库根目录的 `.env`。该文件只是真实值的本地清单；部署时必须把这些变量注入 frpc 进程，具体见后文 Linux（systemd `EnvironmentFile`）与 Windows（WinSW `<env>`）小节。
+
+串口服务推荐只监听回环地址，代理中相应使用 `localIP = "127.0.0.1"`，让本机串口服务不直接暴露到 LAN，由 `frpc` 主动连接本地监听端口并转发流量。
+
+### 3. 单端口代理示例
+
+Linux 和 Windows 均可使用同一份 TOML 结构；只需让 `localPort` 与本机 RFC 2217 服务实际监听端口一致。
+
+```toml
+serverAddr = "{{ .Envs.FRP_SERVER_ADDR }}"
+serverPort = {{ .Envs.FRP_SERVER_PORT }}
+auth.token = "{{ .Envs.FRP_AUTH_TOKEN }}"
+
+[[proxies]]
+name = "ser2net-rfc2217-1"
+type = "tcp"
+localIP = "127.0.0.1"
+localPort = 2217
+remotePort = 2217
+```
+
+如果 Windows 上的 hub4com 或其他串口服务监听本机端口 `7001`，只调整本地侧即可：
+
+```toml
+[[proxies]]
+name = "windows-com3-rfc2217"
+type = "tcp"
+localIP = "127.0.0.1"
+localPort = 7001
+remotePort = 2217
+```
+
+### 4. 四端口代理示例
+
+保留同一组顶层连接参数，为每个通道添加一个 `[[proxies]]` 块：
+
+```toml
+serverAddr = "{{ .Envs.FRP_SERVER_ADDR }}"
+serverPort = {{ .Envs.FRP_SERVER_PORT }}
+auth.token = "{{ .Envs.FRP_AUTH_TOKEN }}"
+
+[[proxies]]
+name = "ser2net-rfc2217-1"
+type = "tcp"
+localIP = "127.0.0.1"
+localPort = 2217
+remotePort = 2217
+
+[[proxies]]
+name = "ser2net-rfc2217-2"
+type = "tcp"
+localIP = "127.0.0.1"
+localPort = 2218
+remotePort = 2218
+
+[[proxies]]
+name = "ser2net-rfc2217-3"
+type = "tcp"
+localIP = "127.0.0.1"
+localPort = 2219
+remotePort = 2219
+
+[[proxies]]
+name = "ser2net-rfc2217-4"
+type = "tcp"
+localIP = "127.0.0.1"
+localPort = 2220
+remotePort = 2220
+```
+
+### 5. 三类端口不要混淆
+
+- `serverPort = 21315`：FRP 控制/隧道端口，供 `frpc` 连接 `frps`，不是串口应用对外访问端口。
+- `localPort`：串口服务器本机的 RFC 2217 监听端口；本指南中通常绑定在 `127.0.0.1`。
+- `remotePort`：由 `frps` 主机对外打开、供远程 RFC 2217 客户端连接的应用端口。
+
+例如 `localPort = 7001`、`remotePort = 2217` 表示 `frpc` 从本机回环端口 `7001` 取流量，而外部客户端连接 `frps` 主机的 `2217` 端口。
+
+### 6. `frps` 侧要求
+
+若 `frps` 配置了 `allowPorts`，必须允许所选 `remotePort`；四端口示例需加入 `2217-2220`。`frps` 所在主机的防火墙还应：
+
+- 允许入站 TCP `21315`，供 `frpc` 建立控制连接；
+- 允许每个已配置的入站 TCP `remotePort`；
+- 尽量把公开串口端口限制为可信客户端源地址，而不是向整个互联网开放。
+
+## 二、Linux 部署
+
+### 1. 安装 `frpc`
+
+从匹配 `frps` 版本和目标架构的 Linux FRP 发布包中解压 `frpc`，然后安装二进制并创建配置目录：
+
+```bash
+sudo install -m 0755 frpc /usr/local/bin/frpc
+sudo install -d -m 0750 /etc/frp
+```
+
+### 2. 创建专用账户
+
+```bash
+getent group frpc >/dev/null || sudo groupadd --system frpc
+id frpc >/dev/null 2>&1 || sudo useradd \
+  --system \
+  --gid frpc \
+  --home-dir /nonexistent \
+  --shell /usr/sbin/nologin \
+  frpc
+```
+
+如果账户已存在，用 `id frpc` 核实。后续 systemd 单元明确以 `frpc:frpc` 运行。
+
+### 3. 写入配置与环境变量文件
+
+将“共用概念与配置”中的单端口或四端口 TOML（使用 `{{ .Envs.* }}` 模板）写入 `/etc/frp/frpc.toml`：
+
+```bash
+sudoedit /etc/frp/frpc.toml
+```
+
+再把真实值放入服务器上的环境变量文件 `/etc/frp/frpc.env`（内容与仓库根目录 `.env` 相同）：
+
+```bash
+sudoedit /etc/frp/frpc.env
+```
+
+```dotenv
+FRP_SERVER_ADDR=your-frps-host.example.com
+FRP_SERVER_PORT=21315
+FRP_AUTH_TOKEN=your-frps-token
+```
+
+真实令牌只在 `frpc.env` 中；`frpc.toml` 只含模板，不含明文。仅允许 `root` 修改、`frpc` 组读取二者：
+
+```bash
+sudo chown root:frpc /etc/frp/frpc.toml /etc/frp/frpc.env
+sudo chmod 0640 /etc/frp/frpc.toml /etc/frp/frpc.env
+```
+
+前台手动测试时，可先加载环境变量再运行：
+
+```bash
+set -a; . /etc/frp/frpc.env; set +a
+/usr/local/bin/frpc -c /etc/frp/frpc.toml
+```
+
+### 4. 配置依赖 `ser2net` 的 systemd 服务
+
+创建 `/etc/systemd/system/frpc.service`：
+
+```ini
+[Unit]
+Description=FRP client for ser2net RFC 2217
+Wants=network-online.target ser2net.service
+After=network-online.target ser2net.service
+
+[Service]
+Type=simple
+User=frpc
+Group=frpc
+EnvironmentFile=/etc/frp/frpc.env
+ExecStart=/usr/local/bin/frpc -c /etc/frp/frpc.toml
+Restart=on-failure
+RestartSec=5s
+NoNewPrivileges=true
+PrivateTmp=true
+ProtectHome=true
+ProtectSystem=strict
+
+[Install]
+WantedBy=multi-user.target
+```
+
+加载、启用并启动服务：
+
+```bash
+sudo systemctl daemon-reload
+sudo systemctl enable --now frpc
+sudo systemctl status frpc --no-pager
+```
+
+查看日志：
+
+```bash
+sudo journalctl -u frpc -n 100 --no-pager
+```
+
+日志应显示每个代理均已成功注册并启动。
+
+## 三、Windows 部署
+
+### 1. 准备归档目录
+
+从 [FRP 官方发布页](https://github.com/fatedier/frp/releases) 下载与已部署 `frps` 版本和 Windows 目标架构匹配的压缩包（通常为 `frp_*_windows_amd64.zip`），并采用以下布局：
+
+```text
+C:\frp\frpc.exe
+C:\frp\frpc.toml
+C:\frp\frpc-service.exe
+C:\frp\frpc-service.xml
+C:\frp\logs\
+```
+
+将“共用概念与配置”中的同一份 TOML（使用 `{{ .Envs.* }}` 模板）写入 `C:\frp\frpc.toml`。无需因为操作系统不同而改变代理结构；只需确保 `localPort` 与 Windows 上实际运行的 RFC 2217 服务监听端口一致。真实地址与令牌不写进 `frpc.toml`，而通过环境变量注入（手动测试见下方，服务方式见 WinSW 小节）。
+
+### 2. 验证并交互运行
+
+在安装服务前先在当前 PowerShell 会话注入环境变量，再检查配置并通过交互日志确认认证、远端端口和本地串口后端都能工作：
+
+```powershell
+Set-Location C:\frp
+$env:FRP_SERVER_ADDR = 'your-frps-host.example.com'
+$env:FRP_SERVER_PORT = '21315'
+$env:FRP_AUTH_TOKEN   = 'your-frps-token'
+.\frpc.exe verify -c .\frpc.toml
+.\frpc.exe -c .\frpc.toml
+```
+
+`verify` 只检查配置，不能证明认证成功、`remotePort` 已被允许或串口后端可用；这些必须从交互运行日志确认。
+
+### 3. 使用 WinSW 安装服务
+
+`frpc.exe` 是控制台程序，不应直接用 `sc.exe create` 作为服务安装方式。将稳定版本的 WinSW 可执行文件重命名为 `C:\frp\frpc-service.exe`，并创建 `C:\frp\frpc-service.xml`：
+
+```xml
+<service>
+  <id>frpc</id>
+  <name>FRP Client</name>
+  <description>FRP tunnel for the local RFC 2217 server</description>
+  <executable>%BASE%\frpc.exe</executable>
+  <arguments>-c "%BASE%\frpc.toml"</arguments>
+  <workingdirectory>%BASE%</workingdirectory>
+  <env name="FRP_SERVER_ADDR" value="your-frps-host.example.com" />
+  <env name="FRP_SERVER_PORT" value="21315" />
+  <env name="FRP_AUTH_TOKEN" value="your-frps-token" />
+  <logpath>%BASE%\logs</logpath>
+  <log mode="roll" />
+  <onfailure action="restart" delay="10 sec" />
+  <resetfailure>1 hour</resetfailure>
+</service>
+```
+
+将上面三个 `<env>` 的值替换为真实值（与本地 `.env` 保持一致）。frpc 启动时会用这些进程环境变量渲染 `frpc.toml` 中的 `{{ .Envs.* }}` 模板。真实令牌因此保存在该 XML 中，而 `frpc.toml` 只含模板、无明文。
+
+创建 XML 后立即收紧其 ACL（若服务以 LocalSystem 运行）：
+
+```bat
+icacls C:\frp\frpc-service.xml /inheritance:r
+icacls C:\frp\frpc-service.xml /grant:r "SYSTEM:(R)" "Administrators:(F)"
+```
+
+若改用专用服务账户，应相应调整 ACL，使该账户可读，同时避免普通本地用户读取令牌。
+
+随后在提升权限的 PowerShell 中安装并启动：
+
+```powershell
+New-Item -ItemType Directory -Force C:\frp\logs
+C:\frp\frpc-service.exe install
+C:\frp\frpc-service.exe start
+C:\frp\frpc-service.exe status
+```
+
+安装后可继续使用系统服务工具检查，并配置延迟自动启动：
+
+```bat
+sc.exe query frpc
+sc.exe qc frpc
+sc.exe config frpc start= delayed-auto
+```
+
+`sc.exe` 要求 `start=` 后保留空格。`frpc` 可以先于本地 RFC 2217 服务启动并稍后重连，但在本地监听器就绪前，外部连接会失败。延迟自动启动和 WinSW 的失败重启策略有助于处理开机时 USB 枚举较慢的情况。
+
+## 四、暴露面、防火墙与安全边界
+
+### 1. 回环监听与 Windows 防火墙
+
+当 RFC 2217 服务只绑定 `127.0.0.1`，且 `frpc.exe` 主动建立出站连接时，通常不需要添加 Windows 入站防火墙规则。Windows 主机只需能够出站访问 `FRPS_HOST:21315`。
+
+只有在串口服务确实必须监听 LAN 接口时，才添加范围严格的入站规则，例如：
+
+```powershell
+New-NetFirewallRule `
+  -DisplayName 'RFC2217 from operations subnet' `
+  -Direction Inbound `
+  -Action Allow `
+  -Protocol TCP `
+  -LocalPort 2217 `
+  -RemoteAddress '192.0.2.0/24' `
+  -Profile Domain,Private
+```
+
+推荐的回环专用配置不要添加此规则。
+
+### 2. `frps` 防火墙与访问控制
+
+无论客户端运行在 Linux 还是 Windows，`frps` 主机都需要与前文一致的控制端口、`remotePort`、`allowPorts` 和防火墙配置。尤其应对每个公开串口端口设置可信源 IP 白名单；不能因为 `frpc` 已认证就认为远程串口访问者也已认证。
+
+### 3. 令牌与 TLS 的范围
+
+- `auth.token` 仅认证 `frpc` 向 `frps` 注册代理的权限；它不会认证连接公开 `remotePort` 的最终用户。
+- FRP 传输 TLS 保护的是 `frpc` 到 `frps` 这一段。普通公开 TCP 代理不会因此自动加密或认证外部客户端到 `FRPS_HOST:remotePort` 的连接。
+- 本部署直接暴露该 TCP 端口，并在 `frps` 侧集中处理访问控制（源 IP 白名单、防火墙，必要时叠加 VPN）；frpc 侧只负责把本地回环监听转发出去。相关取舍见 [安全说明](security.md)。
diff --git a/docs/hardware.md b/docs/hardware.md
new file mode 100644
index 0000000..16c388f
--- /dev/null
+++ b/docs/hardware.md
@@ -0,0 +1,92 @@
+[返回首页](../README.md)
+
+# USB 转 RS-485 转换器选型与识别
+
+## 概述
+
+本方案使用 USB 转 RS-485 转换器把 Linux 主机连接到 RS-485 设备，再由串口服务器以 **RFC 2217** 模式提供远程访问。
+
+RFC 2217 与普通的原始 TCP 串口桥接不同：兼容客户端可以远程修改串口的波特率、数据位、校验位、停止位和控制线。
+
+硬件链路如下：
+
+```text
+Linux 串口服务器
+    |
+    v
+USB 转 RS-485 转换器
+    |
+    v
+RS-485 设备
+```
+
+转换器在 Linux 中通常显示为 `/dev/ttyUSB0`、`/dev/ttyACM0`，也可能使用厂商驱动提供的名称，例如 `/dev/ttyCH343USB0`。
+
+## 转换器选型
+
+产品图见 [`assets/converter.jpg`](../assets/converter.jpg)，提供以下芯片方案：
+
+| 端口数 | FTDI 方案 | WCH 方案 |
+|---|---|---|
+| 2 | FT2232H | CH342F |
+| 4 | FT4232H | CH344Q |
+
+### 推荐方案
+
+如需尽量降低 Linux 部署难度，建议选择：
+
+- 四路 RS-485：**FT4232H 隔离型**；
+- 两路 RS-485：**FT2232H 隔离型**。
+
+FTDI 的 `ftdi_sio` 驱动已获得广泛的 Linux 内核原生支持。产品图中标出的型号也是隔离型 FT4232H 四口版本。
+
+WCH 型号通常成本更低，也可作为合理选择。但多口 CH342/CH344 板卡可能以 USB CDC ACM 设备运行，也可能依赖 WCH 多口驱动，具体取决于产品和固件；它们并不都会以相同方式映射到主线内核的 `ch341` 驱动。采用 WCH 前，应在目标 Linux 镜像上测试具体板卡，并确认：
+
+- 每个通道的设备枚举方式；
+- 断开并重新连接后的稳定性；
+- 重启后的设备映射稳定性。
+
+### 电气隔离
+
+在以下场景中，强烈建议选择带电气隔离的型号：
+
+- RS-485 设备使用不同电源；
+- 线缆距离较长；
+- 设备之间可能存在地电位差。
+
+实际部署中，电气隔离和浪涌保护的重要性可能高于 USB 桥接芯片的品牌。
+
+## 在 Linux 中识别转换器
+
+连接转换器后，检查 USB 设备和内核日志：
+
+```bash
+lsusb
+sudo dmesg --follow
+```
+
+在另一个终端中查看稳定的串口设备链接：
+
+```bash
+ls -l /dev/serial/by-id/
+ls -l /dev/serial/by-path/
+```
+
+如需检查单个端口，请把以下命令中的 TTY 替换为目标主机上实际生成的设备：
+
+```bash
+udevadm info --query=property --name=/dev/ttyUSB0
+```
+
+根据转换器及其驱动，还应检查 `/dev/ttyACM*` 或 `/dev/ttyCH*`。
+
+## 使用稳定设备路径
+
+不要在长期配置中直接使用 `/dev/ttyUSB0` 等动态名称。系统重启或连接其他 USB 串口设备后，其编号可能发生变化。
+
+应按实际情况选择：
+
+- `/dev/serial/by-id/...`：每个通道都有唯一且可靠的标识时使用；
+- `/dev/serial/by-path/...`：需要让通道身份跟随物理 USB 插口和接口时使用。
+
+对于多口转换器，部署前应执行一次断开和重新连接，逐一确认每条稳定路径对应的物理 RS-485 端子，并为各端口贴上标签。
diff --git a/docs/references.md b/docs/references.md
new file mode 100644
index 0000000..3bbbc3d
--- /dev/null
+++ b/docs/references.md
@@ -0,0 +1,45 @@
+[返回首页](../README.md)
+
+# 参考资料
+
+本页按主题汇总本手册使用的上游源码与官方文档。
+
+## ser2net/gensio（串口服务器与协议库）
+
+- [ser2net 项目主页（SourceForge）](https://sourceforge.net/projects/ser2net/)
+- [ser2net 上游代码仓库](https://github.com/cminyard/ser2net)
+- [ser2net 上游 YAML 配置示例](https://github.com/cminyard/ser2net/blob/8cf64baadd55bb79749db80f3ac58a5b3ce44318/ser2net.yaml)
+- [ser2net 上游 YAML 手册](https://github.com/cminyard/ser2net/blob/8cf64baadd55bb79749db80f3ac58a5b3ce44318/ser2net.yaml.5)
+- [ser2net 上游 RFC 2217 测试](https://github.com/cminyard/ser2net/blob/8cf64baadd55bb79749db80f3ac58a5b3ce44318/tests/test_rfc2217.py)
+- [ser2net 4.6.7 Windows 版本](https://github.com/cminyard/ser2net/releases/tag/v4.6.7)
+- [gensio 3.0.2 Windows 版本](https://github.com/cminyard/gensio/releases/tag/v3.0.2)
+- [gensio Windows 构建说明](https://github.com/cminyard/gensio/blob/master/BUILDING.rst)
+- [gensio 协议与 Windows 串口设备文档](https://github.com/cminyard/gensio/blob/master/man/gensio.5)
+
+## FRP/RFC2217 client（FRP 转发与 RFC 2217 客户端）
+
+- [FRP 项目仓库](https://github.com/fatedier/frp)
+- [FRP 官方发布/下载页](https://github.com/fatedier/frp/releases)
+- [FRP TCP/UDP 代理文档](https://gofrp.org/en/docs/features/tcp-udp/)
+- [FRP 配置文件与环境变量模板](https://gofrp.org/en/docs/features/common/configure/)
+- [FRP 身份验证文档](https://gofrp.org/en/docs/features/common/authentication/)
+- [FRP 传输层 TLS 文档](https://gofrp.org/en/docs/features/common/network/network-tls/)
+- [pySerial RFC 2217 URL 处理器](https://pyserial.readthedocs.io/en/latest/url_handlers.html#rfc2217)
+
+## Windows tools（Windows 串口网络工具与服务包装器）
+
+- [hub4com 上游发布文件](https://sourceforge.net/projects/com0com/files/hub4com/2.1.0.0/)
+- [com0com 项目](https://com0com.sourceforge.net/)
+- [HHD TCP/IP Serial Ports Server 文档](https://hhdsoftwaredocs.online/vspt/sharing-com-ports-over-network/tcp-serial-ports-server/overview.html)
+- [HHD TCP/IP Serial Ports Server 命令行文档](https://hhdsoftwaredocs.online/vspt/sharing-com-ports-over-network/tcp-serial-ports-server/command-line-parameters.html)
+- [HHD TCP/IP Serial Ports Server 授权文档](https://hhdsoftwaredocs.online/vspt/redistribution/overview.html)
+- [FabulaTech Serial Port Redirector](https://www.fabulatech.com/serial-port-redirector.html)
+- [FabulaTech 物理服务器端口文档](https://www.fabulatech.com/serial-port-redirector-help/creating-physical-server-port.html)
+- [WinSW 服务包装器](https://github.com/winsw/winsw)
+
+## Windows system/driver docs（Windows 系统与驱动文档）
+
+- [Microsoft PnPUtil 命令语法](https://learn.microsoft.com/en-us/windows-hardware/drivers/devtest/pnputil-command-syntax)
+- [Microsoft PowerShell PnP 设备清单](https://learn.microsoft.com/en-us/powershell/module/pnpdevice/get-pnpdevice)
+- [Microsoft Windows 防火墙规则创建](https://learn.microsoft.com/en-us/powershell/module/netsecurity/new-netfirewallrule)
+- [FTDI Windows VCP 驱动程序](https://ftdichip.com/drivers/vcp-drivers/)
diff --git a/docs/security.md b/docs/security.md
new file mode 100644
index 0000000..f45d2ce
--- /dev/null
+++ b/docs/security.md
@@ -0,0 +1,44 @@
+[返回首页](../README.md)
+
+# 安全模型与部署控制
+
+## 威胁模型
+
+RFC 2217 协议本身不提供加密或身份认证。使用普通 FRP TCP 代理时，`remotePort` 会作为 `frps` 主机上的普通 TCP 服务对外开放。能够连接该端口的客户端可能读取或写入串行总线，并修改波特率、校验位等串口参数。
+
+FRP 传输层 TLS 只保护 `frpc` 与 `frps` 之间的隧道段；它不会自动加密或认证外部客户端到 `FRPS_HOST:remotePort` 的连接。因此，即使 FRP 传输层 TLS 已启用，公网侧 RFC 2217 连接仍可能是明文且无认证的。
+
+FRP 认证令牌的作用范围也不同：令牌用于授权 `frpc` 向 `frps` 注册代理，不用于认证连接已暴露 `remotePort` 的终端用户。
+
+## 部署控制
+
+本部署的选择是：`frpc` 侧只把本地回环监听经普通 TCP 代理暴露出去，边界访问控制主要在 `frps` 服务器上实施。不要将不受限制的 RFC 2217 端口直接暴露到公共互联网——请至少采用一种控制，必要时组合使用：
+
+1. **防火墙源地址白名单**（`frps` 侧边界控制）：仅允许已知客户端源地址访问 `2217-2220/tcp` 或实际配置的 `remotePort`。
+2. **认证 VPN**（`frps` 侧边界控制）：将 RFC 2217 端点置于 WireGuard、Tailscale 或其他经过认证的 VPN 后方。
+3. **ser2net/gensio TLS 与认证**（端到端应用层加固，不在 `frps` 侧）：如果所有客户端都支持相应协议栈，可另行启用 ser2net/gensio 的 TLS 和认证能力。
+
+推荐的 Windows 串口服务仅监听 `127.0.0.1`，由 `frpc.exe` 主动连接 `FRPS_HOST:21315`。这种配置通常不需要 Windows 入站防火墙规则。`frps` 主机仍需允许：
+
+- 入站 TCP `21315`，用于 FRP 控制流量；
+- 每个已配置 `remotePort` 的入站 TCP；
+- 对应的 FRP `allowPorts` 条目。
+
+只有当 Windows 串口服务确实需要监听 LAN 接口时，才添加范围受限的规则。例如：
+
+```powershell
+New-NetFirewallRule `
+  -DisplayName 'RFC2217 from operations subnet' `
+  -Direction Inbound `
+  -Action Allow `
+  -Protocol TCP `
+  -LocalPort 2217 `
+  -RemoteAddress '192.0.2.0/24' `
+  -Profile Domain,Private
+```
+
+不要为推荐的仅回环监听配置添加此入站规则。
+
+## RS-485 共享总线影响
+
+RS-485 通常由多个现场设备共享一条物理总线。RFC 2217 会修改物理 UART 的参数；某个会话改变波特率时，影响的是整条已连接总线，而不是单个从站。部署前应限制谁能够修改串口参数，并确保总线上所有设备使用一致的通信参数。
diff --git a/docs/serial-server-linux.md b/docs/serial-server-linux.md
new file mode 100644
index 0000000..5a4ef2e
--- /dev/null
+++ b/docs/serial-server-linux.md
@@ -0,0 +1,177 @@
+[返回首页](../README.md)
+
+# 在 Linux 上部署 ser2net RFC 2217 串口服务器
+
+本页说明如何在 Linux 上安装和配置 ser2net 4.x，以 RFC 2217 模式提供一个或四个串口。RFC 2217 客户端可以远程修改波特率、数据位、校验位、停止位和控制线。
+
+## 安装 ser2net
+
+Debian 或 Ubuntu：
+
+```bash
+sudo apt update
+sudo apt install ser2net
+```
+
+其他常见发行版：
+
+```bash
+# Fedora
+sudo dnf install ser2net
+
+# Arch Linux
+sudo pacman -S ser2net
+```
+
+确认已安装 ser2net 4.x：
+
+```bash
+ser2net -v
+```
+
+本文使用 ser2net 4.x 支持的现代 YAML 配置格式。
+
+## 确认配置文件路径
+
+当前 Debian 和 Ubuntu 软件包通常使用：
+
+```text
+/etc/ser2net.yaml
+```
+
+并通过 `/etc/default/ser2net` 中的 `CONFFILE` 选择该文件。上游构建版本和部分其他发行版则默认使用：
+
+```text
+/etc/ser2net/ser2net.yaml
+```
+
+编辑前先检查已安装的 systemd 服务：
+
+```bash
+systemctl cat ser2net
+sudo grep -E '^[[:space:]]*CONFFILE=' /etc/default/ser2net 2>/dev/null || true
+```
+
+以下示例使用 Debian/Ubuntu 常见的 `/etc/ser2net.yaml`。如果服务指向其他路径，应编辑它实际加载的文件，不要另建一个不会被使用的配置文件。
+
+## 配置 RFC 2217
+
+编辑软件包服务选择的配置文件：
+
+```bash
+sudoedit /etc/ser2net.yaml
+```
+
+### 单端口配置
+
+将串口设备路径替换为已确认的稳定路径：
+
+```yaml
+%YAML 1.1
+---
+connections:
+  rs485-1:
+    accepter: telnet(rfc2217),tcp,127.0.0.1,2217
+    connector: serialdev,/dev/serial/by-id/REPLACE_WITH_YOUR_DEVICE,115200n81,local
+```
+
+配置要点：
+
+- `telnet(rfc2217)` 显式启用 RFC 2217 协商及远程串口参数控制；
+- `tcp,127.0.0.1,2217` 仅监听回环地址，同机进程可以连接，但不会在 Linux 主机的 LAN 接口上单独暴露服务；
+- `115200n81` 是初始/默认参数：115200 baud、无校验、8 个数据位、1 个停止位；
+- RFC 2217 客户端连接后可以修改波特率及其他受支持的串口参数；
+- `local` 忽略调制解调器载波检测，通常适用于 USB 转 RS-485 转换器。
+
+无需添加额外选项来允许修改波特率；关键是使用 `telnet(rfc2217)` accepter。
+
+### 四端口 FT4232H 或 CH344Q 配置
+
+每个串口通道必须使用独立的本地 TCP 端口：
+
+```yaml
+%YAML 1.1
+---
+connections:
+  rs485-1:
+    accepter: telnet(rfc2217),tcp,127.0.0.1,2217
+    connector: serialdev,/dev/serial/by-id/REPLACE_PORT_1,115200n81,local
+
+  rs485-2:
+    accepter: telnet(rfc2217),tcp,127.0.0.1,2218
+    connector: serialdev,/dev/serial/by-id/REPLACE_PORT_2,115200n81,local
+
+  rs485-3:
+    accepter: telnet(rfc2217),tcp,127.0.0.1,2219
+    connector: serialdev,/dev/serial/by-id/REPLACE_PORT_3,115200n81,local
+
+  rs485-4:
+    accepter: telnet(rfc2217),tcp,127.0.0.1,2220
+    connector: serialdev,/dev/serial/by-id/REPLACE_PORT_4,115200n81,local
+```
+
+一个物理串口通常只应有一个活动客户端。如果应用允许新连接替换已经失效但未释放的连接，可查阅 ser2net 的 `kickolduser` 选项；若断开当前客户端可能产生安全问题，不要直接启用该选项。
+
+## 配置串口设备权限
+
+不同发行版的软件包可能使用不同的服务账户。先检查服务用户和用户组：
+
+```bash
+systemctl show ser2net -p User -p Group
+```
+
+如果服务以专用 `ser2net` 用户运行，应确保该账户可以打开串口设备。在通过 `dialout` 组授予串口访问权限的发行版上，执行：
+
+```bash
+sudo usermod -aG dialout ser2net
+```
+
+然后重启服务。如果服务已配置 `Group=dialout`，或发行版软件包让服务以 root 身份运行，则无需执行该命令。
+
+检查稳定链接及其目标设备的实际所有权：
+
+```bash
+ls -l /dev/serial/by-id/REPLACE_WITH_YOUR_DEVICE
+ls -lL /dev/serial/by-id/REPLACE_WITH_YOUR_DEVICE
+```
+
+## 前台测试配置
+
+ser2net 当前没有无副作用的“仅验证配置”命令。前台测试前，先停止软件包提供的服务，避免它占用串口或监听端口：
+
+```bash
+sudo systemctl stop ser2net
+sudo ser2net -d -c /etc/ser2net.yaml
+```
+
+有效配置会启动监听器，并让进程保持在前台。配置错误、权限错误和设备打开错误会直接输出到终端。测试完成后按 `Ctrl-C` 退出。
+
+如果实际配置文件不在 `/etc/ser2net.yaml`，应在 `-c` 后使用服务实际加载的路径。
+
+## 启用和管理 systemd 服务
+
+启动服务并设置为开机自动启动：
+
+```bash
+sudo systemctl enable --now ser2net
+sudo systemctl restart ser2net
+sudo systemctl status ser2net --no-pager
+```
+
+确认服务仅监听回环地址：
+
+```bash
+sudo ss -ltnp | grep -E ':(2217|2218|2219|2220)[[:space:]]'
+```
+
+单端口配置的预期监听地址类似：
+
+```text
+127.0.0.1:2217
+```
+
+查看最近 100 条服务日志：
+
+```bash
+sudo journalctl -u ser2net -n 100 --no-pager
+```
diff --git a/docs/serial-server-windows.md b/docs/serial-server-windows.md
new file mode 100644
index 0000000..a43125c
--- /dev/null
+++ b/docs/serial-server-windows.md
@@ -0,0 +1,280 @@
+[返回首页](../README.md)
+
+# Windows 串口服务器部署
+
+本文仅说明 Windows 上将物理 COM 口发布为 RFC 2217 或原始 TCP 串口服务的方法。FRP 客户端配置、服务安装和防火墙规则请参阅 [FRP 客户端部署指南](frpc.md)。
+
+## 方案比较与建议
+
+| 方案 | 适用场景 | RFC 2217 | Windows 服务 | 主要注意事项 |
+|---|---|---:|---:|---|
+| 原生 Windows `ser2net` | 可控制安装环境的开源生产部署 | 支持 | 需使用 WinSW 等包装器 | 必须安装相互匹配的 `ser2net`/`gensio` 版本 |
+| `hub4com` | 快速开源实验或维护旧部署 | 支持 | 需使用外部包装器 | 上游最后一个版本发布于 2012 年 |
+| HHD TCP/IP Serial Ports Server | 偏好 GUI 的商业部署 | 支持 | 内置 | 运行主机需要 HHD Virtual Serial Port Tools 许可证 |
+| FabulaTech Serial Port Redirector | 需要持续维护和厂商支持的商业部署 | 支持 | 内置 | 收费，按容量授权 |
+
+建议如下：
+
+- 新建开源生产环境：优先使用原生 Windows `ser2net`。
+- 快速实验室验证：`hub4com` 配置最简单，但必须评估其年代和稳定性限制。
+- 需要 GUI、原生服务管理和商业支持：优先评估 FabulaTech。
+
+## 1. 安装转换器并确认 COM 口
+
+使用 Windows Update 或芯片厂商提供的已签名驱动。不要在未确认硬件型号时尝试安装 FTDI、WCH 等不同厂商的驱动；应先检查硬件 ID。
+
+在“设备管理器”中展开“端口（COM 和 LPT）”，选中转换器并打开“属性 → 详细信息”。记录以下信息：
+
+- COM 名称；
+- 包含 VID、PID 的硬件 ID；
+- 设备实例路径；
+- USB 序列号（如有）；
+- 容器 ID；
+- 位置路径。
+
+使用 PowerShell 盘点当前端口：
+
+```powershell
+Get-PnpDevice -Class Ports -PresentOnly |
+  Sort-Object FriendlyName |
+  Format-Table Status, FriendlyName, InstanceId -AutoSize
+
+Get-CimInstance -ClassName Win32_SerialPort |
+  Select-Object DeviceID, Name, Description, PNPDeviceID |
+  Format-Table -AutoSize
+```
+
+也可使用 pySerial 查看更详细的信息：
+
+```powershell
+py -m pip install pyserial
+py -m serial.tools.list_ports -v
+```
+
+COM 编号只是 Windows 分配结果，不是持久的硬件身份。具有唯一序列号的 FTDI 转换器通常能稳定保留编号，但部分低价转换器没有序列号，或多个设备使用重复序列号。若无法通过序列号区分同型号设备，应固定其物理 USB 插口并记录位置路径。
+
+端口编号达到 COM10 及以上时，各工具使用的写法不同：
+
+- 原生 Windows API：`\\.\COM10`
+- `ser2net`/gensio：`//./COM10`
+- pySerial：`COM10`
+
+## 2. 方案 A：原生 Windows ser2net
+
+### 2.1 安装 ser2net 和 gensio
+
+截至 2026 年 7 月，上游提供以下原生 Windows 安装包：
+
+- `ser2net` 4.6.7；
+- `gensio` 3.0.2。
+
+预编译包之间存在版本耦合，应安装同期配套版本，不要任意混用：
+
+1. `Gensio-3.0.2-windows.exe`
+2. `Ser2Net-4.6.7-windows.exe`
+
+使用更新版本前先检查上游发布说明，配套版本号会随时间变化。原生安装包使用 MinGW/UCRT 运行时 DLL，但运行时不需要 MSYS2 shell。
+
+默认配置文件通常位于：
+
+```text
+C:\Program Files\Ser2Net\etc\ser2net\ser2net.yaml
+```
+
+以管理员身份创建或编辑该文件。
+
+### 2.2 配置 COM3 的 RFC 2217 服务
+
+新部署应使用现代的 version-2 YAML：
+
+```yaml
+%YAML 1.1
+---
+connections:
+  com3:
+    accepter: telnet(rfc2217),tcp,127.0.0.1,2217
+    connector: serialdev,//./COM3,115200n81
+```
+
+该配置具有以下行为：
+
+- 仅监听 IPv4 回环地址；
+- 允许同一 Windows 主机上的隧道客户端连接；
+- 不会额外在局域网接口上暴露通配监听器；
+- COM3 初始参数为 115200 波特、无校验、8 数据位、1 停止位；
+- 兼容的 RFC 2217 客户端可远程修改串口参数。
+
+旧的 version-1 写法仍可被 `ser2net` 接受：
+
+```yaml
+connection: &com3
+  accepter: telnet(rfc2217),tcp,127.0.0.1,2217
+  connector: serialdev,//./COM3,115200n81
+```
+
+但 version 1 有意不遵循标准 YAML。新部署必须优先使用 `connections:` 映射。
+
+若只需要原始 TCP，不需要远程调整串口参数，可删除 `telnet(rfc2217)`：
+
+```yaml
+%YAML 1.1
+---
+connections:
+  com3-raw:
+    accepter: tcp,127.0.0.1,2217
+    connector: serialdev,//./COM3,115200n81
+```
+
+远端客户端需要选择波特率时，不要使用原始 TCP 模式。
+
+### 2.3 交互式本机测试
+
+创建服务前，先在管理员 PowerShell 中前台运行：
+
+```powershell
+& 'C:\Program Files\Ser2Net\bin\ser2net.exe' `
+  -d `
+  -c 'C:\Program Files\Ser2Net\etc\ser2net\ser2net.yaml'
+```
+
+`-d` 会保持前台运行并输出诊断信息。测试完成后按 `Ctrl-C` 停止。
+
+若已安装 gensio 客户端工具，可测试本机协议栈：
+
+```powershell
+gensiot 'telnet(rfc2217),tcp,127.0.0.1,2217'
+```
+
+仅能建立原始 TCP 连接，不能证明 RFC 2217 完整可用；还必须使用 pySerial 等兼容客户端实际测试一次波特率变更。
+
+### 2.4 使用 WinSW 注册 Windows 服务
+
+官方 Windows `ser2net` 安装程序不会创建原生 Windows 服务。不要使用 `sc.exe create` 直接注册 `ser2net.exe`：它是控制台程序，没有实现 Windows Service Control Manager 生命周期。
+
+使用 [WinSW](https://github.com/winsw/winsw) 等服务包装器：
+
+1. 将稳定版 WinSW 放在 `ser2net.exe` 所在目录。
+2. 将 WinSW 重命名为 `ser2net-service.exe`。
+3. 在同一目录创建同名配置文件 `ser2net-service.xml`：
+
+```xml
+<service>
+  <id>ser2net-rfc2217</id>
+  <name>ser2net RFC 2217</name>
+  <description>Exports Windows COM ports through RFC 2217</description>
+  <executable>%BASE%\ser2net.exe</executable>
+  <arguments>-n -c "%BASE%\..\etc\ser2net\ser2net.yaml"</arguments>
+  <workingdirectory>%BASE%</workingdirectory>
+  <logpath>C:\ProgramData\Ser2Net\logs</logpath>
+  <log mode="roll" />
+  <onfailure action="restart" delay="10 sec" />
+  <resetfailure>1 hour</resetfailure>
+</service>
+```
+
+在管理员 PowerShell 中创建日志目录，然后安装、启动并检查服务：
+
+```powershell
+New-Item -ItemType Directory -Force C:\ProgramData\Ser2Net\logs
+& 'C:\Program Files\Ser2Net\bin\ser2net-service.exe' install
+& 'C:\Program Files\Ser2Net\bin\ser2net-service.exe' start
+& 'C:\Program Files\Ser2Net\bin\ser2net-service.exe' status
+```
+
+上述示例为简化部署而使用 WinSW 默认服务账户。生产环境应改用专用的最小权限服务身份，只授予必要的程序文件、配置文件和日志目录访问权限。
+
+## 3. 方案 B：hub4com
+
+com0com 项目包含提供 RFC 2217 功能的 `hub4com` 包装器。若发布的是现有物理 COM 口，不需要创建 com0com 虚拟串口对。
+
+上游基础示例为：
+
+```bat
+com2tcp-rfc2217 COM3 7001
+```
+
+该命令默认监听所有 IPv4 接口。供本机隧道客户端使用时，应显式绑定回环地址并使用规范 COM 写法：
+
+```bat
+com2tcp-rfc2217 --interface 127.0.0.1 \\.\COM3 7001
+```
+
+高编号端口（例如 COM17）：
+
+```bat
+com2tcp-rfc2217 --interface 127.0.0.1 \\.\COM17 7001
+```
+
+包装器默认会持续占用物理 COM 口。若只希望在网络客户端已连接时打开串口，可使用：
+
+```bat
+com2tcp-rfc2217 --interface 127.0.0.1 --share-com-port \\.\COM3 7001
+```
+
+仅在业务确实要求连接间释放端口时使用 `--share-com-port`；该选项不代表多个进程可以安全地并发占用同一串口。
+
+### 3.1 限制与服务化
+
+- 上游最新 `hub4com` 版本为 2012 年发布的 2.1.0.0。
+- 分发的可执行文件是 32 位控制台程序。
+- 不内置 Windows 服务宿主。
+- 不提供 TLS、身份认证或访问控制。
+- 必须在实际部署镜像上验证现代 Windows、USB 重连、睡眠/恢复、服务账户和长时间运行行为。
+
+只需要发布物理 COM 口时，不要安装 com0com 内核驱动。已签名的 com0com 驱动只在创建虚拟 COM 对时需要，典型场景是 Windows 客户端必须向旧应用呈现本地 COM 口。
+
+服务化时可沿用前述 WinSW 模式：将 `com2tcp-rfc2217` 包装命令拆分为 WinSW 的 executable 和 arguments，并将 working directory 指向解压后的 `hub4com` 目录，确保可执行文件和插件能被找到。上线前应启用失败重启，并执行冷启动、USB 重插和睡眠恢复测试。
+
+## 4. 方案 C：商业 GUI 产品
+
+### 4.1 HHD TCP/IP Serial Ports Server
+
+HHD TCP/IP Serial Ports Server 可将现有物理或 USB COM 口发布为原始 TCP 或 RFC 2217，并提供 GUI、命令行管理和内置 Windows 服务安装能力。
+
+安装为服务：
+
+```bat
+psip_server.exe -install-service
+```
+
+文档给出的独立端口映射命令为：
+
+```bat
+psip_server.exe COM5=11111
+```
+
+省略协议时默认使用 RFC 2217；`,raw` 用于选择原始 TCP。
+
+部署前必须确认以下限制：
+
+- 根据厂商文档，服务会监听所有可用网络接口。如果预期只通过隧道访问，必须限制其局域网直接访问。
+- 当前公开的服务器文档中未验证到内置 TLS 功能。
+- HHD 的再分发文档说明：运行 TCP/IP Serial Ports Server 的计算机需要 Virtual Serial Port Tools 许可证。
+- HHD 另有一个限制条件不同的 Free Virtual Serial Ports 产品；不能据此假定 TCP/IP Serial Ports Server 已获得生产许可。
+
+部署前向 HHD 确认当前试用条款和生产授权条件。
+
+### 4.2 FabulaTech Serial Port Redirector
+
+应选用 **Serial Port Redirector**，而不是 Network Serial Port Kit。该产品支持：
+
+- 物理 COM 口服务器模式；
+- RFC 2217 和原始 TCP；
+- GUI 和 `SPRCmd.exe` 配置；
+- 作为 Windows 系统服务在用户登录前运行；
+- x86、x64 和 ARM64 安装包；
+- 厂商所述的可选证书式 SSL，以及可选客户端认证。
+
+文档中的物理串口服务器命令为：
+
+```bat
+SPRCmd.exe setserver telnet-bin 3 7001 physical
+```
+
+该语法可能随产品版本变化；自动化前必须用已安装版本的帮助信息复核。
+
+FabulaTech 是按容量收费的商业产品，试用期有限。公开说明没有完全明确试用期间物理服务器端口的计数方式，应向厂商确认。厂商将加密传输称为“SSL”，但已审阅的公开资料未说明实际启用的 TLS 协议版本和密码套件基线；如涉及合规要求，必须单独验证。
+
+## 5. 故障排查
+
+Windows 侧的常见问题——COM 口占用或拒绝访问、重新连接后 COM 编号变化、开机时序（服务早于 USB 枚举）、hub4com 意外监听 LAN、原生 ser2net 无法加载 DLL——集中在 [故障排查](troubleshooting.md) 一页的“Windows 特定问题”一节，此处不再重复。
diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md
new file mode 100644
index 0000000..0a55388
--- /dev/null
+++ b/docs/troubleshooting.md
@@ -0,0 +1,127 @@
+[返回首页](../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`，并避免混用不同代的预编译发行包。