152 lines
17 KiB
Markdown
152 lines
17 KiB
Markdown
# DSH Runtime Release
|
||
|
||
## runtime-7.9：DSH next 与启动配置迁移
|
||
|
||
锁文件同步修复：内置依赖迁移或补建 workspace 配置前，先持久化 `.dsh-lockfile-pending` 标记。仅带标记的启动安装显式传入 `--no-frozen-lockfile`，同步 `pnpm-lock.yaml`；成功后清除标记，后续启动恢复 CI 默认冻结检查。安装失败或超时保留标记并阻止应用启动，下次启动继续同步，不自动恢复旧 manifest。已有 manifest 备份机制保持不变。若旧版失败迁移已经留下“新 manifest＋旧锁文件”且没有标记，应先恢复匹配的旧 profile 备份再升级；不要直接删除锁文件。
|
||
|
||
本次修复验证：45 项自动化测试通过；`node image/lockfile-upgrade-smoke.mjs` 使用本地 `dsh-upgrade-test:runtime-7.8` 与 `dsh-web:runtime-7.9-amd64` 镜像、独立临时卷、禁网非 root 容器，挂载当前修复脚本，验证真实旧锁文件迁移、随后冻结安装成功及重启锁文件哈希不变。脚本结束删除测试卷。本次未重跑面板 HTTP 升级接口或首页验收，未发布新镜像。
|
||
|
||
DSH 固定为 `0.2.1-rc.2`（本次明确选择 npm `next`，查询时 `latest` 仍为 `0.2.0-rc.2`），mobile 升级为 `3.1.0`，Chat Manager 升级为明确声明支持新宿主的 `1.5.16-dsh-mgr.1`。free-search 升级为 `0.9.2`，workspace `1.0.0`、preview-download `1.0.1` 保持不变。
|
||
|
||
现有 runtime 每次启动时检查 `profiles/web/package.json`，不另加容器、不联网追踪最新版。仅将 dependencies/devDependencies/optionalDependencies 中同名 `file:/usr/local/lib/dsh-mgr/<包名>-<版本>.tgz` 引用对齐镜像内置清单，并补齐相关缺失的 pnpm overrides。保留自定义安装来源、自定义 overrides、bundles、已删除的插件和其他配置。目标归档缺失、无效配置或不安全的符号链接会阻止启动。
|
||
|
||
只有配置变化才写入，原文保存在同目录 `package.json.backup-<UUID>`，新文件通过原子替换写入，权限 `0600`；重复启动不会反复改写。恢复时先停止实例并备份现状，再恢复对应备份；要回退旧内置版本必须同时使用匹配的旧镜像，否则下一次启动会再次对齐当前镜像。迁移不提供针对同 UID 恶意并发修改目录的沙箱保护。
|
||
|
||
新版设置 UI 已原生使用 host settings describe/mutate，构建只验证接口、不再应用旧 persistence 替换。Office 转换补丁仍限定精确宿主及插件版本；下载 slot/readBytes 和 workspaceRegistry 接口已核对上游源码。mobile/free-search 的预发布 peer 例外仅允许精确 `0.2.1-rc.2` 的 DSH 包且仍要求满足原版本范围（includePrerelease），其他依赖照常严格校验。
|
||
|
||
当前自动化回归 40 项通过；AMD64 镜像已构建，禁网 UID 1000 新 profile 安装、HTTP 未认证 401、旧 mobile/free-search/chat-manager 引用迁移、备份与幂等检查通过。Office 的已安装 DSH convertBytes 集成及 DOCX/PPTX/DOC/PPT 并发、限制、超时、清理测试通过。pnpm 会提示由宿主提供的 peer 缺失/范围冲突；这不是浏览器交互兼容性证明。浏览器完整交互、真实搜索结果、设置保存、终端原生模块和 ARM64 尚未验收。以下旧发布记录中的“已有 profile 不自动改写”仅适用于旧版本。
|
||
|
||
## runtime-7.8：修复下载按钮服务依赖
|
||
|
||
下载插件升级为 dsh-preview-download@1.0.1，补齐 remote 服务声明，修复点击时在发送请求前抛出 cannot get property "remote" without inject 的问题。同步更新内置包和新 profile 引用，新增注册回调依赖回归测试。此修复不处理面板 401、Office 504 或 plugins/events HTTP/2 连接错误。
|
||
|
||
已有实例升级镜像时，必须把 profile 中 dsh-preview-download 依赖的归档路径从 dsh-preview-download-1.0.0.tgz 改为 dsh-preview-download-1.0.1.tgz，保留其他配置和 bundles，重启后刷新页面；已有 profile 不自动改写。尚未完成线上浏览器下载验收。
|
||
|
||
## runtime-7.7：预览下载插件
|
||
|
||
内置独立插件 dsh-preview-download@1.0.0，在文档预览工具栏提供「下载原文件」。使用正式 sidebar.right.tab.document.actions 插槽，不修改上游 UI、不扫描 DOM、不增加服务端下载接口。通过当前会话 workspaceFiles.readBytes 获取原始字节，沿用服务端权限和完整文件大小上限；支持中文文件名、下载中状态、失败提示及切换文件/卸载时取消读取。下载的是原始文件，不是 Office 转换出的 PDF。文件元数据无法读取时不会显示工具栏按钮。
|
||
|
||
新建空 profile 默认启用。已有实例升级镜像后，在 /workspace/profiles/web/package.json 的 dependencies 中添加以下条目，并在 dsh.profile.bundles 中追加一次 dsh-preview-download，保留其他配置，然后重启：
|
||
|
||
~~~json
|
||
"dsh-preview-download": "file:/usr/local/lib/dsh-mgr/dsh-preview-download-1.0.1.tgz"
|
||
~~~
|
||
|
||
插件源码位于 image/preview-download，也可单独打包安装。无第三方运行时依赖，React 由 DSH 浏览器提供。当前仅针对 DSH 0.2.0-rc.2 验证。25 项离线回归测试通过，已在现有 AMD64 镜像中验证插件打包、新 profile 离线安装及服务启动；完整 runtime-7.7 构建在 MiSans 下载阶段超时，尚未完成浏览器实际点击下载、移动端和 ARM64 验收。不应把单元测试中的拒绝响应模拟当作真实权限端到端验收。
|
||
|
||
## runtime-7.6：原生 Office 文档预览
|
||
|
||
Linux 文档预览通过构建期补丁将 Office-to-PDF 转换入口接到系统 LibreOffice，不再使用该入口原先默认的 WASM 后端。补丁限定 DSH 和 dsh-office-to-pdf 为 0.2.0-rc.2，目标 import 不匹配或重复应用时构建失败。保留上游授权、队列、缓存和 PDF 验证；不修改独立 dsoffice CLI 或其他插件。
|
||
|
||
每次转换使用私有临时目录、独立 profile、最高宏安全级别和独立进程组；保留默认 60 秒超时，取消时终止进程组。检查输入大小、OOXML 条目数、解压总量和 CRC、输出大小及完整性。子进程采用最小环境变量；校验器地址空间上限 512 MiB，LibreOffice 为 2 GiB，单文件写入上限为 max(maxOutputBytes, 16 MiB)，最终 PDF 仍严格检查 maxOutputBytes。进程资源限制不是进程树总量或临时目录总量限制，部署时仍须容器内存、CPU、PID 和临时磁盘限制。
|
||
|
||
PDF 浏览器兼容补丁：image/install-pdf-compat.mjs 在构建期为 DSH / documentpreview 0.2.1-rc.2 的 PDF.js 主线程及内嵌 worker 注入缺失的 Map.getOrInsert、Map.getOrInsertComputed 和 Math.sumPrecise，不覆盖原生方法。版本不匹配、worker 入口变化或重复安装时直接失败。精确求和使用 BigInt 累加，避免嵌入字体因 Chrome 143 缺少 API 而回退。回归测试命令：node --test image/pdf-compat.test.mjs。已用 Chrome for Testing 143.0.7499.192（移动视口、触摸模拟）验证镜像内真实 PDF 加载/渲染代码：补丁前复现 methodPromises 报错，补丁后 14 页样本加载、第 1→2→1 页渲染与文本提取成功，控制台无错误或警告；不等同 Android 真机或完整业务 UI 测试。现有部署须重新构建并更新镜像才会获得补丁。
|
||
|
||
安全边界：原生 LibreOffice 与 DSH 使用同一 UID，独立 profile 不是文件系统或网络沙箱；不应将此功能视为隔离恶意文档的服务。容器内敏感文件及网络访问仍需部署侧隔离，尤其是处理不可信外部文档时。
|
||
|
||
字体由系统解析；显式 fontDirectories/fontFallbacks 配置会被拒绝，应移除并改用系统字体配置。kit 的 maxFontFiles/maxFontFileBytes/maxLoadedFontBytes 不再约束系统字体。missingFonts 为空仅表示不提供缺失字体诊断，不代表没有字体替换。
|
||
|
||
已完成 AMD64 构建、22 项回归测试，以及非 root/禁网容器中 DOCX/PPTX/DOC/PPT 并发转换、已安装 DSH convertBytes 集成、输出/压缩包限制、超时及清理验证。小型单页样本约 3 秒/文件，不代表实际文档性能保证。ARM64、真实失败样本、浏览器端到端、XLS/XLSX 和视觉版式尚未验收。
|
||
|
||
构建后在仓库根目录运行：
|
||
|
||
~~~sh
|
||
docker run --rm --network none --init \
|
||
--mount type=bind,src="$PWD/image",dst=/test,readonly \
|
||
--entrypoint node dsh-web:runtime-7.6-amd64 /test/office-preview-smoke.mjs
|
||
~~~
|
||
|
||
现有实例需升级新镜像才生效，不需要清空工作区。不自动提交、推送或升级线上实例。
|
||
|
||
## runtime-7.5：精简 MiSans 字重
|
||
|
||
runtime-7.5 修订仅保留 MiSans Regular 和 Bold，从第三方 GitHub 仓库 boyan01/mi_sans_font 的固定提交下载独立 TTF 并逐个校验 SHA-256，合计约 15.73 MB，不再下载官方完整 ZIP。构建环境需要能够访问 raw.githubusercontent.com。
|
||
|
||
## runtime-7.4：文档工具、中文字体与 Chat Manager 修复
|
||
|
||
runtime-7.4 修订内容：新增 Python、LibreOffice、Noto CJK 与 MiSans，并内置修复版 Chat Manager。DSH 版本仍为 0.2.0-rc.2，运行布局仍为 7，继续保留 runtime-7.3 的域名设置适配。已完成本地 AMD64 构建、19 项测试、离线启动及插件接口认证拒绝检查；ARM64 与线上面板完整删除流程尚未验收。
|
||
|
||
## 内置修复版 Chat Manager
|
||
|
||
镜像内置 `[email protected]`（基于官方 1.5.12，保留 MIT 许可及服务端安全校验）。补丁仅针对客户端：删除、恢复、归档搜索在面板内使用当前 `/dsh/<实例ID>/` 前缀，独立 DSH 根路径部署保持原行为；非 JSON 响应显示 HTTP 状态和代理排查提示，不再直接暴露 JSON 解析异常。不会修改全局 fetch、绕过 Cookie/Origin/可信主机校验或自动重试删除请求。
|
||
|
||
新建空 web profile 默认启用此插件，内置包和 clsx 依赖均支持离线安装。已有 profile 不会被覆盖，也不会自动替换用户已安装的官方版本。升级镜像后，如需迁移已有实例，请保留其他设置，将 profile 中同名依赖改为 `file:/usr/local/lib/dsh-mgr/dsh-chat-manager-1.5.12-dsh-mgr.1.tgz`，并设置 pnpm override `dsh-chat-manager>clsx` 为 `file:/usr/local/lib/dsh-mgr/clsx-2.1.1.tgz`，确保 bundles 中只有一次 `dsh-chat-manager`，再重启实例。不要同时启用重复的手动 patch 插件条目。
|
||
|
||
域名访问仍要求 DSH 配置相应 trusted host，且 runtime 必须经过面板认证与实例归属校验。此修复不开放面板根路径的插件接口。
|
||
|
||
## 内置 Python 与 LibreOffice
|
||
|
||
Runtime 镜像包含 Debian Bookworm 的 Python 3、pip、venv（`python` 指向 `python3`），以及 LibreOffice 和 Noto CJK 中文字体。LibreOffice 可通过 `libreoffice --headless` 无界面运行。Python 项目依赖请安装到工作区的虚拟环境中，不要覆盖系统 Python 包。
|
||
|
||
这些依赖在镜像构建时安装；已有实例需要重建镜像并升级后才生效。
|
||
|
||
另包含小米 MiSans 简体中文字体的 Regular 和 Bold 两个静态 TTF 字重，保留 Noto CJK，不修改默认字体优先级。构建时从第三方镜像 boyan01/mi_sans_font 的固定提交 68f3ec3fee5830ce8a1d955d462fa0df401a5341 下载两个 TTF 并校验各自 SHA-256；镜像文件与当前官网 ZIP 不同，不保证为最新版本，GitHub 仓库许可不替代小米字体许可。字体及声明位于 `/usr/local/share/fonts/misans`。MiSans 使用小米专有免费商用许可，并非开源字体许可；安装使用及对外分发镜像前应阅读[官方许可协议](https://hyperos.mi.com/font/zh/download/)，不得单独分发或售卖字体。
|
||
|
||
## runtime-7.3：域名访问设置适配
|
||
|
||
自 runtime-7.3 起，构建时对 DSH 0.2.0-rc.2 的设置 UI 应用精确补丁，使设置视图与表单使用 host 持久化；不修改 connection.isLoopback、可信主机、Origin 或认证逻辑。版本或目标语句不匹配时构建失败，升级上游版本必须重新审核补丁。
|
||
|
||
这是构建期适配，不是普通插件。补丁本身不识别面板登录状态，该镜像的设置 UI 会对所有访问地址尝试远程设置操作，因此只能部署在受认证、校验实例归属的面板入口之后，不得绕过认证直接公开 runtime 端口。权限由服务端保证。
|
||
|
||
发布前须在非 localhost 域名验证提供商目录、配置与凭据保存、刷新和重启持久化，以及未登录、跨用户和非法 Origin 的拒绝行为。单元测试不代替这些验收；现有实例需升级镜像才生效，不覆盖用户 profile 或创建空 patch。
|
||
|
||
`dockerfile` 分支只维护发布清单和 runtime 镜像构建文件，不包含管理面板源码或部署配置。
|
||
|
||
## 发布清单
|
||
|
||
`release.json` 是发布入口：`schema_version` 为清单格式版本，`release_id` 标识一次发布，`version` 为精确 DSH 版本，`deployment_schema` 为运行布局版本，`platforms` 为支持的平台。当前待发布配置为 `runtime-7.9`、DSH `0.2.1-rc.2`、布局 7、`linux/amd64` 和 `linux/arm64`（aarch64，不含 32 位 ARM）。
|
||
|
||
ARM64 验收状态：已确认 Node/Caddy 基础镜像提供 ARM64 版本，但尚未完成 ARM64 runtime 构建及运行验收。清单声明会开放面板的对应平台构建入口，不等于兼容性证明；验收完成前不要推送发布。
|
||
|
||
此分支是可信代码来源，不是仅供读取的数据源：Dockerfile 和安装脚本会在构建时执行。只使用经过审核的提交，不要将不可信分支、PR 或任意远端内容直接用于构建。清单本身不代表镜像已经完成运行验收。
|
||
|
||
## 本地构建与检查
|
||
|
||
需要 Docker、Node.js，以及拉取基础镜像和构建依赖的网络。从仓库根目录执行，DSH 版本取自清单，平台按 Docker daemon 架构选择，不跟踪 latest：
|
||
|
||
~~~sh
|
||
set -eu
|
||
DSH_VERSION="$(node -p "require('./release.json').version")"
|
||
case "$(docker info --format '{{.Architecture}}')" in
|
||
aarch64|arm64) PLATFORM=linux/arm64 ;;
|
||
x86_64|amd64) PLATFORM=linux/amd64 ;;
|
||
*) echo 'Unsupported Docker daemon architecture' >&2; exit 1 ;;
|
||
esac
|
||
RELEASE_ID="$(node -p "require('./release.json').release_id")"
|
||
node --test image/*.test.mjs
|
||
docker build --platform "$PLATFORM" \
|
||
--build-arg DSH_VERSION="$DSH_VERSION" \
|
||
-t "dsh-web:$RELEASE_ID-${PLATFORM#linux/}" ./image
|
||
~~~
|
||
|
||
默认按 Docker daemon 架构原生构建，不再固定取清单第一个平台。在交叉构建环境可手动将 PLATFORM 设置为 linux/arm64 或 linux/amd64；需要事先配置对应原生 builder 或 QEMU/binfmt，仅设置 --platform 不会自动提供模拟能力。
|
||
|
||
Dockerfile 两个阶段均继承目标平台，无需写死架构；不要将 Caddy 阶段固定为构建主机平台，也不要复用另一架构的 node_modules。
|
||
|
||
发布前分别验证两个架构的镜像构建、非 root 启动、代理认证、终端及原生模块、内置插件离线协调、工作区写入和重启持久化，以及升级/恢复路径。迁移工作区时需重新安装其中的架构相关依赖。
|
||
|
||
`image/` 是构建上下文。构建只生成本地镜像，不推送镜像，也不自动发布分支。保留 `image/init-profile.test.mjs` 作为独立 runtime 回归测试，覆盖初始化幂等性、保留已有配置和拒绝符号链接目录；它不依赖面板，且被 `image/.dockerignore` 排除在构建上下文之外。此测试不能替代真实容器启动、插件和持久化验收。
|
||
|
||
## 布局 7 合约
|
||
|
||
- 以 UID/GID 1000 运行；实例持久目录挂载到 `/workspace`，必须允许该身份读写。`DSH_HOME`、`HOME` 和工作目录均为 `/workspace`，XDG 数据与配置也位于其中。
|
||
- `/data/dsh-home` 是指向 `/workspace` 的兼容符号链接；不要用旧 home 挂载覆盖该路径。`/shared` 不是布局 7 的持久化入口。
|
||
- DSH 监听 loopback 3080，Caddy 在容器 8080 转发；只通过受信入口访问，不直接公开 runtime 端口，不挂载 Docker socket。原生模块需要可执行的 `/tmp`，可保留 nosuid/nodev 与容量限制。
|
||
- 新 profile 默认启用固定版本的 mobile、free-search 和 workspace bundle，默认工作区为 `/workspace`。已有非空 profile 不自动注入或覆盖；升级镜像不会强制改变已有插件选择。
|
||
- 启动前协调插件依赖，失败则不启动应用；仅含内置固定依赖的 profile 使用离线安装。用户添加插件后可能需要网络。
|
||
|
||
## 手动发布
|
||
|
||
1. 审核 runtime 资产变更及其可信来源，选择精确 DSH 版本，更新 `release.json`。每次发布变更都必须使用新的 `release_id`；布局合约变化时同步更新 `deployment_schema`、镜像及调用方适配，不能只修改数字。
|
||
2. 运行上述测试与本地构建，并完成目标平台的容器启动、插件、持久化与兼容验收；检查 `git diff --check` 和最终差异。
|
||
3. 维护者确认后，**手动提交并手动推送** `dockerfile` 分支到已核实的发布远端。修改清单或本地构建不会自动 commit/push，也不会自动更新运行中的实例。
|
||
|
||
## 文件范围
|
||
|
||
- `release.json`：发布清单。
|
||
- `README.md`：本分支说明。
|
||
- `image/Dockerfile`、`image/Caddyfile`、`image/entrypoint.sh`、`image/.dockerignore`：镜像构建与启动。
|
||
- `image/install-*.mjs`、`image/init-profile.mjs`：内置 runtime 资产安装与 profile 初始化。
|
||
- `image/init-profile.test.mjs`：保留的 profile 初始化回归测试。
|
||
- `image/entrypoint.test.mjs`：从面板测试迁移的 runtime 启动失败保护与镜像约束测试，需要 Bash；不依赖 Go 或面板。
|