dsh 启动参数怎么配:web 的 --host、--port、--public-url 与 patch 覆盖顺序
dsh 的启动参数分两套:启动器自己的参数写在最前面,--port、--host 这类属于 web 应用,必须落在 profile 之后。 分不清这条边界,参数就会静默失效。
dsh 启动参数:启动器参数与 web 应用 flag
启动器只解析自己的 flag,遇到第一个不认识的 token 就停手,把剩下的原样交给应用。 因此同一条命令里参数的位置决定了它归谁:
| 写法 | 谁解析 | 结果 |
|---|---|---|
dsh --help | 启动器 | 打印启动器帮助 |
dsh --profile web --help | web 应用 | 打印 web 的参数列表,不启动 |
dsh --profile web --port 8080 | web 应用 | 换端口启动 |
dsh --port 8080 | 启动器 | 非预期用法,端口不生效 |
dsh web 是 dsh --profile web 的简写。 简写里的名字必须紧跟 dsh,所以带应用参数时,用完整写法更不容易出错。
分清归属之后,再看 web 应用实际接受哪些 flag。
官方参考列出的 web flag 只有七个,先把名字记准,比背用法有用。 一览:
--host:指定监听的具体本机地址;--port:指定监听端口,默认 3080;--no-open:本次调用不自动打开浏览器;--public-url:对外公告应用根地址;--trusted-host:可重复,声明被信任的浏览器 authority;--tls-cert与--tls-key:成对的证书链与无口令私钥文件,要么都给,要么都不给。
没有列在上面的参数就不是 web 的参数。 想确认当前版本支持什么,直接跑 dsh --profile web --help,这份输出才和你手上的版本一致。
dsh web 换端口:写对位置
换端口的正确写法是 dsh --profile web --port 8080,--port 必须跟在 profile 之后。 步骤:
- 先执行
lsof -i :8080确认目标端口空闲; - 执行
dsh --profile web --port 8080启动; - 看启动输出里的绑定地址,确认端口已变成 8080;
- 用
curl -I http://127.0.0.1:8080验证响应; - 固定使用后,把完整命令写进脚本而不是靠记忆。
端口只影响监听,不影响会话数据。 换端口后历史会话照旧,因为它们存在 DSH_HOME 里,不跟端口绑定。
dsh web 对外访问:--host 的硬限制与反向代理
--host 只接受一个具体的本机地址,不接受通配地址;--host 0.0.0.0 会直接以用法错误退出。 步骤:
- 用
hostname -i或ipconfig getifaddr en0查本机地址; - 输出可能有多条,只挑一条传给
--host; - 启动后用
curl -I http://<该地址>:<端口>自测; - 确认来源网段与防火墙规则,再交给别人访问。
绑定不等于授权。 把地址放开只是让连接能到达服务,认证、Host 与 Origin 校验仍然生效,别把「能连上」当成「可以公开」。
要让外部设备访问,除了绑对地址,通常还要和反向代理配合。
--public-url 负责告诉浏览器「从哪个地址访问我」,--trusted-host 负责授权那个地址,两者不能互相替代。 典型组合:
--public-url写成外部可见的 HTTPS 根地址,可带代理前缀;--trusted-host写成浏览器地址栏里出现的主机名;- 证书交给代理终结时,不要同时传
--tls-cert与--tls-key; - 启动后从外部地址访问一次,确认没有 Host 校验报错。
证书参数必须成对出现。 只给 --tls-cert 或只给 --tls-key 属于无效配置,缺文件、不可读、为空或无效时启动直接失败,且不会退回明文 HTTP。
dsh 启动参数与 patch 谁优先
同一项配置,flag 的值优先于配置行里写的值;而配置行之间,后应用的 patch 层优先。 层序固定为:
- 组合包自带的 patch;
- profile 自己的
cordis.patch.yml; - home 级的
$DSH_HOME/cordis.patch.yml; - 按 argv 顺序传入的各个
--patch。
两个细节最容易踩:patch 是整体替换一行的 config,不做深度合并;flag 的优先级来自配置行里的运行时表达式,被字面量替换后就失效。 所以「我明明加了 --port 却没生效」,先看 patch 有没有把那行改死。
dsh 启动日志、诊断文件与四个常见坑
正常启动看终端输出,启动失败看诊断文件。 关键事实:
- 必需插件激活失败时,终端先列失败插件与堆栈,再列等待中的插件;
- 完整诊断写到
$DSH_HOME/logs/下唯一的startup-<时间戳>-<uuid>.log; - 报告包含 dsh 与 Node 版本、平台、profile、根配置路径与每个未激活插件状态;
- 即使还有句柄未关闭,进程也会以退出码 1 结束;
- 该报告不脱敏,可能含配置或凭据片段,分享前必须自己检查。
默认 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 的启动器只解析自己的参数,遇到第一个不认识的 token 就把后面全部交给 profile 应用。--port 属于 web 应用,写在最前面会被当成应用参数起点,启动器不再解析。正确写法是 dsh --profile web --port 8080。
dsh web 的 --host 只接受一个具体的本机地址,不接受通配地址。--host 0.0.0.0 会以用法错误退出。要让外部设备访问,应改为绑定某个本机网卡地址,或走反向代理、SSH 隧道。
dsh 的 --port 被覆盖,通常是参数位置或 patch 字面量造成的。先确认 --port 是否落在启动器参数边界之后,再检查 profile 的 patch 是否用字面量替换了整个 config。patch 会整体替换一行的 config 值,不会深度合并,因此可能把运行时读取端口的表达式一起删掉。
必需插件启动失败时,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 行为参考
来源
- dsh CLI 行为参考· deepseek-ai
- dsh CLI README· deepseek-ai
- DeepSeek Harness 官方文档· deepseek-harness