# DeepSeek Harness 安装后 127.0.0.1:3080 无法打开：六大原因与修复方法

- 原文：[https://news.qiniu.com/archives/1787219510119](https://news.qiniu.com/archives/1787219510119)
- 发布时间：2026-08-21
- 分类：教程与实践
- 标签：DeepSeek Harness

> 发布日期：2026-08-20｜适用系统：Windows、macOS、Linux、WSL2、Docker｜适用版本：DeepSeek Harness Developer Preview

**核心结论**：DeepSeek Harness 安装后无法打开 `http://127.0.0.1:3080`，通常不是浏览器故障，而是 Web 服务没有成功启动、3080 端口被占用、程序实际监听了其他地址，或者 Docker/WSL2 没有正确暴露端口。先保留启动终端并查看报错，再检查 3080 是否处于监听状态，可以最快区分问题属于“服务端”还是“浏览器端”。

**最快排查顺序**：

1. 在终端重新运行 `npx @deepseek-ai/dsh web`，不要关闭终端。
2. 确认启动输出中显示的实际访问地址和端口。
3. 用 `curl -v http://127.0.0.1:3080/` 测试本机连接。
4. 检查 3080 端口由哪个进程监听。
5. 根据 `Connection refused`、页面空白、端口占用或容器无法访问分别处理。

* * *

DeepSeek Harness Web UI 默认通过 `http://127.0.0.1:3080` 提供本地页面。浏览器打不开这个地址，只能说明浏览器没有从该地址获得可用页面，并不能证明 Harness 已经正确安装。最有价值的线索通常在启动命令所在的终端里。

## 先用 5 分钟判断问题在哪里

打开一个新的终端窗口，重新启动 Web UI：

```bash
npx @deepseek-ai/dsh web
```

命令运行后不要关闭终端。正常情况下，进程应持续运行，并输出本地访问地址。如果命令立即退回提示符，或者出现依赖、权限、配置、端口等错误，说明 Web 服务并没有成功启动，应先处理终端中的第一条明确错误。

再打开另一个终端测试 HTTP 连接：

```bash
curl -v --connect-timeout 5 http://127.0.0.1:3080/
```

根据结果判断：

| 检查结果 | 代表什么 | 下一步 |
|---|---|---|
| `Connection refused` | 3080 没有服务监听，或服务已退出 | 查看启动日志和端口监听 |
| 返回 HTML | 服务端正常，问题更可能在浏览器、代理或缓存 | 使用无痕窗口并绕过代理 |
| 返回 `404` | 端口有服务，但可能不是 Harness 或访问路径不对 | 核对监听进程和启动输出 |
| 一直超时 | 服务卡住、网络层拦截或容器端口未暴露 | 检查进程、Docker/WSL2 和防火墙 |
| 页面能开但空白 | 前端资源或脚本加载失败 | 查看浏览器控制台和终端日志 |

## 原因一：DeepSeek Harness Web 服务没有启动成功

这是最常见的原因。`npx` 完成下载安装，不等于 Web 服务已经成功运行。Node.js 版本、包下载、配置加载或插件启动失败，都可能让进程在绑定 3080 端口前退出。

先确认运行环境：

```bash
node -v
npm -v
npx --version
```

如果其中任意命令不存在，应先安装项目要求的 Node.js 版本。Node.js 已存在时，再执行启动命令，并优先处理终端中最早出现的明确报错，不要只看最后一行通用退出信息。

还可以让 `npx` 明确使用当前发布包，排除旧缓存命令或本地同名脚本的干扰：

```bash
npx --yes @deepseek-ai/dsh web
```

如果当前版本的命令参数发生变化，先查看内置帮助，而不是直接套用旧教程中的参数：

```bash
npx @deepseek-ai/dsh web --help
```

DeepSeek Harness 仍处于 Developer Preview，不同版本的命令、配置和插件可能发生变化。升级后才出现问题时，应同时记录包版本、Node.js 版本和完整启动日志。

## 原因二：3080 端口没有监听或被其他程序占用

### macOS 和 Linux

检查谁在监听 3080：

```bash
lsof -nP -iTCP:3080 -sTCP:LISTEN
```

Linux 也可以使用：

```bash
ss -lntp | grep ':3080'
```

没有输出，说明当前没有进程监听 3080，问题仍在 Harness 启动阶段。有输出但进程不是 Node.js 或 DeepSeek Harness，则 3080 已被其他程序占用。

### Windows PowerShell

```powershell
Get-NetTCPConnection -LocalPort 3080 -State Listen
```

查到 PID 后确认进程身份：

```powershell
Get-Process -Id <PID>
```

不要看到端口占用就直接结束进程。先确认它是否属于正在运行的 Harness、另一个开发服务或系统程序。如果是旧的 Harness 进程，应先回到原终端正常停止；如果是其他项目，则查看 `web --help`，确认当前版本是否支持改端口，并使用其实际支持的参数或配置项。

## 原因三：浏览器代理拦截了本地地址

如果 `curl` 能返回 HTML，但浏览器仍显示“无法访问此网站”，服务端大概率已经正常。此时依次检查：

1. 地址必须是 `http://127.0.0.1:3080/`，不要误写成 `https://`。
2. 分别尝试 `http://localhost:3080/` 和 `http://127.0.0.1:3080/`。
3. 使用浏览器无痕窗口，排除旧缓存和扩展影响。
4. 在代理软件中将 `localhost`、`127.0.0.1` 和本地地址加入直连规则。
5. 暂时停用会改写网页或拦截脚本的浏览器扩展，再重新加载。

本地地址不需要经过公网代理。代理工具若把 `127.0.0.1` 请求转发到远程节点，可能产生连接失败、502 或证书错误。

## 原因四：页面打开后一直空白

“无法连接”和“白屏”不是同一种故障。白屏说明浏览器通常已经收到入口页面，但前端 JavaScript、静态资源或后端接口没有正常完成加载。

先执行：

```bash
curl -I http://127.0.0.1:3080/
```

然后在浏览器开发者工具中检查 **Console** 和 **Network**：

- 静态文件返回 `404`：可能是构建产物缺失或版本混装。
- 接口返回 `500`：查看启动终端中的对应服务端错误。
- 出现 WebSocket 失败：检查代理、反向代理或安全软件。
- JavaScript 报模块加载错误：清理浏览器缓存后重启当前版本，不要混用源码构建和 `npx` 安装目录。

如果安装了社区 Web UI、主题或其他 Harness 插件，也要考虑插件与当前 Developer Preview 版本不兼容。应使用独立 profile 验证，或按插件文档暂时停用最近新增的插件，再确认原生 Web UI 是否恢复。

## 原因五：Docker 内启动了服务，但宿主机没有暴露 3080

在容器内部打开 `127.0.0.1:3080`，只代表容器自己可以访问。要从宿主机浏览器访问，必须同时满足：

- 容器发布了 3080 端口，例如 Docker 映射中存在 `3080:3080`；
- Harness 在容器内监听可对外连接的地址，而不是只监听容器内部的 `127.0.0.1`；
- 宿主机上的 3080 没有被其他程序占用。

检查容器和端口映射：

```bash
docker ps
docker port <容器名或容器ID>
docker logs <容器名或容器ID>
```

如果 `docker port` 没有显示宿主机端口映射，应修改容器启动或 Compose 配置后重新创建容器。监听地址和端口参数必须以当前版本 `web --help` 或项目部署文档为准，不要凭经验假设参数名称。

## 原因六：WSL2 中启动，Windows 浏览器无法访问

先在 WSL2 内部测试：

```bash
curl -v http://127.0.0.1:3080/
```

如果 WSL2 内也连接失败，应回到 Harness 启动和端口监听问题；如果 WSL2 内正常、Windows 浏览器失败，再检查以下项目：

1. 当前 Windows 与 WSL 版本是否支持 localhost 转发。
2. Harness 是否只监听了不对外暴露的地址。
3. Windows 防火墙或安全软件是否拦截 Node.js。
4. 公司代理是否接管了 localhost 请求。

在 WSL2 中查看地址：

```bash
hostname -I
```

可使用输出的 WSL2 IP 做一次临时验证。如果 WSL2 IP 可以访问而 `localhost` 不行，问题在 Windows 到 WSL2 的转发层；但 WSL2 IP 可能在重启后变化，不适合写死在长期配置中。

## 从源码安装时的专项检查

如果不是使用 `npx`，而是从官方仓库运行，应确认依赖安装和构建均已完成：

```bash
git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
pnpm install
pnpm run build
pnpm dsh web
```

重点检查：

- `pnpm install` 是否真正成功结束；
- 构建过程中是否出现 TypeScript 或前端资源错误；
- 当前目录是否是正确的仓库目录；
- Node.js、pnpm 与项目锁文件要求是否一致；
- 切换分支或更新代码后是否重新安装依赖并构建。

不要在依赖安装或构建失败后继续判断 3080 端口，因为此时 Web 服务通常根本没有生成或启动。

## 一套可直接照做的排查流程

```text
运行 dsh web
    ↓
终端是否持续运行？
    ├─ 否 → 修复终端第一条错误
    └─ 是
        ↓
3080 是否处于 LISTEN？
    ├─ 否 → 核对实际端口和启动日志
    └─ 是
        ↓
curl 是否返回 HTML？
    ├─ 否 → 检查监听进程、容器、WSL2、防火墙
    └─ 是
        ↓
浏览器是否正常显示？
    ├─ 否 → 检查 HTTP/HTTPS、代理、缓存、扩展和前端控制台
    └─ 是 → 进入模型与工作区配置
```

## Web UI 打开后还需要做什么？

`127.0.0.1:3080` 能打开只代表 Harness Web UI 已经启动，并不代表模型已经可用。进入页面后还需要：

1. 在 **Settings → Models** 中配置 Provider、API Key 和模型。
2. 通过 **Choose workspace** 添加并选择工作目录。
3. 新建 Session，发起一个最小请求验证模型连接。

如果页面能打开，但输入框不可用，优先检查是否已经选择工作区；如果请求报 `MISSING_CREDENTIAL` 或 `UNKNOWN_MODEL`，则属于模型 Provider 配置问题，不再是 3080 端口问题。

## 常见问题

### DeepSeek Harness 3080 端口打不开，是否需要重装？

通常不需要。先检查启动终端、端口监听和 `curl` 结果。只有依赖安装或构建持续失败，并且确认版本与环境要求匹配后，才需要考虑重新安装。

### `127.0.0.1:3080` 显示“拒绝连接”是什么意思？

表示浏览器能够访问本机网络栈，但 3080 当时没有可接受连接的服务。最常见原因是 Harness 没启动、启动后退出，或实际使用了其他端口。

### 可以把 `127.0.0.1` 改成 `0.0.0.0` 吗？

`0.0.0.0` 是服务端监听地址，不是通常供浏览器访问的目标地址。只有需要从容器、局域网或其他设备访问时才应考虑对外监听，而且必须同时增加防火墙、身份认证和访问控制。具体配置方式以当前版本文档和 `web --help` 为准。

### 关闭启动终端后为什么页面也打不开了？

`npx @deepseek-ai/dsh web` 启动的是前台服务，关闭终端通常会同时结束进程。调试阶段应保持终端开启；需要长期运行时，再根据官方部署文档选择受控的进程管理方式。

### 页面能打开，但 DeepSeek 模型不能回复怎么办？

这通常与端口无关。检查 API Key、Base URL、模型 ID、Provider 协议和工作区选择，并根据页面或终端中的具体错误继续排查。

## 结论

DeepSeek Harness 安装后 `http://127.0.0.1:3080` 无法打开，最有效的方法不是反复刷新或立即重装，而是按“启动日志 → 端口监听 → curl 响应 → 浏览器环境 → Docker/WSL2 网络”的顺序定位。`Connection refused` 优先检查服务是否运行；返回 HTML 但浏览器打不开，优先检查代理和浏览器；容器或 WSL2 内正常而宿主机失败，则重点检查监听地址和端口转发。

## 参考资料

- [DeepSeek Harness 官方仓库](https://github.com/deepseek-ai/deepseek-harness)
- [DeepSeek Harness Quickstart](https://deepseek-harness.github.io/deepseek-harness/en/guide/quickstart)
- [DeepSeek Harness Provider 配置](https://deepseek-harness.github.io/deepseek-harness/en/guide/providers)
