# Agent Note: 显式指定 Web 绑定地址

Status: implemented
Archived: 2026-09-04

[English](2026-07-22-web-bind-address.md) | 中文

## 问题

Web 应用可以用 Host 用户的 authority 运行命令。同机使用只需要 loopback 可达性；CLI 若提供全接口模式，就会在没有 TLS 或明确代理约定时暗示支持网络部署。

HTTP 承载层还把绑定地址隐藏在 `startWebServer()` 内部，导致其他壳层无法在包边界明确表达自己的网络策略。

## 决策

`dsh web` 绑定 `127.0.0.1` 并拒绝 `--host 0.0.0.0`；CLI 不开放网络模式。进程令牌与浏览器 cookie 认证不扩大该部署约定（[决策](../architecture/2026-08-24-browser-token-authentication.zh.md)）。

`WebServer` 仍要求 `host: '127.0.0.1' | '0.0.0.0'`，并在没有 fallback 的情况下传给 `node:http`。通用承载层让自定义组合策略显式留在包接口上；产品 CLI 持有更严格的 loopback 选择。

## 曾考虑的替代方案

**保留以 `0.0.0.0` 作为默认值。** 不予采纳，因为普通的同机使用不需要在全网范围内可达，也不应隐式获得这种可达性。

**使用布尔型暴露标志。** 不予采纳，因为 `--host 0.0.0.0` 直接说明最终的套接字行为，并与底层服务器选项一致，无需再引入第二套术语。

**保留显式 `--host 0.0.0.0` 模式。** 不予采纳，因为仅有认证并不能为工具型 Host 提供 TLS、转发语义或受支持的远程部署约定。

**在 `startWebServer()` 内设置默认值。** 不予采纳，因为承载层可能由多种壳层调用，没有依据替它们选择部署策略。要求传入 `host`，可使每次装配调用都明确作出这一选择。

## 后果

`dsh web` 的本地启动仍可通过 `http://127.0.0.1:3080` 访问。CLI 不开放自定义接口、全接口或 IPv6 模式；自定义 WebServer 组合保留承载层的两个地址选择并自行承担全部后果。服务器测试固定两个承载值都会进入 Node listen，CLI 测试则固定全接口 flag 被拒绝。