# @crossdelta/infrastructure 中文文档

规范地址：https://npmcn.com/package/%40crossdelta/infrastructure/

版本：0\.19\.0
npm 元数据更新时间：2026-10-25T12:40:23.783Z
中文译文更新时间：2026-11-11T01:34:06.892Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40crossdelta/infrastructure
原文对照：https://npmcn.com/package/%40crossdelta/infrastructure/?lang=original

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

- 包体积（解压后）：295 kB，48 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：1 个
- peer 依赖：@pulumi/pulumi ^3\.0\.0，@pulumi/kubernetes ^4\.0\.0，@pulumi/digitalocean ^4\.0\.0
- 首次发布：2025-11-30T21:26:04.142Z
- 最新版本发布：2026-10-25T12:40:23.605Z
- 近 30 天下载量：4405（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：92（近 12 个月 92 个）

## 中文简介

[![npm version](https://img.shields.io/npm/v/@crossdelta/infrastructure.svg)](https://www.npmjs.com/package/@crossdelta/infrastructure) [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)

## 安装

```sh
npm install @crossdelta/infrastructure
```

也可以使用：`pnpm add @crossdelta/infrastructure`、`yarn add @crossdelta/infrastructure`、`bun add @crossdelta/infrastructure`

## README

# @ crossdelta/ 基础设施

[![npm version](https://img.shields.io/npm/v/@crossdelta/infrastructure.svg)](https://www.npmjs.com/package/@crossdelta/infrastructure) [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)

对向 **DigitalOcean Kubernetes (DOKS) (英语)**。您将每项服务描述为一个打入的配置对象,软件包生成部署、服务、入侵、秘密、健康探测器和滚动更新策略.

为在DOKS上运行TypeScript微服务的团队所建,有NATS JetStream,GHCR和Pulumi. 如果这是你的堆栈, 这可以节省真正的锅炉板。 如果不是,你可能更好 与平地普鲁米或赫尔姆.

## 何时使用

-   您将多种类型脚本服务部署到一个 **数字海洋** Kubernetes集群
-   你用这个 **普鲁米** (不是Terraform,不是仅Helm)用于基础设施
-   您需要每个服务一个配置对象, 而不是 K8s 资源声明的 ~ 150行
-   你需要NATS JetStream,NGINX入侵,cert-manager, 或者凯迪作为反向代理

## 当不使用时

-   **AWS/GCP/祖尔**:只有DOKS被执行. EKS/AKS/GKE不支持.
-   **平地或平地螺旋桨**:这是只用普鲁米.
-   **非倾向设置**:软件包为您作出选择(Helm图表版本,部署策略,DO特定说明). 需要完全控制时,直接使用普鲁米.
-   **单一服务项目**: 管理费对于一项服务不值得.

## 安装

```bash
npm install @crossdelta/infrastructure @pulumi/pulumi @pulumi/kubernetes
# For DOKS cluster creation:
npm install @pulumi/digitalocean
# For NATS stream deployment (optional):
npm install @crossdelta/cloudevents
```

## 包括什么

| 模块 | 它会做什么 |
| --- | --- |
| **组** | `createDOKSCluster()`, (中文(简体) ), `createVPC()`, (中文(简体) ), `createK8sProviderFromKubeconfig()` |
| **工作量** | `deployK8sService()`, (中文(简体) ), `deployK8sServices()`, (中文(简体) ), `createNamespace()`, (中文(简体) ), `createImagePullSecret()` |
| **NGINX侵略** | `deployNginxIngress()` 通过Helm(图 v4.11.3) |
| **证书管理器** | `deployCertManager()` 通过Helm(图v1.16.2) |
| **海军** | `deployNats()` 通过Helm(图v1.2.6), `buildNatsUrl()` |
| **凯蒂** | `deployCaddy()`, (中文(简体) ), `generateCaddyfile()` 使用点播 TLS 的反向代理 |
| **流线** | `collectStreamDefinitions()`, (中文(简体) ), `deployStreams()`, (中文(简体) ), `materializeStreams()` (NATS喷气相机) |
| **服务发现** | `discoverServiceConfigs()` 自动发现配置 `infra/services/*.ts` |
| **本地开发** | `generateComposeYaml()`, k3d 集群脚本 |
| **国 际** | `generate-env` 生成 `.env.local` 从 Pulumi 配置 + 服务发现 |

## 快速启动

一个 `index.ts` 提供集群、运行时间组件和所有服务:

```typescript
import {
  createDOKSCluster,
  createVPC,
  createNamespace,
  deployRuntime,
  deployK8sServices,
  discoverServiceConfigs,
} from '@crossdelta/infrastructure'

const vpc = createVPC({ name: 'my-vpc', region: 'fra1' })
const { provider } = createDOKSCluster({
  name: 'my-cluster',
  vpcUuid: vpc.id,
  nodePool: { name: 'default', size: 's-4vcpu-8gb', nodeCount: 1 },
})
createNamespace(provider, 'my-namespace')

const runtime = deployRuntime(provider, 'my-namespace', {
  nats: { enabled: true, config: { replicas: 1, jetstream: { enabled: true } } },
  ingress: { enabled: true },
  certManager: { enabled: true, config: { email: 'ops@example.com' } },
})

const configs = discoverServiceConfigs('services')
deployK8sServices(provider, 'my-namespace', configs)
```

## 服务配置

每个文件在 `infra/services/` 导出一个配置对象。 软件包从中获取所有 K8s 资源 :

```typescript
import { ports, type K8sServiceConfig } from '@crossdelta/infrastructure'

const config: K8sServiceConfig = {
  name: 'my-service',
  ports: ports().http(4000).public().build(),
  healthCheck: { httpPath: '/health' },
  ingress: { path: '/api', host: 'example.com' },
  env: { DATABASE_URL: dbUrl },
  secrets: { API_KEY: apiKey },
  resources: {
    requests: { cpu: '50m', memory: '64Mi' },
    limits: { cpu: '200m', memory: '256Mi' },
  },
}

export default config
```

见 `K8sServiceConfig` 所有字段:复制品、卷、策略、容器Env、标签、说明、服务Type等.

从 `replicas: 2` 向上服务还获得地形分布限制(每个节点一个吊舱, `ScheduleAnyway`)和一项可能中断的预算(`maxUnavailable: 1`) (中文(简体) ). 在两个复制品下面也没有创造出来,因为一个复制品上的 " PodDisruption " 预算会阻碍每个节点的排出。 设定 `highAvailability: false` 以选择一个多replica服务,例如当其吊舱共享ReadWriteOnce卷时.

## 共享集群( 多层)

Pin 数字海洋资源名称 `clusterName`编号 :`vpcName` 用于在 Pulumi 堆栈上共享一个集群:

```typescript
// Stage stack owns the cluster
const { provider, kubeconfig } = createDOKSCluster({
  name: 'my-cluster',
  clusterName: 'my-cluster',
  vpcUuid: vpc.id,
  nodePool: { name: 'default', size: 's-4vcpu-8gb', nodeCount: 1 },
})
export const clusterKubeconfig = kubeconfig

// Production stack references stage
const stageStack = new StackReference('org/project/stage')
const provider = createK8sProviderFromKubeconfig(
  'production',
  stageStack.getOutput('clusterKubeconfig'),
)
```

## 生成- env CLI

生成 `.env.local` 从普鲁米的秘密和发现的服务配置:

```bash
npx generate-env              # defaults to stage stack
npx generate-env --stack=production
npx generate-env --no-pulumi  # skip Pulumi, only service discovery
```

## 限制

-   **仅限DOKS.** 没有实施其他云提供者.
-   **Helm图表版本被固定.** NGINX v 4.11.3, cert-manager v 1.16.2, NATS v1.2.6. 尚未覆盖选项 .
-   **服务发现假定一项公约:** `infra/services/*.ts` 文件为 `export default config`。 。 。 .
-   **`@crossdelta/cloudevents` 是一个很难依赖的** 即使你不使用NATS流 [https://github.com/orderboss/platform/issues/TBD 互联网档案馆的存檔,存档日期2013-12-02](https://github.com/orderboss/platform/issues/TBD)。 。 。 .
-   **Caddy 部署使用再创建策略** (RWO PVC与滚动更新不相容).

## 许可证

麻省理工学院 [横跨德尔塔](https://crossdelta.de/)

## 常见问题

### 如何安装 @crossdelta/infrastructure？

在项目目录运行 npm install @crossdelta/infrastructure，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 generate-env，可以用 npx generate-env 直接运行。

### @crossdelta/infrastructure 支持 TypeScript 吗？

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

### @crossdelta/infrastructure 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @crossdelta/infrastructure 可以商用吗？

@crossdelta/infrastructure 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @crossdelta/infrastructure 的下载量有多少？

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

### @crossdelta/infrastructure 还在维护吗？

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