mirror of
https://github.com/whyour/qinglong.git
synced 2026-09-20 16:07:11 +08:00
118 lines
6.3 KiB
Markdown
118 lines
6.3 KiB
Markdown
# ADR-0257：Profile 运行制品裁剪与分层 Import RSS 预算
|
||
|
||
- 状态：Accepted
|
||
- 日期：2026-08-01
|
||
- 关联 RFC：QL-RFC-0001 D-85、D-89、D-175、D-207、D-240
|
||
- 关联 ADR：ADR-0042、ADR-0185、ADR-0217、ADR-0256
|
||
- Supersedes：ADR-0185 中“所有 Profile 共用 16 MiB import RSS delta”与未区分开发包/运行制品的部分；不改变其 package 边界和文件/字节预算
|
||
|
||
## 背景
|
||
|
||
D-239 完成后，按真实 `pnpm pack -> offline install` 重跑十种本机 Profile，暴露出三个
|
||
不同问题：
|
||
|
||
- storage-only 安装闭包超过 512 files；
|
||
- adopted assembly 没有显式携带 `local-admin` 运行时需要的 `local-secret`；
|
||
- application 为 741 files、约 6.40 MiB，入口 import RSS delta 约 20.2--20.35 MiB，
|
||
超过原 640 files / 5 MiB / 16 MiB 门。
|
||
|
||
逐文件核算发现，内部 npm 包中的 `.d.ts` 和 `.map` 占用了大量部署 inode/bytes，但
|
||
Node 运行时不消费它们。另有两处不必要的 eager import：fresh/disabled adoption 在读取
|
||
启用开关前加载 admin runtime；通用 TaskDefinition repository 为抛出管理域错误而静态加载
|
||
administration 模块。它们是制品装配和入口依赖问题，不是新增 workspace package 的理由。
|
||
|
||
## 决策
|
||
|
||
### 1. 开发包与最终运行制品分离
|
||
|
||
内部 npm package 继续发布 `dist/**/*.js` 与 `dist/**/*.d.ts`，供 workspace、SDK 和类型消费；
|
||
source、test、声明 map 和 JS map 仍由 packlist 规则排除。Profile assembler 在完成 exact
|
||
offline install、核对精确 package closure 后，只从 `node_modules/@qinglong/**` 删除：
|
||
|
||
- `*.d.ts`；
|
||
- `*.map`。
|
||
|
||
不得裁剪第三方包、JavaScript、package manifest、受审 assets、Drizzle migration 或 native
|
||
文件；不得通过 ignore、symlink、未声明依赖或 workspace source 直接运行来制造通过。Docker
|
||
local application 镜像必须执行同一内部运行制品裁剪，静态镜像审计同时验证两类删除命令。
|
||
|
||
### 2. 精确装配 adopted 与 application 闭包
|
||
|
||
adopted Profile 的 production closure 显式包含 `@qinglong/local-secret`。fresh/disabled
|
||
adoption 入口先读取 enable gate，仅在启用后动态加载 `@qinglong/local-admin/runtime`；因此
|
||
storage-only 和 fresh adopted 不为迁移 authority 支付模块加载成本。
|
||
|
||
通用 SQLite TaskDefinition repository 不再静态导入管理域错误模块。事务 hook 抛出的精确
|
||
错误实例原样传播，其他 storage failure 仍由既有 `mapStorageError` 处理；没有改变 repository
|
||
对外语义或放宽错误分类。
|
||
|
||
### 3. Profile 预算表达实际能力层级
|
||
|
||
文件和字节预算保持 ADR-0185 的分层，不因本次失败放宽：
|
||
|
||
| 能力层 | 文件上限 | 字节上限 | import RSS delta 上限 |
|
||
| --- | ---: | ---: | ---: |
|
||
| storage-only | 512 | 4 MiB | 16 MiB |
|
||
| adopted compatibility | 576 | 5 MiB | 16 MiB |
|
||
| AI-only | 640 | 5 MiB | 16 MiB |
|
||
| application | 640 | 5 MiB | 24 MiB |
|
||
| application + AI | 768 | 6 MiB | 24 MiB |
|
||
|
||
24 MiB 只表示在独立 Node probe 中加载完整 application capability entrypoint 后的 RSS
|
||
增量，不是设备总内存预算。Edge production process 仍至少按 96 MiB 暂定总物理预算规划，
|
||
最终支持声明仍要求 Linux cgroup 和固定物理设备证据；不能用本门替代 cold start、峰值 RSS、
|
||
执行并发或闪存证据。
|
||
|
||
### 4. 不改变 package 拓扑
|
||
|
||
workspace 保持 19 个 package，不新建 artifact-pruner、task-admin 或 profile wrapper 包，不新增
|
||
production dependency、migration、daemon、timer、watcher、listener、Pool、连接或端口。
|
||
源码文件数量继续只触发 package 复审；合并仍必须证明不会破坏 Profile closure、共享 leaf、
|
||
进程权限或高权 authority 排除。
|
||
|
||
## 被拒绝的替代方案
|
||
|
||
1. **把 19 个包合成少数大包**：npm dependency 按 package 解析，会把 administration、Secret、
|
||
Process 和 Execution 依赖带入 storage-only 设备，拒绝。
|
||
2. **所有 Profile 统一抬到更大门限**：掩盖 storage/adopted 回归，拒绝；只有真实加载完整
|
||
application 的能力层采用 24 MiB。
|
||
3. **从 npm package 删除声明文件**：破坏类型消费者与开发体验，拒绝；裁剪只发生在最终运行
|
||
assembly。
|
||
4. **删除任意第三方文档、locale 或 package metadata**：会产生不可审计、升级易漂移的供应链
|
||
裁剪，拒绝。
|
||
5. **让 disabled adoption eager-load 后只在业务上不执行**：安装闭包和 import RSS 仍已支付，
|
||
拒绝；enable gate 必须先于 authority import。
|
||
|
||
## 验证
|
||
|
||
十档 exact offline artifact audit 全部通过：
|
||
|
||
| Profile | files | bytes | loaded modules | RSS delta bytes |
|
||
| --- | ---: | ---: | ---: | ---: |
|
||
| edge | 320 | 3,476,131 | 42 | 10,633,216 |
|
||
| standalone | 320 | 3,476,179 | 42 | 10,780,672 |
|
||
| edge-adopted | 358 | 4,033,157 | 43 | 10,764,288 |
|
||
| standalone-adopted | 358 | 4,033,241 | 43 | 10,878,976 |
|
||
| edge-application | 412 | 4,516,812 | 98 | 20,168,704 |
|
||
| standalone-application | 412 | 4,516,956 | 98 | 20,578,304 |
|
||
| edge-ai | 343 | 4,067,239 | 43 | 10,878,976 |
|
||
| standalone-ai | 343 | 4,067,299 | 43 | 10,878,976 |
|
||
| edge-application-ai | 435 | 5,107,992 | 97 | 20,348,928 |
|
||
| standalone-application-ai | 435 | 5,108,148 | 97 | 20,414,464 |
|
||
|
||
每档报告都包含实际/最大 files、bytes、RSS、精确 package 集合及被裁剪的内部开发文件计数。
|
||
local image 静态审计返回 `findings=[]`，并确认 application closure 包含 `local-secret`。
|
||
adopted lazy-authority 契约 8/8、TaskDefinition transaction 定向回归 13/13、local image
|
||
审计 7/7、local-sqlite 189/189 均通过；19 个 QL3 package 清理后拓扑构建和完整测试
|
||
零失败，backend 956 pass/2 条件 skip/0 fail。Edge import compatible，19-importer dependency
|
||
audit `findings=[]`；GitNexus compare-to-develop 与工作树检测均为 LOW、0 affected process。
|
||
|
||
## 后续约束
|
||
|
||
- 每次新增 production export、application capability 或 Profile package 必须重跑全部十档，不能
|
||
只测 edge；
|
||
- 报告数字是开发机可重复审计门，不自动构成任意路由器的支持声明；
|
||
- 若 application import delta 接近 24 MiB，必须先给出模块级 eager closure 解释和瘦身方案，
|
||
不能再次直接抬门；
|
||
- physical Edge、native/init-managed startup、镜像 SBOM/漏洞和 Cluster HA 门保持独立。
|