简介这是一份面向Qt开发者的Telnet客户端完整源码版本v2.1以LGPL/GPL3开源协议发布。项目基于Qt框架完整实现了Telnet协议的关键环节包括TCP连接管理、命令交互的编码与解码、选项协商、异常处理与会话重连并自带simpleClient示例与跨平台构建脚本适合需要学习Qt网络编程、终端模拟或Telnet协议实现的开发者阅读。资源包共29个文件涵盖4个pro工程文件、qttelnet核心cpp与h源码、pri构建配置以及txt说明文档、qdoc/qch帮助文档、html页面与png图片等压缩包整体仅79KB目录将src、examples、doc、buildlib清晰分区便于按模块查阅。目前已有283人学习/浏览。通过研读源码可以掌握在Qt中搭建终端模拟客户端的完整思路理解QWidget界面与网络通信组件的配合方式结合examples示例还能学习工程组织、模块划分与跨平台构建方法代码侧重协议交互细节适合二次开发或教学演示。1. 项目整体设计与思路拆解做嵌入式开发这些年打交道最多的两个工具就是串口终端和Telnet终端。串口好办工具一堆但Telnet这个场景反而挺尴尬——Windows自带的telnet客户端难用不说对终端仿真、乱码、字体这些细节几乎是零支持用Xshell、SecureCRT这类商业软件吧功能又过于臃肿很多功能根本用不上还得考虑授权问题。所以我干脆自己动手用Qt写了一个Telnet客户端也就是这个v2.1版本的源码项目。1.1 为什么自己写Telnet客户端先说一个很扎心的现状Qt官方并没有专门为Telnet协议封装好的高层类。Qt的QNetworkAccessManager是给HTTP这类应用层协议用的QTcpSocket虽然能干这事但Telnet协议本身的状态机、选项协商、命令字节处理这些都得自己实现。很多人在网上搜Qt telnet拿到的要么是半成品要么就是直接把数据往QTcpSocket里一塞就完事完全没处理Telnet协议里最关键的IACInterpret As Command字节。这样导致的直接后果就是连上设备之后交互乱了套设备发来的WILL ECHO、WILL SUPPRESS GO AHEAD这些协商指令会直接变成乱码显示出来终端行为也完全不对。v2.1这个版本的定位很明确做一个开箱即用的Telnet客户端把协议解析、选项协商、终端显示这三件事都处理好同时保持代码轻量、单文件可移植、直接在Qt工程里拖进去就能编译。1.2 模块划分与选区考量整个项目的模块划分其实很清晰就三层网络层负责TCP连接的建立、断开、数据收发直接封装QTcpSocket协议层解析Telnet数据流中的控制命令处理选项协商向上层暴露干净的读写接口UI层连接配置界面、命令输入、回显显示、日志记录v2.1相比v2.0最大的改动在协议层——把原来散乱的switch-case处理改成了一套基于状态机的解析流程同时补齐了对NAWSNegotiate About Window Size窗口尺寸协商和TTYPETerminal Type终端类型协商这两个选项的支持。这两个选项在实际调试中太常用了不告诉对端终端类型很多网络设备会拒绝给你全功能菜单或者行为表现异常。2. Telnet协议核心原理别被老协议吓住Telnet协议是1969年就定型的远古协议但它并没有过时——今天几乎所有网络设备的管理接口、嵌入式Linux的调试入口、光猫超级密码获取通道底层用的还是这套协议。理解了Telnet协议很多设备交互上的疑难杂症也就迎刃而解了。2.1 IAC命令与状态机基础Telnet协议有个关键设计数据流中的普通数据字节和控制命令字节是混在一起传输的。如果直接把收到的QByteArray当普通文本处理命令字节就会和显示内容混在一起。解决方法是引入一个特殊字节IACInterpret As Command十进制255。当接收方看到这个字节就知道后续的数据不是普通文本而是一条控制命令。在一个简单的Telnet数据流中可能出现这样的原始数据FF FD 18 FF FB 01 68 65 6C 6C 6F 0D 0A其中FF FD 18是一条命令IAC DO 终端类型0x18表示对端要求我们发送终端类型FF FB 01是另一条IAC WILL ECHO表示对端准备开启回显后面的68 65 6C 6C 6F才是真正的文本hello。如果代码不解析直接在文本框里显示那一行字符会变成一堆乱码。v2.1的协议层核心就是一个状态机专门区分当前字节属于命令还是普通数据。状态机逻辑其实很朴素初始状态是Data所有字节都按普通数据输出收到IAC进入IAC状态等待下一个字节如果第二个字节是命令类型如WILL、DO再进入CommandOption状态继续读一个字节获取选项编号如果是SBSubnegotiation子协商进入子协商的接收状态直到遇到IAC SE才结束2.2 选项协商机制解析Telnet协议里最活跃的部分就是选项协商。打个比方你到一家餐厅服务员服务器会先问问你需不需要茶水回显、需不需要靠窗座位窗口尺寸、能不能扫码点餐终端类型。这些询问就是选项协商报文。常见的选项协商命令有四个配合选项编号使用命令字节含义WILL251发送方将要开启某个选项WONT252发送方拒绝开启某个选项DO253发送方要求接收方开启某个选项DONT254发送方要求接收方关闭某个选项常见的选项编号有选项字节说明ECHO1回显SUPPRESS GO AHEAD3抑制Go AheadSTATUS5状态查询TTYPE24终端类型NAWS31窗口尺寸v2.1的协议层会做这样几件事收到WILL ECHO回复DO ECHO表示接受回显开启收到DO TTYPE回复WILL TTYPE然后发送子协商报文附上终端类型字符串收到DO NAWS回复WILL NAWS然后发送当前窗口宽度和高度不处理这些协商的后果是什么大部分设备在收到DONT或没有任何响应后会降级到最保守的交互模式比如不给你回显你敲命令看不见自己打了什么、不给你菜单某些交换机会隐藏高级命令。所以协议层这一块不能偷懒。2.3 子协商Subnegotiation的处理子协商是选项协商的进阶版用于传输比开/关更复杂的信息。格式是IAC SB 选项编号 数据... IAC SE比如TTYPE的子协商全流程是这样的服务器发IAC DO TTYPE请告诉我你的终端类型客户端回IAC WILL TTYPE好的我会发服务器发IAC SB TTYPE 1 IAC SE请发你的终端类型1表示SEND客户端回IAC SB TTYPE 0 xterm IAC SE我的终端类型是xterm0表示IS整个过程中SB和SE是成对出现的中间的数据段不能被普通状态机拦截。所以我在v2.1里专门加了SubNegotiation子状态进入SB后所有字节都往缓冲区里存直到遇到IAC SE才解除状态。这一步不处理好数据流会错乱。3. v2.1核心代码实现与实操要点如果只打算拿源码直接编译你可以跳过协议理论那部分但代码的几个关键模块还是要看懂后面排查问题会省力很多。3.1 连接管理模块封装QTcpSocketv2.1的连接管理依然基于QTcpSocket但做了几个增强超时处理、自动重连、错误分类。核心连接函数长这样bool TelnetClient::connectToHost(const QString host, quint16 port, int timeoutMs) { if (m_socket-state() ! QAbstractSocket::UnconnectedState) { m_socket-abort(); } m_socket-connectToHost(host, port); if (!m_socket-waitForConnected(timeoutMs)) { m_lastError m_socket-errorString(); m_socket-abort(); return false; } m_connected true; m_parser.reset(); emit connected(); return true; }注意waitForConnected是一个阻塞调用如果在UI线程里直接用界面会卡死。v2.1的做法是把连接操作丢到QtConcurrent::run里执行连接完成后再通过信号槽把结果传回主线程。这样既保持了代码简单又避免了界面冻结。另外一个细节是m_parser.reset()。每建立一次新连接协议解析器的状态机必须重置——你不想上一个连接残留在缓冲区里的半截报文污染新连接吧。这一点在实际切换不同设备调试时尤为重要。断开连接的实现也做了优化不是直接暴力disconnectFromHost()而是先尝试通知对端再断开void TelnetClient::disconnectFromHost() { if (!m_connected) return; // 发送Telnet断开命令: IAC IP (Interrupt Process) QByteArray bye; bye.append(static_castchar(255)); // IAC bye.append(static_castchar(244)); // IP m_socket-write(bye); m_socket-flush(); m_socket-disconnectFromHost(); m_connected false; emit disconnected(); }很多设备对突然断开的TCP连接处理得很粗糙导致端口长期处于TIME_WAIT状态重连就报address already in use。主动发一个IAC IP告诉对端我要中断本次进程了可以明显降低这种概率。3.2 协议解析器QByteArray缓冲兼容粘包嵌入式设备调试中最常见的网络问题是粘包和半包。TCP是流式协议不会保证每次readyRead信号读到的一定是完整数据所以协议解析器必须自己维护一个缓冲区。v2.1的做法是这样的void TelnetClient::onReadyRead() { m_buffer.append(m_socket-readAll()); parseBuffer(); } void TelnetClient::parseBuffer() { int i 0; while (i m_buffer.size()) { uchar byte static_castuchar(m_buffer.at(i)); switch (m_state) { case ParserState::Data: if (byte IAC) { m_state ParserState::IAC; } else { appendToDisplay(byte); } i; break; case ParserState::IAC: // 判断下一个字节 switch (byte) { case Command::WILL: case Command::WONT: case Command::DO: case Command::DONT: m_pendingCmd byte; m_state ParserState::Command; break; case Command::SB: m_subBuffer.clear(); m_state ParserState::SubNegotiation; break; case Command::IAC: // 转义数据中出现的255 appendToDisplay(byte); m_state ParserState::Data; break; default: m_state ParserState::Data; break; } i; break; case ParserState::Command: handleOption(m_pendingCmd, byte); m_state ParserState::Data; i; break; case ParserState::SubNegotiation: if (byte IAC) { // 检查下一个字节是不是SE if (i 1 m_buffer.size() m_buffer.at(i 1) Command::SE) { handleSubNegotiation(m_subBuffer); m_state ParserState::Data; i 2; continue; } m_subBuffer.append(byte); } else { m_subBuffer.append(byte); } i; break; } } m_buffer.remove(0, i); }这版解析器最需要注意的地方是IAC IAC转义序列。255这个字节既是命令的引导符也可能作为普通数据出现。协议规定如果数据中真的需要传255这个字节发送方会将其写成IAC IAC两个连续字节。解析时必须把这个情况单独处理否则数据就会被切断、显示异常。3.3 选项协商的自动回包之前讲过协议层要做的关键事情之一是对WILL/DO等请求自动回包。v2.1的handleOption函数是这么实现的void TelnetClient::handleOption(uchar cmd, uchar option) { QByteArray response; switch (cmd) { case Command::WILL: switch (option) { case Option::ECHO: // 接受回显 response.append(static_castchar(IAC)); response.append(static_castchar(Command::DO)); response.append(static_castchar(Option::ECHO)); break; case Option::SUPPRESS_GO_AHEAD: response.append(static_castchar(IAC)); response.append(static_castchar(Command::DO)); response.append(static_castchar(Option::SUPPRESS_GO_AHEAD)); break; case Option::TTYPE: response.append(static_castchar(IAC)); response.append(static_castchar(Command::DO)); response.append(static_castchar(Option::TTYPE)); break; default: // 不支持的选项回复DONT response.append(static_castchar(IAC)); response.append(static_castchar(Command::DONT)); response.append(static_castchar(option)); break; } break; case Command::DO: switch (option) { case Option::TTYPE: response.append(static_castchar(IAC)); response.append(static_castchar(Command::WILL)); response.append(static_castchar(Option::TTYPE)); // 立即发送终端类型 sendTerminalType(); break; case Option::NAWS: response.append(static_castchar(IAC)); response.append(static_castchar(Command::WILL)); response.append(static_castchar(Option::NAWS)); sendWindowSize(); break; default: response.append(static_castchar(IAC)); response.append(static_castchar(Command::WONT)); response.append(static_castchar(option)); break; } break; default: break; } if (!response.isEmpty()) { m_socket-write(response); } }这里有个细节对于不认识的选项一定要回WONT或DONT而不是什么都不发。因为很多网络设备是你默认接受的假设不发回包它就一直等导致后续交互卡住。这就像电话沟通中对方问你问题你不回答他就只能一直追问或者干等。3.4 UI层从QPlainTextEdit到终端渲染v2.1的UI层很简单上面一个QPlainTextEdit做显示区下面一个QLineEdit做输入区加一个连接按钮。但这里埋了一个坑QPlainTextEdit默认不支持终端控制序列比如\x1b[2J清屏、\x1b[0m重置颜色、\x1b[1;31m红色粗体等。设备端会发这些ANSI转义序列直接显示就是一片乱七八糟的字符。我的处理方案是写了一个轻量的TerminalTextEdit类继承QPlainTextEdit重写appendData(const QByteArray)方法在做解析时把常见的控制序列剥掉仅保留可显示的文本。完整的VT100仿真工作量大得惊人但v2.1里做了个折中识别并处理最常用的几个序列——清屏、光标归位、颜色重置、换行、回车、退格。void TerminalTextEdit::appendData(const QByteArray data) { int i 0; while (i data.size()) { uchar ch static_castuchar(data.at(i)); if (ch 0x1B) { // ESC // 查找下一个字母字符跳过完整的控制序列 int j i 1; while (j data.size() !(data.at(j) 0x40 data.at(j) 0x7E)) { j; } parseEscapeSequence(data.mid(i, j - i 1)); i j 1; } else if (ch \r) { // 忽略裸CR除非后面跟LF i; } else { insertPlainText(QString::fromUtf8(data.mid(i, 1))); i; } } ensureCursorVisible(); }注意这里用QString::fromUtf8处理数据。如果设备返回的是GBK编码的中文显示会变成问号。很多光猫和旧交换机默认输出GBK编码所以v2.1的编码处理也要做配置在连接窗口里加一个编码下拉框支持UTF-8、GBK、GB18030。实际处理时用QTextCodec转换一行代码的事但能救回无数乱码页面。3.5 发送数据的处理输入框的发送逻辑也做了处理不只是简单地write(text.toUtf8())。关键要处理回车换行符——Telnet协议规定回车是\r\nCRLF而不是普通聊天工具的\n。void MainWindow::onCommandSubmitted(const QString text) { if (!m_telnet-isConnected()) { appendLocalMessage(tr(尚未连接到服务器)); return; } QByteArray data text.toUtf8(); data.replace(\n, \r\n); m_telnet-sendData(data); m_inputEdit-clear(); }还有个小细节回显。连接开启回显后你敲的命令会在本地显示一次设备端又会回显一次导致命令看起来出现两遍。实际处理是在显示区过滤掉自己发的数据只保留设备端的回显或者干脆在本地禁止回显、只显示设备端返回的内容。v2.1默认是后者这样更加贴近真正的终端体验。4. 常见问题与排查技巧实录这部分是实际调试中踩坑最集中的地方我把遇到的高频问题整理成一个速查表再逐个细说。问题现象可能原因解决方案连接后立即断开提示errno 104对端主动重置连接协议协商失败先检查端口和协议类型抓包确认协商包是否正确ping通但telnet端口不通设备禁用了telnet服务防火墙拦截确认端口是否为23用nmap -p 23扫描检查服务配置中文显示乱码编码不匹配切换GBK/UTF-8编码命令敲了没反应没发CRLF确认发数据时是否替换为\r\n界面卡死阻塞调用waitForConnected改用异步连接或丢到线程池设备内容显示重叠不换行CR/LF处理不当把\r\n统一交给渲染层处理4.1 errno 104Connection reset by peer这是最常见的报错表示对端把你的TCP连接主动重置了。我遇到过很多次排查路径基本固定第一确认协议类型。很多设备同时开了telnet和SSH你连的是23端口但设备那边根本没起telnet服务壳都不存在连上就RST。第二检查是否被防火墙拦截。第三抓包看协商过程。如果设备端发送了WILL ECHO、你的客户端回了DO ECHO但设备后续仍没有响应很可能是协商包格式不对比如字段顺序错了、IAC重复了、或者直接用文本工具发送了不可见字节。在v2.1里我专门加了一个协议日志窗口会把原始二进制数据按十六进制打出来排查这类问题效率极高。4.2 快速定位协议错乱十六进制日志聊到排查要特别建议你在自己的工具里加上十六进制日志。只靠肉眼观察文本输出很多协议问题根本看不见。举个例子Telnet传输过程中收到的数据经常是这样FF FD 1F FF FB 03 FF FD 18 FF FB 01 ......这些字节在文本显示区基本是不可见的或者会变成奇怪的符号但你根本看不出是什么协议指令。十六进制日志把每条收到的原始报文都打出来配合协议文档对照协议协商成功与否一目了然。v2.1里实现这个功能很简单就是在onReadyRead和sendData两个函数的入口加一行emit rawDataReceived(m_buffer.mid(0, n)); // n为本次读取的字节数在UI上接一个QPlainTextEdit把字节转成十六进制输出同时保留ASCII版本QString hex data.toHex( ).toUpper(); QString ascii; for (char c : data) { ascii.append(QChar::isPrint(static_castuchar(c)) ? QChar(c) : QChar(.)); } m_hexLog-appendPlainText(hex ascii);这个工具在跟设备厂商联调协议问题时简直是救命的。你可以直接把日志丢给对方双方对着报文说话。4.3 ping通但telnet一直失败另一个高频问题是设备能ping通但telnet 23端口就是连不上。这个问题的排查路径要宽一些设备是否开启了telnet服务很多设备默认只开SSHtelnet服务要在配置页面手动开启或者需要通过串口/特定命令激活。是否有ACL限制不少网络设备支持管理ACL只允许指定源IP访问管理端口。你的机器IP可能不在允许列表里。是否存在中间防火墙拦截这个问题在办公网环境很常见。端口冲突设备上23端口被其他服务占用或者设备本身telnet进程挂了。针对这些问题v2.1额外加了一个小功能连接前的端口探测。说白了就是用QTcpSocket先试探性连接一下端口如果连接成功则立刻断开然后再走完整的Telnet握手流程。这个功能用于区分端口不通和协议协商失败可以在界面上直接提示用户。4.4 Qt环境相关的几个坑除了协议层的问题开发环境本身也有几个容易踩的坑尤其新手容易在这里卡很久。一个是qxcbconnection: failed to initialize xrandr这类X11错误。在无图形界面的服务器上运行Qt程序或者通过SSH远程执行带GUI的Qt程序时经常碰到。解决办法很朴素程序本身不需要GUI就编译成命令行版本或者用QT_QPA_PLATFORMoffscreen环境变量强制使用离屏渲染。不过如果你要是做一个纯命令行交互工具那压根别带Qt的GUI模块直接用QCoreApplication就行。另一个是QCoreApplication::exec()执行后信号槽不触发的问题。有些初学者习惯把业务逻辑写在main()里但exec()一跑起来任何不在其事件循环中的代码都无法收到信号因为它们没有跑在事件循环里。解决方法是所有连接、发送数据的逻辑都要在主窗口或协议对象的构造函数里完成初始化靠信号槽驱动而不是靠顺序调用驱动。还有一个和VS Code相关的问题。很多人在VS Code里打开别人的Qt工程发现头文件都找不到这是因为没有配置includePath。VS Code默认不知道Qt安装目录需要在.vscode/c_cpp_properties.json里指定Qt头文件路径{ configurations: [ { name: Qt, includePath: [ ${workspaceFolder}/**, D:/Qt/5.15.2/mingw81_64/include, D:/Qt/5.15.2/mingw81_64/include/QtWidgets, D:/Qt/5.15.2/mingw81_64/include/QtNetwork, D:/Qt/5.15.2/mingw81_64/include/QtCore ], defines: [], compilerPath: D:/Qt/Tools/mingw810_64/bin/g.exe, cStandard: c17, cppStandard: c17, intelliSenseMode: windows-gcc-x64 } ] }5. 项目扩展与实际应用心得v2.1源码除了作为一个Telnet客户端直接使用还可以二次开发成很多有用的东西。我在实际项目里就把它改成了自动化巡检工具定时连接网络设备执行命令抓取输出保存到日志文件。这比在命令行里一条条敲要高效得多。5.1 从客户端到自动化脚本如果你希望Telnet客户端能自动执行一组命令只需要在协议层之上加一个命令队列void TelnetClient::execCommandBatch(const QStringList commands, int intervalMs) { m_commandQueue commands; m_commandTimer.start(intervalMs); } void TelnetClient::onCommandTimerTimeout() { if (m_commandQueue.isEmpty()) { m_commandTimer.stop(); return; } QString cmd m_commandQueue.takeFirst(); sendData(cmd.toUtf8() \r\n); }这里有个经验设备执行命令是需要时间的尤其是一些耗时操作如保存配置、重启服务连续发送命令会导致部分命令丢失。所以每条命令之间的间隔时间要足够长或者用输出匹配等待——发送一条命令等收到期望的输出再发下一条。后者更可靠但实现复杂度更高。v2.1目前的定时器轮流发送方案对大多数巡检场景已经够用。5.2 编码识别再做一层加固在应对老设备时编码问题永远是个痛。v2.1的编码切换是手动的但如果你的工具要交付给不太懂技术的人用可以考虑自动识别编码。常见做法是先按UTF-8解析如果检测到非法字节序列就尝试用GBK重新解析。Qt里QStringDecoder可以辅助判断QString decodeWithFallback(const QByteArray data) { auto utf8Decoder QStringDecoder(QStringDecoder::Utf8); QString result utf8Decoder.decode(data); if (utf8Decoder.hasError()) { auto gbkDecoder QStringDecoder(QStringDecoder::Gb18030); return gbkDecoder.decode(data); } return result; }这个逻辑不复杂但能省掉用户手动切换编码的麻烦。5.3 多协议扩展Telnet只是起点Telnet和SSH在协议层面是孪生兄弟——都是连接网络设备、执行命令、获取输出的通道差别在传输层加密和认证方式。如果你想更进一步可以在v2.1的架构上接入libssh或者Qt的QProcess调用系统ssh命令实现SSH客户端。有了v2.1的UI框架和命令队列机制切换协议只是换掉连接层和传输层的事。实际上我在自己的开发工作流里已经把v2.1做成了万能网络调试器既能连Telnet也能连串口通过QSerialPort还接了一个HTTP API用来测试设备REST接口。这种一个入口连所有设备的工作方式对日常开发调试的效率提升非常明显。如果你也经常跟网络设备、嵌入式Linux开发板打交道建议花点时间把v2.1源码吃透改成适合自己习惯的工具。别小看这个看起来古老的协议它至今仍然是网络设备最通用的调试入口掌握了它你的武器库里就多了一把万能钥匙。本文还有配套的精品资源点击获取 
长河君 · 2026/9/1 16:34:16 · 阅读 1.2k 基于Qt的Telnet客户端实现：协议解析与选项协商实战
简介这是一份面向Qt开发者的Telnet客户端完整源码版本v2.1以LGPL/GPL3开源协议发布。项目基于Qt框架完整实现了Telnet协议的关键环节包括TCP连接管理、命令交互的编码与解码、选项协商、异常处理与会话重连并自带simpleClient示例与跨平台构建脚本适合需要学习Qt网络编程、终端模拟或Telnet协议实现的开发者阅读。资源包共29个文件涵盖4个pro工程文件、qttelnet核心cpp与h源码、pri构建配置以及txt说明文档、qdoc/qch帮助文档、html页面与png图片等压缩包整体仅79KB目录将src、examples、doc、buildlib清晰分区便于按模块查阅。目前已有283人学习/浏览。通过研读源码可以掌握在Qt中搭建终端模拟客户端的完整思路理解QWidget界面与网络通信组件的配合方式结合examples示例还能学习工程组织、模块划分与跨平台构建方法代码侧重协议交互细节适合二次开发或教学演示。1. 项目整体设计与思路拆解做嵌入式开发这些年打交道最多的两个工具就是串口终端和Telnet终端。串口好办工具一堆但Telnet这个场景反而挺尴尬——Windows自带的telnet客户端难用不说对终端仿真、乱码、字体这些细节几乎是零支持用Xshell、SecureCRT这类商业软件吧功能又过于臃肿很多功能根本用不上还得考虑授权问题。所以我干脆自己动手用Qt写了一个Telnet客户端也就是这个v2.1版本的源码项目。1.1 为什么自己写Telnet客户端先说一个很扎心的现状Qt官方并没有专门为Telnet协议封装好的高层类。Qt的QNetworkAccessManager是给HTTP这类应用层协议用的QTcpSocket虽然能干这事但Telnet协议本身的状态机、选项协商、命令字节处理这些都得自己实现。很多人在网上搜Qt telnet拿到的要么是半成品要么就是直接把数据往QTcpSocket里一塞就完事完全没处理Telnet协议里最关键的IACInterpret As Command字节。这样导致的直接后果就是连上设备之后交互乱了套设备发来的WILL ECHO、WILL SUPPRESS GO AHEAD这些协商指令会直接变成乱码显示出来终端行为也完全不对。v2.1这个版本的定位很明确做一个开箱即用的Telnet客户端把协议解析、选项协商、终端显示这三件事都处理好同时保持代码轻量、单文件可移植、直接在Qt工程里拖进去就能编译。1.2 模块划分与选区考量整个项目的模块划分其实很清晰就三层网络层负责TCP连接的建立、断开、数据收发直接封装QTcpSocket协议层解析Telnet数据流中的控制命令处理选项协商向上层暴露干净的读写接口UI层连接配置界面、命令输入、回显显示、日志记录v2.1相比v2.0最大的改动在协议层——把原来散乱的switch-case处理改成了一套基于状态机的解析流程同时补齐了对NAWSNegotiate About Window Size窗口尺寸协商和TTYPETerminal Type终端类型协商这两个选项的支持。这两个选项在实际调试中太常用了不告诉对端终端类型很多网络设备会拒绝给你全功能菜单或者行为表现异常。2. Telnet协议核心原理别被老协议吓住Telnet协议是1969年就定型的远古协议但它并没有过时——今天几乎所有网络设备的管理接口、嵌入式Linux的调试入口、光猫超级密码获取通道底层用的还是这套协议。理解了Telnet协议很多设备交互上的疑难杂症也就迎刃而解了。2.1 IAC命令与状态机基础Telnet协议有个关键设计数据流中的普通数据字节和控制命令字节是混在一起传输的。如果直接把收到的QByteArray当普通文本处理命令字节就会和显示内容混在一起。解决方法是引入一个特殊字节IACInterpret As Command十进制255。当接收方看到这个字节就知道后续的数据不是普通文本而是一条控制命令。在一个简单的Telnet数据流中可能出现这样的原始数据FF FD 18 FF FB 01 68 65 6C 6C 6F 0D 0A其中FF FD 18是一条命令IAC DO 终端类型0x18表示对端要求我们发送终端类型FF FB 01是另一条IAC WILL ECHO表示对端准备开启回显后面的68 65 6C 6C 6F才是真正的文本hello。如果代码不解析直接在文本框里显示那一行字符会变成一堆乱码。v2.1的协议层核心就是一个状态机专门区分当前字节属于命令还是普通数据。状态机逻辑其实很朴素初始状态是Data所有字节都按普通数据输出收到IAC进入IAC状态等待下一个字节如果第二个字节是命令类型如WILL、DO再进入CommandOption状态继续读一个字节获取选项编号如果是SBSubnegotiation子协商进入子协商的接收状态直到遇到IAC SE才结束2.2 选项协商机制解析Telnet协议里最活跃的部分就是选项协商。打个比方你到一家餐厅服务员服务器会先问问你需不需要茶水回显、需不需要靠窗座位窗口尺寸、能不能扫码点餐终端类型。这些询问就是选项协商报文。常见的选项协商命令有四个配合选项编号使用命令字节含义WILL251发送方将要开启某个选项WONT252发送方拒绝开启某个选项DO253发送方要求接收方开启某个选项DONT254发送方要求接收方关闭某个选项常见的选项编号有选项字节说明ECHO1回显SUPPRESS GO AHEAD3抑制Go AheadSTATUS5状态查询TTYPE24终端类型NAWS31窗口尺寸v2.1的协议层会做这样几件事收到WILL ECHO回复DO ECHO表示接受回显开启收到DO TTYPE回复WILL TTYPE然后发送子协商报文附上终端类型字符串收到DO NAWS回复WILL NAWS然后发送当前窗口宽度和高度不处理这些协商的后果是什么大部分设备在收到DONT或没有任何响应后会降级到最保守的交互模式比如不给你回显你敲命令看不见自己打了什么、不给你菜单某些交换机会隐藏高级命令。所以协议层这一块不能偷懒。2.3 子协商Subnegotiation的处理子协商是选项协商的进阶版用于传输比开/关更复杂的信息。格式是IAC SB 选项编号 数据... IAC SE比如TTYPE的子协商全流程是这样的服务器发IAC DO TTYPE请告诉我你的终端类型客户端回IAC WILL TTYPE好的我会发服务器发IAC SB TTYPE 1 IAC SE请发你的终端类型1表示SEND客户端回IAC SB TTYPE 0 xterm IAC SE我的终端类型是xterm0表示IS整个过程中SB和SE是成对出现的中间的数据段不能被普通状态机拦截。所以我在v2.1里专门加了SubNegotiation子状态进入SB后所有字节都往缓冲区里存直到遇到IAC SE才解除状态。这一步不处理好数据流会错乱。3. v2.1核心代码实现与实操要点如果只打算拿源码直接编译你可以跳过协议理论那部分但代码的几个关键模块还是要看懂后面排查问题会省力很多。3.1 连接管理模块封装QTcpSocketv2.1的连接管理依然基于QTcpSocket但做了几个增强超时处理、自动重连、错误分类。核心连接函数长这样bool TelnetClient::connectToHost(const QString host, quint16 port, int timeoutMs) { if (m_socket-state() ! QAbstractSocket::UnconnectedState) { m_socket-abort(); } m_socket-connectToHost(host, port); if (!m_socket-waitForConnected(timeoutMs)) { m_lastError m_socket-errorString(); m_socket-abort(); return false; } m_connected true; m_parser.reset(); emit connected(); return true; }注意waitForConnected是一个阻塞调用如果在UI线程里直接用界面会卡死。v2.1的做法是把连接操作丢到QtConcurrent::run里执行连接完成后再通过信号槽把结果传回主线程。这样既保持了代码简单又避免了界面冻结。另外一个细节是m_parser.reset()。每建立一次新连接协议解析器的状态机必须重置——你不想上一个连接残留在缓冲区里的半截报文污染新连接吧。这一点在实际切换不同设备调试时尤为重要。断开连接的实现也做了优化不是直接暴力disconnectFromHost()而是先尝试通知对端再断开void TelnetClient::disconnectFromHost() { if (!m_connected) return; // 发送Telnet断开命令: IAC IP (Interrupt Process) QByteArray bye; bye.append(static_castchar(255)); // IAC bye.append(static_castchar(244)); // IP m_socket-write(bye); m_socket-flush(); m_socket-disconnectFromHost(); m_connected false; emit disconnected(); }很多设备对突然断开的TCP连接处理得很粗糙导致端口长期处于TIME_WAIT状态重连就报address already in use。主动发一个IAC IP告诉对端我要中断本次进程了可以明显降低这种概率。3.2 协议解析器QByteArray缓冲兼容粘包嵌入式设备调试中最常见的网络问题是粘包和半包。TCP是流式协议不会保证每次readyRead信号读到的一定是完整数据所以协议解析器必须自己维护一个缓冲区。v2.1的做法是这样的void TelnetClient::onReadyRead() { m_buffer.append(m_socket-readAll()); parseBuffer(); } void TelnetClient::parseBuffer() { int i 0; while (i m_buffer.size()) { uchar byte static_castuchar(m_buffer.at(i)); switch (m_state) { case ParserState::Data: if (byte IAC) { m_state ParserState::IAC; } else { appendToDisplay(byte); } i; break; case ParserState::IAC: // 判断下一个字节 switch (byte) { case Command::WILL: case Command::WONT: case Command::DO: case Command::DONT: m_pendingCmd byte; m_state ParserState::Command; break; case Command::SB: m_subBuffer.clear(); m_state ParserState::SubNegotiation; break; case Command::IAC: // 转义数据中出现的255 appendToDisplay(byte); m_state ParserState::Data; break; default: m_state ParserState::Data; break; } i; break; case ParserState::Command: handleOption(m_pendingCmd, byte); m_state ParserState::Data; i; break; case ParserState::SubNegotiation: if (byte IAC) { // 检查下一个字节是不是SE if (i 1 m_buffer.size() m_buffer.at(i 1) Command::SE) { handleSubNegotiation(m_subBuffer); m_state ParserState::Data; i 2; continue; } m_subBuffer.append(byte); } else { m_subBuffer.append(byte); } i; break; } } m_buffer.remove(0, i); }这版解析器最需要注意的地方是IAC IAC转义序列。255这个字节既是命令的引导符也可能作为普通数据出现。协议规定如果数据中真的需要传255这个字节发送方会将其写成IAC IAC两个连续字节。解析时必须把这个情况单独处理否则数据就会被切断、显示异常。3.3 选项协商的自动回包之前讲过协议层要做的关键事情之一是对WILL/DO等请求自动回包。v2.1的handleOption函数是这么实现的void TelnetClient::handleOption(uchar cmd, uchar option) { QByteArray response; switch (cmd) { case Command::WILL: switch (option) { case Option::ECHO: // 接受回显 response.append(static_castchar(IAC)); response.append(static_castchar(Command::DO)); response.append(static_castchar(Option::ECHO)); break; case Option::SUPPRESS_GO_AHEAD: response.append(static_castchar(IAC)); response.append(static_castchar(Command::DO)); response.append(static_castchar(Option::SUPPRESS_GO_AHEAD)); break; case Option::TTYPE: response.append(static_castchar(IAC)); response.append(static_castchar(Command::DO)); response.append(static_castchar(Option::TTYPE)); break; default: // 不支持的选项回复DONT response.append(static_castchar(IAC)); response.append(static_castchar(Command::DONT)); response.append(static_castchar(option)); break; } break; case Command::DO: switch (option) { case Option::TTYPE: response.append(static_castchar(IAC)); response.append(static_castchar(Command::WILL)); response.append(static_castchar(Option::TTYPE)); // 立即发送终端类型 sendTerminalType(); break; case Option::NAWS: response.append(static_castchar(IAC)); response.append(static_castchar(Command::WILL)); response.append(static_castchar(Option::NAWS)); sendWindowSize(); break; default: response.append(static_castchar(IAC)); response.append(static_castchar(Command::WONT)); response.append(static_castchar(option)); break; } break; default: break; } if (!response.isEmpty()) { m_socket-write(response); } }这里有个细节对于不认识的选项一定要回WONT或DONT而不是什么都不发。因为很多网络设备是你默认接受的假设不发回包它就一直等导致后续交互卡住。这就像电话沟通中对方问你问题你不回答他就只能一直追问或者干等。3.4 UI层从QPlainTextEdit到终端渲染v2.1的UI层很简单上面一个QPlainTextEdit做显示区下面一个QLineEdit做输入区加一个连接按钮。但这里埋了一个坑QPlainTextEdit默认不支持终端控制序列比如\x1b[2J清屏、\x1b[0m重置颜色、\x1b[1;31m红色粗体等。设备端会发这些ANSI转义序列直接显示就是一片乱七八糟的字符。我的处理方案是写了一个轻量的TerminalTextEdit类继承QPlainTextEdit重写appendData(const QByteArray)方法在做解析时把常见的控制序列剥掉仅保留可显示的文本。完整的VT100仿真工作量大得惊人但v2.1里做了个折中识别并处理最常用的几个序列——清屏、光标归位、颜色重置、换行、回车、退格。void TerminalTextEdit::appendData(const QByteArray data) { int i 0; while (i data.size()) { uchar ch static_castuchar(data.at(i)); if (ch 0x1B) { // ESC // 查找下一个字母字符跳过完整的控制序列 int j i 1; while (j data.size() !(data.at(j) 0x40 data.at(j) 0x7E)) { j; } parseEscapeSequence(data.mid(i, j - i 1)); i j 1; } else if (ch \r) { // 忽略裸CR除非后面跟LF i; } else { insertPlainText(QString::fromUtf8(data.mid(i, 1))); i; } } ensureCursorVisible(); }注意这里用QString::fromUtf8处理数据。如果设备返回的是GBK编码的中文显示会变成问号。很多光猫和旧交换机默认输出GBK编码所以v2.1的编码处理也要做配置在连接窗口里加一个编码下拉框支持UTF-8、GBK、GB18030。实际处理时用QTextCodec转换一行代码的事但能救回无数乱码页面。3.5 发送数据的处理输入框的发送逻辑也做了处理不只是简单地write(text.toUtf8())。关键要处理回车换行符——Telnet协议规定回车是\r\nCRLF而不是普通聊天工具的\n。void MainWindow::onCommandSubmitted(const QString text) { if (!m_telnet-isConnected()) { appendLocalMessage(tr(尚未连接到服务器)); return; } QByteArray data text.toUtf8(); data.replace(\n, \r\n); m_telnet-sendData(data); m_inputEdit-clear(); }还有个小细节回显。连接开启回显后你敲的命令会在本地显示一次设备端又会回显一次导致命令看起来出现两遍。实际处理是在显示区过滤掉自己发的数据只保留设备端的回显或者干脆在本地禁止回显、只显示设备端返回的内容。v2.1默认是后者这样更加贴近真正的终端体验。4. 常见问题与排查技巧实录这部分是实际调试中踩坑最集中的地方我把遇到的高频问题整理成一个速查表再逐个细说。问题现象可能原因解决方案连接后立即断开提示errno 104对端主动重置连接协议协商失败先检查端口和协议类型抓包确认协商包是否正确ping通但telnet端口不通设备禁用了telnet服务防火墙拦截确认端口是否为23用nmap -p 23扫描检查服务配置中文显示乱码编码不匹配切换GBK/UTF-8编码命令敲了没反应没发CRLF确认发数据时是否替换为\r\n界面卡死阻塞调用waitForConnected改用异步连接或丢到线程池设备内容显示重叠不换行CR/LF处理不当把\r\n统一交给渲染层处理4.1 errno 104Connection reset by peer这是最常见的报错表示对端把你的TCP连接主动重置了。我遇到过很多次排查路径基本固定第一确认协议类型。很多设备同时开了telnet和SSH你连的是23端口但设备那边根本没起telnet服务壳都不存在连上就RST。第二检查是否被防火墙拦截。第三抓包看协商过程。如果设备端发送了WILL ECHO、你的客户端回了DO ECHO但设备后续仍没有响应很可能是协商包格式不对比如字段顺序错了、IAC重复了、或者直接用文本工具发送了不可见字节。在v2.1里我专门加了一个协议日志窗口会把原始二进制数据按十六进制打出来排查这类问题效率极高。4.2 快速定位协议错乱十六进制日志聊到排查要特别建议你在自己的工具里加上十六进制日志。只靠肉眼观察文本输出很多协议问题根本看不见。举个例子Telnet传输过程中收到的数据经常是这样FF FD 1F FF FB 03 FF FD 18 FF FB 01 ......这些字节在文本显示区基本是不可见的或者会变成奇怪的符号但你根本看不出是什么协议指令。十六进制日志把每条收到的原始报文都打出来配合协议文档对照协议协商成功与否一目了然。v2.1里实现这个功能很简单就是在onReadyRead和sendData两个函数的入口加一行emit rawDataReceived(m_buffer.mid(0, n)); // n为本次读取的字节数在UI上接一个QPlainTextEdit把字节转成十六进制输出同时保留ASCII版本QString hex data.toHex( ).toUpper(); QString ascii; for (char c : data) { ascii.append(QChar::isPrint(static_castuchar(c)) ? QChar(c) : QChar(.)); } m_hexLog-appendPlainText(hex ascii);这个工具在跟设备厂商联调协议问题时简直是救命的。你可以直接把日志丢给对方双方对着报文说话。4.3 ping通但telnet一直失败另一个高频问题是设备能ping通但telnet 23端口就是连不上。这个问题的排查路径要宽一些设备是否开启了telnet服务很多设备默认只开SSHtelnet服务要在配置页面手动开启或者需要通过串口/特定命令激活。是否有ACL限制不少网络设备支持管理ACL只允许指定源IP访问管理端口。你的机器IP可能不在允许列表里。是否存在中间防火墙拦截这个问题在办公网环境很常见。端口冲突设备上23端口被其他服务占用或者设备本身telnet进程挂了。针对这些问题v2.1额外加了一个小功能连接前的端口探测。说白了就是用QTcpSocket先试探性连接一下端口如果连接成功则立刻断开然后再走完整的Telnet握手流程。这个功能用于区分端口不通和协议协商失败可以在界面上直接提示用户。4.4 Qt环境相关的几个坑除了协议层的问题开发环境本身也有几个容易踩的坑尤其新手容易在这里卡很久。一个是qxcbconnection: failed to initialize xrandr这类X11错误。在无图形界面的服务器上运行Qt程序或者通过SSH远程执行带GUI的Qt程序时经常碰到。解决办法很朴素程序本身不需要GUI就编译成命令行版本或者用QT_QPA_PLATFORMoffscreen环境变量强制使用离屏渲染。不过如果你要是做一个纯命令行交互工具那压根别带Qt的GUI模块直接用QCoreApplication就行。另一个是QCoreApplication::exec()执行后信号槽不触发的问题。有些初学者习惯把业务逻辑写在main()里但exec()一跑起来任何不在其事件循环中的代码都无法收到信号因为它们没有跑在事件循环里。解决方法是所有连接、发送数据的逻辑都要在主窗口或协议对象的构造函数里完成初始化靠信号槽驱动而不是靠顺序调用驱动。还有一个和VS Code相关的问题。很多人在VS Code里打开别人的Qt工程发现头文件都找不到这是因为没有配置includePath。VS Code默认不知道Qt安装目录需要在.vscode/c_cpp_properties.json里指定Qt头文件路径{ configurations: [ { name: Qt, includePath: [ ${workspaceFolder}/**, D:/Qt/5.15.2/mingw81_64/include, D:/Qt/5.15.2/mingw81_64/include/QtWidgets, D:/Qt/5.15.2/mingw81_64/include/QtNetwork, D:/Qt/5.15.2/mingw81_64/include/QtCore ], defines: [], compilerPath: D:/Qt/Tools/mingw810_64/bin/g.exe, cStandard: c17, cppStandard: c17, intelliSenseMode: windows-gcc-x64 } ] }5. 项目扩展与实际应用心得v2.1源码除了作为一个Telnet客户端直接使用还可以二次开发成很多有用的东西。我在实际项目里就把它改成了自动化巡检工具定时连接网络设备执行命令抓取输出保存到日志文件。这比在命令行里一条条敲要高效得多。5.1 从客户端到自动化脚本如果你希望Telnet客户端能自动执行一组命令只需要在协议层之上加一个命令队列void TelnetClient::execCommandBatch(const QStringList commands, int intervalMs) { m_commandQueue commands; m_commandTimer.start(intervalMs); } void TelnetClient::onCommandTimerTimeout() { if (m_commandQueue.isEmpty()) { m_commandTimer.stop(); return; } QString cmd m_commandQueue.takeFirst(); sendData(cmd.toUtf8() \r\n); }这里有个经验设备执行命令是需要时间的尤其是一些耗时操作如保存配置、重启服务连续发送命令会导致部分命令丢失。所以每条命令之间的间隔时间要足够长或者用输出匹配等待——发送一条命令等收到期望的输出再发下一条。后者更可靠但实现复杂度更高。v2.1目前的定时器轮流发送方案对大多数巡检场景已经够用。5.2 编码识别再做一层加固在应对老设备时编码问题永远是个痛。v2.1的编码切换是手动的但如果你的工具要交付给不太懂技术的人用可以考虑自动识别编码。常见做法是先按UTF-8解析如果检测到非法字节序列就尝试用GBK重新解析。Qt里QStringDecoder可以辅助判断QString decodeWithFallback(const QByteArray data) { auto utf8Decoder QStringDecoder(QStringDecoder::Utf8); QString result utf8Decoder.decode(data); if (utf8Decoder.hasError()) { auto gbkDecoder QStringDecoder(QStringDecoder::Gb18030); return gbkDecoder.decode(data); } return result; }这个逻辑不复杂但能省掉用户手动切换编码的麻烦。5.3 多协议扩展Telnet只是起点Telnet和SSH在协议层面是孪生兄弟——都是连接网络设备、执行命令、获取输出的通道差别在传输层加密和认证方式。如果你想更进一步可以在v2.1的架构上接入libssh或者Qt的QProcess调用系统ssh命令实现SSH客户端。有了v2.1的UI框架和命令队列机制切换协议只是换掉连接层和传输层的事。实际上我在自己的开发工作流里已经把v2.1做成了万能网络调试器既能连Telnet也能连串口通过QSerialPort还接了一个HTTP API用来测试设备REST接口。这种一个入口连所有设备的工作方式对日常开发调试的效率提升非常明显。如果你也经常跟网络设备、嵌入式Linux开发板打交道建议花点时间把v2.1源码吃透改成适合自己习惯的工具。别小看这个看起来古老的协议它至今仍然是网络设备最通用的调试入口掌握了它你的武器库里就多了一把万能钥匙。本文还有配套的精品资源点击获取