---
title: "生命周期与打包"
description: "运行时钩子、应用模型、不可变迁移、完整包校验和受控安装更新。"
canonical_url: "https://docs.mcent.cn/qicore/lifecycle-and-packaging"
---
# 生命周期与打包

> 运行时钩子、应用模型、不可变迁移、完整包校验和受控安装更新。

应用自行构建业务产物，宿主负责受控装配、迁移、维护排空和健康提交。开发工作区能够启动，不等于完整发行包已经具备客户安装条件。

## 运行时方法

<table>
<thead>
  <tr>
    <th>
      方法
    </th>
    
    <th>
      应用责任
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        createApplication(serverSdk)
      </code>
    </td>
    
    <td>
      返回与描述一致的格式、版本、definition 和运行时工厂，可附带应用模型片段
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        createRuntime(resources)
      </code>
    </td>
    
    <td>
      借用宿主资源，为应用创建运行时，返回自己的 key 和 consumerPaths
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        connect(services)
      </code>
    </td>
    
    <td>
      接收宿主连接的支付、订阅等公共服务
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        initialize()
      </code>
    </td>
    
    <td>
      初始化已迁移的运行资源，不在启动时创建演示租户或重建数据库
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        tick(enabled)
      </code>
    </td>
    
    <td>
      参数表示当前组件的 License 可用性，宿主 <code>
        system
      </code>
      
       运行时传入 <code>
        true
      </code>
      
      ；worker 仍须逐任务核验租户状态、当前应用绑定及业务条件
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        admin(session, path, method, req)
      </code>
    </td>
    
    <td>
      处理受信后台请求，继续核验应用权限和目标数据范围
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        consumer(session, path, method, req, res)
      </code>
    </td>
    
    <td>
      处理业务客户端路由，完整使用租户、应用与用户范围
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        health()
      </code>
    </td>
    
    <td>
      返回实际就绪结果，成功必须为 <code>
        true
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        close()
      </code>
    </td>
    
    <td>
      等待或安全停止自身任务，关闭自有资源，不断开宿主数据库
    </td>
  </tr>
</tbody>
</table>

`admin` 收到移除 `/api/v1` 后的完整路径段，例如 `['admin', 'tenants', tenantId, 'apps', applicationKey, ...]`；`consumer` 再移除 `apps/<applicationKey>` 两段，业务路径从 `path[0]` 开始。路由与身份前置见[HTTP 接口](https://docs.mcent.cn/qicore/http-api)。

`tick(true)` 不代表所有租户均可执行业务，也不包含租户停用、到期或当前绑定的逐项检查。发起新业务前按具体任务重新核验；收到 `false` 时停止发起新业务，仍保留既有回执处理、补偿和恢复责任。

应用是受信服务端代码。只有经验证的组件清单或显式开发装配能够加载入口；该契约不提供任意第三方代码的安全沙箱。

## 应用模型

有数据库模型时，入口可返回 `database` 片段：

<table>
<thead>
  <tr>
    <th>
      字段
    </th>
    
    <th>
      当前约束
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        format
      </code>
    </td>
    
    <td>
      <code>
        qicore-prisma-models-v1
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        prismaVersion
      </code>
    </td>
    
    <td>
      精确为 <code>
        6.19.3
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        schema
      </code>
    </td>
    
    <td>
      仅含应用自己的 model 块
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        models
      </code>
    </td>
    
    <td>
      与 schema 一致的生成模型元数据，字段为标量类型
    </td>
  </tr>
</tbody>
</table>

片段不加入 datasource、generator 或额外 schema 指令。模型名和物理表名分别按不区分大小写检查，与宿主及其他应用冲突时拒绝装配。

在应用自己的 Prisma 源码中使用命名空间，例如：

```prisma
model NotesDemoEntry {
  id             String @id @db.VarChar(64)
  tenantId       String @db.VarChar(64)
  applicationKey String @db.VarChar(64)
  userId         String @db.VarChar(64)
  title          String @db.VarChar(120)

  @@index([tenantId, applicationKey, userId])
  @@map("notes_demo_entry")
}
```

这只是应用模型源码示意。运行片段的模型元数据应由锁定工具链生成并与 schema 核对，不能只复制这段文本后手写一个不匹配的 models 对象。

宿主将通过校验的应用模型与公共模型装配到共享数据库客户端，使业务、资产和公共资金状态能使用同一事务。升级 Prisma 适配必须重新验证模型装配与真实数据库行为。

## 增量迁移

应用维护自己的迁移文件，包内固定为 `migrations/<迁移编号>.sql`。每项的编号、顺序和 SHA256 均进入真实发行清单。

当前自动迁移只接受经过解析器校验的增量 DDL，包括创建表、创建索引和 `ALTER TABLE ... ADD ...`。改名、修改列、破坏性 SQL、数据回填及存储过程调用等变更，需要另外的迁移与恢复方案。

- 已记录迁移不能修改、删除或以新摘要覆盖。
- 同一包的迁移历史按编号和摘要核对，已完成项不重复执行。
- 迁移执行中断、历史摘要不符或缺失旧迁移时阻止继续；先核对持久状态和备份。
- 不以重置数据库或重新编号迁移来消除错误。
- 宿主的框架空库基线不能直接用于已有应用数据库。

## 完整包结构

```text
应用包根/
├─ application.json
├─ release-manifest.json
├─ entry.mjs
├─ migrations/
│  └─ YYYYMMDDHHmmss_create_notes.sql
└─ web/
   ├─ admin/
   │  ├─ server/index.mjs
   │  └─ public/
   ├─ h5/
   │  ├─ index.html
   │  └─ h5-routes.json
   └─ mini-program/
      ├─ mini-program-template.json
      └─ ...
```

`entry.mjs` 是新应用推荐入口，实际入口以完整清单声明为准；各 web 端按[应用描述](https://docs.mcent.cn/qicore/application-manifest)选配。没有迁移或对应前端时，省略相应目录，不创建占位产物。

声明 H5 时必须带 `index.html` 和 `h5-routes.json`；声明后台时必须带固定 SSR 入口；声明小程序时必须带模板清单。小程序模板不携带真实实例身份。

包内允许应用自己的必要生产运行依赖。包中不放宿主实现、开发依赖、测试、源码映射、缓存、环境文件、数据库、上传、密钥或安装回执。

生产依赖应整理成包内独立的真实文件，不直接携带开发 `node_modules` 的 pnpm 符号链接或硬链接布局。运行树校验拒绝符号链接、共享硬链接、未声明的文件和目录；每个实际文件仍须满足发行路径约束并进入完整清单。

## 打包时使用同一份契约

从实际产物扫描出完整清单，使用安装器同样的公开校验入口：

```js
import {
  nativeArchiveManifestSchema,
  applicationDescriptorSchema,
  assertApplicationReleaseLayout
} from '@qicore/application-sdk/contracts'

const release = nativeArchiveManifestSchema.parse(manifest)
const descriptor = applicationDescriptorSchema.parse(applicationJson)
assertApplicationReleaseLayout(descriptor, release)
```

此处 `manifest` 和 `applicationJson` 分别来自真实发行清单及描述文件。大小、文件 SHA256、运行时与框架兼容范围必须依据实际产物和验收，不填示例占位摘要。

组件类型、包标识或版本不匹配返回 `APPLICATION_DESCRIPTOR_MISMATCH`；已声明端缺少必需文件返回 `APPLICATION_LAYOUT_INCOMPLETE`。

布局检查只核对结构，不执行应用入口，也不证明迁移、业务和渠道均已通过。发行材料按组件适用的发布策略验证，已有签名历史继续严格校验；不能把某个产品的材料例外推广到其他应用或插件。

## 安装、更新与恢复

<table>
<thead>
  <tr>
    <th>
      操作
    </th>
    
    <th>
      应满足的条件
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      安装
    </td>
    
    <td>
      持久身份一致、依赖与兼容范围满足，下载与完整性验证通过后才进入维护和迁移
    </td>
  </tr>
  
  <tr>
    <td>
      更新
    </td>
    
    <td>
      累计迁移历史保持一致，候选健康通过并持久提交活动回执
    </td>
  </tr>
  
  <tr>
    <td>
      修复
    </td>
    
    <td>
      针对当前精确版本及原清单，保留所需恢复材料，不改变版本或重新执行迁移
    </td>
  </tr>
  
  <tr>
    <td>
      卸载
    </td>
    
    <td>
      核对依赖、持久任务、支付、退款、通知和恢复引用，保留业务数据及历史绑定
    </td>
  </tr>
  
  <tr>
    <td>
      重新安装
    </td>
    
    <td>
      继续核对历史身份和迁移记录，不清空原数据来冒充首次安装
    </td>
  </tr>
</tbody>
</table>

活动代码指针与健康回执分别验证。代码清理服从宿主当前受控策略，只有健康回执提交且恢复引用解决后才收尾；备份、上传、配置和审计数据采用各自生命周期，不随代码清理删除。

如果活动版本健康但回执或清理仍未完成，只继续对应收尾，不重新下载、迁移或重复切换。

客户收到的是已构建、校验材料匹配的完整运行交付物。应用构建、完整包验证、正式发行、客户实例安装和真实渠道联调分别记录结果。


## Sitemap

See the full [sitemap](https://docs.mcent.cn/sitemap.md) for all pages.