1. 先搞清楚 dsh-pocket 到底卡在哪一层

装完 dsh-pocket 连不通，这件事我遇到过太多次了。不管是自己装还是帮同事看，十有八九不是软件本身坏了，而是链路上某一环没打通。dsh-pocket 这类工具的本质，是在本地起一个轻量客户端，通过 CLI 跟远端服务建立一条受认证保护的通道，中间要经过认证、端口绑定、隧道协商这几道关卡。任何一道没过，表现都是“连不通”，但根因完全不同。

所以排查的第一步不是急着改配置，而是先定位故障发生在哪一层。我的习惯是把整条链路拆成四段：CLI 是否正常加载、认证是否通过、端口是否被占用、隧道是否协商成功。这四段对应了热搜里反复出现的几个词——CLI、认证、端口占用、隧道错误，基本覆盖了 90% 的连不通场景。

这篇文章适合两类人看：一类是刚装完 dsh-pocket、对着黑屏终端一脸懵的新手；另一类是装过几次、但每次出问题都要重新翻文档的老手。我会把每一层的排查逻辑、具体命令、判断依据都写清楚，你照着做基本能自己定位问题。需要说明的是，dsh-pocket 的具体实现细节官方文档未必写全，下面涉及的操作步骤和参数，一部分来自我自己的实操记录，一部分是基于这类 CLI 工具的通用实践做的合理补充，你对照自己的版本微调即可。

先给一个整体判断思路，避免你上来就乱试：

这张表你先存着，后面每一节我都会展开讲怎么用。

2. CLI 层排查：命令能不能跑起来是第一步

2.1 确认 dsh-pocket 真的装上了

很多人以为装完了，其实只是下载了安装包，或者装到了非标准路径。先跑一条最基础的命令确认二进制存在：

which dsh-pocket dsh-pocket --version

如果which返回空，说明 PATH 里没有这个可执行文件。这时候别急着重装，先找找它到底装哪了。常见的几个位置：

ls -l /usr/local/bin/dsh-pocket ls -l ~/.local/bin/dsh-pocket ls -l ~/bin/dsh-pocket

找到之后，要么把它软链到 PATH 目录，要么把所在目录加进 PATH。我一般倾向于软链，干净：

ln -s /实际路径/dsh-pocket /usr/local/bin/dsh-pocket

注意：软链之后要重新开一个终端窗口，或者source一下配置文件，否则当前 shell 的 PATH 缓存不会更新。

2.2 版本不匹配是隐形杀手

--version能跑出来，但版本号跟你预期的对不上，这种情况特别容易被忽略。dsh-pocket 的 CLI 和服务端之间通常有版本协商，客户端太旧或者太新，都可能在握手阶段被拒，表现就是“连不通”但没有任何明确报错。

我踩过一次坑：本地 CLI 是 0.9.x，服务端已经升到 1.2.x，连的时候一直卡在握手，日志里只有一行含糊的protocol mismatch。后来把 CLI 升到同大版本就好了。所以养成习惯，装完先对一下版本：

dsh-pocket --version # 对比服务端要求的版本区间

如果版本差得远，直接重装对应版本，别想着凑合。

2.3 环境变量和配置文件的位置

dsh-pocket 一般会读一个配置文件，位置通常在~/.config/dsh-pocket/config或者~/.dsh-pocket/下。CLI 找不到配置时，有的版本会静默用默认值，有的会直接报错退出。先确认配置文件在不在：

ls -la ~/.config/dsh-pocket/ ls -la ~/.dsh-pocket/

如果目录不存在，可能是安装时没初始化。跑一次初始化命令（具体命令看你的版本，常见的是dsh-pocket init或dsh-pocket setup），让它生成默认配置，再往里填参数。

3. 认证层排查：凭证对不对、有没有过期

3.1 认证失败的几种典型表现

认证这一层是热搜里出现频率最高的，ssh认证失败、portal认证、无线认证这些词都指向同一个核心问题：凭证没通过校验。dsh-pocket 的认证方式可能是 token、密钥对或者账号密码，具体看你的部署方式。不管哪种，排查逻辑是一样的。

先看报错信息。认证失败通常会有比较明确的提示，比如：

• authentication failed: invalid token
• auth error: credential expired
• permission denied (publickey)

这几种指向不同原因。invalid token是凭证本身不对，credential expired是过期了，permission denied多半是密钥没配对或者权限设置有问题。

3.2 凭证有效期和时钟同步

token 类凭证一般有有效期。如果你的机器时间跟服务端差太多，会出现“刚生成的 token 就提示过期”的诡异现象。先对一下时间：

date # 跟服务端时间对比，偏差超过几分钟就要校准

Linux 下校准时间：

sudo ntpdate pool.ntp.org # 或者用 chrony sudo chronyc makestep

提示：时间偏差导致的认证失败特别隐蔽，因为报错信息往往只说“过期”，不会告诉你是因为时钟不同步。我建议把这条列为认证排查的固定动作。

3.3 密钥文件权限问题

如果用密钥对认证，权限设置不对会直接被拒。SSH 体系对私钥权限要求很严，太开放会报permission denied。检查一下：

ls -l ~/.ssh/id_rsa # 应该是 -rw------- (600) chmod 600 ~/.ssh/id_rsa chmod 700 ~/.ssh

dsh-pocket 如果用自己的密钥文件，同样要检查对应路径的权限。这一步很多人会漏，尤其是从别处拷贝过来的密钥，权限往往是 644，直接导致认证失败。

3.4 认证配置文件里的坑

配置文件里跟认证相关的字段，常见的有token、auth_method、key_path、username这几项。逐个核对：

• auth_method要跟你实际用的方式一致，写key却配了密码，肯定过不了
• key_path要写绝对路径，相对路径在不同工作目录下会失效
• username大小写敏感，别写错

我见过一次，配置文件里username多了一个空格，排查了半小时才发现。所以核对的时候，建议用cat -A看隐藏字符：

cat -A ~/.config/dsh-pocket/config | grep username

4. 端口层排查：谁占了我的端口

4.1 端口占用的判断方法

address already in use这个报错太经典了。dsh-pocket 启动时要绑定一个本地端口，如果这个端口被别的进程占了，就会起不来。先确认它想用哪个端口，一般在配置文件里写着，比如local_port = 1080之类。

然后查这个端口有没有被占：

# Linux lsof -i :1080 # 或者 ss -tlnp | grep 1080 # macOS lsof -i :1080 # Windows netstat -ano | findstr 1080

有输出就说明被占了，看是哪个进程。如果是之前没退干净的 dsh-pocket 残留进程，直接杀掉：

kill -9 <PID>

如果是别的程序占着，要么换端口，要么停掉那个程序。

4.2 换端口的正确姿势

换端口不是随便改个数字就行。要避开几个雷区：

• 别用 1-1023 的知名端口，需要 root 权限，而且容易冲突
• 别用系统保留端口，比如 5000 在某些系统上被 AirPlay 占用
• 选一个 1024-65535 之间、当前没被占用的端口

改完配置后重启 dsh-pocket，再确认端口绑上了：

ss -tlnp | grep <新端口>

4.3 端口冲突的预防

与其每次出问题再排查，不如一开始就规划好。我的做法是给 dsh-pocket 固定分配一个不常用的端口段，比如 20000-20100 之间，然后在配置里写死。这样既避免了跟常见服务冲突，也方便记忆和管理。

另外，如果 dsh-pocket 支持端口自动选择（有些版本会），可以开启这个功能，让它自己找空闲端口。但要注意，自动选择的端口每次可能不一样，如果你有别的程序依赖固定端口，还是手动指定更稳。

5. 隧道层排查：握手为什么失败

5.1 隧道错误的常见原因

隧道层是最后一关，也是最复杂的一关。tunnel error、handshake failed、connection reset这些报错都出在这一层。常见原因有这么几类：

• 网络策略拦截了隧道协议
• 协议版本不匹配
• 中间设备对长连接做了超时处理
• 服务端隧道服务没起来

排查顺序建议从简到繁。先确认服务端隧道服务在跑，再确认网络能通，最后看协议。

5.2 网络连通性测试

先做最基础的连通性测试，确认能到服务端：

ping <服务端地址> telnet <服务端地址> <端口> # 或者 nc -zv <服务端地址> <端口>

telnet或nc能连上，说明网络层没问题，问题在隧道协议本身。连不上，那就是网络策略或者服务端没监听。

注意：有些环境禁 ping，ping 不通不代表网络不通，一定要用 telnet/nc 测端口。

5.3 协议版本和加密套件

隧道握手失败，很多时候是协议版本对不上。dsh-pocket 的隧道协议可能有多个版本，客户端和服务端要协商一致。如果客户端配置里写死了某个版本，而服务端只支持另一个，就会握手失败。

检查配置文件里的协议相关字段，比如protocol_version、cipher之类。不确定的话，先注释掉这些字段，让它用默认值自动协商，往往能解决。

5.4 长连接被中断的处理

有些网络环境会对长时间空闲的连接做清理，导致隧道建起来一会儿就断。表现是“能连上，但过几分钟就掉”。这种情况可以在配置里开启心跳保活：

keepalive = true keepalive_interval = 30

具体字段名看你的版本，逻辑就是定期发个包，让连接保持活跃。间隔别设太短，30 秒到 60 秒比较合适，太频繁反而增加负担。

6. 常见问题速查与避坑经验

6.1 问题速查表

把上面几层的典型问题整理成一张表，出问题时对着查：

6.2 我踩过的几个坑

坑一：配置文件改了没生效。dsh-pocket 有的版本会缓存配置，改完文件要重启进程才读新配置。我一开始改完直接测，怎么都不对，重启一下就好了。所以改配置后养成重启的习惯。

坑二：日志级别太低看不到关键信息。默认日志可能只输出 ERROR，很多握手细节看不到。排查阶段把日志级别调到 DEBUG：

dsh-pocket --log-level debug # 或者配置文件里 log_level = debug

调完能看到完整的握手过程，哪一步失败一目了然。

坑三：多个版本共存导致命令混乱。系统里装了多个 dsh-pocket，which找到的是旧版本。用type -a dsh-pocket看所有同名命令，确认当前用的是哪个。

6.3 排查的通用心法

最后分享一个我总结的排查心法：从下往上、逐层验证、一次只改一个变量。

从下往上，就是先确认最底层的 CLI 能跑，再往上查认证、端口、隧道。逐层验证，是每一层都要有明确的“通过”证据，不能靠猜。一次只改一个变量，是改配置时别同时改好几个地方，否则出了问题不知道是哪个改动导致的。

这套方法不光适用于 dsh-pocket，任何 CLI 工具的连不通问题都能套用。装完连不通别慌，按这四层走一遍，大部分问题都能自己解决。真遇到搞不定的，把 DEBUG 日志抓下来，对着日志里的时间线看，基本能定位到具体哪一步卡住了。