@microi.net/cli 6.3.0 → 6.3.3

package/skills/microi-deployment/SKILL.md

@@ -1,373 +1,376 @@
----
-name: microi-deployment
-description: Microi 安装、部署、升级和本地运行指南。用于吾码服务器运维面板 Microi.Panel、Docker Compose、离线安装、Windows IIS、源码运行、本地 ApiBase/OsClient 切换与浏览器隔离、数据库、MinIO、反向代理、滚动发布、健康检查、备份恢复和生产部署验收。
----
-
-> **Microi吾码基础规范（强制）：** 任何 AI 模型与宿主每次新建或接续吾码任务，先完整读取 `../workspace-conventions/SKILL.md`，必须执行版本播报、`@microi.net/cli` 后台自动升级、Skills/MCP 同步和进度播报。安装与诊断读取 `../microi-codex-installer/SKILL.md`；更新失败延后重试，不阻断当前工作。
-
-# Microi 安装与部署
-
-本 Skill 把官网 Docker、Windows 和源码运行文档转成可执行的安全流程。具体镜像、
-版本、端口和命令可能变化，执行前必须回读当前中文官网、仓库 compose/配置和目标
-主机状态，不能把旧示例当作当前生产事实。
-
-数据库备份 MCP 使用 `microi_list_database_backup_tenants` 盘点可备份租户，使用 `microi_run_database_backup` 提交带稳定幂等键的持久化任务。备份必须进入共享存储并回读文件大小、哈希和任务终态；本机进程返回成功不等于备份可恢复。
-
-## 必读参考
-
-- 完全断网核心 ZIP、宿主工具和验收：`references/offline-installer.md`
-
-- 部署方式、依赖、配置和验收矩阵：`references/deployment-matrix.md`
-- 完全断网核心 ZIP、宿主工具和验收：`references/offline-installer.md`
-- 系统级交付与 MCP：`../microi-system-delivery/SKILL.md`
-- 文件/对象存储：`../v8-file-upload/SKILL.md`
-- 数据库模型：`../microi-db-schema/SKILL.md`
-
-## 完全断网的新装入口
-
-核心 ZIP 由 `数据库、案例、文档、资料/offline/prepare.py` 制作；以 root 执行
-`sh microi-offline-linux-x86_64.zip` 自解压，目标机不要求预装 Docker、Compose、
-unzip、Python 或 curl。镜像和 SQL 与冻结的在线安装器同源，包和镜像身份均须验证；
-不允许联网补下载，也不覆盖已有吾码数据库。主机仍须满足 x86_64、systemd、内核
-4.18+、AVX 和 cgroup 控制器条件，CentOS 7 旧内核不属于该核心包范围。
-
-离线入口的 umask 077 不得让 MySQL 忽略配置：不含秘密的 `my_microi.cnf` 显式设为
-0644。子进程安装面板必须继承本次实际 API/Web 镜像仓库；宿主监测用只读方式访问
-`/home` 数据目录，并由 systemd 创建权限 0700、重启服务保留 inode 的运行目录。
-真实断网验收覆盖核心就绪、登录、存储公私权限、面板就绪以及服务器重启恢复。
-MySQL 就绪和后续 SQL 使用最终 TCP 服务，不能把镜像初始化时的临时 Unix socket
-当作就绪；新建容器的密码只在容器内读取环境，不拼入 Docker 命令参数。
-源码/单元测试、CDN 上传、NAS 校验和消费者回退分别记证据；细节读取上述离线参考。
-
-## 发布测试范围
-
-### 普通吾码发布固定流程（30 分钟）
-
-`PlatformRelease` 在同一原入口先执行 C# 编译及组件测试，再执行原有四组 Node 回归；
-编译或组件失败立即停止该候选，所有已选 Node 组、断言与最终证据门禁继续保留。
-
-测试失败后修复源码，且原会话尚无任何成功阶段/渠道时，可显式使用同一入口
-`--resume=<原会话绝对路径> --refreeze-unaccepted-candidate`。原生检查确认旧候选证据
-未改动、没有已封存测试/构建或已接受上传后，保留旧候选和原始 TRX/TAP，归档候选
-指纹到同一会话历史，再以原版本、渠道和累计起点重新冻结并执行完整门禁。
-此开关不能复用失败测试，也不能重写已有成功阶段；默认续发仍严格拒绝源码漂移。
-
-仅当用户明确改定唯一最终发行版本，且原会话没有任何成功阶段或上传时，使用原入口
-`--resume=<原会话绝对路径> --retarget-unaccepted-version=x.y.z` 顺延一次。原生门禁核验
-原计划、全部旧候选证据及不变的配置、渠道和测试范围，保留原始起点、版本变更记录与
-失败 TRX/TAP；新版本重新冻结并执行完整门禁。不得与重冻、凭据或控制恢复叠加，
-也不能用于已有成功发布结果的会话；普通续发仍保留原版本。
-
-收到“发布吾码”“完整正式发布”“一键发布”时，默认执行根目录 `Microi一键编译发布.sh --platform-release`（默认完整选项）：新版本号按原规则 +1 一次，NuGet、API Docker、PC Docker、官方网站文档及其 Docker 全部发布。官网不再是可选追加项；只有用户明确要求“仅前端/仅后端/仅官网”等局部发布时才缩小范围。完整入口使用 `PlatformRelease` 执行常规 Microi.Tests（平台单元/组件，不自动追加 Full 专项）、吾码前端通用 Node 测试、真实接口检查与最终加密产物启动/运行冒烟；扩展浏览器验收仅在显式传入 `--platform-frontend-tests` 时追加。真实付费 AI、鸿地/JUNCHI、XJY 等指定客户数据专项和 SQL Server 等独立提供商专项默认不纳入，不再逐次询问；只有用户另行明确要求专项时才执行，回执逐项列为“不适用/未执行”，不能冒充通过。独立商城应用、OpenClaw 等应用源码专项由各自入口执行，不作为平台发布前置；平台 SDK、商城协议、安装器、SaaS 与工作流通用回归继续保留。Microi Code/Agent 是独立产品，不混入吾码平台测试与发行。
-
-1. 默认确认 NuGet、API/PC 和官网完整渠道及版本；记录开始时间，每次新完整发布从当前版本 +1 一次。中断后使用脚本输出的 `--resume=<会话JSON>` 恢复同一完整发布，沿用原版本、渠道、候选和累计起点；`--release-version=x.y.z` 只用于显式选择版本，本身不代表复用测试或产物。不能仅凭版本文件未提交推断为续发。
-2. 取得对应产品锁并冻结源码、依赖与官网构建输入；执行本次基础范围全部 C#/Node 测试，核对接口及启动/运行回执；扩展浏览器测试仅显式追加 --platform-frontend-tests 时执行。禁止把缺少授权/夹具、零用例、失败、取消或跳过写成成功；不能因测试需要依赖就自动新建租户、安装应用或创建 Docker。保留既有测试数据写入保护。
-3. 以 `.microi-local` 选定配置复用 MySQL、Redis、MongoDB 和 SaaS 生效的 MinIO/OSS；生成平台正式产物，执行完整 DLL 加密和一致性校验，在本机进程运行最终产物冒烟。PC 执行自身正式构建与产物检查，官网执行原完整构建与页面验收，不使用临时运行容器替代本机程序。
-4. 完成 NuGet 与全部选中 API/PC/官网 Docker 推送，逐标签回读远端不可变 digest；新推送和断点复用都必须验证，并回读官网关键页面。任一渠道缺凭据、未执行、失败或未知，不能报告全部发布成功。
-5. 输出各渠道、候选标识、常规测试数量与结果及独立专项未执行清单、各阶段和总耗时、镜像 digest 及官网回读；回收本次进程/临时文件并释放锁。客户部署独立，不以镜像推送代替。
-
-交互选项确认完毕后，本轮共用一个 **1800 秒耗时目标，而非强制截止时间**，覆盖锁/资源准备、测试、编译、加密、冒烟、Docker 检查、推送与回读。超过目标时告警并记录当前阶段、实际耗时和瓶颈，继续推进至发布成功；不能仅因达到 30 分钟杀进程、停止后续步骤或将成功退出改为失败。真实命令失败、用户取消、单操作超时及安全门禁仍保持原有失败语义，定位修复后按候选与回执安全续发。阶段切换或重试不能隐瞒累计耗时，重启续发须保留前次及累计耗时；不能通过跳过测试、吞掉错误或重复盲跑来追求时长。
-
-用户要求同时完成源码交付时，先记录各仓原分支与上游，安全拉取合并并解决冲突，再冻结候选；按归属提交、推送原分支并独立回读。源码同步清单可以包含独立工具仓，但不因此触发其测试、打包或发布。分别记录 Git 准备、脚本执行和任务总耗时，整体仍争取 30 分钟；官网已属于完整发布默认渠道，开发工具和独立应用不因“有变更”自动追加。远端推送问题可以与合格制品发布并行解决，未补齐时如实标为未完成。
-
-普通发布的“完整”指全部发行渠道，不自动扩展测试深度。默认只运行基础平台 C#、平台/前端 Node 与最终产物冒烟。发布前一次完成版本、凭据、资源与官网基础预检；完成代码合并后冻结候选，避免边发布边追加其它任务。后续阶段失败时先保存候选、原始测试和已发布渠道回执，重新核验相同源码、配置、工具与实际产物后复用有效结果，只续做未完成范围；结果不匹配或缺少必要证据时按原门禁复验，不能把通过截图当作缓存。npm、NuGet 等渠道的正式发布命令明确成功，即记录对应渠道发布完成；用户已明确确认其本机终端发布成功时，同样直接按成功继续，不再要求提供最终输出或回执。默认不查版本索引、包页面或下载地址，不等待公共索引/CDN 传播，不因即时 404 重传、升版、降为未完成或再次追问。公共可见状态仅在用户另外要求时核验。
-
-**原生断点续发**：完整入口在发布结果目录保存 `session-*.json`，失败提示给出准确恢复命令。始终重新运行同一个正式入口并使用 `--resume=<会话JSON>`，禁止临时截取、拼接或改写脚本尾部。原始 TRX/TAP 重新核验后复用；前端构建文件、最终后端/加密/冒烟产物及 NuGet 包字节不变时复用。每个已接受的 NuGet 包单独记录，每个 Docker 标签须有独立摘要回执；续发只上传缺项，已完成 Docker 标签仍只读核对摘要，不覆盖其它任务后续发布。镜像身份读取 `docker image inspect` 的实际 `.Id`，不能拿构建日志的 config digest 代替。官网恢复只执行官网未完成部分，不重新选择 API/PC 渠道。
-
-**静态镜像校验复用**：一键入口的 `release-image-verification.mjs` 将同一次 `docker image save` 交给原有配置和五个 DLL 严格解析器，不创建容器；成功回执绑定同一发布会话、冻结候选、不可变 ImageID/configId、模板 SHA-256、加密回执原始 SHA-256 和校验器源码 SHA-256。绑定一致且证据完整才复用，命中仍读取真实 DLL 与加密签名，不能无意义重写 `encryptedAt`。身份、输入或证据变化时重新校验，失败不写成功缓存；每个远端标签仍独立回读摘要，缓存不能替代发布确认。
-
-**成功资源与共同基线回交**：准备前核对当前工作区实际脚本版本和门禁工具，不能因修复已推远端就认定旧工作区已更新。上轮及本轮成功发布、经官网真实回读的资源与 `.resource-sync-base` 必须随源码提交并回交原分支，不能只推版本文件导致下次重复合并。共同基线滞后时先核对上轮成功回执和当前远端差异，仅通过原生 `--repair-base-from-remote` 入口读取真实远端修复；不得伪造基线或强选本地吞掉远端变更。
-
-**耗时优化验收边界**：阶段回执续发、上述静态镜像复用和一次收集已选 Node 各组失败已有实现；Node 各组仍按原顺序各执行一次，任一组失败、缺用例、异常退出或取消均整体失败，不生成成功摘要。失败后的测试组级复用、测试并行和渠道并行尚未实施，不能作为已获得的提速承诺。30 分钟仍是待完整端到端实测的目标，须计入整合准备、失败修复、等待与最终验收；定向夹具通过不等于真实发布已达标，超时继续完成并如实报告。
-
-候选冻结前一次合并本批功能、修复和依赖输入；冻结后不继续接收下一批业务能力。新增需求或与本轮无关的改动排到下一候选。确需修改当前发布源码时，原测试不能继续冒充新候选结果；保留前次耗时和失败，再按实际变更复验。对没有改变的候选、制品与渠道，不重新准备、重测或重发。
-
-官网打包 Skills 一致性等构建输入在整套回归前检查；这是分发输入校验，不是执行 Agent 产品测试。官方资源 HTTP 524 按原同步器先回读完整状态，再用相同候选和 CAS 只补差异，最多定向恢复一次；其它真实错误直接保留失败。重试沿用原计时文件，退出后的修复/等待也计入累计总耗时。候选、配置、渠道、原始证据或制品变化时拒绝复用，先说明具体失效项；不能清空会话来掩盖失败，也不能给一个变化的候选换签成功回执。
-
-**普通发布禁止混入**：新建/准入主子租户、安装消息通知或聊天应用、Microi Code/Agent 的 Vitest/E2E/桌面打包、全提供商兼容专项。隔离测试数据与新建租户不是同一件事，不得借“准备权限夹具”触发安装。平台已有的通用消息/权限离线回归仍保留，不能为缩短耗时删掉已选断言。
-
-`--full-only` 仅供用户明确要求的独立深度测试；它不推送镜像，也不作为普通发布的隐含前置。`--microi-agent` / `--microi-code` 仅供独立产品显式发布。发布流程自身的修改只执行对应定向回归；没有新的发版要求时，不为验证规范再发一轮镜像。
-
-普通吾码 PC/API 发布使用 PlatformRelease，包含平台自动化、编译、闭源 DLL 加密、最终产物冒烟、Docker 推送和远端摘要回读；完整发布以 30 分钟为可度量预算，记录各阶段耗时，超时如实记未达标，不承诺未知网络下必然成功。普通发布不运行 Microi Code/Agent 测试，不新建租户、不安装聊天应用。Full 保留为显式独立深度测试；本次修复需要真实依赖时复用指定 MCP 的已授权环境，SQL Server 等兼容专项只在明确指定时执行。已选必测项仍须全部通过。
-
-搜索标签真实浏览器门禁默认使用 1366px 和 1920px 常规桌面；测试进程显式设置 `MICROI_TEST_BROWSER_4K=1` 时追加 3840px 专项。所选宽度随显式 Full 或浏览器专项矩阵冻结，回读必须包含全部所选用例且零失败、零跳过；该变量不进入生产 API 配置。正式发布与同版本 Docker 热修复均拒绝历史 `--skip-tests` / `SmokeOnly` 入口，候选始终包含完整测试输入。
-
-本地发布测试默认复用 `.microi-local` 选定配置对应的已有服务，HDFS 使用该租户 SaaS 的实际 MinIO/OSS。固定夹具库名、端口或归属冲突先修正配置传递和可配置隔离，采用本任务唯一记录/Key/对象前缀并核验所有者；不能因此新建本地依赖容器、切换到其它 MCP 租户、删除他人夹具或放宽断言。清理与专项例外统一见 [本地测试程序与依赖生命周期](../workspace-conventions/references/progressive-02-microi-net-api-本地启动约定.md#本地测试程序与依赖生命周期强制)。
-
-选择、旧脚本冲突处理及结果记录统一读取 [发布测试矩阵](../microi-system-delivery/references/progressive-02-自动化测试必须覆盖的坑.md#按指定-mcp-选择发布测试矩阵) 和 `../workspace-conventions/SKILL.md`；实际目标未使用的提供商不能被虚构为已验证。
-
-完整入口自动读取当前工作区已忽略且仅当前用户/系统可访问的 `.microi-e2e/platform-release/profile.json`，也可由发行进程变量 `MICROI_PLATFORM_RELEASE_PROFILE` 指向既有授权配置。配置记录项目 `.microi-local` 对应依赖、明确的测试写入范围、归属及独立端口；必须保留所有者与目标校验，不存旧 Token，不依赖历史 `.tmp`。缺配置或授权不匹配时明确失败，不能自动创建租户、数据库、容器或安装应用。
-
-该入口在同一轮计时中启动受管原生依赖转发，待本轮构建完成后启动对应 API/Vite，并向测试子进程传递私有环境；测试完成先停止自有 API/Vite，转发保留到最终加密产物冒烟完成，脚本成功、失败或取消退出均精确收尾。显式已有 `MICROI_PLATFORM_RUNTIME_CONTROL` 时复用其监督进程，不重复启动；局部前端/仅官网入口不强制加载完整发布配置。只读检查可执行 `node Microi.Server/tools/platform-release-runtime.mjs dry-preflight <工作区绝对路径> [profile绝对路径]`，它不启动服务、不创建测试资源。
-
-## 先确认部署类型
-
-官方标准空库的新安装包含完整平台应用快照，安装记录与所保留资源的已校验版本一致，
-并保留系统首页及两个基础角色。历史库的启动恢复仍只修复登录、权限、导航和商城的
-最小基础；不能把启动投影当作完整空库，也不能在客户库执行空库清理。`ApplicationType=Platform`
-的“全部安装／更新”是显式维护动作，不得用作默认开机或普通功能联调的准备步骤。
-记录启动就绪、首次登录、商城打开、单个可选包安装和全部包维护各自耗时；全量维护通过
-不能代替最小空库验收。缩小启动范围不卸载既有租户的应用，也不删现有配置。
-
-### 吾码服务器运维面板 Microi.Panel
-
-- 项目由 `Microi.Ops` 更名为 `Microi.Panel`；独立 .NET + Vue + Microi.UI 宿主使用自己的管理员账号、SQLite 和 Docker 权限，业务 API/Web 停止时仍可操作。只安装面板时使用 `install-microi-panel.sh`，不要求先安装吾码业务平台、宝塔或 1Panel。具体命令与能力边界见中文官网 `server-panel/overview.md`。
-- 先确认主机内存、Docker Engine 身份、活动任务、已有 Ops/Panel 控制器、端口、编排和数据目录。每台 Docker 主机只运行一个吾码控制器。与宝塔/1Panel 共存时使用独立安装目录、容器名、卷、网络和端口；80/443 等监听端口不能被两个入口同时占用，不得重置 Docker 或自动接管第三方面板资源。
-- 安装器选端口同时回读 Docker PortBindings 与主机监听状态，包含未运行容器已声明的 TCP 绑定和本次规划的自定义 Ops 端口；探测失败不能当作空闲。WebSocket `/diy-websocket` 共用 API 端口，TCP/MQTT 使用各自显式映射。Ops 运行时禁止命令行竞争更新是控制器互斥，不能通过抢占或挪走 WebSocket 端口绕过。
-- 宝塔原厂进程检查可能识别 Docker 内的 Nginx，后装时即使端口独立也会提示已有 Web 环境。按已授权范围处理原厂确认：隔离机验收保存确认记录与安装前基线，客户机不自动确认未授权的覆盖或迁移。非交互执行要显式处理已识别的提示并设置超时，不能把挂起、安装器退出或仅出现目录当作安装成功；完成后回读原 Docker 身份、面板凭据/证书哈希及真实网站内容。
-- 1Panel 版本检查使用原厂支持的 `1pctl version` 或 `1panel-core version`，再核对 core/agent 的真实 systemd ExecStart 和官方包 ELF 哈希。不要猜测执行 `1panel-agent version`：已验收的 v2.4.1 会启动另一个 agent 并争用 Unix socket。宝塔新版本不一定保留旧 `data/version.pl`，应使用当前安装版本支持的读取方法，并独立验证真实服务、浏览器页面和网站。
-- 插件市场只安装目录内明确版本与 SHA-256 的镜像；检查架构、许可、健康检查、持久卷和真实业务读写。Oracle 等原厂许可渠道不擅自镜像；MinIO 社区归档后的源码构建必须保留对应源码、许可与摘要。跨数据库大版本升级仍需专用迁移方案。
-- 吾码新建网站和反向代理由受管 Docker Nginx 执行；配置先 `nginx -t`，再原子发布与回读。`2.0.2` 稳定版提供已有宝塔 Nginx / 1Panel OpenResty 网站直接管理：默认只读发现，用户明确接入实例后才允许修改其已识别站点。宿主适配器通过固定 root Unix socket 核对真实实例、站点配置和容器挂载，不复制第三方面板资源为假受管实例，不暴露任意文件或 Shell 入口。
-- 外部站点修改必须绑定实例指纹、站点标识、配置 SHA-256 和稳定请求号；CAS 不匹配停止覆盖。发布前备份原配置，校验、切换与重载失败保留恢复现场；历史回滚同样检查当前版本。原面板仍可管理自身资源，跨面板并发修改需重新回读，不能自动选择吾码版本覆盖。
-- 宝塔原生进程身份核验读取固定 PID 的 `/proc/PID/exe`，宿主 systemd 的能力集合需包含 `CAP_SYS_PTRACE`；同时用 `SystemCallFilter=~ptrace process_vm_readv process_vm_writev` 禁止实际调试和跨进程内存系统调用，保留 `NoNewPrivileges`、`ProtectSystem=strict` 和固定可写目录。必须在等效 systemd 限制下验证真实 Nginx 发现与禁止调用，不能用普通 root 成功或吞掉权限异常冒充接入通过，不新增任意 PID/Shell 接口。
-- HTTP-01 需真实 DNS 和公网 80 挑战路由，不能用跳过验证冒充签发成功。外部站点在已核验根目录及现有挂载内创建独立挑战子目录，helper 仅挂该目录；不得挂整个第三方站点根目录、重建原容器或异步镜像 token 冒充可靠挑战。已有验证 location/include 或重写冲突按实际适配结果处理，不盲目覆盖其它 CA 工具。通配符继续使用外部 DNS 验证后导入证书。
-- 自动续期默认启用，保留 lego v5 `run` 的 ARI 和动态有效期判断，不使用强制续签；正常检查不超过 12 小时，短周期证书缩短间隔。SQLite 持久化下一次检查、失败退避、操作编号和执行轮次；预检失败、重启与重复投递按同一轮次幂等补偿，已签发待发布时继续原检查点。暂停阻止后续排程及尚未开始的旧自动任务，不承诺终止已经发出的 CA 请求。
-- 区分普通 HTTP、TCP TLS 与 QUIC / HTTP/3 监听，不能因 `listen 443 quic` 没有 `ssl` 关键字就对其执行明文 HTTP-01 探测。持久旧计划按冻结配置正文重算传输类型，保留原请求、CAS、路由和隔离目录。初次网络失败留下本地 ACME 账号时，托管与外部站点共用恢复逻辑：只有 CA 明确 `accountDoesNotExist` 且本地没有注册回执才归档，保留原私钥，以无网络、独占状态卷的固定帮助容器完成可恢复步骤；不能清空状态卷或换任务掩盖失败。
-- 证书须验证私钥、有效期和 SAN，发布在 `nginx -t`、重载及真实 SNI 叶证书 SHA-256 回读成功后才提交；失败保留旧证书，回退也验证旧 TLS。外部网站重载后发布与恢复分别共享 10 秒回读预算，每轮全部域名/端口须同时通过精确叶证书与 HTTPS 响应检查；TCP、TLS、HTTP 和 Docker 读取都计入预算，身份/CAS 与非法重定向立即失败，不累计各轮局部成功。通用动态主页不强制正文恒等，真实验收的静态测试正文则须精确匹配。未换证书仅检查实际服务，不记作新签发。验收覆盖原任务重试、服务重启、暂停、配置冲突、新旧指纹及恢复失败；HTTP 200、文件写入和配置测试不能单独作为换证成功。
-- 网站文件仅管理受管卷；文本编辑使用内容哈希拒绝覆盖并发修改。冷备份须明确服务中断，检查正常退出与归档哈希；恢复写入新卷并保留原卷，重试继续原操作 Id。卸载保留业务卷，重新安装沿用记录的原镜像、凭据和数据卷。
-- 新面板默认独立 HTTPS 端口 61890，管理员密码与 PFX 密码存于服务器权限受限文件；不要把它们复制进业务 SaaS、V8、MCP 参数或日志。旧 Ops 保留原 `OPS_*`、目录、账号、端口、数据保护密钥及 `MicroiOpsUrl`，用原 Compose 替换为 Panel 镜像，不能重新初始化。
-- 业务 MCP 继续通过 `microi_get_administrative_capabilities`、`microi_admin_table_data`、`microi_update_module` 和应用发布工具维护平台入口；DiyToken 不授予主机 Docker 权限，不增加能从租户会话执行任意宿主机命令的工具。主机安装与恢复使用授权的 SSH/终端和独立面板会话。
-- 真实验收归入 `Microi.Tests/Panel` 专项，包含全部目录版本、数据库/对象存储写读与冷恢复、SSL/续期、文件、任务重启、独立安装升级回退，以及真实宝塔/1Panel 两种安装顺序。普通外部容器只能证明资源归属保护，不能替代第三方面板共存结论。
-- 上述外部网站管理与续期增强从 `2.0.1` 引入，现纳入含磁盘治理的 `2.0.2` 交付版本。源码安装器默认镜像准备为 `v2.0.2`；版本号不代表已经发布，必须核对同一冻结源码、实际镜像和最终门禁回执。完整门禁通过后先发布并回读镜像，再发布默认安装脚本，不可提前破坏仍使用历史镜像的公开入口。文档、单元测试或本地 CA 协议成功不代表新镜像正式发行、真实宝塔/1Panel VM 验收、公网 Let's Encrypt 签发或客户上线，必须分别保存并说明各层证据。
-- Let's Encrypt IPv4 免费证书的签发与续期均显式选择 `shortlived`，HTTP-01 仍要求公网 80；自定义面板管理端口不能代替验证入口。公网 CA 成功必须回读实际签发、在线证书和自动续期，本地测试 CA 只证明协议、部署和调度链路。共享工作区冻结验收时保留并发安装器改动，编译配置和测试依赖一并固定；原始失败记录不能改写成通过。
-- 集成夹具也必须挂载真实的磁盘维护 socket，让镜像拉取经过生产容量与回滚保护。原生 Linux 使用宿主服务；Docker Desktop 使用明确登记、核对所有权的独立服务与 socket 卷，控制器只读挂载。不能为了跑通旧用例关闭磁盘保护、伪造 Unix socket 成功或降低空间阈值。
-- 主机密码防爆破必须同时核对镜像 `io.microi.panel.authguard.protocol=1`、root 专用 Unix socket 和 `microi-auth-guard` 的真实回执。默认开启，同 IP 跨已接入服务累计 3 次封禁 86400 秒，窗口 0 表示累计至解封；成功登录不清零。配置与实际保护分别回读，来源日志/代理或防火墙异常不能标为已生效。稳定版无参数安装默认 `v2.0.2`，必须满足协议 1，不保留隐式旧版豁免。两种安装顺序、原厂网站管理及重启后自动续期已在 Ubuntu 24.04、宝塔 13.1.0、1Panel 2.4.1 上通过；证书测试 CA 与公网 CA 验收分别记录。显式选择历史镜像必须带 `--legacy-panel-only` 并说明不含新防护，已经安装协议 1 的面板禁止降为旧协议；不可在新镜像拉取失败后悄悄回退为无防护旧版。
-- 面板登录有独立 SQLite 防护与可撤销会话；SSH 读取真实宿主认证日志，新 MySQL/MongoDB 使用可验证认证日志，Redis 必须经逐次认证结果代理。禁止根据跨 IP 聚合的 Redis ACL LOG count 封禁最后一个 IP。新 Redis 使用独立网络、不直接发布后端端口；存量实例需维护窗口迁移，不能升级时静默断开连接或宣称已保护。
-- 主机防护使用最小 systemd 服务，面板只挂载其 root Unix socket，不给业务 V8/MCP 泛化 Shell/防火墙能力。nftables 使用内核超时；iptables 兼容模式的自动解封依赖运行中的守护进程。IPv4/IPv6、INPUT/转发、两个来源 IP、真实失败/成功、手动/自动解封、去重、重启、白名单与规则故障分别验收；Docker Desktop 的专有网络空间测试不能替代原生 Linux 安装/重启或客户生产验收。独立安全专项入口在 `Microi.Panel/Tests/Security` 和 `Microi.Panel/AuthGuard/tests`。
-- 宿主 Python 至少 3.9，检查 SSL、SQLite 和 `asyncio.to_thread`；旧系统用 `--guard-python /opt/microi-python/python/bin/python3` 选择独立运行时，解释器及真实祖先必须由 root 控制且不可组/全局写。不能替换系统 Python 或仅因宝塔自带解释器可运行就忽略版本要求；升级时保留并明确使用同一路径。`--check` 同样核验实际运行时，但不启动服务。
-- systemd 219–231 的安装兼容路径使用 `ReadOnlyDirectories=/` 加原固定目录的 `ReadWriteDirectories`，保留 `NoNewPrivileges`、能力集合、系统调用过滤及兼容内存限制；新版继续使用 `ProtectSystem=strict`。必须用当前 `systemd-analyze verify` 拒绝未知/忽略的关键指令，再做实际进程能力、挂载和网络验收。旧版使用 `systemctl show <unit> --all --no-pager` 读取完整属性，严格解析唯一 `Key=value`；未知单属性会返回错误，空属性在缺少 `--all` 时会被省略。缺少 InvocationID 时以稳定 PID/单调启动时间识别运行实例，读取错误或并发变化仍停止；不能改成无身份回读的覆盖。候选增强不等于所有旧发行版均已通过交付验收。
-- 旧版 `journalctl` 使用受限批次的 JSON 输出，不依赖 `--output-fields`；仍逐条检查可信 root UID、真实 sshd 可执行文件、时间戳与游标。旧 `iproute2` 不支持 `ip -j` 时，仅解析 `ip -o address show` 的固定地址字段；格式异常保留上次可信地址并明确告警，不能把广播地址或接口名加入白名单。
-- Docker 创建网络可能调整 FORWARD 顺序。iptables 只能重新定位带自有链归属证明的跳转：先插入带唯一注释的新首条，回读确认，再按旧规则的完整匹配条件移除旧跳转；禁止按规则序号删除、清空链或覆盖宝塔/Docker 规则。并发变化、封禁/解封内核回读或 TCP 实测失败时不能报告成功。
-- 生成 Compose 时 `cpus` 必须是 JSON/YAML 数值，不能用数字字符串假定旧 Compose 会转换。现场中断已生成账号、证书或编排时保留原文件，不重新初始化凭据；修复需保存原字节、限定修改字段并验证实际容器健康及就绪。
-
-### 宿主磁盘容量与历史镜像
-
-- 遇到频繁更新后满盘，先按 Docker 数据根、数据库/备份真实挂载盘分别核对空间与 inode；镜像、容器写层、标准输出、数据库数据/日志、备份、模型与构建缓存分别归因。`docker system df` 的可回收估算不能冒充实际腾出的磁盘空间。
-- `docker image prune -a -f` 只处理未被任何容器引用的镜像，重复执行不会变成卷或构建缓存清理；带标签回滚镜像也可能被清除。不要将其直接写入客户定时任务。数据卷未引用不等于可删除，默认不自动执行 volume/system prune。
-- 安装器部署、宿主独立执行、面板管理同一策略；业务 API 不新增 Docker socket 或另一份主机清理调度。源码安装候选默认开启安全回收，仅限已登记的吾码 API/Web 历史镜像，保护停止容器引用、当前版本、至少两个不同历史版本及最近验证通过的回滚版本、预拉取目标、活动更新及恢复计划，默认连续未使用 7 天。删除前核对精确镜像 ID、引用、策略版本及共享维护锁，状态变化跳过，不强制删。
-- 容量不足先暂停新增拉取/更新并告警，不关闭数据库；拉取预检预算包含展开峰值、回滚、备份与安全余量，监测还须覆盖 inode。日志通过原编排轮转，不能直接删除 Docker 内部日志或数据库文件。默认不自动清理卷、停止容器、备份与其它项目资源；构建机缓存另行配置。
-- 实现事实源为 `Microi.Server/Microi.Panel/HostMaintenance`；`tools/sync-disk-guard-installer.mjs --check` 检查平台/独立面板安装器嵌入字节与原件一致。平台旧安装独立补装入口是 `install-microi.sh --disk-guard-install`，不进入数据库初始化。root 服务为 `microi-disk-guard.service`，账本在 `/var/lib/microi-disk-guard`；固定 root Unix socket 只向独立面板开放类型化维护动作，业务 API 不读取它。
-- 新装默认开启、15 分钟监测、UTC+08:00 每天 03:00 清理、空间/inode 85% 预警与 90% 暂停下载、另留 5 GiB、闲置满 7 天。原策略与停止状态升级时保留。预检先尝试原规则内最多 8 个候选，再独立回读容量；仍不足保持原容器并阻止本次新增下载。外部 Watchtower/手工 Docker 不受本入口仲裁，不宣称能拦截所有宿主写入。
-- `data` 登记只监测实际可写绑定盘，不授予数据库镜像或卷删除权；API/Web 登记核对部署清单仓库和实际容器身份。首次历史候选只标为未验证，不冒充业务回滚验收。预拉取每服务只固定最新目标，失败/恢复中的操作保护不超时删除；处理原任务后使用固定 complete 入口释放。
-- systemd 的只读沙箱不能作为宿主只读盘证据：容量读取 statvfs，真实挂载标志从 PID 1 的 mountinfo 核对，不关闭隔离或进入宿主命名空间。控制 socket、FIFO 和设备节点不作为数据盘检查；普通绑定文件和目录继续监测，避免小型 /run tmpfs 触发数据盘 5 GiB 余量误报。真实 Linux 验收同时覆盖服务重启、面板停止后的自动任务、跨进程 flock、数据卷校验和非强制删除回读。
-- 仅当实际安装并回读服务、策略、候选和删除回执后才称客户已启用。源码、Linux/浏览器专项、客户现场、候选分发、正式商业门禁分别记录；参数及排查命令原位维护在官网 `getting-started/docker-run.md` 的“磁盘容量与安全回收”。
-
-### 依赖镜像统一镜像源
-
-- 安装器、Dockerfile、发布与测试夹具的依赖镜像统一使用 `Microi一键编译发布配置.json` 中 Region/Namespace 对应的阿里云仓库。源镜像清单维护在 `Microi.Server/tools/dependency-images.json`，禁止客户每次安装直接拉 Docker Hub/MCR。
-- 联网发行机执行 `Microi一键编译发布.sh --mirror-dependencies`，由 `dependency-images.mjs` 读取同一配置的账号密码并用 stdin 登录；禁止将凭据写进命令、日志、镜像或仓库。完成后用 `verify` 回读摘要和多架构清单。
-- 上游固定 SHA-256；国内加速只能作为传输通道，不能修改版本、替换不明镜像或丢失 CPU 架构。上游和阿里云目标摘要不一致立即停止。Oracle/达梦/金仓等受许可限制的镜像只在具备再分发权后镜像，不用无授权镜像代替。
-
-用户明确要求同版本仅发布 Docker 热修复时，运行 `Microi一键编译发布.sh --docker-only-hotfix` 并选择后端镜像方案。该入口保持当前版本，禁止 NuGet、文档和官方资源数据库发布，同时保留 PlatformRelease、候选源码一致性、混淆后冒烟和镜像门禁。修复应进入本地源码及捆绑资源，由目标程序启动升级；不得通过直接改生产表结构代替源码修复。
-
-共享源码持续变化时，可在独立目录保存完整候选源码和依赖，以该目录运行同一 PlatformRelease 与发布脚本。专用测试服务使用独立端口，通过发布脚本变量 `MICROI_RELEASE_BACKEND_PORT`、`MICROI_RELEASE_FRONTEND_PORT` 指定收尾端口（默认仍为 61501、61500）；进程管理器仍必须核验 PID、命令行和工作区归属，不得结束原工作区服务。变量仅供发布脚本使用，不进入生产 API 配置。
-
-私有原生规则的静态后端组合必须设置构建专用 `MICROI_RELEASE_COMPOSITION_FILE`，不能把根仓忽略的应用源码当作已经进入发布候选。工作区内契约 `schema:1` 固定 `properties/files/directories/artifacts`；四个文件属性 `CustomAfterMicrosoftCommonTargets`、`PrivateRulesProject`、`ApprovedRulesBootstrapSource`、`MicroiCoreProject` 必须与当前 MSBuild 环境属性一致并进入源清单。契约、规则目录、静态审批及项目文件的新增/修改/删除均绑定候选，链接和越界路径拒绝。API 最终 `publish/<规则DLL>.dll` 必须与 `artifacts` 中后台审批的实际 SHA256 一致；不重新签名另一份 DLL 来通过门禁。普通无组合发布与 PC 制品保持兼容，镜像发布须推送命令明确成功并回读目标不可变摘要；目标部署和运行验收仍独立执行。详细契约见官网 `getting-started/local-run.md`；这是发行进程参数，不是生产 AppSettings、V8 或 MCP 代码上传入口。
-
-Windows Git Bash 发布锁必须把当前 Shell 的 MSYS PID 经真实 `ps` 的 `WINPID` 映射成 Windows 原生 PID，再以原生 PID 和唯一令牌登记、释放；映射失败或持有者退出立即停止，不借用其它进程。中文旧热修复入口通过 PowerShell UTF-8 命令行与精确工作区路径核验，不能只看标签或因大小写规范化误拒绝已核验入口。API、PC、官网和 Agent 仍各自互斥，实际 Bash 与原生宿主回归必须通过后重新执行所选发布门禁。
-
-PowerShell 5/7 进程管理入口同时固定 UTF-8 控制台与管道输出；脚本有 UTF-8 BOM
-不代表错误流编码正确。用真实子进程强制继承旧代码页，核对非零拒绝状态、完整中文
-诊断和无非法 UTF-8；保留原锁与进程归属断言，再重新执行所选发布门禁。
-
-macOS 前端构建使用有界 `vm_stat` 探针，根据真实页大小读取空闲页与可回收文件页；匿名非活动页、压缩页和已包含的预读页不叠加。探针失败时回退原生空闲内存，Windows/Linux 保持既有方式。吾码PC默认现代构建保留6144MiB堆，以5632MiB（5.5GiB）进程树预算加max(1GiB,物理内存3%)余量准入，32GiB主机约6.5GiB、64GiB约7.42GiB；全机占用97%暂停本轮树，95%以内连续五秒恢复。低于8GiB宿主保留至少1.5GiB余量，宿主限堆/自定义堆或未知阶段按堆加有界原生开销回退；串行压缩/legacy保留1536/2048MiB堆及768MiB原生下限，32GiB启动目标约3.25/3.75GiB。顺序阶段不叠加峰值，正式发布不跳保护，不结束共享服务；修复后执行所选发布门禁。
-
-DLL 加密脚本只在 Git Bash、MSYS 或 Cygwin 中转换 Windows 路径，优先使用 `cygpath`；macOS/Linux 必须保留原生绝对路径，不能把 `/Users` 或 `/usr` 误认为盘符。修复时先对隔离的构建副本执行原加密器，核对五个目标 DLL 的实际哈希变化及加密指纹，再由一键脚本重新执行 PlatformRelease、加密和最终产物冒烟；不得以专项测试替代发布门禁。
-
-加密脚本被 `source` 引入时只提供函数，不执行发行入口。SQLite 回归使用真实解释器及隔离标准库，Windows 选择 `python`，其它宿主使用 `python3`；不能用假解释器或跳过 SQL 断言。字节契约下的包投影、内联源码以及官方资源目录的全部 JavaScript 接口、表事件和 Hook 模板均按 Git 的 LF 规则检出，不能忽略原始字节差异来通过测试。缺少发行运行产物时，可按同版本包正文的大小与 SHA-256 恢复；明确标记为制品恢复，不能报告为新的源码构建。
-
-只要检测到闭源项目源码，就必须具备完整的五项目加密链；源码不完整、加密脚本缺失都要硬失败，不能降级为 `HAS_ENCRYPT=false` 的开源模式。一键脚本由 `release-encryption.mjs` 保存五个实际 DLL 的加密前后 SHA-256，并要求每个 DLL 字节改变且匹配原加密器指纹。上传 NuGet 前检查真实 ZIP 中所有闭源 DLL；上传后端 Docker 前通过 `docker image save` 静态读取镜像层中的五个 DLL，不创建或启动容器，与加密回执逐字节哈希核对。缺回执、明文重编译覆盖、包或镜像中的旧 DLL 均阻止上传；NuGet 等渠道发布命令明确成功可报告该渠道发布完成，不等待传播；Docker 还须回读目标不可变摘要；本地检查不能替代实际发布命令，目标部署和业务验收仍独立执行。
-
-在线 AI 的 MCP 运行目录必须由已锁定依赖干净安装、编译和裁剪后完整复制。生产命令的符号链接应解析为真实文件并保留执行权限，不能依赖即将清理的临时目录；损坏、越界或循环链接在替换旧运行目录前失败，重新打包清除旧依赖残留。保留制品门禁对符号链接的拒绝规则，专项验证使用同一复制逻辑并核对清理临时目录后命令仍可运行；修复打包逻辑后重新执行所选发布门禁。
-
-
-私有原生规则的静态后端组合必须设置构建专用 `MICROI_RELEASE_COMPOSITION_FILE`，不能把根仓忽略的应用源码当作已经进入发布候选。工作区内契约 `schema:1` 固定 `properties/files/directories/artifacts`；四个文件属性 `CustomAfterMicrosoftCommonTargets`、`PrivateRulesProject`、`ApprovedRulesBootstrapSource`、`MicroiCoreProject` 必须与当前 MSBuild 环境属性一致并进入源清单。契约、规则目录、静态审批及项目文件的新增/修改/删除均绑定候选，链接和越界路径拒绝。API 最终 `publish/<规则DLL>.dll` 必须与 `artifacts` 中后台审批的实际 SHA256 一致；不重新签名另一份 DLL 来通过门禁。普通无组合发布与 PC 制品保持兼容，镜像发布须推送命令明确成功并回读目标不可变摘要；目标部署和运行验收仍独立执行。详细契约见官网 `getting-started/local-run.md`；这是发行进程参数，不是生产 AppSettings、V8 或 MCP 代码上传入口。
-
-组合环境只属于发行工具所在工作区；临时测试仓库和其它源码根显式传递自己的环境。不得把主发行环境传入隔离夹具，也不得吞掉显式错误组合；实际 CLI 继续严格验证全部四项属性。
-
-原生依赖审批在目标 Linux CLR 中验证完整程序集引用链及实际字节哈希。驱动扩展也属于交付依赖：Oracle Core 23.26.300 同时交付同版本 Azure、Kerberos、OCI、ConfigFile、AWS、GCP 六个官方扩展及传递依赖，以 `ProviderDependencyDeliveryTests` 验证真实装载，不连接云服务。缺文件、身份冲突和哈希变化继续失败关闭；先复现并修复包装，再重新执行所选发布门禁 和镜像发布，禁止跳过未执行的依赖或开放 V8/MCP 任意装载。
-
-包清单不能代替真实程序集引用：Oracle AWS 扩展还引用清单未声明的 AWSSDK.SQS，Dos.ORM 显式交付官方 4.0.100.15 包，并由 NuGet 统一 AWS Core。回归递归检查扩展引用链，仍保留 512 个程序集预算；诊断集中列出缺失项，正式验证继续拒绝缺失和身份冲突。
-
-System.Drawing.Common 的 .NET 10 支持库引用 System.Formats.Nrbf，Dos.Common 显式交付同版本官方包；该文件不能从 WindowsDesktop 共享框架复制来冒充 Linux 制品。通过真实引用装载回归和 Linux 依赖验证，保留 Windows GDI 平台限制，Linux 绘图使用既有 SkiaSharp。
-| 场景 | 推荐入口 |
-|---|---|
-| 生产 Linux、快速安装、可滚动升级 | Docker/Compose |
-| 无互联网环境 | 在联网机制作离线包，再在目标机校验并安装 |
-| Windows 传统环境 | IIS + .NET Hosting Bundle + 独立依赖 |
-| 开发/调试 | 复用健康服务，或启动后端源码/隔离目录中的编译产物 + 前端 Vite；优先共用已授权开发/测试依赖 |
-
-本地测试遵循 `../workspace-conventions/SKILL.md` 的依赖生命周期：默认复用 `.microi-local` 选定项目配置对应的 MySQL、Redis、MongoDB 和 SaaS 生效的 MinIO/OSS，启动本机源码或最终产物进程。不能按 AI 任务、完整测试或双节点测试创建 Docker/Compose，也不运行临时 API/官网测试容器。无法复用时先记录具体缺口并修复，普通发布不授予新建容器例外。结束后精确回收自有进程及纯测试资源，回读清理结果，既有共享服务保持原状态。
-
-本地 `Microi.Client` 默认读取 `src/config.json` 的 `ApiBaseDev`，也允许在 `#` 前通过 URL 参数
-临时指定运行目标：
-
-```text
-http://localhost:61500/?OsClient=iTdos&ApiBase=https%3A%2F%2Fapi.microi.net
-```
-
-URL 的 `ApiBase`、`OsClient` 优先级最高，但不会隔离同源 localStorage/Pinia/Token。多个 AI
-对话或自动化并行测试不同目标时，每个 `ApiBase + OsClient` 必须使用独立浏览器上下文/Profile；
-Playwright 使用 `browser.newContext()`。人工第二组至少使用无痕窗口，多个 Chrome 无痕窗口不能
-视为多组强隔离。完整取值顺序、线上识别和验收见 `../microi-client-frontend/SKILL.md` 与
-`../playwright-e2e/SKILL.md`。
-
-不得在未确认目标主机、目录、数据卷和备份的情况下执行官网“删除所有容器/编排”
-或任何递归删除命令。
-
-## 变更前只读盘点
-
-至少记录：
-
-- 操作系统、CPU、物理内存、可用磁盘、时区与端口占用；
-- 当前 API/Web/Worker 节点数、镜像/版本、反向代理与证书；
-- MySQL、Redis、MongoDB、MinIO/HDFS 地址和持久卷；
-- 当前 `OsClient`、数据库备份、对象存储备份和配置备份；
-- JWT/AuthSecret 等集群共享密钥的指纹一致性，绝不输出明文；
-- `/api/Diagnostics/health`、`/api/Diagnostics/liveness` 与兼容地址 `/apiengine/platform-service-health` 仅证明 API 宿主存活，均不检查 MongoDB、Redis、MySQL 或外部设备接口；依赖可用性另查服务探针与真实业务路径。健康 GET 在动态路由和业务压力控制前响应，禁止把相似路径或 POST 当作免限流入口；
-- 当前运行中的 Node、dotnet、Docker build 等重任务。
-
-## 后端配置单一事实源（强制）
-
-Microi API 安装时，`AppSettings` 与同名容器环境变量只允许以下十个启动引导项：
-
-`OsClient`、`OsClientType`、`OsClientNetwork`、`OsClientDbType`、`OsClientDbConn`、`OsClientRedisHost`、`OsClientRedisPort`、`OsClientRedisPwd`、`OsClientRedisDataBase`、`OsClientDbMongoConn`。
-
-- 除这十项外，业务开关、超时、重试次数、资源上限、代理信任、密钥路径和第三方密钥通常必须在 SaaS 引擎 `sys_osclients` 的合适 Tab 中动态配置，并提供代码安全默认值；影响整个 API 进程的字段只读取主租户记录。唯一固定例外是官方 License 信任链：恢复重试次数/间隔使用代码常量，签发私钥只读取固定只读挂载 `/app/microi_private.pem`，不得为这三项创建 SaaS 字段。
-- 不得新增 `MICROI_*`、`DOS_ORM_*`、自定义 `AppSettings` 节点或通用 `Environment.GetEnvironmentVariable(name)` 作为 API 运行配置；新增配置必须同步升级字段、表单 Tab、脱敏/子租户隔离、缓存刷新、文档和源码扫描测试。
-- `ASPNETCORE_*`、`DOTNET_*` 属于 .NET 宿主配置；构建、安装器、测试、MCP 和发布脚本自己的进程变量也不属于 API 业务配置，但生产 API 代码不得读取它们来控制业务行为。
-- `AuthSecret` 等已有 SaaS 敏感字段继续由受保护的主租户记录提供。普通业务私钥路径仍按相应 SaaS 配置管理；官方 License 签发私钥路径固定为 `/app/microi_private.pem`，只允许生产签发节点只读挂载。密钥明文不得写入镜像、Compose、日志或普通 V8 投影。
-- 验收必须扫描生产源码、`appsettings.json`、在线/离线安装编排，断言 API 容器仅出现上述十项；不能只检查某一个示例文件。
-
-## 一键安装脚本版本时间（强制）
-
-- 每次修改 `数据库、案例、文档、资料/install-microi.sh`，必须同时更新文件头版本和 `SCRIPT_VERSION`，两处完全一致。
-- 新装 MySQL 推荐 `max_connections=500`、最高 800，内存预算优先：宿主 95% 与已算共享父级预算取较小值，留出 30% 给 API/同机服务，扣除全局缓冲及固定开销后按 8MiB/连接估算，低内存明确降低并提示。连接数不等于重 SQL 并发；临时表等按负载实测，不能宣称绝对无 OOM。已有数据库不自动改全局配置。
-- 未显式配置的 MySQL 业务池默认最大 100、最小 0，显式连接串优先；多个节点/租户、独立读写池、Quartz 与其它客户端须合计并保留管理员/备份/滚动发布余量。200 是否不足要看拒绝增量与总预算，大量 Sleep 不能证明泄漏，不默认杀连接、重启数据库或自动无限放大。
-- 固定格式为 `vYYYY-MM-DD HH:mm:ss`，使用 `Asia/Shanghai` 时间并精确到秒；禁止只写日期或沿用上一次修改时间。
-- 验收同时断言两处版本一致、格式正确，并以脚本实际启动输出为准；官网静态地址尚未发布新文件时，不能把本地版本误报为客户已经可下载。
-- 恢复旧数据库时，OCR、翻译等附加字段先出现不代表完整升级链已经成功。安装器必须先回读 `sys_config.ServerVersion` 达到本脚本最低版本并通过 API liveness/readiness，才能部署和配置附加能力；核心中间迁移失败或超时应失败关闭，禁止用部分字段就绪冒充整个平台升级成功，也禁止在升级事务仍执行时主动重启 API。
-- Compose v2 生成文件不再写顶层 `version`；所有模板直接以 `services:` 开始，避免 `the attribute version is obsolete` 告警。
-- LibreTranslate 属于一键安装默认组件：安装选择空输入按 `1` 处理，语言套餐空输入按基础套餐 `1` 处理；因此用户一路按 Enter 使用官方推荐组合。只有明确输入 `0` 才跳过，提示、端口预算、官网文档和静态回归测试必须一致。
-- OCR 的 Upgrade29 与 LibreTranslate 的 Upgrade31 字段门禁只在对应附加服务部署检查通过后回读，每秒一次、最多 15 秒；首轮成功就继续，超时快速关闭对应能力并提示镜像/迁移版本，不得退回 5 分钟空等，也不得直接创建字段绕过平台升级。附加能力门禁失败不得中断已通过完整升级链和 readiness 的核心平台。
-- 官方 API/Web 使用浮动 `latest` 时，生成的 Compose 必须设置 `pull_policy: always` 或在启动前显式拉取并核对，不能因宿主机已有同名镜像就复用旧版本；测试专用本机镜像覆盖必须明确使用 `never`，避免误访问或覆盖远端镜像。
-- 端口、密码和数据目录全部生成后，安装器必须注册统一的失败收尾：数据库、缓存、存储、API/Web、完整升级链或 API liveness/readiness 等核心后段错误保留原始非零退出码，并输出标题为“安装未完成”的恢复汇总，列出已生成端口、受限凭据文件位置与脱敏状态、目录、失败阶段和全部容器状态。OCR/LibreTranslate 的网络、镜像、容器或 SaaS 配置失败只记录附加能力警告、保持对应能力未启用并继续核心安装。两种结果都不得把 `Running` 当 readiness，也不得绕过 Upgrade29/Upgrade31 或完整升级链门禁。
-- 从客户/旧库恢复安装时，安装器只按 `OsClient + OsClientType + OsClientNetwork + IsEnable + IsDeleted` 处理目标主租户：0 条时幂等创建最小可运行记录，1 条时原位复用，超过 1 条失败关闭。禁止把所有活动 `sys_osclients` 批量改成输入的 OsClient；新记录不得落库 `DbConn/DbReadConn/DbMongoConnection` 或 Redis 主机、端口、密码，这些继续由十项编排启动配置提供。MinIO、OCR 等安装值随后只更新这个精确三元组并回读唯一性。
-
-### 复盘：普通帐号运行安装器直到步骤 5 才因 `/microi/compose` 权限失败
-
-- 触发场景：普通帐号已经加入 Docker 组，前四步的探测和交互看似正常；脚本在开放防火墙后直接执行 `mkdir -p /microi/compose`，才报 `Permission denied`。命令替换中的数据目录创建错误还可能被旧 Bash 的 `set -e` 语义掩盖，使成功提示先于真实失败出现。
-- 根因：安装器把 `sudo` 零散放在软件包、防火墙和 systemd 命令前，却没有在真实安装或修复入口统一取得 root 身份；同时假设精简系统一定安装 `sudo`，普通用户与“root 但无 sudo”两种环境都没有明确的早期门禁。
-- 通用规则：会写 `/microi`、`/home`、防火墙、systemd/cgroup 或 Docker 宿主状态的一键安装/修复，必须在步骤 1 和任何交互、凭据生成、宿主机写入前完成一次 root 门禁。普通帐号有 `sudo` 时重新执行同一绝对脚本并保留参数；无 `sudo` 或验证失败时零副作用停止并给出 `su -` 恢复指引。已经是 root 时不得要求系统额外安装 `sudo`；目录创建仍要显式检查只读文件系统、空间和权限错误。
-- 自动化检查：提供只执行权限门禁的无副作用入口；在本地 Linux 容器分别覆盖 root 且无 sudo、普通帐号且无 sudo、普通帐号通过 sudo 提权三种场景，断言成功路径最终 `uid=0`、失败路径发生在步骤 1 之前且不创建 `/microi`。源码契约同时锁定正常安装与 `--repair-app` 均调用同一门禁，并执行 `bash -n`。
-
-## 多节点与滚动发布
-
-后端默认按多个 API/Worker 节点设计：
-
-- 所有节点共享业务数据库、MongoDB、Redis 和持久对象存储。
-- 全局状态、任务进度、锁和幂等事实不能只放进程内存/本机文件。
-- 新旧版本并存期间使用“先扩展、后迁移、再收缩”的兼容顺序。
-- 节点先停止接新工作，再有界排空；readiness 退出流量，liveness 只反映进程存活。
-- 数据库迁移、建索引、种子和缓存预热必须幂等，多节点同时启动不能重复副作用。
-- AuthSecret 在全部节点保持一致；轮换必须有明确的全节点策略，否则现有 JWT 会失效。
-
-## 构建资源保护
-
-启动 Node/Vite/dotnet/Docker build 前检查物理内存和同类进程。默认只运行一个重任务。
-吾码PC使用上文专用准入和97%暂停/95%稳定恢复策略；其余任务的启动门槛按“当前阶段进程树预算 + `max(1.5GB, 物理内存 5%)` 系统安全余量”计算，
-优先采用实测峰值；顺序阶段分别计算，不叠加峰值，也不得再用固定 20% 随机器容量放大门槛。
-资源不足时改做定向测试/构建，不并行启动多个全量任务；其余任务全机占用达到95%时暂停或终止本轮启动的重任务树。
-
-## Windows 多 AI 本地服务与 Release 文件锁
-
-多个 AI 对话共用同一工作区和固定 `61500/61501` 时，前后端是工作区级单例共享服务，
-不是每个对话各自拥有的后台进程。发布必须使用“同范围互斥 + 精确身份识别 + DLL 锁复核”：
-
-- 健康开发服务默认复用；需要重载源码时串行重启。长期后端只从项目目录执行
-  `dotnet run --launch-profile Microi.net.Api`，禁止直接运行 `bin/Release/net10.0`
-  或 `bin/Release/publish` 作为长期 E2E 服务。一次性测试本轮编译/发布产物时，复制到任务隔离目录启动，并登记身份、端口与最终收尾，避免占用共享 Release 输出。
-- API、PC、官网、Agent 分别使用 `api-release.lock`、`pc-release.lock`、`website-release.lock`、`agent-release.lock`，可并行发布；同类发布互斥。合并发布只取得所选产品的锁，部分取得失败时释放本次已取得的锁。
-- API 启动前执行 `node Microi.Server/tools/release-lock.mjs assert api <工作区根>`，PC 使用 `assert pc`；官网/Agent 不阻塞二者。旧全局锁仅在真实命令入口和状态目录证明 API 热修复或 Agent 归属后缩小阻塞范围，未知锁仍阻塞，不能删除活跃锁。
-- Windows 发布前调用 `Microi.Server/tools/Microi.LocalProcessManager.ps1 -Action PrepareRelease -ReleaseScope api|pc|all`。API 仅处理匹配工作区的后端与 Release DLL；PC 仅处理匹配的 Vite；官网不清理二者。禁止按进程名全机清理。
-- PC/API 普通发布执行 PlatformRelease，Full 仅为显式深度测试；restore/build/test/package audit 输出统一隔离到本次结果目录 `.net-artifacts`。并行验收使用独立结果目录及所需测试服务/端口，普通发布不创建租户；共享版本与跨产品源码先冻结，测试期间不得修改。资源排队依据为当前并行阶段预算之和与系统余量，不使用单一全局发布窗口。
-- 测试进程的 `MICROI_TEST_REPOSITORY_ROOT` 必须绑定本轮源码工作区；源码定位核对真实项目文件，不能把 SDK 产物中的同名目录当成源码。内存诊断保留子进程隔离，只使用当前 Configuration 和当前输出布局对应的夹具 DLL，缺失即失败，禁止借用旧 Debug 产物。诊断守护器的调用参数与报告路径必须属于同一次尝试，历史报告不可用于本轮放行。
-- Vite 以相对 `node_modules/vite/bin/vite.js` 启动且父进程退出时，命令行可能没有绝对工作区路径。
-  进程管理器只能把只读回读到的 CWD 精确等于当前 `Microi.Client` 作为补充证据；读取失败、
-  CWD 属于其它目录或仅检测到孤儿状态时仍须失败关闭。回归同时覆盖当前工作区可精确停止、
-  外部工作区同名相对 Vite 保持运行。
-- 停止后必须确认 `61500/61501` 已释放，并以 `FileShare.None` 独占打开
-  `Microi.net.Api/bin/Release/net10.0` DLL。只结束 `VBCSCompiler` 不能解决正在运行的
-  `.NET Host` 对业务 DLL 的锁定。
-- Edge/Chrome 用户浏览器、VS Code 的 Playwright Test Server、MCP/语言服务 Node、
-  既有或借用的数据库和 Redis 不属于发布清理范围；本轮新建临时依赖仍须按基础规范收尾。人工查看使用进程管理器的 `-Action Status`。
-- PowerShell 7 下的 macOS/Linux 进程管理使用真实端口、命令行、精确大小写 CWD 和启动时间回读；身份不明或 PID 复用时失败关闭，只结束已核验根进程的后代。无扩展名 `Microi.net.Api` apphost 须采用规范绝对可执行路径，精确位于当前 API 项目的 `bin/` 下，且 CWD 精确等于项目目录；非规范路径、同名外部程序、读取失败均拒绝。身份函数回归进入 Full，实际停止能力仍需自有进程与端口验收。专项回归必须在自有目录、端口和真实进程中证明当前工作区可停止、外部工作区保留，以及原始文件锁诊断；不允许为了跨平台放宽跳过门禁。
-
-## 一键发布产物边界与缓存
-
-- 最终 API 冒烟只临时注入项目配置中的十个基础设施 `AppSettings` 字段，不复制 `DevLoginBypass` 或其它本地节点，不改写用户源配置。成功、失败和可捕获中断都先恢复公共 `appsettings.json` 原始字节，再清理自有 scratch；恢复失败保留恢复证据并停止发布。产物捕获/复用、每次 Docker 构建及 API 镜像上传前均校验公共模板字节与 SHA-256，拒绝环境配置、旧冒烟备份和本地选择文件残留；镜像通过不可变 imageId 静态读取配置，不运行测试容器。不可捕获的强杀/掉电不保证即时恢复，后续门禁仍必须拒绝污染产物。
-
-- 一键脚本的本次构建、pack、冒烟日志和 NuGet 替换临时目录由 `Microi.Server/tools/release-scratch.mjs` 创建在发布结果目录的唯一 `release-scratch-*` 下，`EXIT` 自动收尾；归属清单与 `.cleanup.json` 回执在同级。成功仅留小回执，失败保留清单、原始错误和未清范围。它不删除 Full 报告、已发布制品、源码、共享 `.tmp` 或其它任务目录。执行器在 shell 启动前拒绝时，脚本内检查尚未运行；先定位当前宿主与拒绝阶段，不换工具绕过，也不默认添加 `-Force`、清除属性或修改 ACL。完整规则见工作区规范的“Windows 默认普通删除与策略拒绝排查”。
-
-- 需要完整解决方案构建和 NuGet 打包时，先完成一次 Release build；publish 阶段复用已验证产物，禁止先 clean 再重复编译同一项目引用链。
-- API 镜像只允许使用 `bin/Release/publish`，前端镜像只允许使用 `bin/Release/dist` 和必要的服务器配置；`net10.0`、源码、测试输出及其它构建中间目录不得进入 Docker 上下文。
-- `logs`、故障 spool、WAL 和节点诊断文件属于运行态数据。发布前后及冒烟测试后都要从 publish 清理，但不得删除源码/持久卷中尚待重放的原始 spool；项目文件应从源头设置为不复制到发布目录。
-- 正式发布不需要 PDB 时，从 publish 清单统一排除项目引用和第三方 PDB，并在推送前断言数量为零；这不等于删除编译中间目录中用于本地诊断的符号。
-- Docker 使用内容摘要缓存并在基础镜像标签可变时检查更新；不要在每个镜像方案前无条件 `prune -a` 或永久使用 `--no-cache`。磁盘不足时先报告占用，再对精确目标做可恢复或有条件清理。
-- DLL 混淆/签名必须先于最终冒烟测试，确保被验证、写入 NuGet 和放入 Docker 的是同一份最终 DLL。前端旧浏览器产物可以按源码、转换器和依赖锁文件的内容指纹做增量缓存，但缓存命中后仍需执行完整依赖、polyfill 和入口校验。
-
-## 部署证据分层
-
-不要把某一层成功等同生产完成：
-
-1. 配置/compose 静态检查。
-2. 镜像拉取或定向构建成功。
-3. 容器/进程启动且无启动错误。
-4. liveness/readiness 正常，依赖可达。
-5. 登录、菜单、FormEngine、ApiEngine、文件上传等真实路径正常。
-6. 双节点重复投递、节点退出、滚动升级与恢复验证。
-
-未执行的层必须明确写“未验证”，不能用“部署成功”概括。
-
-### 复盘：启动文案变化导致一键发布冒烟假失败
-
-- 触发场景：发布产物已经输出 `Now listening` / `Application started` 并可访问，但发布脚本因为等待某句历史中文启动文案而持续到超时，期间运行态日志或 spool 不断写入 `publish/logs`。
-- 根因：把易变化的日志文本当成服务可用事实源；超时/异常路径没有对临时进程和运行态目录做完整的有界收尾。
-- 通用规则：发布冒烟必须启动最终混淆/签名后的产物，确认本次进程仍存活，再以 `/api/Diagnostics/liveness` HTTP 200 判定启动成功；使用专用空闲端口，成功、超时、异常和中断路径都要在有限时间内结束本次进程并清理 publish 内的临时 logs/PDB。新完整发布默认从当前版本递增一次；确认续发同一候选时显式传 `--release-version=x.y.z`，不能依据未提交版本隐式复用。
-- 自动化检查：构造不再输出旧中文文案但 liveness 返回 200 的版本，断言冒烟成功；另覆盖端口占用、进程提前退出和 liveness 超时，断言脚本失败原因准确、进程无残留、`publish/logs` 不存在。再把工作区版本设为高于 HEAD，验证新完整发布仍递增一次、显式续发版本保持不变。
-
-### 复盘：旧租户启动闭包把应用包展示字段当成物理列并反复重启
-
-- 触发场景：升级后的节点发现平台运行时接口缺失，准备从内置官方应用包自愈；旧包把接口名称导出为 `Name`，目标 `sys_apiengine` 的真实字段却是 `ApiName`，直接拼接包对象后出现 `Unknown column 'Name' in 'field list'`。修完别名后，另一批旧库又因 `UserId NOT NULL` 且无默认值、而少数新接口包漏出审计字段，出现 `Field 'UserId' doesn't have a default value`。启动门禁失败会使 Docker 的 restart policy 不断重启同一进程。
-- 根因：启动自愈把“应用包传输对象”误当成“数据库物理行”，既没有规范化历史别名，也没有按目标租户的真实表结构过滤；同时只检查“列是否存在”，却没有覆盖旧结构中仍为必填且无默认值的审计列。不同年代租户会依次暴露 unknown-column 或 required-column 错误。
-- 通用规则：任何在 FormEngine 可用前直接写核心物理表的可信自愈，都必须先规范化已知历史别名，再应用固定实体字段白名单，并与目标租户实时回读的物理列取交集；SQL 只使用经过双重筛选的固定标识符和参数值。官方包本身必须携带完整审计字段；无登录上下文的启动门禁还必须为历史必填审计列提供稳定的系统身份兜底，并为 `IsDeleted/IsEnable/Lock` 等开关及 `ApiRole/Files` 等集合字段补齐语义明确的插入默认值，这些默认值不得参与授权。必需业务列缺失时给出明确物理升级错误，写入后按稳定 Key 强回读，禁止把包级元数据直接转换成列名。
-- 自动化检查：使用包含旧 `Name`、未来包级字段、新版本可选列及缺失 `UserId/UserName/Lock` 的官方包样例，分别对完整结构与精简旧结构断言 `Name -> ApiName`、未知字段被丢弃、必需字段保留、审计字段和传统必填列获得稳定非空值；同时扫描全部启动闭包包，保证 `SysApiEngines` 只输出 `ApiName` 且审计字段及传统必填开关完整，并锁定新增接口生成器输出的集合字段，最后执行真实启动日志门禁回归。
-
-## 空数据库 SQL 导入回归
-
-- 官方七种空库发布后逐一记录 ZIP SHA-256/大小并纳入原生公开副本。安装器通过固定 Database 枚举的只读选择器解析当前 NAS 地址，正文先 hub.microi.net、失败再 CDN；NAS 及仍带当前证明的 CDN 必须校验 SHA/大小，不将过期缓存导入为最新版。自定义 ZIP 不改下载来源。
-- 空库初始登录密码只用宿主 CSPRNG 派生的六位随机数字，登录页提示和加密存储使用同一值；AuthSecret 独立保持高熵。不得缩短数据库/Redis/MinIO 凭据或改变恢复库密码。制作任务成功、CDN/NAS 回读和各数据库实际导入分别记录。
-- 空库应用清理必须以平台基础表为保护边界：历史业务包误声明 diy_lang、组件、角色等核心字典表时，V8 与原生清理均不得将其作为应用表删除。脱敏发生失败并清理临时库后，新的生成请求须从 Prepare 开始；不得把原 Sanitize 检查点当成已有临时库继续。
-
-- PostgreSQL 导出中的 V8、默认值和注释使用显式 `E'…'` 字符串，同时转义反斜杠、引号、
-  物理换行及控制字符。分别在 `standard_conforming_strings=on/off` 中完整导入，回读代码
-  哈希、长度、空字符串与 NULL；不能把关闭标准字符串模式当作通用修复，也不能删改 V8 代码。
-- MySQL 5.7/8 分别在隔离 Docker 数据库执行完整原始脚本。SaaS 宽表的非索引配置文本
-  优先使用 `mediumtext`，保留主键、租户标识和索引列；字段元数据、物理列与应用包 DDL
-  必须一致。不通过关闭严格模式掩盖行宽错误，不将字符转义问题一概归为字段长度不足。
-- 通过官方 MCP 修复母版后发布归属应用，后端导出修复进入镜像后再运行既有空库制作后台任务。
-  等待成功终态，完整下载各 ZIP 并校验 SHA-256，再做导入与数据完整性验收。
-
-## 禁止事项
-
-- 启动字段门禁必须检查核心普通列的可空约束，不能仅以“字段存在”判定就绪。旧库非空列在程序共享租约内放宽为 `NULL`，保留 Id/数据库主键、列类型、默认值、注释和索引；同版本热修复也需回读真实结构。修复必须在插入启动接口之前执行，禁止通过逐次补默认值掩盖结构问题。
-
-- 不把数据库/Redis/MinIO 密码写入仓库、日志、命令回显或最终答复。
-- 不因容器更新而删除数据库卷、对象存储卷或日志 spool。
-- 不在所有节点同时硬重启。
-- 不把 `docker ps` 的 Running 当作 readiness。
-- 不在没有备份和恢复演练时执行数据库升级或不可逆迁移。
-- 不修改 `microi.doc/docs/doc/about/update-log.md`，除非用户明确要求发版。
-- 撤回或重写版本日志前，必须遵循 `../workspace-conventions/SKILL.md` 的“多对话共享工作区变更归属保护”；当天提交、最新 `HEAD`、相同作者或相关提交信息都不能单独证明改动属于当前对话。
-
-- 空库应用清理必须以平台基础表为保护边界：历史业务包误声明 diy_lang、组件、角色等核心字典表时，V8 与原生清理均不得将其作为应用表删除。脱敏发生失败并清理临时库后，新的生成请求须从 Prepare 开始；不得把原 Sanitize 检查点当成已有临时库继续。
+---
+name: microi-deployment
+description: Microi 安装、部署、升级和本地运行指南。用于吾码服务器运维面板 Microi.Panel、Docker Compose、离线安装、Windows IIS、源码运行、本地 ApiBase/OsClient 切换与浏览器隔离、数据库、MinIO、反向代理、滚动发布、健康检查、备份恢复和生产部署验收。
+---
+
+> **Microi吾码基础规范（强制）：** 任何 AI 模型与宿主每次新建或接续吾码任务，先完整读取 `../workspace-conventions/SKILL.md`，必须执行版本播报、`@microi.net/cli` 后台自动升级、Skills/MCP 同步和进度播报。安装与诊断读取 `../microi-codex-installer/SKILL.md`；更新失败延后重试，不阻断当前工作。
+
+# Microi 安装与部署
+
+本 Skill 把官网 Docker、Windows 和源码运行文档转成可执行的安全流程。具体镜像、
+版本、端口和命令可能变化，执行前必须回读当前中文官网、仓库 compose/配置和目标
+主机状态，不能把旧示例当作当前生产事实。
+
+数据库备份 MCP 使用 `microi_list_database_backup_tenants` 盘点可备份租户，使用 `microi_run_database_backup` 提交带稳定幂等键的持久化任务。备份必须进入共享存储并回读文件大小、哈希和任务终态；本机进程返回成功不等于备份可恢复。
+
+## 必读参考
+
+- 完全断网核心 ZIP、宿主工具和验收：`references/offline-installer.md`
+
+- 部署方式、依赖、配置和验收矩阵：`references/deployment-matrix.md`
+- 完全断网核心 ZIP、宿主工具和验收：`references/offline-installer.md`
+- 系统级交付与 MCP：`../microi-system-delivery/SKILL.md`
+- 文件/对象存储：`../v8-file-upload/SKILL.md`
+- 数据库模型：`../microi-db-schema/SKILL.md`
+
+## 完全断网的新装入口
+
+核心 ZIP 由 `数据库、案例、文档、资料/offline/prepare.py` 制作；以 root 执行
+`sh microi-offline-linux-x86_64.zip` 自解压，目标机不要求预装 Docker、Compose、
+unzip、Python 或 curl。镜像和 SQL 与冻结的在线安装器同源，包和镜像身份均须验证；
+不允许联网补下载，也不覆盖已有吾码数据库。主机仍须满足 x86_64、systemd、内核
+4.18+、AVX 和 cgroup 控制器条件，CentOS 7 旧内核不属于该核心包范围。
+
+离线入口的 umask 077 不得让 MySQL 忽略配置：不含秘密的 `my_microi.cnf` 显式设为
+0644。子进程安装面板必须继承本次实际 API/Web 镜像仓库；宿主监测用只读方式访问
+`/home` 数据目录，并由 systemd 创建权限 0700、重启服务保留 inode 的运行目录。
+真实断网验收覆盖核心就绪、登录、存储公私权限、面板就绪以及服务器重启恢复。
+MySQL 就绪和后续 SQL 使用最终 TCP 服务，不能把镜像初始化时的临时 Unix socket
+当作就绪；新建容器的密码只在容器内读取环境，不拼入 Docker 命令参数。
+源码/单元测试、CDN 上传、NAS 校验和消费者回退分别记证据；细节读取上述离线参考。
+
+## 发布测试范围
+
+### 普通吾码发布固定流程（30 分钟）
+
+`PlatformRelease` 在同一原入口先执行 C# 编译及组件测试，再执行原有四组 Node 回归；
+编译或组件失败立即停止该候选，所有已选 Node 组、断言与最终证据门禁继续保留。
+
+测试失败后修复源码，且原会话尚无任何成功阶段/渠道时，可显式使用同一入口
+`--resume=<原会话绝对路径> --refreeze-unaccepted-candidate`。原生检查确认旧候选证据
+未改动、没有已封存测试/构建或已接受上传后，保留旧候选和原始 TRX/TAP，归档候选
+指纹到同一会话历史，再以原版本、渠道和累计起点重新冻结并执行完整门禁。
+此开关不能复用失败测试，也不能重写已有成功阶段；默认续发仍严格拒绝源码漂移。
+
+仅当用户明确改定唯一最终发行版本，且原会话没有任何成功阶段或上传时，使用原入口
+`--resume=<原会话绝对路径> --retarget-unaccepted-version=x.y.z` 顺延一次。原生门禁核验
+原计划、全部旧候选证据及不变的配置、渠道和测试范围，保留原始起点、版本变更记录与
+失败 TRX/TAP；新版本重新冻结并执行完整门禁。不得与重冻、凭据或控制恢复叠加，
+也不能用于已有成功发布结果的会话；普通续发仍保留原版本。
+
+收到“发布吾码”“完整正式发布”“一键发布”时，默认执行根目录 `Microi一键编译发布.sh --platform-release`（默认完整选项）：新版本号按原规则 +1 一次，NuGet、API Docker、PC Docker、官方网站文档及其 Docker 全部发布。官网不再是可选追加项；只有用户明确要求“仅前端/仅后端/仅官网”等局部发布时才缩小范围。完整入口使用 `PlatformRelease` 执行常规 Microi.Tests（平台单元/组件，不自动追加 Full 专项）、吾码前端通用 Node 测试、真实接口检查与最终加密产物启动/运行冒烟；扩展浏览器验收仅在显式传入 `--platform-frontend-tests` 时追加。真实付费 AI、鸿地/JUNCHI、XJY 等指定客户数据专项和 SQL Server 等独立提供商专项默认不纳入，不再逐次询问；只有用户另行明确要求专项时才执行，回执逐项列为“不适用/未执行”，不能冒充通过。独立商城应用、OpenClaw 等应用源码专项由各自入口执行，不作为平台发布前置；平台 SDK、商城协议、安装器、SaaS 与工作流通用回归继续保留。Microi Code/Agent 是独立产品，不混入吾码平台测试与发行。
+
+1. 默认确认 NuGet、API/PC 和官网完整渠道及版本；记录开始时间，每次新完整发布从当前版本 +1 一次。中断后使用脚本输出的 `--resume=<会话JSON>` 恢复同一完整发布，沿用原版本、渠道、候选和累计起点；`--release-version=x.y.z` 只用于显式选择版本，本身不代表复用测试或产物。不能仅凭版本文件未提交推断为续发。
+2. 取得对应产品锁并冻结源码、依赖与官网构建输入；执行本次基础范围全部 C#/Node 测试，核对接口及启动/运行回执；扩展浏览器测试仅显式追加 --platform-frontend-tests 时执行。禁止把缺少授权/夹具、零用例、失败、取消或跳过写成成功；不能因测试需要依赖就自动新建租户、安装应用或创建 Docker。保留既有测试数据写入保护。
+3. 以 `.microi-local` 选定配置复用 MySQL、Redis、MongoDB 和 SaaS 生效的 MinIO/OSS；生成平台正式产物，执行完整 DLL 加密和一致性校验，在本机进程运行最终产物冒烟。PC 执行自身正式构建与产物检查，官网执行原完整构建与页面验收，不使用临时运行容器替代本机程序。
+4. 完成 NuGet 与全部选中 API/PC/官网 Docker 推送，逐标签回读远端不可变 digest；新推送和断点复用都必须验证，并回读官网关键页面。任一渠道缺凭据、未执行、失败或未知，不能报告全部发布成功。
+5. 输出各渠道、候选标识、常规测试数量与结果及独立专项未执行清单、各阶段和总耗时、镜像 digest 及官网回读；回收本次进程/临时文件并释放锁。客户部署独立，不以镜像推送代替。
+
+交互选项确认完毕后，本轮共用一个 **1800 秒耗时目标，而非强制截止时间**，覆盖锁/资源准备、测试、编译、加密、冒烟、Docker 检查、推送与回读。超过目标时告警并记录当前阶段、实际耗时和瓶颈，继续推进至发布成功；不能仅因达到 30 分钟杀进程、停止后续步骤或将成功退出改为失败。真实命令失败、用户取消、单操作超时及安全门禁仍保持原有失败语义，定位修复后按候选与回执安全续发。阶段切换或重试不能隐瞒累计耗时，重启续发须保留前次及累计耗时；不能通过跳过测试、吞掉错误或重复盲跑来追求时长。
+
+用户要求同时完成源码交付时，先记录各仓原分支与上游，安全拉取合并并解决冲突，再冻结候选；按归属提交、推送原分支并独立回读。源码同步清单可以包含独立工具仓，但不因此触发其测试、打包或发布。分别记录 Git 准备、脚本执行和任务总耗时，整体仍争取 30 分钟；官网已属于完整发布默认渠道，开发工具和独立应用不因“有变更”自动追加。远端推送问题可以与合格制品发布并行解决，未补齐时如实标为未完成。
+
+普通发布的“完整”指全部发行渠道，不自动扩展测试深度。默认只运行基础平台 C#、平台/前端 Node 与最终产物冒烟。发布前一次完成版本、凭据、资源与官网基础预检；完成代码合并后冻结候选，避免边发布边追加其它任务。后续阶段失败时先保存候选、原始测试和已发布渠道回执，重新核验相同源码、配置、工具与实际产物后复用有效结果，只续做未完成范围；结果不匹配或缺少必要证据时按原门禁复验，不能把通过截图当作缓存。npm、NuGet 等渠道的正式发布命令明确成功，即记录对应渠道发布完成；用户已明确确认其本机终端发布成功时，同样直接按成功继续，不再要求提供最终输出或回执。默认不查版本索引、包页面或下载地址，不等待公共索引/CDN 传播，不因即时 404 重传、升版、降为未完成或再次追问。公共可见状态仅在用户另外要求时核验。
+
+**原生断点续发**：完整入口在发布结果目录保存 `session-*.json`，失败提示给出准确恢复命令。始终重新运行同一个正式入口并使用 `--resume=<会话JSON>`，禁止临时截取、拼接或改写脚本尾部。原始 TRX/TAP 重新核验后复用；前端构建文件、最终后端/加密/冒烟产物及 NuGet 包字节不变时复用。每个已接受的 NuGet 包单独记录，每个 Docker 标签须有独立摘要回执；续发只上传缺项，已完成 Docker 标签仍只读核对摘要，不覆盖其它任务后续发布。镜像身份读取 `docker image inspect` 的实际 `.Id`，不能拿构建日志的 config digest 代替。官网恢复只执行官网未完成部分，不重新选择 API/PC 渠道。
+
+**静态镜像校验复用**：一键入口的 `release-image-verification.mjs` 将同一次 `docker image save` 交给原有配置和五个 DLL 严格解析器，不创建容器；成功回执绑定同一发布会话、冻结候选、不可变 ImageID/configId、模板 SHA-256、加密回执原始 SHA-256 和校验器源码 SHA-256。绑定一致且证据完整才复用，命中仍读取真实 DLL 与加密签名，不能无意义重写 `encryptedAt`。身份、输入或证据变化时重新校验，失败不写成功缓存；每个远端标签仍独立回读摘要，缓存不能替代发布确认。
+
+**成功资源与共同基线回交**：准备前核对当前工作区实际脚本版本和门禁工具，不能因修复已推远端就认定旧工作区已更新。上轮及本轮成功发布、经官网真实回读的资源与 `.resource-sync-base` 必须随源码提交并回交原分支，不能只推版本文件导致下次重复合并。共同基线滞后时先核对上轮成功回执和当前远端差异，仅通过原生 `--repair-base-from-remote` 入口读取真实远端修复；不得伪造基线或强选本地吞掉远端变更。
+
+**耗时优化验收边界**：阶段回执续发、上述静态镜像复用和一次收集已选 Node 各组失败已有实现；Node 各组仍按原顺序各执行一次，任一组失败、缺用例、异常退出或取消均整体失败，不生成成功摘要。失败后的测试组级复用、测试并行和渠道并行尚未实施，不能作为已获得的提速承诺。30 分钟仍是待完整端到端实测的目标，须计入整合准备、失败修复、等待与最终验收；定向夹具通过不等于真实发布已达标，超时继续完成并如实报告。
+
+候选冻结前一次合并本批功能、修复和依赖输入；冻结后不继续接收下一批业务能力。新增需求或与本轮无关的改动排到下一候选。确需修改当前发布源码时，原测试不能继续冒充新候选结果；保留前次耗时和失败，再按实际变更复验。对没有改变的候选、制品与渠道，不重新准备、重测或重发。
+
+官网打包 Skills 一致性等构建输入在整套回归前检查；这是分发输入校验，不是执行 Agent 产品测试。官方资源 HTTP 524 按原同步器先回读完整状态，再用相同候选和 CAS 只补差异，最多定向恢复一次；其它真实错误直接保留失败。重试沿用原计时文件，退出后的修复/等待也计入累计总耗时。候选、配置、渠道、原始证据或制品变化时拒绝复用，先说明具体失效项；不能清空会话来掩盖失败，也不能给一个变化的候选换签成功回执。
+
+**普通发布禁止混入**：新建/准入主子租户、安装消息通知或聊天应用、Microi Code/Agent 的 Vitest/E2E/桌面打包、全提供商兼容专项。隔离测试数据与新建租户不是同一件事，不得借“准备权限夹具”触发安装。平台已有的通用消息/权限离线回归仍保留，不能为缩短耗时删掉已选断言。
+
+`--full-only` 仅供用户明确要求的独立深度测试；它不推送镜像，也不作为普通发布的隐含前置。`--microi-agent` / `--microi-code` 仅供独立产品显式发布。发布流程自身的修改只执行对应定向回归；没有新的发版要求时，不为验证规范再发一轮镜像。
+
+普通吾码 PC/API 发布使用 PlatformRelease，包含平台自动化、编译、闭源 DLL 加密、最终产物冒烟、Docker 推送和远端摘要回读；完整发布以 30 分钟为可度量预算，记录各阶段耗时，超时如实记未达标，不承诺未知网络下必然成功。普通发布不运行 Microi Code/Agent 测试，不新建租户、不安装聊天应用。Full 保留为显式独立深度测试；本次修复需要真实依赖时复用指定 MCP 的已授权环境，SQL Server 等兼容专项只在明确指定时执行。已选必测项仍须全部通过。
+
+搜索标签真实浏览器门禁默认使用 1366px 和 1920px 常规桌面；测试进程显式设置 `MICROI_TEST_BROWSER_4K=1` 时追加 3840px 专项。所选宽度随显式 Full 或浏览器专项矩阵冻结，回读必须包含全部所选用例且零失败、零跳过；该变量不进入生产 API 配置。正式发布与同版本 Docker 热修复均拒绝历史 `--skip-tests` / `SmokeOnly` 入口，候选始终包含完整测试输入。
+
+本地发布测试默认复用 `.microi-local` 选定配置对应的已有服务，HDFS 使用该租户 SaaS 的实际 MinIO/OSS。固定夹具库名、端口或归属冲突先修正配置传递和可配置隔离，采用本任务唯一记录/Key/对象前缀并核验所有者；不能因此新建本地依赖容器、切换到其它 MCP 租户、删除他人夹具或放宽断言。清理与专项例外统一见 [本地测试程序与依赖生命周期](../workspace-conventions/references/progressive-02-microi-net-api-本地启动约定.md#本地测试程序与依赖生命周期强制)。
+
+选择、旧脚本冲突处理及结果记录统一读取 [发布测试矩阵](../microi-system-delivery/references/progressive-02-自动化测试必须覆盖的坑.md#按指定-mcp-选择发布测试矩阵) 和 `../workspace-conventions/SKILL.md`；实际目标未使用的提供商不能被虚构为已验证。
+
+完整入口自动读取当前工作区已忽略且仅当前用户/系统可访问的 `.microi-e2e/platform-release/profile.json`，也可由发行进程变量 `MICROI_PLATFORM_RELEASE_PROFILE` 指向既有授权配置。配置记录项目 `.microi-local` 对应依赖、明确的测试写入范围、归属及独立端口；必须保留所有者与目标校验，不存旧 Token，不依赖历史 `.tmp`。缺配置或授权不匹配时明确失败，不能自动创建租户、数据库、容器或安装应用。
+
+该入口在同一轮计时中启动受管原生依赖转发，待本轮构建完成后启动对应 API/Vite，并向测试子进程传递私有环境；测试完成先停止自有 API/Vite，转发保留到最终加密产物冒烟完成，脚本成功、失败或取消退出均精确收尾。显式已有 `MICROI_PLATFORM_RUNTIME_CONTROL` 时复用其监督进程，不重复启动；局部前端/仅官网入口不强制加载完整发布配置。只读检查可执行 `node Microi.Server/tools/platform-release-runtime.mjs dry-preflight <工作区绝对路径> [profile绝对路径]`，它不启动服务、不创建测试资源。
+
+## 先确认部署类型
+
+官方标准空库的新安装包含完整平台应用快照，安装记录与所保留资源的已校验版本一致，
+并保留系统首页及两个基础角色。历史库的启动恢复仍只修复登录、权限、导航和商城的
+最小基础；不能把启动投影当作完整空库，也不能在客户库执行空库清理。`ApplicationType=Platform`
+的“全部安装／更新”是显式维护动作，不得用作默认开机或普通功能联调的准备步骤。
+记录启动就绪、首次登录、商城打开、单个可选包安装和全部包维护各自耗时；全量维护通过
+不能代替最小空库验收。缩小启动范围不卸载既有租户的应用，也不删现有配置。
+
+### 吾码服务器运维面板 Microi.Panel
+
+- 项目由 `Microi.Ops` 更名为 `Microi.Panel`；独立 .NET + Vue + Microi.UI 宿主使用自己的管理员账号、SQLite 和 Docker 权限，业务 API/Web 停止时仍可操作。只安装面板时使用 `install-microi-panel.sh`，不要求先安装吾码业务平台、宝塔或 1Panel。具体命令与能力边界见中文官网 `server-panel/overview.md`。
+- 先确认主机内存、Docker Engine 身份、活动任务、已有 Ops/Panel 控制器、端口、编排和数据目录。每台 Docker 主机只运行一个吾码控制器。与宝塔/1Panel 共存时使用独立安装目录、容器名、卷、网络和端口；80/443 等监听端口不能被两个入口同时占用，不得重置 Docker 或自动接管第三方面板资源。
+- 安装器选端口同时回读 Docker PortBindings 与主机监听状态，包含未运行容器已声明的 TCP 绑定和本次规划的自定义 Ops 端口；探测失败不能当作空闲。WebSocket `/diy-websocket` 共用 API 端口，TCP/MQTT 使用各自显式映射。Ops 运行时禁止命令行竞争更新是控制器互斥，不能通过抢占或挪走 WebSocket 端口绕过。
+- 宝塔原厂进程检查可能识别 Docker 内的 Nginx，后装时即使端口独立也会提示已有 Web 环境。按已授权范围处理原厂确认：隔离机验收保存确认记录与安装前基线，客户机不自动确认未授权的覆盖或迁移。非交互执行要显式处理已识别的提示并设置超时，不能把挂起、安装器退出或仅出现目录当作安装成功；完成后回读原 Docker 身份、面板凭据/证书哈希及真实网站内容。
+- 1Panel 版本检查使用原厂支持的 `1pctl version` 或 `1panel-core version`，再核对 core/agent 的真实 systemd ExecStart 和官方包 ELF 哈希。不要猜测执行 `1panel-agent version`：已验收的 v2.4.1 会启动另一个 agent 并争用 Unix socket。宝塔新版本不一定保留旧 `data/version.pl`，应使用当前安装版本支持的读取方法，并独立验证真实服务、浏览器页面和网站。
+- 插件市场只安装目录内明确版本与 SHA-256 的镜像；检查架构、许可、健康检查、持久卷和真实业务读写。Oracle 等原厂许可渠道不擅自镜像；MinIO 社区归档后的源码构建必须保留对应源码、许可与摘要。跨数据库大版本升级仍需专用迁移方案。
+- 吾码新建网站和反向代理由受管 Docker Nginx 执行；配置先 `nginx -t`，再原子发布与回读。`2.0.2` 稳定版提供已有宝塔 Nginx / 1Panel OpenResty 网站直接管理：默认只读发现，用户明确接入实例后才允许修改其已识别站点。宿主适配器通过固定 root Unix socket 核对真实实例、站点配置和容器挂载，不复制第三方面板资源为假受管实例，不暴露任意文件或 Shell 入口。
+- 外部站点修改必须绑定实例指纹、站点标识、配置 SHA-256 和稳定请求号；CAS 不匹配停止覆盖。发布前备份原配置，校验、切换与重载失败保留恢复现场；历史回滚同样检查当前版本。原面板仍可管理自身资源，跨面板并发修改需重新回读，不能自动选择吾码版本覆盖。
+- 宝塔原生进程身份核验读取固定 PID 的 `/proc/PID/exe`，宿主 systemd 的能力集合需包含 `CAP_SYS_PTRACE`；同时用 `SystemCallFilter=~ptrace process_vm_readv process_vm_writev` 禁止实际调试和跨进程内存系统调用，保留 `NoNewPrivileges`、`ProtectSystem=strict` 和固定可写目录。必须在等效 systemd 限制下验证真实 Nginx 发现与禁止调用，不能用普通 root 成功或吞掉权限异常冒充接入通过，不新增任意 PID/Shell 接口。
+- HTTP-01 需真实 DNS 和公网 80 挑战路由，不能用跳过验证冒充签发成功。外部站点在已核验根目录及现有挂载内创建独立挑战子目录，helper 仅挂该目录；不得挂整个第三方站点根目录、重建原容器或异步镜像 token 冒充可靠挑战。已有验证 location/include 或重写冲突按实际适配结果处理，不盲目覆盖其它 CA 工具。通配符继续使用外部 DNS 验证后导入证书。
+- 自动续期默认启用，保留 lego v5 `run` 的 ARI 和动态有效期判断，不使用强制续签；正常检查不超过 12 小时，短周期证书缩短间隔。SQLite 持久化下一次检查、失败退避、操作编号和执行轮次；预检失败、重启与重复投递按同一轮次幂等补偿，已签发待发布时继续原检查点。暂停阻止后续排程及尚未开始的旧自动任务，不承诺终止已经发出的 CA 请求。
+- 区分普通 HTTP、TCP TLS 与 QUIC / HTTP/3 监听，不能因 `listen 443 quic` 没有 `ssl` 关键字就对其执行明文 HTTP-01 探测。持久旧计划按冻结配置正文重算传输类型，保留原请求、CAS、路由和隔离目录。初次网络失败留下本地 ACME 账号时，托管与外部站点共用恢复逻辑：只有 CA 明确 `accountDoesNotExist` 且本地没有注册回执才归档，保留原私钥，以无网络、独占状态卷的固定帮助容器完成可恢复步骤；不能清空状态卷或换任务掩盖失败。
+- 证书须验证私钥、有效期和 SAN，发布在 `nginx -t`、重载及真实 SNI 叶证书 SHA-256 回读成功后才提交；失败保留旧证书，回退也验证旧 TLS。外部网站重载后发布与恢复分别共享 10 秒回读预算，每轮全部域名/端口须同时通过精确叶证书与 HTTPS 响应检查；TCP、TLS、HTTP 和 Docker 读取都计入预算，身份/CAS 与非法重定向立即失败，不累计各轮局部成功。通用动态主页不强制正文恒等，真实验收的静态测试正文则须精确匹配。未换证书仅检查实际服务，不记作新签发。验收覆盖原任务重试、服务重启、暂停、配置冲突、新旧指纹及恢复失败；HTTP 200、文件写入和配置测试不能单独作为换证成功。
+- 网站文件仅管理受管卷；文本编辑使用内容哈希拒绝覆盖并发修改。冷备份须明确服务中断，检查正常退出与归档哈希；恢复写入新卷并保留原卷，重试继续原操作 Id。卸载保留业务卷，重新安装沿用记录的原镜像、凭据和数据卷。
+- 新面板默认独立 HTTPS 端口 61890，管理员密码与 PFX 密码存于服务器权限受限文件；不要把它们复制进业务 SaaS、V8、MCP 参数或日志。旧 Ops 保留原 `OPS_*`、目录、账号、端口、数据保护密钥及 `MicroiOpsUrl`，用原 Compose 替换为 Panel 镜像，不能重新初始化。
+- 业务 MCP 继续通过 `microi_get_administrative_capabilities`、`microi_admin_table_data`、`microi_update_module` 和应用发布工具维护平台入口；DiyToken 不授予主机 Docker 权限，不增加能从租户会话执行任意宿主机命令的工具。主机安装与恢复使用授权的 SSH/终端和独立面板会话。
+- 真实验收归入 `Microi.Tests/Panel` 专项，包含全部目录版本、数据库/对象存储写读与冷恢复、SSL/续期、文件、任务重启、独立安装升级回退，以及真实宝塔/1Panel 两种安装顺序。普通外部容器只能证明资源归属保护，不能替代第三方面板共存结论。
+- 上述外部网站管理与续期增强从 `2.0.1` 引入，现纳入含磁盘治理的 `2.0.2` 交付版本。源码安装器默认镜像准备为 `v2.0.2`；版本号不代表已经发布，必须核对同一冻结源码、实际镜像和最终门禁回执。完整门禁通过后先发布并回读镜像，再发布默认安装脚本，不可提前破坏仍使用历史镜像的公开入口。文档、单元测试或本地 CA 协议成功不代表新镜像正式发行、真实宝塔/1Panel VM 验收、公网 Let's Encrypt 签发或客户上线，必须分别保存并说明各层证据。
+- Let's Encrypt IPv4 免费证书的签发与续期均显式选择 `shortlived`，HTTP-01 仍要求公网 80；自定义面板管理端口不能代替验证入口。公网 CA 成功必须回读实际签发、在线证书和自动续期，本地测试 CA 只证明协议、部署和调度链路。共享工作区冻结验收时保留并发安装器改动，编译配置和测试依赖一并固定；原始失败记录不能改写成通过。
+- 集成夹具也必须挂载真实的磁盘维护 socket，让镜像拉取经过生产容量与回滚保护。原生 Linux 使用宿主服务；Docker Desktop 使用明确登记、核对所有权的独立服务与 socket 卷，控制器只读挂载。不能为了跑通旧用例关闭磁盘保护、伪造 Unix socket 成功或降低空间阈值。
+- 主机密码防爆破必须同时核对镜像 `io.microi.panel.authguard.protocol=1`、root 专用 Unix socket 和 `microi-auth-guard` 的真实回执。默认开启，同 IP 跨已接入服务累计 3 次封禁 86400 秒，窗口 0 表示累计至解封；成功登录不清零。配置与实际保护分别回读，来源日志/代理或防火墙异常不能标为已生效。稳定版无参数安装默认 `v2.0.2`，必须满足协议 1，不保留隐式旧版豁免。两种安装顺序、原厂网站管理及重启后自动续期已在 Ubuntu 24.04、宝塔 13.1.0、1Panel 2.4.1 上通过；证书测试 CA 与公网 CA 验收分别记录。显式选择历史镜像必须带 `--legacy-panel-only` 并说明不含新防护，已经安装协议 1 的面板禁止降为旧协议；不可在新镜像拉取失败后悄悄回退为无防护旧版。
+- 面板登录有独立 SQLite 防护与可撤销会话；SSH 读取真实宿主认证日志，新 MySQL/MongoDB 使用可验证认证日志，Redis 必须经逐次认证结果代理。禁止根据跨 IP 聚合的 Redis ACL LOG count 封禁最后一个 IP。新 Redis 使用独立网络、不直接发布后端端口；存量实例需维护窗口迁移，不能升级时静默断开连接或宣称已保护。
+- 主机防护使用最小 systemd 服务，面板只挂载其 root Unix socket，不给业务 V8/MCP 泛化 Shell/防火墙能力。nftables 使用内核超时；iptables 兼容模式的自动解封依赖运行中的守护进程。IPv4/IPv6、INPUT/转发、两个来源 IP、真实失败/成功、手动/自动解封、去重、重启、白名单与规则故障分别验收；Docker Desktop 的专有网络空间测试不能替代原生 Linux 安装/重启或客户生产验收。独立安全专项入口在 `Microi.Panel/Tests/Security` 和 `Microi.Panel/AuthGuard/tests`。
+- 宿主 Python 至少 3.9，检查 SSL、SQLite 和 `asyncio.to_thread`；旧系统用 `--guard-python /opt/microi-python/python/bin/python3` 选择独立运行时，解释器及真实祖先必须由 root 控制且不可组/全局写。不能替换系统 Python 或仅因宝塔自带解释器可运行就忽略版本要求；升级时保留并明确使用同一路径。`--check` 同样核验实际运行时，但不启动服务。
+- systemd 219–231 的安装兼容路径使用 `ReadOnlyDirectories=/` 加原固定目录的 `ReadWriteDirectories`，保留 `NoNewPrivileges`、能力集合、系统调用过滤及兼容内存限制；新版继续使用 `ProtectSystem=strict`。必须用当前 `systemd-analyze verify` 拒绝未知/忽略的关键指令，再做实际进程能力、挂载和网络验收。旧版使用 `systemctl show <unit> --all --no-pager` 读取完整属性，严格解析唯一 `Key=value`；未知单属性会返回错误，空属性在缺少 `--all` 时会被省略。缺少 InvocationID 时以稳定 PID/单调启动时间识别运行实例，读取错误或并发变化仍停止；不能改成无身份回读的覆盖。候选增强不等于所有旧发行版均已通过交付验收。
+- 旧版 `journalctl` 使用受限批次的 JSON 输出，不依赖 `--output-fields`；仍逐条检查可信 root UID、真实 sshd 可执行文件、时间戳与游标。旧 `iproute2` 不支持 `ip -j` 时，仅解析 `ip -o address show` 的固定地址字段；格式异常保留上次可信地址并明确告警，不能把广播地址或接口名加入白名单。
+- Docker 创建网络可能调整 FORWARD 顺序。iptables 只能重新定位带自有链归属证明的跳转：先插入带唯一注释的新首条，回读确认，再按旧规则的完整匹配条件移除旧跳转；禁止按规则序号删除、清空链或覆盖宝塔/Docker 规则。并发变化、封禁/解封内核回读或 TCP 实测失败时不能报告成功。
+- 生成 Compose 时 `cpus` 必须是 JSON/YAML 数值，不能用数字字符串假定旧 Compose 会转换。现场中断已生成账号、证书或编排时保留原文件，不重新初始化凭据；修复需保存原字节、限定修改字段并验证实际容器健康及就绪。
+
+### 宿主磁盘容量与历史镜像
+
+- 遇到频繁更新后满盘，先按 Docker 数据根、数据库/备份真实挂载盘分别核对空间与 inode；镜像、容器写层、标准输出、数据库数据/日志、备份、模型与构建缓存分别归因。`docker system df` 的可回收估算不能冒充实际腾出的磁盘空间。
+- `docker image prune -a -f` 只处理未被任何容器引用的镜像，重复执行不会变成卷或构建缓存清理；带标签回滚镜像也可能被清除。不要将其直接写入客户定时任务。数据卷未引用不等于可删除，默认不自动执行 volume/system prune。
+- 安装器部署、宿主独立执行、面板管理同一策略；业务 API 不新增 Docker socket 或另一份主机清理调度。源码安装候选默认开启安全回收，仅限已登记的吾码 API/Web 历史镜像，保护停止容器引用、当前版本、至少两个不同历史版本及最近验证通过的回滚版本、预拉取目标、活动更新及恢复计划，默认连续未使用 7 天。删除前核对精确镜像 ID、引用、策略版本及共享维护锁，状态变化跳过，不强制删。
+- 容量不足先暂停新增拉取/更新并告警，不关闭数据库；拉取预检预算包含展开峰值、回滚、备份与安全余量，监测还须覆盖 inode。日志通过原编排轮转，不能直接删除 Docker 内部日志或数据库文件。默认不自动清理卷、停止容器、备份与其它项目资源；构建机缓存另行配置。
+- 实现事实源为 `Microi.Server/Microi.Panel/HostMaintenance`；`tools/sync-disk-guard-installer.mjs --check` 检查平台/独立面板安装器嵌入字节与原件一致。平台旧安装独立补装入口是 `install-microi.sh --disk-guard-install`，不进入数据库初始化。root 服务为 `microi-disk-guard.service`，账本在 `/var/lib/microi-disk-guard`；固定 root Unix socket 只向独立面板开放类型化维护动作，业务 API 不读取它。
+- 新装默认开启、15 分钟监测、UTC+08:00 每天 03:00 清理、空间/inode 85% 预警与 90% 暂停下载、另留 5 GiB、闲置满 7 天。原策略与停止状态升级时保留。预检先尝试原规则内最多 8 个候选，再独立回读容量；仍不足保持原容器并阻止本次新增下载。外部 Watchtower/手工 Docker 不受本入口仲裁，不宣称能拦截所有宿主写入。
+- `data` 登记只监测实际可写绑定盘，不授予数据库镜像或卷删除权；API/Web 登记核对部署清单仓库和实际容器身份。首次历史候选只标为未验证，不冒充业务回滚验收。预拉取每服务只固定最新目标，失败/恢复中的操作保护不超时删除；处理原任务后使用固定 complete 入口释放。
+- systemd 的只读沙箱不能作为宿主只读盘证据：容量读取 statvfs，真实挂载标志从 PID 1 的 mountinfo 核对，不关闭隔离或进入宿主命名空间。控制 socket、FIFO 和设备节点不作为数据盘检查；普通绑定文件和目录继续监测，避免小型 /run tmpfs 触发数据盘 5 GiB 余量误报。真实 Linux 验收同时覆盖服务重启、面板停止后的自动任务、跨进程 flock、数据卷校验和非强制删除回读。
+- 仅当实际安装并回读服务、策略、候选和删除回执后才称客户已启用。源码、Linux/浏览器专项、客户现场、候选分发、正式商业门禁分别记录；参数及排查命令原位维护在官网 `getting-started/docker-run.md` 的“磁盘容量与安全回收”。
+
+### 依赖镜像统一镜像源
+
+- 安装器、Dockerfile、发布与测试夹具的依赖镜像统一使用 `Microi一键编译发布配置.json` 中 Region/Namespace 对应的阿里云仓库。源镜像清单维护在 `Microi.Server/tools/dependency-images.json`，禁止客户每次安装直接拉 Docker Hub/MCR。
+- 联网发行机执行 `Microi一键编译发布.sh --mirror-dependencies`，由 `dependency-images.mjs` 读取同一配置的账号密码并用 stdin 登录；禁止将凭据写进命令、日志、镜像或仓库。完成后用 `verify` 回读摘要和多架构清单。
+- 上游固定 SHA-256；国内加速只能作为传输通道，不能修改版本、替换不明镜像或丢失 CPU 架构。上游和阿里云目标摘要不一致立即停止。Oracle/达梦/金仓等受许可限制的镜像只在具备再分发权后镜像，不用无授权镜像代替。
+
+用户明确要求同版本仅发布 Docker 热修复时，运行 `Microi一键编译发布.sh --docker-only-hotfix` 并选择后端镜像方案。该入口保持当前版本，禁止 NuGet、文档和官方资源数据库发布，同时保留 PlatformRelease、候选源码一致性、混淆后冒烟和镜像门禁。修复应进入本地源码及捆绑资源，由目标程序启动升级；不得通过直接改生产表结构代替源码修复。
+
+共享源码持续变化时，可在独立目录保存完整候选源码和依赖，以该目录运行同一 PlatformRelease 与发布脚本。专用测试服务使用独立端口，通过发布脚本变量 `MICROI_RELEASE_BACKEND_PORT`、`MICROI_RELEASE_FRONTEND_PORT` 指定收尾端口（默认仍为 61501、61500）；进程管理器仍必须核验 PID、命令行和工作区归属，不得结束原工作区服务。变量仅供发布脚本使用，不进入生产 API 配置。
+
+私有原生规则的静态后端组合必须设置构建专用 `MICROI_RELEASE_COMPOSITION_FILE`，不能把根仓忽略的应用源码当作已经进入发布候选。工作区内契约 `schema:1` 固定 `properties/files/directories/artifacts`；四个文件属性 `CustomAfterMicrosoftCommonTargets`、`PrivateRulesProject`、`ApprovedRulesBootstrapSource`、`MicroiCoreProject` 必须与当前 MSBuild 环境属性一致并进入源清单。契约、规则目录、静态审批及项目文件的新增/修改/删除均绑定候选，链接和越界路径拒绝。API 最终 `publish/<规则DLL>.dll` 必须与 `artifacts` 中后台审批的实际 SHA256 一致；不重新签名另一份 DLL 来通过门禁。普通无组合发布与 PC 制品保持兼容，镜像发布须推送命令明确成功并回读目标不可变摘要；目标部署和运行验收仍独立执行。详细契约见官网 `getting-started/local-run.md`；这是发行进程参数，不是生产 AppSettings、V8 或 MCP 代码上传入口。
+
+Windows Git Bash 发布锁必须把当前 Shell 的 MSYS PID 经真实 `ps` 的 `WINPID` 映射成 Windows 原生 PID，再以原生 PID 和唯一令牌登记、释放；映射失败或持有者退出立即停止，不借用其它进程。中文旧热修复入口通过 PowerShell UTF-8 命令行与精确工作区路径核验，不能只看标签或因大小写规范化误拒绝已核验入口。API、PC、官网和 Agent 仍各自互斥，实际 Bash 与原生宿主回归必须通过后重新执行所选发布门禁。
+
+PowerShell 5/7 进程管理入口同时固定 UTF-8 控制台与管道输出；脚本有 UTF-8 BOM
+不代表错误流编码正确。用真实子进程强制继承旧代码页，核对非零拒绝状态、完整中文
+诊断和无非法 UTF-8；保留原锁与进程归属断言，再重新执行所选发布门禁。
+
+macOS 前端构建使用有界 `vm_stat` 探针，根据真实页大小读取空闲页与可回收文件页；匿名非活动页、压缩页和已包含的预读页不叠加。探针失败时回退原生空闲内存，Windows/Linux 保持既有方式。吾码PC默认现代构建保留6144MiB堆，以5632MiB（5.5GiB）进程树预算加max(1GiB,物理内存3%)余量准入，32GiB主机约6.5GiB、64GiB约7.42GiB；全机占用97%暂停本轮树，95%以内连续五秒恢复。低于8GiB宿主保留至少1.5GiB余量，宿主限堆/自定义堆或未知阶段按堆加有界原生开销回退；串行压缩/legacy保留1536/2048MiB堆及768MiB原生下限，32GiB启动目标约3.25/3.75GiB。顺序阶段不叠加峰值，正式发布不跳保护，不结束共享服务；修复后执行所选发布门禁。
+
+DLL 加密脚本只在 Git Bash、MSYS 或 Cygwin 中转换 Windows 路径，优先使用 `cygpath`；macOS/Linux 必须保留原生绝对路径，不能把 `/Users` 或 `/usr` 误认为盘符。修复时先对隔离的构建副本执行原加密器，核对五个目标 DLL 的实际哈希变化及加密指纹，再由一键脚本重新执行 PlatformRelease、加密和最终产物冒烟；不得以专项测试替代发布门禁。
+
+加密脚本被 `source` 引入时只提供函数，不执行发行入口。SQLite 回归使用真实解释器及隔离标准库，Windows 选择 `python`，其它宿主使用 `python3`；不能用假解释器或跳过 SQL 断言。字节契约下的包投影、内联源码以及官方资源目录的全部 JavaScript 接口、表事件和 Hook 模板均按 Git 的 LF 规则检出，不能忽略原始字节差异来通过测试。缺少发行运行产物时，可按同版本包正文的大小与 SHA-256 恢复；明确标记为制品恢复，不能报告为新的源码构建。
+
+只要检测到闭源项目源码，就必须具备完整的五项目加密链；源码不完整、加密脚本缺失都要硬失败，不能降级为 `HAS_ENCRYPT=false` 的开源模式。一键脚本由 `release-encryption.mjs` 保存五个实际 DLL 的加密前后 SHA-256，并要求每个 DLL 字节改变且匹配原加密器指纹。上传 NuGet 前检查真实 ZIP 中所有闭源 DLL；上传后端 Docker 前通过 `docker image save` 静态读取镜像层中的五个 DLL，不创建或启动容器，与加密回执逐字节哈希核对。缺回执、明文重编译覆盖、包或镜像中的旧 DLL 均阻止上传；NuGet 等渠道发布命令明确成功可报告该渠道发布完成，不等待传播；Docker 还须回读目标不可变摘要；本地检查不能替代实际发布命令，目标部署和业务验收仍独立执行。
+
+在线 AI 的 MCP 运行目录必须由已锁定依赖干净安装、编译和裁剪后完整复制。生产命令的符号链接应解析为真实文件并保留执行权限，不能依赖即将清理的临时目录；损坏、越界或循环链接在替换旧运行目录前失败，重新打包清除旧依赖残留。保留制品门禁对符号链接的拒绝规则，专项验证使用同一复制逻辑并核对清理临时目录后命令仍可运行；修复打包逻辑后重新执行所选发布门禁。
+
+
+私有原生规则的静态后端组合必须设置构建专用 `MICROI_RELEASE_COMPOSITION_FILE`，不能把根仓忽略的应用源码当作已经进入发布候选。工作区内契约 `schema:1` 固定 `properties/files/directories/artifacts`；四个文件属性 `CustomAfterMicrosoftCommonTargets`、`PrivateRulesProject`、`ApprovedRulesBootstrapSource`、`MicroiCoreProject` 必须与当前 MSBuild 环境属性一致并进入源清单。契约、规则目录、静态审批及项目文件的新增/修改/删除均绑定候选，链接和越界路径拒绝。API 最终 `publish/<规则DLL>.dll` 必须与 `artifacts` 中后台审批的实际 SHA256 一致；不重新签名另一份 DLL 来通过门禁。普通无组合发布与 PC 制品保持兼容，镜像发布须推送命令明确成功并回读目标不可变摘要；目标部署和运行验收仍独立执行。详细契约见官网 `getting-started/local-run.md`；这是发行进程参数，不是生产 AppSettings、V8 或 MCP 代码上传入口。
+
+组合环境只属于发行工具所在工作区；临时测试仓库和其它源码根显式传递自己的环境。不得把主发行环境传入隔离夹具，也不得吞掉显式错误组合；实际 CLI 继续严格验证全部四项属性。
+
+原生依赖审批在目标 Linux CLR 中验证完整程序集引用链及实际字节哈希。驱动扩展也属于交付依赖：Oracle Core 23.26.300 同时交付同版本 Azure、Kerberos、OCI、ConfigFile、AWS、GCP 六个官方扩展及传递依赖，以 `ProviderDependencyDeliveryTests` 验证真实装载，不连接云服务。缺文件、身份冲突和哈希变化继续失败关闭；先复现并修复包装，再重新执行所选发布门禁 和镜像发布，禁止跳过未执行的依赖或开放 V8/MCP 任意装载。
+
+包清单不能代替真实程序集引用：Oracle AWS 扩展还引用清单未声明的 AWSSDK.SQS，Dos.ORM 显式交付官方 4.0.100.15 包，并由 NuGet 统一 AWS Core。回归递归检查扩展引用链，仍保留 512 个程序集预算；诊断集中列出缺失项，正式验证继续拒绝缺失和身份冲突。
+
+System.Drawing.Common 的 .NET 10 支持库引用 System.Formats.Nrbf，Dos.Common 显式交付同版本官方包；该文件不能从 WindowsDesktop 共享框架复制来冒充 Linux 制品。通过真实引用装载回归和 Linux 依赖验证，保留 Windows GDI 平台限制，Linux 绘图使用既有 SkiaSharp。
+| 场景 | 推荐入口 |
+|---|---|
+| 生产 Linux、快速安装、可滚动升级 | Docker/Compose |
+| 无互联网环境 | 在联网机制作离线包，再在目标机校验并安装 |
+| Windows 传统环境 | IIS + .NET Hosting Bundle + 独立依赖 |
+| 开发/调试 | 复用健康服务，或启动后端源码/隔离目录中的编译产物 + 前端 Vite；优先共用已授权开发/测试依赖 |
+
+本地测试遵循 `../workspace-conventions/SKILL.md` 的依赖生命周期：默认复用 `.microi-local` 选定项目配置对应的 MySQL、Redis、MongoDB 和 SaaS 生效的 MinIO/OSS，启动本机源码或最终产物进程。不能按 AI 任务、完整测试或双节点测试创建 Docker/Compose，也不运行临时 API/官网测试容器。无法复用时先记录具体缺口并修复，普通发布不授予新建容器例外。结束后精确回收自有进程及纯测试资源，回读清理结果，既有共享服务保持原状态。
+
+本地 `Microi.Client` 默认读取 `src/config.json` 的 `ApiBaseDev`，也允许在 `#` 前通过 URL 参数
+临时指定运行目标：
+
+```text
+http://localhost:61500/?OsClient=iTdos&ApiBase=https%3A%2F%2Fapi.microi.net
+```
+
+URL 的 `ApiBase`、`OsClient` 优先级最高，但不会隔离同源 localStorage/Pinia/Token。多个 AI
+对话或自动化并行测试不同目标时，每个 `ApiBase + OsClient` 必须使用独立浏览器上下文/Profile；
+Playwright 使用 `browser.newContext()`。人工第二组至少使用无痕窗口，多个 Chrome 无痕窗口不能
+视为多组强隔离。完整取值顺序、线上识别和验收见 `../microi-client-frontend/SKILL.md` 与
+`../playwright-e2e/SKILL.md`。
+
+不得在未确认目标主机、目录、数据卷和备份的情况下执行官网“删除所有容器/编排”
+或任何递归删除命令。
+
+## 变更前只读盘点
+
+至少记录：
+
+- 操作系统、CPU、物理内存、可用磁盘、时区与端口占用；
+- 当前 API/Web/Worker 节点数、镜像/版本、反向代理与证书；
+- MySQL、Redis、MongoDB、MinIO/HDFS 地址和持久卷；
+- 当前 `OsClient`、数据库备份、对象存储备份和配置备份；
+- JWT/AuthSecret 等集群共享密钥的指纹一致性，绝不输出明文；
+- `/api/Diagnostics/health`、`/api/Diagnostics/liveness` 与兼容地址 `/apiengine/platform-service-health` 仅证明 API 宿主存活，均不检查 MongoDB、Redis、MySQL 或外部设备接口；依赖可用性另查服务探针与真实业务路径。健康 GET 在动态路由和业务压力控制前响应，禁止把相似路径或 POST 当作免限流入口；
+- 当前运行中的 Node、dotnet、Docker build 等重任务。
+
+## 后端配置单一事实源（强制）
+
+Microi API 安装时，`AppSettings` 与同名容器环境变量只允许以下十个启动引导项：
+
+`OsClient`、`OsClientType`、`OsClientNetwork`、`OsClientDbType`、`OsClientDbConn`、`OsClientRedisHost`、`OsClientRedisPort`、`OsClientRedisPwd`、`OsClientRedisDataBase`、`OsClientDbMongoConn`。
+
+- 除这十项外，业务开关、超时、重试次数、资源上限、代理信任、密钥路径和第三方密钥通常必须在 SaaS 引擎 `sys_osclients` 的合适 Tab 中动态配置，并提供代码安全默认值；影响整个 API 进程的字段只读取主租户记录。唯一固定例外是官方 License 信任链：恢复重试次数/间隔使用代码常量，签发私钥只读取固定只读挂载 `/app/microi_private.pem`，不得为这三项创建 SaaS 字段。
+- 不得新增 `MICROI_*`、`DOS_ORM_*`、自定义 `AppSettings` 节点或通用 `Environment.GetEnvironmentVariable(name)` 作为 API 运行配置；新增配置必须同步升级字段、表单 Tab、脱敏/子租户隔离、缓存刷新、文档和源码扫描测试。
+- `ASPNETCORE_*`、`DOTNET_*` 属于 .NET 宿主配置；构建、安装器、测试、MCP 和发布脚本自己的进程变量也不属于 API 业务配置，但生产 API 代码不得读取它们来控制业务行为。
+- `AuthSecret` 等已有 SaaS 敏感字段继续由受保护的主租户记录提供。普通业务私钥路径仍按相应 SaaS 配置管理；官方 License 签发私钥路径固定为 `/app/microi_private.pem`，只允许生产签发节点只读挂载。密钥明文不得写入镜像、Compose、日志或普通 V8 投影。
+- 验收必须扫描生产源码、`appsettings.json`、在线/离线安装编排，断言 API 容器仅出现上述十项；不能只检查某一个示例文件。
+
+## 一键安装脚本版本时间（强制）
+
+- 每次修改 `数据库、案例、文档、资料/install-microi.sh`，必须同时更新文件头版本和 `SCRIPT_VERSION`，两处完全一致。
+- 新装 MySQL 推荐 `max_connections=500`、最高 800，内存预算优先：从数据库自身的容器硬帽计算，buffer pool 约 40%、查询余量约 25%，再扣日志/key/固定开销后按 8MiB/连接估算，低内存明确降低并提示。连接数不等于重 SQL 并发；临时表等按负载实测，不能宣称绝对无 OOM。已有数据库不自动改全局配置。
+- 新建 managed MySQL 的 `OsClientDbConn` 同时限池：服务端连接数先保留max(4,ceil(max_connections/5))给管理/备份等，剩余按单API业务/Quartz两个独立池均分，每池至多100、最小池0，不再固定写500。主租户相同规范化参数的读写共池；Quartz默认寿命120秒与ORM300秒不同，分别计入。多节点、独立读库和其它不同参数池要重新合计；不改外部MySQL或repair已有连接串，不新增API环境配置。
+- 未显式配置的 MySQL 业务池默认最大 100、最小 0，显式连接串优先；多个节点/租户、独立读写池、Quartz 与其它客户端须合计并保留管理员/备份/滚动发布余量。200 是否不足要看拒绝增量与总预算，大量 Sleep 不能证明泄漏，不默认杀连接、重启数据库或自动无限放大。
+- 固定格式为 `vYYYY-MM-DD HH:mm:ss`，使用 `Asia/Shanghai` 时间并精确到秒；禁止只写日期或沿用上一次修改时间。
+- 验收同时断言两处版本一致、格式正确，并以脚本实际启动输出为准；官网静态地址尚未发布新文件时，不能把本地版本误报为客户已经可下载。
+- 恢复旧数据库时，OCR、翻译等附加字段先出现不代表完整升级链已经成功。安装器必须先回读 `sys_config.ServerVersion` 达到本脚本最低版本并通过 API liveness/readiness，才能部署和配置附加能力；核心中间迁移失败或超时应失败关闭，禁止用部分字段就绪冒充整个平台升级成功，也禁止在升级事务仍执行时主动重启 API。
+- Compose v2 生成文件不再写顶层 `version`；所有模板直接以 `services:` 开始，避免 `the attribute version is obsolete` 告警。
+- 完整资源规划先按实际 MemTotal 预留 max(12.5%, 低于8GiB为1GiB/其余2GiB)；全部新建常驻核心/模型进入同一父池且各有硬帽，核心帽总和不能超父池。Redis数据上限至多自身帽一半，Mongo显式WT cache；Panel独立在宿主余量内。新装发现已有容器先只读审计并退出，禁止因此自动停止模型、创建Swap、覆盖客户限额或重建容器；旧环境使用 `bash install-microi.sh --resource-audit` 只读盘点。详见 [部署矩阵](references/deployment-matrix.md)。
+- 模型预算最低 OCR 2048MiB、翻译1024MiB；只有完整预算容得下、物理≥7680MiB且可用≥max(2048MiB,已选模型预算)才启动，否则固定跳过并明确关闭对应租户能力。不要为使预算数学通过而压低正常热身所需硬帽；帽与sum回归不等于真实热峰验收。
+- LibreTranslate 属于一键安装默认选择，但服从容量门禁：安装选择空输入按 `1` 处理，语言套餐空输入按基础套餐 `1` 处理；因此用户一路按 Enter 使用官方推荐组合。只有明确输入 `0` 才跳过，提示、端口预算、官网文档和静态回归测试必须一致。
+- OCR 的 Upgrade29 与 LibreTranslate 的 Upgrade31 字段门禁只在对应附加服务部署检查通过后回读，每秒一次、最多 15 秒；首轮成功就继续，超时快速关闭对应能力并提示镜像/迁移版本，不得退回 5 分钟空等，也不得直接创建字段绕过平台升级。附加能力门禁失败不得中断已通过完整升级链和 readiness 的核心平台。
+- 官方 API/Web 使用浮动 `latest` 时，生成的 Compose 必须设置 `pull_policy: always` 或在启动前显式拉取并核对，不能因宿主机已有同名镜像就复用旧版本；测试专用本机镜像覆盖必须明确使用 `never`，避免误访问或覆盖远端镜像。
+- 端口、密码和数据目录全部生成后，安装器必须注册统一的失败收尾：数据库、缓存、存储、API/Web、完整升级链或 API liveness/readiness 等核心后段错误保留原始非零退出码，并输出标题为“安装未完成”的恢复汇总，列出已生成端口、受限凭据文件位置与脱敏状态、目录、失败阶段和全部容器状态。OCR/LibreTranslate 的网络、镜像、容器或 SaaS 配置失败只记录附加能力警告、保持对应能力未启用并继续核心安装。两种结果都不得把 `Running` 当 readiness，也不得绕过 Upgrade29/Upgrade31 或完整升级链门禁。
+- 从客户/旧库恢复安装时，安装器只按 `OsClient + OsClientType + OsClientNetwork + IsEnable + IsDeleted` 处理目标主租户：0 条时幂等创建最小可运行记录，1 条时原位复用，超过 1 条失败关闭。禁止把所有活动 `sys_osclients` 批量改成输入的 OsClient；新记录不得落库 `DbConn/DbReadConn/DbMongoConnection` 或 Redis 主机、端口、密码，这些继续由十项编排启动配置提供。MinIO、OCR 等安装值随后只更新这个精确三元组并回读唯一性。
+
+### 复盘：普通帐号运行安装器直到步骤 5 才因 `/microi/compose` 权限失败
+
+- 触发场景：普通帐号已经加入 Docker 组，前四步的探测和交互看似正常；脚本在开放防火墙后直接执行 `mkdir -p /microi/compose`，才报 `Permission denied`。命令替换中的数据目录创建错误还可能被旧 Bash 的 `set -e` 语义掩盖，使成功提示先于真实失败出现。
+- 根因：安装器把 `sudo` 零散放在软件包、防火墙和 systemd 命令前，却没有在真实安装或修复入口统一取得 root 身份；同时假设精简系统一定安装 `sudo`，普通用户与“root 但无 sudo”两种环境都没有明确的早期门禁。
+- 通用规则：会写 `/microi`、`/home`、防火墙、systemd/cgroup 或 Docker 宿主状态的一键安装/修复，必须在步骤 1 和任何交互、凭据生成、宿主机写入前完成一次 root 门禁。普通帐号有 `sudo` 时重新执行同一绝对脚本并保留参数；无 `sudo` 或验证失败时零副作用停止并给出 `su -` 恢复指引。已经是 root 时不得要求系统额外安装 `sudo`；目录创建仍要显式检查只读文件系统、空间和权限错误。
+- 自动化检查：提供只执行权限门禁的无副作用入口；在本地 Linux 容器分别覆盖 root 且无 sudo、普通帐号且无 sudo、普通帐号通过 sudo 提权三种场景，断言成功路径最终 `uid=0`、失败路径发生在步骤 1 之前且不创建 `/microi`。源码契约同时锁定正常安装与 `--repair-app` 均调用同一门禁，并执行 `bash -n`。
+
+## 多节点与滚动发布
+
+后端默认按多个 API/Worker 节点设计：
+
+- 所有节点共享业务数据库、MongoDB、Redis 和持久对象存储。
+- 全局状态、任务进度、锁和幂等事实不能只放进程内存/本机文件。
+- 新旧版本并存期间使用“先扩展、后迁移、再收缩”的兼容顺序。
+- 节点先停止接新工作，再有界排空；readiness 退出流量，liveness 只反映进程存活。
+- 数据库迁移、建索引、种子和缓存预热必须幂等，多节点同时启动不能重复副作用。
+- AuthSecret 在全部节点保持一致；轮换必须有明确的全节点策略，否则现有 JWT 会失效。
+
+## 构建资源保护
+
+启动 Node/Vite/dotnet/Docker build 前检查物理内存和同类进程。默认只运行一个重任务。
+吾码PC使用上文专用准入和97%暂停/95%稳定恢复策略；其余任务的启动门槛按“当前阶段进程树预算 + `max(1.5GB, 物理内存 5%)` 系统安全余量”计算，
+优先采用实测峰值；顺序阶段分别计算，不叠加峰值，也不得再用固定 20% 随机器容量放大门槛。
+资源不足时改做定向测试/构建，不并行启动多个全量任务；其余任务全机占用达到95%时暂停或终止本轮启动的重任务树。
+
+## Windows 多 AI 本地服务与 Release 文件锁
+
+多个 AI 对话共用同一工作区和固定 `61500/61501` 时，前后端是工作区级单例共享服务，
+不是每个对话各自拥有的后台进程。发布必须使用“同范围互斥 + 精确身份识别 + DLL 锁复核”：
+
+- 健康开发服务默认复用；需要重载源码时串行重启。长期后端只从项目目录执行
+  `dotnet run --launch-profile Microi.net.Api`，禁止直接运行 `bin/Release/net10.0`
+  或 `bin/Release/publish` 作为长期 E2E 服务。一次性测试本轮编译/发布产物时，复制到任务隔离目录启动，并登记身份、端口与最终收尾，避免占用共享 Release 输出。
+- API、PC、官网、Agent 分别使用 `api-release.lock`、`pc-release.lock`、`website-release.lock`、`agent-release.lock`，可并行发布；同类发布互斥。合并发布只取得所选产品的锁，部分取得失败时释放本次已取得的锁。
+- API 启动前执行 `node Microi.Server/tools/release-lock.mjs assert api <工作区根>`，PC 使用 `assert pc`；官网/Agent 不阻塞二者。旧全局锁仅在真实命令入口和状态目录证明 API 热修复或 Agent 归属后缩小阻塞范围，未知锁仍阻塞，不能删除活跃锁。
+- Windows 发布前调用 `Microi.Server/tools/Microi.LocalProcessManager.ps1 -Action PrepareRelease -ReleaseScope api|pc|all`。API 仅处理匹配工作区的后端与 Release DLL；PC 仅处理匹配的 Vite；官网不清理二者。禁止按进程名全机清理。
+- PC/API 普通发布执行 PlatformRelease，Full 仅为显式深度测试；restore/build/test/package audit 输出统一隔离到本次结果目录 `.net-artifacts`。并行验收使用独立结果目录及所需测试服务/端口，普通发布不创建租户；共享版本与跨产品源码先冻结，测试期间不得修改。资源排队依据为当前并行阶段预算之和与系统余量，不使用单一全局发布窗口。
+- 测试进程的 `MICROI_TEST_REPOSITORY_ROOT` 必须绑定本轮源码工作区；源码定位核对真实项目文件，不能把 SDK 产物中的同名目录当成源码。内存诊断保留子进程隔离，只使用当前 Configuration 和当前输出布局对应的夹具 DLL，缺失即失败，禁止借用旧 Debug 产物。诊断守护器的调用参数与报告路径必须属于同一次尝试，历史报告不可用于本轮放行。
+- Vite 以相对 `node_modules/vite/bin/vite.js` 启动且父进程退出时，命令行可能没有绝对工作区路径。
+  进程管理器只能把只读回读到的 CWD 精确等于当前 `Microi.Client` 作为补充证据；读取失败、
+  CWD 属于其它目录或仅检测到孤儿状态时仍须失败关闭。回归同时覆盖当前工作区可精确停止、
+  外部工作区同名相对 Vite 保持运行。
+- 停止后必须确认 `61500/61501` 已释放，并以 `FileShare.None` 独占打开
+  `Microi.net.Api/bin/Release/net10.0` DLL。只结束 `VBCSCompiler` 不能解决正在运行的
+  `.NET Host` 对业务 DLL 的锁定。
+- Edge/Chrome 用户浏览器、VS Code 的 Playwright Test Server、MCP/语言服务 Node、
+  既有或借用的数据库和 Redis 不属于发布清理范围；本轮新建临时依赖仍须按基础规范收尾。人工查看使用进程管理器的 `-Action Status`。
+- PowerShell 7 下的 macOS/Linux 进程管理使用真实端口、命令行、精确大小写 CWD 和启动时间回读；身份不明或 PID 复用时失败关闭，只结束已核验根进程的后代。无扩展名 `Microi.net.Api` apphost 须采用规范绝对可执行路径，精确位于当前 API 项目的 `bin/` 下，且 CWD 精确等于项目目录；非规范路径、同名外部程序、读取失败均拒绝。身份函数回归进入 Full，实际停止能力仍需自有进程与端口验收。专项回归必须在自有目录、端口和真实进程中证明当前工作区可停止、外部工作区保留，以及原始文件锁诊断；不允许为了跨平台放宽跳过门禁。
+
+## 一键发布产物边界与缓存
+
+- 最终 API 冒烟只临时注入项目配置中的十个基础设施 `AppSettings` 字段，不复制 `DevLoginBypass` 或其它本地节点，不改写用户源配置。成功、失败和可捕获中断都先恢复公共 `appsettings.json` 原始字节，再清理自有 scratch；恢复失败保留恢复证据并停止发布。产物捕获/复用、每次 Docker 构建及 API 镜像上传前均校验公共模板字节与 SHA-256，拒绝环境配置、旧冒烟备份和本地选择文件残留；镜像通过不可变 imageId 静态读取配置，不运行测试容器。不可捕获的强杀/掉电不保证即时恢复，后续门禁仍必须拒绝污染产物。
+
+- 一键脚本的本次构建、pack、冒烟日志和 NuGet 替换临时目录由 `Microi.Server/tools/release-scratch.mjs` 创建在发布结果目录的唯一 `release-scratch-*` 下，`EXIT` 自动收尾；归属清单与 `.cleanup.json` 回执在同级。成功仅留小回执，失败保留清单、原始错误和未清范围。它不删除 Full 报告、已发布制品、源码、共享 `.tmp` 或其它任务目录。执行器在 shell 启动前拒绝时，脚本内检查尚未运行；先定位当前宿主与拒绝阶段，不换工具绕过，也不默认添加 `-Force`、清除属性或修改 ACL。完整规则见工作区规范的“Windows 默认普通删除与策略拒绝排查”。
+
+- 需要完整解决方案构建和 NuGet 打包时，先完成一次 Release build；publish 阶段复用已验证产物，禁止先 clean 再重复编译同一项目引用链。
+- API 镜像只允许使用 `bin/Release/publish`，前端镜像只允许使用 `bin/Release/dist` 和必要的服务器配置；`net10.0`、源码、测试输出及其它构建中间目录不得进入 Docker 上下文。
+- `logs`、故障 spool、WAL 和节点诊断文件属于运行态数据。发布前后及冒烟测试后都要从 publish 清理，但不得删除源码/持久卷中尚待重放的原始 spool；项目文件应从源头设置为不复制到发布目录。
+- 正式发布不需要 PDB 时，从 publish 清单统一排除项目引用和第三方 PDB，并在推送前断言数量为零；这不等于删除编译中间目录中用于本地诊断的符号。
+- Docker 使用内容摘要缓存并在基础镜像标签可变时检查更新；不要在每个镜像方案前无条件 `prune -a` 或永久使用 `--no-cache`。磁盘不足时先报告占用，再对精确目标做可恢复或有条件清理。
+- DLL 混淆/签名必须先于最终冒烟测试，确保被验证、写入 NuGet 和放入 Docker 的是同一份最终 DLL。前端旧浏览器产物可以按源码、转换器和依赖锁文件的内容指纹做增量缓存，但缓存命中后仍需执行完整依赖、polyfill 和入口校验。
+
+## 部署证据分层
+
+不要把某一层成功等同生产完成：
+
+1. 配置/compose 静态检查。
+2. 镜像拉取或定向构建成功。
+3. 容器/进程启动且无启动错误。
+4. liveness/readiness 正常，依赖可达。
+5. 登录、菜单、FormEngine、ApiEngine、文件上传等真实路径正常。
+6. 双节点重复投递、节点退出、滚动升级与恢复验证。
+
+未执行的层必须明确写“未验证”，不能用“部署成功”概括。
+
+### 复盘：启动文案变化导致一键发布冒烟假失败
+
+- 触发场景：发布产物已经输出 `Now listening` / `Application started` 并可访问，但发布脚本因为等待某句历史中文启动文案而持续到超时，期间运行态日志或 spool 不断写入 `publish/logs`。
+- 根因：把易变化的日志文本当成服务可用事实源；超时/异常路径没有对临时进程和运行态目录做完整的有界收尾。
+- 通用规则：发布冒烟必须启动最终混淆/签名后的产物，确认本次进程仍存活，再以 `/api/Diagnostics/liveness` HTTP 200 判定启动成功；使用专用空闲端口，成功、超时、异常和中断路径都要在有限时间内结束本次进程并清理 publish 内的临时 logs/PDB。新完整发布默认从当前版本递增一次；确认续发同一候选时显式传 `--release-version=x.y.z`，不能依据未提交版本隐式复用。
+- 自动化检查：构造不再输出旧中文文案但 liveness 返回 200 的版本，断言冒烟成功；另覆盖端口占用、进程提前退出和 liveness 超时，断言脚本失败原因准确、进程无残留、`publish/logs` 不存在。再把工作区版本设为高于 HEAD，验证新完整发布仍递增一次、显式续发版本保持不变。
+
+### 复盘：旧租户启动闭包把应用包展示字段当成物理列并反复重启
+
+- 触发场景：升级后的节点发现平台运行时接口缺失，准备从内置官方应用包自愈；旧包把接口名称导出为 `Name`，目标 `sys_apiengine` 的真实字段却是 `ApiName`，直接拼接包对象后出现 `Unknown column 'Name' in 'field list'`。修完别名后，另一批旧库又因 `UserId NOT NULL` 且无默认值、而少数新接口包漏出审计字段，出现 `Field 'UserId' doesn't have a default value`。启动门禁失败会使 Docker 的 restart policy 不断重启同一进程。
+- 根因：启动自愈把“应用包传输对象”误当成“数据库物理行”，既没有规范化历史别名，也没有按目标租户的真实表结构过滤；同时只检查“列是否存在”，却没有覆盖旧结构中仍为必填且无默认值的审计列。不同年代租户会依次暴露 unknown-column 或 required-column 错误。
+- 通用规则：任何在 FormEngine 可用前直接写核心物理表的可信自愈，都必须先规范化已知历史别名，再应用固定实体字段白名单，并与目标租户实时回读的物理列取交集；SQL 只使用经过双重筛选的固定标识符和参数值。官方包本身必须携带完整审计字段；无登录上下文的启动门禁还必须为历史必填审计列提供稳定的系统身份兜底，并为 `IsDeleted/IsEnable/Lock` 等开关及 `ApiRole/Files` 等集合字段补齐语义明确的插入默认值，这些默认值不得参与授权。必需业务列缺失时给出明确物理升级错误，写入后按稳定 Key 强回读，禁止把包级元数据直接转换成列名。
+- 自动化检查：使用包含旧 `Name`、未来包级字段、新版本可选列及缺失 `UserId/UserName/Lock` 的官方包样例，分别对完整结构与精简旧结构断言 `Name -> ApiName`、未知字段被丢弃、必需字段保留、审计字段和传统必填列获得稳定非空值；同时扫描全部启动闭包包，保证 `SysApiEngines` 只输出 `ApiName` 且审计字段及传统必填开关完整，并锁定新增接口生成器输出的集合字段，最后执行真实启动日志门禁回归。
+
+## 空数据库 SQL 导入回归
+
+- 官方七种空库发布后逐一记录 ZIP SHA-256/大小并纳入原生公开副本。安装器通过固定 Database 枚举的只读选择器解析当前 NAS 地址，正文先 hub.microi.net、失败再 CDN；NAS 及仍带当前证明的 CDN 必须校验 SHA/大小，不将过期缓存导入为最新版。自定义 ZIP 不改下载来源。
+- 空库初始登录密码只用宿主 CSPRNG 派生的六位随机数字，登录页提示和加密存储使用同一值；AuthSecret 独立保持高熵。不得缩短数据库/Redis/MinIO 凭据或改变恢复库密码。制作任务成功、CDN/NAS 回读和各数据库实际导入分别记录。
+- 空库应用清理必须以平台基础表为保护边界：历史业务包误声明 diy_lang、组件、角色等核心字典表时，V8 与原生清理均不得将其作为应用表删除。脱敏发生失败并清理临时库后，新的生成请求须从 Prepare 开始；不得把原 Sanitize 检查点当成已有临时库继续。
+
+- PostgreSQL 导出中的 V8、默认值和注释使用显式 `E'…'` 字符串，同时转义反斜杠、引号、
+  物理换行及控制字符。分别在 `standard_conforming_strings=on/off` 中完整导入，回读代码
+  哈希、长度、空字符串与 NULL；不能把关闭标准字符串模式当作通用修复，也不能删改 V8 代码。
+- MySQL 5.7/8 分别在隔离 Docker 数据库执行完整原始脚本。SaaS 宽表的非索引配置文本
+  优先使用 `mediumtext`，保留主键、租户标识和索引列；字段元数据、物理列与应用包 DDL
+  必须一致。不通过关闭严格模式掩盖行宽错误，不将字符转义问题一概归为字段长度不足。
+- 通过官方 MCP 修复母版后发布归属应用，后端导出修复进入镜像后再运行既有空库制作后台任务。
+  等待成功终态，完整下载各 ZIP 并校验 SHA-256，再做导入与数据完整性验收。
+
+## 禁止事项
+
+- 启动字段门禁必须检查核心普通列的可空约束，不能仅以“字段存在”判定就绪。旧库非空列在程序共享租约内放宽为 `NULL`，保留 Id/数据库主键、列类型、默认值、注释和索引；同版本热修复也需回读真实结构。修复必须在插入启动接口之前执行，禁止通过逐次补默认值掩盖结构问题。
+
+- 不把数据库/Redis/MinIO 密码写入仓库、日志、命令回显或最终答复。
+- 不因容器更新而删除数据库卷、对象存储卷或日志 spool。
+- 不在所有节点同时硬重启。
+- 不把 `docker ps` 的 Running 当作 readiness。
+- 不在没有备份和恢复演练时执行数据库升级或不可逆迁移。
+- 不修改 `microi.doc/docs/doc/about/update-log.md`，除非用户明确要求发版。
+- 撤回或重写版本日志前，必须遵循 `../workspace-conventions/SKILL.md` 的“多对话共享工作区变更归属保护”；当天提交、最新 `HEAD`、相同作者或相关提交信息都不能单独证明改动属于当前对话。
+
+- 空库应用清理必须以平台基础表为保护边界：历史业务包误声明 diy_lang、组件、角色等核心字典表时，V8 与原生清理均不得将其作为应用表删除。脱敏发生失败并清理临时库后，新的生成请求须从 Prepare 开始；不得把原 Sanitize 检查点当成已有临时库继续。