# @appneurox/service-runtime 中文文档

规范地址：https://npmcn.com/package/%40appneurox/service-runtime/

版本：0\.1\.0
npm 元数据更新时间：2026-10-26T18:00:53.486Z
中文译文更新时间：2026-11-06T17:11:03.057Z
软件包许可：Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40appneurox/service-runtime
原文对照：https://npmcn.com/package/%40appneurox/service-runtime/?lang=original
项目主页：https://github.com/APPNEURAL-Microservices/nestjs-fleet#readme
源码仓库：https://github.com/APPNEURAL-Microservices/nestjs-fleet

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：95.2 kB，32 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=24 \<25
- 运行依赖：9 个
- 首次发布：2026-10-26T17:59:19.592Z
- 最新版本发布：2026-10-26T18:00:53.114Z
- 近 30 天下载量：2632（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：2（近 12 个月 2 个）

## 中文简介

共享的NestJS集装箱基线;目录业务能力仍未得到明确执行.

## 安装

```sh
npm install @appneurox/service-runtime
```

也可以使用：`pnpm add @appneurox/service-runtime`、`yarn add @appneurox/service-runtime`、`bun add @appneurox/service-runtime`

## README

# 共享 NestJS 集装箱基线

`@appneurox/service-runtime` 是目录服务寄存器的常见 HTTP 基础。 它在端口启动一个节点 24 进程 `8080`;在部署容器中作为非根本用户运行。 主机边缘终止了HTTPS. 本套件不执行目录业务,代理现有后端,提供数据库,或索赔提供者准备状态.

标注部署的公众反应 `runtime: "BOILERPLATE"`, (中文(简体) ), `businessImplementation: "not_implemented"`,以及 `businessReady: false`。 。 。 . `/health/ready` 仅计量HTTP靴子和排出状态. `/health/business` 返回时 **501 (简体中文)**. 能力元数据总是有作用 `implementation: "not_implemented"`,即使所提供的文件要求不同的状态.

## 独立条目

在远程跑道上构建和测试, 不安装本地多克或依赖性 :

```sh
npm ci --ignore-scripts
npm test
SERVICE_NAME=example-service SERVICE_CAPABILITY_LABEL="Example capability" node dist/main.js
```

`npm ci` 使用已执行的锁文件。 不在仓库文件、 CI 输出、 图像或能力元数据中发布证书 。 运行时间证书属于平台机密. 软件包是私有的,每个服务库都有销售商 `.platform/nestjs/`。 。 。 .

远程安装/构建此包后仓库根引用 :

```sh
node .platform/nestjs/dist/main.js
```

## 设置

| 设置 | 默认和验证 |
| --- | --- |
| `SERVICE_NAME` | 所需的小写 kebab sult, 例如 `example-service` |
| `SERVICE_CAPABILITY_LABEL` | 显示标签; 默认服务名称 |
| `CATALOG_SLUG` | 带有后缀的服务名称 `-service` 删除 |
| `SERVICE_VERSION` | `0.1.0-boilerplate` |
| `BUILD_SHA` | `unknown`; 否则为 7-64 十进制字符 |
| `NODE_ENV` | `production`; 还接受 `development`, (中文(简体) ), `test` |
| `PORT`, (中文(简体) ), `HOST` | `8080`, (中文(简体) ), `0.0.0.0`; 明确的回放/ IPv6 绑定地址也被接受 |
| `MAX_BODY_BYTES` | `65536`; 范围 1024-1048576; 压缩 JSON 被拒绝 |
| `REQUEST_TIMEOUT_MS` | `15000`; 范围 1000-60000; 边框头和套接字不活动 |
| `SHUTDOWN_TIMEOUT_MS` | `20000`; 范围 1000-60000 |
| `LOG_LEVEL` | `info`· ; `debug`, (中文(简体) ), `warn`, (中文(简体) ), `error`, (中文(简体) ), `silent` 也接受了 |
| `CORS_ORIGINS` | 空; 否则以逗号分隔的 HTTPS 来源, 没有通配符或证书 |
| `EXISTING_BACKEND_URL` | 仅可选 HTTPS 引用, 不使用用户信息、 查询或片段 |
| `SERVICE_METADATA_FILE` | 可选的 UTF-8 JSON 文件,最多64 KiB |
| `SERVICE_CAPABILITIES_JSON` | 替代内置元数据 JSON; 与文件相互排斥 |

元数据文件格式,仅包含公共产品信息:

```json
{
  "capabilities": [
    { "id": "example-operation", "name": "Example operation", "description": "Planned business capability." }
  ]
}
```

在没有文件或内部JSON的情况下,软件包将一个待发能力从 `CATALOG_SLUG` 财务报告和审定财务报表 `SERVICE_CAPABILITY_LABEL`。最大500个容量条目;重复ID和无效名称失败启动。 设置无效报告设置名称, 从未提供值 .

## 终点

| 路径 | 含义 |
| --- | --- |
| `/` | 服务身份和明确的锅炉板披露 |
| `/version` | 版本/构建身份和待定业务地位 |
| `/health/live` | 进程可以回答 HTTP |
| `/health/ready` | HTTP 运行时间初始化且不耗用, 200/503 |
| `/health/business` | 未执行的业务能力,501 |
| `/v1/capabilities` | 计划能力和共同基线元数据 |

所有其他已注册控制器都需要经过核实的认证,除非有明确说明 `@Public()`。未注册的路径返回一个正常的404。 基准从未将任何共享的令牌,租户头,已解码的JWT或前端会话解释为已核实的身份.

## 扩展服务

```ts
import { bootstrapService, RequireScopes, RequireTenant } from '@appneurox/service-runtime';
import type { AuthVerifier } from '@appneurox/service-runtime';
import { RecordsModule } from './records/records.module';

// Implement this port using the actual identity authority. Verify signature,
// issuer, audience and expiry; resolve membership/scopes. Invalid token -> null.
// Provider/authority outage -> throw. No reference verifier is fabricated here.
declare const verifier: AuthVerifier;

void bootstrapService({ imports: [RecordsModule], authVerifier: verifier });
```

使用 `@RequireTenant()` 财务报告和审定财务报表 `@RequireScopes('records:read')` 在保护路线. `X-Tenant-ID` 是不可信的选择,直到警卫确认 成为经核实的校长的成员 `tenantIds`;没有租户头创建权威。 拥有一名租户的校长可以隐含地选择;多个租户要求选择租户需要的路线。 范围完全匹配,没有自动通配符升级. 核查人私下收到原始无记名标志,不得登录. 受保护的路线在无证书的情况下返回401条,在未配置核查者的情况下返回503条,在成员/范围不匹配的情况下返回403条.

`CurrentPrincipal`, (中文(简体) ), `CurrentTenant`, (中文(简体) ), `requestContext`,以及 `SERVICE_CONFIG` 为业务代码导出。 将每个寄存器查询/写入给经认证的租户;这项HTTP合同不能取代数据库隔离或资源授权。 业务单元必须分别实施其真正的依赖性探测、OpenAPI合同、存储/迁移、交易/能力、供应商集成、授权、遥测和功能测试。 在采用共同代码的同时保留已有的业务后端;这个软件包是一个启动器,而不是自动迁移.

`createServiceApplication()` 初始化不听或信号处理器进行测试/嵌入. `bootstrapService()` 听,处理SIGTERM/SIGINT,关闭前排出标记,关闭后强制退出. 它回来了 `{ app, config, shutdown }`;方案关闭是一能的。 使用 `handleSignals: false` 当主机拥有生命周期处理.

严格的DTO验证使用类验证元数据:未知属性和隐性强制被拒绝,验证值被排除在响应之外. 在语法检查后传播请求/关系ID;重复的安全头被拒绝. 日志包括方法,路由模板,持续时间,状态和ID,不包括原始的URL,信头,正文和查询. 安全头,被禁用的代理头信任,JSON限制和通用例外适用于每个控制器. 在边缘和(或)一个真正的共享商店应用认证-意识率限制;这个起动器并不假装内置计数器是全舰队的配额.

## 核查

`npm test` 编译 TypeScript 然后运行节点测试跑道. 测试内容包括元数据诚实、配置限制、编辑、公共卫生语义、认证默认拒绝、租户/镜像、请求-本地上下文、DTO拒绝、变形/大小过大/压缩JSON、重复头、安全头、CORS和无秘密例外/日志。 对这支车队的远程CI跑手有意进行依赖性安装和可执行测试.

## 常见问题

### @appneurox/service-runtime 是什么？

共享的NestJS集装箱基线;目录业务能力仍未得到明确执行\.

### 如何安装 @appneurox/service-runtime？

在项目目录运行 npm install @appneurox/service-runtime，或使用 pnpm add / yarn add / bun add。

### @appneurox/service-runtime 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @appneurox/service-runtime 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @appneurox/service-runtime 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=24 \<25。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @appneurox/service-runtime 可以商用吗？

@appneurox/service-runtime 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @appneurox/service-runtime 的下载量有多少？

根据 npm 官方下载统计，@appneurox/service-runtime 在 2026/10/07 – 2026/11/05 这 30 天内被下载 2,632 次，日均约 88 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @appneurox/service-runtime 还在维护吗？

最新版本 0\.1\.0 发布于 2026/10/27（12 天前）；至今共发布 2 个版本，其中过去 12 个月发布了 2 个；首次发布于 2026/10/27。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。