企业官网建设流程全解析

1. 先搞清楚 dsh-codex-connect 到底在干什么

dsh-codex-connect 这个插件，名字拆开看就三块：dsh 是宿主环境，codex 是它要对接的代码智能服务，connect 是它的核心动作——把本地开发环境和远端代码模型之间的链路打通。很多人第一次装完，看到插件面板亮绿灯就以为万事大吉，结果一敲命令就报错，或者干脆卡在“connecting”转圈。这类问题的根源，九成不在插件本身，而在链路中间某一环断了，而插件只告诉你“失败了”，不告诉你“哪一段失败了”。

我前后在三个不同网络环境、两台 Windows 和一台 Linux 机器上反复装过这个插件，踩过的坑基本能覆盖新手会遇到的全部类型。这篇就把最高频的五个现象拎出来，每个现象配一套可以直接复制粘贴的排查命令，再讲清楚每条命令背后的判断逻辑。你不需要理解插件源码，只需要按顺序敲命令、看输出、对号入座。

适合谁看：刚装完 dsh-codex-connect 发现用不了的；用了一段时间突然连不上的；换了网络环境或换了机器之后插件罢工的。如果你还没装，建议先装完再回来对照排查，因为下面很多命令的输出需要插件实际运行时的状态才有意义。

提示：全文命令以 Windows 的 cmd 和 PowerShell 为主，Linux/macOS 的对应命令我会在括号里标注。所有命令都不涉及任何敏感操作，纯粹是本地网络和进程排查。

2. 排查前的通用准备：先把“变量”固定住

2.1 确认插件版本与宿主版本匹配

在动手排查之前，有一件事必须先做：确认你装的 dsh-codex-connect 版本和 dsh 宿主版本是兼容的。我遇到过两次“连不上”，最后发现是插件版本比宿主新了一个大版本，接口对不上。查看方式很简单，在 dsh 的插件管理面板里找到 dsh-codex-connect，看它的版本号，然后去插件市场的更新日志里核对兼容的宿主版本区间。

如果你用的是命令行方式管理插件，可以用类似下面的命令列出已安装插件及其版本（具体命令名以你的 dsh 版本为准）：

dsh plugin list --verbose

输出里会包含插件名、版本、状态、依赖的宿主版本范围。重点看两列：version和requires。如果requires写的宿主版本范围不包含你当前的宿主版本，那后面所有排查都是白费功夫，先降级或升级插件再说。

2.2 记录当前网络环境的关键参数

排查网络类问题，最忌讳“边猜边改”。先把当前环境的关键参数记下来，后面每改一次只动一个变量，才能定位到真正的元凶。需要记录的有四项：本机 IP、默认网关、DNS 服务器、代理设置状态。

Windows 下用一条命令全拿到：

ipconfig /all

Linux/macOS 下：

ip addr && ip route && cat /etc/resolv.conf

把输出里的 IPv4 地址、默认网关、DNS 服务器抄下来。代理设置单独看：Windows 在“设置 > 网络和 Internet > 代理”里看，Linux 看环境变量http_proxy、https_proxy、no_proxy。

注意：很多人排查时反复重启插件，却从来没看过代理设置。dsh-codex-connect 默认会读取系统代理，如果系统代理指向一个已经失效的地址，插件就会一直卡在连接阶段，而浏览器可能因为走了别的通道反而正常。这是最隐蔽的坑之一。

2.3 准备一个“干净”的测试终端

后面很多命令需要在终端里跑，建议单独开一个干净的终端窗口，不要和 IDE 内置终端混用。原因是 IDE 内置终端可能注入了额外的环境变量（比如 IDE 自己设的代理），会干扰判断。用系统自带的 cmd、PowerShell 或 Terminal 就行。

3. 现象一：插件面板一直显示“连接中”，永远不变成“已连接”

这是出现频率最高的现象，没有之一。表现是插件图标一直在转圈，或者状态栏写着“connecting”，等五分钟还是这样。很多人第一反应是“网络不通”，但实际上这个现象背后至少有四种完全不同的原因，得逐层剥。

3.1 第一步：确认插件进程是否真的活着

先别急着测网络，先看插件进程在不在。有时候插件崩溃了但 UI 没刷新，你看到的“连接中”其实是僵尸状态。

Windows 下：

tasklist | findstr /i "dsh codex"

Linux/macOS 下：

ps aux | grep -i "dsh\|codex" | grep -v grep

如果输出为空，说明插件进程根本没起来，问题在插件加载阶段，不在网络。这时候去看 dsh 的日志目录，通常在主目录下的.dsh/logs里，找最新的日志文件，搜codex-connect关键字，看有没有加载失败的堆栈。

如果进程在，但 CPU 占用一直是 0，说明它卡在某个等待上，继续往下走。

3.2 第二步：用 telnet 测端口通不通

这是最经典也最有效的一招。先确认插件要连的目标地址和端口，这个信息在插件的配置文件里，通常在.dsh/plugins/dsh-codex-connect/config.json或类似路径。找到host和port两个字段。

假设目标是api.example-codex.com的 443 端口，用 telnet 测：

telnet api.example-codex.com 443

如果屏幕变成一片黑或者显示Connected to ...，说明 TCP 层是通的，问题在更上层（TLS 握手或应用层协议）。如果显示Could not open connection或一直卡住然后超时，说明 TCP 层就不通，问题在路由、防火墙或 DNS。

提示：Windows 默认没开 telnet 客户端。开启方法：控制面板 > 程序 > 启用或关闭 Windows 功能 > 勾选“Telnet 客户端”。或者用 PowerShell 的Test-NetConnection代替，效果一样：

Test-NetConnection api.example-codex.com -Port 443

输出里的TcpTestSucceeded为True就是通，False就是不通。

3.3 第三步：DNS 解析是否正常

如果 telnet 直接报“找不到主机”，那就是 DNS 问题。先用 nslookup 确认：

nslookup api.example-codex.com

正常应该返回一个或多个 IP 地址。如果返回Non-existent domain或超时，说明 DNS 解析失败。这时候换一个公共 DNS 试试，比如把系统 DNS 临时改成223.5.5.5或119.29.29.29，再测一次。如果换了 DNS 就通了，说明是你原来那个 DNS 服务器的问题，不是插件的问题。

我遇到过一种情况：公司内网 DNS 把某个域名解析到了一个内网地址，而那个地址上根本没有对应的服务，导致 telnet 能通但 TLS 握手失败。这种“假通”最迷惑人，所以 DNS 解析出来的 IP 一定要和预期对一下。

3.4 第四步：抓包看卡在哪一步

如果前三步都正常，但插件还是连不上，就得上抓包了。Windows 下用pktmon（Win10 1809 以后自带），Linux 下用tcpdump。

Windows：

pktmon start --etw -c --comp nics

然后复现一次连接，停止抓包：

pktmon stop pktmon etl2txt PktMon.etl -o capture.txt

在 capture.txt 里搜目标 IP，看 TCP 三次握手有没有完成。如果只有 SYN 没有 SYN-ACK，说明对方没响应，可能是防火墙拦了。如果 SYN-ACK 有了但紧接着是 RST，说明对方主动拒绝，可能是目标端口不对或服务没起。

Linux 下更简单：

tcpdump -i any host api.example-codex.com -w capture.pcap

抓完用 Wireshark 打开看时序图，一目了然。

4. 现象二：提示“认证失败”或“token 无效”

连接能建立，但一到认证环节就挂。这个现象比第一个好排查，因为错误信息更具体。核心就三个方向：token 本身过期、token 传丢了、系统时间不对。

4.1 检查 token 是否过期

dsh-codex-connect 用的 token 通常有有效期。在插件配置里找到 token 字段，它一般是一串 JWT 格式的字符串（三段用点分隔）。把中间那段拿出来，用 base64 解码，看exp字段对应的时间戳。

echo "中间那段" | base64 -d

解出来是个 JSON，里面有exp（过期时间，Unix 时间戳）和iat（签发时间）。把exp转成可读时间：

date -d @1700000000

如果这个时间已经过了，那就是 token 过期，重新在插件里走一遍授权流程拿新 token 就行。

4.2 确认 token 有没有被环境变量覆盖

这是个很隐蔽的坑。插件读取 token 的优先级通常是：环境变量 > 配置文件。如果你之前为了测试在系统里设过一个CODEX_TOKEN环境变量，插件会优先用它，而你可能早就忘了这回事。

Windows 下查看：

set | findstr /i "codex token"

Linux/macOS 下：

env | grep -i "codex\|token"

如果有输出，而且值和你配置文件里的不一样，那就是它在捣乱。临时清掉再试：

set CODEX_TOKEN=

Linux/macOS：

unset CODEX_TOKEN

4.3 系统时间偏差导致签名校验失败

JWT 的签名校验依赖时间。如果你的系统时间比真实时间慢了或快了超过几分钟，签名校验就会失败，报“token 无效”。这个现象特别容易在虚拟机或长时间没同步时间的机器上出现。

Windows 下同步时间：

w32tm /resync

Linux 下：

sudo ntpdate pool.ntp.org

或者用timedatectl看当前时间同步状态：

timedatectl status

看System clock synchronized是不是yes。如果不是，先解决时间同步问题。

实操心得：我有一次在一台离线虚拟机上排查了半小时，最后发现虚拟机时间停在三个月前。同步完时间，token 立刻就能用了。这个坑的迷惑性在于，错误信息只说“token 无效”，完全不提时间。

5. 现象三：连接成功但命令执行超时

插件显示已连接，但一执行具体命令就卡住，最后报 timeout。这个现象说明链路是通的，但数据传输出问题。常见原因有三个：MTU 不匹配、中间设备做了深度包检测、目标服务响应慢。

5.1 用 ping 测 MTU 和丢包

先测基础连通性和丢包率：

ping -n 20 api.example-codex.com

Windows 下-n是次数，Linux 下是-c。看输出里的丢包率和平均延迟。如果丢包率超过 5%，那超时就是网络质量导致的，跟插件无关。

再测 MTU。默认以太网 MTU 是 1500，但经过某些隧道或特殊链路时可能需要调小。用带-f（不分片）和指定包大小的 ping 来探测：

ping -f -l 1472 api.example-codex.com

Windows 下-l指定数据部分大小，1472 + 28 字节头 = 1500。如果报“需要分片但设置了 DF 标志”，说明 MTU 小于 1500，逐步减小-l的值直到能通，找到实际 MTU。

Linux 下：

ping -M do -s 1472 api.example-codex.com

如果实际 MTU 明显小于 1500，需要在网卡上调整：

netsh interface ipv4 set subinterface "以太网" mtu=1400 store=persistent

5.2 检查是否有中间设备干扰

有些企业网络或公共网络会对长连接做限制，或者对特定协议做深度包检测。判断方法是：换一个网络环境（比如用手机热点）再试。如果热点下正常，原网络下超时，那就是网络中间设备的问题。

这种情况下，可以尝试让插件走更短的连接或调整心跳间隔。在插件配置里找keepalive或heartbeat相关字段，把间隔调小，让连接保持活跃，减少被中间设备断开的概率。

5.3 目标服务响应慢的确认方法

如果换网络也慢，那可能是目标服务本身响应慢。用 curl 直接测一次请求耗时：

curl -o /dev/null -s -w "DNS: %{time_namelookup}s\nConnect: %{time_connect}s\nTLS: %{time_appconnect}s\nTotal: %{time_total}s\n" https://api.example-codex.com/health

看各阶段耗时。如果time_connect就很大，是网络问题；如果time_appconnect大，是 TLS 握手慢；如果time_total大但前面都小，是服务端处理慢。

6. 现象四：插件加载失败或直接闪退

这个现象通常发生在启动阶段，插件还没进入连接流程就挂了。原因集中在依赖缺失、权限不足、配置文件损坏三类。

6.1 查看插件加载日志

dsh 的日志是排查这类问题的第一手资料。日志位置一般在：

• Windows:%USERPROFILE%\.dsh\logs\
• Linux/macOS:~/.dsh/logs/

找最新的那个日志文件，搜codex-connect和error。常见的错误信息有：

6.2 检查端口占用

如果日志里提到端口被占用，用命令查是谁占的：

Windows：

netstat -ano | findstr :你的端口号

拿到 PID 后：

tasklist | findstr PID

Linux：

lsof -i :你的端口号

或者：

ss -tlnp | grep 你的端口号

找到占用进程后，要么杀掉它，要么在插件配置里换一个端口。

6.3 配置文件损坏的修复

配置文件损坏最常见的原因是手动编辑时格式错了，或者写入过程中断电。修复方法很简单：把配置文件重命名备份，然后重启 dsh，插件会自动生成一份默认配置。

mv config.json config.json.bak

重启后如果插件能正常加载，说明就是配置问题。然后对照备份文件，把必要的字段（token、host、port）手动填回新配置里，别整个覆盖回去。

注意：有些插件的配置文件里存了加密后的凭据，直接复制备份文件可能导致解密失败。所以建议只手动迁移必要字段，而不是整个文件覆盖。

7. 现象五：能连上但功能异常，比如代码补全不工作

这是最“软”的一类问题，链路完全正常，但具体功能不对。排查思路和前四种完全不同，重点在功能配置和版本兼容。

7.1 确认功能开关是否打开

dsh-codex-connect 的很多功能是分开关控制的。在插件设置面板里，逐项确认：代码补全、代码解释、重构建议这些开关是不是都开了。有时候插件更新后，新版本默认关闭了某些功能，而你没注意到。

配置文件里对应的字段通常是features下面的布尔值：

{ "features": { "completion": true, "explain": true, "refactor": false } }

如果refactor是false，那重构功能不工作就是正常的，打开就行。

7.2 检查语言服务器是否正常

代码补全这类功能依赖语言服务器。如果语言服务器没起来，补全就不工作。在 dsh 的输出面板里找语言服务器相关的日志，看有没有启动失败的记录。

常见问题是语言服务器需要的运行时（比如某个版本的 Node.js 或 Python）没装或版本不对。用命令确认：

node --version python --version

对照插件文档里要求的版本范围，不在范围内就升级或降级。

7.3 版本兼容性矩阵

功能异常很多时候是版本组合不对。我整理了一个常见的兼容性对照表，供参考：

如果你的组合不在表里，去插件市场的更新日志里找对应版本的说明。版本不匹配导致的功能异常，靠改配置是修不好的，只能升级或降级。

7.4 用最小化配置复现

如果以上都正常但功能还是不对，用最小化配置测试：新建一个干净的配置文件，只填 host、port、token 三个必填项，其他全用默认值。然后重启插件，看功能是否恢复。如果恢复了，说明是你原来的某个配置项有问题，逐项加回去定位。

8. 常见问题速查表与排查顺序建议

把上面五个现象和对应的排查命令整理成一张速查表，方便你遇到问题时快速定位：

排查顺序建议按这个优先级来：先确认进程活着，再确认 TCP 通，再确认认证过，最后才看功能。不要跳步，因为后面的问题往往被前面的问题掩盖。我见过有人直接去查功能配置，结果发现根本原因是 token 过期，白折腾一小时。

实操心得：每次排查只改一个变量，改完立刻复现。同时改多个地方，即使问题解决了你也不知道是哪个改动起的作用，下次遇到同样问题还是不会修。

9. 几个我踩过的坑和对应的土办法

第一个坑：Windows 下用 PowerShell 跑 telnet 测试，结果 PowerShell 把 telnet 当成了别名，实际执行的是Test-NetConnection，输出格式完全不一样，我对着输出愣了半天。后来改用 cmd 跑 telnet 才正常。所以命令在哪个 shell 里跑，一定要看清楚。

第二个坑：插件配置文件里的 host 字段填的是域名，但 DNS 解析出来是 IPv6 地址，而我的网络环境 IPv6 不通，导致连接超时。解决办法是在配置里强制用 IPv4，或者把 host 直接改成 IPv4 地址。判断方法很简单，nslookup看返回的是 A 记录还是 AAAA 记录。

第三个坑：公司网络对长连接有 5 分钟空闲断开的策略，插件默认心跳是 10 分钟，结果每次空闲几分钟后第一个命令必然超时。把心跳改成 2 分钟后问题消失。这个坑的隐蔽性在于，它只在“空闲一段时间后”才出现，如果你一直在用，反而不会触发。

第四个坑：插件更新后配置文件格式变了，旧配置里的某个字段在新版本里被重命名了，但插件没有做向后兼容，直接报解析错误。解决办法是看更新日志里的“Breaking Changes”部分，手动迁移字段。养成看更新日志的习惯，能省很多排查时间。

10. 把排查流程固化成脚本

如果你经常需要在多台机器上排查，可以把上面的命令串成一个脚本，一键输出所有关键信息。Windows 下写个.bat：

@echo off echo === Process === tasklist | findstr /i "dsh codex" echo === Port Test === powershell -Command "Test-NetConnection api.example-codex.com -Port 443" echo === DNS === nslookup api.example-codex.com echo === Proxy === reg query "HKCU\Software\Microsoft\Windows\CurrentVersion\Internet Settings" | findstr /i "ProxyEnable ProxyServer" echo === Time === w32tm /query /status

Linux 下写个.sh：

#!/bin/bash echo "=== Process ===" ps aux | grep -i "dsh\|codex" | grep -v grep echo "=== Port Test ===" timeout 5 bash -c "cat < /dev/null > /dev/tcp/api.example-codex.com/443" && echo "TCP OK" || echo "TCP FAIL" echo "=== DNS ===" nslookup api.example-codex.com echo "=== Proxy ===" env | grep -i proxy echo "=== Time ===" timedatectl status

跑一遍脚本，把输出保存下来，对比正常和异常时的差异，定位速度会快很多。这个脚本我放在每台开发机的桌面，出问题先跑一遍，五分钟内基本能锁定方向。

最后分享一个判断“是不是插件本身问题”的土办法：找一个确定能用的环境（比如同事的机器），把同样的配置导过去试。如果那边能用，说明是你环境的问题；如果那边也不能用，说明是插件或服务端的问题。这个二分法能帮你快速排除掉一半的可能性，省下大量瞎猜的时间。