DeepSeek Harness 端口冲突总览：dsh web 与桌面端的占用、改端口排查

DeepSeek Harness 的端口问题看起来只有一个症状「起不来」，但错误码分三类、修法完全不同：地址已在使用（被占）、权限被拒绝（权限或保留区间）、地址不可用（绑定地址不存在）。 顺序是先看错误码归类，再决定换端口还是处理占用者，最后确认绑定地址。三个入口各有自己的端口，冲突只发生在两个入口绑同一个端口时，改失败的那个即可。

DeepSeek Harness 的三种「端口不可用」要分清与三种处置

一句话结论：错误码决定了修法——认错类别会白折腾。

1. 别跳过归类这步：拿不到错误码时，先看启动输出的最后几行——它通常直接写明是哪一类。
2. 三类都可能表现为「起不来」，所以「换端口试试」只能解决第一类与第二类的一部分。

方案 A：换端口（最快）

一句话结论：绝大多数情况下换端口比找占用者快得多——除非该端口已被写进反代配置或团队文档。

1. 确认候选端口没人用（示例，macOS / Linux）：

lsof -nP -iTCP:3180 -sTCP:LISTEN      # 预期：无输出 = 该端口空闲

2. 用新端口启动（参数名以 dsh web --help 为准）：

dsh web --host 0.0.0.0 --port 3180
# 预期：启动成功并打印监听地址

3. 同步更新引用它的地方：反代配置、团队文档、书签——漏改一处就会表现为「服务正常但访问不到」。
4. 验证：本机 curl -I http://127.0.0.1:3180 有响应，再从反代/另一台设备访问一次。
5. 挑选端口的建议：避开低位端口（权限）与常见服务端口（易撞），选 3000-9000 区间里不常用的一个。

方案 B：找出占用者并处理（要保留原端口时）

一句话结论：只有当端口被固定引用、必须复用时，才值得去查占用者——顺序是「查进程 → 判断能否停 → 再决定」。

1. 查是谁在占：

# macOS / Linux
lsof -nP -iTCP:3080 -sTCP:LISTEN
# Windows（PowerShell）
# Get-NetTCPConnection -LocalPort 3080 | Select-Object OwningProcess

2. 判断能否停：是上次没退干净的 DeepSeek Harness 进程 → 可以停；是别的服务 → 评估影响后再动。

ps -ef | grep -i dsh | grep -v grep     # 确认是不是残留的 DSH 进程

3. 停掉残留进程后再启动（优先用系统信号正常终止，不要一上手就强杀）。
4. 验证：重启服务并确认端口已被自己占用（再次查 lsof 应显示你的进程）。
5. 顺手排查「为什么会有残留」：容器没删、上次异常退出、或同时开了多个入口——这三条是残留的主因。

方案 C：让端口分配避开保留区间（长期方案）

一句话结论：Windows 上「没人占用却起不来」多半是端口落在动态/保留区间——查清区间并固定用区间外的端口即可根治。

1. 了解本机保留区间（Windows 可用系统自带命令查看动态端口范围，具体命令以官方文档为准）。
2. 把 DeepSeek Harness 的端口固定在保留区间之外，并写进启动脚本，避免每次随机。
3. 容器场景另有一层：容器内若以非 root 运行，低位端口同样绑不了——统一改用高位端口。
4. 把端口写进文档：团队共享时，端口是配置的一部分，写清能避免「每人一个端口」导致的混乱。
5. 验证：重启机器后再启动一次，确认不再出现权限类失败（重启最容易复现这类问题）。

DSH plugin 三个入口的端口关系

一句话结论：CLI、桌面端、dsh web 各有端口，冲突只发生在绑同一个端口时——改失败的那一个就够了。

1. 先确认哪个入口失败，只处理它——三个都改反而会引入新问题。
2. 不要给两个入口配同一个端口，这是最直接的冲突来源。
3. 反代在场时：反代监听一个端口、dsh web 监听另一个，两者不能相同（配置见 给 dsh web 配反向代理与 HTTPS）。
4. 容器场景：宿主端口与容器内端口是两件事，映射关系写错也会表现为「端口冲突/连不上」（见 DeepSeek Harness 容器化安装）。

DeepSeek Harness 端口排查三步与判据表

一句话结论：归类 → 查占用 → 验绑定地址，三步走完必有结论。

1. 第一步（归类）：看启动输出里的错误码/提示，对照第一节三类。
2. 第二步（查占用）：lsof（POSIX）或 Get-NetTCPConnection（Windows）确认端口状态。
3. 第三步（验地址）：ipconfig / ip addr 确认你绑定的地址在本机存在（写错 IP 会出现「地址不可用」）。
4. 判据表：

5. 验证修复：重启服务并实际访问一次，而不是只看启动输出没有报错。

DSH plugin 排查注意事项

一句话结论：端口问题与插件无关——先把它排除掉，再去查插件侧，能省一半时间。

1. 服务起不来是端口层问题；服务能起但插件功能异常才是插件层问题（见 DeepSeek Harness 插件冲突总览）。
2. 别急着改鉴权配置：端口类失败与鉴权无关，混着改会让问题更难定位。
3. 容器里先分清宿主端口与容器端口，映射写错常被误报为冲突。
4. 团队共享时把端口写进文档，并保留一个备用端口。
5. 重启能复现的问题要记下来：只在重启后出现的端口失败，多半与保留区间或开机自启服务抢占有关。
6. 修复状态如实：本文三类错误码的分类与处置属通用操作系统行为的归纳；DeepSeek Harness 侧的具体默认端口与参数名请以你机器上 dsh web --help 的输出为准，Windows 保留区间的查看命令以微软官方文档为准确来源。

如果 dsh web 暂时起不来，也可以先用桌面端或 CLI 顶上，并在 DSH Plugin Hub 里确认插件状态——端口问题不该阻塞你手头的事。

只遇到 3080 被占用这一种情况，可直接看3080 端口冲突的定位与释放。

来源：apps/cli/README.md、apps/desktop/README.zh.md、Microsoft Learn · netsh。