feat: build runtime releases from pinned Git branch commits

OPERATIONS.md

@@ -53,6 +53,36 @@
 - 人工恢复前停止相关容器并另做完整备份。中断点不同，不能统一用一次目录覆盖或状态修改处理；当前无自动灾难恢复命令。
 - 删除实例会删除其容器与网络，但保留数据目录。升级快照暂无自动清理；不要删除仍被未完成 journal 引用的快照。
 
+## Git 分支发布运行镜像构建配置
+
+发布源默认为本仓库 `https://git.misaka.ren/m1saka/dsh-web.git` 的 `dockerfile` 分支，通过 `DSH_RELEASE_REPOSITORY` / `DSH_RELEASE_BRANCH` 配置。它发布的是构建文件，不是预构建镜像，也不是面板程序自身的更新。修改配置后需重新创建面板容器。
+
+直接运行面板二进制时需要安装 `git`；面板 Dockerfile 已包含该依赖。当前通道仅支持无需认证的 HTTPS 仓库，不读取宿主 Git 凭据、不跟随重定向，也不支持 SSH 或 URL 内嵌令牌。私有仓库认证需另行扩展，不能把访问令牌写入仓库地址。
+
+分支根目录放 `release.json`，完整构建目录放 `image/`。本仓库提供初始描述文件；发布时一起提交 Dockerfile、Caddyfile、entrypoint 和全部安装/适配脚本。只把 Dockerfile 单独放到分支上是不完整的发布。不要把 `.env`、私钥、凭据、用户数据或 `.git` 放进构建目录；`.dockerignore` 只是辅助措施，发布者仍须审查内容。
+
+Git 通道直接向 Docker API 发送构建上下文，不执行 Docker CLI 的 `.dockerignore` 过滤。面板会排除 `.git`、`.env` 系列和常见凭据文件，并拒绝链接、特殊文件及越界路径，但不能识别任意文件名下的秘密。构建归档最大 32 MiB；Git 获取有 45 秒超时及文件大小限制，建议发布分支仅保留发布所需文件。
+
+`release.json` 示例：
+
+```json
+{
+  "schema_version": 1,
+  "release_id": "runtime-7.1",
+  "version": "0.2.0-rc.2",
+  "deployment_schema": 7,
+  "platforms": ["linux/amd64"]
+}
+```
+
+`version` 是精确 DSH 版本；`release_id` 是构建配置发布编号，修改脚本或 Dockerfile 后即使 DSH 版本不变，也应使用新的编号。`deployment_schema` 声明运行布局兼容协议，当前 Git 发布通道支持协议 7：实例 home 挂载 `/workspace`、共享目录 `/shared`、代理端口 8080，并保留现有认证与启动约定。它不应随普通构建修订递增；不兼容的运行约定需要面板新增支持。`platforms` 只能声明发布者实际验证的平台。
+
+首次发布时，在独立 checkout 或 worktree 准备 `dockerfile` 分支，将 `release.json` 和完整 `image/` 目录提交并推送到同一远程仓库。无需切换正在开发的主工作目录，也无需 CI。此功能的代码安装本身不会替你创建或推送远程分支；分支未发布前，检查失败是预期状态，旧实例与旧构建入口不受影响。
+
+管理员打开镜像页会检查 Git 发布，页面保持打开时每五分钟复查，也可手动刷新。确认构建后面板以固定 commit 获取文件；确认期间分支发生变化会拒绝并要求重新检查。构建任务记录发布编号、仓库和 commit，同一 DSH 版本的新构建发布不会误用旧版本构建任务。构建与验证成功后才可选择镜像；不会自动升级任何已有实例，升级仍走密码确认、备份、快照和失败回滚流程。
+
+该分支是可执行代码信任边界：限制写权限，发布前审查 Dockerfile 与脚本，不向不可信仓库开放构建。可信发布只替代内置版本名单，不替代完整的上线验收；应在发布前验证启动、代理/认证、文件访问、插件以及升级恢复。管理员对精确镜像设置的禁用策略仍然有效。上游依赖、基础镜像和网络变化可能影响重建结果，commit 固定并不意味着所有外部依赖都已固定。Git 故障不会停止已有实例。
+
 ## 创建与构建恢复记录
 
 创建失败不代表 Docker 没有创建资源。面板在发请求前记录 `runtime_creates`（实例 ID、容器/网络结果待确认标志及其置位时间）及 `image_build_checks`（构建 ID、镜像 ID、已确认的验证容器 ID、记录创建时间），已确认网络身份保存在 `runtime_networks`。资源可见后按身份校验再清理；已记录 ID 时按 ID 查询，不能把名称消失当成资源删除。身份不一致时拒绝删除。构建验证残留在启动时及后台重试回收，无需新建构建任务触发。