Repository navigation
Releases
v0.6.9-dsh-0.2.2-rc.3
Changed
- DSH 升级到
0.2.2-rc.3(Dockerfile的ARG DSH_VERSION),从0.2.2-rc.1在
rc 线内前进(跨过rc.2)。稳定性线不变(仍 rc),只是向前推进两个补丁版本。⚠️ 本镜像现在领先latest两个版本:latest仍停在0.2.2-rc.1,而0.2.2-rc.3挂在
next下。上一轮那个"锁定版本 = latest"只是当时的巧合 —— 这正说明必须钉死显式版本号,
不能依赖 tag 别名。- ✅
--public-url仍在:chunk 名与历次完全相同(public-url-D_dMK-yI.js),
parsePublicUrl仍在dsh-web-app的startup.js/index.js;真实启动实测打印带 token 的地址。 - 无会话/设置数据换代:
SESSION_FORMAT_VERSION两版均为 4、迁移包集合完全相同
(catalog+v0-to-v1..v3-to-v4,无新增)→ 本次升级不需要备份会话。 ⚠️ RETIRED_BUNDLES新增一项:除schedule-bundle外,多了
@deepseek-ai/dsh-experimental-agent-team-profile(上游把该实验 bundle 标记为退役,
会自动从 profile 的 bundle 列表里剔除)。本项目 profile 只列dsh-base+dsh-web-app,
未引用它,故零影响。- 包级 +14 / −7(331 → 338)。14 个新增包中只有 6 个会真正装载:
dsh-agent-team、dsh-tool-agent-team(进dsh-base)、
dsh-client-ui-account-notifications、dsh-client-ui-agent-team、dsh-mcp-manager、
dsh-office-kit(进dsh-web-app)。其余 8 个不装载,其中包括又回来的
dsh-computer-use/dsh-cua/dsh-cua-bundle(上一轮 rc.1 刚移除、这轮 rc.3 又加回,
但始终不在本项目的 bundle patch 里)。 ⚠️ 移除的 7 个包里有 3 个曾被实际装载(与上一轮"移除的都没装载过"不同),已逐个核查
并确认是合并重构、不是能力丢失:dsh-office-to-pdf(原进dsh-web-app)→ 能力并入dsh-office-kit,后者描述为
"Office rendering, conversion, and recalculation",是能力超集,lib 内有 pdf 实现;dsh-api-account-controller(原进dsh-web-app,"Expose safe account operations over
authenticated Remote")→ 并入dsh-deepseek-account(lib 内有 controller 实现);dsh-deepseek-account-platform(原进dsh-base)→ 同样并入dsh-deepseek-account
(该包两版都存在,不是新增包)。
另外 4 个experimental-agent-team*原本就没装载,本轮以dsh-agent-team等正式名转正。
- 渲染配置差异 63 行(1243 → 1288 行,条目 302 → 310):新增 10 个条目
(上述 6 个装载包,其中tool-office出现 2 处)+ 移除 2 个(account-controller、
office-to-pdf,均已并包),净 +8;另有searchProvider由deepseek-official改为
deepseek-search-api、agent-preset 增加customSkillDirs等上游配置调整。
本项目对以上引用数均为 0。 hmr条目逐字节相同;nodeLinker: hoisted未变;--patch语义未变(对既有
settings行实测生效);CLI 透传仍在、--dump-config实测可用。
⚠️ 核对陷阱:rc.3 把dsh/lib/bin.js拆成了带哈希的分块文件
(bin-CwxESKe-.js、dump-config-*.js等),在旧路径bin.js里 grep CLI 透传 /
--dump-*会匹配不到,看起来像"能力被移除"——实际是文件拆分,改用功能实测即可确认仍在。- GUI 认证行为与历次一致(无新增变化):裸访问
401、带 token303下发 cookie、
cookie 访问200、未认证 API403—— 四项实测与rc.1完全相同,用户访问指引无需变更。
Verified
- 真机(Docker 29.1.3)构建并全硬化启动:只读根 FS +
--cap-drop ALL
(仅补 CHOWN/DAC_OVERRIDE/FOWNER/SETUID/SETGID)+no-new-privileges+ 三卷挂载
→ 容器Up (healthy),启动日志零 warning / 零 error,首启一次到位(无 EACCES、
无 lifeboat、无需手动重启),seed→卷升级链路正确,镜像内 seed 自证0.2.2-rc.3。 - 全量门禁
scripts/t/test-*.sh在真机 node 容器内 39/39 PASS、0 FAIL;
e2e 容器自检(e2e-container-selftest.sh)PASS。 - 认证插件注入链路端到端实测:插件段与
alpha.4/rc.2/alpha.2/rc.1
五方逐字节一致(8 行 / 163 字节);真实启动带 cookie 访问200、未认证 API403。 - 本地沙箱因
/data/dsh不可写而有环境性失败(spill-local的 EACCES 历次都有,
已确证与本次改动无关)。
v0.6.8-dsh-0.2.2-rc.1
Changed
- DSH 升级到
0.2.2-rc.1(Dockerfile的ARG DSH_VERSION),从0.2.2-alpha.2的
alpha 线回到 rc 线。这次是上一轮承诺的兑现:当时锁 alpha 的无奈是 0.2.2 还没有 rc,
现在 rc 出来了,于是稳定性回正。- 既前进又更稳:跨过了
alpha.3(0.2.2-rc.1>0.2.2-alpha.3,同数字段下 rc 高于
alpha),发布时间也更晚(rc.1= 11-04,alpha.3= 11-03)。 - ✅ 本次锁定的版本同时就是
latest(也是next) —— 项目历史上第一次锁到上游的
稳定推荐版本体,而不是"最新预览"。但结论不变:仍要写全版本号,因为latest是会漂移的别名。 - ✅
--public-url仍在:chunk 名与历次完全相同(public-url-D_dMK-yI.js),
parsePublicUrl仍在dsh-web-app的startup.js/index.js;真实启动实测打印带 token 的地址。 - 无会话/设置数据换代:
SESSION_FORMAT_VERSION两版均为 4、迁移包集合完全相同
(catalog+v0-to-v1..v3-to-v4,无新增)→ 本次升级不需要备份会话。 - 包级 +3 / −3(331 → 331,总数不变、内容流动):
- 新增
dsh-client-ui-context-menu、dsh-client-ui-file-actions(这两个会真正装载,
进dsh-web-app)、dsh-fs-patch(不装载,两个 bundle 的 patch 里都没有它); - 移除
dsh-computer-use/dsh-cua/dsh-cua-bundle—— 上游撤掉了整个 cua 子系统。
这三个包此前就没有被本项目装载,故移除对本项目零影响。
(这一条值得记住:包级"移除"≠"能力移除",要看它是否曾被装载。)
- 新增
- 渲染配置差异仅 13 行(1230 → 1243 行,条目 300 → 302):新增
ui-context-menu、
ui-file-actions两个条目;既有tool-fs上新增applyPatch: false(共 4 处:顶层 1 +
嵌套 3,是上游新引入的默认关闭开关,dsh-fs-patch的能力开关,本项目未启用)。
零移除、零其它修改,本项目对以上引用数均为 0。 hmr条目逐字节相同;nodeLinker: hoisted、CLI 透传、--patch语义(实测生效)、
--dump-*选项均未变。RETIRED_BUNDLES内容不变(仍只含 schedule-bundle),
注意它自 alpha.2 起已迁到新包dsh-official-bundles,在旧位置 grep 不到不等于被删除。- GUI 认证行为与上一轮一致,无新增变化:裸访问
401、带 token303下发 cookie、
cookie 访问200、未认证 API403—— 四项实测与 alpha.2 完全相同,故本轮不需要再改
用户访问指引(上一轮已在 CHANGELOG 与 docs/03 说明)。健康检查仍不受影响。
- 既前进又更稳:跨过了
Verified
- 真机(Docker 29.1.3)构建并全硬化启动:只读根 FS +
--cap-drop ALL
(仅补 CHOWN/DAC_OVERRIDE/FOWNER/SETUID/SETGID)+no-new-privileges+ 三卷挂载
→ 容器Up (healthy),启动日志零 warning / 零 error,首启一次到位(无 EACCES、
无 lifeboat、无需手动重启),seed→卷升级链路正确,镜像内 seed 自证0.2.2-rc.1。 - 全量门禁
scripts/t/test-*.sh在真机 node 容器内 39/39 PASS、0 FAIL;
e2e 容器自检(e2e-container-selftest.sh)PASS。 - 认证插件注入链路端到端实测:插件段与
alpha.4/rc.2/alpha.2四方逐字节一致
(8 行 / 163 字节);真实启动后带 cookie 访问200、未认证 API403。 - 本地沙箱因
/data/dsh不可写而有环境性失败(spill-local的 EACCES 历次都有,
已确证与本次改动无关)。
v0.6.7-dsh-0.2.2-alpha.2
Changed
- DSH 升级到
0.2.2-alpha.2(Dockerfile的ARG DSH_VERSION),从0.2.1-rc.2的
rc 线回到 alpha 线,同时跨入新的 0.2.2 数字段。性质是「数字段前进 + 稳定性退一步」:
按 semver0.2.2-alpha.2>0.2.1-rc.4>0.2.1-rc.2(0.2.2>0.2.1是前进),
但0.2.2数字段目前只有 alpha(0.2.2-alpha.1上游从未发布,实测 npm 404),
要跟新数字段就只能走预览线。若更看重稳定性可覆盖DSH_VERSION到0.2.1-rc.4。
完整逐契约分析见docs/analysis/2026-10-29-dsh-0.2.2-alpha.2-适配分析.md,要点:- ✅
--public-url仍在(跟随的前提):chunk 名与上一轮完全相同
(public-url-D_dMK-yI.js)、parsePublicUrl仍在dsh-web-app的startup.js/index.js;
真实启动实测打印带 token 的对外地址。跟随新版不会失去当初锁 alpha 要拿的能力。 - 无会话/设置数据换代:
SESSION_FORMAT_VERSION两版均为 4、迁移包集合完全相同
(catalog+v0-to-v1..v3-to-v4,无新增)→ 本次升级不需要备份会话。 RETIRED_BUNDLES内容不变(仍只含@deepseek-ai/dsh-experimental-schedule-bundle,
本项目零引用),但迁到了新包dsh-official-bundles(由dsh-app-boot再导出)。
属结构性重构、语义等价 —— 核对时别因"旧位置 grep 不到"误判成被删除。- 包级 +26 / −1(306 → 331),但只有 6 个新增包会真正装进本项目(出现在
dsh-base/dsh-web-app的 bundle patch 内):dsh-tool-executor-native、
dsh-tool-executor-ptc(进dsh-base)、dsh-message-quotes、dsh-client-ui-file-drag、
dsh-deliverable-file-references、dsh-client-ui-entry-customization(进dsh-web-app)。
其余 20 个(forge / liveshare / cua / recommendations / plugin-* 等)是可选或实验 bundle,
本项目 profile 只列dsh-base+dsh-web-app,故不装载。
移除的dsh-client-ui-deepseek-model-label-1017是上游回退了上一版新增的模型标签,本项目零引用。 - 渲染配置差异 45 行(1229 → 1230 行,条目 299 → 300),全部可解释:新增上述 6 个包对应的 7 个渲染条目(
tool-executor-ptc出现 2 处);
tool-presentation(mode: ptc)→ 被tool-executor-ptc取代(能力重构);
tool-subagent-list-agents子条目被上游移除(包本体仍在,属产品决策);
modelSelectionSettings: true→ 拆成modelSelection+modelDiscovery;
移除ui-deepseek-model-label-1017。本项目对以上全部引用数为 0。 hmr条目逐字节相同;nodeLinker: hoisted未变;CLI 透传未变;--patch语义未变
(对既有settings行实测生效);--dump-*选项均在。
- ✅
⚠️ 新版改变了 GUI 的访问方式(安全加固,用户可见):对不带 token 的访问,由200
改为返回401(正文dsh web authentication required; reopen the URL printed by dsh web.);带 token 访问返回303并下发HttpOnly+SameSitecookie,之后靠 cookie
正常使用(200)。不能再用裸地址直接打开 GUI。
已实测不阻断容器场景:token 不绑定 Host authority,经 socat 从宿主地址访问同样303
成功、随后 cookie 请求200;设了DSH_PUBLIC_URL时日志打印的是对外地址 + token
(可直接点开),未设时从docker logs取 token 换宿主地址访问即可。
健康检查不受影响:HEALTHCHECK是 TCP 探测;scripts/probe-ready.js的 L2 明确注释
「任何状态码都算 HTTP 栈就绪」,且 L4 的四个启动失败标志都不匹配 401 正文(已实测核对)。
Verified
- 真机(Docker 29.1.3)构建并全硬化启动:只读根 FS +
--cap-drop ALL
(仅补 CHOWN/DAC_OVERRIDE/FOWNER/SETUID/SETGID)+no-new-privileges+ 三卷挂载
→ 容器Up (healthy),启动日志零 warning / 零 error,首启一次到位(无 EACCES、
无 lifeboat、无需手动重启),seed→卷升级链路正确,镜像内 seed 自证0.2.2-alpha.2。 - 全量门禁
scripts/t/test-*.sh在真机 node 容器内 39/39 PASS、0 FAIL;
e2e 容器自检(e2e-container-selftest.sh)PASS。 - 认证插件注入链路端到端实测:插件段与
alpha.4/rc.2均逐字节一致(8 行 / 163 字节)。 - 本地沙箱因
/data/dsh不可写、缺node而有环境性失败(spill-local的 EACCES 在
rc.2下同样出现,已确证与本次改动无关)。
v0.6.6-dsh-0.2.1-rc.2
Changed
- DSH 换线到
0.2.1-rc.2(Dockerfile的ARG DSH_VERSION),从0.2.1-alpha.4的
alpha 线换到 rc 线。这不是同线小版本前进,而是一次换线,但方向是前进:
按 semver 数字段0.2.1-rc.2>0.2.1-alpha.4(同数字段下 rc 高于 alpha),
且rc.2发布于 2026-10-17、晚于alpha.5(10-16)—— rc 线是从 alpha 线转正而来。
按稳定性线 alpha < rc,本次同时提升了稳定性。
完整逐契约分析见docs/analysis/2026-10-18-dsh-0.2.1-rc.2-适配分析.md,要点:- ✅ 换线的前提:
--public-url已在 rc 线可用。此前该能力只在 alpha 线可用,故本项目
一直锁 alpha;本次实测确认它已随0.2.1转正进入 rc 线 —— chunk 名与 alpha 线完全相同
(public-url-D_dMK-yI.js)、parsePublicUrl仍在dsh-web-app的startup.js/index.js,
项目侧守卫rescue_supports_public_url判定0.2.1-rc.2为支持,真实启动实测打印 token。 - 无会话/设置数据换代:
SESSION_FORMAT_VERSION两版均为 4、迁移包集合完全相同
(catalog+v0-to-v1..v3-to-v4,无新增)→ 本次升级不需要备份会话。这与 0.1.6→0.1.7
那次的「V3→V4 单向迁移、必须备份」性质根本不同,勿套用旧结论。 - 包级 +2 / −0(304 → 306)。新增的 2 个包进的是本项目实际装载的 bundle,故会生效:
dsh-web-deepseek-api(进dsh-base,为ctx.web提供 DeepSeek 搜索/抓取 provider)、
dsh-client-ui-deepseek-model-label-1017(进dsh-web-app,UI 模型标签)。均为
纯功能增强、非破坏性,本项目对其内部 API 的引用数为 0。 - 渲染配置差异仅 6 行(1223 → 1229),全部是上述 2 个新条目的新增 —— 零移除、零修改。
RETIRED_BUNDLES未变(仍只含@deepseek-ai/dsh-experimental-schedule-bundle,本项目零引用);
hmr条目逐字节相同;nodeLinker: hoisted未变;CLI 透传(allowUnknownOption/
passThroughOptions)未变;--patch叠加层语义未变(对既有settings行实测生效);
三个--dump-*选项均在。- ⚠ 仍不是
latest:latest仍指向0.2.0-rc.2(旧的0.2.0数字段)。若只要绝对稳定、
可接受失去--public-url,可覆盖DSH_VERSION回退到0.2.0-rc.2。
- ✅ 换线的前提:
- 本项目核心耦合点(认证插件注入链路)已端到端实测:profile bundles 加
@xgone/dsh-remotecordis.patch.yml写- id: remote覆盖config,在rc.2下渲染出的插件段与alpha.4
逐字节一致(8 行 / 163 字节);真实启动打印访问 token,HTTP 认证边界同为
登录页200/ 未认证 API403。
Verified
- 真机(Docker 29.1.3)构建并全硬化启动:只读根 FS +
--cap-drop ALL
(仅补 CHOWN/DAC_OVERRIDE/FOWNER/SETUID/SETGID)+no-new-privileges+ 三卷挂载
→ 容器Up (healthy),启动日志零 warning / 零 error,首启一次到位(无 EACCES、
无 lifeboat、无需手动重启),seed→卷升级链路正确,镜像内 seed 自证0.2.1-rc.2。 - 全量门禁
scripts/t/test-*.sh在真机 node 容器内 39/39 PASS、0 FAIL;
e2e 容器自检(e2e-container-selftest.sh)PASS。 - 本地沙箱因
/data/dsh不可写、缺node而有环境性失败,已用git stash在未改动代码上
复现同样失败,确证与本次改动无关。
v0.6.5-dsh-0.2.1-alpha.4
Changed
- DSH 升级到
0.2.1-alpha.4(Dockerfile的ARG DSH_VERSION)。这是0.2.1-alpha.3→
0.2.1-alpha.4的同线小版本前进,锁 alpha 线的动机(拿到--public-url)不变。
完整逐契约分析见docs/analysis/2026-10-16-dsh-0.2.1-alpha.4-适配分析.md,要点:- 无会话/设置数据换代:
SESSION_FORMAT_VERSION两版均为 4、迁移包集合完全相同
(catalog+v0-to-v1..v3-to-v4,无新增)→ 本次升级不需要备份会话。这与 0.1.6→0.1.7
那次的「V3→V4 单向迁移、必须备份」性质根本不同,勿套用旧结论。 - 渲染配置差异仅 9 行、能力面零变化:1214 → 1223 行,全部差异是新增的
tool-plugin-market禁用行(3 处均为disabled: true或条件禁用),与既有的
tool-plugin-manager形态完全一致 —— 零移除、零其它变化。这是历次升级中渲染差异最干净的一次。 - 包级 +4 / −3 = 净增 1(303 → 304)。新增 4 个包是上游新的可选「插件市场」子系统
(dsh-plugin-market/dsh-plugin-market-index/dsh-client-ui-plugin-market/
dsh-experimental-plugin-market-bundle),均不在dsh-base或dsh-web-app的 bundle patch
内,本项目 profile 只列这两个 bundle,故不会装载(引用数 0);移除的 3 个包
(dsh-client-store/dsh-client-ui-primitives/dsh-client-ui-slots)在本项目引用数均为 0。 --public-url续存:选项仍在,且是同一份parsePublicUrl模块(chunk 名
public-url-D_dMK-yI.js两版一致)。RETIRED_BUNDLES未变(仍只含@deepseek-ai/dsh-experimental-schedule-bundle,本项目零引用);
hmr条目逐字节相同;nodeLinker: hoisted未变;CLI 透传(allowUnknownOption/
passThroughOptions)未变;--patch叠加层语义未变(对既有settings行实测生效);
三个--dump-*选项均在。- ⚠ 本次新增包全部为可选、默认禁用,无模型可见变化(与上次 alpha.3 引入
harness-dev-context不同)。
- 无会话/设置数据换代:
- 本项目核心耦合点(认证插件注入链路)已端到端实测:profile bundles 加
@xgone/dsh-remotecordis.patch.yml写- id: remote覆盖config,在 alpha.4 下渲染出的插件段与 alpha.3
逐字节一致(8 行 / 163 字节);两版真实启动均成功并打印访问 token,HTTP 认证边界同为
登录页200/ 未认证 API403。
Verified
- 真机(Docker 29.1.3)构建
dsh-alpha4:test并全硬化启动:只读根 FS +--cap-drop ALL
(仅补 CHOWN/DAC_OVERRIDE/FOWNER/SETUID/SETGID)+no-new-privileges+ 三卷挂载
→ 容器Up (healthy),启动日志零 warning / 零 error,首启一次到位(无 EACCES、
无 lifeboat、无需手动重启),seed→卷升级链路正确,镜像内 seed 自证0.2.1-alpha.4。 - 全量门禁
scripts/t/test-*.sh在真机 node 容器内 39/39 PASS、0 FAIL;
e2e 容器自检(e2e-container-selftest.sh)PASS。 - 本地沙箱因
/data/dsh不可写、缺node而有 22 项环境性失败,已用git stash在未改动
代码上复现同样失败,确证与本次改动无关。
v0.6.4-dsh-0.2.1-alpha.3
Changed
- DSH 升级到
0.2.1-alpha.3(Dockerfile的ARG DSH_VERSION)。这是0.2.1-alpha.2→
0.2.1-alpha.3的同线小版本前进,锁 alpha 线的动机(拿到--public-url)不变。
完整逐契约分析见docs/analysis/2026-10-15-dsh-0.2.1-alpha.3-适配分析.md,要点:- 无会话/设置数据换代:
SESSION_FORMAT_VERSION两版均为 4、迁移包集合完全相同
(catalog+v0-to-v1..v3-to-v4,无新增)→ 本次升级不需要备份会话。这与 0.1.6→0.1.7
那次的「V3→V4 单向迁移、必须备份」性质根本不同,勿套用旧结论。 - 本次是历次升级中变更面最小的一次:包级 净增 3、移除 0(上次是 +15/−6);
渲染条目按- id:精确对照只有新增、零移除。 --public-url续存:选项仍在,且是同一份parsePublicUrl模块(chunk 名
public-url-D_dMK-yI.js两版一致);真实dsh web启动实测打印访问 token。hmr条目逐字节相同;RETIRED_BUNDLES仍只含schedule-bundle,本项目
web/lifeboat profile 只列dsh-base+dsh-web-app,零引用。- ✅ 本项目核心耦合点(认证插件注入链路)已端到端实测:按项目真实方式(profile
bundles加@xgone/dsh-remote+cordis.patch.yml写- id: remote覆盖 config)
在两版上分别验证 —— 渲染出的插件段逐行一致,--dump-config均退出 0、bootstrap
凭据正确注入;宿主进程实测(配 bootstrap 凭据)无凭据 401 / 带 token 303。
真容器内实测(默认配置)登录页 200 / 未认证 API 403,两版一致。 - 新增 3 个包(均在对应 bundle 中默认生效):
dsh-api-remote-access(进dsh-base)、
dsh-client-ui-secret-mask与dsh-harness-dev-context(进dsh-web-app)。本项目对三者
引用数均为 0。 - ⚠ 唯一模型可见的变化:
harness-dev-context让模型得知容器内 dsh checkout 路径与 Web GUI
公开 URL。评估为可接受 —— 该路径容器内本就可读(dsh 自己跑在那儿)、公开 URL 正是本项目
已通过DSH_PUBLIC_URL主动公告的信息,且它不改写系统提示。要关闭可在 profile 的
cordis.patch.yml写- id: harness-dev-context+disabled: true(本项目当前不做,仅备查)。 - ⚠ 上游另新增 base 条目
remote-access(@deepseek-ai/dsh-api-remote-access,非 owner Peer
的方法级访问控制)—— 与本项目注入的id: remote(@xgone/dsh-remote密码+MFA 认证)是
两个不同的东西、id 不同、无冲突,且 owner 永远不被检查,单用户容器部署无行为影响。
升级时勿混淆二者。 - ⚠ plan mode 结构性重构(对本项目零影响):组 id
plan-mode→planning,组内新增
tool-fs显式声明(read/write/edit: false、readImage: true)与compaction子组,
并移除 plan mode 对schedule_*的 6 处toolFilter.deny(该 bundle 已退休,无需再屏蔽)。
方向是把隐式提示词约束改为显式声明(收紧),不是放开。
注:toolFilter机制本身未从 alpha.3 移除(仍用于子代理ToolRestriction),
消失的只是 plan mode 的那 6 处 deny —— 勿得出"上游删了 toolFilter"的错误结论。 - ⚠ 稳定性线未变:本镜像仍在 alpha 线(
latest/next仍指向0.2.0-rc.2)。 - ⚠
DSH_PUBLIC_URL_MIN_VERSION刻意保持0.2.1-alpha.1不变:它是--public-url的
能力起点("该选项从哪个版本开始存在"),与本 ARG 的"当前锁定版本"语义不同。跟着升会让
"卷内 dsh 为alpha.1/alpha.2"的用户被守卫误判为不支持而静默失去地址公告。
同理,docs/07中英、.env.example、docker-compose.yml及test-public-url-guard.sh
里描述该下限的内容均未改动。
- 无会话/设置数据换代:
Verified
- 真机(192.168.1.88:3333,真 Docker 29.1.3)构建 + 全硬化运行 + 对照验证:
- 构建镜像
dsh-alpha3:test(docker build --build-arg DSH_VERSION=0.2.1-alpha.3)成功。 - seed 版本自证:
docker run --entrypoint /opt/dsh-seed/bin/dsh dsh-alpha3:test --version
→0.2.1-alpha.3;pnpm →12.5.1;镜像内认证插件 seed →@xgone/dsh-remote@0.3.5。 - 全硬化下可运行:
--read-only+--tmpfs /tmp:size=128m,exec+--cap-drop ALL+
5 项最小cap_add+no-new-privileges+ 三个卷(/opt/dsh、/data/dsh、/workspace)
→Up (healthy),启动日志零警告零错误。 - 首启一次到位:
boot attempt 1/4 (profile=web)→dsh healthy on 127.0.0.1:3081,
无 EACCES、无 lifeboat、无需手动 restart(上期修复的属主收尾在 alpha.3 下继续有效)。 --public-url端到端打通:[entrypoint] public URL: https://dsh.example.com (dsh 0.2.1-alpha.3)。- HTTP 认证边界:容器内探测
index→ 200(登录页)、api→ 403(未认证被拦截)。 - ✅ 同代码严格对照(用同一份仓库代码、只换
DSH_VERSION构建dsh-alpha2-ctrl:test):
alpha.2 与 alpha.3 在 首启进度、健康状态、--public-url公告、HTTP 认证边界(200/403)
上完全一致 —— 证明本次升级未改变部署行为。 - ✅ seed→卷升级链路:用 alpha.2 写过的卷 + alpha.3 镜像启动,日志显示
seeding dsh into /opt/dsh (image seed 0.2.1-alpha.3 > volume 0.2.1-alpha.2)→
effective=0.2.1-alpha.3→healthy。"镜像升级携带 dsh" 机制继续有效。
- 构建镜像
- 全量门禁 39/39 全绿(真机 + node 容器内执行):含
test-dsh-version-pin.sh对
"ARG / README 徽章 / docs03 表 / CHANGELOG 段"四处版本号同步性的强制校验。 - 静态契约核对:16 项耦合契约逐项通过(见分析文档 §三),阻断 0 / 高风险 0;
两版本隔离安装对照(包数 300 → 303,净增 3、移除 0;渲染条目按- id:精确对照
只有新增、零移除)。
v0.6.3-dsh-0.2.1-alpha.2
Changed
- DSH 升级到
0.2.1-alpha.2(Dockerfile的ARG DSH_VERSION)。这是0.2.1-alpha.1→
0.2.1-alpha.2的同线小版本前进,锁 alpha 线的动机(拿到--public-url)不变。
完整逐契约分析见docs/analysis/2026-10-10-dsh-0.2.1-alpha.2-适配分析.md,
要点:- 无会话/设置数据换代:
SESSION_FORMAT_VERSION两版均为 4、迁移包集合完全相同
(v0..v4五个,无新增)→ 本次升级不需要备份会话。这与 0.1.6→0.1.7 那次的
「V3→V4 单向迁移、必须备份」性质根本不同,勿套用旧结论。 --public-url续存:选项仍在,且是同一份parsePublicUrl模块(chunk 名
public-url-D_dMK-yI.js两版一致);真实dsh web --public-url https://…启动实测
打印dsh web: https://…/?token=…,公告行为正常。hmr条目逐字节相同;RETIRED_BUNDLES仍只含schedule-bundle,本项目
web/lifeboat profile 只列dsh-base+dsh-web-app,零引用。- 上游移除 6 个包(
dsh-webhook、dsh-webhook-github、dsh-hooks-claude-code、
dsh-hooks-codex、dsh-hook-protocol、dsh-subagent-in-process-driver)——
逐一 grep 确认本项目引用数均为 0。 - ⚠ 唯一能力面变化:
dsh-base新增两条默认生效条目working-directory+
tool-working-directory(后者给模型一个cd工具)。评估为可接受 —— 它只改"当前目录",
不绕过ctx.fs的 workspace 围栏,且容器内 dsh 本就可读写/data/dsh。已记入分析文档备查。 - ⚠ 稳定性线未变:本镜像仍在 alpha 线(
latest/next仍指向0.2.0-rc.2)。 - ⚠
DSH_PUBLIC_URL_MIN_VERSION刻意保持0.2.1-alpha.1不变:它是--public-url的
能力起点("该选项从哪个版本开始存在"),与本 ARG 的"当前锁定版本"语义不同。跟着升到
alpha.2会让"卷内 dsh 恰为 alpha.1"的用户被守卫误判为不支持而静默失去地址公告。
同理,docs/07中英、.env.example、docker-compose.yml里描述该下限的注释均未改动。
- 无会话/设置数据换代:
Verified
- 真机(192.168.1.88,真 Docker 29.1.3)构建 + 运行,镜像
dsh:a2:- 镜像内 seed 版本自证:
docker run --entrypoint /opt/dsh-seed/bin/dsh dsh:a2 --version
→0.2.1-alpha.2;pnpm →12.5.1。 - 全硬化下可运行:
--read-only+--tmpfs /tmp:size=128m,exec+--cap-drop ALL+
4 项最小cap_add+no-new-privileges+ 三个卷(/opt/dsh、/data/dsh、/workspace)
→Up (healthy),web profile 正常启动,HTTP 可访问。 --public-url端到端打通:日志
[entrypoint] public URL: https://dsh.example.com (dsh 0.2.1-alpha.2),
且 dsh 自身打印dsh web: https://…/?token=…。- ⚠ 验证机为嵌套 DinD,
mem_limit/cpus无法应用(cgroupv2 threaded mode),
故运行验证剔除了这两项资源限制、保留其余全部硬化 —— 与本项目配置无关(二分实测)。
- 镜像内 seed 版本自证:
- 真机观察到的首启缺陷已定位并修复(原"既有现象"记录,归属判定与 alpha.2 无关):
首次启动时 entrypoint 以 root 写/data/dsh/profiles/web/cordis.patch.yml(mode 0600),
降权后 uid 1000 的 dsh 读不了它(EACCES: failed to read overlay …)→ 自愈耗尽 →
lifeboat 标记 → 自动重启后停在 lifeboat,需手动docker restart dsh一次才回到
web profile;与docs/zh-CN/01-快速开始.md的"首次启动秒级就绪"承诺有出入。
归属判定依据:两版dsh-app-boot的loadOverlayPatches代码路径完全相同(均
readFileSync失败即throw),且写/读该文件的都是本项目脚本(remote-setup.sh/
entrypoint.sh),不随 dsh 版本变化 —— 属既有缺陷,非本次升级引入。
已在紧随其后的提交修复(entrypoint 新增 ⑤c 在降权前就地收尾属主 + 新增门禁
test-entrypoint-ownership.sh,真机对照验证 EACCES/lifeboat 均归零、首启一次进 web)。
Added
- Cloudflare Tunnel 可选接入层
docker-compose.cloudflare.yml(补"家庭宽带无公网 IP"这个缺口)。
既有远程方案只有两条路:SSH 隧道(临时、单人)与反向代理 + HTTPS(需要域名解析到主机、
且入站 80/443 可达)。两者都默认"你这台机器在公网上够得着"—— 而 CGNAT / 大内网里的
家庭宽带根本没有可入站的公网 IP,端口转发也无从谈起,于是这类用户此前只能退回局域网。
新覆盖文件补上第三条路:由cloudflared主动出站连 Cloudflare 边缘并建立长连接,
公网流量从这条已建立的隧道回源 —— 全程不需要任何入站端口、不需要公网 IP、不需要动路由器。- 这是"附加层",不是"覆盖层":文件只新增一个
cloudflared服务,不改写主 compose
的任何字段(image/ports/command等一字未动),主 compose 的行为保持不变。
门禁专门断言了这一点:覆盖文件里若声明dsh,只允许networks/depends_on/extra_hosts
这类纯接线键。之所以不禁止覆盖文件写dsh,是因为给既有服务追加网络本就是覆盖文件的
常规用法,初版写成"禁止出现 dsh"会对合法写法误报 —— 门禁误报会逼人删掉真需求,比漏报更糟。 - 网络靠"同一个 compose 项目"打通,刻意不定义
networks:两个-f一起传入时
compose 合并成同一个 project(项目名取第一个-f文件所在目录),cloudflared 因此自动
加入主 compose 创建的网络,直接用服务名dsh即可访问。⚠ 反过来若在本文件里另起
networks,很可能新建出第二个网络,症状是隧道注册成功但公网 502。
- 这是"附加层",不是"覆盖层":文件只新增一个
- "默认不部署"由 compose
profiles: [cloudflare]门控。不带--profile cloudflare时,
上游快速开始里那条docker compose up -d连容器都不会创建(用默认路径的用户零影响),
要启用须显式--profile cloudflare。- 为什么用 profiles,而不是把 cloudflared 塞进主 compose:主 compose 一个 profile 都没有,
塞进去等于给所有用户强加一个默认启动的外部依赖(还得额外拉云厂商镜像),与"可选"直接冲突;
加上 cloudflared 与 dsh 的生命周期、升级节奏、失败域完全不同 —— 隧道挂了不该连累 dsh,
dsh 升级也不该顺带重建隧道容器。独立文件 + profile 之后,未配 token 的用户零影响。 - 精确边界(照抄官方文档的口径,不要记反):compose-spec 的 15-profiles.md 原文是
「服务在没有任何 profile 命中时被 compose 忽略,除非该服务被命令显式点名」。
所以"默认不部署"的准确含义是「照常跑docker compose up -d不会起它」,
不是"任何写法都不会起它":up -d cloudflared或--profile cloudflare up -d cloudflared
同样会把它拉起来。门禁把 (a) 不点名不带 profile → 不启动、(b) 显式点名 → 启动、
(c)--profile cloudflare→ 启动、(d) 无关 profile → 仍不启动四条全断了:
只断 (a) 会漏掉"有人把 profiles 写成恒真"的退化,只断 (b) 会漏掉边界本身。 - ⚠
restart: unless-stopped只保证"容器已存在时"开机自恢复,不会让一份没被启用的
compose 在重启后突然拉起 cloudflared —— 这一点容易被误读,故在文件头与文档里都写明了。
- 为什么用 profiles,而不是把 cloudflared 塞进主 compose:主 compose 一个 profile 都没有,
TUNNEL_TOKEN用:-兜底而非:?强校验(本次最容易改错的一行,取舍写在这里)。
验证版用的是TUNNEL_TOKEN=${TUNNEL_TOKEN:?…},那在测试包里是合理的(单文件、专用场景、
就是要"没配 token 就当场报错"),但进了本仓库必须改。依据是 compose-spec 规范原文而非猜测:- 插值早于 profile 过滤(决定性的一条):12-interpolation.md 写明变量替换适用于 compose
文件里任何值,且在按文件合并之前就已应用 —— 即插值属于"读文件、构建 project model"
这一步,而不是"决定起哪个容器"那一步。后果:哪怕压根没打算开隧道,只要命令行挂了
-f docker-compose.cloudflare.yml,config/ps/up -d都会因缺 token 而失败,
把"忘了配 token"这个只该影响隧道的失误升级成"整个 compose 命令都跑不动"。 - 空值同样触发,且更隐蔽:同一节写明
:?的判据是"未设置或为空",
于是从模板复制却没填干净的TUNNEL_TOKEN=也会报错,而用户会以为 dsh 坏了。
实际部署里这比"完全没写"更常见。 :-在两种实现下都安全:${VAR:-}在未设置时求值为空串,两边都不报错 ——
不依赖"未启用 profile 的服务是否被插值"这一实现细节,属纯保守选择。- 代价可控且有兜底:value 写成空串而不是省略该行,让 cloudflared 自己去报
"token 为空 / unauthorized",比让 compose 报一个跟隧道无关的错更好定位;
且隧道起不来时restart: unless-stopped会持续重试但dsh 完全不受影响(失败域隔离)。
想要旧强校验体验的用户,正确做法是在调用侧加前置检查,而不是把:?改回去
(那会波及所有用户)—— 文件头 §3 给出了那行grep -E '^TUNNEL_TOKEN=.+'示例。
- 插值早于 profile 过滤(决定性的一条):12-interpolation.md 写明变量替换适用于 compose
- 门禁测试
scripts/t/test-cloudflare-tunnel.sh(已纳入 CI)。它守的是"沉默的边界回退":
profiles:看起来只是几行 YAML,删掉/改名之后docker compose up -d仍然成功、容器照跑、
功能全对,只有对外暴露面没了 —— 正是test-compose-wiring.sh顶部记的那类教训(门禁恒绿而边界已失)。
断言覆盖:profiles键存在且值精确等于cloudflare(写成cf会让文档里的
--profile cloudflare静默启不动,故要求精确而非包含)、profiles 块内无额外 profile 名、
cloudflared段无ports映射、镜像为官方cloudflare/cloudflared、command 含
--no-autoupdate(容器内自更新会让"镜像 tag"与实际运行版本错位)、TUNNEL_TOKEN/TZ已注入、
段内 零:?引用、以及主 compose 不得出现cloudflared。CI 无需额外登记:
docker-image.yml的 unit-tests job 以for f in scripts/t/test-*.sh通配执行。- 反恒真与反误报同等重要:脚本里写了三处"反向护栏",确保断言不是"在空气上做检查"
(文件读不到、服务段被切空、主 compose 读不到时都必须报红而非通过);
"默认不部署"那条改成对 profiles 语义做离线求值的 node 断言 —— 因为 CI 的 unit-tests job
跑在 bare shell 上(没有 docker daemon),任何依赖docker compose的断言都会退化成
"命令不存在 → 跳过 → 恒绿",比没有门禁更危险。 - YAML 解析降级是显式的:本仓库无 YAML 依赖(实测
require('js-yaml')报
Cannot find module)、宿主无 python3,故默认走"按缩进切出服务段后逐行精确匹配"的文本断言;
解析器可得时才附加真结构校验,不可得时打印[DROP]提示明确宣告"哪些校验没做"。
静默跳过校验再打印 ALL-PASS 属于"假装验证通过",是本项目明确禁止的行为。
- 反恒真与反误报同等重要:脚本里写了三处"反向护栏",确保断言不是"在空气上做检查"
- 文档同步:
docs/02中英新增 Cloudflare Tunnel 章节(访问方式总览里补一行,
让"无公网 IP"不再是三条既有路径都覆盖不到的空白);TUNNEL_TOKEN与CF_CONTAINER_NAME/
CF_MEM_LIMIT/CF_CPU_LIMIT/CF_PIDS_LIMIT登记进.env.example与docs/07中英。- 与既有方案的关系:它不改也不取代反向代理方案 —— 有公网 IP 的用户继续用 Caddy
(TLS 与证书在自己手里,不经第三方);隧道方案是给"确实入不了站"的人的第二条路,
代价是把边缘交给 Cloudflare、且隧道内是明文 HTTP(TLS 在 Cloudflare 边缘终结)。 - 安全前提写进了文档而非只写代码:公网暴露前须确认
DSH_SETUP_REMOTE=on
(这是公网暴露唯一的认证防线)并在首次登录后立刻开启 MFA;.env保持 600 且
TUNNEL_TOKEN绝不进 git(token 泄露 = 别人能把流量引到自己的源站);
建议填DSH_PUBLIC_URL=https://<域名>/否则日志与给模型的系统提示仍指向容器内地址;
不要填DSH_TRUSTED_HOSTS(已装 dsh-remote 时其 trustProxy 会把 Host 归一为 loopback,
隧道域名天然放行)。另注明 Cloudflare Access 属 Zero Trust、需绑卡,不想绑卡可用免费 WAF
速率限制,且隧道本身与 Zero Trust 是两个独立产品,跑隧道无需绑卡。
- 与既有方案的关系:它不改也不取代反向代理方案 —— 有公网 IP 的用户继续用 Caddy
Notes
- 验证状态与尚未覆盖的边界:
- 隧道链路本身已于 2026-10-09 在真机全流程验证通过(Cloudflare 自建域名 + Docker):
建隧道 → 填http://dsh:3080路由 →Registered tunnel connection→ 公网可访问。
§2 记的 Service URL 三个坑(必须带协议前缀、服务名必须是dsh而不是 localhost、
端口必须是 socat 的 3080 而不是只绑回环的 3081)以及"新版 Dashboard 里选
Published application而非Private hostname""拿 token 要把 OS 手动切成 Docker"
都是那轮实测踩出来的。 - 本文件相对验证版做的两处改造 ——
profiles门控与:?→:-—— 同样已在真机验证通过:
docker compose config真跑过,profiles门控的四种行为边界(不带 profile 不启动 /
--profile cloudflare启动 / 显式点名启动 / 无关 profile 不启动)与:-在 token 缺失、
token 为空两种情形下均不报错,都已实测确认。故"结论不依赖『未启用 profile 时是否跳过插值』"
这一判断已由实测背书,而不只是规范推理;依据 compose-spec 原文的那段论证(文件头 §3)
予以保留,作为"为什么这样选"的记录而非唯一依据。 docker compose config已在真机实跑(不再是"本机无 docker"的推理):上述两处改造均经过
真实的 compose 解析与启动验证。CI 侧的test-cloudflare-tunnel.sh仍是纯文本/离线求值断言,
它守的是回归——防止后人删掉profiles这类"功能全对、只有边界没了"的沉默回退——
与真机验证是互补关系,不是替代关系。- 容器硬化已开到与 dsh 服务同级,并已真机实测:
no-new-privileges:true(纯保险)之外,
read_only: true/tmpfs: /tmp:size=32m/cap_drop: [ALL]三项原本以注释形式保留
(当时担心官方镜像会写~/.cloudflared或临时目录),现已逐项验证通过并默认生效:
容器 inspect 实测ReadonlyRootfs=true、CapDrop=[ALL]、Tmpfs=map[/tmp:size=32m],
同时日志有 4 条Registered tunnel connection、CONNECTIVITY PRE-CHECKS全 PASS,
全程无read-only file system/permission denied—— "配置生效"与"功能未退化"两头都验到了。
结论:token 模式下 cloudflared 不写根 FS(凭据只从TUNNEL_TOKEN读,不走需落盘的
cert.pem 流程),且不需要任何 capability。⚠ 日后升级镜像若启动失败,按注释里的回退手法
二分定位(报写盘错误 = 给它一个具体可写卷,而不是整体放弃硬化)。 - ⚠ 未验证的还有:本项目未在除上述单机之外的环境(不同 NAS、不同 compose 版本、
podman-compose 等)验证过;depends_on: service_healthy意味着首次up -d时
cloudflared 可能要等几分钟(dsh 的 healthcheck 带start_period: 300s),这是预期行为而非故障。 - 改动范围限定在隧道这一层:
docker-compose.yml一字未动;scripts/下无任何改动
(隧道不需要碰 entrypoint)。本 Unreleased 段同时收录的另外两部分与本条不是同一批工作:
(a) 上一个提交f8aedc7的DSH_PUBLIC_URL对外地址公告(涉及entrypoint.sh、
librescue.sh、rescue-supervise.sh与 5 个门禁脚本),当时未发版,故仍停留在本段;
(b) 由本批带来的文档改动 —— 两个 README 的远程访问描述、docs/02中英的隧道章节、
docs/07中英的变量登记。上述 (a) 的正文见该提交信息与[v0.6.2]段落。
- 隧道链路本身已于 2026-10-09 在真机全流程验证通过(Cloudflare 自建域名 + Docker):
v0.6.2-dsh-0.2.1-alpha.1
Changed
- DSH 升级到
0.2.1-alpha.1(Dockerfile的ARG DSH_VERSION)。动机是拿到
--public-url(见下面的DSH_PUBLIC_URL)。基于 81 个上游包的全量比对评估:- 本项目依赖的关键契约逐字节未变:
dsh-base的 patch 与 lib、CLI 的lib/、
profile 的 pnpm 布局(nodeLinker: hoisted)、原生绑定 hook、dsh.bundle.patch校验、
/api信任围栏。耦合点清单影响分级为阻断 0 / 高 0。 - 两个候选高风险项经核实均不触发:① 上游新增的
RETIRED_BUNDLES自动改写 profile
manifest(只读根 FS 下可能写盘失败)—— 本项目的 web/lifeboat profile 只列
dsh-base+dsh-web-app,全仓库零引用该退役 bundle,短路条件成立、不写盘;
②dsh-hmr新增原生依赖node-addon-require-builtin并 hook Node 内部模块 ——
该绑定已在镜像内验证可用,且其依赖的node-addon-native-custom-loader正是既有
NARB_DISABLE_NATIVE_CACHE=1所针对的加载器,防护直接覆盖。 - ⚠ 稳定性线取舍:按 semver 数字段
0.2.1-alpha.1>0.2.0-rc.2(前进),但按
稳定性线 alpha < rc —— 本镜像自此从 rc 线切到 alpha 线。dist-tag 亦印证:
latest/next仍指向0.2.0-rc.2。需要稳定线可覆盖DSH_VERSION回退。
- 本项目依赖的关键契约逐字节未变:
Added
- 对外访问根公告
DSH_PUBLIC_URL(容器场景的地址说反问题)。容器内 dsh 只监听
127.0.0.1:$PORT_INNER,它打印的 URL 行与给模型的系统提示都指向这个容器内地址 ——
用户与容器内的 AI 都容易把127.0.0.1:3081当成可访问地址,于是出现"日志里的链接点不开"
"模型给的地址打不开"。新变量把真实对外地址交给 dsh--public-url公告(影响打印的 URL 行、
自动打开、web-surface 提示词、DSH_WEB_URL四处)。- 能力守卫:
--public-url是 dsh 0.2.1-alpha.1 起才有的选项,更早版本不认识它 ——
实测dsh 0.2.0-rc.2 --public-url ...直接error: unknown option '--public-url'退出码 1。
在set -e+ 监督循环下这会连锁消耗自愈预算、最坏把用同一份 seed dsh 的救生舱一起拖崩。
故rescue_supports_public_url按卷内 dsh 实际版本决定是否追加;版本读不到/不可比时
一律保守判"不支持"(宁可少公告一次地址,也不能把一次必然的启动失败喂给自愈循环)。 - 输入按保守白名单校验(绝对 http(s)、无凭据、无查询/片段、无空白与 shell 元字符),
非法值丢弃并记审计日志 —— 与rescue_trusted_args同款,避免畸形值把启动变成 usage error。 - 它只做"公告",不授予任何信任(上游设计如此):浏览器可见的 authority 仍须由
DSH_TRUSTED_HOSTS声明(已装 dsh-remote 时由登录态覆盖),它也不配置监听器/路由/cookie。 - 浏览器入口提示:启动日志新增宿主侧入口行,并说明容器内地址为何点不开(不含任何凭据)。
- 能力守卫:
Fixed
--public-url在默认启动路径上静默失效(本次改动之前的状态等于没交付)。
PUBLIC_URL_ARGS只拼进了 entrypoint 的两处降级 exec,而默认主启动路径
rescue_supervise()自己拼命令行 —— 5 处 dsh 启动点一处都没带上该参数。后果是
静默失效 + 误导性日志:用户设了DSH_PUBLIC_URL,日志打印[entrypoint] public URL: ...
看起来已生效,而真正拉起 dsh 的进程从未收到它。现 5 处全部补齐(${PUBLIC_URL_ARGS:-}形式,
兼容set -u与独立 source)。
为什么不写单测拦不住:既有测试只测"参数构造函数本身",没有任何测试断言"参数是否真的
拼进了命令行"——与test-entrypoint-order.sh注释里描述的事故模式同源(单测全绿、真机失效)。
故新增门禁scripts/t/test-public-url-wiring.sh:静态断言每一处 dsh 启动点都含该引用,
并已用变异测试确认它确有牙(去掉任意一处即红灯并报出行号)。DSH_PUBLIC_URL对 compose 用户彻底不可达。该变量既不在 compose 的environment
白名单,也不在.env.example/docs/07—— 而 README 主推docker compose up,用户按文档
怎么填都无法启用。现已补齐全三处(compose 注入 +.env.example+ 中英docs/07新增 3.6 节)。test-compose-wiring.sh的裸$VAR检测盲区(正是上一条逃过门禁的原因)。
门禁正则只认${VAR:-}/${VAR:?}形式,而DSH_PUBLIC_URL在 entrypoint 里只以
[ -n "$DSH_PUBLIC_URL" ]这类裸引用出现 → "代码读它、compose 不注入、文档也没写"三项
全部漏报而门禁恒绿。现已补裸变量检测,并加了一条更耐用的排除规则:凡代码里被赋值过的
变量名一律跳过(内部派生变量如RESCUE_DIR="$DSH_HOME/.rescue"、RESCUE_DIAG由此自动
免疫,无需人肉维护白名单)。已用变异测试确认:把DSH_PUBLIC_URL的注入去掉即精确报错。DSH_PUBLIC_URL_MIN_VERSION畸形值时静默退化为"全部拒绝"(带尾随空格/garbage/空串
会让守卫判"不支持一切版本",功能无声全灭且无任何告警)。失败方向虽安全(保守拒绝),
但"静默"本身就是要避免的:现与版本参数同款做字符集 + 形状双重校验,非法即回落默认值
并记一条日志。- 归因更正(注释与测试的前提写错了,守卫本身正确)。原注释称「dsh-cmdline 未开
allowUnknownOption」——经代码核实不成立:dsh-cmdline根本不声明任何选项
(只做exitOverride+configureOutput);启动器dsh/lib/bin.js反而明确开了
.allowUnknownOption().passThroughOptions(),未知选项是被透传给 app 的;真正报错的是
web-app 的 startup program。结论不变(守卫必要),但错误归因会诱导后人删掉守卫,
故修正entrypoint.sh/librescue.sh/ 两个测试共四处注释并写明正确模型。
v0.6.1-dsh-0.2.0-rc.2
Fixed
-
救生舱日志里的"原因"不再说谎(
auto fallback: self-heal exhausted曾是硬编码)。
真机 2026-09-30:某实例重启后直接进救生舱,日志写着"自愈耗尽",据此排查了很久 ——
但那一轮启动里监督主循环压根没跑过(日志中没有任何 attempt / 自愈输出),
真实情况是读到了一个更早留下的陈旧标记。
根因:librescue.sh写标记时记了真实来源与时刻
({"requested":"<iso>","reason":"manual|self-heal exhausted"}),
entrypoint.sh读标记时却把 reason 写死成self-heal exhausted。
现在如实回读两个字段,并把标记写入时刻一并打进出参 ——
时刻远早于本次启动即可一眼判定"陈旧标记",不必再靠推断。
标记损坏/缺字段时用兜底文案,但会自曝是兜底(unreadable marker),
不再伪装成"已确认的原因"。读标记的顺序也加了门禁:必须先读后清
(rescue_lifeboat_clear会删掉文件)。 -
首启凭据横幅:密码独占行尾 + 明确告知存档位置。真机同一天踩到两个可用性问题:
① 原格式密码 / password : xxxx [generated]的密码尾部紧跟空格与[generated],
用户复制时带上尾随空格、或把密码里的大写O看成数字0,反复登录失败并撞上
插件限速(too many attempts; retry in 818s);
② 事后想再确认密码时,日志里已经找不到(设计上只打印一次),而用户不知道密码
同时被明文写进了 profile 的cordis.patch.yml,只能来问"这密码从哪来的"。
现在:密码行行尾即密码(来源另起一行),并新增一行
stored : <路径>,让看到密码的当下就知道日后去哪取回。 -
remote-setup.sh的容器日志全部改为英文。按本仓库既有约定(docker logs可见的
输出一律英文 —— 面向任意环境运维/排障、便于贴 issue 与搜索;中文只用于仓库文档、
rescueCLI 提示与各类报告),首启凭据横幅此前是这文件里唯一的中文输出,现改为全英文:DSH first-boot admin credentials username : admin password : xxxx source : generated stored : /data/dsh/profiles/web/cordis.patch.yml (mode 0600; plaintext kept there for later recovery)该文件其余
elog/elog_warn输出本就已是英文,本次仅统一了这一处。
写进cordis.patch.yml的文件注释保持中文(那是写入用户文件的内容,不属容器日志)。
门禁:test-remote-setup.sh新增「横幅不得含 CJK 字符」断言(用 node 精确判定,
避免 grep 的 locale 依赖)。 -
构建期
pnpm必须用绝对路径(tag v0.6.0-dsh-0.2.0-rc.2构建失败的真因)。
该 tag 推上去后build-and-push-image的Build and push步骤失败,exit code 127
(单测 job 全绿 —— 这正是本项目最忌讳的"绿着但已失效")。根因:插件 seed 层里裸写了
pnpm add …,而pnpm并不是基础镜像自带的 —— 它是上一个RUN用
NPM_CONFIG_PREFIX=/opt/dsh-seed装进/opt/dsh-seed/bin的;可PATH里只有
ENV PATH=/opt/dsh/bin:$PATH,那指向的是运行时挂载卷路径,不含/opt/dsh-seed/bin。
于是 shell 找不到pnpm直接 127。
修法:改用pnpm_bin=/opt/dsh-seed/bin/pnpm绝对路径调用(与本仓库对 seed 内可执行文件的
既有惯例一致:entrypoint 的/opt/dsh-seed/bin/dsh、/opt/dsh-seed/bin/pnpm,rescue 的
/opt/dsh-seed/bin/dsh)。刻意不改全局 PATH —— 那会波及后续所有层与运行期行为。
另加:调用前先if [ ! -x "$pnpm_bin" ]给出可读的致命提示(含"PATH 指向 /opt/dsh 而非
seed"的说明与ls -l /opt/dsh-seed/bin现场),而不是让失败退化成难以定位的 127。 -
补上漏掉的门禁(本次事故的直接教训):
scripts/t/test-remote-setup.sh新增 T13,
用 awk 状态机扫描 Dockerfile 的RUN续行,断言不得出现裸pnpm调用
(匹配(^|[;&|(])[[:space:]]*pnpm,故$pnpm_bin与绝对路径不会被误报),
并正向断言绝对路径变量、实际调用与可执行性检查三者都在位(防止"整块被删"让反向断言空过)。
该门禁已用变异测试双向验证:回退成裸pnpm即报FAIL-t13-dockerfile-bare-pnpm。 -
顺带修掉测试脚本自身的一个缺陷:
fail()在set -u下被只传一个参数调用时会以
parameter not set崩掉(掩盖真正被检测到的问题),改为fail() { echo "FAIL-$1${2:+: $2}"; …; }。 -
test-script-modes.sh改为检查 git index 模式,修掉"本地绿、CI 红"的可执行位陷阱。
发本版时main连续三次构建失败(1584274/dbbc7cc/dcdcd88),失败的不是
Docker 构建而是unit-testsjob —— 元凶是test-script-modes.sh,而它在本地永远通过。根因有两层,缺一不可:
- 本仓库
.git/config里是core.filemode=false(bind mount / NAS 上常见),
git 会忽略 chmod:chmod +x之后git add不记录模式变化,
于是新增的scripts/t/test-lifeboat-marker.sh与test-dockerfile-hygiene.sh
在 git index 里停在100644(本地文件系统却是755)。 - 原门禁用
[ -x "$file" ]检查 —— 那测的是本地文件系统,不是别人 clone 到的东西。
CI 按 index 的 644 落盘 → 门禁红;本地文件系统 755 → 门禁绿。
这个门禁结构上不可能在本地发现该问题,所以同一个坑已经踩过两次
(上一次是test-remote-setup.sh,当时只手工git update-index --chmod=+x了事,
没有动门禁本身,于是这次又踩)。
现在门禁读
git ls-files -s的 index 模式(= clone / CI checkout 后真正落盘的模式),
本地与 CI 判断一致;未纳入 git 的文件(本地临时脚本)退回文件系统检查,有兜底。
本次修复当场在本地复现了失败(报出两个git index mode=100644的文件),
修git update-index --chmod=+x后转绿 —— 这正说明门禁改动生效。
文件头也写清了正确修法:新增测试脚本要报红时用git update-index --chmod=+x,
不是chmod +x。 - 本仓库
Added
docs/04故障排查(中英)新增两条实测坑:- 登录报
too many attempts; retry in Ns→ 这是插件限速(15 分钟 5 次失败),
docker restart dsh立即清除(限速状态只在内存里),不必干等 N 秒; - 找不到初始管理员密码 → 先去凭据存档取回(
grep -A8 'id: remote' …/cordis.patch.yml),
而不是直接删store.json重置(后者会清掉所有账号与 MFA)。
docs/02与docs/07(中英)同步把"凭据存档位置"提到显眼处。
- 登录报
scripts/t/test-lifeboat-marker.sh:新建 18 组断言,覆盖
librescue 写标记 / entrypoint 读标记的跨文件契约。它从entrypoint.sh里
awk 提取真实代码段并执行(不是手抄副本),断言manual标记不得被报成
"自愈耗尽"、必须带上写入时刻、标记必须被一次性消费、损坏标记走兜底且自曝。
已用变异测试双向验证:还原成硬编码即报FAIL-hardcoded-reason,
把 clear 提到 read 之前即报FAIL-clear-before-read。scripts/t/test-remote-setup.sh新增横幅断言:密码行必须"行尾即密码"、
必须打印凭据存档路径(同样经变异测试确认能抓到回归)。
Removed
-
不再干预 profile 的 HMR(删除
--patch hmr-off.yml整套机制)。
此前 entrypoint 在每条 dsh 启动命令上注入--patch /opt/dsh-rescue/hmr-off.yml,
关掉 base 组合包的hmr条目 —— 理由是"HMR 依赖的原生绑定在只读根 FS 下不可用,
dsh 会抛--expose-internals is required for HMR service而崩溃"。为什么现在可以整个去掉(三条依据,前两条是实测):
- 崩溃的根因早已由另外两层修复,与 HMR 开关无关 ——
Dockerfile 的NARB_DISABLE_NATIVE_CACHE=1(绑定改从可执行卷/opt/dsh原路径
dlopen,绕开 tmpfs)与 compose 的tmpfs /tmp:size=128m,exec。
关闭 HMR 从来只是症状层的保险,不是根因修复。 - 实测(dsh 0.2.0-rc.2):不带该叠加层启动 dsh web 完全正常 —— 无任何
--expose-internals报错,启动后服务可用。--dump-config亦确认此时hmr条目
为disabled: !!js "!ctx.get('profileContext')"(即 web 下默认启用)。 - 实测:带与不带该叠加层的 dsh 进程,inotify 句柄数都是 0 ——
HMR 的 chokidar watcher(dsh-hmr用chokidar监听 profile patch 文件)
在该环境下根本没有启动。也就是说这层关闭一直是零效果的。
佐证:把cordis.patch.yml改成非法 YAML(源码保证重载失败会
logger.warn("config reload ... failed"))也没有任何输出,进程照常存活。
代价与收益:这层无效的关闭让本项目长期背着一个"关掉上游功能"的补丁,
并且掩盖了"绑定不可用"这个本该暴露的信号 —— 同一根因(绑定不可用)还会让
第三方插件报ERR_MODULE_NOT_FOUND,而 HMR 被静默关掉后,用户看不到任何提示。
去掉后 HMR 完全跟随 dsh 默认,本项目不再对上游行为做无谓干预。改动范围:删除
scripts/hmr-off.yml;entrypoint.sh与rescue-supervise.sh
移除HMR_OFF_YML/HMR_OFF_PATCH的构造与全部注入点(7 处启动命令);
Dockerfile移除其 COPY 与 CRLF 归一;docs/07(中英)安全加固节改写为
"不再干预 HMR"并说明前提;docs/03、README(中英)同步口径。
⚠ 若你自建 compose 覆盖了上述两层修复(去掉tmpfs … ,exec或改
NARB_DISABLE_NATIVE_CACHE),请自行确认绑定仍可加载,否则症状是 dsh 启动失败
或第三方插件全部加载不出来。 - 崩溃的根因早已由另外两层修复,与 HMR 开关无关 ——
-
scripts/t/test-hmr-off.sh→scripts/t/test-dockerfile-hygiene.sh。
原测试的主体(断言每条启动路径都注入--patch、镜像携带叠加层、叠加层真的禁用)
随机制一起消失,但它夹着三条与 HMR 无关、由真机事故换来的通用断言,不能跟着删,
故迁移并补反向断言:- H1
RUN续行内不得出现注释行(会被 shell 当注释,吞掉其后命令 —— 真机踩过,
镜像静默丢掉 rescue 软链); - H2 救援资产必须
chmod a+r(umask 077 的构建机会让资产落成 0600,uid 1000 读不到); - H3 不得再依赖 0.1.6-alpha.2 已被上游删除的
patchReload字段; - H4 反向锁住本次决定:
HMR_OFF_PATCH/HMR_OFF_YML/hmr-off.yml不得再出现在
可执行代码或镜像资产里(注释里解释"当初为何移除"不算)。锁的理由是"半恢复"
(改了 entrypoint 却没改 Dockerfile,或反之)会以"看起来在关 HMR、实际没关"的形式
静默漂移 —— 正是当初那次事故的翻版。
test-nonroot.sh中"entrypoint 必须有HMR_OFF_PATCH"的断言一并移除。
- H1
Notes
- 本版把四项修复一次性带出(
v0.6.0的镜像可用但缺它们):构建期 pnpm 绝对路径、
救生舱标记原因如实呈现、凭据横幅(行尾密码 + 英文 + 存档位置)、不再干预 HMR。
建议直接升级到v0.6.1。 v0.6.0-dsh-0.2.0-rc.2的镜像曾构建失败,已删除并重推修复:首次推送时构建在插件
seed 层中断(exit 127,见上「构建期 pnpm」条),镜像与 Release 均未产出(同 SHA 的
create-release工作流虽成功,但没有镜像可拉)。修复推上main并经main分支构建
验证通过后才删除并重推同一 tag,构建成功、镜像已发布。重推 tag 的副作用(GitHub
Release 被转为 draft)已由仓库工作流里的--draft=false覆盖。- 升级影响面:本次改动触及启动逻辑(HMR 注入被移除、救生舱判定、首启凭据横幅),
但不改变数据格式与部署方式 —— 挂载卷、compose 变量、profile 布局均无变化,
docker compose pull && docker compose up -d即可;无需迁移。 - 本次事故暴露的盲区:
scripts/t的单测只能静态检查 Dockerfile 文本,无法真的执行构建。
T13 把"构建期命令是否可达"这一不变量纳入静态覆盖,但首次使用新的构建期命令时,
仍应在本地或临时分支真跑一次docker build再打 tag。
v0.6.0-dsh-0.2.0-rc.2
Changed
- 镜像锁定的 dsh 升级到
0.2.0-rc.2(ARG DSH_VERSION)。首次从 0.1.7 线切到 0.2.0 线:
seed → 挂载卷 → entrypoint 监督的部署链路未变,ver_gt正确判定0.2.0-rc.2 > 0.1.7-rc.2。 docs/03的 dist-tag 快照更新为 2026-09-29 实测:latest → 0.1.7-rc.2(原0.1.5-rc.3)、
next → 0.2.0-rc.2(原0.1.7-rc.2)、alpha → 0.1.7-alpha.2(不变);README 中英徽章同步。
Added
- 默认安装认证插件
@xgone/dsh-remote(ARG REMOTE_PLUGIN_VERSION=0.3.5),并在首启自动
创建一个管理员账号:用户名admin(可用DSH_DEFAULT_ADMIN_USER改),密码为随机 16 位,
只打印一次到首次启动日志。此前默认无认证、仅内网直连 —— 一旦把3080暴露出去,任何人
打开页面就是一个拥有完整 agent 权限的会话;本版把"要不要保护"从"记得去装个插件"改成
"默认就有、可显式关掉"。- 离线可用:插件以 pnpm 同构形态预置在镜像内
/opt/dsh-remote-seed(构建期用真实 pnpm
安装,产出带 lockfile 的完整树 +nodeLinker: hoisted,与 profile 自身的布局一致),
首启由 entrypoint 复制进 profile —— 不依赖 npm registry。这与 dsh 本体的 seed 机制同款,
保证内网/NAS 部署开箱即有认证(也避免了首启联网拖长冷启动、撞RESCUE_START_TIMEOUT)。 - 密码只打印一次:判据是账号库(
$DSH_HOME/auth/store.json)是否已有账号,而不是容器启动
了几次 —— 否则密码会被写进每一次docker logs,而日志常被转发、归档或贴进 issue。 - 不覆盖已有账号:插件在账号库非空时忽略
bootstrap配置并打 warn,用户自行改过的密码
不会被镜像重置。 - 不顶回旧版:profile 里已有该插件时 entrypoint 不覆盖 —— 用
dsh plugin add @xgone/dsh-remote@<更高版本>升过的版本会保留(镜像种子只负责"从无到有",
与 dsh 本体的"seed 只升不降"约定刻意不同:插件升级一律走dsh plugin)。 - 可关闭:
DSH_SETUP_REMOTE=off回到历史行为(不装插件、不建账号、无认证层)。 - 新增
scripts/remote-setup.sh(整备逻辑,无顶层副作用、可单测)与 4 个环境变量
(DSH_SETUP_REMOTE/DSH_DEFAULT_ADMIN_USER/DSH_ADMIN_PASSWORD/DSH_REMOTE_SEED)。 - 构建参数可置空(
--build-arg REMOTE_PLUGIN_VERSION=)以产出不带该插件的镜像。
- 离线可用:插件以 pnpm 同构形态预置在镜像内
- 文档同步:
docs/02(中英)改写为"默认已启用认证"的叙事,新增关闭方式、密码找回、
手工升级与"托管块"说明;docs/07(中英)新增 §3.5 默认认证插件一节与 3 个构建参数;
.env.example新增对应条目;docker-compose.yml注入上述变量。
Notes
- 本次升级经全树 diff 评估(
0.1.7-rc.2 → 0.2.0-rc.2),对本项目的契约面零破坏:dshCLI 参数定义逐字相同(--profile/--patch/--dump-*);- web 的
--port/--no-open/--trusted-host(dsh-web-app的startup.js)两版逐字节相同; getDshRuntimeVersion(--version输出格式)、PROFILE_TEMPLATES(web 的 bundles 列表)、
/data/dsh/profiles/<name>目录布局 均未变;dsh-base的hmrrow 逐字节相同 →scripts/hmr-off.yml的关闭叠加层继续有效
(门禁test-hmr-off.sh仍绿)。dsh-baserows 93 → 94(新增 typert 系列),无本项目关注的 row 被删;dsh-web-app的
patch 增删(desktop 遥测行、schedule 族改为可选 bundle)对本容器 web profile 无影响。
- 插件兼容性:
@xgone/dsh-remote@0.3.5依赖的@deepseek-ai/cordis ^4.0.4/
schemastery ^3.18.4与 0.2.0-rc.2 精确匹配;它未声明 DSHpeerDependencies,故不触发
0.1.7-rc.1 起引入的插件 peer 版本门禁(incompatible-version)。 - 实测验证(本机真跑 0.2.0-rc.2 + 该插件 + 本仓库生成的 profile,非静态推断):
进程零激活告警启动;未登录GET /返回登录页、/api/*返回 403 unauthorized;
用预置的 admin 密码POST /auth/login返回
{"ok":true,"user":{"username":"admin","role":"admin"}}并发下会话 cookie,
带 cookie 请求/auth/me得到authenticated:true, role:admin;错误密码返回
401 invalid credentials;$DSH_HOME/auth/store.json中账号为
role:admin+protected:true+ scrypt 哈希。 - ⚠ 升级后仍建议强制刷新浏览器:0.2.0 重建了前端预构建资源(与 0.1.7-rc.2 同类情形)。
若浏览器持有旧前端,会表现为大片客户端 entry pending /Failed to load plugins,
而服务端日志完全正常 —— 用无痕窗口或强制刷新即可,不是升级失败。 - ⚠ 不要忽略首启日志里的密码横幅:
docker logs dsh 2>&1 | grep -A9 'first-boot admin credentials'。
若卷里已有旧账号(此前手工装过 dsh-remote 的部署),本版不会建号也不会打印密码,
沿用你原有的凭据即可。