# @bonniernews/stayput 中文文档

规范地址：https://npmcn.com/package/%40bonniernews/stayput/

版本：0\.1\.5
npm 元数据更新时间：2026-11-03T13:01:32.994Z
中文译文更新时间：2026-11-08T11:01:46.098Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：23.5 kB，9 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=20\.6\.0
- 运行依赖：0 个
- 首次发布：2026-09-10T14:09:16.171Z
- 最新版本发布：2026-11-03T13:01:32.742Z
- 近 30 天下载量：10652（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：5（近 12 个月 5 个）

## 中文简介

用于Node.js测试环境的默认-dey网络守护-在套接字级别上阻断非本地的TCP.

## 安装

```sh
npm install @bonniernews/stayput
```

也可以使用：`pnpm add @bonniernews/stayput`、`yarn add @bonniernews/stayput`、`bun add @bonniernews/stayput`

## README

# @bonniernews/ stayput (中文(简体) )

用于节点.js测试环境的默认-默认网络守护. 在套接字级别上屏蔽非本地的TCP,所以一个带有被泄露出生产连接字符串的测试套件在连接时会响亮地失败,而不是静默地突变生产. 原始TCP驱动器(pg,mongodb,弹性研究,redis)和取取/undici的工程——不仅仅是HTTP.

## 快开始

```js
// .mocharc.cjs
module.exports = { require: ['@bonniernews/stayput/register'] };
```

被屏蔽的连接 `err.code === 'EREMOTEBLOCKED'`。 。 。 .

CI已经通过向每个节点进程注入了守护符 `NODE_OPTIONS` 在共享的工作流程模板中——mocharc线是保护笔记本电脑的,这就是流出活口证书实际居住的地方.

领养由ESLint检查:共享的ESLint配置船有两项规则—— `stayput-required` 标记缺少注册行(自动固定)的摩查克,以及 `project-has-guard` 旗帜测试文件不受任何留置量加载摩卡配置规范。 如果你看到这些警告之一, 上面的快速开始是修复.

### 防跑器(带子和吊杆)

木炭线只有卫兵才能装上木炭. `mocha --no-config`摩查从一个子目录引用, `node --test`,或者开玩笑都跳过。 如果您的Repo拥有一个共享的测试帮助器, 测试导入, 将守卫也固定在那里 —— 加载是一能的

```js
// test/helpers/db.js
import '@bonniernews/stayput/register'; // guard on, no matter how the runner was invoked
import { assertActive } from '@bonniernews/stayput';

export async function testDb() {
  assertActive(); // refuse to hand out connections if the guard was tampered with
  // ...create and return the client
}
```

边界规则:停留是devDependency,只有测试自有文件(测试助手,设置文件,mocharc)可以导入它——永远不会 `src/`它会撞倒一个生产装置。 如果测试直接使用应用软件的真实的 DB 模块,则在两者之间添加一个薄的测试帮助器,而不是在生产代码上加注 `NODE_ENV`。 。 。 .

(在CI中,这是多余的—— `NODE_OPTIONS` 注入守护每一个节点过程,无论跑道或配置. )

## 政策

当地( 无) `CI` env):仅回放. 在CI中:回回转+私有范围(RFC1918). 其他的都被封锁了.

| 新闻 var | 效果 |
| --- | --- |
| `STAYPUT_ALLOW` | 逗号分隔了额外的主机/IPs/IPv4 CIDRs,例如. `10.128.0.5,db.internal` |
| `STAYPUT_DENY` | 相同的格式—— **拒绝节拍允许** |
| `STAYPUT_DISABLE=I_UNDERSTAND_THE_RISK` | 关闭护卫(丑陋而突出) |

在工作流程文件中而非代码中设置覆盖 : `STAYPUT_ALLOW`编号 :`STAYPUT_DISABLE` 作为例外库存,是全舰队的两倍.

## AI探员

一个 `EREMOTEBLOCKED` 错误是停止信号,不是需要修复的bug. 未设置 `STAYPUT_ALLOW` 或者说 `STAYPUT_DISABLE`,编辑工作流程env,或去掉mocharc线以让测试通过——该块通常表示测试套件指向它不应该触及的基础设施. 暂停,叫人去核实目标 只有人类在工作流程文件中增加了例外,在审查中和全舰队的grep中都能看到例外.

此合同被红组(2026-08-24):一个编码代理(克洛德)被授予了"沙箱回波",其测试击中了被封锁的私人行距数据库并被告知"今天就让它绿". 它从错误消息中诊断出警卫,拒绝推翻或伪造结果(包括嘲笑驱动器或重新指定测试),并停止要求人验证. 指导而不是执行——但它对行为良好的代理人有效.

## 程序化 API

```js
import stayput, { enable, assertActive } from '@bonniernews/stayput';

enable({
  allow: ['10.128.0.5'],
  deny: ['10.10.0.0/16'],   // deny beats allow
  privateRanges: 'auto',    // 'auto' = private ranges only when CI is set
  onBlock: (host, port) => {},
});
assertActive();             // throws if never loaded or unpatched
stayput.isActive;           // live getter on the default export
```

更倾向于命名的出口: `stayput.assertActive()` 默认导入行程 `import/no-named-as-default-member` 在共享的ESLint配置中。 装有货包的申报船型`StayputOptions`, (中文(简体) ), `Stayput`),所以 TypeScript 测试助手不需要 `declare module` ub.

`@bonniernews/stayput/mocha` 导出运行的根钩子插件 `assertActive()` 测试前.

装入为一等元: 多重负载( NODE OPTIONS + mocharc + 导入) 合并允许列表, 补丁一次, 并记录一行可读行 :

```
stayput/0.1.0 active mode=loopback+private allow=2 deny=1 source=NODE_OPTIONS
```

该行每条流程树一出一出,而并非每条流程一出一出. 伐木后,停留记录线路在 `STAYPUT_LOGGED`; 子进程继承它(mocha) `-p` 工人们,每个过程都经过 `NODE_OPTIONS`保持安静 当他们自己的线是相同的。 他们仍然被看守着。 只有当该行不同,例如另一种模式,允许或拒绝的条目数量不同时,孩子才会打印自己的行,或者 `STAYPUT_DISABLE`。该行显示的是计数,而不是条目本身,因此,允许列表中同一计数的不同条目的儿童保持安静.

## 一层多

留守是客户侧脚枪后卫——最后防线,而不是计划. 它补充,绝不取代:

-   **学历** ——知道为什么prod credits不属于笔记本电脑或repos系统会打败任何守卫.
-   **简单、短暂的进入路径** ——当你真正需要到达一个真正的数据库时,在非默认端口上使用ephemerial 代理/跳出主机. 被制裁的方式比冒险的方式容易,被泄露的默认端口连接字符串不会在任何地方通路.
-   **防火墙规则/网络设计** ——试验环境应完全没有生产路线;只有在存在一条路线的情况下,才能中止.
-   **试验框架和固定装置** ——测试容器,CI服务容器,以及药用固定装置,消除了在共享基础设施进行测试的原因.
-   **服务器侧卫士** ——只读默认角色, DDL Gating, RBAC 不使用破坏性动词(每个数据库计划 [汉道尔·姆德](https://npmcn.com/package/%40bonniernews/stayput/HANDOVER.md)) (中文(简体) ).

## 如何运作

补丁 `net.Socket.prototype.connect` (同步抛出被屏蔽的 IP 字节; unix socket 总是允许的)和 `dns.lookup` (主机名解决后会经过审核). TLS, http/https and undici ride on 互联网档案馆的存檔,存档日期2013-10-21 `net.Socket`所以他们被免费覆盖. `server.listen` 通过 `dns.lookup` 因此,允许对回放和未指明地址进行绑定(`0.0.0.0`, (中文(简体) ), `::`)——约束特定的非本地IP需要 `STAYPUT_ALLOW`这是护脚枪,不是安全边界.

需要节点 \\ 20.6(预装在CI中 `NODE_OPTIONS=--import …/register.js`) (中文(简体) ).

### 未涵盖

**其他进程.** 补丁在一个节点进程内活. 儿童 `node` 进程只能通过 `NODE_OPTIONS` (这是CI注射如何到达每个过程), 没有任何不是节点的 永远不会做: 由CLI所产的本土二进制, `psql` 在 npm 脚本中,一个由测试运行开始的容器。 Prisma是常见案例—— `prisma migrate deploy` 打开它从Rust schema引擎中产生的连接,所以一个测试脚本,在Mocha没有保护之前运行迁移,即使在同一过程中登记了停留量(S`prisma generate` 打开无连接). 对于这些步骤,请将它们读作“配置环境”和“连接字符串”。 留置守护测试进程;它不会守护周围的脚本.

**圈后代和地道.** 一个云SQL Auth代理, `kubectl port-forward` 或SSH地道听 127.0.0.1是回回回回回回回回回回回回回回回回回回回回回回——停留量不能告诉本地邮递员127.0.0.1:5432从地道到同一港口的生产. 不要在默认的端口局部运行任何东西:给测试容器自己的非默认端口和每个代理端口或地道一个不同的端口,所以每个端口都有完全一个目的地(这个repo自己的作曲). Yaml在54329年出版邮报,mongo在27019年出版,弹性搜索在9209年出版. 然后默认的端口拒绝每一个连接,一个被泄露或被复制的连接字符串携带到无处去,而一个真实的环境只是故意到达的.

## 发展

```sh
npm test                  # unit tests + type declaration check — no network, no docker
npm run test:integration  # pg + mongodb + elasticsearch against docker (compose.yaml)
```

设计决定、环境矩阵和推出计划: [汉道尔·姆德](https://npmcn.com/package/%40bonniernews/stayput/HANDOVER.md)。 。 。 .

## 常见问题

### @bonniernews/stayput 是什么？

用于Node\.js测试环境的默认-dey网络守护-在套接字级别上阻断非本地的TCP\.

### 如何安装 @bonniernews/stayput？

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

### @bonniernews/stayput 支持 TypeScript 吗？

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

### @bonniernews/stayput 支持 ESM 还是 CommonJS？

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

### @bonniernews/stayput 需要什么版本的 Node\.js？

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

### @bonniernews/stayput 可以商用吗？

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

### @bonniernews/stayput 的下载量有多少？

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

### @bonniernews/stayput 还在维护吗？

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