Capistrano 项目安装与配置完全指南-优快云博客

Capistrano 项目安装与配置完全指南

前言：为什么选择 Capistrano？

你是否曾经为手动部署项目到多台服务器而感到头疼？每次部署都要重复执行相同的 SSH 命令，还要担心部署过程中出现意外情况？Capistrano 正是为解决这些痛点而生的自动化部署工具。

Capistrano 是一个基于 Ruby、Rake 和 SSH 构建的自动化部署框架，它能够：

✅ 自动化执行重复的部署任务
✅ 支持多环境（staging、production 等）配置
✅ 实现并行执行，提高部署效率
✅ 提供强大的回滚机制
✅ 保持部署过程的一致性和可重复性

本文将为你提供从零开始的 Capistrano 完整安装与配置指南，让你轻松掌握这个强大的部署工具。

环境要求与准备工作

系统要求

在开始之前，请确保你的系统满足以下要求：

组件	最低要求	推荐版本
Ruby	2.0+	2.7+
SSH	支持密钥认证	OpenSSH 7.0+
Git/Mercurial/SVN	任意版本控制工具	Git 2.0+

SSH 密钥配置

Capistrano 依赖 SSH 密钥进行无密码认证，请确保：

生成 SSH 密钥对（如果尚未拥有）：

ssh-keygen -t rsa -b 4096 -C "your_email@example.com"

将公钥添加到目标服务器：

ssh-copy-id user@your-server-ip

测试 SSH 连接：

ssh user@your-server-ip

安装 Capistrano

方法一：作为独立 Gem 安装

# 安装最新稳定版
gem install capistrano

# 或者安装特定版本
gem install capistrano -v 3.17.1

方法二：在项目中使用 Bundler（推荐）

在项目的 Gemfile 中添加：

group :development do
  gem "capistrano", "~> 3.17", require: false
  # 如果是 Rails 项目，还可以添加
  gem "capistrano-rails", "~> 1.6", require: false
  gem "capistrano-bundler", "~> 2.0", require: false
  gem "capistrano-rvm", "~> 0.1", require: false
end

然后运行：

bundle install

初始化 Capistrano 项目

创建基础配置文件

# 进入项目根目录
cd /your/project/path

# 初始化 Capistrano
bundle exec cap install

这个命令会创建以下目录结构：

mermaid

自定义环境配置

如果你需要更多的环境配置，可以使用：

bundle exec cap install STAGES=development,staging,production,qa

核心配置文件详解

1. Capfile - 主配置文件

# 加载 DSL 和默认任务
require "capistrano/setup"
require "capistrano/deploy"

# 加载自定义任务
Dir.glob("lib/capistrano/tasks/*.rake").each { |r| import r }

# 如果是 Rails 项目，取消注释以下行
# require "capistrano/rails"
# require "capistrano/bundler"
# require "capistrano/rvm"

2. config/deploy.rb - 全局配置

# 应用名称
set :application, "my_app_name"
set :repo_url, "git@example.com:me/my_repo.git"

# 部署选项
set :deploy_to, "/var/www/#{fetch(:application)}"
set :scm, :git
set :branch, :master
set :format, :pretty
set :log_level, :debug
set :pty, true

# 链接文件和目录
set :linked_files, %w{config/database.yml config/secrets.yml}
set :linked_dirs, %w{log tmp/pids tmp/cache tmp/sockets vendor/bundle public/system}

# 保留的发布版本数量
set :keep_releases, 5

# RVM 配置（如使用）
# set :rvm_type, :user
# set :rvm_ruby_version, '2.7.0'

namespace :deploy do
  desc '重启应用'
  task :restart do
    on roles(:app), in: :sequence, wait: 5 do
      # 你的重启命令
      execute :touch, release_path.join('tmp/restart.txt')
    end
  end

  after :publishing, :restart
  after :finishing, 'deploy:cleanup'
end

3. config/deploy/production.rb - 生产环境配置

# 服务器定义
server 'production-server-ip', 
  user: 'deploy', 
  roles: %w{app db web}, 
  ssh_options: {
    user: 'deploy',
    keys: %w(~/.ssh/id_rsa),
    forward_agent: false,
    auth_methods: %w(publickey)
  }

# 环境特定配置
set :branch, 'main'
set :deploy_to, '/home/deploy/production_app'

# 如果需要设置环境变量
set :default_env, {
  'RAILS_ENV' => 'production',
  'RACK_ENV' => 'production'
}

4. config/deploy/staging.rb - 预发布环境配置

server 'staging-server-ip', 
  user: 'deploy', 
  roles: %w{app web}, 
  ssh_options: {
    keys: %w(~/.ssh/id_rsa),
    forward_agent: false
  }

set :branch, 'develop'
set :deploy_to, '/home/deploy/staging_app'
set :rails_env, 'staging'

部署流程详解

Capistrano 的部署过程遵循严格的流程：

mermaid

常用部署命令

基础命令

# 查看所有可用任务
bundle exec cap -T

# 部署到预发布环境
bundle exec cap staging deploy

# 部署到生产环境
bundle exec cap production deploy

# 模拟部署（不实际执行）
bundle exec cap production deploy --dry-run

# 查看任务依赖关系
bundle exec cap production deploy --prereqs

# 启用详细调试信息
bundle exec cap production deploy --trace

高级命令

# 回滚到上一个版本
bundle exec cap production deploy:rollback

# 检查服务器配置
bundle exec cap production doctor

# 进入服务器控制台
bundle exec cap production console

# 只执行特定任务
bundle exec cap production deploy:check

自定义任务编写

创建自定义任务

在 lib/capistrano/tasks/ 目录下创建 .rake 文件：

# lib/capistrano/tasks/custom.rake
namespace :deploy do
  desc '重启 Sidekiq'
  task :restart_sidekiq do
    on roles(:worker) do
      within current_path do
        execute :bundle, :exec, :sidekiqctl, 'stop', "#{current_path}/tmp/pids/sidekiq.pid"
        execute :bundle, :exec, :sidekiq, '-d', '-L', 'log/sidekiq.log', '-C', 'config/sidekiq.yml', '-P', 'tmp/pids/sidekiq.pid'
      end
    end
  end

  after 'deploy:published', 'deploy:restart_sidekiq'
end

常用任务模式

# 文件操作任务
task :upload_config do
  on roles(:app) do
    upload! 'config/production.yml', "#{shared_path}/config/production.yml"
  end
end

# 数据库任务
task :migrate do
  on roles(:db) do
    within release_path do
      execute :rake, 'db:migrate'
    end
  end
end

# 服务管理任务
task :restart_nginx do
  on roles(:web) do
    execute :sudo, :service, :nginx, :restart
  end
end

故障排除与最佳实践

常见问题解决

SSH 连接问题

# 测试 SSH 连接
ssh -T user@server

# 检查 SSH 代理
ssh-add -l

权限问题

# 确保部署用户有写入权限
ssh user@server "mkdir -p /var/www/my_app && chown user:user /var/www/my_app"

Git 仓库访问问题

# 测试 Git 访问
git ls-remote your-repo-url

最佳实践

使用版本锁定

# 在 Gemfile 中固定版本
gem 'capistrano', '~> 3.17.0'

配置合理的链接文件

set :linked_files, %w{
  config/database.yml
  config/secrets.yml
  config/application.yml
}

设置适当的保留版本数

set :keep_releases, 10  # 根据磁盘空间调整

使用环境变量管理敏感信息

set :default_env, {
  'DATABASE_URL' => ENV['PRODUCTION_DATABASE_URL'],
  'SECRET_KEY_BASE' => ENV['SECRET_KEY_BASE']
}

进阶配置技巧

多服务器角色配置

# 定义不同角色的服务器
server 'web1.example.com', user: 'deploy', roles: %w{web}
server 'web2.example.com', user: 'deploy', roles: %w{web}
server 'db.example.com', user: 'deploy', roles: %w{db}
server 'app.example.com', user: 'deploy', roles: %w{app}
server 'worker.example.com', user: 'deploy', roles: %w{worker}

# 角色特定配置
namespace :deploy do
  task :restart do
    on roles(:web), in: :sequence do
      execute :sudo, :service, :nginx, :reload
    end
    
    on roles(:app), in: :sequence do
      execute :touch, release_path.join('tmp/restart.txt')
    end
  end
end

自定义部署策略

# 蓝绿部署策略
set :deploy_strategy, :blue_green

namespace :deploy do
  task :switch do
    on roles(:web) do
      # 切换流量到新版本
      execute :ln, '-sfn', release_path, '/var/www/current'
    end
  end
  
  after :finished, :switch
end

总结

Capistrano 是一个强大而灵活的部署自动化工具，通过本文的详细指南，你应该已经掌握了：

✅ Capistrano 的安装和基本配置
✅ 多环境部署的设置方法
✅ 自定义任务的编写技巧
✅ 常见问题的解决方法
✅ 最佳实践和进阶配置

记住，成功的自动化部署需要：

可靠的 SSH 配置 - 确保密钥认证正常工作
清晰的目录结构 - 遵循 Capistrano 的约定
适当的权限设置 - 避免部署过程中的权限问题
完善的错误处理 - 为各种异常情况做好准备

现在就开始使用 Capistrano 来简化你的部署流程吧！如果有任何问题，记得查看详细的日志信息（使用 --trace 参数）和官方文档。

Happy deploying! 🚀

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考