Milia 多租户 Ruby on Rails 应用技术文档

1. 安装指南

1.1 在新应用中安装 Milia

最快的方式是遵循 Sample App 章节中的简单指令，生成一个使用 Devise 和 Milia 的新应用。

1.2 在现有应用中添加 Milia

推荐的方式是将 Milia 添加到现有应用中，首先启动 Sample App，确保其正常工作，然后将你的应用移植到该示例应用中。这样可以确保 Rails 和 Devise 的设置正确无误。

逐步操作

不要试图一次性改变所有内容！不要追求完美，试图一次性启动一个完全编写的应用！

只需按照创建示例的说明，一步一步地操作。先让基础功能正常工作，然后再进行修改、调整和优化。

1.3 最小化手动设置

（如果你已经生成了 Sample App，以下所有步骤都已经完成。）

在你的 Gemfile 中添加：

gem 'milia', '~>1.3'

然后运行 Milia 生成器：

$ bundle install
$ rails g milia:install --org_email='<your smtp email for dev work>'

注意：Milia 生成器有一个选项，用于指定用于发送确认和账户激活邮件的开发工作邮箱。

有关生成器所做操作的详细说明，请参阅 README_DETAILS。

对生成的迁移文件进行任何必要的更改，然后运行：

$ rake db:create
$ rake db:migrate

应用控制器

在 app/controllers/application_controller.rb 中，在 protect_from_forgery 之后立即添加以下行：

before_action :authenticate_tenant!   # 认证用户并设置租户

rescue_from ::Milia::Control::MaxTenantExceeded,   :with => :max_tenants
rescue_from ::Milia::Control

2. 项目的使用说明

2.1 基本概念

租户 == 组织与用户/成员

租户是一个拥有多个成员（用户）的组织。最初，用户创建一个新组织（租户）并成为其第一个成员（通常是管理员）。然后他邀请其他成员，这些成员可以登录并加入该租户。Milia 确保用户只能访问自己租户（组织）的数据。

租户模型

属于某个租户（组织）的模型。在模型主体中添加 acts_as_tenant 以激活该模型的租户功能。大多数表（除了纯连接表、用户表和租户表）应该是租户模型。每个租户表的记录都需要设置 tenant_id。Milia 会处理这一点。

通用模型

不属于特定租户（组织）但具有系统范围相关性的模型。在模型主体中添加 acts_as_universal 以将其标记为通用模型。通用表从不包含关键的用户/公司信息。Devise 用户表必须是通用的，并且只应包含电子邮件、加密密码和 Devise 所需的数据。所有其他用户数据（姓名、电话、地址等）应分解到一个名为 members 的租户表中（Member belongs_to :user, User has_one :member）。同样适用于组织（账户或公司）信息。通用表的记录必须将 tenant_id 设置为 nil。Milia 会处理这一点。

连接表

纯连接表（has_and_belongs_to_many HABTM 关联）既不是通用的，也不是租户的。

3. 项目 API 使用文档

3.1 获取当前租户

current_tenant

3.2 更改当前租户

switch_tenant(new_tenant)

迭代租户

Tenant.all.each do |tenant|
  switch_tenant(tenant)
  # 在此租户下执行操作
end

Rails 控制台

Tenant.all.each do |tenant|
  switch_tenant(tenant)
  # 在此租户下执行操作
end

3.3 Milia 回调

Milia 提供了多个回调，可以在租户切换、用户认证等事件时触发。具体回调请参阅 README_DETAILS。

4. 项目安装方式

4.1 在新应用中安装 Milia

最快的方式是遵循 Sample App 章节中的简单指令，生成一个使用 Devise 和 Milia 的新应用。

4.2 在现有应用中添加 Milia

推荐的方式是将 Milia 添加到现有应用中，首先启动 Sample App，确保其正常工作，然后将你的应用移植到该示例应用中。这样可以确保 Rails 和 Devise 的设置正确无误。

逐步操作

不要试图一次性改变所有内容！不要追求完美，试图一次性启动一个完全编写的应用！

只需按照创建示例的说明，一步一步地操作。先让基础功能正常工作，然后再进行修改、调整和优化。

4.3 最小化手动设置

（如果你已经生成了 Sample App，以下所有步骤都已经完成。）

在你的 Gemfile 中添加：

gem 'milia', '~>1.3'

然后运行 Milia 生成器：

$ bundle install
$ rails g milia:install --org_email='<your smtp email for dev work>'

注意：Milia 生成器有一个选项，用于指定用于发送确认和账户激活邮件的开发工作邮箱。

有关生成器所做操作的详细说明，请参阅 README_DETAILS。

对生成的迁移文件进行任何必要的更改，然后运行：

$ rake db:create
$ rake db:migrate

应用控制器

在 app/controllers/application_controller.rb 中，在 protect_from_forgery 之后立即添加以下行：

before_action :authenticate_tenant!   # 认证用户并设置租户

rescue_from ::Milia::Control::MaxTenantExceeded,   :with => :max_tenants
rescue_from ::Milia::Control

通过以上步骤，你可以成功安装并使用 Milia 来实现 Ruby on Rails 应用的多租户功能。