Capistrano Unicorn 技术文档

1. 安装指南

1.1 添加依赖

首先，将 capistrano-unicorn 添加到你的 Gemfile 中：

group :development do
  gem 'capistrano-unicorn', :require => false
end

1.2 加载插件

在你的部署脚本 config/deploy.rb 中加载 capistrano-unicorn：

require 'capistrano-unicorn'

1.3 配置重启任务钩子

根据你的需求，选择以下任意一种方式配置重启任务钩子：

after 'deploy:restart', 'unicorn:reload'    # 应用未预加载
after 'deploy:restart', 'unicorn:restart'   # 应用预加载
after 'deploy:restart', 'unicorn:duplicate' # 实现了 before_fork 钩子（零停机部署）

1.4 创建 Unicorn 配置文件

创建一个新的配置文件 config/unicorn.rb 或 config/unicorn/STAGE.rb，其中 STAGE 是你的部署环境（如 production 或 staging）。

你可以参考 examples/rails3.rb 作为配置文件的示例。

2. 项目的使用说明

2.1 部署

确保你使用的是最新版本，然后执行部署：

cap deploy

2.2 测试任务

你可以测试每个单独的任务：

cap unicorn:start
cap unicorn:stop
cap unicorn:reload

3. 项目 API 使用文档

3.1 可用任务

要获取所有 Capistrano 任务的列表，可以运行：

cap -T

以下是一些常用的任务：

• cap unicorn:add_worker：添加一个新的工作进程
• cap unicorn:remove_worker：移除指定数量的工作进程
• cap unicorn:reload：重新加载 Unicorn
• cap unicorn:restart：重启 Unicorn
• cap unicorn:show_vars：调试 Unicorn 变量
• cap unicorn:shutdown：立即关闭 Unicorn
• cap unicorn:start：启动 Unicorn 主进程
• cap unicorn:stop：停止 Unicorn

3.2 配置参数

你可以在 deploy.rb 中修改以下 Capistrano 变量：

• unicorn_env：设置 Unicorn 配置文件的基名，默认为 rails_env 变量，如果未设置则为 production。
• unicorn_rack_env：设置传递给 Unicorn 的 Rack 环境，默认为 development（如果 rails_env 为 development），否则为 deployment。
• unicorn_user：指定运行 Unicorn 主进程的用户，默认为 nil，即使用 user 变量定义的用户。
• unicorn_roles：定义执行 Unicorn 任务的角色，默认为 :app。
• unicorn_bundle：设置 Unicorn 的 Bundler 命令，默认为 bundle。
• unicorn_bin：设置 Unicorn 可执行文件，默认为 unicorn。
• unicorn_options：设置传递给 Unicorn 的额外启动选项。
• unicorn_restart_sleep_time：设置重启 Unicorn 时等待旧 PID 文件出现的时间，默认为 2 秒。

4. 项目安装方式

4.1 多阶段部署

在多阶段部署中，Capistrano 会先加载默认配置，然后执行你的阶段任务并覆盖之前定义的变量。默认环境在执行阶段任务之前设置为 :production，因此你需要确保 :rails_env 和 :unicorn_env 设置正确。

假设你有两个部署阶段：staging 和 production。你需要在 config/deploy/staging.rb 和 config/deploy/production.rb 中分别定义这些文件。为了避免重复代码，可以将通用设置放在 config/deploy.rb 中，而只在每个阶段定义文件中放置特定于该环境的设置。

例如，config/deploy.rb 文件可以包含以下内容：

set :stages, %w(production staging)
set :default_stage, "staging"
require 'capistrano/ext/multistage'

set(:unicorn_env) { rails_env }

role(:web) { domain }
role(:app) { domain }
role(:db, :primary => true) { domain }

set(:deploy_to)    { "/home/#{user}/#{application}/#{fetch :rails_env}" }
set(:current_path) { File.join(deploy_to, current_dir) }

然后，config/deploy/production.rb 文件可以包含：

set :domain,      "app.mydomain.com"
set :rails_env,   "production"

而 config/deploy/staging.rb 文件只需要包含：

set :domain,      "app.staging.mydomain.com"
set :rails_env,   "staging"

这样配置既简洁又清晰。

5. 测试

要执行测试套件，可以运行：

bundle exec rake test

6. 许可证

有关许可证的详细信息，请参阅项目中的 LICENSE 文件。

---

通过本文档，你应该能够顺利安装、配置和使用 capistrano-unicorn 插件，并了解其核心功能和配置选项。如果你有任何问题或需要进一步的帮助，请参考项目的 GitHub 页面或联系社区支持。