Turnout 技术文档

1. 安装指南

Rails 3+ 安装

在 Gemfile 中添加以下内容：

gem 'turnout'

然后运行以下命令进行安装：

bundle install

注意：安装完成后需要重启 Rails 服务器才能生效。

Sinatra 安装

在 Sinatra 应用文件中添加以下内容：

require 'rack/turnout'

class App < Sinatra::Base
  configure do
    use Rack::Turnout
  end
end

在 Rakefile 中添加以下内容：

require 'turnout/rake_tasks'

2. 项目的使用说明

激活维护模式

可以通过以下命令激活维护模式：

rake maintenance:start

还可以在激活时指定原因、允许访问的路径或 IP 地址：

rake maintenance:start reason="Somebody googled Google!"
rake maintenance:start allowed_paths="/login,^/faqs/[0-9]*"
rake maintenance:start allowed_ips="4.8.15.16"

也可以同时指定多个参数：

rake maintenance:start reason="Someone told me I should type <code>sudo rm -rf /</code>" allowed_paths="^/help,^/contact_us" allowed_ips="127.0.0.1,192.168.0.0/24"

如果配置了 named_maintenance_file_paths，可以使用以下命令激活维护模式：

rake maintenance:server:start

关闭维护模式

可以通过以下命令关闭维护模式：

rake maintenance:end

如果使用了命名路径激活维护模式，可以使用以下命令关闭：

rake maintenance:server:end

3. 项目 API 使用文档

配置 Turnout

Turnout 可以通过两种方式进行配置：

1. 通过中间件传递配置哈希

   use Rack::Turnout,
     app_root: '/some/path',
     named_maintenance_file_paths: {app: 'tmp/app.yml', server: '/tmp/server.yml'},
     maintenance_pages_path: 'app/views/maintenance',
     default_maintenance_page: Turnout::MaintenancePage::JSON,
     default_reason: 'Somebody googled Google!',
     default_allowed_paths: ['^/admin/'],
     default_response_code: 418,
     default_retry_after: 3600
   

2. 使用配置块

   Turnout.configure do |config|
     config.skip_middleware = true
     config.app_root = '/some/path'
     config.named_maintenance_file_paths = {app: 'tmp/app.yml', server: '/tmp/server.yml'}
     config.maintenance_pages_path = 'app/views/maintenance'
     config.default_maintenance_page = Turnout::MaintenancePage::JSON
     config.default_reason = 'Somebody googled Google!'
     config.default_allowed_paths = ['^/admin/']
     config.default_response_code = 418
     config.default_retry_after = 3600
   end
   

默认配置

Turnout.configure do |config|
  config.app_root = '.'
  config.named_maintenance_file_paths = {default: config.app_root.join('tmp', 'maintenance.yml').to_s}
  config.maintenance_pages_path = config.app_root.join('public').to_s
  config.default_maintenance_page = Turnout::MaintenancePage::HTML
  config.default_reason = "The site is temporarily down for maintenance.\nPlease check back soon."
  config.default_allowed_paths = []
  config.default_response_code = 503
  config.default_retry_after = 7200
end

4. 项目安装方式

Rails 3+ 安装

在 Gemfile 中添加以下内容：

gem 'turnout'

然后运行以下命令进行安装：

bundle install

注意：安装完成后需要重启 Rails 服务器才能生效。

Sinatra 安装

在 Sinatra 应用文件中添加以下内容：

require 'rack/turnout'

class App < Sinatra::Base
  configure do
    use Rack::Turnout
  end
end

在 Rakefile 中添加以下内容：

require 'turnout/rake_tasks'

自定义维护页面

默认的维护页面位于 public/maintenance.[html|json|html.erb]，你可以创建自己的维护页面文件。如果提供了 reason 参数，Turnout 会尝试在维护页面文件中替换 {{ reason }} 标签。因此，请确保在 maintenance.html 文件中包含 {{ reason }} 标签。

警告：如果你在 /public 目录下创建了自定义的维护页面文件，用户可以直接访问这些文件的源代码（例如 http://example.com/maintenance.html.erb）。对于 HTML 和 JSON 文件来说，这通常不是问题，但对于 ERB 文件来说，可能会暴露敏感信息。因此，建议将 maintenance_pages_path 设置为 /public 以外的目录。

检测维护模式

如果你想在应用中检测是否处于维护模式（对于未被阻止的用户或页面），可以调用以下代码：

!Turnout::MaintenanceFile.find.nil?

多应用维护

可以通过在所有应用中配置一个中央 named_maintenance_file_path（例如 /tmp/turnout.yml），以便同时将所有应用置于维护模式。你还可以配置基于服务的路径（例如 /tmp/mongodb_maintenance.yml），以便将所有使用 MongoDB 的应用置于维护模式。

示例 maintenance.yml 文件

---
reason: Someone told me I should type <code>sudo rm -rf /</code>
allowed_paths:
- ^/help
- ^/contact_us
allowed_ips:
- 127.0.0.1
- 192.168.0.0/24
response_code: 503
retry_after: 3600

通过以上文档，用户可以详细了解如何安装、配置和使用 Turnout 来管理应用的维护模式。