# @authhero/multi-tenancy 中文文档

规范地址：https://npmcn.com/package/%40authhero/multi-tenancy/

版本：15\.6\.0
npm 元数据更新时间：2026-11-05T14:41:35.511Z
中文译文更新时间：2026-11-09T20:11:34.360Z
软件包许可：AGPL-3\.0-only

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

原始 npm 页面：https://www.npmjs.com/package/%40authhero/multi-tenancy
原文对照：https://npmcn.com/package/%40authhero/multi-tenancy/?lang=original
项目主页：https://authhero.net/
源码仓库：https://github.com/sesamyab/authhero

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

- 包体积（解压后）：427 kB，115 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：1 个
- peer 依赖：hono ^4\.7\.0，authhero ^9\.27\.0，@hono/zod-openapi ^1\.4\.0，@authhero/adapter-interfaces ^4\.25\.0
- 首次发布：2025-12-05T14:16:33.454Z
- 最新版本发布：2026-11-05T14:41:35.091Z
- 近 30 天下载量：1757（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：92（近 12 个月 92 个）

## 中文简介

为AuthHero提供多租期支助,提供基于组织的出入控制和每租户数据库隔离

## 安装

```sh
npm install @authhero/multi-tenancy
```

也可以使用：`pnpm add @authhero/multi-tenancy`、`yarn add @authhero/multi-tenancy`、`bun add @authhero/multi-tenancy`

## README

# @authhero/多层租房

对AuthHero的多租期支持有基于组织的访问控制,per租期数据库隔离,以及子域路由.

## 特征

-   🔐 **以组织为基础的访问控制** - 控制租户通过JWT标志进入 `org_id` 索赔
-   💾 **数据库隔离** - 拥有D1、Turso或自定义提供者的租户数据库
-   ⚙️ **设置继承** 从主要租户到儿童租户的继承结构
-   🌐 **子域运行** - 自动子域到租户分辨率
-   🔄 **租户生命周期** - 自动提供和解除规定
-   🪝 **可编解结构** - 将多租期特性与AuthHero基套件结合起来
-   📡 **实体同步** - 自动同步资源服务器、角色和从控制平面到所有儿童租户的连接

## 安装

```bash
pnpm add authhero @authhero/multi-tenancy
```

\* 同行依赖情况 `@authhero/multi-tenancy` 需求 `authhero` 作为同伴的依赖。 两个软件包都必须安装. \* :

## 文档

📚 **完整文档**数字 : [https://docs.authhero.net/ 海关化/多租/](https://docs.authhero.net/customization/multi-tenancy/)

-   [建筑](https://docs.authhero.net/customization/multi-tenancy/architecture) - 组织租户模式和象征性准入
-   [数据库隔离](https://docs.authhero.net/customization/multi-tenancy/database-isolation) - 租户数据库
-   [API 参考](https://docs.authhero.net/customization/multi-tenancy/api-reference) - 完成API文档

## 快速启动

```typescript
import { initMultiTenant } from "@authhero/multi-tenancy";
import createAdapters from "@authhero/kysely-adapter";

const dataAdapter = createAdapters(db);

const { app } = initMultiTenant({
  dataAdapter,
  // That's it! Everything else has sensible defaults:
  // - controlPlaneTenantId: "control_plane"
  // - Resource servers, roles, and connections sync enabled
  // - Tenants API mounted at /tenants
  // - Protected synced entities middleware applied
});

export default app;
```

### 自定义

```typescript
const { app } = initMultiTenant({
  dataAdapter,
  controlPlaneTenantId: "main",
  sync: {
    resourceServers: true,
    roles: true,
    connections: false, // Don't sync connections
  },
  defaultPermissions: ["tenant:admin", "tenant:read"],
});
```

### 高级设置

对于更多的控制,请使用下级API:

```typescript
import { init, fetchAll } from "authhero";
import {
  createSyncHooks,
  createTenantsOpenAPIRouter,
  createProtectSyncedMiddleware,
} from "@authhero/multi-tenancy";

const { entityHooks, tenantHooks } = createSyncHooks({
  controlPlaneTenantId: "control_plane",
  getChildTenantIds: async () => {
    /* ... */
  },
  getAdapters: async () => dataAdapter,
  getControlPlaneAdapters: async () => dataAdapter,
});

const tenantsRouter = createTenantsOpenAPIRouter(
  { accessControl: { controlPlaneTenantId: "control_plane" } },
  { tenants: tenantHooks },
);

const { app } = init({
  dataAdapter,
  entityHooks,
  managementApiExtensions: [{ path: "/tenants", router: tenantsRouter }],
});

app.use("/api/v2/*", createProtectSyncedMiddleware());
```

## 关键概念

### 组织-十年模式

一个“主”租户的组织代表和控制儿童租户的进出。 每个组织向一名儿童租户绘制地图.

### 基于脚本的访问

访问通过 `org_id` 以JWT符号提出的索赔:

-   **没有 `org_id`**仅主要租户
-   **与 `org_id`**: 接触匹配的租户

### 静态认证

换租户,向不同的组织申请新的代币:

```typescript
const token = await getAccessTokenSilently({
  authorizationParams: {
    organization: "tenant-id",
  },
});
```

## 资源服务器同步

自动同步资源服务器(API)从主要租户到所有的儿童租户. 当你在主租户上创建,更新或删除一个资源服务器时,它会自动向所有其他租户传播.

```typescript
import { createResourceServerSyncHooks } from "@authhero/multi-tenancy";

const resourceServerHooks = createResourceServerSyncHooks({
  mainTenantId: "main",
  getChildTenantIds: async () => {
    // Return all tenant IDs except the main tenant
    const { tenants } = await adapters.tenants.list();
    return tenants.filter((t) => t.id !== "main").map((t) => t.id);
  },
  getAdapters: async (tenantId) => {
    // Return adapters for the target tenant
    return createAdaptersForTenant(tenantId);
  },
  // Optional: filter which resource servers to sync
  shouldSync: (resourceServer) => {
    // Only sync resource servers that start with "api:"
    return resourceServer.identifier.startsWith("api:");
  },
});

// Use with AuthHero config
const config: AuthHeroConfig = {
  dataAdapter,
  entityHooks: {
    resourceServers: [resourceServerHooks],
  },
};
```

## 移徙指南

### 从遗产设置中移走继承

如果您正在使用被贬损的设置继承功能, 请迁移到新的运行时间倒计时 API :

#### 前(已过期)

```typescript
import {
  withSettingsInheritance,
  SettingsInheritanceConfig,
} from "@authhero/multi-tenancy";

const config: SettingsInheritanceConfig = {
  controlPlaneTenantId: "main",
  controlPlaneClientId: "main-client",
};

const adapters = withSettingsInheritance(baseAdapters, config);
```

#### 后 (当前)

```typescript
import {
  withRuntimeFallback,
  RuntimeFallbackConfig,
} from "@authhero/multi-tenancy";

const config: RuntimeFallbackConfig = {
  controlPlaneTenantId: "main",
  controlPlaneClientId: "main-client",
};

const adapters = withRuntimeFallback(baseAdapters, config);
```

**改变了什么:**

-   `withSettingsInheritance` → `withRuntimeFallback`
-   `createSettingsInheritanceAdapter` → `createRuntimeFallbackAdapter`
-   `SettingsInheritanceConfig` → `RuntimeFallbackConfig`

功能依然相同——这纯粹是命名变化,以更好地反映设置在运行时被继承,而不在租户之间复制数据.

## 许可证

麻省理工学院

## 常见问题

### @authhero/multi-tenancy 是什么？

为AuthHero提供多租期支助,提供基于组织的出入控制和每租户数据库隔离

### 如何安装 @authhero/multi-tenancy？

在项目目录运行 npm install @authhero/multi-tenancy，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：hono（^4\.7\.0）、authhero（^9\.27\.0）、@hono/zod-openapi（^1\.4\.0）、@authhero/adapter-interfaces（^4\.25\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @authhero/multi-tenancy 支持 TypeScript 吗？

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

### @authhero/multi-tenancy 支持 ESM 还是 CommonJS？

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

### @authhero/multi-tenancy 可以商用吗？

@authhero/multi-tenancy 使用 AGPL-3\.0-only 许可。最严格的 Copyleft：除分发外，通过网络向用户提供基于它的服务也需要开源对应源码。闭源 SaaS 使用前务必评估。以上为概括，不构成法律意见，请以许可原文为准。

### @authhero/multi-tenancy 的下载量有多少？

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

### @authhero/multi-tenancy 还在维护吗？

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