ChatGPTClaudeGrok / X / CursorGemini

DeepSeek Harness 本地快速入门能否发给同事:两个启动参数与令牌地址怎么配置

配置与使用发布于 2026-11-18作者: DeepSeek Plugin 插件市场
DeepSeek HarnessDSH plugin远程访问public-urltrusted-host
DeepSeek Harness 默认只监听 loopback,直接把打印地址发给同事通常打不开。本文讲 public-url 与 trusted-host 的分工、令牌地址为什么不能外发,以及反向代理必须做对的四件事。

DeepSeek Harness 本地快速入门跑通后,第一反应常是「把地址发给同事看看」。 但默认的 Web UI 只在 loopback 上提供服务,其他机器访问不到;打印地址还带着进程凭据。真要对外,需要三样东西分工:代理负责外部链路,--public-url 负责公告,--trusted-host 负责放行(来源)。

DeepSeek Harness 三条边界:监听端口、公告地址、信任 authority

对外发布不是「换一个地址」那么简单,而是三条边界同时成立。 先把它们分开(来源):

边界由谁负责作用
监听端口dsh 进程决定请求从哪里进来
公告地址--public-url告诉浏览器和使用者外部地址是什么
信任 authority--trusted-host决定哪些浏览器 Host 被接受

三条边界缺一不可。只改公告地址,请求仍然进不来;只开端口,浏览器 Host 可能被拒;只配信任,外部链路又没建好。官方的设计是把「展示」「接入」「放行」拆开,避免一个参数承担所有责任。

最常见的错误是只配一个:只配 public-url,页面地址对了但 API 403;只配 trusted-host,请求能进但打印地址仍是 loopback,复制给别人还是打不开;只开端口,页面能连但 Host 校验不过。三个都配,才是完整链路。

理解这一点,后面每个参数的作用就不会混。public-url 不是「开放访问」,trusted-host 也不是「设置域名」,它们各自只解决一段。

DeepSeek Harness 为什么不能直接把打印地址发给同事

打印地址不能外发,有两个原因:访问不到,以及带着凭据。 第一个原因是网络边界:dsh --profile web 在 loopback 端口上提供 GUI,其他机器上的浏览器无法访问,进程也不知道你实际使用的外部地址(来源)。

第二个原因是安全边界:打印的 URL 携带进程凭据,只应与预期用户分享。把它贴到群里,等于把启动令牌一起发出去。令牌可以换会话 cookie,拿到的人就能进入你的 Web UI。

所以,正确的共享方式不是「复制地址」,而是「建一条受控的外部链路,再给同事一个不带启动令牌的入口」。这条链路通常由反向代理承担,具体写法见《给 dsh web 配反向代理与 HTTPS》。

DeepSeek Harness --public-url 公告什么、不保护什么

--public-url 只负责「告诉别人地址是什么」,不负责「让请求进来」或「放行」。 官方说明:它接受可带挂载前缀的 http:// 或 https:// 根,并归一化为以 / 结尾;它提供打印与打开的启动 URL、DSH_WEB_URL,以及 agent 运行时上下文中的 Web GUI URL(来源)。

关键点是:webserver 继续提供 origin-root 路由,且从不了解挂载。也就是说,--public-url https://app.example/ui/ 只是公告「外部看到的是这个地址」,内部路由仍然是 / 开头。挂载前缀由代理剥离,不是由 DeepSeek Harness 自己处理。

这带来两个实践结论:

  1. 公告地址要与代理配置一致 — 代理把 /ui/ 剥成 /,public-url 就写带 /ui/ 的外部地址;
  2. 不要指望 public-url 保护端口 — 它只是展示,端口仍然暴露在监听地址上。

举例来说,外部用户访问 https://app.example/ui/,代理把 /ui/api/... 转成监听器的 /api/...,public-url 就应写 https://app.example/ui/。如果写成 https://app.example/,打印出来的地址会少一段,用户打开就可能是 404。

「公告」和「保护」是两件事。把 public-url 当成安全开关,是对它最常见的误解。

DeepSeek Harness --trusted-host 不配就 403

--trusted-host 决定浏览器用的 authority 是否被接受,不配就可能每个 API 都 403。 官方说明:栅栏接受 loopback、监听器自身的绑定地址,以及每个由 --trusted-host 点名的 authority;浏览器若以其他 authority 访问,无论代理多么正确,每个 API 调用都会得到 403(来源)。

这里要区分两个动作:

  • --public-url 公告地址 — 只是展示,不等于接纳;
  • --trusted-host 接纳 authority — 才决定放行。

所以,配了 public-url 但没配 trusted-host,是典型的「地址看起来对、API 全 403」。反过来,只配 trusted-host 不配 public-url,可能能访问但打印出来的地址不对,复制给别人仍然打不开。

如果使用隧道且每次绑定端口不同,trusted-host 不带端口的条目可以匹配任意端口。这一点对临时分享很有用,但不要把「任意端口」理解成「任意主机」。

还要注意:trusted-host 只影响放行,不负责认证。真正完成认证的是打印 URL 中的启动 token 与签名会话 cookie;栅栏只决定浏览器使用的 authority 是否被接受。两者不是替代关系。

DeepSeek Harness 代理四件必做

代理不是「转发一下」就行,官方列了四件必须做对的事。 少一件,表现可能是 403、白屏、WebSocket 断开或登录循环(来源):

  1. 保留浏览器可见的 Host — 栅栏把收到的 Host 与被接受的 authority 比对,代理原样转发,不要改写成监听器地址;
  2. 剥离挂载前缀 — 监听器应答 origin-root 路由,/ui/api/... 必须以 /api/... 抵达;
  3. 转发升级请求 — 页面请求与 WebSocket 升级都要带 Upgrade 与 Connection 头;
  4. 改写 cookie 作用域 — 后端签发的是 host-only Path=/ cookie,代理把 Path 改写为挂载路径,并在 HTTPS 链路上加 Secure。

还有一条容易被忽略:/ui/ 是唯一入口,裸挂载 /ui 必须重定向到 /ui/。只有 /ui/ 会把启动 token 换成会话 cookie;已持有 cookie 的浏览器也可以由它或 /ui/index.html 取得文档。

这四件加一条重定向,基本覆盖了「代理看起来通、页面却用不了」的常见原因。具体 Nginx/Caddy 写法不在本篇展开,见反向代理那篇。

TLS 可以终止在代理,也可以由监听器自己提供证书。无论哪种,public-url 仍然只是公告;监听器自己提供 TLS 时,会话 cookie 会带 Secure,代理只需要改写 Path。证书保护的是浏览器到服务器这一段,不改变 Host 校验与令牌认证。

DeepSeek Harness 验证:从另一台机器访问

验证对外发布,必须从另一台机器访问,不能只在本机开新标签。 本机访问 loopback 永远成功,不能证明外部链路通了。推荐五步(来源):

  1. 另一台机器打开公告地址 — 能拿到页面,而不是连接超时;
  2. 看 API 是否 403 — 如果页面能开、API 全 403,先查 trusted-host;
  3. 看 WebSocket 是否升级 — 会话流不动、状态不更新,查 Upgrade 头;
  4. 看 cookie 是否带对 — 登录循环或每次都要重新进,查 Path 与 Secure;
  5. 确认端口没有裸露 — 监听端口只对可信代理或内网开放,不要直接暴露公网。

五步都过,才算真正「发给同事能用」。只过第一步,说明页面能开,但交互链路可能还没通。

如果只是临时给同网络的同事看,不一定要公网发布,可以先看《DeepSeek Harness 远程访问怎么配》里的 SSH 隧道方案;需要长期对外,再走反向代理与 TLS。启动与端口的完整说明见《dsh web 怎么打开》。

最后提醒:分享前先确认你分享的是「入口」还是「带令牌的启动地址」。前者需要代理和认证配置,后者等于把进程凭据交出去。

如果只是自己换一台机器访问,优先用隧道,不要先改公网发布配置。

ChatGPTClaudeGrok / X / CursorGemini

常见问题

DeepSeek Harness 启动后打印的地址,能直接发给同事打开吗?

DeepSeek Harness 里,通常不能。DeepSeek Harness 默认在 loopback 端口提供服务,其他机器的浏览器访问不到;打印地址还携带进程凭据,只应与预期用户分享。对外访问要配反向代理与 public-url。

DeepSeek Harness 的 public-url 和 trusted-host 有什么区别?

DeepSeek Harness 里,public-url 只是公告浏览器使用的地址,不负责放行;trusted-host 才决定哪些浏览器 authority 被接受。不配 trusted-host,代理再正确也可能每个 API 都返回 403。

DeepSeek Harness 反向代理必须保留 Host 吗?

DeepSeek Harness 里,必须。DeepSeek Harness 的安全栅栏会把收到的 Host 与被接受的 authority 比对,代理改写 Host 会导致请求被拒。代理应原样转发 Host,不要改写成监听器地址。

DeepSeek Harness 配了 public-url 之后,端口就安全了吗?

DeepSeek Harness 里,没有。public-url 和栅栏都不保护监听端口本身,端口仍应限制在可信代理或网络内。TLS 也只保护浏览器到代理这一段,不等于端口自动安全。

相关术语

loopback
loopback 是本机回环地址;DeepSeek Harness 的 Web UI 默认在 loopback 端口提供服务,因此其他机器上的浏览器无法直接访问。— DeepSeek Harness 官方文档 - 在反向代理之后发布 Web UI
public-url
public-url 是 DeepSeek Harness 用来公告浏览器可见地址的启动参数,会归一化为以斜杠结尾,并用于打印 URL、DSH_WEB_URL 与运行时上下文。— DeepSeek Harness 官方文档 - 在反向代理之后发布 Web UI
trusted-host
trusted-host 是 DeepSeek Harness 接受浏览器 authority 的白名单参数;栅栏只放行 loopback、监听器绑定地址与显式点名的 authority。— DeepSeek Harness 官方文档 - 在反向代理之后发布 Web UI
启动令牌
启动令牌是 DeepSeek Harness 打印 URL 中携带的进程凭据,用于把启动 token 换成会话 cookie,不应随意外发。— DeepSeek Harness 官方文档 - 在反向代理之后发布 Web UI

来源