Heroku部署Apostrophe 3 CMS时uploads/attachments文件丢失求助

问题根源 #

Heroku采用临时文件系统（Ephemeral Filesystem），每次部署、dyno重启或缩放时，实例上的本地存储会被完全重置——Apostrophe默认将媒体文件存在本地，无法在Heroku上持久化，这就是文件丢失的核心原因。

解决方案：改用云存储服务 #

Apostrophe 3支持通过官方插件对接云存储，以下是两种最常用的落地方案：

方案1：使用AWS S3存储

1. 安装S3存储插件
   在项目根目录执行：

   npm install @apostrophecms/storage-s3
   

2. 配置Apostrophe使用S3
   修改项目根目录的app.js，注册插件并配置存储参数：

   module.exports = {
     modules: {
       '@apostrophecms/storage-s3': {
         options: {
           bucket: process.env.S3_BUCKET_NAME,
           region: process.env.S3_REGION,
           accessKeyId: process.env.AWS_ACCESS_KEY_ID,
           secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY
         }
       },
       '@apostrophecms/attachment': {
         options: {
           // 强制附件模块使用S3存储
           storage: '@apostrophecms/storage-s3'
         }
       }
     }
   };
   

3. 配置Heroku环境变量
   在Heroku控制台「设置」→「Config Vars」中添加以下变量：
   • AWS_ACCESS_KEY_ID：你的AWS账号访问密钥ID
   • AWS_SECRET_ACCESS_KEY：你的AWS账号访问密钥
   • S3_BUCKET_NAME：预先创建好的S3存储桶名称
   • S3_REGION：存储桶所在区域（如us-east-1）
4. 配置S3存储桶CORS规则
   确保存储桶允许Heroku应用域名访问，在S3控制台「权限」→「CORS配置」中添加：

   <CORSConfiguration>
     <CORSRule>
       <AllowedOrigin>https://你的Heroku应用域名.herokuapp.com</AllowedOrigin>
       <AllowedMethod>GET</AllowedMethod>
       <AllowedHeader>*</AllowedHeader>
     </CORSRule>
   </CORSConfiguration>
   

方案2：使用Cloudinary存储（更轻量化）

Cloudinary无需手动创建存储桶，自带CDN加速，适合快速搭建：

1. 安装Cloudinary存储插件

   npm install @apostrophecms/storage-cloudinary
   

2. 配置Apostrophe使用Cloudinary
   修改app.js：

   module.exports = {
     modules: {
       '@apostrophecms/storage-cloudinary': {
         options: {
           cloudName: process.env.CLOUDINARY_CLOUD_NAME,
           apiKey: process.env.CLOUDINARY_API_KEY,
           apiSecret: process.env.CLOUDINARY_API_SECRET
         }
       },
       '@apostrophecms/attachment': {
         options: {
           storage: '@apostrophecms/storage-cloudinary'
         }
       }
     }
   };
   

3. 配置Heroku环境变量
   在Heroku添加Cloudinary控制台获取的三个参数：
   • CLOUDINARY_CLOUD_NAME
   • CLOUDINARY_API_KEY
   • CLOUDINARY_API_SECRET

额外注意事项 #

• 迁移旧文件：之前存在本地uploads目录的文件需要手动上传到云存储，否则旧媒体链接会失效。
• 本地开发兼容：可以通过环境变量控制本地开发用本地存储，生产环境用云存储：

  '@apostrophecms/attachment': {
    options: {
      storage: process.env.NODE_ENV === 'production' ? '@apostrophecms/storage-s3' : null
    }
  }
  

• 禁止本地存储依赖：Heroku上任何需要持久化的文件都不能存在本地，包括用户上传、生成的静态文件等。

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