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 许可证授权的是代码的使用权，不等于替你的使用场景背书。你能自由使用、修改、分发代码，但"把代码用在哪台设备上、有没有授权"是另一回事，二者不冲突。
小结
排错的核心是"对照现象、顺着链路一层层剥"：先确认网络（直连/代理/端口），再确认身份（令牌/房间/指纹），最后确认能力边界（只读/锁屏/分辨率相同/注入权限）。而"已知限制"那张清单，是这个项目最值得信任的地方——一个敢把做不到的事一条条列出来的工具，它说"能做到"的那部分，才真的可信。
