Capistrano部署Rails应用在puma:restart阶段异常终止

我在AWS实例上使用Capistrano部署Ruby on Rails 7应用，手动执行RAILS_ENV=production bundle exec puma -C /var/www/rails-7-app/current/config/puma.rb命令可正常启动服务器，站点能通过IP:3000访问，但Capistrano执行puma:restart或cap production puma:start时流程突然停止，无报错输出，修改puma的systemd服务文件后问题仍未解决。

排查步骤与解决方案 #

1. 校验目录权限 #

• 确保Capistrano使用的部署用户（通常为deploy）对应用目录拥有完整读写权限：

  sudo chown -R deploy:deploy /var/www/rails-7-app
  sudo chmod -R 755 /var/www/rails-7-app/shared
  

• 检查puma依赖的临时目录是否存在且权限正确：

  mkdir -p /var/www/rails-7-app/shared/tmp/{pids,sockets}
  chown -R deploy:deploy /var/www/rails-7-app/shared/tmp
  

2. 核对Capistrano的puma配置 #

• 在config/deploy.rb或config/deploy/production.rb中确认puma路径配置：

  set :puma_state, "#{shared_path}/tmp/pids/puma.state"
  set :puma_pid, "#{shared_path}/tmp/pids/puma.pid"
  set :puma_socket, "#{shared_path}/tmp/sockets/puma.sock"
  set :puma_conf, "#{current_path}/config/puma.rb"
  set :puma_access_log, "#{shared_path}/log/puma.access.log"
  set :puma_error_log, "#{shared_path}/log/puma.error.log"
  

• 确保config/puma.rb的production环境配置指向shared目录：

  production do
    bind 'tcp://0.0.0.0:3000'
    pidfile '/var/www/rails-7-app/shared/tmp/pids/puma.pid'
    state_path '/var/www/rails-7-app/shared/tmp/pids/puma.state'
    stdout_redirect '/var/www/rails-7-app/shared/log/puma.access.log', '/var/www/rails-7-app/shared/log/puma.error.log', true
  end
  

3. 修正systemd服务配置 #

• 检查/etc/systemd/system/puma.service的配置，确保与Capistrano兼容：

  [Unit]
  Description=Puma HTTP Server
  After=network.target
  
  [Service]
  Type=simple
  User=deploy
  WorkingDirectory=/var/www/rails-7-app/current
  ExecStart=/home/deploy/.rbenv/shims/bundle exec puma -C /var/www/rails-7-app/current/config/puma.rb -e production
  ExecReload=/bin/kill -USR1 $MAINPID
  Restart=always
  
  [Install]
  WantedBy=multi-user.target
  

• 重新加载systemd配置并验证服务状态：

  sudo systemctl daemon-reload
  sudo systemctl restart puma
  sudo systemctl status puma
  

4. 查看详细日志定位问题 #

• 开启Capistrano详细日志执行命令，获取更多报错信息：

  cap production puma:start --trace
  

• 检查puma错误日志，排查启动失败的具体原因：

  cat /var/www/rails-7-app/shared/log/puma.error.log
  

5. 解决环境变量加载问题 #

• 在config/deploy.rb中添加部署用户的环境变量配置，确保rbenv/rvm等工具能被正确调用：

  set :default_env, {
    PATH: '$HOME/.rbenv/shims:$HOME/.rbenv/bin:$PATH',
    RBENV_ROOT: '$HOME/.rbenv'
  }
  

• 或在systemd服务文件中明确指定环境变量：

  Environment="PATH=/home/deploy/.rbenv/shims:/home/deploy/.rbenv/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin"
  Environment="RAILS_ENV=production"
  

内容的提问来源于stack exchange，提问作者Syed Rizwan