dataelement · zgqgit · Aug 17, 2026 · Aug 7, 2026 · Aug 9, 2026 · Aug 9, 2026
diff --git a/docker/docker-compose.yml b/docker/docker-compose.yml
@@ -86,7 +86,7 @@ services:
 
   backend:
     container_name: bisheng-backend
-    image: dataelement/bisheng-backend:v2.6.0-fix
+    image: dataelement/bisheng-backend:v2.6.0-fix2
     ports:
       - "7860:7860"
     environment:
@@ -128,7 +128,7 @@ services:
 
   backend_worker:
     container_name: bisheng-backend-worker
-    image: dataelement/bisheng-backend:v2.6.0-fix
+    image: dataelement/bisheng-backend:v2.6.0-fix2
     environment:
       TZ: Asia/Shanghai
       BS_SSO_SYNC__GATEWAY_HMAC_SECRET: "bisheng-local-hmac-20260422"
@@ -161,7 +161,7 @@ services:
 
   frontend:
     container_name: bisheng-frontend
-    image: dataelement/bisheng-frontend:v2.6.0-fix
+    image: dataelement/bisheng-frontend:v2.6.0-fix2
     ports:
       - "3001:3001"
     environment:

diff --git a/docs/architecture/08-deployment.md b/docs/architecture/08-deployment.md
@@ -223,11 +223,56 @@ npm start -- --host 0.0.0.0   # 端口 3001，API 代理到 localhost:7860
 
 要点：
 
-- **为什么 2/3 自动、4 手动**：2/3 是纯 DB、幂等、轻量的 backfill，失败只影响菜单 / 模型配置且可自愈，适合放进启动 lifespan；步骤 4 要写对象存储（MinIO 上的 `SKILL.md`）、数据量可能大、需人工核对迁移摘要，副作用重，故保持手动运维脚本（详见 `src/backend/CLAUDE.md`「Migration vs. script」与 PRD 决策）。
-- **步骤 4 说明**：需要完整 app context（写 MinIO 的 `SKILL.md`）。**不调用 LLM**——技能描述取 SOP 原描述，缺失时用 SOP 名称兜底（技能描述为必填，不会留空）。产出 JSON 迁移摘要（成功/跳过/失败，**运维产物，无管理页报告界面**），失败 / 超大 SOP 项需人工处理（拆分后经管理页重建）。`linsight_sop` 原表保留归档、不删。
+- **为什么 2/3 自动、4 手动**：2/3 是纯 DB、幂等、轻量的 backfill，失败只影响菜单 / 模型配置且可自愈，适合放进启动 lifespan；步骤 4 要写技能正文、数据量可能大、需人工核对迁移摘要，副作用重，故保持手动运维脚本（详见 `src/backend/CLAUDE.md`「Migration vs. script」与 PRD 决策）。
+- **步骤 4 说明**：需要完整 app context（写技能 bundle）。**不调用 LLM**——技能描述取 SOP 原描述，缺失时用 SOP 名称兜底（技能描述为必填，不会留空）。产出 JSON 迁移摘要（成功/跳过/失败，**运维产物，无管理页报告界面**），失败 / 超大 SOP 项需人工处理（拆分后经管理页重建）。`linsight_sop` 原表保留归档、不删。
 - **幂等**：四步均可安全重跑。步骤 2/3 重复启动是 no-op；步骤 4 借 `metadata.sop-id` 识别已迁移项并覆盖自身 bundle，不会重复产生带后缀的技能。
 - 步骤 4 单租户灰度可加 `--tenant-id <id>`。
 
+### v3.0 · 灵思技能 bundle 迁至对象存储
+
+技能正文/脚本/附件此前以**节点本地文件系统**（`SKILLS_ROOT`）为权威存储，DB 只存元数据。单机
+compose 下 `backend` 与 `backend_worker` 恰好 bind-mount 同一个 `/app/data` 才让它工作；一旦两者
+不在同一台宿主机，A 机上传的技能在 B 机 worker 上读不到，而失败是**静默**的——任务照跑，只是技能
+不生效。现改为对象存储（MinIO）为唯一权威 + 节点本地按内容哈希缓存。
+
+| # | 步骤 | 触发方式 | 命令（从 `src/backend/`） | 不执行的后果 |
+|---|------|---------|--------------------------|-------------|
+| 1 | **加 `linsight_skill.content_hash` 列** | 🔧 部署流程 | `uv run alembic upgrade head` | 后端起不来（缺列） |
+| 2 | **发布本机残留的技能 bundle** | ✅ 启动自动（窄） | `python scripts/migrate_skills_to_object_storage.py` → `--apply` | 存量的**用户自建/导入**技能不生效 |
+| 3 | **内置技能重新发布** | ✅ 启动自动 | —（seeder 按内容哈希幂等） | 三个官方技能不生效 |
+
+要点：
+
+- **步骤 2 的启动自愈是刻意做窄的**：只发布本机确实持有、且字节数与 DB 记录一致的 bundle。多副本
+  同时启动时各自看到不同的本地盘，若谁都能发布自己那份，胜出者就是随机的——那正是本次要消除的
+  多节点不一致。凡不满足条件的，日志会**按技能名列出**，这就是「去持有该 bundle 的那台机器上跑一次
+  脚本」的信号。
+- **每台曾经跑过 API 的机器都要跑一次**步骤 2 的脚本。某台机器盘上没有的，它会报告出来。
+- **内置技能不需要迁移**：seeder 直接从镜像重新发布，比任何一台机器的磁盘都更权威。
+- **回滚**：新版本期间创建/编辑的技能只存在于对象存储中，旧代码只读本地盘，会**静默失效**。若确需
+  回滚，先在每台目标机器上跑 `python scripts/restore_skills_to_local.py --apply` 把 bundle 写回
+  `SKILLS_ROOT`。
+- 配置项 `linsight.skills_root` 已降级为「迁移脚本读取本地遗留 bundle 的来源」，运行期不再使用；
+  本地缓存目录由 `linsight.skills_cache_dir` 指定（留空 = 进程缓存目录下的 `linsight_skills`）。
+  **不要**把缓存目录指向共享卷。
+
+## 多节点部署
+
+官方 `docker/docker-compose.yml` 是**单机单副本**编排，但组件本身按多节点设计（`entrypoint.sh` 中
+workflow worker 明确标注「支持多节点运行」，灵思 worker 用 hostname 级 `node_id` + 心跳 + 任务
+ownership）。横向扩容时按下表核对。
+
+| 组件 | 可否多副本 | 注意事项 |
+|------|-----------|---------|
+| `backend`（FastAPI） | ✅ | 无状态。启动期 backfill/seeder 幂等，多副本同启安全 |
+| `backend_worker`（Celery + 灵思 worker + Beat） | ⚠️ | Celery worker 可多节点，队列名需按 `entrypoint.sh` 注释约定；**Beat 只能有一个实例**，否则定时任务重复触发 |
+| MySQL / Redis / MinIO / Milvus / ES / OpenFGA | — | 有状态，按各自方案做高可用 |
+
+**关键约束：不要用共享卷在节点间传递业务数据。** 权威存储只有 MySQL/DM8、Redis、MinIO 三处；节点
+本地磁盘（`/app/data`、进程缓存目录）一律视为可随时丢弃的缓存。这条已写入架构宪法
+[C8](../constitution.md#c8-no-shared-state-on-the-local-filesystem)。单机 compose 下 `backend` 与
+`backend_worker` 共享同一个 `/app/data`，会让「跨进程传文件」看起来能用——这是巧合，不是保证。
+
 ## 相关文档
 
 - 系统架构总览 -- `docs/architecture/01-architecture-overview.md`

diff --git a/docs/constitution.md b/docs/constitution.md
@@ -6,7 +6,7 @@
 > - `scripts/arch-guard.sh` is the **machine-enforcement arm** of this document: each RULE maps to a clause below (see the anchor table).
 > - Violations are reported as **BLOCKER** during `/sdd-review design`.
 > - **Change governance**: editing this file requires PR review (a law change affects every feature). If a RULE is involved, sync the "→ Cx" note in `arch-guard.sh`.
-> - Last revised: 2026-08-06 (F048: lazy permission runtime and operational migration traffic control).
+> - Last revised: 2026-08-14 (C8: no shared state on the local filesystem).
 
 ## Anchor Table (clause ↔ arch-guard RULE)
 
@@ -19,6 +19,7 @@
 | **C5** | Error-code convention | — (review) | — |
 | **C6** | No hardcoded secrets | RULE-7 | WARNING |
 | **C7** | Frontend store must not call HTTP directly | RULE-6 | WARNING |
+| **C8** | No shared state on the local filesystem | — (review) | — |
 
 ---
 
@@ -133,3 +134,30 @@ No `password` / `secret_key` / `api_key` / `access_token` literals in code. Use
 
 A frontend store must not call HTTP directly — go through `controllers/API/` (platform) or `api/` (client).
 All other frontend conventions (state library, UI library, path aliases, i18n, Toast, etc.) live in `.claude/rules/platform-frontend.md` and `.claude/rules/client-frontend.md` (see also `AGENTS.md §4`).
+
+## C8. No Shared State on the Local Filesystem ⚠️
+
+**Multi-node is the default assumption, not an edge case.** The backend already runs as several
+processes that need not share a machine: API replicas (`uvicorn --workers`), Celery workers, the
+Linsight worker (`bisheng/linsight/worker.py`, hostname-derived `node_id` + heartbeats), and Beat.
+Two processes agreeing today only because a single-host `docker compose` happens to bind-mount the
+same `/app/data` is an accident, not a design.
+
+The authoritative store for anything read by more than one process is **MySQL/DM8, Redis, or MinIO**.
+The local filesystem is a cache: disposable, rebuildable, never the source of truth.
+
+| ✅ Use | ❌ Never |
+|--------|---------|
+| Object storage for bytes + DB row for the pointer | A DB row whose payload only exists on the writer's disk |
+| Content-addressed keys, local cache keyed by that hash | A mutable local path treated as the live copy |
+| Startup work registered in **every** process role that needs it | Initialization only in `main.py`'s FastAPI lifespan |
+| Fail loudly, or report the gap to the user | Log a warning and continue silently degraded |
+
+Reference implementations: `WorkspaceBackend` (MinIO truth + write-through cache) and `SkillStore`
+(content-addressed objects + local materialization) in `bisheng/linsight/domain/services/`.
+
+Precedents that make this a law rather than advice: skill bundles shipped as node-local files and
+were unreadable from any other host (fixed by moving them to object storage); the F048 resource
+registry was installed only in the API process and had to be retrofitted into the background
+workers (`02cbb921a`). Both failed **silently** — which is the real cost, and why the last row of
+the table matters as much as the first.
diff --git a/features/v2.6.0/035-linsight-task-mode/design.md b/features/v2.6.0/035-linsight-task-mode/design.md
@@ -577,7 +577,9 @@ SKILLS_ROOT/                          # 配置项 linsight_conf.skills_root（v2
 
 `FilesystemBackend(root_dir=SKILLS_ROOT, virtual_mode=True)`：`virtual_mode=True` 把所有路径约束在 `root_dir` 内，**防路径穿越**（`../` 逃逸被拦截）。租户自定义目录按 `tenant_id` 分片，配合 §6 自动注入实现隔离。
 
-> ⚠️ **多节点部署约束**：`worker.py` 的 `NodeManager` 为多节点设计（hostname 级 node_id + 心跳 + ownership），磁盘 Skill 要求 `SKILLS_ROOT` 为**所有 Worker 节点可见的同一卷** —— 须满足「灵思 Worker 单机部署」或「多机挂共享存储（NFS 等）」之一，否则 A 机新建/编辑的 Skill 在 B 机 worker 上读不到、CRUD 与执行不一致。元数据若入 DB 则跨节点一致；**正文一致性依赖共享卷**。运维须将此约束写入部署文档；启动期可加 `SKILLS_ROOT` 可写 + 共享性自检告警。若未来多机且不便共享盘，演进为 MinIO 正文 + 本地物化（`FilesystemBackend` 退化为物化后的本地只读层）。
+> ~~⚠️ **多节点部署约束**：`worker.py` 的 `NodeManager` 为多节点设计（hostname 级 node_id + 心跳 + ownership），磁盘 Skill 要求 `SKILLS_ROOT` 为**所有 Worker 节点可见的同一卷** —— 须满足「灵思 Worker 单机部署」或「多机挂共享存储（NFS 等）」之一，否则 A 机新建/编辑的 Skill 在 B 机 worker 上读不到、CRUD 与执行不一致。元数据若入 DB 则跨节点一致；**正文一致性依赖共享卷**。运维须将此约束写入部署文档；启动期可加 `SKILLS_ROOT` 可写 + 共享性自检告警。若未来多机且不便共享盘，演进为 MinIO 正文 + 本地物化（`FilesystemBackend` 退化为物化后的本地只读层）。~~
+>
+> **已解决（v3.0，2026-08-14）**：本段末尾预留的演进路径已实施 —— Skill bundle 改为**对象存储内容寻址**（`linsight/skills/{tenant_id}/{name}/{content_hash}.zip`）为唯一权威，节点按内容哈希本地物化；共享卷不再是正确性前提。`SKILLS_ROOT` 降级为迁移脚本读取遗留 bundle 的来源。约束本身也已上升为架构宪法 C8（禁止用本地文件系统承载跨进程共享状态），并写入 `docs/architecture/08-deployment.md`「多节点部署」。**当时把它降级成一条"运维须知"而没有落地，是这次返工的根因**：契约写在设计文档里、部署文档零覆盖、启动自检也没做，等于没有约束。
 
 > **两类技能的本质区别（对齐 PRD §4.5/§4.7）**：`built-in/` 是任务模式**内核能力**，所有租户共用同一份磁盘文件、随内核常驻加载，**不出现在技能选择器与管理页，也不经 `/skill` API**；`data/skills/{tenant_id}/` 才是前端可见、可管理的**租户自定义技能**（租户管理员从 0 新建 / 导入）。系统管理员不直接管 built-in，如需维护某租户的自定义技能须经 admin-scope 切入该租户。