SQLite 登录网关 qw2500279440/dsh-auth-sqlite

dsh-auth-sqlite

dsh-auth-sqlite 1.0.0 是 DeepSeek Harness Web profile 的 SQLite 登录认证与资源归属 bundle。它把原 Web 服务隐藏到随机回环端口，并在原 --port 前启动认证网关，保护页面、HTTP API、Session 导出和 WebSocket。

本版本面向受控内网的可信用户。它承诺登录认证、Workspace 归属和对话数据隔离，但不同用户仍共享同一个 DSH 进程与操作系统账号；Shell 和文件工具不能提供宿主文件机密性隔离。互不信任用户或公网服务必须改用每用户独立进程、容器或虚拟机。

要求

- DeepSeek Harness 0.1.0-rc.6 或 0.1.0-rc.7。
- Node.js ^22.19.0 || >=24.0.0。
- web profile；bundle patch 依赖该 profile 的稳定行 ID。
- Unix 宿主使用专用非 root 服务账号。只有隔离容器或测试环境可以显式使用 --auth-allow-root。

本地开发安装

在 DeepSeek Harness 根目录执行：

pnpm --dir project/dsh-auth-sqlite install
pnpm --dir project/dsh-auth-sqlite run build
pnpm dsh plugin --profile web add ./project/dsh-auth-sqlite

本地目录以 link: 安装。修改源码后只需重新构建：

pnpm --dir project/dsh-auth-sqlite run build

卸载命令：

pnpm dsh plugin --profile web remove dsh-auth-sqlite

打包安装

先在插件目录生成 tarball：

cd project/dsh-auth-sqlite
pnpm run build
pnpm pack

服务器通过 npm 安装的 dsh 直接管理 $DSH_HOME/profiles/web，不需要在 tarball 所在目录创建 package.json：

export DSH_HOME=/srv/deepseek-harness/.dsh
dsh plugin --profile web add /srv/packages/dsh-auth-sqlite-1.0.0.tgz

从 Harness 源码运行时使用 pnpm dsh plugin ...。安装或升级后重启 Web 服务，并确认 patch 已组合：

dsh --profile web --dump-config > /tmp/dsh-web-config.yml
grep -nE "auth-sqlite|web-startup|webserver|web-runtime" /tmp/dsh-web-config.yml

发布仓库需要提交构建后的 lib/。包不设置安装期 prepare，安装过程不会执行授权脚本。

首次启动

本地非 root 启动：

export DSH_HOME="$PWD/.dsh"
pnpm dsh --profile web --port 3080

全新数据库只创建内置 admin。未配置密码文件时，插件生成 32 字符高强度密码，写入权限为 0600 的 $DSH_HOME/auth/bootstrap-admin-password，终端只输出该文件路径：

dsh auth bootstrap password file: /absolute/path/.dsh/auth/bootstrap-admin-password

读取密码后访问终端输出的网关地址，以 admin 登录。初始管理员必须立即修改密码；完成前只能访问 /auth/me、/auth/account、改密和退出接口，其他 API 返回 428 password_change_required。使用插件自动生成的 bootstrap 文件时，成功改密后文件会被删除。

也可以从管理员准备的私有文件初始化：

chmod 600 /run/secrets/dsh-admin-password
pnpm dsh --profile web --port 3080 \
--auth-bootstrap-password-file /run/secrets/dsh-admin-password

密码文件内容必须为 12 至 256 个字符，不能带首尾空白，文件不能是符号链接，也不能向 group 或 other 授权。插件只读取管理员提供的文件，不会删除它。

账号与密码

管理员可以在 /auth/admin 创建普通用户或其他管理员。每个新账号初始密码都必须修改，数据库会在当前用户根目录下创建权限为 0700 的专属目录。

所有启用账号都可以通过 Harness 侧边栏或 /auth/account 修改自己的密码。成功后，该账号的全部登录 Session 和活动 WebSocket 立即失效，浏览器返回登录页。

管理员可以为其他非内置账号生成一次性临时密码。临时密码由 96 位随机输入编码为 16 字符 base64url，只在当前响应显示一次；重置同时撤销目标账号的全部登录 Session 和 WebSocket。管理员不能重置自己，内置 admin 只能使用自助改密。

内置标识保存在 users.built_in，不再根据用户名推断。内置 admin 不能删除、禁用、改角色或由管理员重置密码。管理员管理页也不能修改、重置或删除当前登录账号。

管理员功能

管理页采用概览、用户、Workspace 和对话归属四个模块。管理员可以：

- 创建用户和专属目录，查看账号角色、状态及资源数量。
- 分页查看 Session 与 Workspace 归属，每页 10 条。
- 将 Workspace 及其当前全部 Session 在一个事务中转移给指定用户。
- 修改其他非内置账号的角色和启用状态；禁用会撤销全部登录状态。
- 重置其他非内置账号密码并显示一次性临时密码。
- 删除其他非内置账号及其登录状态、归属行、Workspace 注册、JSONL Session 日志、投影缓存和专属目录。
- 读取全部用户的对话和 Workspace。
管理员对其他用户资源保持只读。网关拒绝对他人对话执行 prompt、重命名、模型切换、队列更新、取消、fork、Subagent、Goal、反馈、命令执行、preset 状态修改以及审批或问题回答。管理员仍可修改自己拥有的资源和全局设置。

删除用户要求再次输入目标用户名。存在已加载或运行 Session/Agent 时删除会被拒绝，避免内存中的对象重新写回日志；重启 DSH 后，在重新打开相关对话前可以重试。专属目录之外的 Workspace 主机目录不会递归删除。

用户根目录可由管理员修改，但只有数据库中不存在普通用户时允许切换。切换只影响之后创建的账号，已有管理员目录保持记录路径。

Workspace 与路径规则

每个 Session 和 Workspace 都有一个 SQLite 所有者。普通用户只能读取和修改自己的资源；管理员可以读取全部资源，但跨用户写入被拒绝。升级前没有归属行的资源保持未分配，只对管理员可见，管理员可在管理页明确分配 Workspace 及其 Session。

普通用户创建 Session 时，未提供 cwd 或 workspaceId 会自动使用其专属目录。显式 cwd、Workspace 创建、目录浏览、目录创建和 host.openPath 必须位于专属目录或管理员已分配 Workspace 中。

路径策略对已存在路径使用 realpath，对新建目标解析最深已存在父目录。符号链接、..、兄弟用户目录和授权根之外的路径统一返回中文业务错误，不向普通用户暴露其他账号的目录清单。

普通用户只能选择部署提供的 trust=system preset，不能读取或编辑本地 preset，也不能通过 /permission danger-full-access 提升权限。选择结果作为个人默认值保存在认证数据库中，只影响该用户之后创建且未显式指定 preset 的 Session，不修改 Harness 全局默认。RPC 和 Typert Remote 采用显式策略表；新增或未知 Core RPC 在编译或运行时默认拒绝。

普通用户可以读取模型 provider、模型目录、插件清单、provider 声明的脱敏设置，以及这些设置实际引用的凭据是否已配置，但不能探测其他凭据名称、读取密钥值或修改全局模型、凭据和插件设置。settings.describe 还返回 ui-onboarding；单次设置 welcomeNoticeVersion 的确认按用户保存在当前认证进程中，不写入 Harness 全局设置。模型发现、凭据写入、设置文档路径和其他 namespace 始终只对管理员开放。

命令行配置

| 参数 | 默认值 | 说明 |
| --port | 3080 | 用户访问的认证网关端口；0 由操作系统分配 |
| --host | 127.0.0.1 | --auth-host 的兼容别名，二者不能同时使用 |
| --auth-host | 127.0.0.1 | 127.0.0.1 或 0.0.0.0 |
| --auth-public-origin | 本地回环网关地址 | 精确的外部 HTTP/HTTPS origin，不得包含路径、查询或片段 |
| --auth-db | $DSH_HOME/auth/auth.sqlite | 独立认证数据库路径 |
| --auth-user-root | $DSH_HOME/users | 新账号专属目录的根目录 |
| --auth-session-ttl | 86400 | 绝对登录有效期，范围 60 秒至一年 |
| --auth-bootstrap-password-file | 自动生成文件 | 全新数据库的私有管理员密码文件 |
| --auth-allow-root | 关闭 | 仅隔离容器或测试环境显式允许 UID 0 |
| --auth-login-window | 900 | 登录失败统计窗口 |
| --auth-login-user-limit | 5 | 每个客户端地址与用户名组合的窗口失败上限 |
| --auth-login-client-limit | 20 | 每个客户端地址的窗口总失败上限 |
| --auth-scrypt-concurrency | 4 | 最大并发 scrypt 操作数 |
| --auth-scrypt-queue | 32 | 最大排队 scrypt 操作数 |
| --auth-max-api-body-mib | 32 | 单个缓冲 API 请求体上限，单位 MiB |
| --auth-max-api-concurrency | 4 | 最大并发缓冲 API 请求数 |

监听 0.0.0.0 时必须显式配置 --auth-public-origin。收到 X-Forwarded-Proto: https 但 publicOrigin 仍是 HTTP 时，HTTP 返回明确 503，WebSocket Upgrade 也会拒绝，不会签发非 Secure Cookie。

HTTP 接口

- GET /auth/login：登录页面。
- POST /auth/login：接受表单或 JSON，成功后创建 Cookie Session。
- GET /auth/me：返回包含 id、username、role、homeDirectory、builtIn 和 mustChangePassword 的 user 对象。
- GET /auth/account：自助改密页面。
- POST /auth/account/password：验证当前密码并修改密码，成功后撤销该账号全部登录状态。
- POST /auth/logout：只撤销当前 Token，并清除 Cookie。
- GET /auth/admin：管理员页面。
- POST /auth/admin/users/create：创建账号和专属目录。
- POST /auth/admin/users/reset-password：为其他非内置账号生成一次性密码。
- POST /auth/admin/users：更新其他非内置账号角色和状态。
- POST /auth/admin/users/delete：确认用户名后删除账号及其 Harness 资源。
- POST /auth/admin/workspaces：转移 Workspace 及其当前 Session 归属。
- POST /auth/admin/settings/user-root：更新之后新建账号使用的用户根目录。

未登录页面导航跳转到登录页，API 返回 JSON 401，WebSocket Upgrade 返回 401。所有状态变更接口验证 Host、Origin 或 Referer 和 Fetch Metadata。

SQLite schema v7

认证数据库独立于 Harness Storage，默认位于 $DSH_HOME/auth/auth.sqlite。schema v7 包含：

- auth_settings：管理员选择的用户根目录。
- users：随机盐、scrypt 哈希、角色、启用状态、专属目录、built_in 和 must_change_password。
- login_sessions：浏览器 Token 的 SHA-256 摘要、用户和绝对过期时间。
- session_owners：Session 的唯一用户归属。
- workspace_owners：Workspace 的唯一用户归属。
- user_preferences：用户个人默认 Agent preset；删除账号时通过外键级联删除。

SQLite 不保存明文密码或原始 Session Token。密码使用异步 scrypt、每个账号独立 16 字节随机盐和 64 字节派生值；Cookie Token 使用 32 字节随机值。数据库目录和用户根目录权限为 0700，数据库文件和自动生成的 bootstrap 文件权限为 0600，配置目标不能是符号链接。

v6 升级到 v7 时只新增 user_preferences，保留账号、目录、Workspace、对话归属和登录数据。v5 升级时，唯一启用且用户名为 admin 的管理员成为持久化内置账号；找不到该唯一账号时启动失败，并要求离线修复，而不是猜测身份。仍使用 admin123 或 user123 的历史账号会标记为必须改密并撤销旧登录 Session，其他已修改密码不受影响。

schema v1 至 v4 会先执行既有迁移，再进入相同的内置账号规则，最后升级到 v7。旧 user1/admin 和 user2/user 只有在仍使用 123456 且目标用户名未占用时才迁移为 admin 和 user；稳定 ID、目录和资源归属保持不变。外部数据库、未知版本或字段不完整的已知 schema 会被拒绝。

Harness Session 日志和 Workspace 注册仍由 $DSH_HOME/sessions 与 $DSH_HOME/storages 持久化。普通归属调整不会移动或重写历史数据；用户永久删除是唯一会删除对应 Session 目录、投影缓存和 Workspace 注册的管理操作。

HTTPS 与 Nginx

TLS 由同机 Nginx、Caddy 等终止，认证网关继续监听回环 HTTP。公网地址必须通过精确 publicOrigin 告知插件：

DSH_HOME=/srv/deepseek-harness/.dsh dsh web \
--port 3081 \
--auth-public-origin https://dsh.example.com

Nginx 上游仍指向固定的认证网关端口 3081。原 Harness 服务由 bundle 自动移动到随机内部回环端口。Nginx 必须保留浏览器的真实 Host、Origin 和 Fetch Metadata：

map $http_upgrade $connection_upgrade {
default upgrade;
'' close;
}

server {
listen 443 ssl;
server_name dsh.example.com;

ssl_certificate /etc/nginx/certs/server.crt;
ssl_certificate_key /etc/nginx/certs/server.key;

location / {
proxy_pass http://127.0.0.1:3081;
proxy_http_version 1.1;

proxy_set_header Host $http_host;
proxy_set_header Origin $http_origin;
proxy_set_header Sec-Fetch-Site $http_sec_fetch_site;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto https;

proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $connection_upgrade;
proxy_buffering off;
proxy_cache off;
proxy_read_timeout 3600s;
proxy_send_timeout 3600s;
}
}

不要把 Host、Origin 或 Sec-Fetch-Site 固定为内部地址或伪造为 same-origin。网关只在直接连接来自回环地址时读取 Nginx 追加的 X-Forwarded-For；直连非回环请求的该头会被忽略。

deploy/Caddyfile.example 提供 Caddy 示例。HTTPS publicOrigin 启用 Secure Cookie 和 HSTS；Cookie 始终使用 HttpOnly; SameSite=Strict; Path=/，不设置 Domain。

非 root 部署

宿主机不要使用 --auth-allow-root。创建专用账号，并确保它拥有 $DSH_HOME、用户根目录和需要访问的 Workspace：

useradd --system --create-home --home-dir /srv/deepseek-harness dshsh
chown -R dsh:dsh /srv/deepseek-harness
sudo -u dsh env DSH_HOME=/srv/deepseek-harness/.dsh \
dsh web --port 3081 --auth-public-origin https://dsh.example.com

在隔离容器内必须以 root 运行时，显式增加 --auth-allow-root，并把它视为部署风险确认，而不是默认配置。

升级顺序

1. 停止 DSH，备份认证数据库及完整 $DSH_HOME。
2. 在非生产端口安装 1.0.0，使用备份副本验证现有数据库升级到 v7。
3. 确认内置管理员、强制改密标记、Workspace、历史对话和消息实时渲染正常。
4. 使用真实 HTTPS/WSS 入口验证登录、发送消息、刷新、退出和管理员操作。
5. 内网灰度稳定后再替换正式服务。

不要在运行中的 SQLite WAL 文件上只复制 auth.sqlite。应停止进程后备份整个 $DSH_HOME，或使用 SQLite 在线备份工具。

安全限制

- 本版只面向受控内网的可信用户，不防御恶意或互不信任用户。
- Shell 和文件工具共享同一个系统账号，仍可能读取该账号可读的宿主文件。
- 认证网关不防御已经拥有同机访问权的用户或进程；它们可能连接随机回环内部端口。
- 登录身份暂不写入 Harness Session 日志。
- 管理员可以读取其他用户的完整对话内容，但不能跨用户修改。
- bundle patch 依赖 Web profile 行 ID；Harness 升级后必须重新执行组合、启动和浏览器测试。

开发与发布检查 sh
pnpm run typecheck
pnpm run test
pnpm run build
pnpm run pack:check
pnpm audit --prod

pnpm run build 从 src/ 生成随包发布的 lib/。详细数据流和授权规则见 docs/architecture.md。