ChatGPTClaudeGrok / X / CursorGemini

dsh 启动参数怎么配:web 的 --host、--port、--public-url 与 patch 覆盖顺序

配置与使用发布于 2026-11-02作者: DeepSeek Plugin 插件市场
dsh 启动启动参数dsh web端口反向代理
dsh 启动器只解析自己的参数,其余全部交给 web 应用。本文拆开 --port、--host、--public-url、--trusted-host、--no-open 的用法,并说明参数与三层 patch 谁优先。

dsh 的启动参数分两套:启动器自己的参数写在最前面,--port、--host 这类属于 web 应用,必须落在 profile 之后。 分不清这条边界,参数就会静默失效。

dsh 启动参数:启动器参数与 web 应用 flag

启动器只解析自己的 flag,遇到第一个不认识的 token 就停手,把剩下的原样交给应用。 因此同一条命令里参数的位置决定了它归谁:

写法谁解析结果
dsh --help启动器打印启动器帮助
dsh --profile web --helpweb 应用打印 web 的参数列表,不启动
dsh --profile web --port 8080web 应用换端口启动
dsh --port 8080启动器非预期用法,端口不生效

dsh web 是 dsh --profile web 的简写。 简写里的名字必须紧跟 dsh,所以带应用参数时,用完整写法更不容易出错。

分清归属之后,再看 web 应用实际接受哪些 flag。

官方参考列出的 web flag 只有七个,先把名字记准,比背用法有用。 一览:

  1. --host:指定监听的具体本机地址;
  2. --port:指定监听端口,默认 3080;
  3. --no-open:本次调用不自动打开浏览器;
  4. --public-url:对外公告应用根地址;
  5. --trusted-host:可重复,声明被信任的浏览器 authority;
  6. --tls-cert 与 --tls-key:成对的证书链与无口令私钥文件,要么都给,要么都不给。

没有列在上面的参数就不是 web 的参数。 想确认当前版本支持什么,直接跑 dsh --profile web --help,这份输出才和你手上的版本一致。

dsh web 换端口:写对位置

换端口的正确写法是 dsh --profile web --port 8080,--port 必须跟在 profile 之后。 步骤:

  1. 先执行 lsof -i :8080 确认目标端口空闲;
  2. 执行 dsh --profile web --port 8080 启动;
  3. 看启动输出里的绑定地址,确认端口已变成 8080;
  4. 用 curl -I http://127.0.0.1:8080 验证响应;
  5. 固定使用后,把完整命令写进脚本而不是靠记忆。

端口只影响监听,不影响会话数据。 换端口后历史会话照旧,因为它们存在 DSH_HOME 里,不跟端口绑定。

dsh web 对外访问:--host 的硬限制与反向代理

--host 只接受一个具体的本机地址,不接受通配地址;--host 0.0.0.0 会直接以用法错误退出。 步骤:

  1. 用 hostname -i 或 ipconfig getifaddr en0 查本机地址;
  2. 输出可能有多条,只挑一条传给 --host;
  3. 启动后用 curl -I http://<该地址>:<端口> 自测;
  4. 确认来源网段与防火墙规则,再交给别人访问。

绑定不等于授权。 把地址放开只是让连接能到达服务,认证、Host 与 Origin 校验仍然生效,别把「能连上」当成「可以公开」。

要让外部设备访问,除了绑对地址,通常还要和反向代理配合。

--public-url 负责告诉浏览器「从哪个地址访问我」,--trusted-host 负责授权那个地址,两者不能互相替代。 典型组合:

  1. --public-url 写成外部可见的 HTTPS 根地址,可带代理前缀;
  2. --trusted-host 写成浏览器地址栏里出现的主机名;
  3. 证书交给代理终结时,不要同时传 --tls-cert 与 --tls-key;
  4. 启动后从外部地址访问一次,确认没有 Host 校验报错。

证书参数必须成对出现。 只给 --tls-cert 或只给 --tls-key 属于无效配置,缺文件、不可读、为空或无效时启动直接失败,且不会退回明文 HTTP。

dsh 启动参数与 patch 谁优先

同一项配置,flag 的值优先于配置行里写的值;而配置行之间,后应用的 patch 层优先。 层序固定为:

  1. 组合包自带的 patch;
  2. profile 自己的 cordis.patch.yml;
  3. home 级的 $DSH_HOME/cordis.patch.yml;
  4. 按 argv 顺序传入的各个 --patch。

两个细节最容易踩:patch 是整体替换一行的 config,不做深度合并;flag 的优先级来自配置行里的运行时表达式,被字面量替换后就失效。 所以「我明明加了 --port 却没生效」,先看 patch 有没有把那行改死。

dsh 启动日志、诊断文件与四个常见坑

正常启动看终端输出,启动失败看诊断文件。 关键事实:

  1. 必需插件激活失败时,终端先列失败插件与堆栈,再列等待中的插件;
  2. 完整诊断写到 $DSH_HOME/logs/ 下唯一的 startup-<时间戳>-<uuid>.log;
  3. 报告包含 dsh 与 Node 版本、平台、profile、根配置路径与每个未激活插件状态;
  4. 即使还有句柄未关闭,进程也会以退出码 1 结束;
  5. 该报告不脱敏,可能含配置或凭据片段,分享前必须自己检查。

默认 DSH_HOME 是 ~/.dsh。 改过 DSH_HOME 的话,日志跟着走,别去旧目录找。

日志能定位个案,下面四个坑则覆盖大多数参数误用。

参数类问题几乎都出在位置、通配地址、patch 覆盖与证书成对性上。 对照检查:

现象原因处理
--port 不生效写在启动器参数边界之前移到 --profile web 之后
启动报用法错误--host 传了 0.0.0.0换成具体本机地址
代理后访问被拒只配了 public-url补 --trusted-host
HTTPS 起不来证书或私钥只给了一个补齐成对参数

每次只改一个变量再复测。 同时改端口和 host,出问题时无法判断是哪一项被拒。

dsh 下一步

先确认参数位置,再谈监听范围与代理。 想看启动失败怎么分层排查,读 dsh 启动失败决策树;想看局域网访问的三种方案,读 dsh web 局域网访问;想看命令速查,读 dsh 命令速查表;想自定义 profile,读 配置自定义 profile。

来源:dsh CLI 行为参考、dsh CLI README、DeepSeek Harness 官方文档

ChatGPTClaudeGrok / X / CursorGemini

常见问题

为什么 dsh --port 8080 不生效,必须写在 --profile web 后面?

dsh 的启动器只解析自己的参数,遇到第一个不认识的 token 就把后面全部交给 profile 应用。--port 属于 web 应用,写在最前面会被当成应用参数起点,启动器不再解析。正确写法是 dsh --profile web --port 8080。

想把 dsh web 绑到 0.0.0.0 让手机访问,为什么直接报用法错误?

dsh web 的 --host 只接受一个具体的本机地址,不接受通配地址。--host 0.0.0.0 会以用法错误退出。要让外部设备访问,应改为绑定某个本机网卡地址,或走反向代理、SSH 隧道。

命令行加了 --port,但启动后还是 3080,是哪个地方覆盖了它?

dsh 的 --port 被覆盖,通常是参数位置或 patch 字面量造成的。先确认 --port 是否落在启动器参数边界之后,再检查 profile 的 patch 是否用字面量替换了整个 config。patch 会整体替换一行的 config 值,不会深度合并,因此可能把运行时读取端口的表达式一起删掉。

dsh web 启动失败时日志文件在哪里,为什么终端只给出一行提示?

必需插件启动失败时,CLI 会先在终端输出失败插件与堆栈,并把完整诊断写到 $DSH_HOME/logs/ 下唯一的 startup-<时间戳>-<uuid>.log,然后以退出码 1 结束。注意该报告不做脱敏,分享前先检查内容。

相关术语

启动器参数
启动器参数是 `dsh` 自己解析的 flag,必须写在命令开头,用来选择 profile 或执行插件管理、配置 dump 等模式。— dsh CLI 行为参考
应用参数
应用参数是启动器交给 profile 应用的 flag,从第一个无法识别的 token 开始,由该 profile 的插件自行解析。— dsh CLI 行为参考
patch 层
patch 层是叠加在配置树上的覆盖层,按组合包、profile、home、`--patch` 的顺序应用,后应用的层优先。— dsh CLI 行为参考
public-url
public-url 是 `dsh web` 对外公告的应用根地址,可带反向代理前缀,但不授予信任,浏览器可见的域名仍要写进 `--trusted-host`。— dsh CLI 行为参考

来源