# @castleio/sdk 中文文档

规范地址：https://npmcn.com/package/%40castleio/sdk/

版本：3\.2\.0
npm 元数据更新时间：2026-09-08T12:34:49.257Z
中文译文更新时间：2026-11-09T04:18:20.138Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40castleio/sdk
原文对照：https://npmcn.com/package/%40castleio/sdk/?lang=original
项目主页：https://github.com/castle/castle-node
源码仓库：https://github.com/castle/castle-node

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

- 包体积（解压后）：361 kB，9 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=20
- 运行依赖：2 个
- 首次发布：2018-12-20T09:54:13.295Z
- 最新版本发布：2026-09-08T12:34:48.997Z
- 近 30 天下载量：49528（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：29（近 12 个月 3 个）

## 中文简介

节点的SDK城堡

## 安装

```sh
npm install @castleio/sdk
```

也可以使用：`pnpm add @castleio/sdk`、`yarn add @castleio/sdk`、`bun add @castleio/sdk`

## README

# 节点的SDK城堡

[![Test](https://github.com/castle/castle-node/actions/workflows/test.yml/badge.svg)](https://github.com/castle/castle-node/actions/workflows/test.yml) [![Lint](https://github.com/castle/castle-node/actions/workflows/lint.yml/badge.svg)](https://github.com/castle/castle-node/actions/workflows/lint.yml) [![npm version](https://img.shields.io/npm/v/@castleio/sdk.svg)](https://www.npmjs.com/package/@castleio/sdk)

官方节点Js SDK为 [城堡](https://castle.io/). Castle分析网络和移动应用程序中的用户行为,以便在欺诈发生前停止.

这个包裹是薄薄的依赖性灯光包裹 [城堡 HTTP API](https://reference.castle.io/)它揭露:

-   **风险评估** —— 说 `POST /v1/risk`, (中文(简体) ), `POST /v1/filter`
-   **事件记录** —— 说 `POST /v1/log` (火与忘,无判决
-   **列表项目( L)** —完整 CRUD + 搜索 + 计数 + 批次
-   **隐私/ GDPR** —— 说 `POST` 财务报告和审定财务报表 `DELETE /v1/privacy/users` (第15和17条)
-   **活动** (企业)——搜索、小组和计划
-   **Webhook 签名验证** - 验证 `X-Castle-Signature`
-   **安全模式** – 从浏览器发送的签名用户ID

每一有效载荷的受支持事件和JSON形状的完整清单记录在 [https://reference.castle.io 页面存档备份,存于互联网档案馆](https://reference.castle.io/)。 。 。 .

## 所需资源

-   节点.js `>= 20` (SDK使用内置全球 `fetch` 编号 : `AbortSignal`(中文(简体) )
-   A 类 [城堡](https://dashboard.castle.io/) API 秘密

一揽子船舶,包括无害环境管理和共同JS,因此 `import` 财务报告和审定财务报表 `require` 工作从盒子.

## 安装

```bash
npm install --save @castleio/sdk
```

```bash
yarn add @castleio/sdk
```

## 快开始

```js
import { Castle, ContextPrepareService } from '@castleio/sdk';

const castle = new Castle({ apiSecret: process.env.CASTLE_API_SECRET });

const context = ContextPrepareService.call(
  req,
  undefined,
  castle.configuration
);

const verdict = await castle.risk({
  type: '$login',
  status: '$succeeded',
  request_token: req.body.castle_request_token,
  user: { id: '12345', email: 'user@example.com' },
  context,
});

switch (verdict.policy?.action) {
  case 'deny':
    // block the user
    break;
  case 'challenge':
    // send 2FA / additional verification
    break;
  default:
  // allow
}
```

带有 commonJS :

```js
const { Castle, ContextPrepareService } = require('@castleio/sdk');
```

`ContextPrepareService.call(request, options, configuration)` 从节点提取 Castle 所需的 IP 和信头 `request` 对象。 见 [高级配置](https://npmcn.com/package/%40castleio/sdk/#readme-advanced-configuration) 用于解析页眉允许/拒绝列表和代理链.

## 配置

库配置为每个 `Castle` 实例:

```js
import { Castle, FailoverStrategy } from '@castleio/sdk';

const castle = new Castle({
  apiSecret: process.env.CASTLE_API_SECRET,

  // Automatic verdict from `risk`/`filter` when Castle is unreachable or
  // times out. One of FailoverStrategy.allow (default), .deny, .challenge.
  failoverStrategy: FailoverStrategy.allow,

  // Request timeout in milliseconds before the failover strategy kicks in.
  timeout: 1500,

  // Logs Castle API requests and responses; must respond to `info`.
  logger: console,
});
```

### 配置选项

| 选项 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `apiSecret` | `string` |  | API 密码 [仪表板](https://dashboard.castle.io/settings/general)。 。 。 . |
| `timeout` | `number` | `1500` | 返回故障策略前的时间为毫秒. |
| `failoverStrategy` | `FailoverStrategy` | `FailoverStrategy.allow` | 自动 `risk` 超时响应 : `allow`, (中文(简体) ), `deny`,或 `challenge`。 。 。 . |
| `logger` | `object` |  | 日志 Castle API 请求/答复;必须响应 `info`。 。 。 . |
| `doNotTrack` | `boolean` | `false` | 何时 `true`并触发失败 `risk`在开发和测试方面很有用. |
| `allowlisted` | `string[]` | `[]` | 严格的页眉允许列表(参见 [页眉允许/ 拒绝列表](https://npmcn.com/package/%40castleio/sdk/#readme-header-allowdeny-lists)) (中文(简体) ). |
| `denylisted` | `string[]` | `[]` | 除了总是被堵住的外, 总是要擦去的 `Cookie` 编号 : `Authorization`。 。 。 . |
| `ipHeaders` | `string[]` | `[]` | 自定义读取客户端 IP 的标题( 见 [客户端IP检测](https://npmcn.com/package/%40castleio/sdk/#readme-client-ip-detection)) (中文(简体) ). |
| `trustedProxies` | `(string | RegExp)[]` | `[]` | 已知代理IP (字符串或 regexes). 挑这个 **或者说** `trustedProxyDepth`从来没有两者. |
| `trustedProxyDepth` | `number` | `0` | 链中已知的可信任代理数 。 挑这个 **或者说** `trustedProxies`从来没有两者. |
| `trustProxyChain` | `boolean` | `false` | 相信整个人 `X-Forwarded-For` 链条. **警告:** 滥交——恶意代理可以骗取客户IP. |
| `baseUrl` | `string` | `https://api.castle.io/v1` | 基地城堡 API URL. |

### 多环境/多租户

每个 `Castle` 所以多重环境或租户只是多重情况:

```js
const castleTenantA = new Castle({
  apiSecret: process.env.CASTLE_API_SECRET_TENANT_A,
});
const castleTenantB = new Castle({
  apiSecret: process.env.CASTLE_API_SECRET_TENANT_B,
});
```

## 使用量

所有端点都是在 a 上的同步方法 `Castle` 举个例子.

### 风险

评价高风险事件(记录、登记、密码重置、交易)。 返回判决(`policy.action`加上风险分数和信号.

```js
await castle.risk({
  type: '$login',
  status: '$succeeded',
  request_token: req.body.castle_request_token,
  user: { id: '12345', email: 'user@example.com' },
  context,
});
```

### 过滤器

链条早期的阻塞bots和不良流量(典型的注册). 反应形状与"风险"相同.

```js
await castle.filter({
  type: '$registration',
  status: '$attempted',
  request_token: req.body.castle_request_token,
  params: { email: 'user@example.com' },
  context,
});
```

### 日志

火灾和遗忘事件记录;没有判决。 对在仪表板上应该可见但不需要实时决定的事件有用.

```js
await castle.log({
  type: '$profile_update',
  status: '$succeeded',
  user: { id: '12345' },
  context,
});
```

### 列表项目( L)

列表允许您组织用户、IP、交易或任何自定义属性,并在允许/拒绝列表时将其用于策略:

```js
const list = await castle.createList({
  name: 'Trusted IPs',
  color: 'green',
  primary_field: 'ip.address',
});

await castle.createListItem({
  list_id: list.id,
  primary_value: '1.2.3.4',
  author: { type: '$analyst_email', identifier: 'analyst@example.com' },
});

await castle.searchListItems({
  list_id: list.id,
  filters: [{ field: 'primary_value', op: '$eq', value: '1.2.3.4' }],
});
```

可用方法: `createList`, (中文(简体) ), `fetchAllLists`, (中文(简体) ), `fetchList`, (中文(简体) ), `updateList`, (中文(简体) ), `deleteList`, (中文(简体) ), `searchLists`, (中文(简体) ), `createListItem`, (中文(简体) ), `batchUpdateListItems`, (中文(简体) ), `fetchListItem`, (中文(简体) ), `searchListItems`, (中文(简体) ), `countListItems`, (中文(简体) ), `updateListItem`, (中文(简体) ), `archiveListItem`, (中文(简体) ), `unarchiveListItem`。 。 。 .

### 隐私( GDPR)

第15条(使用权)和第17条(被遗忘的权利) `/v1/privacy/users`。两者都使用 `identifier` 财务报告和审定财务报表 `identifier_type` (单位:千美元)`$id` 或者说 `$email`:

```js
await castle.requestUserData({
  identifier: 'rhea@example.org',
  identifier_type: '$email',
});

await castle.deleteUserData({
  identifier: 'user_42',
  identifier_type: '$id',
});
```

### 活动(企业)

查询,组,并检查存储事件的计划. 使用 `queryEvents`, (中文(简体) ), `groupEvents`,以及 `eventsSchema`数字 :

```js
await castle.queryEvents({
  filters: [
    /* ... */
  ],
});
await castle.groupEvents({
  filters: [],
  group_by: { fields: [] },
  columns: [],
});
await castle.eventsSchema();
```

`searchEvents` 财务报告和审定财务报表 `getEventsSchema` 也可作为以下的别名: `queryEvents` 财务报告和审定财务报表 `eventsSchema`。 。 。 .

### Webhook 签名验证

城堡在每一个网页上标出 `X-Castle-Signature` 头曰. 对照 **原始内容** 在信任有效载荷之前先请求机体—— `verifyWebhookSignature` 丢出一个 `WebhookVerificationError` 不匹配时 :

```js
import express from 'express';
import { WebhookVerificationError } from '@castleio/sdk';

const app = express();

// The signature is computed over the raw body, so capture it as a Buffer.
app.post(
  '/castle/webhooks',
  express.raw({ type: 'application/json' }),
  (req, res) => {
    try {
      castle.verifyWebhookSignature(req.body, req.get('x-castle-signature'));
    } catch (err) {
      if (err instanceof WebhookVerificationError) {
        return res.sendStatus(400);
      }
      throw err;
    }

    const event = JSON.parse(req.body.toString());
    // signature is valid; proceed
    res.sendStatus(200);
  }
);
```

### 安全模式

安全模式在用户ID服务器侧上签名,这样在浏览器中不能被篡改. 将签名传递给客户端 `castle.js` SDK: (英语)

```js
const signature = castle.secureModeSignature('user_123');
```

签名是用你的API 密钥键入的用户代号HMAC-SHA256的十六进制.

## 高级配置

默认对大多数部署都有好处. 以下选项仅在您有非三角代理链或严格的标题政策时才重要 .

### 页眉允许/ 拒绝列表

默认情况下, SDK 发送每个 HTTP 信头, 除非 `Cookie` 财务报告和审定财务报表 `Authorization`Castle用这些信头来打印请求,所以越广越好.

```js
import { DEFAULT_ALLOWLIST } from '@castleio/sdk';

const castle = new Castle({
  apiSecret: process.env.CASTLE_API_SECRET,

  // Always-blocked headers (in addition to Cookie/Authorization).
  denylisted: ['X-Internal-Header'],

  // Strict allow-list mode. Headers outside the list are sent with scrubbed
  // values, except User-Agent which is always preserved. If you must use an
  // allow list, we recommend starting from the curated default.
  allowlisted: DEFAULT_ALLOWLIST,
});
```

页眉名称对大小写不敏感并接受两者 `_` 财务报告和审定财务报表 `-` 作为分离者。 领先 `HTTP_` 前缀自动被剥去.

### 客户端IP检测

Castle需要原始客户端IP,而不是您的代理机或负载平衡器的IP. SDK读取 `X-Forwarded-For` 财务报告和审定财务报表 `Remote-Addr` 默认; 选择 **一个** 以下战略取决于您的基础设施:

```js
const castle = new Castle({
  apiSecret: process.env.CASTLE_API_SECRET,

  // 1. Custom header (e.g. Cloudflare's Cf-Connecting-Ip).
  ipHeaders: ['Cf-Connecting-Ip'],

  // 2. Static, known proxy IPs.
  trustedProxies: ['10.0.0.1'],

  // 3. Ephemeral proxies but known chain depth.
  trustedProxyDepth: 2,

  // 4. Last resort: trust the entire X-Forwarded-For chain.
  // Warning: vulnerable to header spoofing if a malicious proxy is in path.
  trustProxyChain: false,
});
```

选择 **无论是** `trustedProxies` **或者说** `trustedProxyDepth`从来没有两者。 导出中的私密/后退范围 `TRUSTED_PROXIES` 常数总是被认为是信任的.

## 错误

所有 HTTP/API 例外继承自 `APIError`。 。 。 . `ConfigurationError` (设置问题)和 `WebhookVerificationError` (webhook 签名不匹配) 延伸 `Error` 直接说 最有用的是:

| 类 | 升起时 |
| --- | --- |
| `ConfigurationError` | SDK的配置错误(缺少API秘密,糟糕的URL). |
| `BadRequestError` | `400` 反应. |
| `UnauthorizedError` | `401` 糟糕的API秘诀. |
| `ForbiddenError` | `403` 反应. |
| `NotFoundError` | `404` 反应. |
| `InvalidParametersError` | `422` 附有验证细节的答复. |
| `InvalidRequestTokenError` | `422` - 那个 `request_token` 缺少或无效. |
| `RateLimitError` | `429` ——退后再试. |
| `PaymentRequiredError` | `402` 反应. |
| `InternalServerError` | `5xx` 卡塞尔的回复. |
| `WebhookVerificationError` | 网签不符 . |

完整名单中 [`src/errors.ts`](https://npmcn.com/package/%40castleio/sdk/src/errors.ts)。 。 。 .

## 升级到 3. 0

`3.0.0` 是一种现代化的释放。 公众API(公共 `Castle` 分类及其分类 方法)是不变的——大多数项目可以升级而无需更改代码.

改变了什么:

-   **遗产终点被移除 .** `authenticate`, (中文(简体) ), `track`设备 结束点( e)`getDevice`, (中文(简体) ), `getDevicesForUser`, (中文(简体) ), `approveDevice`, (中文(简体) ), `reportDevice`(中文(简体) ) 已经消失——使用 `risk`, (中文(简体) ), `filter`,以及 `log` 换句话说 匹配的有效载荷类型 (单位:千美元)`Payload`, (中文(简体) ), `DevicePayload`, (中文(简体) ), `UserDevicePayload`, (中文(简体) ), `AuthenticateResult`曾经 也删除了.
    -   如果您以前使用过 `reportDevice` 编号 : `approveDevice`,管理设备 核准和报告 **列表 API** 相反(例如:. `createListItem` 编号 : `archiveListItem`) (中文(简体) ). 见 [使用清单的报告装置](https://docs.castle.io/docs/reporting-devices-using-lists)。 。 。 .
-   **节点.js `>= 20` 现在需要.** SDK使用运行时间的内置 `fetch` 财务报告和审定财务报表 `AbortSignal` 改为 `node-fetch` 编号 : `abort-controller`,哪个 不再是依赖关系.
-   **建立双重无害环境管理+共同JS.** 包裹现在暴露出一个合适的 `exports` 地图 单独 `import` 财务报告和审定财务报表 `require` 出入口和类型定义。 深处 进口 `dist/` 从未被支持,并且始终不支持; 从 软件包根 (`@castleio/sdk`) (中文(简体) ).
-   这个 `lodash.*` 微依赖性被取消,以有利于本地的JavaScript; 这是内部的,不影响行为.

如果您先前依赖的是习惯 `overrideFetch`,它仍然工作——通过任何 `fetch`\- 兼容的执行.

## 许可证

根据《公约》条款作为公开源码提供 [MIT 许可证](https://npmcn.com/package/%40castleio/sdk/LICENSE)。 。 。 .

## 常见问题

### @castleio/sdk 是什么？

节点的SDK城堡

### 如何安装 @castleio/sdk？

在项目目录运行 npm install @castleio/sdk，或使用 pnpm add / yarn add / bun add。

### @castleio/sdk 支持 TypeScript 吗？

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

### @castleio/sdk 支持 ESM 还是 CommonJS？

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

### @castleio/sdk 需要什么版本的 Node\.js？

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

### @castleio/sdk 可以商用吗？

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

### @castleio/sdk 的下载量有多少？

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

### @castleio/sdk 还在维护吗？

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