cPanel部署Rails应用时Active Storage生成空Blob链接问题

核心问题分析 #

问题根源是Active Storage的Disk服务在子目录部署时，无法正确生成包含子路径的URL，同时ActiveStorage::Current.url_options的设置方式未覆盖全局和请求上下文场景，导致控制台、非请求上下文（如后台任务）无法生成有效URL。

具体解决方案 #

1. 全局+请求上下文双层配置url_options #

• 在config/application.rb中添加全局默认配置，覆盖非请求场景的URL生成规则：

config.active_storage.url_options = { host: '你的域名.com', port: 443, protocol: 'https', path: '/my-app' }

替换你的域名.com为实际域名，port根据协议调整（HTTPS用443，HTTP用80），path严格对应子目录/my-app。

• 在app/controllers/application_controller.rb中添加请求上下文的动态配置，确保请求过程中生成的URL匹配当前请求环境：

class ApplicationController < ActionController::Base
  before_action :set_active_storage_url_options

  private
  def set_active_storage_url_options
    ActiveStorage::Current.url_options = {
      host: request.host,
      port: request.port,
      protocol: request.protocol,
      path: '/my-app'
    }
  end
end

2. 修正Disk服务的URL前缀配置 #

编辑config/storage.yml，给local磁盘服务添加带自目录的URL前缀：

local:
  service: Disk
  root: <%= Rails.root.join("storage") %>
  public: true
  url: "/my-app/rails/active_storage/blobs/:signed_id/:filename"

这里的url前缀必须包含子目录/my-app，确保生成的Blob URL自动带上子路径。

3. 控制台/后台任务的临时URL配置 #

在控制台或后台任务中调用blob.url前，手动设置上下文：

ActiveStorage::Current.url_options = { host: '你的域名.com', port: 443, protocol: 'https', path: '/my-app' }
# 之后执行
blob = ActiveStorage::Blob.last
blob.url # 可正常生成URL

如果需要长期生效，在config/initializers/active_storage.rb中添加：

unless Rails.env.development?
  ActiveStorage::Current.url_options = {
    host: '你的域名.com',
    port: 443,
    protocol: 'https',
    path: '/my-app'
  }
end

4. 验证权限与路由 #

• 检查storage文件夹权限：设置为755，内部文件权限设为644，确保Web服务器可读取文件。
• 确认cPanel的子目录配置已将请求转发到Rails应用的public目录，路由规则正常生效。

5. 清理缓存并重启应用 #

执行以下命令更新静态资源并清理缓存：

rails assets:precompile RAILS_ENV=production
rails cache:clear

通过cPanel的Passenger模块或主机提供的工具重启Rails应用。

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