Kamal部署Rails应用时secret_key_base问题的解决方案

问题背景

在使用Kamal(原MRSK)部署Rails 7.1应用时，经常会遇到关于secret_key_base的配置问题。当从Kamal 1.3.1升级到1.9.2版本后，部署过程中可能会出现以下两种典型错误：

1. 缺少secret_key_base的环境变量错误
2. 消息加密器无法验证的InvalidMessage错误

根本原因分析

这些问题的核心在于Rails应用的安全机制和Kamal部署环境配置之间的不匹配：

1. Rails 7.1的安全要求：从Rails 5.2开始，框架引入了加密凭证系统，要求生产环境必须配置secret_key_base和RAILS_MASTER_KEY。

2. Kamal环境变量传递：Kamal通过.env文件和环境变量来管理配置，但需要确保这些变量正确传递到Docker容器中。

3. 凭证文件同步：config/credentials/production.key和config/credentials/production.yml.enc文件必须存在于代码仓库中，否则部署时会因无法解密凭证而失败。

详细解决方案

第一步：检查基础配置

1. 确保.env文件包含必要变量：

   RAILS_MASTER_KEY=your_master_key_here
   SECRET_KEY_BASE=your_secret_key_base_here
   

2. 运行环境变量推送命令：

   kamal env push
   

第二步：处理凭证文件

1. 检查凭证文件是否存在：

   • config/credentials/production.key
   • config/credentials/production.yml.enc

2. 如果文件丢失或损坏，重新生成凭证：

   rm config/credentials/production.key
   rm config/credentials/production.yml.enc
   EDITOR="code --wait" rails credentials:edit --environment production
   

3. 确保.gitignore没有排除这些文件：

   # 确保没有排除生产凭证文件
   !config/credentials/production.key
   !config/credentials/production.yml.enc
   

第三步：验证部署配置

1. 检查deploy.yml中的环境变量设置：

   env:
     secret:
       - DATABASE_URL
       - RAILS_MASTER_KEY
       - SECRET_KEY_BASE
   

2. 确保RAILS_ENV设置正确：

   env:
     clear:
       RAILS_ENV: production
   

第四步：处理加密错误

如果遇到ActiveSupport::MessageEncryptor::InvalidMessage错误：

1. 备份现有凭证文件
2. 重新生成所有凭证：

   rails credentials:edit --environment production
   

3. **更新.env中的RAILS_MASTER_KEY**为新生成的值

最佳实践建议

1. 凭证管理：

   • 将production.key加入.gitignore，但确保它通过安全渠道(如Kamal的环境变量)传递
   • 使用密码管理器存储主密钥

2. 环境一致性：

   • 在开发、测试和生产环境使用相同的Ruby和Rails版本
   • 定期更新Kamal到最新版本

3. 部署前检查：

   kamal env print
   kamal app exec "rails runner 'puts Rails.application.credentials.config'"
   

总结

Kamal部署Rails应用时的凭证问题通常源于环境配置不完整或凭证文件缺失。通过系统性地检查环境变量、凭证文件和部署配置，可以解决大多数secret_key_base相关问题。记住，安全凭证的正确管理是Rails应用安全部署的关键环节。