DeepSeek Harness 设置页面 403 报错排查：一层层剥开 API 信任机制

前言

最近在远程 Linux 服务器上部署了 DeepSeek Harness（一个基于 Node.js 的 AI Agent 平台），项目整体运行正常，但一打开设置页面就报错，模型配置和通用设置都无法使用。本文完整记录这次的排查过程：从最直观的 nginx 反代配置，一直追到应用源码里的安全信任机制，最终一行代码修复问题。

一、问题现象

服务通过 nginx 反向代理对外提供访问（117.72.91.40:8080 → 127.0.0.1:3080）。打开设置页面后，模型页显示：

加载提供方目录失败: transport failure for /api/settings.describe: HTTP 403

通用设置页同样报错。但奇怪的是，页面本身能打开，会话功能也正常，只有设置相关的接口返回 403。

二、第一层排查：nginx 反代

403 是"无权限"，第一反应是反代配置问题。检查 nginx 配置后发现一个明显的问题——Host 头被硬编码了：

location / {
    proxy_pass http://127.0.0.1:3080;
    proxy_set_header Host 127.0.0.1:3080;
    ...
}

应用接收到请求后拿到的 Host 是 127.0.0.1:3080，而不是浏览器实际访问的 117.72.91.40:8080。把它改为透传原始 Host：

proxy_set_header Host $http_host;

修改并 reload 后，部分接口确实恢复了，但 settings.describe 等设置接口依然 403。

三、第二层排查：SSH 隧道验证

为了确认应用本身是否正常，我在本地建立 SSH 隧道直连应用的 loopback 端口：

ssh -f -N -L 13080:127.0.0.1:3080 root@117.72.91.40

通过 localhost:13080 访问，所有接口全部 200，数据正常。这说明：应用逻辑没问题，问题出在"请求从哪里来"。

四、第三层排查：源码里的信任围栏

沿着 403 的关键词去源码里找，在 packages/client/connection/src/index.ts 中发现了关键逻辑：

const PRIVILEGED_METHODS = new Set([
  'agentPreset.read', 'agentPreset.copy', 'agentPreset.openDocument', 'agentPreset.remove',
  'host.pickDirectory', 'host.openPath',
  'settings.describe', 'settings.openDocument', 'settings.update', 'settings.replace', 'settings.mutate',
  'credentials.describe', 'credentials.set', 'credentials.unset',
  'llm.discoverModels',
])

这些方法被称为"特权方法"——设置读写、凭据管理、发现模型等敏感操作。请求分发时的检查代码是：

if (method !== undefined
    && PRIVILEGED_METHODS.has(method)
    && !isTrustedApiRequest(request, [])) {
  return new Response('forbidden', { status: 403 })
}

注意第二个参数传的是空数组 []。isTrustedApiRequest 的语义是"Host 是 loopback 或位于可信列表则放行"。传空数组意味着：无论部署时通过 --trusted-host 117.72.91.40:8080 配置了什么，特权方法都只允许 loopback 访问。

这是有意的安全设计：trustedHosts 只是防 DNS rebinding 的围栏，不是身份认证。在真正的认证层出现之前，配置面（settings）和凭据面（credentials）只允许本机回环访问，防止局域网甚至公网上的匿名调用者读取配置、探测凭据。

但问题在于：这个部署场景下，只有 nginx 一条对外通路，远程访问是刚需。SSH 隧道虽然能用，但每次都要手动开隧道，显然不是长期方案。

五、解决方案

看清机制后，修复就很简单了——让特权方法的信任检查复用外层路由已经使用的 trustedHosts 列表，而不是传空数组：

// 修改前
&& !isTrustedApiRequest(request, [])) {

// 修改后
&& !isTrustedApiRequest(request, trustedHosts)) {

外层路由的围栏仍然生效（非 loopback 且不在 trustedHosts 内的请求照样 403），只是特权方法不再额外加严到 loopback-only。配合已有的 --trusted-host 117.72.91.40:8080 启动参数，nginx 转发的请求即可通过全部检查。

六、验证

项目通过 tsx 直接运行 TypeScript 源码，改完无需重新构建，重启进程即可：

kill <pid>
nohup node --import tsx/esm apps/cli/src/bin.ts web --trusted-host 117.72.91.40:8080 > /tmp/dsh.log 2>&1 &

验证结果：

curl -X POST http://117.72.91.40:8080/api/settings.describe → HTTP 200，返回完整配置

浏览器打开设置页面，模型页和通用设置页均正常加载，可以正常编辑保存，问题彻底解决。

七、总结与思考

这次排查最深的体会是：报错信息只是起点，真正的答案在源码里。整个过程是从表象到本质的层层递进——nginx 的 Host 头是表象之一，但修复它之后问题仍在；SSH 隧道的"全通"排除了应用故障；最终源码里的空数组参数才揭示了真正的设计意图。

另外也值得反思安全与易用性的权衡：框架作者把特权方法钉死在 loopback 上的初衷完全正确，但对于"单机部署 + nginx 反代"这种常见场景，缺少一个显式的配置开关。修改后的行为相当于把特权面交给了 trustedHosts 配置，部署者需要自行保证该列表的可信度（例如只放内网域名、配合防火墙限制 8080 端口来源）。

如果你的 DeepSeek Harness 也遇到同样问题，希望这篇文章能帮你少走弯路。

关键词

DeepSeek Harness、403 报错、nginx 反向代理、SSH 隧道、信任机制、PRIVILEGED_METHODS、trustedHosts、Node.js、源码排查