# Dify 用户注册及添加成员指南

  

本文档详细说明 Dify 自部署版本中用户注册和添加成员的各种方法及配置。

  

## 目录

  

- [用户注册方式](#用户注册方式)

  - [方式一：邮箱注册](#方式一邮箱注册)

  - [方式二：通过邀请链接注册](#方式二通过邀请链接注册)

  - [方式三：OAuth 第三方登录注册](#方式三oauth-第三方登录注册)

- [添加成员到工作空间](#添加成员到工作空间)

  - [方法一：通过邮箱邀请（推荐）](#方法一通过邮箱邀请推荐)

  - [方法二：通过账号 ID 手动添加](#方法二通过账号-id-手动添加)

- [配置说明](#配置说明)

  - [启用注册功能](#启用注册功能)

  - [配置邮件服务](#配置邮件服务)

  - [常见邮件服务商配置示例](#常见邮件服务商配置示例)

- [常见问题](#常见问题)

- [附录](#附录)

  

---

  

## 用户注册方式

  

### 方式一：邮箱注册

  

#### 前提条件

  

1. **启用注册功能**：配置 `ALLOW_REGISTER=true`

2. **配置邮件服务**：必须配置 SMTP 或 Resend/SendGrid 等邮件服务

3. **启用邮箱登录**：需要启用邮箱密码登录或邮箱验证码登录

  

#### 注册流程

  

1. **访问注册页面**

   - 在登录页面点击"注册"链接

   - 或直接访问：`http://your-domain/signup`

  

2. **输入邮箱地址**

   - 在注册页面输入有效的邮箱地址

   - 系统会自动发送验证码邮件到该邮箱

  

3. **验证邮箱**

   - 进入验证码页面：`/signup/check-code`

   - 输入收到的 6 位数字验证码

   - 验证通过后进入设置密码页面

  

4. **设置密码**

   - 在 `/signup/set-password` 页面设置账户密码

   - **密码要求**：

     - 至少 8 位字符

     - 包含大小写字母

     - 包含数字

     - 包含特殊字符

   - 确认密码后完成注册

   - 系统会自动创建个人工作空间

  

#### 相关代码位置

  

- 注册 API：`api/controllers/console/auth/email_register.py`

- 注册前端页面：`web/app/signup/`

  

---

  

### 方式二：通过邀请链接注册

  

#### 适用场景

  

当管理员需要邀请新用户加入工作空间时，可以通过发送邀请邮件的方式，用户通过邮件中的链接完成注册并加入工作空间。

  

#### 注册流程

  

1. **接收邀请邮件**

   - 管理员在工作空间成员管理中发送邀请

   - 被邀请人收到包含激活链接的邮件

  

2. **点击激活链接**

   - 打开邮件中的激活链接

   - 如果已有账户，直接加入工作空间

   - 如果没有账户，系统会引导完成注册流程

  

3. **完成注册**

   - 按照提示设置密码或验证邮箱

   - 注册完成后自动加入对应的工作空间

  

#### 注意事项

  

- 邀请链接有时效性（默认 72 小时）

- 需要确保邮件服务配置正确，否则无法发送邀请邮件

  

---

  

### 方式三：OAuth 第三方登录注册

  

#### 适用场景

  

如果配置了 OAuth 登录（如 Google、GitHub、Microsoft 等），用户可以通过第三方账号登录，系统会自动创建账户。

  

#### 配置要求

  

需要配置相应的 OAuth 提供商信息。

  

#### 注册流程

  

1. 在登录页面选择第三方登录方式

2. 跳转到第三方登录页面进行授权

3. 授权成功后自动创建账户并登录

  

---

  

## 添加成员到工作空间

  

### 方法一：通过邮箱邀请（推荐）

  

#### 操作步骤

  

1. **进入成员管理**

   - 登录 Dify 控制台

   - 进入「设置」→「成员管理」

  

2. **发送邀请**

   - 点击「邀请成员」按钮

   - 输入被邀请人的邮箱地址（可多个）

   - 选择成员角色（normal、admin、editor、dataset_operator）

   - 点击「发送邀请」

  

3. **被邀请人操作**

   - 被邀请人收到邀请邮件

   - 点击邮件中的激活链接

   - 如果已有账户，直接加入工作空间

   - 如果没有账户，完成注册后自动加入

  

#### 前提条件

  

- **必须配置邮件服务**，否则无法发送邀请邮件

- 工作空间成员数量未达到限制

  

#### 相关代码位置

  

- 邀请 API：`api/controllers/console/workspace/members.py`

- 前端组件：`web/app/components/header/account-setting/members-page/`

  

---

  

### 方法二：通过账号 ID 手动添加

  

#### 适用场景

  

当邮件服务未配置或无法发送邮件时，可以通过账号 ID 直接添加已注册的用户到工作空间。

  

#### 方法 2.1：通过数据库直接添加（临时方案）

  

**⚠️ 警告：直接操作数据库有风险，请谨慎操作！**

  

1. **查找用户账号 ID**

   ```sql

   -- 连接数据库

   -- 查询用户信息

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

   ```

  

2. **添加成员到工作空间**

   ```sql

   -- 假设：

   -- 账号 ID: 'user-account-id'

   -- 工作空间 ID: 'workspace-id'（可通过 SELECT id, name FROM tenants 查询）

   -- 角色: 'normal'（可选值：normal, admin, editor, dataset_operator, owner）

   INSERT INTO tenant_account_joins (tenant_id, account_id, role, current, created_at, updated_at)

   VALUES ('workspace-id', 'user-account-id', 'normal', false, NOW(), NOW())

   ON CONFLICT (tenant_id, account_id) DO NOTHING;

   ```

  

3. **验证添加结果**

   ```sql

   -- 查询工作空间成员

   SELECT a.email, a.name, taj.role

   FROM tenant_account_joins taj

   JOIN accounts a ON taj.account_id = a.id

   WHERE taj.tenant_id = 'workspace-id';

   ```

  

#### 方法 2.2：创建 API 端点（推荐）

  

创建一个新的 API 端点来支持通过账号 ID 添加成员。

  

**实现步骤：**

  

1. **修改 `api/controllers/console/workspace/members.py`**

  

   在文件末尾添加以下代码：

  

   ```python

   class MemberAddByAccountIdPayload(BaseModel):

       account_id: str = Field(..., description="Account ID")

       role: TenantAccountRole

  

   reg(MemberAddByAccountIdPayload)

  

   @console_ns.route("/workspaces/current/members/add-by-account-id")

   class MemberAddByAccountIdApi(Resource):

       """Add a member by account ID."""

  

       @console_ns.expect(console_ns.models[MemberAddByAccountIdPayload.__name__])

       @setup_required

       @login_required

       @account_initialization_required

       @cloud_edition_billing_resource_check("members")

       def post(self):

           payload = console_ns.payload or {}

           args = MemberAddByAccountIdPayload.model_validate(payload)

           current_user, _ = current_account_with_tenant()

           if not current_user.current_tenant:

               raise ValueError("No current tenant")

           # 查找账号

           account = db.session.get(Account, args.account_id)

           if not account:

               return {"code": "account-not-found", "message": "Account not found"}, 404

           # 检查是否已在工作空间中

           existing_join = db.session.query(TenantAccountJoin).filter_by(

               tenant_id=current_user.current_tenant.id,

               account_id=args.account_id

           ).first()

           if existing_join:

               return {"code": "already-member", "message": "Account is already a member"}, 400

           # 检查工作空间成员限制

           workspace_members = FeatureService.get_features(tenant_id=current_user.current_tenant.id).workspace_members

           if not workspace_members.is_available(1):

               raise WorkspaceMembersLimitExceeded()

           # 添加成员

           try:

               TenantService.create_tenant_member(

                   current_user.current_tenant,

                   account,

                   role=args.role.value

               )

               return {

                   "result": "success",

                   "account_id": args.account_id,

                   "tenant_id": str(current_user.current_tenant.id)

               }, 201

           except Exception as e:

               return {"code": "error", "message": str(e)}, 500

   ```

  

2. **使用 API 添加成员**

  

   ```bash

   # 使用 curl 调用 API

   curl -X POST "http://your-domain/api/console/workspaces/current/members/add-by-account-id" \

     -H "Content-Type: application/json" \

     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \

     -d '{

       "account_id": "user-account-id",

       "role": "normal"

     }'

   ```

  

3. **获取账号 ID 的方法**

  

   - 通过数据库查询（见方法 2.1）

   - 通过用户个人资料 API 获取

   - 通过管理员后台查看

  

---

  

## 配置说明

  

### 启用注册功能

  

在 Docker 部署中，编辑 `.env` 文件（位于 `docker` 目录）：

  

```bash

# 启用注册功能

ALLOW_REGISTER=true

  

# 启用邮箱密码登录（注册需要）

ENABLE_EMAIL_PASSWORD_LOGIN=true

  

# 或者启用邮箱验证码登录

ENABLE_EMAIL_CODE_LOGIN=true

```

  

### 配置邮件服务

  

#### 基本配置

  

```bash

# 邮件服务类型：smtp、resend 或 sendgrid

MAIL_TYPE=smtp

  

# 默认发件人邮箱

MAIL_DEFAULT_SEND_FROM=noreply@yourdomain.com

  

# SMTP 服务器配置

SMTP_SERVER=smtp.yourdomain.com        # SMTP 服务器地址

SMTP_PORT=465                          # SMTP 端口（通常 465 用于 SSL，587 用于 TLS）

SMTP_USERNAME=your-email@yourdomain.com  # SMTP 用户名（通常是邮箱地址）

SMTP_PASSWORD=your-email-password      # SMTP 密码或应用专用密码

SMTP_USE_TLS=true                      # 是否使用 TLS（端口 587 时设为 true）

SMTP_OPPORTUNISTIC_TLS=false           # 是否启用机会性 TLS

```

  

#### 使用 Resend 服务

  

```bash

MAIL_TYPE=resend

RESEND_API_KEY=your-resend-api-key

RESEND_API_URL=https://api.resend.com

MAIL_DEFAULT_SEND_FROM=noreply@yourdomain.com

```

  

#### 使用 SendGrid 服务

  

```bash

MAIL_TYPE=sendgrid

SENDGRID_API_KEY=your-sendgrid-api-key

MAIL_DEFAULT_SEND_FROM=noreply@yourdomain.com

```

  

### 常见邮件服务商配置示例

  

#### Gmail

  

```bash

MAIL_TYPE=smtp

SMTP_SERVER=smtp.gmail.com

SMTP_PORT=587

SMTP_USERNAME=your-email@gmail.com

SMTP_PASSWORD=your-app-password  # ⚠️ 需要使用应用专用密码，不是登录密码

SMTP_USE_TLS=true

SMTP_OPPORTUNISTIC_TLS=false

```

  

**获取 Gmail 应用专用密码：**

1. 登录 Google 账户

2. 进入「安全性」→「两步验证」

3. 在「应用专用密码」中生成新密码

  

#### QQ 邮箱

  

```bash

MAIL_TYPE=smtp

SMTP_SERVER=smtp.qq.com

SMTP_PORT=587

SMTP_USERNAME=your-email@qq.com

SMTP_PASSWORD=your-authorization-code  # ⚠️ 需要使用授权码，不是登录密码

SMTP_USE_TLS=true

SMTP_OPPORTUNISTIC_TLS=false

```

  

**获取 QQ 邮箱授权码：**

1. 登录 QQ 邮箱

2. 进入「设置」→「账户」

3. 开启「POP3/IMAP/SMTP/Exchange/CardDAV/CalDAV 服务」

4. 生成授权码

  

#### 163 邮箱

  

```bash

MAIL_TYPE=smtp

SMTP_SERVER=smtp.163.com

SMTP_PORT=465

SMTP_USERNAME=your-email@163.com

SMTP_PASSWORD=your-authorization-code  # ⚠️ 需要使用授权码

SMTP_USE_TLS=false

SMTP_OPPORTUNISTIC_TLS=false

```

  

**获取 163 邮箱授权码：**

1. 登录 163 邮箱

2. 进入「设置」→「POP3/SMTP/IMAP」

3. 开启「POP3/SMTP 服务」

4. 生成授权码

  

#### 企业邮箱（以腾讯企业邮箱为例）

  

```bash

MAIL_TYPE=smtp

SMTP_SERVER=smtp.exmail.qq.com

SMTP_PORT=465

SMTP_USERNAME=your-email@yourcompany.com

SMTP_PASSWORD=your-password

SMTP_USE_TLS=false

SMTP_OPPORTUNISTIC_TLS=false

```

  

#### 阿里云企业邮箱

  

```bash

MAIL_TYPE=smtp

SMTP_SERVER=smtp.mxhichina.com

SMTP_PORT=465

SMTP_USERNAME=your-email@yourcompany.com

SMTP_PASSWORD=your-password

SMTP_USE_TLS=false

SMTP_OPPORTUNISTIC_TLS=false

```

  

### 应用配置

  

配置完成后，重启 Dify 服务：

  

```bash

cd docker

docker compose down

docker compose up -d

```

  

### 验证配置

  

1. **测试邮件发送**

   - 尝试注册新账户或邀请成员

   - 检查被邀请人是否收到邮件

  

2. **查看日志**

   ```bash

   # 查看邮件相关日志

   docker compose logs api | grep -i mail

   docker compose logs api | grep -i smtp

   # 查看错误日志

   docker compose logs api | grep -i error

   ```

  

---

  

## 常见问题

  

### 注册相关问题

  

#### 1. 注册按钮不显示

  

**原因：**

- `ALLOW_REGISTER` 未设置为 `true`

- 未启用邮箱登录方式

  

**解决方法：**

```bash

# 检查配置

ALLOW_REGISTER=true

ENABLE_EMAIL_PASSWORD_LOGIN=true

# 或

ENABLE_EMAIL_CODE_LOGIN=true

```

  

#### 2. 收不到验证码邮件

  

**可能原因：**

- 邮件服务配置错误

- 邮件被拦截到垃圾邮件

- 邮件服务商限制

  

**解决方法：**

1. 检查邮件服务配置是否正确

2. 查看服务器日志：`docker compose logs api | grep -i mail`

3. 检查邮箱的垃圾邮件文件夹

4. 确认邮件服务商的发送限制

  

#### 3. 注册失败

  

**可能原因：**

- 邮箱已被注册

- 密码不符合要求

- 系统限制

  

**解决方法：**

- 确认邮箱未被注册过

- 检查密码要求（至少 8 位，包含大小写字母、数字和特殊字符）

- 查看具体错误提示

  

### 添加成员相关问题

  

#### 1. 无法发送邀请邮件

  

**原因：**

- 邮件服务未配置

- 邮件服务配置错误

  

**解决方法：**

- 参考「配置邮件服务」章节正确配置

- 使用「通过账号 ID 手动添加」方法

  

#### 2. 邀请链接失效

  

**原因：**

- 邀请链接有时效性（默认 72 小时）

  

**解决方法：**

- 重新发送邀请邮件

- 使用账号 ID 手动添加

  

#### 3. 成员数量达到限制

  

**原因：**

- 工作空间成员数量已达到许可证限制

  

**解决方法：**

- 升级许可证

- 移除不活跃成员

  

### 邮件服务相关问题

  

#### 1. 邮件发送失败

  

**可能原因：**

- SMTP 配置错误

- 网络连接问题

- 认证失败

  

**解决方法：**

- 检查 SMTP 配置是否正确

- 确认防火墙允许 SMTP 端口（465 或 587）

- 检查邮件服务商是否要求应用专用密码

- 测试网络连接：`telnet smtp.server.com 587`

  

#### 2. 无法连接 SMTP 服务器

  

**可能原因：**

- 网络连接问题

- SMTP 服务器地址或端口错误

- 防火墙阻止

  

**解决方法：**

- 检查网络连接

- 确认 SMTP 服务器地址和端口

- 尝试使用不同的端口（465 或 587）

- 检查防火墙规则

  

#### 3. 认证失败

  

**可能原因：**

- 用户名或密码错误

- 需要使用应用专用密码

  

**解决方法：**

- 确认用户名和密码正确

- Gmail 等需要应用专用密码而非登录密码

- 检查邮件服务商的特殊要求

  

---

  

## 附录

  

### 相关配置文件位置

  

- Docker 环境变量：`docker/.env`

- API 配置：`api/configs/feature/__init__.py`

- 注册 API：`api/controllers/console/auth/email_register.py`

- 成员管理 API：`api/controllers/console/workspace/members.py`

- 注册前端：`web/app/signup/`

- 成员管理前端：`web/app/components/header/account-setting/members-page/`

  

### 相关环境变量列表

  

```bash

# 注册相关

ALLOW_REGISTER=true                    # 是否允许注册

ENABLE_EMAIL_PASSWORD_LOGIN=true      # 启用邮箱密码登录

ENABLE_EMAIL_CODE_LOGIN=true          # 启用邮箱验证码登录

  

# 邮件服务相关

MAIL_TYPE=smtp                         # 邮件服务类型

MAIL_DEFAULT_SEND_FROM=                # 默认发件人

SMTP_SERVER=                           # SMTP 服务器

SMTP_PORT=465                          # SMTP 端口

SMTP_USERNAME=                         # SMTP 用户名

SMTP_PASSWORD=                         # SMTP 密码

SMTP_USE_TLS=true                      # 使用 TLS

SMTP_OPPORTUNISTIC_TLS=false           # 机会性 TLS

  

# Resend 相关

RESEND_API_KEY=

RESEND_API_URL=https://api.resend.com

  

# SendGrid 相关

SENDGRID_API_KEY=

  

# 邀请相关

INVITE_EXPIRY_HOURS=72                 # 邀请链接有效期（小时）

```

  

### 数据库表结构

  

#### accounts 表（账户表）

  

```sql

-- 查询所有账户

SELECT id, email, name, created_at FROM accounts;

  

-- 查询特定账户

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

```

  

#### tenant_account_joins 表（工作空间成员关联表）

  

```sql

-- 查询工作空间所有成员

SELECT

    a.email,

    a.name,

    taj.role,

    taj.created_at

FROM tenant_account_joins taj

JOIN accounts a ON taj.account_id = a.id

WHERE taj.tenant_id = 'workspace-id';

  

-- 查询用户所属的所有工作空间

SELECT

    t.name as workspace_name,

    taj.role,

    taj.created_at

FROM tenant_account_joins taj

JOIN tenants t ON taj.tenant_id = t.id

WHERE taj.account_id = 'account-id';

```

  

#### tenants 表（工作空间表）

  

```sql

-- 查询所有工作空间

SELECT id, name, created_at FROM tenants;

```

  

### API 端点参考

  

#### 注册相关

  

- `POST /api/console/email-register/send-email` - 发送注册验证码邮件

- `POST /api/console/email-register/validity` - 验证注册验证码

- `POST /api/console/email-register` - 完成注册

  

#### 成员管理相关

  

- `GET /api/console/workspaces/current/members` - 获取工作空间成员列表

- `POST /api/console/workspaces/current/members/invite-email` - 通过邮箱邀请成员

- `DELETE /api/console/workspaces/current/members/{member_id}` - 移除成员

- `PUT /api/console/workspaces/current/members/{member_id}/update-role` - 更新成员角色

  

### 密码要求

  

Dify 对密码有以下要求：

  

- **最小长度**：8 个字符

- **必须包含**：

  - 至少一个大写字母（A-Z）

  - 至少一个小写字母（a-z）

  - 至少一个数字（0-9）

  - 至少一个特殊字符（!@#$%^&*等）

  

### 成员角色说明

  

- **owner**：工作空间所有者，拥有所有权限

- **admin**：管理员，可以管理成员和应用

- **editor**：编辑者，可以创建和编辑应用

- **dataset_operator**：数据集操作员，可以管理数据集

- **normal**：普通成员，基础使用权限

  

---

  

## 更新日志

  

- **2024-XX-XX**：初始版本，包含注册和添加成员的完整说明

  

---

  

## 相关文档

  

- [Dify 官方文档](https://docs.dify.ai)

- [Dify GitHub](https://github.com/langgenius/dify)

- [Docker 部署指南](https://docs.dify.ai/getting-started/install-self-hosted)

  

---

  

**注意**：本文档基于 Dify 最新版本编写，不同版本可能存在差异。如有问题，请参考官方文档或提交 Issue。