DeepSeek Harness 桌面端启动失败：Web authentication failed 根因分析

[qlql765]

一份关于 dsh-auth-* 认证 cookie 无限累积导致本地服务返回 431 Request Header Fields Too Large 的完整记录。

分析日期：2026-10-27　|　被测版本：@deepseek-ai/dsh-desktop 0.2.1-rc.2（Electron 44.7.0 / Node 24.21.0，win32 x64）

---

1. 问题现象

安装第三方插件后重启 DeepSeek Harness，弹出启动失败对话框，应用无法进入工作区：

DeepSeek Harness is unavailable
Web authentication failed

崩溃日志位于 %APPDATA%\@deepseek-ai\dsh-desktop\logs\crash-<timestamp>-host.log：

Error: desktop welcome: Web authentication failed
    at connectDesktopWelcome (file:///D:/DeepSeek%20Harness/resources/app.asar/lib/main.js:8886:31)
    at async Object.start (file:///D:/DeepSeek%20Harness/resources/app.asar/lib/main.js:12195:22)

触发条件与插件无关。本例中插件安装只是让重启次数多了一次，恰好越过了临界点。

---

2. 启动认证链路

主进程（lib/main.js）的启动顺序：

1. host.start() 拉起本地 Host 子进程（dsh-desktop-host），监听 127.0.0.1:<随机端口>
2. Host 通过 IPC 回传就绪信息，其中 ready.url 形如：http://127.0.0.1:64932/?token=<launchToken>
3. authenticateWebHost(ready.url) —— 用 Node 原生 fetch 请求该 URL，期望 303 + Set-Cookie
4. connectDesktopWelcome(ready.url, net.fetch) —— 用 Electron net.fetch（Chromium 网络栈） 再访问同一 URL，跟随 303 跳到 /，靠 Chromium 里已保存的 cookie 完成认证

// lib/main.js:8882 —— 失败点
async function connectDesktopWelcome(authenticatedUrl, send, cookies = ...) {
  const origin = new URL(authenticatedUrl).origin;
  const authenticated = await send(authenticatedUrl, { credentials: "include" });
  await authenticated.body?.cancel();
  if (!authenticated.ok) throw new Error("desktop welcome: Web authentication failed");
  // ...
}

关键：只要响应不是 2xx 就抛这个错，且错误信息不携带状态码，导致日志里看不到真正原因。

注意第 3 步用 Node fetch（无 cookie jar，一定成功），第 4 步用 Chromium（携带全部 cookie，才是失败的那一步）。

---

3. 根因

3.1 cookie 命名方式（源码）

@deepseek-ai/dsh-client-connection 的 browser-auth.js：

const COOKIE_PREFIX = "dsh-auth-";

function cookieName(authority) {
  return COOKIE_PREFIX + encodeBase64Url(createHash("sha256").update(authority).digest());
}

authority 是规范化后的 hostname:port，即 127.0.0.1:64932。

签发逻辑（authorizeIndex）：

const value = encodeCookie({ version: 1, authority, issuedAt, expiresAt }, this.secret);
res.writeHead(303, {
  "set-cookie": sessionCookie(cookieName(authority), value, expiresAt, maxAgeSeconds, secure)
});

sessionCookie 的固定属性：

Max-Age=2592000; Path=/; Expires=<绝对过期时间>; HttpOnly; SameSite=Strict

cookieMaxAgeDays 默认 30 天。文档注释明确说明是刻意把 hostname + port 同时绑进「确定性名称」和「签名 payload」。

3.2 为什么会累积

桌面端用 --port 0 启动 Host，每次启动端口都不同 → authority 不同 → cookie 名的 sha256 不同 → 每次都是一个全新的 cookie 名。

而 HTTP 的 Set-Cookie 只能新增，或者覆盖「同名 + 同 Path + 同 Domain」的那一条。名字不同，新的 303 响应覆盖不到任何一条旧 cookie，也没有任何删除逻辑：

组件	行为
authorizeIndex	只下发一条 set-cookie，无清理代码
isAuthenticated	cookieValue(cookieHeader, 当前 authority 的名字) 精确匹配，只读当前那条
旧 cookie	不被读取、不被覆盖、不被删除，纯粹占位

所以那 70 条旧 cookie 对服务端毫无用处，唯一作用是撑大请求头。

3.3 为什么最终是 431

Host 的 HTTP 服务使用 Node 默认 maxHeaderSize = 16384 字节。实测单条 cookie：

Cookie: dsh-auth-<43字符sha256>=v1.<Base64URL payload>.<Base64URL sig>
        名字 44 + "=" 1 + 值 179 + "; " 2  ≈ 226 字节

累积到约 70 条即触顶。

3.4 为什么不会自愈

Chromium 单域名 cookie 上限是 180 条，超出才驱逐最旧的。而服务端在 约 70 条时就已经因为 16KB 请求头拒绝请求。于是浏览器永远等不到自动清理那一步——必然先撞 431。

---

4. 实测数据

手动以 host 模式启动运行时（不经过 Electron 外壳），用真实 cookie 值构造请求头：

# 手动起 Host（ELECTRON_RUN_AS_NODE 模式，使用 app.asar 内的 host 入口）
ELECTRON_RUN_AS_NODE=1 "DeepSeek Harness.exe" --expose-internals \
  "<...>/resources/app.asar/dsh/node_modules/@deepseek-ai/dsh-desktop-host/lib/index.js" \
  "<...>/resources/app.asar/dsh" \
  "C:/Users/<user>/.dsh/profiles/desktop" \
  "<...>/resources/runtime/primary-runtime"

# 输出：dsh web: http://127.0.0.1:64932/?token=<launchToken>

逐个叠加 cookie 条数测试 GET /：

请求头中的旧 cookie 条数	Cookie 头大小	响应
60	13,906 B	200 OK
67	15,502 B	200 OK
69	15,958 B	200 OK
70	16,186 B	200 OK（临界内）
71	16,414 B	431 Request Header Fields Too Large

其他实测结论：

• GET / 无有效 cookie → 401 dsh web authentication required
• GET / 带有效 cookie → 200
• GET /?token=<launchToken> → 303 + set-cookie（同一 token 可重复使用，不是一次性）
• 通过系统代理或本地代理访问均正常，与代理无关

现场数据吻合

• cookie 库中 dsh-auth-* 共 71 条，全部 host_key='127.0.0.1'，最早 10-18，最后一条写入时间 01:09:02 UTC
• 崩溃记录：01:09:05、01:09:43、01:09:51、01:10:20 —— 第一次崩溃正好在最后一条 cookie 写入后 3 秒（第 70 条时刚好通过并写入第 71 条，随后跳转被 431 拒绝）
• 后续 3 次启动再无新 cookie 写入（第一个请求就已超限，连 303 都拿不到）

---

5. 影响

• 桌面端启动直接失败，且无法通过重启自愈（每次重启仍在阈值之上，可能还会多写入一条，越陷越深）
• 报错信息不含 HTTP 状态码，用户与技术支持都难以定位
• 触发时间取决于使用频率：约 70 ÷ 每日启动次数 天后必然发作（本例 9 天积累 71 条）
• 使用固定端口的 dsh CLI 模式几乎不受影响——这是该缺陷只在桌面端爆出的原因

---

6. 临时处置（用户侧）

前提：完全退出应用（Chromium 运行时会独占 cookie 库，无法写入）。

1. 备份 %APPDATA%\@deepseek-ai\dsh-desktop\Network\Cookies
2. 删除该库中 host_key = '127.0.0.1' 的记录
3. 重新启动应用

import sqlite3, shutil, os
db = os.path.expandvars(r'%APPDATA%\@deepseek-ai\dsh-desktop\Network\Cookies')
shutil.copy2(db, db + '.bak')            # 先备份
con = sqlite3.connect(db)
con.execute("delete from cookies where host_key='127.0.0.1'")
con.commit(); con.execute("vacuum"); con.commit()
con.close()

注意：

• Host 的 cookie 只是「本地端口认证凭据」，与账号登录态无关（账号凭证在 $DSH_HOME/.credentials.yaml），清掉不影响登录
• 清理后每次启动仍会新增一条，约 1~2 周后复发，需周期性重复

---

7. 建议的正式修复

方案 A（推荐）：cookie 名固定，authority 移入签名 payload

// 现状：名字绑 authority → 每次端口变化产生新 cookie
cookieName(authority) = "dsh-auth-" + base64url(sha256(authority))

// 建议：固定名字，authority 仍保留在 HMAC 签名内校验
Set-Cookie: dsh-auth=<v1.payload(含authority).sig>; Path=/; HttpOnly; SameSite=Strict

• 同名即覆盖，永远只有 1 条，彻底消除累积
• 安全性不降级：authority 依然在签名 payload 中，isAuthenticated 继续校验 payload.authority === 当前 authority
• 兼容旧版本：读取时可同时尝试「新固定名」与「旧 hash 名」，并对旧名下发的 Max-Age=0 做清理

方案 B：改为会话 cookie

去掉 Max-Age / Expires，随 Chromium 关闭失效。可与其他方案叠加，作为兜底。

方案 C：签发时主动回收

服务端在 303 响应中遍历请求头 Cookie 里所有 dsh-auth-* 名字，对 ≠ 当前 authority 的逐个下发删除（一个响应可携带多条 Set-Cookie）：

Set-Cookie: dsh-auth-<旧hash>=; Max-Age=0; Path=/

可单独使用，也可作为兼容层，配合方案 A 使用。

方案 D（附带）：改进错误可观测性

connectDesktopWelcome 抛错时携带 response.status 与 response.headers.get('content-type')，例如：

desktop welcome: Web authentication failed (HTTP 431)

当前实现只判断 !authenticated.ok，把 431/401/500 全部压成同一句话，是这次排查成本高的主要原因。

---

8. 复现步骤（供提 issue 使用）

1. 全新安装桌面端，反复启动/退出（或直接向 Network/Cookies 注入 71 条 host_key='127.0.0.1' 的 dsh-auth-* 记录）
2. 观察 Network/Cookies 中 dsh-auth-* 条数随启动次数线性增长，且都是不同名字
3. 达到 70 条左右后启动 → 弹「Web authentication failed」
4. 崩溃日志 desktop welcome: Web authentication failed（lib/main.js:8886）
5. 清理 127.0.0.1 的 cookie 后立即恢复

---

9. 一句话结论

cookieName() 把 hostname+port 的 sha256 拼进 cookie 名，而桌面端每次用随机端口启动、cookie 有效期 30 天、且无任何回收逻辑——三者叠加使每个「端口-进程」组合永久残留一条约 226 字节的 cookie，约 70 条后击穿 Node 的 16KB 请求头上限，Host 返回 431，主进程将其报为 Web authentication failed。

属于设计层面的组合缺陷（不是用户操作问题，也与第三方插件无关）。修复成本极低：把 authority 从 cookie 名移入签名 payload 即可，安全性不变。