226 lines
20 KiB
Markdown
226 lines
20 KiB
Markdown
# DSH Web Manager
|
||
|
||
面向本机或受信任团队的DSH容器管理面板，使用Go、React和SQLite。目标见 [DESIGN.md](DESIGN.md)，接口见 [API.md](API.md)，部署和恢复见 [OPERATIONS.md](OPERATIONS.md)。不适合直接作为公网不可信多租户平台。
|
||
|
||
本项目定位为本机或可信团队试运行，可由管理员通过 HTTPS 反代提供公网入口；不支持不可信租户。选型差异及真实验证边界见 [ACCEPTANCE.md](ACCEPTANCE.md)。
|
||
|
||
## DSH 工作台与移动端
|
||
|
||
登录后默认进入内嵌 DSH 工作台。在“设置”中选择当前账号的实例；选择仅保存在当前浏览器并按账号区分，不保存登录凭据。没有实例时先到“实例”创建，停止或异常的实例需先启动或处理。切换实例会重新加载内嵌页面，但不会停止原容器。
|
||
|
||
移动端使用底部导航：DSH、实例、文件、设置；桌面保留侧栏，管理员可直接从侧栏进入镜像与用户管理，移动端这两个入口仍在“设置”中。切换面板栏目会保留内嵌 DSH 页面，重新加载与独立窗口入口收在工具栏的溢出菜单中。此为同源 iframe，不是安全隔离边界，仍仅适合本机或受信任团队。
|
||
|
||
## 当前实现
|
||
|
||
文件管理中的 PNG、JPEG、GIF、WebP、SVG 可通过“预览”按钮查看（最大 16 MiB），支持适应窗口、原始尺寸、缩放和下载。预览沿用实例归属校验，SVG 只作为图片加载，响应限制脚本与外部资源；直接打开预览地址会下载文件，不作为网页执行。
|
||
|
||
文件管理支持通过“编辑”按钮在线查看和保存不超过 1 MiB 的 UTF-8 文本，使用本地 Monaco 编辑器并跟随系统深浅色。二进制或超限文件请下载处理。关闭、重新加载及离开浏览器前会提醒未保存修改；保存失败保留草稿。保存按读取版本检查冲突，不提供强制覆盖；原子替换需要额外的临时文件配额。DSH 等外部写入不受面板锁控制，最终检查与替换之间仍有竞态，修改运行配置前建议停机并备份。通用编辑不执行专用 Profile 流程的 YAML 校验或强制停机。
|
||
|
||
DSH 新运行镜像仅由管理员从本仓库 `dockerfile` 分支获取独立发布的构建配置，无需 CI 预构建镜像。`release.json` 和完整的 `image/` 目录仅维护在发布分支，main 不再内置运行镜像构建资产；面板锁定 Git commit，在本地构建并验证。管理员在镜像页检查并确认构建，实例升级仍需另行确认，不会因分支更新自动停机。发布约定和首次启用步骤见 [OPERATIONS.md](OPERATIONS.md)。
|
||
|
||
实例所有者可管理完整 home，包括读取自己的配置和凭据；不承诺密钥 write-only，跨用户隔离保持不变。通用文件操作不受专用 Profile 编辑器的 YAML 校验和停机要求约束。下载、打包与敏感修改提示用于防误操作，不是权限限制；文件下载和目录 ZIP 不会自动加密，修改配置前建议先停止实例并备份。
|
||
|
||
- 内置账号、管理员配额、短JWT与refresh轮换、失败锁定及审计。
|
||
- 管理员 Git 发布检查、本地镜像异步构建/验证/清理、使用已验证且准入的本地镜像创建实例与事务名额（每用户最多两个实例）、启动对账。
|
||
- 实例启停删除、独立home（模板7挂载为 `/workspace`）、每实例bridge、归属鉴权及路径反代；DSH认证cookie由服务端保管。
|
||
- 文件上传/下载/重命名/删除及目录ZIP；软配额写前检查、写入串行化与周期巡检。上传最大32 MiB且不覆盖已有文件，删除目录须先清空；删除实例会永久删除其 home、快照及备份。
|
||
- 密码加密配置备份、资源目录与manifest、外部加密包导入、恢复健康检查及回滚。备份只包含六个配置文件及 `skins/`、`pets/`、`agent-presets/`、`.agent-presets/` 资源目录，不是整个 home 的备份；会话、普通工作文件及node_modules不在备份范围内。
|
||
- 备份/恢复/升级自动编排停启；升级保存密码配置备份和home快照，失败尝试回滚。Profile使用本地Monaco及脱敏预览；目前仍需先停止实例，页面“保存并启动”随后验证就绪。
|
||
|
||
新备份使用创建时的登录密码经Argon2id派生密钥、AES-GCM加密，不依赖或创建 `backup.key`。导入/恢复须使用原备份密码，修改登录密码不会重加密旧包。旧版密钥包仍兼容，保留这些包时必须保管原 `backup.key`。
|
||
|
||
## 启动面板
|
||
|
||
需要Linux 5.6+（openat2/renameat2）、Go 1.25+、Node/npm及本机Docker daemon。Docker socket权限等价宿主root。
|
||
|
||
```sh
|
||
npm --prefix web ci
|
||
npm --prefix web run build
|
||
go build -o bin/dsh-mgr ./cmd/server
|
||
# 首次启动设置ADMIN_USERNAME及12–72字节强密码ADMIN_PASSWORD
|
||
./bin/dsh-mgr
|
||
```
|
||
|
||
默认访问 http://127.0.0.1:8088，数据在 `./data`。修改环境密码不会重置已有账号。容器部署使用 `.env.example` 和 `compose.yaml`，按运维文档准备UID/GID 1000数据目录、Docker socket附加组及Docker存储目录映射，再执行 `docker compose up --build -d`。Compose仅发布loopback。
|
||
|
||
## 公网 HTTPS 反向代理（Nginx / Caddy）
|
||
|
||
以下两种方案任选一种，假设反代运行在面板所在宿主机，域名为 `dsh.example.com`，后端为 `http://127.0.0.1:8088`。将示例域名、证书路径替换为实际值。仅支持独立域名根路径部署，不要挂在 `/panel/` 等子路径下；所有路径（包括 `/api/` 和 `/dsh/`）统一转发到面板，不直接代理或公开 runtime 的端口。公网入口仍仅供可信账号使用，不是多租户安全隔离方案。
|
||
|
||
### 面板环境变量
|
||
|
||
使用 Compose 时在项目 `.env` 中设置；直接运行二进制时需通过进程环境传入（二进制不会自动读取 `.env`）：
|
||
|
||
```dotenv
|
||
PANEL_PUBLIC_URL=https://dsh.example.com
|
||
# 仅适用于反代和面板二进制均在宿主机、通过127.0.0.1连接的情况
|
||
TRUSTED_PROXY_CIDRS=127.0.0.1/32
|
||
```
|
||
|
||
`PANEL_PUBLIC_URL` 必须与浏览器访问的 origin 一致，不带路径；非标准 HTTPS 端口需包含端口号。它控制 Origin/CSRF 校验和 Secure Cookie，不依赖 `X-Forwarded-Proto` 推断。修改环境变量后需重启面板进程；Compose 部署应执行 `docker compose up -d panel` 使容器读取新环境，单纯 `docker compose restart` 不会更新环境。
|
||
|
||
注意 Docker 网络差异：宿主机反代访问 Compose 发布端口时，面板看到的来源可能是 Docker 网桥网关，而不是 `127.0.0.1`。此时应将 `TRUSTED_PROXY_CIDRS` 改为确认过的实际代理来源 IP `/32`（IPv6 用 `/128`），不要照抄上述值，也不要信任 `0.0.0.0/0`、`::/0` 或整个不受控内网。未配置信任时，转发头会被忽略，所有用户可能共享代理 IP 的登录额度。可通过后端连接观测确认来源，Docker 网络 inspect 只能提供候选网关信息，不能替代实际确认。
|
||
|
||
如果反代也运行在容器内，`127.0.0.1` 指向反代容器自身，不能使用下面的后端地址。应让反代与面板加入专用 Docker 网络，将后端改为 `panel:8088`（实际服务名），并按面板看到的代理容器地址设置可信来源；不要在同一受信网络放入不可信容器。后端8088和runtime端口不应直接暴露公网。
|
||
|
||
### Nginx
|
||
|
||
示例可放入由 `http {}` 引入的 `/etc/nginx/conf.d/dsh.conf`；`map` 必须位于 `http` 上下文，不能放在 `server` 或 `location` 内。证书需提前申请并配置续期；示例不负责签发证书。
|
||
|
||
```nginx
|
||
map $http_upgrade $dsh_connection_upgrade {
|
||
default upgrade;
|
||
'' close;
|
||
}
|
||
|
||
server {
|
||
listen 80;
|
||
server_name dsh.example.com;
|
||
return 308 https://dsh.example.com$request_uri;
|
||
}
|
||
|
||
server {
|
||
listen 443 ssl;
|
||
server_name dsh.example.com;
|
||
|
||
ssl_certificate /etc/letsencrypt/live/dsh.example.com/fullchain.pem;
|
||
ssl_certificate_key /etc/letsencrypt/live/dsh.example.com/privkey.pem;
|
||
ssl_protocols TLSv1.2 TLSv1.3;
|
||
|
||
# 为multipart封装留余量；应用仍执行自己的上传/备份上限
|
||
client_max_body_size 64m;
|
||
client_body_timeout 60s;
|
||
|
||
location / {
|
||
proxy_pass http://127.0.0.1:8088;
|
||
proxy_http_version 1.1;
|
||
proxy_set_header Host $http_host;
|
||
proxy_set_header Upgrade $http_upgrade;
|
||
proxy_set_header Connection $dsh_connection_upgrade;
|
||
|
||
# 单层公网边缘代理：覆盖客户端提供的转发来源，不能原样信任
|
||
proxy_set_header X-Forwarded-For $remote_addr;
|
||
proxy_set_header X-Real-IP $remote_addr;
|
||
proxy_set_header X-Forwarded-Proto $scheme;
|
||
proxy_set_header X-Forwarded-Host $http_host;
|
||
|
||
proxy_buffering off;
|
||
proxy_request_buffering off;
|
||
proxy_cache off;
|
||
proxy_connect_timeout 10s;
|
||
proxy_read_timeout 3600s;
|
||
proxy_send_timeout 3600s;
|
||
send_timeout 3600s;
|
||
}
|
||
}
|
||
```
|
||
|
||
`Upgrade/Connection` 支持 WebSocket，关闭响应缓冲可及时传送 SSE；读写超时指相邻读写的空闲时间，不是保证连接永久存活。不要改写或删除 `Origin`、Cookie、`X-CSRF-Token`，不要额外添加阻止同源 iframe 的 `X-Frame-Options: DENY`。
|
||
|
||
保存后先检查，再由管理员重载：
|
||
|
||
```sh
|
||
sudo nginx -t
|
||
# 仅在检查成功后执行
|
||
sudo systemctl reload nginx
|
||
```
|
||
|
||
### Caddy
|
||
|
||
将以下内容加入 `/etc/caddy/Caddyfile`。域名 DNS 应指向该主机，80/443 需按证书签发方式可达；Caddy 默认自动申请/续期 HTTPS 证书并将 HTTP 重定向到 HTTPS。
|
||
|
||
```caddyfile
|
||
dsh.example.com {
|
||
request_body {
|
||
max_size 64MB
|
||
}
|
||
|
||
reverse_proxy 127.0.0.1:8088 {
|
||
# 单层公网边缘代理，覆盖外部传入的XFF
|
||
header_up X-Forwarded-For {http.request.remote.host}
|
||
flush_interval -1
|
||
transport http {
|
||
dial_timeout 10s
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
Caddy 自动支持 WebSocket，默认保留请求 Host，并设置转发协议信息；`flush_interval -1` 用于及时刷新流式响应。此处不设置较短的响应读取/流生命周期超时，避免中断长时间 SSE/终端连接。Caddy 重载可能关闭现有 WebSocket，客户端需重连。
|
||
|
||
```sh
|
||
sudo caddy validate --config /etc/caddy/Caddyfile --adapter caddyfile
|
||
# 仅在检查成功后执行（使用systemd安装时）
|
||
sudo systemctl reload caddy
|
||
```
|
||
|
||
以上示例均假设客户端直接连接这层反代。若前方还有 CDN、负载均衡或第二层代理，不能直接依赖这里的 `$remote_addr` / `remote.host` 得到真实客户端 IP；需要在边缘代理单独配置严格的可信上游及来源解析，并相应调整转发策略，否则用户会共享上一层代理的限流额度。
|
||
|
||
### 部署后检查
|
||
|
||
- 确认 HTTP 跳转 HTTPS，证书有效，公网只能到达反代而不能直接访问面板8088或runtime端口。
|
||
- 通过实际域名完成登录、刷新、退出，确认无 Origin/CSRF 403，认证 Cookie 带 Secure；直接使用后端HTTP测试不能替代HTTPS验收。
|
||
- 打开内嵌 DSH、终端/WebSocket、SSE及插件设置；空闲后重连、登录续期均需验证。
|
||
- 验证文件上传/下载及备份导入；应用限制仍有效，反代64MB上限不代表单文件可上传64MB。
|
||
- 使用不同真实客户端确认登录限流来源隔离；测试应使用专用账号，避免锁定实际账号。
|
||
|
||
这些是配置模板，不代表已在你的公网域名部署或验收；应用侧测试和运维边界见 [ACCEPTANCE.md](ACCEPTANCE.md) 与 [OPERATIONS.md](OPERATIONS.md)。
|
||
|
||
## 用户密码重设
|
||
|
||
所有已登录用户（包括管理员）可在「设置 → 账号 → 修改密码」输入当前密码、新密码及确认新密码。当前密码必须验证通过；成功后撤销该账号全部旧会话并返回登录页。忘记当前密码时仍需联系管理员，不提供匿名找回入口。
|
||
|
||
管理员可在「设置 → 用户与审计 → 用户列表 → 重设密码」为用户设置新密码（12–72 UTF-8字节，二次输入及确认）。重设会撤销目标账号全部登录会话和refresh令牌、清除登录失败锁定；旧密码不能再登录，审计仅记录操作者和目标，不记录密码。重设管理员自身会返回登录页。已建立的DSH WebSocket/SSE连接不保证在重设瞬间断开，后续HTTP请求、连接重建与会话续期会被拒绝。
|
||
|
||
## 本地runtime构建
|
||
|
||
### Git 发布与镜像准入
|
||
|
||
镜像的构建验证与使用准入分开管理：推荐/兼容镜像还必须通过精确身份与实际验证检查才可选择；仅存量镜像允许原实例继续运行和启停，不可新建或作为升级目标；禁止使用镜像还拒绝新的启动/重启，但不会自动停止现有容器或断开工作台。
|
||
|
||
管理员在镜像页检查 Git 发布并确认精确 commit 后构建。普通用户只能选择已验证且准入的本地镜像创建实例；没有可选镜像时需等待管理员发布与构建，不再提供 npm 版本、实验构建或构建后自动创建入口。这是 breaking change：移除 `/api/latest`、`/api/compatibility`、`POST /api/builds` 及 `/api/intents` 的全部查询、创建和取消接口，不提供 410 兼容入口。仅保留 `GET /api/builds` 和 `GET /api/builds/{id}` 构建历史读取。不迁移或恢复旧构建及旧创建意图，不在后台续跑或完成旧预约；这不意味着删除已有实例或数据。准入绑定精确镜像ID、版本、模板和平台，不自动信任同tag的新镜像。
|
||
|
||
历史模板保留其精确身份验证记录，不因模板号不是当前版本就标为缺失。但当前新建/升级及正向准入只支持模板7的挂载布局，且镜像平台必须匹配当前面板平台；旧模板即使有成功验证记录也不能靠管理员填写说明放行。内置默认推荐/兼容策略针对 `linux/amd64`，其他平台不能据此推断已经验收。存量实例的启停仍受实际资源状态与禁止使用策略约束；界面展示具体准入原因，以后端校验为准。
|
||
|
||
当前模板为修订7，同时内置 `[email protected]` 与 `[email protected]`（MIT，https://github.com/DDDMUC/dsh-free-search）。Free Search及其普通依赖固定版本、校验SHA-512并保留镜像内原始tarball；新profile默认正式安装并启用，已有profile不自动注入。模板4的mobile恢复路径继续保留。仅包含内置固定依赖的profile在启动前离线安装，不限制运行期插件管理器联网。
|
||
|
||
Free Search默认引擎为Bing，注册的统一provider ID为ddg；未设置或等于deepseek-official的搜索provider会被它接管（包括显式选择同名官方provider），默认http抓取也会被接管，其他自定义provider保留。名称含free不等于保证零费用：自动回退可能读取已有API凭据并调用计费服务。请在插件设置中按需禁用引擎；fallback顺序不是引擎白名单。内置集成不自动测试搜索、配置密钥或执行在线更新。
|
||
|
||
插件设置页的八个固定API路径由面板在实例归属、登录和同源检查后适配前缀及loopback Host，不开放匿名根路径接口。用户在插件内更新到其他版本可能改变接口或离线依赖，需重新验证兼容性。旧实例需显式安装/启用；升级镜像不会覆盖其已有插件选择。
|
||
|
||
模板修订4默认内置 `[email protected]`（MIT，来源 https://github.com/mexiaosqwq/dsh-web-mobile）。构建校验固定SHA-512、不执行插件安装脚本；新建web profile使用镜像内tarball作为正式依赖并默认启用bundle，可在Plugins的Installed列表查看及启停。为兼容旧profile仍保留宿主副本；UI可能显示Uninstall，但本轮未验证卸载行为，不承诺移除镜像内置副本。已有profile不会被覆盖或强制启用；模板3旧实例须在升级后补正式依赖登记，仅升级镜像不会自动出现在Installed列表。该插件按触屏能力启用移动布局，仅缩窄桌面窗口不一定触发。
|
||
|
||
依赖固定引用 `file:/usr/local/lib/dsh-mgr/dsh-web-mobile-3.0.5.tgz`，首次安装与备份恢复无需下载该包。备份包含依赖和bundle清单，恢复目标必须提供相同tarball路径（模板4及兼容后续镜像）；初始化会在此依赖存在且workspace缺失时补建官方no-auto-peers配置，保留已有workspace及禁用状态。
|
||
|
||
运行镜像的构建源与初始化单测在 `dockerfile` 分支维护；main 只构建面板，不再提供 `scripts/build-image.sh`。镜像构建仍需要基础镜像与依赖网络访问，不推送镜像。
|
||
|
||
注意：dsh-web-mobile还包含响应压缩、移动会话删除入口和自定义模型推理档位补全，并非纯CSS。内置版本随镜像固定，不跟踪GitHub main或npm latest。
|
||
模板4目前限定DSH 0.2.0-rc.1/rc.2，并校验已安装宿主的Cordis/DSH peer版本；其他版本需先更新兼容验证，不会自动安装第二套宿主依赖。插件没有独立参数配置页；它修改DSH原有移动界面与设置页。
|
||
|
||
```sh
|
||
bash scripts/smoke-image.sh "$RUNTIME_IMAGE_ID" # 已由管理员构建的本地镜像 ID
|
||
```
|
||
|
||
`scripts/smoke-image.sh` 只检查已有镜像运行，不读取源码、不构建镜像；需 Docker 和 Bash，会创建并清理临时容器。请从镜像页取得精确镜像 ID，不依赖旧版本 tag 推断 Git 发布身份。当前部署协议为7。runtime以UID/GID 1000运行，home和workspace需允许该身份读写。DSH监听loopback:3080，Caddy监听容器内8080；不要发布runtime端口或挂载socket。原生模块需要可执行的 `/tmp`，保留nosuid/nodev和容量限制。存在插件清单时先协调插件，失败不启动应用；真实验证范围见 ACCEPTANCE.md。
|
||
|
||
## 设计替代与边界
|
||
|
||
构建历史接口现默认分页（20条，最大100条），列表不再携带日志正文；日志通过 `/api/builds/{id}` 按需读取。升级面板后请刷新已打开的旧页面；外部脚本需按 API.md 更新，不能再依赖 `/api/builds` 返回全部历史或日志。
|
||
|
||
合理替代方案为：stdlib HTTP Docker client而非官方SDK；每实例独立bridge而非共享bridge；服务端保管DSH cookie而非下发浏览器。前端已改用 Tailwind CSS + Radix 原语的 shadcn 风格组件（保留本地Monaco），桌面与移动端共用一套响应式界面。界面跟随系统深浅色设置自动切换夜间模式（含 Monaco 编辑器），与内嵌 DSH 行为一致，无独立开关。这些是选型差异，不降低功能、安全或验收标准，详见验收表。
|
||
|
||
同源路径代理仅适用于可信用户/插件，尚无独立origin及宿主/局域网出站防护。默认软配额不能阻止agent直接写满磁盘；硬quota是依赖宿主的可选增强，不是默认路线必做项。升级/恢复快照需额外容量，home快照上限1 GiB，模板7的 `/workspace` 就是实例home，会随home快照回滚。旧的用户级共享工作区接口和新容器共享挂载已经移除；磁盘上可能遗留的旧共享目录不属于实例home快照，也不会自动迁移。中断及回滚失败仍可能需要管理员恢复。
|
||
|
||
## 开发验证与文档维护
|
||
|
||
安装前端依赖后，可运行本地检查：
|
||
|
||
```sh
|
||
bash scripts/check-trial.sh
|
||
node --test scripts/check-trial.test.mjs
|
||
```
|
||
|
||
前者依次执行 Go 单测、race 检查、vet、构建、前端单测与生产构建，以及浏览器验收脚本的语法检查；后者验证检查脚本自身的失败传播行为。它们不等于真实 Docker、浏览器或公网 HTTPS 验收，需要外部环境的测试及历史记录见 [ACCEPTANCE.md](ACCEPTANCE.md)。
|
||
|
||
修改接口时同步 [API.md](API.md) 和 [前端对接说明](web/API_REQUEST.md)；修改用户流程时同步本页和 [前端说明](web/README.md)；修改部署、认证或数据布局时同步 [OPERATIONS.md](OPERATIONS.md)、[认证说明](internal/api/AUTH_DESIGN.md) 与 [DESIGN.md](DESIGN.md)。验收记录应注明验证范围，不把历史通过记录视为当前版本的全量验证。
|