# @avallone-io/rls 中文文档

规范地址：https://npmcn.com/package/%40avallone-io/rls/

版本：2\.0\.4
npm 元数据更新时间：2025-05-27T22:00:44.089Z
中文译文更新时间：2026-11-07T07:37:57.846Z
软件包许可：ISC

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

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

弃用说明：Package has moved to type-rls

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

- 包体积（解压后）：213 kB，60 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：4 个
- peer 依赖：typeorm ~0\.3\.0
- 首次发布：2021-06-03T19:26:44.119Z
- 最新版本发布：2023-02-28T21:30:45.782Z
- 近 30 天下载量：3943（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：21（近 12 个月 0 个）

## 中文简介

用于 TypeORM 和 NestJS 的行级安全套件

## 安装

```sh
npm install @avallone-io/rls
```

也可以使用：`pnpm add @avallone-io/rls`、`yarn add @avallone-io/rls`、`bun add @avallone-io/rls`

## README

[![Build And Test](https://github.com/Avallone-io/rls/actions/workflows/build-and-test.yml/badge.svg?branch=master)](https://github.com/Avallone-io/rls/actions/workflows/build-and-test.yml) [![.github/workflows/release.yml](https://github.com/Avallone-io/rls/actions/workflows/release.yml/badge.svg?branch=master)](https://github.com/Avallone-io/rls/actions/workflows/release.yml)

# 说明

用于 NestJS 和 TypeORM 的行级安全实用软件包.

此解决方案无法通过多个连接到数据库(例如:一个连接/租户)来实现. 相反,这一解决方案通过应用RLS数据库政策来发挥作用,如以下所述: [这篇博客文章](https://aws.amazon.com/blogs/database/multi-tenant-data-isolation-with-postgresql-row-level-security/) (在 **_替代办法_**) (中文(简体) ).

# 安装

> npm 安装@ avallone- io/ rls

# 使用量

要创建 RLSConnection 实例, 您需要与 db 的原始连接 。 按常规设置打字机配置, 然后将其连接包成一个 **RLSC 连接** 例如,针对每项请求.

这将运行一个 `set "rls.tenant_id"` 财务报告和审定财务报表 `set "rls.actor_id"` 对于每个请求,并在查询执行后重新设置.

* * *

**RLS 政策**

您的数据库政策将 **必须** 使用 `rls.tenant_id` 财务报告和审定财务报表 `rls.actor_id` 为了实施隔离。 政策实例:

```sql
CREATE POLICY tenant_isolation ON public."category" for ALL
USING ("tenant_id" = current_setting('rls.tenant_id'))
with check ("tenant_id" = current_setting('rls.tenant_id'));
```

* * *

## 运通/韩国

例如,假设明示申请:

```typescript
app.use((req, res, next) => {
  const dataSource = await new DataSource({...}).initialize(); // create a datasource and initialize it

  // get tenantId and actorId from somewhere (headers/token etc)
  const rlsConnection = new RLSConnection(dataSource, {
    actorId,
    tenantId,
  });

  res.locals.connection = rlsConnection;
  next();
});

// your handlers
const userRepo = res.locals.connection.getRepository(User);
await userRepo.find(); // will return only the results where the db rls policy applies
```

在上述例子中,您必须配合所提供的连接. 直接调用 TypeORM 函数将和没有意识到的原始数据源对象一起工作.

## 雀巢JS一体化

如果您正在使用 NestJS , 这个库会提供帮助, 帮助您了解您的连接和询问租户 .

创建您的 TypeORM 配置并使用 TypeORM 模块加载 `.forRoot`\- 那你得装上 `RLSModule` 与 `.forRoot` 在那里你将定义 在哪里拿 `tenantId` 财务报告和审定财务报表 `actorId` 从. 第二部分是,你现在需要替换 `TypeOrmModule.forFeature` 与 `RLSModule.forFeature`这应该是1比1的替换. 您可以输入非实体依赖模块和提供者。 第一个数组导入模块,第二个数组注入提供者.

使用时 `RLSModule.forRoot` 它会设置你的 `scope` 改为 `REQUEST`确定您理解这个计划的意义, 特别是阅读关于请求范围验证策略的内容 [雀巢文件](https://docs.nestjs.com/security/authentication#request-scoped-strategies)。 。 。 .

这个 `RLSModule.forRoot` 接受工厂的乐趣作为合成或非合成功能.

```typescript
app.controller.ts

@Module({
  imports: [
    TypeOrmModule.forRoot(...),
    RLSModule.forRoot([/*Module*/], [/*Service*/], async (req: Request, /*serviceInstance*/) => {
      // You can take the tenantId and actorId from headers/tokens etc
      const tenantId = req.headers['tenant_id'];
      const actorId = req.headers['actor_id'];

      return {
        actorId,
        tenantId,
      };
    }),
    RLSModule.forFeature([Post, Category]) // <- this
  ],
  controllers: [AppController],
  providers: [AppService],
})
export class AppModule {}
```

现在您可以使用正常的模块注入,用于寄存器,服务等.

要在服务中注入 RLS 连接, 您可以使用 `@Inject(TENANT_CONNECTION)` 地点 `TENANT_CONNECTION` 从 `@avallone-io/rls`。 。 。 .

```typescript
export class AppService {
  constructor(
    @InjectRepository(Category)
    private categoryRepo: Repository<Category>,
    @Inject(TENANT_CONNECTION)
    private connection: RLSConnection,
  ) {}

  // you can now use categoryRepo as normal but it will
  // be scoped for RLS. Same with the connection.
}
```

相同,不直接使用来自 `dataSource` 因为它会给你与数据库的默认连接,而不是被包裹的实例.

详情请查看 `test/nestjs/src`。 。 。 .

# 类型器 >v0.3.0

自打字机v0.3.0起,连接类被"数据源"所取代. 这个模块仍然使用连接作为其语言,现在也有助于区分实际数据库连接(typeorm Data Source)和RLS slapper(RLSConnection). 但是,如果想与打字机绝地游戏等同,则有别名用于 `RLSConnection` 调用 `RLSDataSource`。 。 。 .

## 常见问题

### @avallone-io/rls 是什么？

用于 TypeORM 和 NestJS 的行级安全套件注意：该包已被作者标记为弃用——Package has moved to type-rls

### 如何安装 @avallone-io/rls？

在项目目录运行 npm install @avallone-io/rls，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：typeorm（~0\.3\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @avallone-io/rls 支持 TypeScript 吗？

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

### @avallone-io/rls 支持 ESM 还是 CommonJS？

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

### @avallone-io/rls 可以商用吗？

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

### @avallone-io/rls 的下载量有多少？

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

### @avallone-io/rls 还在维护吗？

最新版本 2\.0\.4 发布于 2023/03/01（3 年前）；至今共发布 21 个版本，其中过去 12 个月发布了 0 个；首次发布于 2021/06/04。作者已将其标记为弃用，新项目建议寻找替代方案。