DSH Desktop 第一次打开要填几项配置，填错就卡在连接那一步

DSH Desktop 第一次打开卡在“连接中”，多数情况不是客户端本身有问题，而是设置页里两三个字段没和实际运行的服务对齐。通常必填的是服务地址和端口，模型名、API Key 是否必填取决于服务端有没有鉴权和默认模型。排查顺序建议固定成：先看清字段，再定地址写法，然后用一条命令确认服务真的在监听，最后按界面层和服务层分开查，别在同一层反复改设置。字段名每个版本可能不同，一律以自己安装后界面里显示的名字为准。

先把设置页里和连接相关的输入框抄下来，区分必填与可留空；地址本机写 127.0.0.1 比 localhost 更稳，远程要写实际主机地址，端口必须等于服务启动时输出的监听端口。用 lsof 或 curl 先确认端口有没有人在听，能区分“配置写错”和“服务没起来”。保存后仍卡住，先看应用日志尾部，再查服务进程，最后核对是否被旧配置覆盖。改动后重启应用，一次只改一个字段再验证。

打开设置页面，把连接相关的输入框逐个记下来

先别急着填，先把设置页里连接相关的输入框抄到便签上，再决定哪项动、哪项留空。常见字段及判断方式：

服务地址 / API 地址 / 服务器地址：基本都是必填，指的是客户端去连谁。留空无法连接。
端口：通常必填，必须和服务实际监听的端口一致，不能凭记忆填默认值。
模型名 / 模型 ID：服务端有默认模型时可以留空；如果服务端要求显式指定，留空会在请求阶段报错，而不是卡在连接中。
API Key / 令牌：本地无鉴权的服务可以留空；远端或开启了鉴权的服务必须填，填错一般表现为 401/403，而不是一直“连接中”。
超时 / 代理设置：一般可留默认，网络慢或经过转发时再调。

不同版本的字段名可能叫“服务端地址”“Endpoint”“Base URL”，含义接近。不要照抄别人的截图，以自己界面上实际显示的文字为准。

填服务地址：本机服务和远程服务写法不一样

服务跑在同一台机器上时，127.0.0.1 和 localhost 大多数情况等价，但有一个常见坑：localhost 可能先被解析到 IPv6 的 ::1，而服务只监听了 IPv4 的 127.0.0.1，这时就会表现为连不上。不确定服务监听方式时，建议先写 127.0.0.1。

服务在另一台机器或容器里时，地址要写那台机器的实际主机地址（或能被解析到的主机名），不要写 0.0.0.0——那是服务端的监听写法，不是客户端的连接地址。端口要和启动服务时终端输出的监听端口一致，例如输出里写着 listening on 0.0.0.0:xxxx，客户端端口就填 xxxx。

服务地址：127.0.0.1
端口：xxxx
模型名：（服务端有默认可留空）
API Key：（本地无鉴权可留空）

上例里的 xxxx 需要替换成实际监听端口，模型名和密钥按服务端是否要求来定。

用一条命令确认服务真的在监听

在改客户端之前，先在终端确认服务这一侧的状态，这样能把“配置写错”和“服务没起来”分开。

# 看端口有没有进程在监听
lsof -i :xxxx

# 直接请求服务基础地址，看有没有响应
curl -v http://127.0.0.1:xxxx/

三种常见结果的含义：

lsof 有 LISTEN 行，curl 能返回内容，哪怕返回 404 或 401，说明服务在听，问题出在客户端配置。
curl 立刻报 Connection refused，说明该端口没有进程监听，先去把服务启动起来，或改用正确的端口。
curl 长时间没反应最后超时，通常是地址不可达、被防火墙拦住，或者服务绑定的网卡和请求地址不匹配（比如服务只绑了 127.0.0.1，你却用主机地址去连）。

保存后还卡在连接中，按界面层和服务层各查一遍

卡住不动时，最耗时间的做法是在设置页里反复改。建议按下面顺序走一遍，避免在同一层打转：

先看应用日志尾部：找到 DSH Desktop 的日志文件，跟踪最后几十行，看它实际请求的是哪个地址、报的是解析失败、拒绝连接还是超时。日志里的目标地址经常和界面里以为填的不一样。
再确认服务进程是否存活：用 ps aux | grep 或 lsof -i :端口 确认进程还在、端口还在听。服务中途退出时，界面表现和“配置填错”几乎一样。
最后核对是否被旧配置覆盖：多份配置文件、多个配置档、环境变量、命令行参数之间可能互相覆盖，界面里显示的未必是运行时真正生效的那份。改完后确认保存的是当前正在使用的那一份。

如果第一步日志显示请求的地址和你填的一致、服务也确实在听，那再回头动客户端设置才有意义。

改完配置怎么确认已经生效

保存不等于生效。建议按以下步骤收尾：

完全退出应用再重新打开，不要只关窗口，部分客户端会保留上次的连接状态。
观察启动首屏日志或状态提示，确认它这次请求的地址、端口和刚填的一致。
发一次最小请求走通链路，例如 curl -s http://127.0.0.1:xxxx/ 加服务实际提供的健康检查路径（可能是 /health、/v1/models 之类，需要结合服务确认），客户端里也做一次最简单的对话或拉取动作。
一次只改一个字段再验证。同时改地址和端口，出问题时无法判断是哪一个引起的。

如果按上述顺序仍然连不上，把日志里的目标地址、服务端 lsof 的结果、curl 的返回这三样放在一起看，基本能定位到断在哪一段，而不是靠反复重装客户端。