- 完成后
- 只读识别 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 的非回环监听是明文传输。不能把公网开放包装成端口冲突的简单修复。
验证修复
- 终端保持运行,没有新的绑定或配置错误。
- 新地址能加载 DSH Web UI。
- 原来的 3080 服务不受影响,或已按预期正常停止。
- Workspace 和模型入口可用。
- 关闭本次 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 检查实际配置层。
来源与维护信息
本文根据以下原始资料整理。版本变化后,请以官方资料和页面标注的验证日期为准。
- GitHub:deepseek-ai/deepseek-harness 固定提交 README.zh.md(外部链接,在新标签页打开)
- GitHub:deepseek-ai/deepseek-harness 固定提交 README.zh.md(外部链接,在新标签页打开)
- GitHub:deepseek-ai/deepseek-harness 固定提交 README.zh.md(外部链接,在新标签页打开)
- GitHub:deepseek-ai/deepseek-harness 固定提交 public-deployments.zh.md(外部链接,在新标签页打开)
- GitHub:deepseek-ai/deepseek-harness 固定提交 README.zh.md(外部链接,在新标签页打开)
- GitHub:deepseek-ai/deepseek-harness 固定提交 README.zh.md(外部链接,在新标签页打开)
- GitHub:deepseek-ai/deepseek-harness 固定提交 README.zh.md(外部链接,在新标签页打开)
- GitHub:deepseek-ai/deepseek-harness 固定提交 README.zh.md(外部链接,在新标签页打开)