Capistrano部署Rails5.2时Puma启动失败 提示bundler命令不存在

故障现象 #

• 部署流程其余环节运行正常，仅Puma服务无法正常启动
• 执行启动命令sudo systemctl start puma_tuma_production后，通过tail -f /var/www/tuma/shared/log/puma_error.log查看错误日志，输出如下：

bundler: command not found: puma
Install missing gem executables with `bundle install`

• 进入Rails项目当前版本目录/var/www/tuma/current后，无法正常启动Rails控制台，执行bundle exec rails c production返回错误：

bundler: command not found: rails
Install missing gem executables with `bundle install`

• 服务状态检查：执行sudo systemctl status puma_tuma_production返回结果显示服务启动失败，退出状态码127，因短时间内重试次数过多被systemd终止
• 环境检查结果：
  • 项目目录下执行gem list bundler，输出显示已安装bundler 2.3.17（默认版本2.1.4）
  • 项目目录外执行同命令，返回bundler路径为/home/ubuntu/.rvm/gems/ruby-2.7.1/bin/bundler
• 已尝试操作：将Capistrano的:rvm_bin_stubs配置修改为append模式，问题未解决
• 已准备排查材料：完整systemd服务配置、puma.rb配置、环境PATH变量、Gemfile、RVM脚本、Capistrano部署配置（config/deploy.rb、Capfile）

根因说明 #

退出码127为系统找不到指定命令的标准错误，核心原因是systemd启动Puma服务时未加载ubuntu用户下RVM管理的Ruby环境变量，默认读取了系统全局的Ruby/Bundler路径，无法找到对应gem安装的puma、rails可执行文件。
手动在项目目录下能识别到RVM安装的bundler，是因为交互式登录shell时自动加载了RVM的环境初始化脚本，但systemd默认启动服务不会加载用户shell的初始化配置，因此出现环境不一致问题。

修复方案 #

1. 修改Puma对应的systemd服务配置，在[Service]配置段显式指定运行用户、工作目录、RVM环境路径，参考配置如下：

   [Service]
   User=ubuntu
   WorkingDirectory=/var/www/tuma/current
   Environment="RAILS_ENV=production"
   Environment="PATH=/home/ubuntu/.rvm/gems/ruby-2.7.1/bin:/home/ubuntu/.rvm/gems/ruby-2.7.1@global/bin:/home/ubuntu/.rvm/rubies/ruby-2.7.1/bin:/home/ubuntu/.rvm/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
   ExecStart=/home/ubuntu/.rvm/gems/ruby-2.7.1/bin/bundle exec puma -C /var/www/tuma/shared/puma.rb
   Restart=always
   

   注意：User必须指定为安装RVM的ubuntu用户，禁止用root运行Puma服务，否则会读取root用户下的gem环境，依然找不到对应依赖。如果Puma配置里已经开启了daemonize模式，需要把配置里的daemonize改成false，否则会和systemd的进程管理冲突导致服务异常。
2. 重新加载systemd配置，重启服务验证状态：

   sudo systemctl daemon-reload
   sudo systemctl restart puma_tuma_production
   sudo systemctl status puma_tuma_production
   

3. 若仍提示gem缺失，进入项目目录手动安装生产环境依赖：

   cd /var/www/tuma/current
   bundle install --deployment --without development test
   

4. 校验Capistrano配置，确认config/deploy.rb中RVM相关配置正确：

   set :rvm_type, :user
   set :rvm_ruby_version, '2.7.1'
   

   部署时不要加sudo执行cap命令，否则会把gem安装到root用户的RVM环境下，普通用户无权限读取。

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