@hyzyn/dsh-docker 0.4.0 → 0.5.1

package/README.md

@@ -1,12 +1,16 @@
 # @hyzyn/dsh-docker
 
-DSH Web GUI 的 **Docker 容器面板**插件：侧边栏「容器」入口打开面板，查看
-**本机或 SSH 主机**上的容器列表（含 **Compose 项目视图**）/ 状态 / 端口 /
-日志（`--tail` 快照 + **FOLLOW 实时流，SSE 推送**）/ **资源占用（实时跟随 +
-迷你趋势图）**，以及镜像列表、**镜像详情（层 / 大小 / 构建历史）与 `docker pull`
-进度流**；并在显式打开开关后执行容器启停删、镜像拉取 / 删除 / 清理与一次性
-`docker exec`。宿主半体用 `ssh2` 的 **exec channel**（非 PTY）在远程跑 docker
-CLI，本机目标直接 spawn；agent 侧配套 `docker_*` 工具，**默认只读**。
+中文 | [English](README.en.md)
+
+> DSH 侧边栏「容器」面板：本机与 SSH 主机的容器一屏巡检——读日志、看资源、进容器、启停删，**默认只读**。
+
+## 特性
+
+- **多目标聚合取数**：总览页对全部 `targets[]` 并行请求，单个目标不可达只污染自己那一格；agent 侧同一口径由 `docker_ps target:"*"` / `docker_attention target:"*"` 暴露，跨目标不互相阻塞。
+- **「需关注」读权威字段**：不健康 / 反复重启 / OOM 被杀 / 非零退出 / 僵死；OOM 与真实退出码由一次 `docker inspect` 补齐——`docker ps` 摘要里的 137 分不出 OOM 与手动 kill，只按摘要筛必然误报。
+- **四条 SSE 长流共用一套基建**：日志 FOLLOW、`docker stats`、`docker events`、`docker pull` 走同一个 `openSseStream`（心跳 / 活跃流登记 / 断开清理），差异只在收尾语义——日志与拉取自然结束，统计与事件由前端主动断。多选聚合日志按 `--timestamps` 前缀还原跨容器真实时序，「暂停」只冻结渲染（流继续接收，恢复时一次性补齐）。
+- **默认只读，能力开关分三级**：启停删 / exec / 镜像变更各自独立开关，未开启时 agent 工具**不注册**、HTTP 路由 403（能力不存在，而非调用后报错）；容器名与 ID 过白名单，命令一律 argv 构造 + 单引号转义，密码 / 口令以 `env:VAR` 引用且永不回传浏览器。
+- **与 dsh-tty 数据级复用、代码级不耦合**：不 import 任何 tty 代码，tty 也无需改一行源码，两者可各自安装与升级；装了 tty 则消费三个可选扩展点——连接栏动作（`ttyConnbar`）、右侧 dock 承载（`ttyPanel.mountPane`）、容器内终端抽屉（`ttyTerminal.mount`，就地嵌入或开标签按版本协商），未装或版本不足逐项静默降级。
 
 ## 与 dsh-tty 的关系
 
@@ -69,8 +73,28 @@ add。装完重启 `dsh web`，侧边栏出现「容器」入口；设置 →
 
 ![容器列表：目标选择 / 搜索与状态筛选 / 卡片动作条（查看 · 变更两组）](https://cdn.jsdelivr.net/gh/hyzyn/dsh-plugin-kit@main/docs/dsh-plugin-kit-docker-panel.png)
 
+- **切目标有过渡与保护**：选择器一变，下方仍是上一个目标的卡片（远端一次往返最长 20s）。
+  过渡层的三条原则——**不推版、有方向感、少灰**：
+  - 面板正文顶部一条 2px **不定长流光进度条**（绝对定位）给「正在取数」的全局信号；
+  - 正文顶部**居中浮出一枚蓝色胶囊**（与 dsh-rss 的加载胶囊同一套位置与配色语言）：
+    底色 `color-mix(accent 12%, surface)`、描边 `accent 42%`、文字与旋转图标走 `--dk-accent`；
+    可见文案只两段 `⟳ 正在切换到 目标2 · 当前显示：目标1`（不写成一句话、不用引号裹目标名），
+    完整的「为什么点不动」放 `title`，需要时 hover 就有；
+  - 旧数据保持 **82% + 轻度去色**（不是压暗到看不清）并**锁住指针**：读起来是「另一批
+    内容」而不是「坏了」，同时避免照着旧列表操作——那会拿新目标当目标、用旧列表的容器
+    ID 发命令，真能停掉对端同名容器；
+  - 新数据 **8px 上滑 + 淡入** 200ms 落地，让「换了一批内容」看得见；动效尊重
+    `prefers-reduced-motion`。
+
+  以上全部**绝对定位**：切换过程中首卡位置与滚动高度实测完全不变（横幅方案会把内容整块
+  推下去）。**切换失败则清空旧列表**并归到新目标的错误态（不继续展示别的目标的数据），
+  空态文案也会区分「读取失败」与「筛选过窄」。
 - **目标选择**：面板先选目标（来自配置 `targets`，本机 / SSH）；只配置了一个
-  目标时默认选中它，agent 工具也可以省略 `target` 参数。换目标是**整段上下文切换**：
+  目标时默认选中它，agent 工具也可以省略 `target` 参数。
+  **会记住上次选的目标**（存浏览器 `localStorage` 的 `dsh-docker:last-target`，不落
+  配置、不进 settings）：下次打开面板自动选中它。优先级是**连接栏指定 > 上次记住的
+  （且仍存在）> 列表第一个**——记住的目标被删掉/改名后会自动退回第一个，不会停在
+  「未知目标」上；从终端连接栏的「容器」按钮进来时，当前会话主机优先于记忆值。换目标是**整段上下文切换**：
   上一个目标还在飞的请求一律作废（列表写入闸），不会出现「选择器已经是目标2、卡片
   还是目标1 的容器」这种串台，也不会让旧目标的超时横幅停在新目标的页面上。
 - **多目标总览（只读）**：目标选择器旁的 `总览` pill（配了 ≥2 个目标才出现）——不选
@@ -102,7 +126,7 @@ add。装完重启 `dsh web`，侧边栏出现「容器」入口；设置 →
   `die` 带退出码如 `die(137)`）。它是**事件驱动刷新**的入口：收到事件后 500ms
   **防抖**触发一次列表重取（不是每帧一次请求），与原有 `AUTO REFRESH` 叠加而不互斥——
   轮询负责兜底，事件负责「刚发生」。事件只留在内存（环形缓冲 50 条），切页即关流，
-  换目标清空缓冲。白名单只留八类生命周期动作（start / die / stop / kill / oom /
+  换目标清空缓冲。白名单只留九类生命周期动作（start / die / stop / kill / oom /
   health_status / destroy / rename / update）：`exec_*`、`archive-path`（`docker cp`）
   这类噪音在服务端就丢掉了——实测一台跑批机器 24 小时 47 条事件全是 exec，白名单
   命中 0，所以只被 exec 的机器上活动条是空的，这是刻意的。
@@ -116,6 +140,10 @@ add。装完重启 `dsh web`，侧边栏出现「容器」入口；设置 →
   再点 `聚合选择` 或按 **Esc** 同样退出并清空。勾选是**临时的**：不持久化、不命名
   组合、不进 settings；切目标 / 切「容器 · 镜像 · Compose」分段 / 关面板即失效，
   列表刷新后已消失的容器按 id 自动剔除。
+- **按条件一键选中**（多选态）：操作条第二行给出一排条件 chip（`全部可见 / 不健康 /
+  需关注 / 已停止`，以及有勾选后的 `同镜像 / 同项目`），计数**按剩余名额截断**——
+  chip 上写 8 就真的会选中 8 个；超出上限的数量在 title 与结果提示里如实说明。
+  条件只在**当前筛选结果**里生效（先搜索/筛状态再一键选中）。
 - **容器卡片**：与参考布局一致的「标签 + 值」行（镜像 / ID / 端口 / 创建 /
   compose，值等宽、可省略）+ 一排图标操作按钮，**按「查看 / 变更」两组用竖线分隔**：
 
@@ -248,6 +276,53 @@ add。装完重启 `dsh web`，侧边栏出现「容器」入口；设置 →
 `permission denied while trying to connect to the Docker daemon socket`
 之类的错误。
 
+### 聚合日志（多选 / Compose 项目）
+
+多选容器或打开一个 Compose 项目，都能把多个容器的日志聚合成一条流（每个容器一条
+`docker logs -f` SSE，客户端按到达顺序混流）。工具栏提供：
+
+| 控件 | 语义 |
+| --- | --- |
+| **实时 / 已暂停** | 真暂停（见下） |
+| **时间戳** | 显示每行时间戳。时间戳**始终随流接收**（`timestamps=1`），只影响显示 |
+| **按到达 / 按时间** | `按到达`：零延迟跟随；`按时间`：用每行的容器时间戳合并成一条真时间线 |
+| **级别过滤** | `全部级别 / WARN+ / ERROR+`。**无级别前缀的行（堆栈等续行）继承上一条日志的级别**，所以 ERROR+ 会连它的堆栈一起保留、INFO 的续行一起滤掉；窗口开头的孤儿续行（记录头在窗口外）无从判断，保留 |
+| **⬇ .log / ⬇ .md** | 导出当前显示内容：`.log` 是纯行文本（`[服务] ISO时间 正文`），`.md` 带来源容器 / 行数 / 导出时间表头，可直接当工单附件 |
+
+**按时间合并怎么做的**：SSE 各容器建连有先后，A 的首屏历史可能整批先到、B 随后才到，
+只对单批排序修不了跨批逆序。实现是**回填最近 400 行**——每批新行到达时把「最近 400 行 +
+新行」整体按时间戳重排（`docker logs --timestamps` 的 RFC3339 前缀为排序依据，解析后从
+正文里剥掉）。这样既不为了让首屏正确而先憋一段时间（不会开页白屏 1 秒），又能事后纠正
+历史错序；代价是「按时间」模式下已在屏上的最近若干行可能轻微重排（正在跟随实时输出时
+建议用「按到达」）。
+
+### 聚合日志的「暂停」（真暂停）
+
+多选容器 / Compose 项目的聚合日志有一个 `实时 / 已暂停` 开关。**暂停是内容冻结**，不只是停止自动滚动：
+
+- 暂停期间新到的日志进入客户端缓冲，**DOM 不再追加**——读屏不会被顶走；也不会因为显示上限
+  （2000 行）裁掉前部而跳屏；
+- 按钮上直接显示攒了多少行（`已暂停 +348`）；
+- 恢复时把缓冲一次性并入（沿用 5000 行环形上限）并回到底部。
+
+只停「自动滚动」是不够的：标签写着「已暂停」而内容还在长，用户会以为开关坏了；日志量大时
+画面还会因裁前部而自己跳。
+
+### 总览（跨目标）与「需关注」口径
+
+「总览」页一屏铺开全部目标：每个目标一张计数卡（运行中 / 已停止 / 不健康 / **需关注**），
+下方是跨目标的「需关注容器」表（容器名 / 目标 / 状态 / **原因** / 镜像，点行进详情、点卡切到
+该目标的列表）。三条设计约束：
+
+- **渐进落地 + 失败隔离**：每个目标独立请求、独立落格；一台 SSH 不可达不会让整页静默，
+  不可达的目标单独出横幅，其余目标结果照常可用。
+- **需关注口径以宿主为准**：容器列表与 `/attention` 并行请求；后者额外做一次 `docker inspect`，
+  因此能识别 **OOM（OOMKilled）** 与**真实退出码**——ps 摘要里 `Exited (137)` 分不出是被 OOM
+  杀还是手动 kill。拿不到 `/attention`（老版本宿主 / 该目标失败）时退回摘要口径，并在
+  计数上标注「需关注（粗判）」。
+- **排序**：OOM > 僵死 > 不健康 > 反复重启 > 非零退出；同权重按「最近一次结束时间」倒序，
+  刚崩的排在最上面（行 hover 显示结束/启动时间、重启次数、退出码）。
+
 ## 配置（设置 → 插件 → Docker 容器面板，保存即热生效）
 
 ![设置卡片：目标 CRUD、能力开关与参数，保存即热生效](https://cdn.jsdelivr.net/gh/hyzyn/dsh-plugin-kit@main/docs/dsh-plugin-kit-docker-setting.png)
@@ -310,12 +385,13 @@ add。装完重启 `dsh web`，侧边栏出现「容器」入口；设置 →
 | 工具 | 注册条件 | 参数 | 作用 / 典型用法 |
 | --- | --- | --- | --- |
 | `docker_targets` | 恒注册 | `probe?: boolean` | 列出目标（name / kind / label）；`probe:true` 逐个探测 docker 版本与 daemon 可达性（SSH 目标会建连接，较慢）。其他工具的 `target` 取自这里 |
-| `docker_ps` | 恒注册 | `target?`、`all?: boolean` | 列容器（名称 / 状态 / 健康 / 镜像 / 端口 / compose 项目与服务 / 短 ID）；默认只列运行中，`all:true` 含已停止。排障第一步 |
+| `docker_ps` | 恒注册 | `target?`（**传 `*` = 全部目标**）、`all?: boolean` | 列容器（名称 / 状态 / 健康 / 镜像 / 端口 / compose 项目与服务 / 短 ID）；默认只列运行中，`all:true` 含已停止。`target:'*'` 时按目标分组返回，**单个目标不可达不影响其他目标**（该组带 `error`）。排障第一步 |
+| `docker_attention` | 恒注册 | `target?`（支持 `*`）、`limit?: number` | **需关注汇总**：不健康 / 反复重启 / 被 OOM 杀 / 非零退出 / 僵死；每条带 `reasons`、`exitCode`、`oomKilled`、`restartCount`。OOM 与真实退出码来自一次 `docker inspect`（ps 摘要里 137 无法区分手动 kill）。排障入口：不确定从哪台/哪个容器看起时先调它 |
 | `docker_inspect` | 恒注册 | `target?`、`id`（必填） | `docker inspect` 的权威详情：状态 / 健康检查 / 退出码 / 重启次数 / 端口 / 挂载 / 网络 / 启动命令 |
 | `docker_logs` | 恒注册 | `target?`、`id`、`tail?`（1~5000，默认 `logTailDefault`）、`timestamps?`、`since?` | `docker logs --tail` 尾部；`since` 用 docker 语法（如 `10m`、`2026-09-09T10:00:00`）；超上限标记 `truncated` |
 | `docker_stats` | 恒注册 | `target?`、`ids?`（逗号分隔的容器名/ID） | `docker stats --no-stream` 快照：CPU% / 内存用量与占比 / 网络 IO / 块 IO / PIDs；`ids` 省略 = 全部运行中容器。实时跟随是面板能力（SSE），工具保持单值快照语义 |
 | `docker_images` | 恒注册 | `target?` | 镜像列表（仓库:标签 / 大小 / 创建时间 / 短 ID） |
-| `docker_events` | 恒注册 | `target?`、`since?`（docker `--since` 语法，默认 `10m`） | 容器事件快照（`docker events --since <d> --until <now>`，同样过服务端白名单）：start / die / stop / kill / oom / health_status / destroy / rename / update 八类，`exec_*` 等噪音已在服务端丢掉。要持续观察请让用户看面板容器列表的「活动」条 |
+| `docker_events` | 恒注册 | `target?`、`since?`（docker `--since` 语法，默认 `10m`） | 容器事件快照（`docker events --since <d> --until <now>`，同样过服务端白名单）：start / die / stop / kill / oom / health_status / destroy / rename / update 九类，`exec_*` 等噪音已在服务端丢掉。要持续观察请让用户看面板容器列表的「活动」条 |
 | `docker_networks` | 恒注册 | `target?` | 网络列表（名称 / 驱动 / 范围 / 是否 internal / 短 ID）。接入的容器列表不进列表行——详情页会连坐 inspect，列表逐行 inspect 就是 N 次 docker 调用 |
 | `docker_volumes` | 恒注册 | `target?` | 卷列表（名称 / 驱动 / 范围 / 挂载点） |
 | `docker_image_inspect` | 恒注册 | `target?`、`ref`（必填） | `docker image inspect` + `docker history`：大小 / 含父层大小 / 创建时间 / 平台 / 层数与层列表 / 入口与命令 / 暴露端口 / digest / 构建历史（每步命令与大小） |
@@ -347,7 +423,8 @@ add。装完重启 `dsh web`，侧边栏出现「容器」入口；设置 →
 | `/config` | POST | 上表配置键的任意子集 | `{ok:true, config}`；未知键 400，非法 JSON 400 |
 | `/targets` | GET / POST | — | `{ok:true, targets:[{name, kind, label?\|error?}]}` |
 | `/probe` | POST | `{target?}` | `{ok:true, probe:{ok, bin, serverVersion, error, target}}` |
-| `/containers` | POST | `{target?, all?}` | `{ok:true, containers: ContainerSummary[]}` |
+| `/containers` | POST | `{target?, all?}` | `{ok:true, containers: ContainerSummary[]}`；`target:'*'` 时返回 `{ok:true, groups:[{target,label,ok,error?,data?}]}`（跨目标并发聚合） |
+| `/attention` | POST | `{target?}` | 单目标 `{ok:true, items: AttentionItem[]}`；`target:'*'` 时 `{ok:true, groups}` |
 | `/inspect` | POST | `{target?, id}` | `{ok:true, details: ContainerDetail[]}` |
 | `/stats` | POST | `{target?, ids?: string[]}` | `{ok:true, stats: ContainerStats[]}` |
 | `/logs` | POST | `{target?, id, tail?, timestamps?, since?}` | `{ok:true, logs:{id, text, truncated}}` |
@@ -504,6 +581,10 @@ abort）、客户端断开静默中止。各自只差执行器与结束原因：
 - **变更操作无独立审计日志**：只有 docker 自身的记录与宿主 `ctx.logger` 的
   常规输出。
 
+- **跨目标聚合的边界**：并发上限 4、单目标超时 45s；单个目标失败/超时只影响它自己那一格
+  （组里带 `error`）。目标很多时总览的请求量随目标数线性增长（每目标 2 个请求），自动刷新
+  会放大这个量——目标多时建议关掉自动刷新。
+
 ## 工作原理
 
 ```