Skip to content

Attachment Storage (AttachmentProxy) ​

Erupt attachments (@Edit(type = ATTACHMENT), rich-text images, etc.) land on the local disk by default. To move them to object storage you have two options:

OptionWhen to useEffort
Add erupt-data-s3 (recommended)The storage service exposes an S3-compatible API — AWS S3, Alibaba Cloud OSS, Tencent Cloud COS, MinIO, Cloudflare R2, etc.; see the compatibility table belowOne annotation + a few lines of yml
Implement AttachmentProxy yourselfThe storage service does not speak S3 (e.g. Upyun, FastDFS), or you need extra processing at upload timeOne class + the vendor SDK

erupt-data-s3 ships a ready-made S3AttachmentProxy built on AWS SDK v2. Two steps:

xml
<dependency>
  <groupId>xyz.erupt</groupId>
  <artifactId>erupt-data-s3</artifactId>
  <version>${erupt.version}</version>
</dependency>
java
@SpringBootApplication
@EruptScan
@EruptAttachmentUpload(S3AttachmentProxy.class)
public class DemoApplication { ... }
yaml
erupt:
  s3:
    bucket: erupt-uploads
    region: ap-southeast-1
    endpoint: http://minio.internal:9000   # omit for AWS
    path-style: true                       # MinIO / self-hosted
    access-key: ${S3_ACCESS_KEY}
    secret-key: ${S3_SECRET_KEY}
    domain: https://cdn.example.com        # optional public URL

For the full property list, storage path rules and frontend behaviour see Erupt S3 → Attachment Upload.

S3 Compatibility by Cloud Provider ​

S3AttachmentProxy relies on only four basic S3 calls — PutObject (single-shot, no multipart), HeadObject, ListObjectsV2 and DeleteObject — signed with SigV4. Any service implementing those works out of the box, so the bar is low. The table grades providers by whether erupt-data-s3 can be used directly:

  • ✅ Native / compatible: fill in endpoint, region and credentials and go
  • ⚠️ Partial: works, but with prerequisites or known limitations
  • ❌ Not supported: no S3 API; implement AttachmentProxy yourself

China

ProviderCompatibilityendpoint exampleregionpath-styleNotes
Alibaba Cloud OSS✅ Compatiblehttps://oss-cn-hangzhou.aliyuncs.comcn-hangzhoufalseVirtual-hosted addressing only; path-style must be false
Tencent Cloud COS✅ Compatiblehttps://cos.ap-guangzhou.myqcloud.comap-guangzhoufalseBoth addressing styles supported; virtual-hosted recommended
Huawei Cloud OBS✅ Compatiblehttps://obs.cn-north-4.myhuaweicloud.comcn-north-4falseBoth addressing styles supported
Baidu AI Cloud BOS✅ Compatiblehttps://s3.bj.bcebos.combjfalseUse the dedicated S3 domain (with the s3. prefix)
Qiniu Kodo✅ Compatiblehttps://s3.cn-east-1.qiniucs.comcn-east-1falseEnable S3-compatible access in the console; the legacy SDK approach is shown in the example below
Volcengine TOS✅ Compatiblehttps://tos-s3-cn-beijing.volces.comcn-beijingfalseUse the dedicated S3 domain (with the tos-s3- prefix)
JD Cloud OSS✅ Compatiblehttps://s3.cn-north-1.jdcloud-oss.comcn-north-1false
UCloud US3✅ Compatiblehttps://s3-cn-bj.ufileos.comcn-bjfalse
Kingsoft Cloud KS3⚠️ PartialS3 endpoint from the consoleFrom the consolefalseSigV4 support is incomplete in some regions; verify with a test bucket first
China Telecom ZOS⚠️ PartialS3 endpoint from the consoleFrom the consolefalseEndpoint format differs between regions
Upyun USS❌ Not supported———Proprietary REST API; implement AttachmentProxy yourself

International

ProviderCompatibilityendpoint exampleregionpath-styleNotes
AWS S3✅ Nativeleave emptyus-east-1falseLeave access-key empty to use an IAM role
Cloudflare R2✅ Compatiblehttps://<account-id>.r2.cloudflarestorage.comautotrueBuckets are private by default; bind a custom domain or enable r2.dev and set it as domain
Backblaze B2✅ Compatiblehttps://s3.us-west-004.backblazeb2.comus-west-004true
DigitalOcean Spaces✅ Compatiblehttps://nyc3.digitaloceanspaces.comnyc3false
Wasabi✅ Compatiblehttps://s3.us-east-1.wasabisys.comus-east-1false
Linode / Akamai✅ Compatiblehttps://us-east-1.linodeobjects.comus-east-1false
Scaleway✅ Compatiblehttps://s3.fr-par.scw.cloudfr-parfalse
Oracle OCI✅ Compatiblehttps://<namespace>.compat.objectstorage.<region>.oraclecloud.com<region>trueUse a Customer Secret Key
IBM Cloud COS✅ Compatiblehttps://s3.us-south.cloud-object-storage.appdomain.cloudus-southfalseRequires HMAC credentials
Google Cloud Storage⚠️ Partialhttps://storage.googleapis.comautotrueXML API interoperability mode; requires HMAC keys, some advanced features unavailable
Azure Blob Storage❌ Not supported———No native S3 API; implement AttachmentProxy yourself or put an S3 gateway in front

Self-hosted / open source

ServiceCompatibilityendpoint exampleregionpath-style
MinIO✅ Compatiblehttp://minio.internal:9000any non-emptytrue
Ceph RGW✅ Compatiblehttp://rgw.internal:7480any non-emptytrue
SeaweedFS✅ Compatiblehttp://seaweed.internal:8333any non-emptytrue
Garage / RustFS✅ Compatibleyour deployment URLany non-emptytrue

Check the console for the exact endpoint

The endpoints above are the providers' common formats; regions and domain suffixes change over time, so use the S3-compatible endpoint shown in the provider console. For non-AWS providers region only feeds the signature — any non-empty value usually works; the table lists the officially recommended one.

Public attachment URL

The browser loads attachments from domain + path, so the bucket (or the CDN in front of it) must allow public reads. Chinese providers usually expose a "public read" switch on the bucket; put the CDN domain into domain. Services that are private by default (R2, OCI, ...) need a custom domain bound first.

Local Storage Configuration ​

Without an AttachmentProxy implementation, attachments are stored on the local disk. The relevant properties live in EruptProp:

PropertyTypeDefaultDescription
erupt.upload-pathString/opt/erupt-attachmentRoot directory for attachment storage
erupt.keep-upload-file-namebooleanfalseWhether to preserve the original filename of uploaded files
yaml
erupt:
  upload-path: /opt/erupt-attachment
  keep-upload-file-name: false

erupt.upload-path ​

The root directory attachments are written to, and also the static-resource directory that the /erupt-attachment/** access path is mapped to.

  • The default is /opt/erupt-attachment. That absolute path usually does not exist on Windows or in a local development environment, so set it explicitly to a writable directory on your machine.
  • A classpath: prefix is supported, in which case the mapping is resolved as a classpath resource (generally only useful for read-only bundled assets).
  • Both upload and download normalize the resolved path and verify that it does not escape this root; requests that do are rejected outright.

erupt.keep-upload-file-name ​

Controls the filename part of the generated storage path. In both modes the directory prefix is the current date (yyyy-MM-dd):

ValueExample generated pathDescription
false (default)/2026-08-30/aBcDeFgHiJkL.pngThe filename is replaced with 12 random letters; only the original extension is kept
true/2026-08-30/annual-report.pngThe original filename is preserved, with &, #, ? and whitespace stripped out

Evaluate before enabling

With keep-upload-file-name = true, files with identical names overwrite each other, and the filename comes from user input. The default random-filename mode is safer — do not enable this unless your business genuinely needs downloads under the original name.

Both properties affect local storage only. If you implement AttachmentProxy and isLocalSave() returns false, nothing is written to upload-path; the storage path (date directory plus filename) is still derived from keep-upload-file-name and passed to upLoad() as the path argument.

Interface Reference ​

@EruptAttachmentUpload Annotation ​

Add this annotation to your Spring Boot entry class, specifying the AttachmentProxy implementation:

java
@EruptAttachmentUpload(QiniuOosProxy.class)
@SpringBootApplication
public class EruptDemoApplication {

    public static void main(String[] args) {
        SpringApplication.run(EruptDemoApplication.class, args);
    }

}

Annotation definition:

java
// Just implement AttachmentProxy to customize attachment storage — e.g. upload to fastDFS or OSS
public @interface EruptAttachmentUpload {
    Class<? extends AttachmentProxy> value();
}

AttachmentProxy Interface ​

java
public interface AttachmentProxy {

    /**
     * @param inputStream file data stream
     * @param path        upload path
     * @return storage path — in most cases, return the path parameter as-is
     */
    String upLoad(InputStream inputStream, String path);

    /**
     * Base URL for accessing attachments over the network
     */
    String fileDomain();

    /**
     * Whether to also save the file locally
     */
    default boolean isLocalSave() {
        return true;
    }
}

Implementing AttachmentProxy Yourself (non-S3 storage) ​

When the storage service has no S3-compatible API, implement the AttachmentProxy interface to plug in any backend. The example below uses the Qiniu SDK (Qiniu Kodo now speaks S3, so real projects can use erupt-data-s3 directly; the SDK version is kept as a reference for custom implementations).

1. Add Dependency ​

xml
<dependency>
    <groupId>com.qiniu</groupId>
    <artifactId>qiniu-java-sdk</artifactId>
    <version>[7.2.0, 7.2.99]</version>
</dependency>

2. Implement AttachmentProxy ​

Create QiniuOosProxy.java:

java
/**
 * Qiniu object storage demo
 *
 * @author yuepeng
 * @date 2020-05-17
 */
@Service
public class QiniuOosProxy implements AttachmentProxy {

    @Value("${qiniu.access_key}")
    private String accessKey; // Qiniu ACCESS_KEY

    @Value("${qiniu.secret_key}")
    private String secretKey; // Qiniu SECRET_KEY

    @Value("${qiniu.bucket}")
    private String bucket; // bucket name

    @Override
    public String upLoad(InputStream inputStream, String path) {
        UploadManager uploadManager = new UploadManager(new Configuration(Region.huanan()));
        String uploadToken = Auth.create(accessKey, secretKey).uploadToken(bucket);
        // Strip leading slash to avoid double-slash in the access URL
        path = path.startsWith("/") ? path.substring(1) : path;
        try {
            Response response = uploadManager.put(inputStream, path, uploadToken, null, MimeUtil.getMimeType(path));
            if (!response.isOK()) {
                throw new EruptWebApiRuntimeException("Failed to upload to Qiniu storage");
            }
            return "/" + path;
        } catch (QiniuException ex) {
            throw new EruptWebApiRuntimeException(ex.response.toString());
        }
    }

    @Override
    public boolean isLocalSave() {
        return false;
    }

    @Override
    public String fileDomain() {
        return "http://oos.erupt.xyz";
    }
}

3. Register the Annotation ​

java
@SpringBootApplication
@EruptAttachmentUpload(QiniuOosProxy.class)
public class EruptDemoApplication {

    public static void main(String[] args) {
        SpringApplication.run(EruptDemoApplication.class, args);
    }

}

4. Configure the Frontend Access URL ​

Since the attachment base URL has changed, update app.js:

javascript
window.eruptSiteConfig.fileDomain = "http://xxxx.com"; // Your OSS domain

Since 2.3.0, /erupt-app returns AttachmentProxy.fileDomain() and the frontend adopts it automatically when eruptSiteConfig.fileDomain is empty, so this step can be skipped; a value set in app.js still acts as an explicit override.

Contributors

The avatar of contributor named as YuePeng YuePeng

Changelog

Released under the Apache-2.0 License.