m1saka/dsh-web
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: synchronize documentation with current implementation

Browse Source
This commit is contained in:
m1saka
2026-10-16 11:37:18 +08:00
parent a8ba3d74dc
commit 09e202796f
8 changed files with 307 additions and 310 deletions
Download Patch File Download Diff File Expand all files Collapse all files
OPERATIONS.md
+9 -14
View File
@@ -7,7 +7,7 @@
## 启动
1. 复制 `.env.example` 为 `.env`，填写专用绝对目录 `DSH_HOST_DATA_ROOT` 和 12–72 字节的随机管理员密码。限制 `.env` 的读取权限，不要提交。管理员账号创建后该密码不再被读取，应从 `.env` 中移除，再运行 `docker compose up -d --force-recreate panel` 重建面板容器，清除容器环境变量中保留的明文密码（`docker inspect` 可见）。仅修改 `.env` 或重启原容器不会更新其环境变量；重建面板会短暂中断面板访问。
2. 面板以 UID/GID 1000 运行。首次部署前由管理员创建专用数据目录并赋予 1000:1000 所有权、0700 权限；不要对已有未知目录递归改权限。将 `stat -c %g /var/run/docker.sock` 的结果填入 `.env` 的 `DOCKER_GID`，以附加组访问 socket。然后运行 `docker compose up --build -d`。默认访问 `http://127.0.0.1:8088`；远程管理优先使用 SSH 本地端口转发，保留此访问地址。Compose 定义了 `dsh-mgr -healthcheck` 健康检查（探测本机 `/healthz`）；进程无响应时容器会被标记为 unhealthy，配合 `restart: unless-stopped` 在退出时自动拉起。
2. 面板以 UID/GID 1000 运行。首次部署前由管理员创建专用数据目录并赋予 1000:1000 所有权、0700 权限；不要对已有未知目录递归改权限。将 `stat -c %g /var/run/docker.sock` 的结果填入 `.env` 的 `DOCKER_GID`，以附加组访问 socket。然后运行 `docker compose up --build -d`。默认访问 `http://127.0.0.1:8088`；远程管理优先使用 SSH 本地端口转发，保留此访问地址。Compose 定义了 `dsh-mgr -healthcheck` 健康检查（探测本机 `/healthz`）；连续探测失败时容器会被标记为 unhealthy，但该状态本身不会触发重启。`restart: unless-stopped` 用于进程退出后的自动拉起；`/healthz` 仅检查HTTP存活，不检查数据库、Docker或实例健康。
3. 管理员登录后在镜像页检查 Git 发布并确认精确 commit 后构建；普通用户选择已验证且准入的本地镜像创建实例。没有可选镜像时等待管理员构建，不再按 npm 版本或预约构建后创建。镜像不推送至仓库。
4. 创建实例后从面板进入 DSH。不要给 runtime 发布宿主端口或挂载 Docker socket。
@@ -17,9 +17,9 @@
## 公网 HTTPS 入口（仅可信账号）
反向代理与证书由部署管理员管理，面板仍建议只监听代理可达的私有入口。设置 `PANEL_PUBLIC_URL=https://你的域名`（仅 origin，不含业务子路径）；Compose 默认值仍为本机 HTTP。此值决定 Cookie 的 Secure 属性及 Origin/CSRF 校验，不从客户端的 X-Forwarded-Proto/Host 推断。
反向代理与证书由部署管理员管理，面板仍建议只监听代理可达的私有入口。设置 `PANEL_PUBLIC_URL=https://你的域名`（仅 origin，不含业务子路径）；Compose 默认值仍为本机 HTTP。此值用于 Origin/CSRF 校验，HTTPS值会启用 Cookie 的 Secure 属性（直接TLS请求也会启用），不从客户端的 X-Forwarded-Proto/Host 推断。
默认只按直连来源 IP 限流，不信任 X-Forwarded-For。经反代部署时，设置 `TRUSTED_PROXY_CIDRS` 为面板实际看到的代理来源地址/CIDR，且确保只有这些代理能连接后端、代理正确维护转发链；不要填写全网 CIDR。未设置时，代理后所有用户将共享该代理来源的每分钟登录额度。公网开放前应实际验证不同客户端来源识别、登录/刷新/退出、DSH iframe、WS/SSE及插件设置接口。
默认只按直连来源 IP 限流，不信任 X-Forwarded-For。经反代部署时，设置 `TRUSTED_PROXY_CIDRS` 为面板实际看到的、逗号分隔的代理来源CIDR（单个IPv4/IPv6地址须写成 `/32` 或 `/128`），且确保只有这些代理能连接后端、代理正确维护转发链；不要填写全网 CIDR。未设置时，代理后所有用户将共享该代理来源的每分钟登录额度。公网开放前应实际验证不同客户端来源识别、登录/刷新/退出、DSH iframe、WS/SSE及插件设置接口。
账号由管理员创建，不支持不可信租户。软配额、同源插件与 Docker socket 权限边界不因 HTTPS 而改变；本版本不承诺抵御分布式拒绝服务。
@@ -41,7 +41,7 @@
在镜像页“准入管理”选择推荐或兼容并填写依据，后端还会检查精确镜像身份、成功验证记录和可支持的挂载布局。审批只作用于该镜像；新镜像需要自己的验证与审批。退为仅存量后不允许新建/升级目标；标为禁止使用还阻止新的启动/重启及受控配置修改、备份/恢复写操作，避免其自动重启绕过禁用。已有配置读取和通用home文件管理仍保留，不会自动停止正在运行的实例。若需要立即隔离已运行实例，管理员必须另行确认并执行停止操作。
历史home布局不同：模板7使用完整home作为 `/workspace`，受支持旧模板使用独立 `/data/dsh-home` 与用户共享 `/workspace`。不要把旧模板准入理解为数据布局可任意互换；不支持的反向迁移仍会拒绝，先做好完整备份。
当前准入仅支持模板7，使用完整home作为 `/workspace`；旧模板的独立 `/data/dsh-home` 与用户共享 `/workspace` 布局不再支持准入。升级也要求原容器只有实例home到 `/workspace` 的单一bind挂载，不会迁移旧共享布局；不符合时返回409。处理历史实例前先做好完整备份。
运行时认证材料由面板首次成功连接实例时提取，并使用 `auth-signing.key` 派生的密钥加密保存在数据根的 `runtime-auth/`（不在用户home内）。按容器 ID 和启动时间绑定，不会将旧启动周期凭据用于新容器；不同 Host 分别缓存 cookie。全量备份应连同签名密钥和该目录保存，不要向用户公开。
@@ -49,7 +49,7 @@
升级到本版本后应在维护窗口逐个访问现有实例，完成首次认证持久化。若在首次成功连接前，启动token已被Docker日志轮转删除，本版本无法凭空恢复；先保存工作，再由管理员安排重启相关实例并访问验证。不要为此删除或重建实例。初次日志扫描上限64 MiB，常规每文件10 MiB/3份保留在此范围内。
- 实例升级选择已经启动验证的本地镜像并提供当前登录密码，面板自动停机、创建密码配置备份与home快照、启动验证及失败回滚，无需先手动停止。home快照最大1 GiB；允许受约束的内部相对链接以支持pnpm，拒绝不安全链接/特殊文件。模板7的 `/workspace` 是实例home，包含在home回滚内；旧共享数据不回滚。跨DSH版本历史验证范围见 ACCEPTANCE.md。
- 实例升级选择已经启动验证且准入的本地模板7镜像并提供当前登录密码，面板自动停机、创建密码配置备份与home快照、启动验证及失败回滚，无需先手动停止。home快照最大1 GiB；允许受约束的内部相对链接以支持pnpm，拒绝不安全链接/特殊文件。模板7的 `/workspace` 是实例home，包含在home回滚内；旧共享挂载布局会在升级前被拒绝。跨DSH版本历史验证范围见 ACCEPTANCE.md。
- Profile是例外：当前需先停止实例，再使用“保存并启动”；页面包含Monaco和脱敏配置预览。不要把备份/升级自动停启理解为Profile可在线改写。
- 若实例进入 `error`，不要直接修改数据库状态强制启动。保留原容器、实例目录与 `upgrade_journal` 记录，检查实际容器与 journal 的旧/新容器 ID、阶段、快照路径是否一致。
- 人工恢复前停止相关容器并另做完整备份。中断点不同，不能统一用一次目录覆盖或状态修改处理；当前无自动灾难恢复命令。
@@ -77,7 +77,7 @@ Git 通道直接向 Docker API 发送构建上下文，不执行 Docker CLI 的
}
```
`version` 是精确 DSH 版本；`release_id` 是构建配置发布编号，修改脚本或 Dockerfile 后即使 DSH 版本不变，也应使用新的编号。`deployment_schema` 声明运行布局兼容协议，当前 Git 发布通道支持协议 7：实例 home 挂载 `/workspace`、共享目录 `/shared`、代理端口 8080，并保留现有认证与启动约定。它不应随普通构建修订递增；不兼容的运行约定需要面板新增支持。`platforms` 只能声明发布者实际验证的平台。
`version` 是精确 DSH 版本；`release_id` 是构建配置发布编号，修改脚本或 Dockerfile 后即使 DSH 版本不变，也应使用新的编号。`deployment_schema` 声明运行布局兼容协议，当前 Git 发布通道支持协议 7：实例 home 是唯一bind挂载，目标为 `/workspace`，不挂载共享目录 `/shared`，代理端口为8080，并保留现有认证与启动约定。它不应随普通构建修订递增；不兼容的运行约定需要面板新增支持。`platforms` 只能声明发布者实际验证的平台。
首次发布时，在独立 checkout 或 worktree 准备 `dockerfile` 分支，将 `release.json` 和完整 `image/` 目录提交并推送到同一远程仓库。无需切换正在开发的主工作目录，也无需 CI。此功能的代码安装本身不会替你创建或推送远程分支；分支未发布前，检查失败是预期状态，旧实例不受影响，但不会回退到内置构建。这是 breaking change：移除 `/api/latest`、`/api/compatibility`、`POST /api/builds` 及 `/api/intents` 的全部查询、创建和取消接口，不提供 410 兼容入口。仅保留 `GET /api/builds` 和 `GET /api/builds/{id}` 构建历史读取。不迁移或恢复旧构建及旧创建意图，不在后台续跑或完成旧预约；这不意味着删除已有实例或数据。
@@ -117,12 +117,7 @@ bash scripts/check-trial.sh
该脚本执行本地自动化测试、race、静态检查及前后端构建，不启动容器、不安装依赖、不部署。需提前准备 Go/Node/npm 和前端依赖。可通过 `TEST_TMPDIR` 指定已存在的临时目录。面板构建单测已隔离真实磁盘空闲量；生产磁盘检查仍保留。`image/init-profile.test.mjs` 属于发布分支的 runtime 测试，不在 main 的检查脚本中运行。
`scripts/test-panel.mjs` 必须指向独立测试部署，通过 `TEST_PANEL_URL`、`TEST_USERNAME`、`TEST_PASSWORD` 指定访问参数；`TEST_UPGRADE=1` 包含同镜像替换升级。运行前需由管理员通过 Git 发布构建准备已验证且准入的本地 runtime 镜像；可用 `TEST_FROM_VERSION` / `TEST_TO_VERSION` 选择源和目标版本。脚本不提交构建，只复用这些镜像，会创建及删除测试实例，删除时一并清理实例数据。不要对生产账号运行。`scripts/smoke-image.sh <image-id>` 和 `scripts/test-mobile-image.mjs <image-id>` 仅测试已有镜像的运行行为，不读取 main 的构建源；仅在隔离测试环境使用。旧构建脚本和构建后创建意图的 live 测试已删除。
# Session lifetime
Set `SESSION_TTL=24h` in `.env` (default), or `SESSION_TTL=168h` for seven days.
Use Go duration units such as `h`, `m`, `s` (not `d`); the value must be a positive
whole number of seconds. Recreate the panel container after changing it:
`docker compose up -d --force-recreate panel`. New logins use the new lifetime;
existing sessions retain their absolute expiry and refresh does not extend it.
Access tokens remain valid for five minutes. `.env` is read by Docker Compose;
when running the binary directly, export `SESSION_TTL` in its environment.
## 会话有效期
在 `.env` 设置 `SESSION_TTL=24h`（默认），七天可设置为 `168h`。使用 Go duration 单位 `h`、`m`、`s`，不支持 `d`；必须至少一秒且为整秒，非法值会阻止启动。修改后运行 `docker compose up -d --force-recreate panel`。新登录使用新期限；已有会话保留原绝对到期时间，刷新不会延长。access token签发有效期为五分钟，但数据库会话过期或被撤销后，即使token尚未到期也不能认证。修改自己的密码或管理员重设密码会撤销该用户所有会话，需要重新登录。`.env` 由 Compose 读取，直接运行二进制时应在进程环境中导出 `SESSION_TTL`。