Storage
Feature Overview
Storage manages files within a project. Create buckets, configure access permissions, file size limits and allowed extensions, and upload or read files through the console or an SDK. Compression, encryption, and moderation options depend on the deployed environment.
For example, a project can use separate buckets for documents and media attachments, with bucket and file permissions set according to its access needs. Bucket names and data in this guide are examples and do not imply these resources exist in any environment.
Core Concepts and Architecture
Agentbase Storage adopts a complete architecture of "bucket policy isolation → chunked upload and security pipeline (extension/size validation, antivirus, encryption, compression, content moderation) → dual-layer authorization gateway (Bucket Permissions + File Security + File Tokens + Client File Listing Gate) → multimodal and knowledge base integration".
Core Concepts and Bucket Attribute Descriptions
| Core concept | Attribute names and default values | Architectural semantics and production behavior description |
|---|---|---|
| Bucket | kb_enterprise_docs, agent_multimedia_bucket | The top-level logical container for files and the boundary of security policies. Each Bucket is independently configured with enable/disable status (enabled), permission list, size limit, allowed extensions, compression algorithm, encryption, antivirus, and image moderation policies. |
| File security | fileSecurity (Default: Off) | • When off: only Bucket Permissions take effect, and permission settings on individual files are ignored. • When on: bucket-level and file-level permissions are evaluated with logical OR — a user can access the file as long as they satisfy the bucket permissions or one of the file-level permissions on that specific file. |
| Client file listing | clientFileListing (Default: On) | Fully decouples “listing the complete file inventory of a bucket (listFiles)” from “accessing an individual file by a known file ID / URL”:• When set to off ( false): any listFiles request made by an unauthenticated, anonymous, or ordinary end-user Session/JWT returns 401 user_unauthorized, completely preventing clients from enumerating all files in the bucket; however, file uploads and access to public or authorized images via known links/tokens are unaffected, API key and privileged project-management identities are exempt from this switch but must still meet applicable authentication and authorization requirements. |
| Chunked Upload | Pending Status → Completion | When uploading large files (over 5 MB), the SDK automatically splits the file into chunks and uploads them sequentially with the Content-Range header, supporting resumable uploads; before all chunks are fully merged, the file displays an Pending badge in the list and its details are inaccessible. |
| File Tokens | ?token=<SECRET> (signed JWT) | Without opening bucket-level/file-level public permissions, issue login-free shareable access links with expiration times (such as 7 Days, 30 days, Never, or a custom date) for specific private files. Once a token is deleted or its expiration time is reached, the corresponding link becomes invalid immediately. |
| Storage mode compatibility | Shared V2 & JsonTable | Configured bucket metadata and file directories fully support both Shared V2 and JsonTable project storage modes, and automatically migrate all attributes losslessly (including clientFileListing) when switching modes in ProjectTableModeConversion. |
Roles, Entry Points, and Relationships
Console Entry and Routes
Main navigation path: Sign in to the console → select a project → select Storage under Infrastructure in the sidebar.
Route addresses:
Bucket list and top-level usage page:
/console/project-{region}-{project}/storage(with two top-level tabs: Buckets and Usage).Individual bucket detail page:
/console/project-{region}-{project}/storage/bucket-{bucketId}(with four sub-tabs: Files, Usage, Moderation, Settings).Standalone file upload wizard page:
/console/project-{region}-{project}/storage/bucket-{bucketId}/createIndividual file detail and token management page:
/console/project-{region}-{project}/storage/bucket-{bucketId}/file-{fileId}
Operation permission gates:
Managing buckets in the Console (create/modify/delete buckets) requires organization roles with
buckets.read/buckets.writepermissions (owner,admin,developer,editor; without write permission, the Settings tab on the bucket detail page is automatically hidden).Managing files within a bucket via the Console or Server SDK requires
files.read/files.writepermissions.
Relationship with Knowledge Base and Multimodal Memory
Knowledge base document storage: The knowledge base stores source documents for its processing pipeline. Antivirus and encryption depend on the environment, storage device, bucket configuration, and file size; verify the conditions below.
Multimodal Memory and vision model integration: When an agent needs to call the
qwen-vl-maxvision model to analyze user-uploaded architecture diagrams or error screenshots, the frontend first securely uploads the image toagent_multimedia_bucket; after it passes the built-in image content moderation, it is handled by Multimodal Memory and the model gateway via the file access URL or File Token.Controlled access from Cloud Functions: When accessing Storage inside the Cloud Functions runtime, the project context and function execution identity are inherited automatically, allowing secure read/write access to files in protected buckets.
Feature Details and Operation Guide
1. Create and view buckets
In the project sidebar, select Infrastructure → Storage, then open Buckets to search and view the project's buckets.
Figure 1: Bucket list in a 2.12.0 environment. The sample bucket ID is masked.
Steps to create a bucket
Click Create bucket. If the button is unavailable, check the account's bucket write permission.
Enter a Name and optionally a custom Bucket ID. The ID can have up to 36 characters, must begin with a letter or digit, and can otherwise contain letters, digits, periods, hyphens, and underscores. Leave it blank to generate one.
Set Allow clients to list files as needed. It is enabled by default in the new bucket dialog. When disabled, listing requires an authorized server or project management identity; uploads and individual file access retain their own permissions.
Click Confirm. After creation succeeds, the bucket detail page opens, where you can upload files or adjust settings.
2. Full explanation of all Bucket Settings parameters
Go to the bucket detail page and switch to the Settings tab, where administrators can adjust the bucket's access control, compression/encryption, and anti-enumeration policies card by card:
Figure: Bucket settings in a 2.12.0 test project. Configure them for your access and security requirements.
The table below details the parameter rules, technical boundaries, and recommended configurations in the two example buckets enterprise-ai-hub-210 for every configuration card on the Settings page:
| Settings card name | Configuration options and values | kb_enterprise_docs Recommended configuration | agent_multimedia_bucket Recommended configuration | Technical rules and boundary notes |
|---|---|---|---|---|
| Enabled (enable status) | Boolean toggle (On / Off) | On | On | When off, ordinary application users cannot access the bucket. API key identities and privileged project-management identities are exempt from this switch but must still meet applicable authentication and authorization requirements. Turning it off does not delete files. |
| Name (bucket name) | String (1–128 characters) | 企业知识库原始文档存储桶 | 智能体多模态媒体与工单附件桶 | Changing the bucket display name does not affect Bucket ID or any previously generated File URLs. |
| Permissions (bucket-level permissions) | Add Create / Read / Update / Delete to Roles | Read: Role.team('team_kb_governance')Write: Role.team('team_kb_governance', 'reviewer') | Create: Role.users('verified')Read: Role.team('team_support_ops') | Supports selecting Any, Guests, Users, specifying User, Team + Role, Label, or writing custom role expressions in the editor. |
| File security | Boolean toggle (On / Off) | On | On | When off: only bucket-level permissions take effect, and individual file permissions are ignored. When on: access is granted by satisfying the bucket permissions or one of the individual file permissions. Toggling the switch takes effect immediately for authentication on all files in the bucket! |
| Security settings (encryption and antivirus) | Encryption (encryption at rest) Antivirus (ClamAV virus scanning) | Both On | Both On | Files are first written to the storage device; post-processing occurs after all chunks complete. Antivirus additionally requires the environment and bucket to enable it, a local storage device, and a file size at most 20,000,000 bytes. Application-level encryption applies only up to 20,000,000 bytes. Verify deployment configuration; enabling the bucket switches does not guarantee every file is scanned or encrypted. |
| Compression (compression algorithm) | Dropdown: None / Gzip / Zstd | Zstd (high compression ratio, extremely fast decompression) | None (images/audio/video are already compressed) | Enabling Zstd or Gzip is recommended for Markdown, JSON, text, and uncompressed documents; large files automatically skip real-time compression. |
| Image transformations | Boolean toggle (On / Off) | Off (document-only buckets need no image transformations) | On | When on, clients may use the getFilePreview endpoint to perform real-time resizing, cropping, rounded corners, background color, and format conversion on images in the bucket. |
| Maximum file size (per-file size limit) | Number + unit (Bytes / KB / MB / GB, converted in 1000 base) | 50 MB | 20 MB | Note: this value limits the maximum size of a single uploaded file (constrained by the plan's fileSize hard cap), not the total storage capacity quota of the entire project. |
| Allowed file extensions (extension allowlist) | List of extension tags (up to 100 items, without leading dots) | md, pdf, docx, txt, html, csv | jpg, png, webp, gif, mp4, mp3 | The interface provides jpg, png, svg, gif, html, pdf, mp4 quick tags; leaving it empty allows uploading files with any extension. |
| Client file listing | Boolean toggle (default: On) | On (for authorized knowledge governance teams) | Off (restricts ordinary application clients) | When off, anonymous and ordinary application users receive 401 user_unauthorized on listFiles. API key identities and privileged project-management identities are exempt from this switch but must still meet applicable authentication and authorization requirements; an ordinary application team owner is not automatically a project manager. Upload and single-file access remain subject to their own permissions. |
| Delete bucket | Red Delete button in the bottom danger zone | Only when decommissioning | Only when decommissioning | Permanent and irreversible: check the target bucket, its files, and tokens before confirming deletion. |
3. Bucket-level image content moderation and Fail-Closed protection
For buckets open to external uploads (such as agent_multimedia_bucket), enable image moderation as needed and restrict public access according to your requirements. Switch to the bucket details Moderation tab:
Enable the bucket-level image content moderation switch and configure risk interception policies (for more global moderation rules, see Content Moderation (Moderation)).
Fail-Closed strict boundary (upload rejected means cleanup):
When a user uploads an image to a bucket with Moderation enabled, the system synchronously calls the moderation service in the upload path.
When an image violates policy, exceeds the moderation limit, cannot be read, or the service is unavailable, the upload request fails. The server attempts to remove written files and associated records when the relevant cleanup step is reached. Earlier errors can prevent cleanup, and cleanup itself can fail; check errors and logs for the actual state.
Privacy compliance auditing: the moderation audit log records only a safe filename preview and the verdict, never the raw image byte stream or Base64-encoded content.
4. Upload file (Create file), chunked resumable upload, and image conversion preview
(1) Steps to upload a file in the Console
Go to the Files tab of the target bucket (such as
kb_enterprise_docs), click Create file in the upper-right corner to enter the upload wizard page (/storage/bucket-{bucketId}/create).Select the file and specify a File ID (Data section):
Drag and drop or click to select a local file (such as
OceanBase分布式事务与向量索引排障指南.md). The client pre-validates locally whether the file extension matches the bucket's Allowed file extensions whitelist; however, the maximum file size is enforced by the server, and files exceeding the limit are rejected by the server at upload time.Optionally expand File ID to define a custom unique file identifier (or leave it blank to auto-generate).
Configure per-file permissions (Permissions section):
If the current bucket has File security enabled, this section shows
"File security enabled", and you can add access roles for this file individually (such asRole.user('user_zhangwei_001')orRole.team('team_support_ops')).If it is not enabled, this section shows
"File security disabled"; you must first enable it in the bucket's Settings before per-file permissions can be used.
After clicking create, the page returns to the file list and shows
"File upload in progress"(before a large file's chunked upload completes, aPendingbadge is displayed; closing the browser tab at this point triggers an anti-loss interception confirmation).
(2) Uploading files via SDK and getting real-time image conversion previews (getFilePreview)
The following example shows how to use agentbase-web-sdk@2.12.0 to upload a support ticket screenshot to agent_multimedia_bucket and generate a thumbnail preview URL with the specified width, height, and WebP format:
Before running, replace <APPBASE_ENDPOINT_WITH_V1> and <APPBASE_PROJECT_ID> with the confirmed target API endpoint and project ID. Until replaced, the SDK rejects the invalid endpoint before making a request.
import { Client, Storage, ID, Permission, Role, ImageGravity, ImageFormat } from 'agentbase-web-sdk'; // Pin version @2.12.0
const client = new Client()
.setEndpoint('<APPBASE_ENDPOINT_WITH_V1>')
.setProject('<APPBASE_PROJECT_ID>');
const storage = new Storage(client);
// 1. Upload the support ticket error screenshot (when the file is > 5MB the SDK automatically switches to chunked upload and reports progress)
const uploadedFile = await storage.createFile(
'agent_multimedia_bucket',
ID.unique(),
document.getElementById('ticketScreenshotInput').files[0],
[
// The submitting customer Zhang Wei himself and the VIP technical support team can read
Permission.read(Role.user('user_zhangwei_001')),
Permission.read(Role.team('team_support_ops')),
Permission.delete(Role.user('user_zhangwei_001'))
],
(progress) => {
console.log(`上传进度: ${progress.progress}% (${progress.chunksUploaded}/${progress.chunksTotal} 块)`);
}
);
// 2. Generate a real-time image transformation preview link (requires the bucket to have Image transformations enabled)
// Center-crop and scale the original image to 800x600 at quality 85%, automatically converting to the high-compression webp format
const previewUrl = storage.getFilePreview(
'agent_multimedia_bucket',
uploadedFile.$id,
800, // width (pixels)
600, // height (height in pixels)
ImageGravity.Center, // gravity (crop focal point)
85, // quality (1-100 compression quality)
0, // borderWidth
'', // borderColor
8, // borderRadius (corner radius in pixels)
1, // opacity
0, // rotation
'FFFFFF', // background
ImageFormat.Webp // output (output format converted to webp)
);5. File details and login-free secure sharing with File Tokens
Click any file in the file list to enter its detail page (/storage/bucket-{bucketId}/file-{fileId}), where you can view the file's thumbnail preview, MIME type, size, and creation time, and copy the File URL, click Download to download the original file, or modify per-file permissions (note: in the current version, the Console does not support renaming uploaded files; the filename is fixed at upload time).
When you need to temporarily share a private file (such as a support ticket diagnostic report or an architecture whitepaper PDF) with an external partner who has no project account, or provide it for an external LLM API to fetch, you can use File tokens:
Find the File tokens card at the bottom of the file detail page (note:
"Use tokens to provide public access to the file."), and click Create token.Set the expiration time (Expiration): choose a preset option Never (never expires) / 7 Days / 30 days / 90 days / 1 Year, or select Custom Date to specify an exact expiry date (the earliest is the next day).
Copy the access link with the signed token (Copy URL):
In the token list row, click Copy URL; the popup provides three dedicated tabs: Preview (image conversion preview link), View (open inline in browser link), and Download (trigger attachment download link), with
...&token={secret}automatically appended to the end of the URL.Any visitor holding the complete URL can access the file normally, even when not logged in and lacking bucket/file ACL permissions, as long as the token has not expired and has not been deleted.
Safe keeping and instant revocation boundary:
The token's
secretis a signed JWT; members with Console read permission can click to copy it again from the list, so treat URLs containingtoken=as shared secrets and keep them safe; for external temporary sharing, strongly set an explicit expiration time (such as7 Days) and avoid usingNever.Once a link leaks or sharing ends, simply click Delete to the right of the token in the File tokens list (or call Edit expiry to set it as expired), and the corresponding share link becomes invalid immediately. Note: merely toggling the bucket's
File securityswitch does not invalidate already-issued File Tokens; revoking access requires directly deleting the token.
FAQ and Troubleshooting
Q1: I enabled File security on bucket agent_multimedia_bucket and configured per-file Read permission for the customer on user_zhangwei_001 when uploading images. Why did the customer suddenly lose access to their images after an administrator later turned off the bucket's File security?
Root cause analysis: This is the core authorization semantics of the File security switch:
When
File securityis enabled, the system uses桶级权限 OR 文件级权限authorization, so the customer can access files using theRole.user('user_zhangwei_001')on individual files.Once the bucket's
File securityis switched to disabled, the system immediately ignores all per-file permissions within the bucket and strictly requires visitors to match the bucket-level permissions (Bucket Permissions). If the bucket-level Permissions only include the internal teamRole.team('team_support_ops')and do not include the customer role, the customer immediately loses access.
Solution: For buckets requiring per-file isolated authorization, always keep the bucket's Settings → File security in the enabled state.
Q2: How can I allow frontend users to upload support ticket attachments to a bucket and allow images to be displayed directly via known image links, while preventing ordinary application users from calling listFiles to fetch the bucket's file list?
Solution: This is exactly the standard use case for Client file listing:
Go to the Settings tab of the target bucket (such as
agent_multimedia_bucket).In Permissions (or per-file permissions), normally configure the roles allowed to upload (
Create) and read (Read).Scroll down to the Client file listing card, turn off the "Allow client file listing" switch, and click Update to save.
After it is disabled, anonymous and ordinary application-user sessions or JWTs calling
storage.listFiles('agent_multimedia_bucket')receive401 user_unauthorized. API key identities and privileged project-management identities are exempt from this switch but must still meet applicable authentication and authorization requirements; an ordinary application team owner is not automatically a project manager. Uploads and single-file access remain subject to their existing permissions and settings.
Q3: Why do some large files of a dozen or more MB not show Gzip/Zstd compression or encryption at rest, or occasionally remain in the Pending state in the file list?
Root cause analysis:
File size and processing conditions: Files larger than 20,000,000 bytes skip in-memory compression and application-level encryption. Antivirus also runs only when enabled in both environment and bucket, the storage device is local, and the file is at most 20,000,000 bytes. These steps occur after the storage device has received the file.
Reason for the
Pendingstate: large files use 5 MB chunked upload; if the client loses network connection mid-upload, closes the browser page, or one chunk is blocked by a network firewall, the server never receives the final merge chunk, so the file record remains in thePendingstate and its details are inaccessible. You can resume the upload by re-initiating with the originalfileIdfrom the client, or select thePendingrecord in the list and delete it directly for cleanup.
Related Documentation
Knowledge base document management: learn how documents uploaded to knowledge base
kb_enterprise_supportreuse Storage buckets and undergo parsing and chunking.Content Moderation (Moderation): configure violation detection policies and Fail-Closed interception rules for images uploaded to buckets.
Authentication Overview (Auth Overview): review the
Role.any(),Role.users(),Role.user(),Role.team()syntax used in bucket and per-file permissions.Cloud Functions (Functions): read and write Storage files in serverless functions on the server side combined with project context.
Core Concepts and Permission Model: an overall understanding of Agentbase's storage, authorization, and quota metering rules.

