05-排错手册与已知限制从连不上到点击偏移的定位思路前面四篇把怎么做出来讲完了。最后这篇讲两件新手最容易用上的事真出问题了怎么定位以及这个工具坦率承认自己有哪些做不到。一个负责任的项目不该只晒能力也要把边界写清楚——因为诚实标注限制比吹得无所不能更可信。一、排错思路从现象到对策下面把常见故障改写成现象 → 排查思路 → 对策的叙事方便你对着症状一步步来。所有涉及公司电脑的操作都请记住先确认公司 IT 与安全政策且只在本人拥有或已获授权的设备上操作。动手查之前先建立一个三层的定位框架能让你少绕很多弯第一层网络通不通。直连能不能出网代理兜不兜得住443 还是 8443这一层没过后面全白搭所以 Phase 0a 侦察要最先做见本系列第 3 篇。第二层身份对不对。两端room同不同relay_token一不一致证书指纹钉扎有没有冲突配错了中继直接拒绝配对。第三层能力边界到哪。是不是只读模式没开注入机器锁屏了用户态够不着多显示器分辨率全同无法区分allow_input开了但目标窗口是管理员权限这一层过了才轮到具体功能是否正常。绝大多数故障落在第一层或第二层——也就是根本没连上或连上了但认不出对方。按网络 → 身份 → 边界的顺序剥比东一榔头西一棒槌快得多。下面 17 条现象基本都能归到这三层里的某一层。1. 所有端口都连不上现象被控端或控制端日志里报所有端口都连不上。排查大概率是公司防火墙拦了出网。但别急着下走不通的结论——先用侦察工具实测它会同时测直连和经代理两条路。对策如果直连不通、但代理可用就在两端的配置里显式指定proxy例如socks5://127.0.0.1:10808。默认proxy auto理论上会自动兜但显式写更稳。2. 直连被拦但公司要求经代理出网现象直连超时日志提示需要走代理。排查很多公司网络不经代理就出不去这是正常现象不是工具坏了。对策保持proxy auto它会先直连、不通再自动尝试系统探测到的代理环境变量 / IE 注册表 / WinHTTP 三处。想显式指定就填proxy http://127.0.0.1:7890或socks5://...。3. 代理地址是 PAC 脚本现象系统配的是自动配置脚本PAC工具连不上。排查本项目不解析 PAC 脚本。PAC 里藏着的才是真实代理地址。对策从 PAC 里找出实际代理地址手动填到proxy。侦察报告里会提示检测到了 PAC照着去查就行。4. 走 SOCKS 时代理解析主机名失败现象配了 SOCKS 代理却连不上中继。排查底层代理库会在本地解析主机名。如果中继地址本机解析不了SOCKS 就废了。对策中继地址用IP最省事。本项目默认就是 IP所以实践上不受影响但文档里写明了这个坑。5. 一直等待对端连接现象一端连上了却一直停在等待状态。排查另一端根本没连上来或room/relay_token不一致——中继只认同房间 同令牌的两条连接配对。对策核对三端的room和relay_token是否完全一致。6. 令牌校验失败现象日志出现令牌校验失败。排查三端的relay_token对不上中继会明确打印拒绝。对策核对relay_token用常量时间比较防止时序侧信道所以填错就是填错没有模糊空间。7. 证书指纹不匹配现象报证书指纹不匹配。排查公司网络做了 TLS 中间人解密把证书换成了公司的和你两端钉扎的指纹对不上。对策把两端的pinned_fingerprint清空即可。仍安全——我们有应用层端到端加密中间人解出来的也只是密文。8. Viewer 里画面不动现象连上了但画面是冻的。排查先看被控端有没有状态日志。两种可能一是对端是只读模式你没开注入但画面本来就在传二是画面真的没变化——静止时不发包是设计如此不是 bug。对策动一下被控端的鼠标或敲个字看画面是否更新确认不是因为静止所以不发包误判。9. 点击有偏移现象控制端点击的位置和被控端实际位置对不上。排查先跑列出显示器确认编号。多显示器偏移现在是自动校正的唯一无法区分的情况是多块显示器分辨率完全相同。对策分辨率全同时工具会在自检和启动日志里明确警告并拒绝猜测注入位置错了比不注入更糟。建议把采集目标留空采主屏。10. SendInput 失败在涨现象注入日志里SendInput 失败计数一直增加。排查目标窗口以管理员权限运行而你的被控端是普通用户态权限不够注入。对策需要以管理员身份运行被控端。注意这会带来需要管理员权限的代价权衡后再决定。11. dxcam 拒绝访问现象日志出现dxcam 初始化失败拒绝访问。排查该显示器已被别的程序占用桌面复制器Windows 限制每个显示器同时只能有一个。常见占用者录屏/截图工具、OBS、其他远控、Xbox Game Bar会话锁定或显示器关闭也会触发。对策不影响使用——会自动回落到 mss/GDI只是采集慢约 7 倍33 ms vs 4.65 ms。关掉占用程序后重启被控端即可恢复。12. 打包后采集报没有 cv2现象源码正常打包后报No module named cv2。排查构建时漏了 dxcam 的动态编译扩展见本系列第 1 篇dxcam 静默回落到 cv2 后端。对策确认构建参数里有--collect-all dxcam并养成打包后跑--selftest的习惯。13. 剪贴板没反应现象两边剪贴板不同步。排查看自检的剪贴板项。组件缺失时该功能失效但其他功能不受影响。Windows 上剪贴板被别的程序占用时会短暂读不到属正常。对策确认组件齐全排除别的程序短暂占用必要时关掉剪贴板同步。14. 配置报 BOM 错误现象启动即报Invalid statement (at line 1, column 1)。排查配置文件带了 UTF-8 BOM标准 TOML 解析器会卡在第一行。对策项目已用utf-8-sig兼容读取。若仍报错检查文件是否被别的编辑器改坏。顺带提醒写 PowerShell 脚本时也要带 UTF-8 BOM否则中文会乱码并吃掉引号见第 1 篇。15. 重连之后画面不更新现象网络抖了一下两端自动重连成功但画面卡住不动。排查重连后第一帧往往要靠关键帧恢复若关键帧在传输中被丢会等到下一个关键帧约 2 秒才把整屏纠正回来。期间画面看起来冻住其实在等兜底帧。对策动一下被控端的鼠标或敲个字触发变化块立即更新若持续不动超过几秒看日志是否停在等待关键帧。这通常是预期内的短暂现象2 秒内自愈。16. 日志到底写哪了现象出问题了想看日志却不知道去哪找。排查控制端打包成纯 GUI 后sys.stdout是None日志不会进黑框而是写在 exe 同目录的日志文件里被控端同理。只有用--console形态带黑框跑时才会同时往黑框打一份。对策直接打开 exe 同目录的日志文件看首次排查强烈建议用--console形态手动跑黑框里实时滚动的日志比事后翻文件快得多。17. 自启后在家连不上现象设置了启动文件夹自启但人在家连不上公司电脑。排查启动文件夹只在该用户登录后触发可能公司机没登录这个账户、exe 目录被挪而快捷方式失效、或config.toml缺失导致程序启动即退出。对策详见本系列第 2 篇自启没生效的四步自查。记住顺序——先用--console手动跑通确认链路本身没问题再切到自启否则出问题时你连日志都看不到。二、已知限制诚实清单下面每一条都是项目自己写进文档的已知限制不美化、不回避全走中继未实现 P2P 直连。延迟和带宽取决于你自己的 VPS比直连多一跳。设计上留了位置但没做。以用户态运行不控制登录界面 / UAC 提权窗口。这是刻意的取舍这样就不需要管理员权限。代价是被控机锁屏后无法远程解锁。若你需要可自行改为以服务方式运行。多块显示器分辨率完全相同时无法区分。此时被控端会在自检和启动日志里明确警告并拒绝猜测注入位置错了比不注入更糟。剪贴板只支持纯文本不含图片 / 文件。未做文件传输。传输层没有自动证书钉扎。安全性由应用层端到端加密保证TLS 只负责看起来像正常 HTTPS。如需钉扎可填tls.pinned_fingerprint但公司若做 TLS 中间人解密需留空。链路质量取决于你自己的网络。实测遇到过偶发丢包导致的 0.5~2 秒延迟尖峰TCP 重传超时设计上不会累积延迟但会偶尔卡一下。未做安全审计。这是一个个人自用工具不是产品。部分运行参数max_fps/target_width目前暂未支持运行时热调只支持运行时调quality。这些限制不是缺陷清单而是边界声明它告诉你这个工具能干什么、不能干什么让你在用它之前就能判断它适不适合我的场景而不是用了一半才发现不行。三、免责声明要点最后把使用须知摆清楚——这部分项目源码和文档都写得很重本项目仅供在本人拥有、或已获得明确授权的设备上使用在公司设备上部署前请先确认是否符合公司的 IT 与安全政策。未经授权在公司设备上安装远控类工具可能违反规定这是使用者的责任项目未经安全审计按现状提供不附带任何担保请务必设置足够强的password与relay_token并妥善保管配置文件。中继靠relay_token认人内容靠password派生的密钥保护这两个串弱了整条链路就弱了。这里要特别区分一个容易混的点MIT 许可证授权的是代码的使用权不等于替你的使用场景背书。你能自由使用、修改、分发代码但把代码用在哪台设备上、有没有授权是另一回事二者不冲突。小结排错的核心是对照现象、顺着链路一层层剥先确认网络直连/代理/端口再确认身份令牌/房间/指纹最后确认能力边界只读/锁屏/分辨率相同/注入权限。而已知限制那张清单是这个项目最值得信任的地方——一个敢把做不到的事一条条列出来的工具它说能做到的那部分才真的可信。