dsh-comfyui-gateway 0.4.3 → 0.4.7

package/README.md

@@ -91,6 +91,33 @@ view 200 233341 png true
 - 会话是 HttpOnly Cookie，30 分钟空闲 / 12 小时上限；
 - 同一账号 10 分钟失败 8 次即锁定窗口内重试。
 
+### 外网访问（反向代理）
+
+控制台自己不做 TLS，也没有域名白名单——它就是普通 HTTP。要给人从外网用，前面必须有一层
+HTTPS 反代（群晖反向代理、nginx、Caddy、cloudflared 都行），把 `https://你的域名` 转到
+`http://192.168.3.253:8186`。
+
+**三条都成立才算配通**（这三条是实测过的，不是清单堆料）：
+
+1. `X-Forwarded-*` 与 `Host`：**保留原始 Host 或改写都行**。实测把 Host 改成
+   `127.0.0.1:8186` 之后登录、取页面、取 `/api/state` 全部照常——控制台不比对 Origin/Host，
+   所以不会被常见的「反代默认改写 Host」卡住。但**必须转发 Host**，不能删掉。
+2. **不要挂子路径**。页面里的跳转是绝对路径（`/app`、`/`），挂到 `https://域名/comfy/`
+   会 404。要单独一个域名或子域名，根路径直达。
+3. **WebSocket 要放行**：画布桥接走 `/bridge/<token>/` 的 upgrade。nginx 需要
+   `proxy_http_version 1.1` + `Upgrade $http_upgrade` + `Connection $connection_upgrade`。
+   没放行时控制台其余功能正常，只有「打开画布」转圈。
+
+上传单文件上限 48 MB（`MAX_UPLOAD_BYTES`），nginx 默认 `client_max_body_size 1m`
+会让稍大的参考图直接 413；把它调到 64m 或以上。
+
+会话 Cookie 是 `HttpOnly; SameSite=Lax`，**没有 Secure**：所以 `https` 与 `http` 下都能登录，
+不需要额外开关。代价是同一域名下若还有别的 HTTP 服务，Cookie 不会被浏览器按 Secure 隔离——
+这是内网自用工具的取舍。
+
+登录仍然要过两道：账号密码 + 桌面「任务池」页那 6 位配对码。**外网就靠这个**，
+所以配对码保持开启；不想让别人看到配对码，就别把「任务池」页面共享出去。
+
 ### 界面
 
 ```
@@ -207,6 +234,23 @@ SFW 账号的成人需求在打模型之前就被拦下；模型若仍答出成
 - `Note`/`MarkdownNote`、静音/旁路节点丢弃；
 - 实例里没有的节点会**报出来**，不会硬塞到生成时才神秘失败。
 
+### 批量导入工作流
+
+一批 API 格式的 JSON（`{节点id: {class_type, inputs}}`）要进库时，不必一个个粘贴：直接调
+`WorkflowLibrary.put()` 就是 `POST /api/workflows` 跑的同一段代码，会一并算出参数槽位、
+归属与等级。
+
+两点在实现里踩过，写在这里免得再踩：
+
+- **API 格式不再被当成 UI 图去转换。** 转换器需要实例的 `/object_info`；批量导入时没有，
+  旧代码于是留下 `api = null`，连带 `targets` 与 `nodeCount` 都是空——控制台在文生图工作流上
+  连提示词框都不显示。现在先判"这已经是 API 格式"，直接当 prompt 用。
+- **库在运行时重读。** `workflows.json` 被外部改写后，控制台会在下一次
+  `/api/workflows` 时按 `mtime+size` 判定并重读，不需要重启宿主。
+  在此之前只有重启整个 DSH 才看得到新导入的条目——「重启网关」只重启监听器，不重读状态。
+
+导入的条目默认 `heads` 为空：这些图是文档的原样转换，擅自加质量词会改变每个工作流本来的行为。
+
 ## 桥接（画中画借用实例）
 
 远程页点某个实例「打开画布」：
@@ -223,19 +267,36 @@ SFW 账号的成人需求在打模型之前就被拦下；模型若仍答出成
 ## 实例管理（含本机启停）
 
 面板「实例」卡片能绑定任意 ComfyUI 地址。要让启动/停止真的作用于进程，把该实例的
-**进程托管**设为 `本机命令`，并填命令行与工作目录：
+**托管方式**设为 `启动 bat 文件`，然后填那个 `.bat` 的完整路径：
 
 ```
-E:\ComfyUI-aki-v3.2\python\python.exe -s E:\ComfyUI-aki-v3.2\ComfyUI\main.py --port 8190 --listen 0.0.0.0
+E:\ComfyUI-aki-v3.2\启动.bat
 ```
 
-- 启动：spawn 该命令 → 轮询 `/system_stats` 直到就绪（超时可配，默认 5 分钟）；
-- 停止：Windows 上先 `taskkill /T /F` 杀进程树再结束子进程（.bat 包装器会留下孙进程，
+**只有 bat，没有命令行，也没有 ssh。** 三种方式里只留有意义的两种：
+
+| 托管方式 | 含义 |
+| --- | --- |
+| `启动 bat 文件` | 网关执行这个 `.bat`；停止时连同它的子进程一起杀掉 |
+| `不托管` | 只派发，不给启停按钮（进程是别人的） |
+
+为什么是文件而不是命令行：启动 ComfyUI 通常要先 `cd`、激活虚拟环境、带上端口参数，
+这些写在 bat 里最清楚，而且双击就能自己验证一次。让面板里再维护一份命令字符串，
+等于同一个启动逻辑存两处，改了一处就会对不上。
+
+- 启动：`cmd /d /s /c ""<bat>""` → 轮询 `/system_stats` 直到就绪（超时可配，默认 5 分钟）。
+  用 `windowsVerbatimArguments` 传参，否则 Node 会把引号转义成字面量 `\"`，
+  cmd 就会把它当成程序名去执行（`'\"C:\...bat\"'` 不是内部或外部命令）；
+- 工作目录默认取 bat 所在目录，所以 bat 不必自己 `cd`；也可以单独填；
+- 停止：Windows 上先 `taskkill /T /F` 杀进程树再结束子进程（bat 包装器会留下孙进程，
   只杀直接子进程的话显存不会释放——这一点在测试里踩过），然后轮询端口确认不再响应；
-- `SSH 远程`：同样的命令经 `ssh <host> <command>` 执行，用于另一台带显卡的机器；
-- `不托管`：只派发，不给启停按钮；
 - 插件卸载 / DSH 退出时杀掉本插件起的所有进程，不留孤儿占显存。
 
+**旧配置迁移**：以前的 `spawn + 命令行` 与 `ssh` 已停用。迁移规则保守——只有当一个旧
+`command` 本身就是 `.bat` / `.cmd` 路径时才转成 `启动 bat 文件`；其余（比如
+`python main.py --port 8190`、以及所有 ssh 行）一律退成 `不托管`。理由很直接：
+把一条命令行当文件路径去执行，或者假装能用本地 bat 启动远端主机，都会让「启动」按钮骗人。
+
 ## 智能体工具 `comfyui_gateway`
 
 `status`（默认，含每卡显存/速度/是否托管）、`dynamic`、`start`/`stop`/`restart`、
@@ -252,6 +313,13 @@ E:\ComfyUI-aki-v3.2\python\python.exe -s E:\ComfyUI-aki-v3.2\ComfyUI\main.py --p
 ```
 
 面板改完立即生效并落盘；只有**网关端口 / 远程端口 / 远程开关**变化需要点「重启网关」。
+
+**面板分组按「谁在用这个端口」划**：远程端口（8186，浏览器看的那套）的输入框在「远程控制」卡里，
+网关端口（8187，脚本调的那套）的在「网关」卡里。两个端口共用一套校验（1–65535、互不相同），
+但各存各的——只发自己那一半，另一个字段原样不动。
+
+**实例端口就地可改**：每张实例卡右上角有「改端口」，点开直接填端口号（`8290`）或完整地址
+（`http://192.168.3.253:8290`）。只填数字时保留该实例原主机名，只换端口——这是"改了端口"的本意。
 `runs.json` 是「退出再登录还能看到历史和资产」的基础，写入已串行化（并发 rename 会写坏索引）。
 
 **旧数据迁移**：启动时跑两条幂等迁移——没有等级的账号（管理员→NSFW、其他→SFW）、
@@ -260,7 +328,7 @@ E:\ComfyUI-aki-v3.2\python\python.exe -s E:\ComfyUI-aki-v3.2\ComfyUI\main.py --p
 ## 测试
 
 ```bash
-node test/all.mjs                # 15 套件 424 项
+node test/all.mjs                # 15 套件 469 项
 node test/live-isolation.mjs     # 真机：账号隔离、表头、助手分级、重启后仍能取图
 node test/live-boundary.mjs      # 真机：成人提示词走 8187 API 直接出图（不审查）
 node test/live-heads.mjs         # 真机：表头随工作流、无文字输入的图不被污染
@@ -272,7 +340,7 @@ node test/live.mjs               # 真机：网关协议与出图
 | --- | --- |
 | `cost` / `settings` / `ordering` | 代价模型、设置合并、FIFO 与动态 LPT、优先级、并发上限 |
 | `gateway` | 真 HTTP 网关：/prompt /queue /history /view /system_stats /object_info /ws |
-| `lifecycle` / `resilience` | 真子进程启停（taskkill 杀树）、死实例故障转移、任务消失重排队 |
+| `lifecycle` / `resilience` | 真子进程启停：真 .bat 经 cmd.exe 启动、非 bat 被拒、taskkill 杀树、死实例故障转移、任务消失重排队 |
 | `remote` | 控制台协议、登录、工作流、生成、桥接租约、/media 归属 |
 | `isolation` | 账号隔离（工作流/任务/历史/媒体）、跨重启持久化、配对码开关、端口开关、迁移 |
 | `assist` | 表头随工作流走（继承默认值、显式指定、改后保存、切工作流即换）、无文字输入的工作流不注入表头、助手分级与无模型降级 |
@@ -281,7 +349,7 @@ node test/live.mjs               # 真机：网关协议与出图
 | `pages` | 三个页面的静态审计：脚本可解析、无裸 window 全局、id 都存在、布局顺序、无渐变/无 emoji；控制台是下拉选择、无显卡面板、描述框与提示词同卡、编辑仅管理员 |
 | `console` | 控制台接口：桥接仅管理员、参数真的写进图、资产像素尺寸与下载、越权取图 404、设置接口仅管理员 |
 | `layout` | 设备适配：UA 判定（iPhone/Android/iPad/平板/桌面/未知）、属性戳在 `<html>`、视口纠正脚本、HTTP 层首屏布局与 `Vary`、手机标签栏、两栏拍平 |
-| `render` | 侧边栏面板真渲染：分组、端口框、开关、账号等级 |
+| `render` | 侧边栏面板真渲染：分组、端口框、开关、账号等级；远程端口只在远程卡里、网关卡不含远程端口、每张实例卡都有「改端口」并真的驱动一次改端口 → 落盘（只填数字保留主机名）；托管方式读得到真实类型，且选择在重复轮询后不被重置 |
 
 `node test/screenshot.mjs` 用真 Edge 登录后截图到 `_shots/`——布局问题只有看图才发现。