Skip to content

Erupt File Center ​

erupt-file-center puts a file center inside the admin: the attachment upload directory, any folder on the server, S3 buckets and SFTP directories, browsed in Finder-style columns with an inline preview of images, video, audio, PDF and text. The page uploads (drag-and-drop included), creates folders, renames, deletes, downloads, and copies a file's public link.

Minimum version: 2.4.0

Setup ​

xml
<dependency>
  <groupId>xyz.erupt</groupId>
  <artifactId>erupt-file-center</artifactId>
  <version>${erupt.version}</version>
</dependency>

erupt-spring-boot-starter-all already includes this module, so projects on starter-all need not add it. The module depends on erupt-upms; its two other dependencies are optional:

  • The S3 store needs erupt-data-s3 on the classpath (it brings the AWS S3 SDK)
  • The SFTP store needs JSch (com.github.mwiede:jsch), which erupt-remote already ships; a project without erupt-remote adds it next to this module

Auto configuration registers two menus: File Center (menu type router, value /file-center, which is erupt-web's route of the same name) and a Write button under it. Everything the page does goes through this module's API under /erupt-api/file-center.

Stores ​

The dropdown at the top left of the page lists every store, in this fixed order:

StoreWherePublic link
Uploadserupt.upload-path, the directory attachment fields write to/erupt-attachment/...
erupt.file-center.rootsany folder on the servernone, download through the page
S3 · bucketthe bucket attachments go to (erupt.s3), present when erupt-data-s3 is on the classpath and a bucket is configuredthe bucket URL or erupt.s3.domain
erupt.file-center.storesany number of local folders, buckets or prefixes with their own keys, and SFTP directoriesthe bucket URL or the store's domain; none for local folders and SFTP

The first two only take a path; the erupt.s3 bucket reuses erupt-data-s3's configuration, so no keys are repeated here. Every entry under stores has its own type (local / s3 / sftp, default local) and its own connection settings:

yaml
erupt:
  file-center:
    roots:                         # extra local folders, keyed by the name the page shows
      Reports: /data/reports
    stores:
      - name: Backups
        type: local
        path: /var/backups
      - name: Media
        type: s3
        bucket: media
        endpoint: https://oss-cn-hangzhou.aliyuncs.com   # MinIO, OSS, COS, R2: any S3 API
        region: cn-hangzhou
        access-key: ${MEDIA_AK}
        secret-key: ${MEDIA_SK}
        path-style: false
        prefix: public             # the store's root inside the bucket
        domain: https://cdn.example.com
      - name: Partner SFTP
        type: sftp
        host: sftp.example.com
        port: 22
        username: exchange
        password: ${SFTP_PASSWORD}
        path: /outbound            # the remote directory that is the store's root
        known-hosts: /etc/ssh/ssh_known_hosts
    text-preview-bytes: 262144

S3 stores ​

prefix turns one prefix inside a bucket into the store's root; / in keys is read as folders. domain is used for public links; without it the link is built from the bucket URL (path-style keeps the bucket in the path, virtual-hosted puts it in front of the host). A new folder is written as an empty object whose key ends in /; renaming a folder copies and then deletes every object under it, so expect a large folder to take a while.

SFTP stores ​

type: sftp is rooted at the remote directory path and logs in with a password or a private key: private-key is either PEM text or the path of a key file, with passphrase alongside; when a private key is set only public-key authentication is tried, otherwise the password. With known-hosts pointing at a known_hosts file the server's host key is verified (StrictHostKeyChecking); without it any host key is accepted. The module keeps one SSH session open and reconnects when it drops; every operation runs on a channel of its own, so a large download never blocks someone else's listing.

WARNING

Set known-hosts in production; without it there is no protection against a man-in-the-middle.

Using the Page ​

Columns Opening a folder shows its contents in a new column to the right, so the columns read as the full path; the breadcrumb at the top jumps back up. ↑ ↓ move within the current column, → enters the selected folder, ← closes the current column and steps back. The search box above the rightmost column filters the current directory only.

File Center column browsing and preview

Preview Selecting a file fills the panel on the right according to its type: images, video and audio play inline, PDF is embedded, and text (text/*, JSON / XML / YAML / CSV / SQL, plus common source extensions such as .md .log .properties .java) is shown as content; a text file larger than text-preview-bytes only shows "Too large to preview". The panel also lists size, modified time and type, and its width can be dragged.

ActionDescription
UploadPick files with the toolbar button, or drop them on a column to upload into that directory; an existing file of the same name is overwritten
New folderCreated in the current directory; the name may not contain /
RenameWithin the same directory only; the name may not contain /
DeleteMulti-select; a folder goes with everything in it, after a confirmation
DownloadThe browser downloads the previewed file
OpenOpens the file itself in a new tab
Copy linkCopies the file's public URL; only for stores that have one (Uploads and S3)

Every path is normalized on the server first (\ to /, empty segments and . dropped) and any .. is refused; local stores additionally check that the resolved absolute path still lies inside the root. No request can climb out of a store, and a store's root itself cannot be deleted.

Endpoints ​

All endpoints live under /erupt-api/file-center and use menu authorisation against the File Center menu (@EruptRouter(verifyType = MENU)). store is the store name and path a store-relative path starting with /:

EndpointDescription
GET /infoWhat the page needs first: the stores, whether this user may write, and textPreviewBytes
GET /list?store=&path=Directory listing, folders first then files, each sorted by name
GET /stat?store=&path=One entry with its public link
GET /raw?store=&path=&download=&_token=The file itself, for previews and downloads; opened by the browser, so the token travels as _token
POST /upload?store=&path=Form field files, uploaded into the given directory
POST /mkdir?store=&path=&name=New folder
POST /rename?store=&path=&name=Rename
POST /delete?store=Body is a list of paths

Permissions ​

The file center is one menu plus one Write button under it (value file-center@write):

  • A role with the File Center menu may browse, preview and download; every endpoint is authorised against this menu
  • Upload, new folder, rename and delete also need the Write button; without it the page is read only, the buttons are disabled, and the server refuses as well ("No write permission")

Write access applies to every store alike. For finer control, a custom store can decide per user and throw.

Properties ​

PropertyDefaultDescription
erupt.file-center.rootsnoneExtra local folders as a name: path map; the name is what the page shows
erupt.file-center.storesnoneList of stores, fields below
erupt.file-center.text-preview-bytes262144 (256 KB)The most of a text file the preview reads; larger files are not previewed

Fields of each stores entry, by type:

FieldTypeDescription
nameallRequired; the name the page shows and the store parameter of the API; a later duplicate replaces the earlier one
typealllocal (default) / s3 / sftp
pathlocal / sftpThe local folder, or the remote directory that is the SFTP root; required
host port usernamesftpHost, port (default 22) and user; host and username are required
passwordsftpPassword login
private-key passphrasesftpKey login: PEM text or a key file path, and its passphrase
known-hostssftpPath of a known_hosts file; the host key is verified only when set
buckets3Required
regions3Default us-east-1
endpoints3Endpoint of a non-AWS service; blank means AWS
access-key secret-keys3Access keys; blank falls back to the SDK's default credential chain
path-styles3Path-style addressing, usually true for MinIO and other self-hosted services
prefixs3Prefix inside the bucket that becomes the store's root
domains3Domain used for public links

TIP

The erupt.s3 attachment bucket already appears as "S3 · bucket" and need not be repeated under stores; stores is for another bucket, another prefix of the same bucket, or a bucket with different keys.

Custom Stores ​

The store abstraction is the xyz.erupt.filecenter.store.FileStore interface; paths are always store-relative, with / as the root. Any Spring bean implementing it joins the list automatically, after the configured stores:

java
@Component
public class ArchiveStore implements FileStore {

    @Override
    public String name() {
        return "Archive";
    }

    @Override
    public List<FileEntry> list(String dir) throws IOException {
        // the directory's contents: folders first, then files, each sorted by name
    }

    @Override
    public FileEntry stat(String path) throws IOException {
        // null when nothing is there
    }

    @Override
    public InputStream read(String path) throws IOException { ... }

    @Override
    public void write(String path, InputStream content, long size, String contentType) throws IOException { ... }

    @Override
    public void mkdir(String path) throws IOException { ... }

    @Override
    public void rename(String path, String newName) throws IOException {
        // renames within the same directory
    }

    @Override
    public void delete(String path) throws IOException {
        // a directory goes with everything in it
    }

    @Override
    public String publicUrl(String path) {
        // where a browser can load the file from directly, or null (the default)
        return null;
    }

}

FileEntry is one listing row: name, path (starts with /, no trailing / for a directory), dir, size, modified (epoch millis, nullable) and contentType. The static helpers on the interface are there to reuse: FileStore.normalize(path) normalizes and refuses .., FileStore.join(dir, name) validates a name and appends it, FileStore.parentOf / FileStore.nameOf split a path. A read-only store simply throws an IOException from its write methods; the page shows the message to the user.

Contributors

The avatar of contributor named as YuePeng YuePeng

Changelog

Released under the Apache-2.0 License.