rdp-cli
排查 RDP 连接、黑屏与输入被拒绝问题
适用版本与平台: 0.1.2 · Windows / macOS / Linux · RDP
先看实际响应
按网络、加密、认证、画面和输入的顺序排查 RDP 连接问题。根据返回的错误码选择处理步骤,避免反复修改密码或重新连接。
rdp-cli --version
rdp-cli list
rdp-cli status --session SESSION
以自己返回的会话 ID 替换 SESSION。失败时读取 error.code、error.message 和 error.retryable;状态成功时核对 data.connection_state、data.control_state、存在时的 data.last_error 及 data.capabilities。可重试标记不代表可以重放输入。
按连接阶段检查
| 错误 | 检查与处理 |
|---|---|
CONNECT_TIMEOUT / RDP_CONNECT_FAILED |
核对主机、实际端口(通常为3389)、局域网/VPN路由和RDP服务是否启动。请管理员确认监听与允许访问的防火墙规则。端口可达不等于RDP登录成功;修正原因后再尝试一次。 |
RDP_TLS_HANDSHAKE_FAILED |
检查服务器TLS配置。默认 modern 要求TLS 1.2;仅对可信网络中已确认的旧服务器按需使用 --tls-profile legacy,它允许旧加密配置。不要全局套用或为通过测试而关闭服务端安全设置。 |
CERTIFICATE_UNTRUSTED |
使用 --cert-policy strict 时核对主机名与证书链,或先与管理员核验返回的SHA-256指纹,再添加精确的信任记录。当前默认值是 ignore,它不验证服务端身份;不要为了消除strict报错直接切换为ignore。 |
AUTH_FAILED |
核对用户名、本地/域账户选择、--domain 和远程登录权限。按快速上手使用密码提示或已有凭据引用,不要循环猜试密码:TLS失败、主机不可达都不能证明密码错误。 |
已连接却没有可用画面
执行下面的只读查询,打开 data.path 指向的PNG。connected 表示协议已激活并收到连贯画面;画面仍可能是登录页、欢迎页或黑屏,不代表桌面已经可用。
rdp-cli screenshot --session SESSION
出现 FRAME_UNAVAILABLE 时查看状态及 error.retryable,等重连或显示切换稳定后再截图。持续黑屏时检查服务器、本机睡眠状态和 VPN 连接。输入凭据前先确认当前画面。
处理输入与权限错误
OBSERVATION_REQUIRED:重新截图并读取画面,下一次输入使用其data.observation。重连、接管、显示变化后都要更新。SESSION_PAUSED、CONTROL_HELD_BY_HUMAN或CONTROL_NOT_OWNED:停止输入并尊重当前控制者。获授权交还后才恢复,并重新截图;不要另开查看器绕过暂停。PERMISSION_DENIED/CAPABILITY_UNAVAILABLE:查看相关能力和访问授权。打开查看器不能让服务器支持缺失的功能。UNICODE_INPUT_UNAVAILABLE需要选择受支持的输入方式,而非盲目重试。
恢复结果未知的操作
对可能需要恢复的输入,操作前为每个不同动作指定并保存唯一 --request-id,示例请求 ID 应替换为你自己的值。若收到错误 JSON,可取顶层 request_id;若响应完全丢失且未保存原 ID,不能事后新建 ID 查询旧操作或盲目重发。
操作过程中出现 REQUEST_TIMEOUT 或 SERVICE_UNAVAILABLE 时保留原始请求ID。先用 list 检查本机服务,再查询原操作后决定是否重试;响应丢失时输入可能已发送。
rdp-cli operations status --session SESSION --request-id REQUEST_ID
rdp-cli status --session SESSION
rdp-cli screenshot --session SESSION
将 REQUEST_ID 替换为原值,而不是状态查询自身的ID。核对 data.state、保留的 data.result 和新截图。OPERATION_NOT_FOUND 可能表示记录过期或服务已更换,不能证明原操作未执行。修复连接原因后,对未关闭会话显式执行 reconnect 仍会保持暂停。SESSION_CLOSED 需要重新建立获授权连接,不要反复重连试图复活它。
rdp-cli 的增强命令
先运行 rdp-cli --version。以下增强命令要求响应中的 agent_execution.contract_version 为 1;旧版本仍可使用上文的单步操作。
将大写占位符换成实际返回值。Windows PowerShell 中在程序目录使用 .\rdp-cli.exe;macOS、Linux 使用已安装的命令或可执行文件的实际路径。
接入 Agent,也把连接问题查清楚
同一个文件提供内置 MCP 和命令行。用命名连接档案保存参数与凭据引用,用 doctor 分层检查连接能力。
这里的 doctor 示例读取已有证据,不发起主动探测。unknown、not-run 都不表示检查通过。连接档案使用凭据引用,示例中不写密码。
rdp-cli profiles list
rdp-cli doctor --session SESSION
带着证据继续排查
仍无法解决时提供客户端版本、服务器版本、协议、时间、错误码及脱敏状态/截图,移除密码、访问令牌与敏感画面。