Dify 手动创建租户指南：后台数据库与密钥配置详解

前言：为何需要手动创建 Dify 工作空间？

通常情况下，Dify 的工作空间（或称“租户”）是通过其图形化界面创建的。但在某些特定场景下，例如进行自动化部署、批量创建租户、数据迁移或在无前端界面的服务器环境中进行管理时，直接通过数据库和命令行手动创建工作空间就成了一种高效的解决方案。

本指南将详细介绍如何一步步手动创建 Dify 工作空间。在开始之前，请确保你已具备以下条件：

• 对 Dify 后端服务器的文件系统有读写权限。
• 能够访问 Dify 的 PostgreSQL 数据库。
• 系统中安装了 OpenSSL 命令行工具。

步骤一：准备并插入数据库记录

创建新工作空间的核心是向数据库中添加两条关键记录：一条在 tenants 表中定义新租户，另一条在 tenant_account_joins 表中将租户与一个现有账户关联起来。

1. 获取 account_id

首先，你需要一个用户账户来作为新工作空间的所有者。这个账户的 ID，即 account_id，是后续操作的基础。你可以通过查询 accounts 表来获取一个现有用户的 ID。

例如，通过邮箱查找用户的 account_id：

SELECT id FROM accounts WHERE email = 'user@example.com';

记下查询到的 UUID 格式的 account_id。

2. 插入租户与关联记录

获取 account_id 后，执行以下 SQL 语句来创建新的租户并建立关联。请将语句中的占位符替换为你的实际值。

• tenants 表: 定义工作空间的基本信息。
• tenant_account_joins 表: 将指定账户设为该工作空间的 “OWNER”。

-- 向 tenants 表插入新工作空间记录，将 'My New Workspace' 替换为你的工作空间名称
INSERT INTO tenants (id, name, plan, status, created_at, updated_at) 
VALUES (uuid_generate_v4(), 'My New Workspace', 'professional', 'active', now(), now())
RETURNING id; -- 执行后会返回新生成的 tenant_id，请务必记下它
-- 向 tenant_account_joins 表插入关联记录
-- 将 '<the_tenant_id_from_above>' 替换为上一步返回的 tenant_id
-- 将 '<your_account_id>' 替换为你在 1.1 节获取的 account_id
INSERT INTO tenant_account_joins (tenant_id, account_id, role, created_at, updated_at) 
VALUES ('<the_tenant_id_from_above>', '<your_account_id>', 'owner', now(), now());

执行第一条 INSERT 命令后，数据库会返回一个新生成的 tenant_id。这个 ID 至关重要，请务必复制并保存好，后续所有步骤都将围绕它展开。

附：数据表结构参考

tenants 表结构

tenant_account_joins 表结构

附：角色与状态说明

租户账号角色 (role)

账号状态 (status)

步骤二：生成 RSA 密钥对

每个工作空间都需要一对 RSA 密钥用于数据加密。这包括一个私钥和一个公钥。

1. 生成私钥

执行以下 OpenSSL 命令来生成一个 2048 位的 RSA 私钥，并将其保存为 private.pem 文件。genpkey 是推荐的现代命令，它通过 -algorithm 参数指定算法为 RSA，并通过 -pkeyopt 设置密钥长度。

openssl genpkey -algorithm RSA -out private.pem -pkeyopt rsa_keygen_bits:2048

2. 提取公钥

接下来，从刚刚生成的私钥 private.pem 中提取出对应的公钥，并保存到 public.pem 文件。rsa 子命令配合 -pubout 选项专门用于此目的。

openssl rsa -pubout -in private.pem -out public.pem

执行完毕后，你将得到 private.pem（私钥）和 public.pem（公钥）两个文件。

步骤三：将公钥更新至数据库

打开 public.pem 文件，复制其中 -----BEGIN PUBLIC KEY----- 和 -----END PUBLIC KEY----- 之间的全部内容。然后，使用这个公钥字符串更新 tenants 表中对应租户的 encrypt_public_key 字段。

执行以下 SQL 命令，记得替换占位符：

-- 将 '<the_tenant_id_from_step_1>' 替换为第一步中记下的 tenant_id
-- 将 '<your_public_key_string>' 替换为你复制的公钥内容
UPDATE tenants 
SET encrypt_public_key = '<your_public_key_string>' 
WHERE id = '<the_tenant_id_from_step_1>';

步骤四：部署私钥文件

最后一步是将生成的私钥文件 private.pem 放置到 Dify 后端应用期望的目录结构中。Dify 会根据租户 ID 动态加载对应的私钥。

将 private.pem 文件移动或复制到以下路径：

dify/api/privkeys/{tenant_id}/private.pem

请将 {tenant_id} 替换为你在第一步中获得的实际 tenant_id。如果 privkeys 目录下不存在以你的 tenant_id 命名的文件夹，你需要手动创建它。

为了安全起见，强烈建议设置私钥文件的访问权限，确保只有运行 Dify 服务的用户可以读取它：

chmod 600 dify/api/privkeys/{tenant_id}/private.pem

完成以上所有步骤后，新的工作空间便已成功创建并配置完毕。