dsh-oauth-remote
v0.1.0
Published
GitHub OAuth gate for public remote access to the DeepSeek Harness web GUI. Provides /oauth login/callback/authz endpoints; pair with an Nginx auth_request location to protect the whole site.
Maintainers
Readme
dsh-oauth-remote — GitHub OAuth 认证门 + Nginx auth_request 公网远程访问
DSH web GUI 的公网访问认证层。因为 DSH 内部放不了全站认证(见下),由 Nginx auth_request 认证门 + 本插件 /oauth/* 端点组成完整方案。
安装
dsh plugin --profile web add dsh-oauth-remote1. 创建 GitHub OAuth App
GitHub → Settings → Developer settings → OAuth Apps → New OAuth App:
- Homepage URL:
https://<你的域名> - Authorization callback URL:
https://<你的域名>/oauth/callback(必须与注册值完全一致)
拿到 Client ID / Client Secret。
2. 环境变量(密钥只走环境,缺失 fail-fast 拒启动)
| 变量 | 说明 |
|---|---|
| GITHUB_CLIENT_ID | OAuth App client id |
| GITHUB_CLIENT_SECRET | OAuth App client secret |
| DSH_OAUTH_SECRET | 会话 cookie 的 HMAC 签名密钥(≥32 字节随机值,openssl rand -hex 32) |
systemd 部署用 drop-in(chmod 600,改完 daemon-reload + restart):
# /etc/systemd/system/dsh-web.service.d/oauth.conf
[Service]
Environment=GITHUB_CLIENT_ID=xxx
Environment=GITHUB_CLIENT_SECRET=xxx
Environment=DSH_OAUTH_SECRET=xxx3. 行注册(cordis.patch.yml)
- id: oauth-remote
config:
allowedUsers: [你的GitHub用户名] # 允许登录的白名单,大小写不敏感,必填
publicBaseUrl: https://<你的域名> # 无尾斜杠,必填
# 可选:cookieName / sessionTtlMs / rateLimitMax / rateLimitWindowMs4. Nginx(完整示例,含 Host 改写与设置持久化 shim)
# map 放 http 级
map $http_upgrade $connection_upgrade { default upgrade; '' close; }
server {
listen 443 ssl;
server_name <你的域名>;
# ssl_certificate ...; ssl_certificate_key ...;
# dsh 站点必须放大限流(首屏几十个 bundle 请求 × 2 的 authz 子请求;
# 1.24 没有 limit_req off,只能覆盖 burst)
limit_req zone=general burst=200 nodelay;
# ── auth_request 判定端点:internal 禁公网直探测 ──
location = /oauth/authz {
internal;
proxy_pass http://127.0.0.1:3080;
proxy_pass_request_body off;
proxy_set_header Content-Length "";
}
location @oauth_login { return 302 https://$host/oauth/login; }
# ── OAuth 业务端点直通(不能再挂 auth_request,否则死循环)──
location = /oauth/login { proxy_pass http://127.0.0.1:3080; }
location = /oauth/start { proxy_pass http://127.0.0.1:3080; }
location = /oauth/callback { proxy_pass http://127.0.0.1:3080; }
location = /oauth/logout { proxy_pass http://127.0.0.1:3080; }
location = /oauth/whoami { proxy_pass http://127.0.0.1:3080; }
location = /manifest.webmanifest { proxy_pass http://127.0.0.1:3080; } # 不过门,防未登录时控制台报错
# ── 设置持久化 shim(公网改设置刷新即丢的问题,见下文「客户端信任 shim」)──
location = /_ma/trust.js {
auth_request /oauth/authz;
error_page 401 = @oauth_login;
alias /etc/nginx/shims/ma-trust.js; # 源文件在本仓库 shims/
default_type application/javascript;
add_header Cache-Control "no-store";
}
# ── 其余一切:先过认证门,再反代 ──
location / {
auth_request /oauth/authz;
error_page 401 = @oauth_login;
proxy_pass http://127.0.0.1:3080;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $connection_upgrade;
# Host 改写过 browser-trust fence(为什么见踩坑记录,两行都必需)
proxy_set_header Host 127.0.0.1:3080;
proxy_set_header Origin "";
# sub_filter 注入 shim(需明文,禁上游 gzip)
proxy_set_header Accept-Encoding "";
sub_filter '<script>window.__DSH_BOOT__' '<script src="/_ma/trust.js"></script><script>window.__DSH_BOOT__';
sub_filter_once on;
}
}部署 shim:cp shims/ma-trust.js /etc/nginx/shims/ && chmod 644 /etc/nginx/shims/ma-trust.js(nginx worker 要可读,600 会 403),然后 systemctl reload nginx。
为什么认证不能放 DSH 内部
rc.6 的 webServer 没有全局中间件钩子,也没有 dsh-web-ui 依赖的 api/gate 事件(当前 DSH 不触发)。所以全站认证必须前置到 Nginx。
架构
公网 → Nginx 443 (auth_request /oauth/authz)
→ 未认证: 302 → /oauth/login → GitHub OAuth → 设 HttpOnly cookie
→ 已认证: 放行 → 127.0.0.1:3080 (DSH, 绑定不变)插件提供端点:/oauth/login|start|callback|authz|logout|whoami。
要点:
- Nginx
location = /oauth/authz { internal; }——internal禁止公网直探测端点,只有 auth_request 子请求能打 /oauth/login|start|callback|logout|whoami五个 location 直通 DSH,不能再挂 auth_request(否则死循环)- 会话 cookie 用 HMAC-SHA256 签名自包含 token(
base64url(json).base64url(hmac)),无服务端状态,重启不掉线;secret 从DSH_OAUTH_SECRET读 - 密钥(client_id/secret/signing key)全部走 systemd drop-in 环境变量(
/etc/systemd/system/dsh-web.service.d/oauth.conf,chmod 600),缺任一 fail-fast 拒启动 - 登录/回调路由必须限流(按 X-Forwarded-For 取客户端 IP,Nginx 会设置)
- GitHub 回调地址必须与 OAuth App 注册的完全一致:
https://dsh.example.com/oauth/callback
踩坑记录
schemastery
- 3.18 的
z.string()没有.url()方法 → 用.pattern(/^https?:\/\/[^/]+/)
systemd / 密钥
- 环境变量注入后必须
systemctl daemon-reload再 restart - 测试签名 cookie 时从 drop-in 取 secret,
cut -d= -f2会取到变量名(Environment=DSH_OAUTH_SECRET=xxx的第二段)→ 用sed 's/.*DSH_OAUTH_SECRET=//' - 插件包同步:改
lib/index.js后要cp到/root/.dsh/profiles/web/node_modules/dsh-oauth-remote/lib/再重启
Nginx 限流
- 全局限流会打爆页面加载:
nginx.conf有limit_req zone=general burst=20(所有站点继承)。DSH 页面首屏并发几十个 bundle 请求 + 每个请求的 authz 子请求,burst=20 秒满 → 429 → 浏览器报failed to import loader entry ... failed to load。dsh 站点必须覆盖:limit_req zone=general burst=200 nodelay;(此 nginx 1.24 不支持limit_req off) - auth_request 子请求也计入 limit_req(子请求走 internal location 继承 server 级限流),放大 burst 时按「资源数 × 2」估量
trustedHosts 与特权方法 403(已由 Host 改写方案解决)
- 公网反代必须过 browser-trust fence:Nginx 把 Host 头设为
dsh.example.com,connection 的 fence 只认 loopback /trustedHosts,不信任该域名会对所有/api请求回 403(host.describe首当其冲,页面卡加载)。曾用cordis.patch.yml配connection.trustedHosts: [dsh.example.com]解决——⚠️ 行 id 是connection(不是导出名client-connection)。 trustedHosts必须写静态数组:dsh-better-sidebar 的/sidebarfence 会从 loader 原始行读该值,!!js表达式在原始行里是未求值对象,侧栏.some()直接抛 TypeError(表现为/sidebar/*空 body 400、/sidebar/ws/*502)。- dsh-better-sidebar v0.11.0 的
trustedHostsOf有 bug(已提 issueomdsh-dev/DSH-better-sidebar#66):entry.options.name === 'connection'永远匹配不上(行 name 是包名)。当时本地 patch 判等改为id === 'connection' || name === '@deepseek-ai/dsh-client-connection'——Host 改写后此 patch 已不需要,恢复官方版(pnpm remove && pnpm add,注意pnpm add对已装同版本不重新解包,必须先 remove)。 - ~~特权方法仍 403(曾误判为 rc.6 设计限制)~~ 已解决(2026-08-15)——Host 改写方案:
- 误判纠正:当时结论「OAuth 门管不住 PRIVILEGED_METHODS、远程改设置必须 SSH 隧道」是错的。
dsh-client-connection源码 + 实测:fence 判定的是 Host 头,不是来源 IP。PRIVILEGED_METHODS(settings.*/credentials.*/agentPreset.read/host.pickDirectory/llm.discoverModels等,路径形态/api/<method>)的检查就是isTrustedApiRequest(request, [])空信任表 = Host 头为 loopback(127.x/localhost/[::1])即放行,Host 是反代一行配置就能改写的。 - 修复(Nginx
location /,两行):proxy_set_header Host 127.0.0.1:3080; # 原为 $host proxy_set_header Origin ""; # 新增 - 删 Origin 是必须的:fence 还校验
Origin.host === Host,只改 Host 不删 Origin,浏览器 same-origin POST(/api RPC)和 WebSocket 握手(带Origin: https://dsh.example.com)会全部 403(实测确认)。 - 实测结果(公网带认证 cookie):
/api/settings.describe200、/api/credentials.describe200、/api/events.muxWS 101、未认证依旧 302 登录页(门未松)。 - 为什么 Host 改写不会绕过认证:改写发生在
location /的proxy_pass,而该 location 第一行就是auth_request——未认证请求在 401→302 阶段就被打回登录页,根本到不了 Host 改写;DSH 进程只绑127.0.0.1:3080,公网物理上没有绕过 Nginx 的直连路径。已实测:未认证打特权方法/凭据/WS 全 302,伪造 Host 头直连服务器 IP 也 302。 - 安全语义:认证边界完全落在 Nginx auth_request OAuth 门(DSH 源码注明 fence 不是 auth 层,是 DNS-rebinding/cross-site 防线);CSRF 由会话 cookie
SameSite=Lax承担。语义上等价于 Cloudflare Access / forward-auth 的「认证在门前」模式。 - 清理:
connection.trustedHosts与 sidebar patch 在 Host 改写后均为冗余,已于 2026-08-15 删除/恢复官方版。回退 Host 改写(恢复proxy_set_header Host $host)时需重新配 trustedHosts + sidebar patch。
- 误判纠正:当时结论「OAuth 门管不住 PRIVILEGED_METHODS、远程改设置必须 SSH 隧道」是错的。
- 配置备份:
/etc/nginx/backup/dsh.example.com.*.conf(sites-enabled 里不能放 .bak,会被 include)。
其它
manifest.webmanifest未登录时返回登录页 HTML → 浏览器控制台报Manifest: Line 1 ... Syntax error。已修:Nginx 加location = /manifest.webmanifest直通(与/oauth/*同列,不过认证门)——manifest 只含应用名/图标/主题色,无敏感信息,直通后未登录/已登录都返回真 JSON。
客户端信任 shim(shims/ma-trust.js,2026-08-15)
问题:Host 改写解决的是服务端 fence;客户端还有一层自我审查。rc.6 的 dsh-client-connection 按页面地址栏 hostname(非 Host 头)判定 connection.isLoopback,公网域名 → false → dsh-client-ui-settings 的 SettingsScopeController 构造时降级 "memory" 持久化(enqueue 直接 return Promise.resolve(),settings.mutate 根本不发)。表现为:通用设置页(繁忙回车/主题/语言)在公网改完当场生效,刷新即丢(loopback 直连正常,故双端表现不一致)。源码注释明说这是配合「settings RPC 仅限 loopback」旧设计的保守降级——本站 Host 侧 fence 已由 Host 改写解决,这层降级已无意义。
方案:Nginx sub_filter 在内联 __DSH_BOOT__ script 前注入经典 <script src="/_ma/trust.js">(经典脚本解析即执行,deferred 模块 bundle 之前必先跑):
location = /_ma/trust.js {
auth_request /oauth/authz; # shim 不过认证门不暴露
error_page 401 = @oauth_login;
alias /etc/nginx/shims/ma-trust.js; # 源头在仓库 dsh-oauth-remote/shims/
default_type application/javascript;
add_header Cache-Control "no-store";
}
# location / 内:
proxy_set_header Accept-Encoding ""; # 禁上游 gzip, 否则 sub_filter 匹配不到明文
sub_filter '<script>window.__DSH_BOOT__' '<script src="/_ma/trust.js"></script><script>window.__DSH_BOOT__';
sub_filter_once on;shim 原理:window.__ModuleLoader__ 此时还不存在(由后面的 module bundle 定义),用 Object.defineProperty setter 陷阱在其落地时包一层 .load,劫持 @deepseek-ai/dsh-client-connection 的 factory 返回值、包装其 apply——原 apply 同步以 ctx.provide("connection", handle) 收尾,包装器在 apply 返回后立刻把 handle.isLoopback 用 getter 钉成 true。后续消费模块(ui-theme/ui-locale/ui-conversation)按 inject 依赖序更晚 apply,settingsScope.bind() 读到 isLoopback === true → 走 "host" 持久化。
为什么不用动态 Cordis 插件:bind() 在各消费方 apply 时一次性读值定死 persistence,动态插件加载在所有内置模块之后,补丁落地时 scope 早已建成 memory 模式,race 必输。必须抢在 connection apply 之后、消费者 apply 之前——只有页面级注入能做到。
实测(公网手机端到端):[ma-trust] loader wrapped + isLoopback forced 双日志命中;繁忙回车 Steer→Queue → settings.mutate 200 → 磁盘 busyEnter: queue → 刷新后 UI 仍 Queue → 切回 Steer → 磁盘 steer。loopback 直连不经 Nginx 无 shim,isLoopback 原生 true,不受影响。
部署:改 shim 后 cp dsh-oauth-remote/shims/ma-trust.js /etc/nginx/shims/ && chmod 644 && systemctl reload nginx(注意 nginx worker 读 /etc/nginx/shims/ 下文件需 644,600 403)。
