n8n-nodes-volcengine-tos

English | 中文

🚀 Built with Trae IDE Vibe Coding - Welcome to use and submit Issues!

✨ Features

• 🔥 10+ Operations: Complete VolcEngine TOS automation with file and bucket management
• 🔐 Pre-signed URLs: Secure file access with configurable expiration times
• 🧪 High Quality: 94.77% test coverage with 139 unit tests
• 🌐 Bilingual: Full English and Chinese documentation
• ⚡ Type Safe: Built with TypeScript for better development experience
• 📦 Easy Setup: Zero configuration, works out of the box

This is an n8n community node that lets you use VolcEngine TOS (Torch Object Storage) in your n8n workflows.

VolcEngine TOS is a secure, durable, and highly scalable cloud storage service provided by ByteDance's VolcEngine platform. It offers object storage capabilities for storing and retrieving any amount of data from anywhere.

n8n is a fair-code licensed workflow automation platform.

Installation
Operations
Credentials
Compatibility
Usage
Resources

Installation

Follow the installation guide in the n8n community nodes documentation.

Package name: n8n-nodes-volcengine-tos

Operations

The VolcEngine TOS node supports the following operations:

File Operations

• Check File Existence: Check if a file exists in the specified bucket and get its metadata
• Upload File: Upload a binary file to VolcEngine TOS bucket with optional public access configuration
• Download File: Download a file from VolcEngine TOS bucket
• Delete File: Delete a file from VolcEngine TOS bucket
• Copy File: Copy a file within VolcEngine TOS (same or different buckets)
• List Files: List files in a VolcEngine TOS bucket with optional prefix filtering
• Get Pre-Signed URL: Generate a pre-signed URL for secure file access with configurable expiration time

Bucket Operations

• Create Bucket: Create a new VolcEngine TOS bucket
• Delete Bucket: Delete an existing VolcEngine TOS bucket
• List Buckets: List all available VolcEngine TOS buckets

Credentials

To use this node, you need to set up VolcEngine TOS API credentials:

Prerequisites

1. Sign up for a VolcEngine account at volcengine.com
2. Create a TOS bucket in the VolcEngine console
3. Generate Access Key ID and Secret Access Key

Authentication Setup

1. In n8n, go to Credentials and create new VolcEngine TOS API credentials
2. Fill in the following information:
   • Access Key: Your VolcEngine Access Key ID
   • Secret Key: Your VolcEngine Secret Access Key
   • Bucket: Your TOS bucket name
   • Endpoint: Your TOS service endpoint (e.g., tos-s3-cn-beijing.volces.com)
   • Region: Your bucket region (e.g., cn-beijing)

Compatibility

• Minimum n8n version: 0.198.0
• Node.js version: >=20.15
• Tested with: n8n 1.x

This node uses the official @volcengine/tos-sdk (v2.7.5) for reliable integration with VolcEngine TOS.

Usage

Check File Existence

1. Select "Check Existence" operation
2. Provide the file path in the bucket
3. The node will return whether the file exists along with file URL and metadata

Upload File

1. Select "Upload File" operation
2. Specify the target file path in the bucket
3. Choose the binary property containing the file data
4. Optionally enable "Make Public" to set public-read ACL
5. The node will upload the file and return the file URL and upload details

Download File

1. Select "Download File" operation
2. Provide the file path in the bucket
3. The node will download the file and return it as binary data

Copy File

1. Select "Copy File" operation
2. Specify the source file path
3. Specify the destination file path
4. The node will copy the file and return operation details

List Files

1. Select "List Files" operation
2. Configure optional parameters:
   • Prefix Filter: Filter files by prefix (e.g., "images/" to list only files in images folder)
   • Maximum Number: Limit the number of files returned (default: 1000)
   • Delimiter: Group files by common prefixes (useful for folder-like structure)
   • Marker: Start listing from a specific file (for pagination)
3. The node returns an enhanced output format:
   • files: Array of file objects with metadata
   • folders: Array of folder prefixes
   • totalFiles: Count of files returned
   • totalFolders: Count of folder prefixes
   • Legacy fields (objects, commonPrefixes) are maintained for backward compatibility

Get Pre-Signed URL

1. Select "Get Pre-Signed URL" operation
2. Provide the file path in the bucket
3. Choose HTTP method (GET for download/view, PUT for upload)
4. Set expiration time in seconds (default: 1800 = 30 minutes)
5. Optionally specify version ID, content type, or content disposition
6. The node will generate a secure pre-signed URL for temporary file access

Bucket Management

• Create Bucket: Specify bucket name and optional configuration
• Delete Bucket: Specify bucket name to delete
• List Buckets: Get all available buckets with metadata

Error Handling

The node includes comprehensive error handling with user-friendly error messages and supports n8n's "Continue on Fail" option for robust workflow execution.

Testing

Unit Tests

The project includes comprehensive unit tests for all operations:

# Run all unit tests (excludes integration tests)
npm test -- --testPathIgnorePatterns=".*\.integration\.test\.ts$"

# Run specific operation tests
npm test -- --testPathPattern="ListBucketsOperation\.test\.ts$"

Test Coverage: 12 test suites, 80 unit tests covering all operations and error scenarios.

Integration Tests

Integration tests require real VolcEngine TOS credentials:

# Set up environment variables
export VOLCENGINE_ACCESS_KEY="your-access-key"
export VOLCENGINE_SECRET_KEY="your-secret-key"
export VOLCENGINE_BUCKET="your-test-bucket"
export VOLCENGINE_REGION="cn-north-1"  # optional
export VOLCENGINE_ENDPOINT=""  # optional

# Run integration tests
npm test -- --testPathPattern="VolcEngineTosNode\.integration\.test\.ts$"

# Run all tests (unit + integration)
npm test

Note: Integration tests will fail without valid credentials, but unit tests ensure code quality and functionality.

Architecture

The project follows a modular architecture:

• Modular Operations: Each TOS operation is implemented as a separate class
• Factory Pattern: OperationFactory manages operation instantiation
• Centralized Error Handling: TosErrorHandler provides consistent error management
• Type Safety: Full TypeScript implementation with proper interfaces
• Base Operation: Abstract BaseOperation class for common functionality

Resources

• n8n community nodes documentation
• VolcEngine TOS Documentation
• VolcEngine TOS SDK Documentation
• Project Repository