@microi.net/cli 6.1.7 → 6.1.8

package/skills/v8-file-upload/references/hotspot-offload-operations.md

@@ -0,0 +1,103 @@
+# 热点公开资源分流操作流程
+
+<!-- microi-progressive:chunk id=v8-file-upload-011 sha256=4983b127efd106705151c7a304de2b3eb30e824068f5b92df73352e79663b322 -->
+## 从费用需求到实际分流
+
+用户希望降低 OSS/CDN 下载费用时，先核对当前连接、运行能力、配置和真实消费入口。
+不全桶迁移，不删除云端源对象，不把私有文件改公有，不承诺费用降到零。
+
+### 配置与计量
+
+- 系统设置路由 /system-config：备用文件服务器 FileServerBak，备用分流阈值（GiB）
+  FileServerBakThresholdGiB，备用分流统计窗口（小时）FileServerBakWindowHours。
+- 示例 1 / 24 表示一个对象或完整公开依赖组在已结束的完整北京时间自然日内，
+  可信实际下载字节达到 1073741824；不是文件大小、当前部分日或滚动窗口。
+- 当前 FileServerBak 使用 HTTPS origin（允许端口，不带桶路径）；SaaS MinIO 绑定
+  内外端点、公私桶与凭据。HDFS 保持 Aliyun，原 FileServer 保留作权威来源/回退。
+- 首次可信达标后 LowTrafficRevokesPreference=false：后续低流量、重启或缓存丢失
+  不撤回同源偏好。内容更新须重新验证；来源/权限改变、健康失败或管理员停用优先。
+
+### AI / MCP 执行顺序
+
+1. profiles 核对 ApiBase、OsClient 与工具链版本；读取当前管理能力、Schema 及唯一
+   sys_config 记录，仅投影三个备用配置字段。先发现、describe_tool 再调用写工具。
+2. microi_run_engine 调用 mci-file-resource-runtime，先 Action=Capabilities、Status，
+   检查原生协议和实际部署；配套系统设置、系统日志/监控应用通过官方应用包安装。
+3. 非敏感阈值通过标准配置保存与独立回读。MinIO 只用 microi_manage_saas_minio：
+   Inspect 取得 Revision，Save 绑定 expectedRevision 与 SAVE_MINIO:<tenant>:<revision>，
+   再 Inspect / Probe。凭据只写不读；超时先回读，不盲重放，不向通用表或临时 V8 写密钥。
+   当前工具列表缺失时核对发行包与已加载 MCP，更新后重新发现；不能猜不存在的工具。
+4. 读取固定任务 microiPublicResourceOffloadScheduler / mci-file-resource-scheduler，
+   保留其启用/暂停意图；不能新建第二套采集复制循环。任务配置需按 job-engine 规范。
+5. 在资源状态读取 Collector、WindowEvaluations、来源绑定、复制与 LastPump，按真实
+   Id/对象键定位失败。采集受 30 分钟到期门禁，日报迟到补最近两个完整日；未知不是零。
+6. 已有历史热点可在授权范围通过 PinHistoricalHotspot、PinHistoricalPublicObject 或
+   PinHistoricalAsset 明确选择；先读取当前引擎参数，按各自精确身份传参。
+   人工指定单独留因，不伪造当日流量、不直接写 Ready、不自动恢复已停用资源。
+7. 验证当前发布的完整依赖组，等原生复制、摘要和匿名门禁全部通过。应用 JS/CSS
+   必须有可信清单；模型包括贴图依赖。独立 JS/CSS 缺清单不能强当无依赖叶文件。
+8. 通过 mci-file-resource-public-url 或应用稳定入口验证选址，再从真实官网/应用
+   核对最终 URL 与 NAS 字节、MIME、CORS、HEAD/Range。静态主域仍 200 可能是保留
+   回退入口，不能仅据此推断全部失败，也不能据 NAS 副本 200 推断所有客户端已接入。
+
+### 请求批次与覆盖范围
+
+前端接入读取 `microi-frontend-sdk/SKILL.md`。独立项目的 SDK 实例使用
+`V8.configure({apiBase,osClient,fileServer,fileServerBak})` 同步当前租户配置，
+在首个资源请求前等待 `V8.resolvePublicResource(value,{private:false})`；
+明确公有上传元数据也可由 `resolveFileUrl` 解析。NAS 加载实际失败时，
+`V8.reportPublicResourceFailure(value)` 提供一次原址回退。
+主后台使用 `DiyCommon.GetPublicResourceRoute`；后端固定原子为
+`V8.Method.GetPublicResourceBackupUrls({ObjectKeys})`，由受管接口编排。
+独立 SDK 的 `V8` 实例不是主后台 V8 事件新增的同名全局函数，不能混用。
+
+ObjectKeys 协议最多 100 项，不代表一轮可确认任意数量的独立组。
+原生实际选择另受独立组数与时间预算约束；只采用每行 UseBackup=true 且回执完整的结果。
+诊断多组可按小批（例如 5 项）读取，并保留每项状态；未选择不是零流量或文件不存在。
+旧硬编码 URL、平台 bootstrap、私有对象和未接入 loader 单独列为缺口，不能全局字符串
+替换，也不能把公开编译组路由扩大到私有源码。
+
+### 归因与财务验收
+
+- 用 mci-cdn-manager 的 Reports / StorageLogs 等受管动作定位具体对象、请求数和字节；
+  公私桶、域名、日期、原始窗口、覆盖边界与 TOP 截断保留，旧报告不冒充当前全集。
+- 高请求数不等于同等次数的完整成功下载；GiB 与账单 GB 分开，不据样本分摊精确人民币。
+- Billing 采用相同币种/税口径，完整分页；OSS NetworkOut、CdnOut 与 CDN 下行分别核对，
+  CdnOut 已在 OSS 总额中时不再次相加。完整旧代码日与完整新代码可用日才能比较。
+- 首次复制成本、混合部署日、欠费停用日和当天部分账单分开；缺少可比日时实际节省为空。
+  按每个源的实际切换时间记录，不能用单节点健康或页面发布替代全部覆盖证明。
+
+<!-- /microi-progressive:chunk -->
+
+<!-- microi-progressive:chunk id=v8-file-upload-003 sha256=18bfbc6466abb62cec99d226b3bdd5091669a8317ab02f5045b7913f366c4334 -->
+## 跨平台文件同步登录会话
+
+文件柜、文件同步等需要连接另一套 Microi API 的工具，必须把远程平台视为独立登录会话：
+
+- 用户必须先完成远程登录，登录成功后显示远程用户名称、帐号、ApiBase、OsClient 和登录状态，并提供明确的退出登录操作。
+- 历史远程连接通过 `mci_` 前缀表保存，并按 `V8.CurrentUser.Id` 做行级隔离；不得把帐号、密码或 Token 放入 `localStorage`。
+- 密码和 Token 只能由受保护的接口引擎写入、读取和清理。数据库必须保存可校验的加密密文，普通 FormEngine 列表不得返回密文字段。
+- 密码和 Token 使用 `V8.Method.ProtectApiEngineSecret/UnprotectApiEngineSecret`，由宿主把密文绑定当前 `OsClient + ApiEngineKey`；不得从已脱敏的 `V8.OsClientModel` 读取 `AuthSecret/DbConn`，也不得使用进程级临时密钥。接口引擎 Key 必须稳定，确保服务重启和应用升级后仍能解密历史连接。
+- 历史连接列表只返回脱敏元数据；一键重连时再按记录 Id 和当前用户读取凭据。删除连接必须同时清除保存的密码和 Token。
+- 远程目标登录后必须调用文件柜能力探针 `mci_file_sync_capability` 检查同步协议版本，并使用其 `Data.FileManagerSysMenuId` 作为目标租户权威文件柜菜单；禁止硬编码发布端菜单 Id。接口不存在、未返回菜单 Id、返回 404/非标准结果或协议版本过低时，提示目标平台更新【文件柜】应用，不得继续同步。
+- 验收至少覆盖：登录成功显示身份、退出后 Token 清空、历史连接一键重连、删除连接、密文落库、服务重启后仍可解密、目标平台缺少能力接口时的升级提示。
+
+### 热点公开资源的可信分流
+
+8.7.11 原生后端把 5–64 MiB 既有公开对象（包括只有一个 8 MiB 捕获块的对象）交给同一原生 multipart 完成协议；保留源权限、签名状态、私有块和整文件 SHA、匿名 MIME/CORS/Range/健康门禁。未知结果先对账，不重新拉取已确认的 OSS 正文；停用仍先撤权再精确清理，不可手改 Ready。回归与实际 NAS 消费分别验收。
+
+- SaaS MinIO 绑定的凭据不能通过通用表工具写入。使用 `microi_manage_saas_minio` 的 Inspect → Save（Revision CAS）→ Probe；旧后端缺少入口先升级。它不改变 HDFS/OSS， 不复制对象或改变桶策略；签名桶探测成功与副本校验、实际分流是不同验收项。
+
+- `PublicResourceOffload/2` 与旧目录/路由第一版分别验收。系统日志应用拥有 `mci-file-resource-runtime`（管理员控制面）与 `mci-file-resource-public-url`（匿名只读公开选择）；目录的 Ready、流量和副本行不作为运行授权，不能通过普通 CRUD 制造成功。
+- 从当前 SaaS 引擎读取 MinIO 凭据，FileServerBak 使用 HTTPS origin 加后端绑定的公有桶。主 HDFS 保留 Aliyun；不全桶迁移、不删源、不公开私桶。第二版应用使用当前已发布公开运行清单完整分组；通用 v3 支持公开图片/音视频等叶子及 GLB/glTF 同桶相对依赖；包含 EXT_texture_webp 解析修复的原生后端仅允许扩展 source 为 images 的合法整数索引，内嵌图片无外部依赖，外链与普通回退图片均保留完整 URI/ACL/版本校验，未知扩展仍拒绝；此兼容不改变应用可见性、不接通未调用解析器的 loader，8.7.7 单对象 64 MiB、组 256 MiB；只有实际 Capabilities.GenericLargeCopyProtocol=PublicResourcePinnedByteCapture/1 的后续后端才将单对象/组分别扩至 2 GiB，含入口仍最多 128 对象，8 MiB 私有暂存块有签名 SHA 回执，恢复复用已确认块；依赖由暂存解析，完整 SHA 由 NAS 组装计算。源 ACL/版本与当前绑定是权威，ETag 不是 SHA。8.7.7 配套 Managed runtime 的 PinHistoricalPublicObject 仅传 ObjectKey，当前公开 HEAD 后保存人工历史选择，worker 重验相同源绑定/版本才纳入；不造流量、不直写 Ready、不恢复暂停。JSON 原样作为叶文件，不解析改写包内 URL，限额按实际原生能力回读，不放宽商城解析/安装正文限制；商城消费须对比返回 VerifiedSha256/VerifiedSize 与权威精确包版本，再验同响应 Binding，旧后端缺证明回源。未接可信提交清单的独立 JS/CSS 拒绝；完整复制、签名回读、匿名 SHA/MIME/Range/CORS 才 Ready，未包含精确 Origin 修复的通用后端仅接受 CORS *；包含本修复后亦接受与本次配置 ApiBase 的 HTTPS Origin 完全相同的单一值，错误域名、多个值、null 或缺失值仍拒绝。
+- 历史安装微服务的商城 `IsPublic=0` 不等同于其已发布编译文件是私有对象。只有原生 `InstalledPublicBuild/1` 提供者从主库独立读取当前应用、唯一协议 0–2 历史版本、唯一启用服务及完整 `dist/` 文件集合，复用安装别名四方一致性校验，并确认匹配且未到期的 `InstalledAliasReconciliation/1` 三次稳定检查点后，才可把整个公开构建依赖组纳入分流。每个文件必须标记 `PublicBuildOnly` 或 `PrivateSource+PublicBuild`，源对象当前公有 ACL、版本、原始 SHA 与同一复制 Run 的目标回执都要核验；单个 JS、私有源码、陈旧检查点、缺失成员或跨租户路径均不准入。首次开放目标前和健康续期复查全组，实际选择时再复查所选源对象；失败继续原授权下载链，不把 `IsPublic`、`LegacyUnverified` 或协议号改成公开/V3 成功。该接口只供原生宿主内部调用，不开放新的 HTTP、MCP 参数或可编辑 V8 能力。探测链最后一个 NAS 响应返回后，准备与续期都通过同一个完成门重新读取当前整组权威和公有 ACL，再检查租约并提交 Ready 或健康时间；变化则走现有失败撤权。两种真实访问入口使用同一个 5 秒总预算覆盖绑定、Redis、主库权威、ACL 和 HTML HEAD，原生权威读取最多 4 个并发，超时停止等待但占用槽位直到已启动读取结束，后续 SQL 不再启动；后台任务仍使用宿主原有取消期限。 稳定微应用资产入口的原生叶资源兼容（须部署包含此修复的后端）：既有 Controller 完成当前版本/清单选择后，若应用组路由不可用，可只读查询该清单**精确对象键、原始 SHA-256 与大小**匹配的通用公开 Ready 副本。公开对象仍须通过源 ACL/版本、源与目标绑定、健康期和受管 NAS URL 校验；不会把应用 IsPublic=0 改为公开，也不公开私有源码或私有对象。HTML、JS、CSS、JSON、SVG 及 OriginalStorage=1 保留原链。root/latest/版本路径即使同名同 SHA 也不能互借 Ready；历史榜单对象已复制不等于当前版本路径已接通。直接 static/CDN URL 绕过稳定入口时仍不受本兼容影响。该能力不新增 V8/MCP 动作或可由调用方覆盖的 owner/摘要参数。
+- 当前权威公开清单中的 `Sha256` / `ContentHash` 与历史 `Hash`（含小写别名）统一按原始文件 SHA-256 校验，仅接受 64 位十六进制值；现代字段优先，任一非空别名无效或多个别名冲突均拒绝。此兼容不改变文件大小、完整原始字节 SHA 回读、公私权限或发布/检查点状态，不能把 ETag、MD5 或目录声明当作可信摘要。
+- 1 GiB / 24 小时按最新已结束的完整北京时间自然日计算，不是滚动或当天部分窗口。CDN/已接 SDK 只证明正向下界，缺行/空报表不是零，版本内分摊未知。迟到日报只补采最近两个完整日；同日同域同 key 快照取最大值，跨域分开、跨日不合并；每个日期先保存指向另一日的签名游标再做 SDK/云读取，避免预算饿死旧日。未知计数为 null，WindowEvaluations 仅两条摘要，诊断明细超 3 MiB 显式截断并保留总数；超签名预算则拒绝签名。固定 microiPublicResourceOffloadScheduler / mci-file-resource-scheduler 使用主库鉴权及共享 tick 租约；旧 Disabled/已签 handoff 须租约迁移，不添 Pin/Ready。升级保留 Redis/索引、建事实表并统一全部节点；handoff 持久化后暂停、删除任务或 Redis 丢失不恢复旧宿主。统一 30 分钟采集；4 分钟 BudgetReached/Partial 不代表全体 Ready。首次资格进入主库签名 CAS，低流量、重启/Redis 丢失不取消；新版本重验权限和副本，显式停用优先。旧 v2 缺源桶/端点不能从 SourceRevision 反推：缺 ConfiguredSourceBinding 拒继承与路由；仅管理员新 PinHistoricalHotspot 对当前完整同清单/版本/SHA/大小/目标明确重申可复用旧 Ready，先健康回读，不造新自动资格。已有绑定不一致须新运行。CDN 只取当前源首次观察之后的整日，旧未绑定 SDK 累计保留但不合并。源码回归不替代生产采集、真实请求下降或完整日账单验收。 别名自动采集须含 NativePublicSourceAlias/1 的后端：固定云只读重验唯一同源 OSS 与显式同源 Host，无 rewrite/条件/未知配置；独立签名 ObservedSince 覆盖整日，本轮现查成功才归属，失败/变化/超过24小时观察间隔重建。只用既有source-observation-v1签名行的CdnAliasCollector子结构（50条/128KiB），不增物理StateKey；同源同目标保留，源/目标变化或旧节点丢字段只重置观察、不追认旧日。每轮最多2域、先存公平游标、每元数据调用15秒，共享总预算；原 FileServer/SDK路径保持。Status.LastCollection.AliasCollection/CdnAliasAuthority展示有限范围，不能把公有桶名当对象ACL，也不改变旧static消费者或SourceMappings；普通V8不能自报映射/流量。 实际旧URL消费须另具PublicSourceUrlRoutes/1：AliasCandidates仅发现；明确公有客户端提交精确无签名PublicUrls，native固定来源重验后走原Generic公开ACL/依赖/Ready选择，60秒有界证明不当永久授权。回执须精确SourceUrl/ObjectKey/目标前缀和最短健康期，tenant变化/异常行/过期回原地址；不得把同步assetUrl、启动JS、旧HTML或任意Three.js都称已覆盖。
+- HTTP/MCP只登记意图，目录 CRUD 不能制造 Ready；先通过拥有方应用包安装 mci_file_offload_state 及 Owner/StateKey 唯一索引，原生主库签名/CAS、租约栅栏与检查点负责副作用。Web/UniApp 按类型取 committed V3，旧 service 不遮蔽；源码草稿 Changed 仅在当前应用/版本均 Completed V3、精确提交归属/正栅栏/请求前缀/完整重算清单与双方摘要一致时沿用已验证运行副本，微服务还须精确匹配该提交投影及不可变对象键。Legacy/Failed/Building 不放宽；只改草稿不改 SourceRevision、不重读 OSS 正文，真正权限/版本/源绑定漂移仍撤权，禁止手工改 Success/Ready；保留权威 AppKey 原大小写，索引按状态键去重。未知上传先对账，异内容不覆盖。源 ACL/版本/依赖或配置变化停止新路由，签名前仍重验源权威。先确认消费路径，再分别验收实际下载下降与完整日费用，文档和离线测试不证明部署或省费。
+
+- 公开之前先持久化签名状态的 PublishedRuns 账本；停用/源变私有/版本或目标变化按账本撤自有前缀 GetObject，策略回读后须逐对象匿名 HEAD 403/404，不能把“移除自有策略”当匿名已撤销。旧目标绑定未知则 PreviousTargetBindingUnavailable 阻断，不借新目标凭据称旧 URL 已失效；历史缓存字节不能召回。
+- 已提交公开应用及受权威版本约束的历史安装包复用 PublicResourceLargeAssetTransfer/1：2 GiB 内按 8 MiB 私有块、NAS server-side multipart Copy 和持久完整 raw SHA 续传；每步 120 秒受宿主预算/租约取消，未知结果先对账。匿名 Range 逐段签名续验，ETag 不是 SHA；旧 MIME 仅在完整 SHA 相符后条件 COPY 修复并重验，不能放宽类型。停用/换版先撤权，精确清理自有 upload/chunk，保留失败账本。具备 PublicResourcePinnedByteCapture/1 时，普通公开叶文件 64 MiB–2 GiB 从 pinned 源块回读推进 SHA，再移交同一私有块，不二次下载 OSS；GLB 只读头与至多 4 MiB JSON，不整读 binary 或大临时文件。旧预知 SHA 入口保持。临时失败保留分块；显式停用/来源失效先记退休意图、撤权再断点清理，重新启用按新运行验证。完整日首次达标的同源长期偏好不随低流量撤回。>2 GiB、私有、缺可信清单的独立脚本和未接消费者仍不覆盖。
+- 历史大安装包使用独立 `PinHistoricalAsset / EnableHistoricalAsset / DisableHistoricalAsset / ListHistoricalAssets`，经标准 MCP 调用拥有方 Managed mci-file-resource-runtime。只传 SourceTenant/AppKey/VersionId/AssetPath；当前主库重新校验公开 Web/UniApp、已完成 V3 历史版本、请求前缀与完整清单 SHA。文件名版本不等于发布版本；不换 latest，不接收调用方 URL/摘要/Ready，不借用通用字节捕获替代历史版本授权。仅精确 exe/dmg/zip，单文件最多 2 GiB。
+- 历史 archive 状态独立主库签名/CAS，人工选择不伪造当前流量；重复 Pin 保留停用。8 MiB 原生分块、NAS multipart 与逐段匿名校验都保存可恢复回执，完整权威 SHA 才 Ready；源/目标变化先撤旧公开授权，私有暂存所有权保留待清理。匿名 Managed HTTP mci-file-resource-archive-download 只读重验后 302 到已验 NAS 或同一历史版本原云地址；私有/权威缺失拒绝。先部署接口再发官网，按 more/hdfs.md 分层验收。
+- 七文件消费者为 public-resource-router.mjs、diy.common.js、diy-imgupload.vue、diy-fileupload.vue、DiyTableSpecialCell.vue、diy-common.mixin.js、diy-richtext.vue：显式 Limit:false 初始 src/链接/新富文本插入前 await 批量原生 GenericPublicResourceRoutes/1，校验绑定、源/行/字段/租户身份，可观测错误最多一次原址回退。卡片 helper 无活动调用点不能算额外页面覆盖；私有、旧富文本 HTML、Three.js/AI 硬编码 URL、平台 bootstrap、独立 JS 缺清单、ZIP 聚合/下游 Office 仍未覆盖；完整入口和 HEAD 后失败限制见官网 more/hdfs.md。
+<!-- /microi-progressive:chunk -->