DeepSeek Harness 3080 端口占用:修改端口与 Host 限制

解决 DSH Web UI 默认 3080 端口占用,提供 Windows、macOS、Linux 只读检查命令、--port 修复、验证与回滚方法。

社区整理已复核原始来源
完成后
只读识别 3080 监听进程;安全停止旧 DSH 或切换新端口;验证新地址并保留回滚路径
适合
终端明确报告 3080 地址被占用的用户
DSH
0.2.2-rc.1
系统
Windows / macOS / Linux
操作时间
5~10 分钟
风险
medium
本页目录(7)

直接修复

DeepSeek Harness Web UI 默认使用 127.0.0.1:3080。3080 被其他进程占用时,DSH 会在绑定端口时失败、以非零状态退出。最小改动是换一个空闲端口启动(当前默认版本 0.2.2-rc.1,需要 Node.js ≥24.9.0):

npx @deepseek-ai/[email protected] web --port 8080

已安装 CLI 的话也可以运行 dsh web --port 8080(等同于 dsh --profile web --port 8080,启动器参数要写在应用参数前面)。

换端口后,打开终端里 dsh web: 那一行打印的完整地址,不要手输裸地址。 每次启动都会生成新的启动令牌,登录 cookie 同时绑定主机名和端口;直接输入 http://127.0.0.1:8080 而没有带令牌,页面可能打开但所有接口都返回 401。(连接认证说明(外部链接,在新标签页打开))

默认配置保留了读取启动参数的表达式,所以命令行端口值优先;如果你的 Profile patch 用字面量替换了整段 config,就会移除这个读取,参数不一定还能生效。

官方桌面端使用系统分配的端口,不会占用 3080,所以 3080 冲突只可能来自另一个 Web 或 CLI 实例,或者其他程序。(桌面端说明(外部链接,在新标签页打开))

先只读确认占用者

只有启动终端明确报告 3080 地址已被使用,才属于本页问题。先读取监听信息,不要直接结束不认识的进程。

Windows PowerShell:

Get-NetTCPConnection -LocalPort 3080 -State Listen | Select-Object LocalAddress,LocalPort,OwningProcess
Get-Process -Id <OwningProcess>

macOS:

lsof -nP -iTCP:3080 -sTCP:LISTEN

Linux:

ss -ltnp 'sport = :3080'

预期结果是看到监听地址和进程标识。若没有监听者,但 DSH 仍在配置解析阶段退出,应回到Web UI 启动失败总排查,检查 Node、插件构建或配置错误。

路径一:正常停止旧 DSH

如果占用者是你之前启动且不再需要的 DSH,回到对应终端按一次 Ctrl+C,等待进程完成关闭,再重新运行默认命令。不要通过模糊进程名批量结束 Node 进程;同一台机器上可能还有其他开发服务。

停止后重新执行对应系统的只读检查命令。3080 不再处于监听状态,才说明旧实例已经释放端口。

路径二:保留旧服务并切换端口

如果占用者用途不明或仍需运行,保留它并给本次 DSH 使用新端口:

npx @deepseek-ai/[email protected] web --port 8080

新端口也被占用时,选择另一个本机空闲端口,并始终使用终端打印的带令牌地址。通过 SSH 启动时不会打开浏览器,需要把新端口转发到本机后再打开打印的地址。一次只修改端口,不要同时改 Host、反向代理和防火墙,这样更容易判断修复是否有效。

为什么 --host 0.0.0.0 不可用

0.2.2-rc.1 的 CLI 参考列出的 Web 参数有 --host、--port、--tls-cert、--tls-key、--public-url、可重复的 --trusted-host 与 --no-open。--host 必须是一个具体的本机地址,不能是通配地址:

dsh web --host 0.0.0.0

该参数会以用法错误退出。这不是端口占用,也不应通过反复换端口解决。--trusted-host 只增加浏览器信任围栏接受的具名地址,不会把监听地址开放到所有网卡;没有加入信任的地址访问时,接口会返回 403。

需要局域网或远程访问时,0.2.2-rc.1 提供的官方做法是:用 --host <具体本机 IP> 绑定一个地址(绑定的 IP 会被直接信任),配合 --tls-cert、--tls-key 启用 TLS,或者放在反向代理后面,用 --public-url 加 --trusted-host 声明对外地址,见公开部署说明(外部链接,在新标签页打开)。不加 TLS 的非回环监听是明文传输。不能把公网开放包装成端口冲突的简单修复。

验证修复

  1. 终端保持运行,没有新的绑定或配置错误。
  2. 新地址能加载 DSH Web UI。
  3. 原来的 3080 服务不受影响,或已按预期正常停止。
  4. Workspace 和模型入口可用。
  5. 关闭本次 DSH 后,新端口不再被它占用。

页面打开但输入框不可用通常不是端口错误,请看DSH Workspace 未选择;模型选择或凭据报错则进入DSH 模型与 Provider 配置。

修复后按启动排障的验证步骤复查服务与页面。2026-11-12 按 0.2.2-rc.1 固定提交 66491b05 的 CLI 参考、web 服务器与连接认证说明复核(2026-09-12 首次按 0.1.5-rc.1 核对),没有运行跨平台端口测试。

回滚

停止使用 --port 启动的进程,下次不带该参数运行,就会恢复默认 3080。若同时修改过 Profile patch,不要假设命令停止后配置也自动恢复;用 dsh --profile web --dump-config 检查实际配置层。

来源与维护信息

本文根据以下原始资料整理。版本变化后,请以官方资料和页面标注的验证日期为准。

完成当前任务后

按结果继续,不要停在文章末尾