# @astrale-domains/services 中文文档

规范地址：https://npmcn.com/package/%40astrale-domains/services/

版本：0\.9\.6
npm 元数据更新时间：2026-11-07T01:35:58.749Z
中文译文更新时间：2026-11-07T01:08:36.177Z
软件包许可：未声明

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

原始 npm 页面：https://www.npmjs.com/package/%40astrale-domains/services
原文对照：https://npmcn.com/package/%40astrale-domains/services/?lang=original
项目主页：https://github.com/astrale-os/domains#readme
源码仓库：https://github.com/astrale-os/domains

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

- 包体积（解压后）：178 kB，124 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=24
- 运行依赖：2 个
- 首次发布：2026-08-26T13:09:50.181Z
- 最新版本发布：2026-11-07T01:35:58.557Z
- 近 30 天下载量：2664（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：39（近 12 个月 39 个）

## 中文简介

`services.astrale.ai` 主机服务:Cloudflare工人身份。 服务是指一个项目在一个环境中的稳定特性。 每一次部署都增加了一个不可改变的部署,而该处的URL服务于它目前指定的一个,li

## 安装

```sh
npm install @astrale-domains/services
```

也可以使用：`pnpm add @astrale-domains/services`、`yarn add @astrale-domains/services`、`bun add @astrale-domains/services`

## README

# 服务

`services.astrale.ai` 主机服务:Cloudflare工人身份。 服务是马厩 在一个环境中识别一个项目。 每次部署都增加了不可改变的部署,而且 该处的URL服务于它目前指定的一个,就像一个项目及其部署一样.

服务是对其宿主的不可知论。 Astrale 域名发布(`astrale-domain deploy` 与 `@astrale-os/adapter-astrale`)和一般工人(工作、API、 [`create-astrale-service`](https://npmcn.com/package/%40astrale-domains/services/#readme-generic-services) 这对於《古兰经》确是同样的, 它冻结的配置, 它绑定的秘密, 当它发布一个, 一个不透明的记录. 每个域的事实(出处,出处,Schema修订,出处,出处)都是部署者. 提供方协议留在中性 SDK 集成后, 图形只允许 生命周期证据.

## 型号

-   **`Service` 编号 : `CloudflareService`**页:1 `(project, environment)`。项目是任意名称 (单位:千美元)`PROJECT_NAME` 联 合 国 `@astrale-os/sdk/deployment/worker`; 一个域名部署者命名其域名 源代码。 内容 `name` 是不透明的 16 个字符 `serviceName(project, environment)`中的独特 服务,DNS标签 `url`, (中文(简体) ), `https://<name>.<routing domain>`。 。 。 . `state` 实值 `active`,或 `deleting` 而在删除时将停止部署.
-   **`service_owned_by`**:服务处最多有一个拥有者,身份:用户、组或 服务账户。 选择一次,当第一次部署建立该处时,只改变 以 `transfer`。内核不能限制删除身份 (单位:千美元)[内核 # 1498](https://github.com/astrale-os/kernel/pull/1498): 删除所有者解析 边缘,而服务局在没有业主的情况下生存([下级](https://npmcn.com/package/%40astrale-domains/services/#readme-a-service-without-an-owner)) (中文(简体) ).
-   **`Deployment` 编号 : `CloudflareDeployment`**:一次不可改变的释放服务,一次服务 在自己的 URL 上为平台服务的工作人员脚本, `https://<label>.<routing domain>`时 `label` 实值 `<name>-<content16>` 和内容覆盖构建摘要和配置摘要。 这个 仅保留一般事实: `buildDigest`页:1 `configuration` (单位:千美元)`WorkerConfigurationV1`和 `configurationDigest`,则 `record` 如果有的话(不透明字节及其介质类型),它会公布其 密钥 id 当它要求签名身份时, 脚本的代码散列, 其密钥摘要 秘密及其生命周期: `deploying` → `active` → `retiring` → `retired`,或 `failed`A级 退役的部署从此不再服务.
-   **`deployment_of`**: 服务部署是版本。 部署没有主人 它属于拥有其服务的人.
-   **`current_deployment`**:服务处的URL服务的部署及其克伦斯运行. 促进 另一种部署移动这个边缘;回滚就是推动一个更古老的边缘.

秘密值只写在 Cloudflare , 并且从不输入突变或图表 。 时间表 是供货国。 日志在被询问时会从提供者处读取.

## 拥有者和当局

一项政策决定一切: `OwnService`,主体为服务所有人. 内核 透过呼叫者来评估 呼叫者通过的所有身份 `extends_with`,与 否认胜利。 检查时没有选择任何内容:没有一组呼叫者到达自己的服务处,a 三组呼叫者也分别到达服务处.

-   创建服务处的部署使呼叫者成为其主人,或 `owner` 名称当 呼叫者是或作为该身份行事(`ActAs`) (中文(简体) ).
-   一个服务账户在它拥有服务时,或当它成为该服务组的成员时,部署服务组 拥有它( o)`Group.assignMember` 写入 `extends_with` 边缘). 每个成员都有权利 集团服务,删除.
-   `OwnDeployment` 向服务所有人提供部署.

每一种方法都是 `authenticated`。每个处理器询问内核 `Identity.can` 供奉召唤者 在它读到任何内容之前,它自己的会话:不拥有服务处的打电话者找不到任何信息 (单位:千美元)`SERVICE_NOT_FOUND`, (中文(简体) ), `DEPLOYMENT_NOT_FOUND`),并拒绝部署另一个业主服务处 `service-owned-elsewhere`。 。 。 .

`list` 在服务域证书下读取服务并保存核心答案 `OwnService` 用于: 调用模式读取时未达到 `service_owned_by` 给一个主人 呼叫者通过 `extends_with` (单位:千美元)[内核 #1138](https://github.com/astrale-os/kernel/issues/1138)) (中文(简体) ).

### 没有主人的服务

一旦所有者身份被删除,一个服务是无人的:没有呼叫者满足 `OwnService` 碞硂妓, 甚至连克内尔根 `Identity.can` 答案是事实性的。 只有超越权力 所有权仍然达到它,例如直接写入图表的根。 处理者视之为 宣布状态:

-   其方法找不到服务处`SERVICE_NOT_FOUND`至於任何服务.
-   其项目和环境的部署被拒绝 `service-owned-elsewhere`,带有信息 它没有主人,必须先转到一个.
-   `list` 从来没有列出它.
-   A 类 `transfer` 或一个 `delete` 谁的打电话者证明它拥有这个服务 在它的主人被删除之前 完成 : 传输给 Service 其名称, 删除不包含 一个主人Edge。 每个变异栅栏在它读到的主人, 或者在服务处仍然没有.

## 方法

你们应当叫他们去见行政官`astrale call ... --admin`) (中文(简体) ). 他们的电线合同 `@astrale-os/sdk/deployment/worker`对.

| 方法 | 打开 | 它会做什么 |
| --- | --- | --- |
| `deploy` | `CloudflareService` (静态) | 主办一个工人发布(`WorkerDeploymentRequestV1`作为该处项目和环境的部署,在该处首次部署时设立该处,默认(`promote` 缺席或 `true`使该处为其服务。 答复 `WorkerDeploymentResponseV1`。 。 。 . |
| `hosting` | `CloudflareService` (静态) | 线路域服务和部署在(b)项下处理:`WorkerHostingV1`名称总是不透明的. |
| `list` | `CloudflareService` (静态) | 呼叫者拥有的服务处的部署情况`WorkerDeploymentSummaryV1`页:1 `project` 还有一个 `environment` 当给定时,每个 `current` 和它所发表的记录. |
| `promote` | `CloudflareService` | 将该处定位在其标签所命名的主动部署之一. |
| `transfer` | `CloudflareService` | 将服务交给另一所有者,即打电话者. |
| `setSecret`, (中文(简体) ), `secrets` | `CloudflareService` | 重写一个已宣布的当前部署的秘密; 列出它绑定的名称, 绝不是一个值 . |
| `setSchedule`, (中文(简体) ), `schedules` | `CloudflareService` | 替换或读取 UTC 的 cron 设置; 在当前部署时, 每个 cron 点火 . |
| `logs` | `CloudflareService` | 目前部署的最近记录,或 `label`。 。 。 . |
| `delete` | `CloudflareService` | 停止对处的调度,退役每次部署,再删除并解开名称. |
| `retire` | `CloudflareDeployment` | 永远撤回一次部署 目前部署从未单独退役. |

## 部署

`deploy` 是不可持久行动:其输入有秘密,没有执行、步骤结果或 日记条目保留它们.

1.  任何读取前,SDK的 `decodeWorkerDeploymentRequest` 接受请求: 每个文件 解码在其界限内, 配置条形, 一个记录, 确切的配置时间 要求一个, 确切的秘密 名称它宣布。 它重录了建筑摘要 上传的字节( e)`build-mismatch`)和来自服务名称、建筑和 配置 (`address-mismatch`) 其他东西是: `invalid-deployment`组合 请求此环境没有的路由器 `hosting-unavailable`。 。 。 .
2.  它在服务域证书下读取了名称的服务 并证明来电者 授权在呼叫者自己的会话中: `OwnService` 现有处, `ActAs` 有关所有者 它的名字是一个新的.
3.  在图租下创建了新的标签. 提供者仅与主机一起上传它 绑定( 其 URL 为 `WORKER_URL`,重新计算 `ASTRALE_BUILD_DIGEST`,该版本 元数据 `ASTRALE_VERSION_METADATA`),配置的变量,生成一个签名密钥 仅用于这一部署`ASTRALE_SIGNING_IDENTITY`只有当它问 `signingIdentity`,则 路由器( r)`ROUTER`只有当它问 `router`和请求的秘密。 当请求名称 准备路径,每个路径必须从上传的版本中回答200(`x-astrale-worker-version`(三); 没有人跳过探测器。 然后通过路线 KV 激活标签 `record:<label>` 与 记录 部署 发布 , 使用 媒体 类型 `/.well-known/astrale/deployment.json`,或者没有出版时的占位符。 图表 记录它的代码散列,它的密钥编号 当它有一个,和密钥 HMAC-SHA256 文摘 隐藏秘密.
4.  同样的发布再次是同一个标签: `deploy` 答题 `reused`。它的秘密被比较 与记录的文摘: `unchanged`或仅就这项部署重写, `updated`。 。 。 .
5.  当它促进, `current_deployment` 行动到部署阶段,用栅栏围住该处 已经送达,还有路线KV `current:<name>` 命名它的标签。 失败的路由写入是 已回复 `service-unavailable`; 部署或升级再次汇合.

主机名称自绑( Name`WORKER_HOST_BINDINGS`数字 : `WORKER_URL`, (中文(简体) ), `ASTRALE_BUILD_DIGEST`, (中文(简体) ), `ASTRALE_VERSION_METADATA`, (中文(简体) ), `ASTRALE_SIGNING_IDENTITY`, (中文(简体) ), `ROUTER`, (中文(简体) ), `ASSETS`) 从来不是一个变量 或请求的秘密.

-   **一个域** 部署人员 `astrale-domain deploy <environment>` 与 `astrale()` 联 合 国 `@astrale-os/adapter-astrale`:它的项目是域名的由来,它的建设名单成员是: 域(所以) `ASTRALE_BUILD_DIGEST` 是密封的释放, 其执行设置旅行 作为 `ASTRALE_SETTINGS` 变量,它公布其 `DeploymentRecordV1` 并请求签署 身份 准备调查释放文件 适配器,而不是服务,验证 释放并安装它.
-   **其他工人** 与 `@astrale-os/adapter-astrale/services` (单位:千美元)`readWorkerDirectory`, (中文(简体) ), `deployWorker`, (中文(简体) ), `callService`作为项目 [`create-astrale-service`](https://npmcn.com/package/%40astrale-domains/services/#readme-generic-services) 生成结果 .

## 骑行和行走

服务调度员是主机设备的调度员`@astrale-os/adapter-cloudflare/hosting`, (中文(简体) ), 仅以东道方部署线路;退休租户线路不再提供. 它服务于一个路径域:

-   `https://<label>.<routing domain>` 为部署服务: `record:<label>` 启动它,并且 `retirement:<label>` 答题 `DEPLOYMENT_RETIRED` (单位:千美元)`410`) (中文(简体) ). 它解答了部署记录 `/.well-known/astrale/deployment.json` 本身; 一种没有公布答案的部署.
-   `https://<name>.<routing domain>` 为部署服务 `current:<name>` 名称,通过相同的 因此,退休的部署也从不通过其部门提供服务.
-   每一分钟调度员都会读到 `cron:<name>` 密钥和帖子 部署该处: `POST https://cron.internal/__scheduled` ,并用 `x-astrale-cron` 发射的一瞬间 以相差几毫秒的速度 `x-astrale-scheduled-time`,10秒内完成. 一个非2 -2xx的答案被记录。 公众 永远无法到达 `/__scheduled`: 调度员拒绝在每一拼写中(案件、重复或 跟踪鞭打,百分率编码) 在任何检查之前。 跑步并非一成不变:工作必须是 安全地重复.

## 秘诀

服务从不保持价值。 部署只将请求的秘密与新的部署联系在一起; 每一次部署都保持自己的状态. `setSecret` 重写当前部署的一个名称 配置在部署图租赁下宣布到位:它比较了按键 文摘,只写更改的值,忘记它先写的名字和记录的文摘 新的,一旦每个写成功。 供应商在几秒钟后提供新的价值。 A 类 新名称,或去掉一个名称,是新发布的;签名密钥从不旋转.

永远不要在argv中传递一个秘密值. 仅将输入写入您能够读取的文件, 写入文件外 仓库 :

```json
{ "name": "API_TOKEN", "value": "<the new value>" }
```

```sh
astrale call "@$SERVICE::services.astrale.ai:class.CloudflareService.method.setSecret" \
  --admin -d @rotate.json --json
```

将新值也放在环境的秘密中:下一次部署会约束其值 携带.

## 退职和退休

```sh
astrale call /:services.astrale.ai:class.CloudflareService:list \
  project=agencies.example.com environment=production --admin --json
astrale call "@$SERVICE::services.astrale.ai:class.CloudflareService.method.promote" \
  label=$PREVIOUS_LABEL --admin --json
```

`retire` 分两个阶段撤回一个部署:第一个呼叫记录 `retiring` 写作 它的墓碑,以及后来的召唤 `retryAfterMs` (每名调度员都读墓碑,大约65个) 秒)删除脚本和密钥及答案 `retired`。 。 。 .

```sh
astrale call "@$DEPLOYMENT::services.astrale.ai:class.CloudflareDeployment.method.retire" \
  --admin --json
```

`delete` 标记服务 `deleting`,删除 `current:<name>` 财务报告和审定财务报表 `cron:<name>`,并逐一退休 部署。 它会回答的 `deleting` 与 `retryAfterMs` 直到最后一个退休,然后删除 在一次突变和回答中 `deleted`。然后名称是免费的 再来一次.

## 一般事务

包装一个孤立的脚手架 二进制( 根导入仍然只有Schema):

```sh
npm exec --package @astrale-domains/services -- create-astrale-service nightly-report
cd nightly-report
npm install
# Edit service.json and src/job.js; put the secret values in .env.production.
npm run deploy -- production
```

生成器只创建本地源并拒绝现有的目的地:普通工人 (单位:千美元)`src/index.js` 回复 `GET /health` 运行 `src/job.js` 打开 `POST /__scheduled`页:1 可选 ES256 账户会话以调用 Astrale Kernel(`src/account.js`, (中文(简体) ), `service.json` (单位:千美元) 项目、工人运行时间、变量、秘密名称、准备路径和路线) 构建(构建)并部署脚本. `npm run deploy -- <environment>` 把它建起来,通过它部署 `@astrale-os/adapter-astrale/services` 作为默认推动的不可改变部署 (单位:千美元)`--no-promote` 然后将该处的克伦斯替换为 `service.json`对 它只安装、登记、赠款和时间表。 生成的 README 解释推广和回滚、秘密、克伦斯、日志和删除。 脚手架住 [`tooling/scaffold`](https://npmcn.com/package/%40astrale-domains/services/tooling/scaffold)· ; `pnpm package` 复制给 `dist/scaffold`。 。 。 .

## 行政托管运行时间

仅为行政院的Kernel提供服务:其图表是服务登记处 名称,而部署命名空间和路径 KV 则共享。 一个域工为每个域服务 安装它的内核; 任何其他内核在读出任何内容前都发现托管不可用 .

这个 `admin` 环境设置平地 `ASTRALE_ROUTER_WORKER`, (中文(简体) ), `SERVICES_DEPLOYMENT_HOST` (单位:千美元) 路由域)和 `SERVICES_DEPLOYMENT_KERNEL` (行政克内尔的发行者URL). 这些瓦斯是 仅宣布主办并具有约束力 `SERVICE_DEPLOYMENTS`它的秘密档案, `.env.admin`, (中文(简体) ), 套装 `SERVICES_SECRET_DIGEST_KEY` (至少32 UTF-8 字节), `CLOUDFLARE_DISPATCH_NAMESPACE` 财务报告和审定财务报表 `CLOUDFLARE_SCHEDULE_KV_ID`; 配置拒绝一个没有它们或设置一个文件的文件 (原始内容存档于2018-09-21). hosting var.

`.env.admin.tpl` 是每个秘密作为1Password参考的文件. `scripts/with-secrets.sh admin -- <command>` 为一个命令决定: `.env.admin` (0600) (中文(简体) ) 命令运行时已存在,其值处于命令环境中,文件是 之后删除。 解决 `.env.admin` 磁盘上被拒绝而不是覆盖.

`pnpm run deploy admin` 在平台调度中 进行一个不可改变的部署 名称空间。 部署从未安装 : 用已部署的 URL 安装 `astrale domain install <url> -i <instance>`Cloudflare 提供者及其操作员工具 以主机包为基础:提供调度员(服务环境)和 平台名称空间”、审计、平台退役和秘密旋转在 [`providers/cloudflare/operator/README.md`](https://npmcn.com/package/%40astrale-domains/services/providers/cloudflare/operator/README.md)。 。 。 .

## 域开发

服务是根据其测试开发的:主机包的假Cloudflare账户 (单位:千美元)`@astrale-os/adapter-cloudflare/hosting/testing`,运行上传的调度器,以及 (脚手架工人本身) [实源套件](https://npmcn.com/package/%40astrale-domains/services/tests/kernel/README.md)。 。 。 .

```sh
pnpm typecheck
pnpm test
pnpm lint
pnpm frontend:build
pnpm build
pnpm package
```

## 常见问题

### @astrale-domains/services 是什么？

services\.astrale\.ai 主机服务:Cloudflare工人身份。 服务是指一个项目在一个环境中的稳定特性。 每一次部署都增加了一个不可改变的部署,而该处的URL服务于它目前指定的一个,li

### 如何安装 @astrale-domains/services？

在项目目录运行 npm install @astrale-domains/services，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 create-astrale-service，可以用 npx create-astrale-service 直接运行。

### @astrale-domains/services 支持 TypeScript 吗？

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

### @astrale-domains/services 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @astrale-domains/services 需要什么版本的 Node\.js？

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

### @astrale-domains/services 可以商用吗？

@astrale-domains/services 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。

### @astrale-domains/services 的下载量有多少？

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

### @astrale-domains/services 还在维护吗？

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