From 37c42ba0c4e5dc20b9b1415efcc684d9291456bc Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Wed, 14 Oct 2026 04:19:45 +0000 Subject: [PATCH 1/2] docs: revise non-native English in the English docs Rewrite translated wording under content/en so it reads like US technical documentation, without changing commands, code samples, or technical claims that still need maintainer confirmation. Co-authored-by: RustFS --- .../en/administration/data/bucket/creation.md | 8 +- .../en/administration/data/bucket/deletion.md | 6 +- .../en/administration/data/object/creation.md | 6 +- .../en/administration/data/object/deletion.md | 4 +- .../data/object/multipart-upload.md | 4 +- .../administration/data/object/object-lock.md | 4 +- .../en/administration/data/object/scanner.md | 16 +-- .../administration/data/object/versioning.md | 4 +- content/en/administration/data/s3-tables.md | 2 +- content/en/administration/index.md | 2 +- content/en/administration/protocols/s3.md | 2 +- .../en/developer/integration/others/index.md | 2 +- content/en/developer/mcp.md | 32 ++--- content/en/developer/sdk/go.md | 20 ++-- content/en/developer/sdk/index.md | 24 ++-- content/en/developer/sdk/java.md | 32 ++--- content/en/developer/sdk/javascript.md | 40 +++---- content/en/developer/sdk/other.md | 48 ++++---- content/en/developer/sdk/python.md | 8 +- content/en/developer/sdk/rust.md | 6 +- content/en/developer/sdk/typescript.md | 8 +- content/en/index.mdx | 4 +- content/en/installation/cloud-native/index.md | 6 +- content/en/installation/container/docker.md | 6 +- content/en/installation/container/index.md | 2 +- content/en/installation/index.md | 10 +- content/en/installation/linux/index.md | 6 +- .../linux/multiple-node-multiple-disk.md | 20 ++-- .../linux/prerequisites-and-service.md | 30 ++--- content/en/installation/linux/quick-start.md | 4 +- .../linux/single-node-multiple-disk.md | 10 +- .../linux/single-node-single-disk.md | 10 +- content/en/installation/macos/index.md | 2 +- .../checklists/hardware-checklists.md | 110 +++++++++--------- .../checklists/hardware-selection.md | 8 +- .../requirement/checklists/index.md | 4 +- .../checklists/network-checklists.md | 26 ++--- .../checklists/security-checklists.md | 12 +- .../checklists/software-checklists.md | 4 +- content/en/integration/tls-configured.md | 10 +- content/en/integration/virtual.md | 20 ++-- content/en/operations/cluster-lifecycle.md | 6 +- content/en/operations/credentials.md | 2 +- content/en/operations/observability.md | 2 +- .../scaling/storage-pool-decommission.md | 2 +- content/en/operations/status-check.md | 2 +- .../en/security-compliance/encryption/kms.md | 4 +- .../security-compliance/encryption/sse-s.md | 2 +- .../security-compliance/iam/access-token.md | 20 ++-- content/en/security-compliance/iam/index.md | 2 +- content/en/troubleshooting/driver.md | 63 +++++----- content/en/troubleshooting/index.md | 4 +- content/en/troubleshooting/node.md | 58 ++++----- 53 files changed, 376 insertions(+), 373 deletions(-) diff --git a/content/en/administration/data/bucket/creation.md b/content/en/administration/data/bucket/creation.md index 46804ffcf..97caf8b40 100644 --- a/content/en/administration/data/bucket/creation.md +++ b/content/en/administration/data/bucket/creation.md @@ -1,5 +1,5 @@ --- -title: "RustFS Bucket Creation" +title: "Create a Bucket" description: "Create buckets using the RustFS UI, rc, or the S3 API." --- @@ -10,11 +10,11 @@ This guide explains how to create buckets using the RustFS UI, `rc`, or the S3 A - A running RustFS instance (see [Installation Guide](../../../installation/index.md)). - [`rc`](/operations/rc) installed and configured with an alias for the command-line workflow. -## Using the RustFS UI +## Use the RustFS Console 1. Log in to the RustFS Console. 2. On the Buckets page, in the top right corner, select **Create Bucket**. -3. Enter the bucket name and click **Create** to complete bucket creation. +3. Enter a bucket name and select **Create**. ![bucket creation](images/bucket-creation-by-ui.png) @@ -49,4 +49,4 @@ aws s3api create-bucket \ --endpoint-url http://localhost:9000 ``` -Verify the bucket creation in the RustFS Console. +Confirm that the bucket appears in the RustFS Console. diff --git a/content/en/administration/data/bucket/deletion.md b/content/en/administration/data/bucket/deletion.md index b2234a810..eacdb065c 100644 --- a/content/en/administration/data/bucket/deletion.md +++ b/content/en/administration/data/bucket/deletion.md @@ -10,14 +10,16 @@ This guide explains how to delete buckets using the RustFS UI, `rc`, or the S3 A - Install and configure [`rc`](/operations/rc) before using the command-line workflow. - Empty the target bucket before deleting it, or use `--force` only after reviewing the objects that will be removed. -**Warning**: Deleting a bucket is irreversible and may break applications relying on it. Ensure you have backed up any necessary data before proceeding. +:::warning[Deletion is permanent] +Deleting a bucket is irreversible and can break applications that depend on it. Back up any data you need before you continue. +::: ## Using the RustFS UI 1. Log in to the RustFS Console. 2. On the homepage, select the bucket you want to delete. 3. On the far right, select the **Delete** button. -4. In the popup dialog, click **Confirm** to complete bucket deletion. +4. In the confirmation dialog, select **Confirm**. ![bucket deletion](images/bucket-deletion-on-ui.png) diff --git a/content/en/administration/data/object/creation.md b/content/en/administration/data/object/creation.md index b0c5ca07b..546a1aacf 100644 --- a/content/en/administration/data/object/creation.md +++ b/content/en/administration/data/object/creation.md @@ -22,7 +22,7 @@ Objects are the fundamental storage units in RustFS, containing data, metadata, ![object creation from ui](images/upload_file_from_ui.png) -Click on an object to view its details. +Select an object to view its details. ![object details info](images/object_details_info.png) @@ -63,7 +63,7 @@ Verify the upload in the RustFS Console. See [Object Deletion](./deletion.md). -Use the following API for file deletion: +To delete an object with the S3 API, use: ```http DELETE /{bucketName}/{objectName} HTTP/1.1 @@ -78,4 +78,4 @@ aws s3api delete-object \ --endpoint-url http://localhost:9000 ``` -You can confirm the file has been deleted on the RustFS UI. +Confirm in the RustFS Console that the object no longer appears. diff --git a/content/en/administration/data/object/deletion.md b/content/en/administration/data/object/deletion.md index 5e3106239..fa53e3672 100644 --- a/content/en/administration/data/object/deletion.md +++ b/content/en/administration/data/object/deletion.md @@ -13,9 +13,9 @@ This guide covers object deletion. ## Using the RustFS UI 1. Log in to the RustFS Console. -2. Select the bucket containing the file to be deleted. +2. Select the bucket that contains the object you want to delete. 3. On the bucket page, select the file to be deleted. -4. Click **Delete Selected Items** in the upper right corner, then click **Confirm** in the popup dialog. +4. Select **Delete Selected Items** in the upper-right corner, and then select **Confirm**. ![object deletion from ui](images/delete_file_from_ui.png) diff --git a/content/en/administration/data/object/multipart-upload.md b/content/en/administration/data/object/multipart-upload.md index d4a6af66e..93877a8bd 100644 --- a/content/en/administration/data/object/multipart-upload.md +++ b/content/en/administration/data/object/multipart-upload.md @@ -27,7 +27,7 @@ RustFS accepts part numbers from `1` through `10000`. `ListParts` and `ListMulti ![Console upload dialog with a selected large file](./images/multipart-upload-console.png) -The observed Console upload dialog supports up to 10,000 selected files and reports a 512 GB maximum for a single file. These are Console upload limits; S3 clients can have different local limits. +The Console upload dialog supports up to 10,000 files and reports a 512 GB maximum for a single file. These are Console upload limits; S3 clients can have different local limits. After upload starts, **Task Management** groups tasks into Pending, Processing, Completed, Failed, and Canceled states. Each processing task shows progress and a **Cancel** action. Canceling an active multipart task aborts the current part request and marks the task as canceled. @@ -42,7 +42,7 @@ rc object copy /path/to/hello.txt rustfs/my-bucket/hello.txt rc object stat rustfs/my-bucket/hello.txt --json ``` -:::note[rc 0.1.29 multipart boundary] +:::note[Multipart limitations in rc 0.1.29] `rc 0.1.29` does not expose create, upload-part, complete, list-parts, or abort multipart commands. A validated 20 MiB `rc object copy` used a single `PutObject` request rather than multipart upload. Use the Console or an S3 SDK when explicit multipart behavior is required; use `rc object stat` to verify the completed object. diff --git a/content/en/administration/data/object/object-lock.md b/content/en/administration/data/object/object-lock.md index 5db3468a1..c769ae64f 100644 --- a/content/en/administration/data/object/object-lock.md +++ b/content/en/administration/data/object/object-lock.md @@ -29,7 +29,7 @@ COMPLIANCE retention cannot be bypassed or shortened before its retain-until dat 2. Select **Create Bucket** and enter the bucket name. 3. Enable **Object Lock**. The Console also enables **Version** because Object Lock requires versioning. 4. To apply retention automatically to new object versions, enable **Retention**. -5. Select **COMPLIANCE** or **GOVERNANCE**, enter the validity, and select **Day** or **Year**. +5. Select **COMPLIANCE** or **GOVERNANCE**, enter the retention period, and select **Day** or **Year**. 6. Select **Create**. ![Create Bucket dialog with versioning, Object Lock, and default retention enabled](./images/object-lock-create-bucket.png) @@ -48,7 +48,7 @@ rc alias set rustfs http://localhost:9000 \ --region us-east-1 --bucket-lookup path ``` -:::note[rc 0.1.29 bucket creation boundary] +:::note[Bucket creation limitation in rc 0.1.29] `rc bucket create --with-lock` and `--with-versioning` appear in the `rc 0.1.29` help output but return `not implemented` when executed. Create the Object Lock bucket in the Console. The upload headers shown below are supported and were validated against RustFS. diff --git a/content/en/administration/data/object/scanner.md b/content/en/administration/data/object/scanner.md index 6330c38f6..9c6616a65 100644 --- a/content/en/administration/data/object/scanner.md +++ b/content/en/administration/data/object/scanner.md @@ -3,30 +3,30 @@ title: "Object Scanning" description: "Guide to the RustFS object scanner, including design, implementation, and monitoring." --- -This guide covers the design and implementation of the RustFS object scanner, including its integration with Erasure Coding, Scrub & Repair mechanisms, scheduling strategies, monitoring metrics, and troubleshooting. +This guide covers the design and implementation of the RustFS object scanner, including how it works with erasure coding, scrubbing and repair, scheduling, metrics, and troubleshooting. ## Overview The RustFS object scanner is built into the storage engine and is responsible for periodically checking object integrity and executing scheduled operations. -Scanning tasks include disk usage statistics, lifecycle management rule evaluation, object replication execution, and triggering corrupted object self-healing. +The scanner collects disk usage statistics, evaluates lifecycle rules, performs object replication, and triggers healing for corrupted objects. ## Architecture and Design Principles ### Scanner Architecture The RustFS scanner uses a hash sampling mechanism, selecting one out of every 1024 objects for inspection based on object name hashing to minimize performance impact. -The scanner is deeply integrated with the Erasure Coding module, utilizing redundant shards for online reconstruction when detecting lost or corrupted shards, ensuring high data availability and consistency. +The scanner works with the erasure coding layer: when it detects a missing or corrupted shard, it rebuilds the shard online from the remaining redundant shards. ## Data Verification and Recovery -The RustFS data verification mechanism checks metadata consistency and performs bit-by-bit reading and verification to discover hidden bad blocks. The object scanner detects issues like bit rot and triggers repair processes when necessary. +The RustFS data verification mechanism checks metadata consistency and reads and verifies data to detect latent bad sectors. The object scanner detects issues like bit rot and triggers repair processes when necessary. ## Scanning Modes and Scheduling -RustFS supports three scanning modes: online scanning during reads, background periodic scanning, and manual full scanning, balancing performance and reliability. -Similar to the `osd_scrub_begin_hour` configuration in Ceph, administrators can set scanning start times and frequency. For example, light verification is set to once daily by default. +RustFS supports three scanning modes that balance performance and reliability: inline checks during reads, periodic background scans, and manual full scans. +Similar to the `osd_scrub_begin_hour` configuration in Ceph, administrators can set scanning start times and frequency. For example, a lightweight check runs once a day by default. ## Monitoring and Metrics -Scanner statistics include total task count, failure count, and time distribution, exposing metrics through the Prometheus data model such as `rustfs_scanner_jobs_total`, `rustfs_scanner_failures_total`, and `rustfs_scanner_duration_seconds`. -Combined with monitoring systems, alerts can be set based on scanning failure rates and duration to promptly discover and locate potential issues at the storage or network levels. \ No newline at end of file +The scanner reports the total number of tasks, the number of failures, and duration distribution as Prometheus metrics, such as `rustfs_scanner_jobs_total`, `rustfs_scanner_failures_total`, and `rustfs_scanner_duration_seconds`. +Configure alerts on scan failure rate and duration so you can detect and diagnose storage or network problems early. diff --git a/content/en/administration/data/object/versioning.md b/content/en/administration/data/object/versioning.md index b891c7567..b6a5130ba 100644 --- a/content/en/administration/data/object/versioning.md +++ b/content/en/administration/data/object/versioning.md @@ -25,7 +25,7 @@ Suspending versioning stops normal creation of new version IDs but preserves exi 3. Enable **Version**. 4. Select **Create**. -### Enable or suspend an existing bucket +### Enable or suspend versioning on an existing bucket 1. Open **Buckets**, locate the bucket, and select **Settings**. 2. Under **Data Protection**, locate **Versioning**. @@ -94,7 +94,7 @@ rc bucket version suspend rustfs/my-bucket rc bucket version info rustfs/my-bucket ``` -:::warning[rc 0.1.29 version deletion boundary] +:::warning[Version deletion limitation in rc 0.1.29] `rc object remove --versions` is listed in the `rc 0.1.29` help output but returns `not implemented`. Use the Console or an S3 SDK to permanently delete selected version IDs. Do not remove an entire version history unless you have verified retention, replication, and recovery requirements. diff --git a/content/en/administration/data/s3-tables.md b/content/en/administration/data/s3-tables.md index 47d1403f9..bcccb465d 100644 --- a/content/en/administration/data/s3-tables.md +++ b/content/en/administration/data/s3-tables.md @@ -3,7 +3,7 @@ title: "S3 Tables" description: "Enable a RustFS table bucket and connect Iceberg clients to the built-in REST catalog." --- -RustFS S3 Tables manages **Apache Iceberg** tables through a built-in REST catalog. Table data, manifests, and Iceberg metadata remain S3 objects in RustFS. This guide enables a dedicated table bucket and explains client connections, permissions, and maintenance boundaries. +RustFS S3 Tables manages **Apache Iceberg** tables through a built-in REST catalog. Table data, manifests, and Iceberg metadata remain S3 objects in RustFS. This guide shows how to enable a dedicated table bucket and explains client connections, permissions, and maintenance limits. :::note[Preview and version scope] diff --git a/content/en/administration/index.md b/content/en/administration/index.md index d2f55515c..51cc9aaf6 100644 --- a/content/en/administration/index.md +++ b/content/en/administration/index.md @@ -12,6 +12,6 @@ Use this section to manage RustFS through the Console, administer buckets and ob - [S3 Tables](/administration/data/s3-tables) covers table buckets and the built-in Iceberg REST catalog. - [Protocol Support](./protocols/s3.md) covers S3, WebDAV, FTPS, and SFTP access. - [CORS Configuration](./cors/index.md) covers cross-origin access to RustFS services. -- [Virtual-Host Access](/integration/virtual) covers domain-based S3 addressing. +- [Virtual-hosted–style requests](/integration/virtual) cover domain-based S3 addressing. For identity, encryption, transport security, and auditing, continue with [Security & Compliance](/security-compliance). diff --git a/content/en/administration/protocols/s3.md b/content/en/administration/protocols/s3.md index 0148cd28b..cb7d2f2b5 100644 --- a/content/en/administration/protocols/s3.md +++ b/content/en/administration/protocols/s3.md @@ -22,7 +22,7 @@ RustFS covers the common S3 data plane used by applications, backup tools, and S | Objects | Put, get, head, copy, delete, multi-delete, range reads, conditional requests, and user metadata | | Listing | `ListObjects`, `ListObjectsV2`, prefixes, delimiters, markers, and pagination | | Large objects | Create, upload, copy, list, complete, and abort multipart uploads | -| Data management | Versioning, lifecycle rules, bucket and object tags, checksums, and object lock | +| Data management | Versioning, lifecycle rules, bucket and object tags, checksums, and Object Lock | | Access control | IAM credentials and policies, bucket policies, public access block, and presigned GET/PUT URLs | | Integration | CORS, bucket notifications, replication configuration, and server-side encryption workflows | diff --git a/content/en/developer/integration/others/index.md b/content/en/developer/integration/others/index.md index 65a45a2de..02b8e1e08 100644 --- a/content/en/developer/integration/others/index.md +++ b/content/en/developer/integration/others/index.md @@ -8,7 +8,7 @@ Integration guides that do not fit the other categories. ## Guides - [capo (Python)](./capo.md) — connect the community-driven capo SDK to RustFS with synchronous or asynchronous clients. -rclone](./rclone.md) — sync, mount, and serve RustFS buckets from the command line. +- [rclone](./rclone.md) — sync, mount, and serve RustFS buckets from the command line. - [tusd](./tusd.md) — receive resumable uploads into a RustFS bucket over the tus protocol. - [JuiceFS](./juicefs.md) — mount a POSIX filesystem backed by a RustFS bucket. - [Nextcloud](./nextcloud.md) — use RustFS as S3 external storage for Nextcloud files. diff --git a/content/en/developer/mcp.md b/content/en/developer/mcp.md index fd997b019..553e2e186 100644 --- a/content/en/developer/mcp.md +++ b/content/en/developer/mcp.md @@ -1,15 +1,15 @@ --- title: "RustFS MCP" -description: "RustFS MCP Usage Guide" +description: "Connect AI assistants to RustFS object storage with the RustFS MCP server." --- -**RustFS MCP Server** is a high-performance [Model Context Protocol (MCP)](https://www.anthropic.com/news/model-context-protocol) server that provides AI/LLM tools with seamless access to S3-compatible object storage operations. Built with Rust for performance and security, it enables AI assistants like Claude Desktop to interact with cloud storage through standardized protocols. +**RustFS MCP Server** is a [Model Context Protocol (MCP)](https://www.anthropic.com/news/model-context-protocol) server that gives AI assistants, such as Claude Desktop, access to S3-compatible object storage. ### What is MCP? The Model Context Protocol is an open standard that enables AI applications to establish secure, controlled connections with external systems. This server acts as a bridge between AI tools and S3-compatible storage services, providing structured access to file operations while maintaining security and observability. -## ✨ Features +## Features ### Supported S3 Operations @@ -18,7 +18,7 @@ The Model Context Protocol is an open standard that enables AI applications to e - **Upload Files**: Uploads local files with automatic MIME type detection and cache control. - **Get Objects**: Retrieves objects from S3 storage, supporting read or download modes. -## 🔧 Installation +## Installation :::warning[Build instructions may be outdated] @@ -46,7 +46,7 @@ cargo build --release -p rustfs-mcp ./target/release/rustfs-mcp ``` -## ⚙️ Configuration +## Configuration ### Environment Variables @@ -77,7 +77,7 @@ The server supports various command line options to customize behavior: - `--endpoint-url`: Custom S3 endpoint URL (for MinIO, LocalStack, etc.) - `--log-level`: Log level configuration (default: rustfs_mcp_server=info) -## 🚀 Usage +## Usage ### Starting the Server @@ -128,7 +128,7 @@ rustfs-mcp --log-level debug --region us-west-2 ### Using with Docker -[RustFS MCP officially provides a Dockerfile](https://github.com/rustfs/rustfs/tree/main/crates/mcp) that can be used to build container images for using RustFS MCP. +RustFS MCP provides an [official Dockerfile](https://github.com/rustfs/rustfs/tree/main/crates/mcp) that you can use to build a container image. ```bash # Clone RustFS repository code @@ -138,11 +138,11 @@ git clone https://github.com/rustfs/rustfs.git docker build -f crates/mcp/Dockerfile -t rustfs/rustfs-mcp . ``` -After successful build, you can configure it in the MCP configuration of AI IDEs. +After the build succeeds, add the server to your IDE's MCP configuration. #### Configuring MCP in AI IDEs -Currently, mainstream AI IDEs such as Cursor, Windsurf, Trae, etc. all support MCP. For example, in Trae, add the following content to the MCP configuration (**MCP --> Add**): +Many AI IDEs, such as Cursor, Windsurf, and Trae, support MCP. For example, in Trae, add the following content to the MCP configuration (**MCP --> Add**): ```json { @@ -174,25 +174,25 @@ Currently, mainstream AI IDEs such as Cursor, Windsurf, Trae, etc. all support M } ``` -> `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` are RustFS access keys. You can refer to the [Access Key Management chapter](../security-compliance/iam/access-token.md) for creation. +> `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` are RustFS access keys. To create them, see [Access Key Management](../security-compliance/iam/access-token.md). -If added successfully, you can list the [available tools](#️-available-tools) on the MCP configuration page. +If the server is added successfully, the MCP configuration page lists its [available tools](#available-tools). -![add rustfs mcp in trae mcp configuration successfully](images/add-rustfs-mcp-succ.png) +![RustFS MCP server added to the MCP configuration in Trae](images/add-rustfs-mcp-succ.png) -In Trae, you can use the corresponding tools by entering the corresponding prompts. For example, in Trae's chat dialog, enter: +To invoke an MCP tool in Trae, enter a prompt in the chat. For example: ```text Please help me list the buckets in the current rustfs instance, thank you! ``` -Returns the following response: +Trae returns the following response: ![list rustfs bucket with rustfs mcp](images/list-rustfs-bucket-with-mcp.png) -Trae uses **Builder with MCP** mode, calling the `list_buckets` tool to list all buckets in the configured RustFS instance. The same applies to calls to other tools. +Trae uses **Builder with MCP** mode, calling the `list_buckets` tool to list all buckets in the configured RustFS instance. Other tools work the same way. -## 🛠️ Available Tools +## Available tools The MCP server exposes the following tools that AI assistants can use: diff --git a/content/en/developer/sdk/go.md b/content/en/developer/sdk/go.md index b40cab279..a30a52601 100644 --- a/content/en/developer/sdk/go.md +++ b/content/en/developer/sdk/go.md @@ -1,9 +1,9 @@ --- -title: "Golang SDK Guide" +title: "Go SDK Guide" description: "Use the AWS SDK for Go v2 to operate on RustFS instances, including creating and deleting buckets and objects." --- -RustFS ships no first-party Go SDK — it is fully S3-compatible, so you use the official AWS SDK for Go v2 configured to point at your RustFS server. Through the SDK, you can operate on RustFS, including creating and deleting buckets/objects, uploading and downloading files, etc. +RustFS ships no first-party Go SDK — it is S3-compatible, so you use the official AWS SDK for Go v2 configured to point at your RustFS server. With the SDK, you can create and delete buckets, and upload, download, and delete objects. ## Prerequisites @@ -26,7 +26,7 @@ go get github.com/aws/aws-sdk-go-v2/credentials go get github.com/aws/aws-sdk-go-v2/service/s3 ``` -## Initializing the Client +## Initialize the client The following is a complete, runnable program. It reads its configuration from environment variables and initializes the client from an `aws.Config`: @@ -104,7 +104,7 @@ Buckets: You can now perform bucket and object operations. The snippets below run inside the `main` function above, reusing `client` and `ctx`. -## Create Bucket +## Create a bucket ```go _, err = client.CreateBucket(ctx, &s3.CreateBucketInput{ @@ -120,7 +120,7 @@ fmt.Println("bucket created") bucket created ``` -## List Buckets +## List buckets ```go resp, err := client.ListBuckets(ctx, &s3.ListBucketsInput{}) @@ -139,7 +139,7 @@ Buckets: - my-bucket ``` -## Delete Bucket +## Delete a bucket ```go _, err = client.DeleteBucket(ctx, &s3.DeleteBucketInput{ @@ -155,7 +155,7 @@ fmt.Println("bucket deleted") bucket deleted ``` -## List Objects +## List objects ```go resp, err := client.ListObjectsV2(ctx, &s3.ListObjectsV2Input{ @@ -173,7 +173,7 @@ for _, obj := range resp.Contents { - hello.txt ``` -## Upload Object +## Upload an object Uploading a string body (add `"strings"` to your imports): @@ -193,7 +193,7 @@ fmt.Println("object uploaded") object uploaded ``` -## Download Object +## Download an object Reading the object body (add `"io"` to your imports): @@ -219,4 +219,4 @@ fmt.Println("content is :", string(data)) content is : hello rustfs ``` -For other operations (presigned URLs, multipart uploads, and more), see the [AWS SDK for Go v2 documentation](https://aws.github.io/aws-sdk-go-v2/docs/) — every S3-compatible call works against RustFS the same way. +For other operations (presigned URLs, multipart uploads, and more), see the [AWS SDK for Go v2 documentation](https://aws.github.io/aws-sdk-go-v2/docs/) — most S3 operations work the same way against RustFS; see [S3 compatibility](/reference/s3-compatibility) for exceptions. diff --git a/content/en/developer/sdk/index.md b/content/en/developer/sdk/index.md index f57b4164b..f5550eb33 100644 --- a/content/en/developer/sdk/index.md +++ b/content/en/developer/sdk/index.md @@ -1,43 +1,41 @@ --- -title: "RustFS SDK Overview" +title: "SDKs" description: "Overview of supported S3 SDKs for RustFS." --- -RustFS is a distributed object storage system fully compatible with the S3 protocol. Users can: +RustFS is a distributed object storage system with an S3-compatible API. You can: -- Manage RustFS through the Console management interface. +- Manage RustFS in the Console. - Manage RustFS through S3 clients. -- Implement object storage operations and management on the business side through SDKs. +- Use an S3 SDK to manage buckets and objects from your application. -Currently, the SDKs provided by RustFS include: +The following guides explain how to use S3 SDKs with RustFS: - [Java SDK](./java.md) - [JavaScript SDK](./javascript.md) - [Python SDK](./python.md) - [Rust SDK](./rust.md) - [TypeScript SDK](./typescript.md) -- [Golang SDK](./go.md) +- [Go SDK](./go.md) ## Terminology -Amazon S3 (Simple Storage Service) was the first widely adopted object storage service. Its API has become the de facto standard for object storage. In this documentation, "S3" refers to the protocol. +Amazon Simple Storage Service (Amazon S3) was the first widely adopted object storage service. Its API has become the de facto standard for object storage. In this documentation, "S3" refers to the protocol. ## SDK Recommendations We recommend using the official AWS S3 SDKs. These SDKs are mature, well-maintained, and highly optimized. -If you have a familiar and trusted SDK from a vendor, you can use it. +You can also use a vendor SDK you know and trust, provided it supports the S3 operations you need. Some third-party SDKs may have non-standard implementations. We recommend avoiding SDKs that are not strictly S3-compliant. ## Compatibility with MinIO SDKs -Yes, RustFS is fully compatible with MinIO SDKs. +RustFS works with the MinIO SDKs. -If you are using MinIO SDKs, you can modify the Endpoint, AK, and SK to be directly compatible with RustFS. +To connect a MinIO SDK to RustFS, set the endpoint, access key, and secret key to your RustFS values. ## Handling Incompatible SDKs -If you encounter an SDK that does not support standard S3, MinIO, or RustFS: - -We recommend switching to a standard AWS S3 SDK. +If an SDK does not work with standard S3, MinIO, or RustFS, we recommend switching to an official AWS SDK for S3. diff --git a/content/en/developer/sdk/java.md b/content/en/developer/sdk/java.md index 938a7f166..d9edb430d 100644 --- a/content/en/developer/sdk/java.md +++ b/content/en/developer/sdk/java.md @@ -46,7 +46,7 @@ Add AWS SDK dependencies in `pom.xml`: ``` -> Recommend using AWS SDK v2, which has more complete features and supports async, reactive, and other patterns. +We recommend AWS SDK for Java v2, which is more complete and supports asynchronous and reactive programming. --- @@ -133,14 +133,14 @@ Deleted hello.txt --- -## 3. Common Issues and Troubleshooting +## 3. Troubleshooting | Issue | Cause | Solution | | -------------------------------------- | ------------------------------------ | ----------------------------------------- | | `S3Exception: 301 Moved Permanently` | Path-style not enabled or region error | Set `.forcePathStyle(true)` and use region `us-east-1` | | `ConnectException: Connection refused` | RustFS not started or incorrect port | Check RustFS status and port | -| `403 Forbidden` | AccessKey / SecretKey error | Check authentication configuration | -| Upload fails with no response | SDK defaults to HTTPS, RustFS only supports HTTP (or needs certificates) | Use `http://` address and configure `endpointOverride` | +| `403 Forbidden` | Incorrect access key or secret key | Check your credentials | +| Upload fails with no response | The SDK defaults to HTTPS. RustFS only supports HTTP (or needs certificates). | Use an `http://` address and set `endpointOverride` | --- @@ -148,38 +148,38 @@ Deleted hello.txt ### 4.1 Maven Package and Run -Package project: +Package the project: ```bash mvn clean package ``` -Execute: +Run it: ```bash java -cp target/rustfs-java-s3-demo-1.0-SNAPSHOT.jar com.example.RustfsS3Example ``` -### 4.2 RustFS Configuration Recommendations +### 4.2 Recommended RustFS settings -* Ensure SSL validation is disabled when service uses HTTP protocol. +* If RustFS serves plain HTTP, disable TLS certificate validation in the SDK. * Enable CORS support (if used for web frontend). -* Recommend setting limits like `max_object_size` and `max_part_size` to prevent large file transfer failures. +* We recommend setting limits such as `max_object_size` and `max_part_size` to prevent large transfers from failing. --- The following advanced examples cover: * Presigned URL generation and usage -* Multipart Upload complete process +* The complete multipart upload workflow --- -## 5. Java Advanced Features Examples +## 5. Advanced examples ### 5.1 Generate and Use Presigned URLs -> Presigned URLs allow clients to temporarily access private objects without exposing credentials, widely used for browser direct upload or download file scenarios. +Presigned URLs give clients temporary access to private objects without exposing credentials. They are commonly used for direct uploads and downloads from a browser. #### 5.1.1 Generate Download Link (GET) @@ -229,11 +229,11 @@ System.out.println("Presigned URL: " + presignedRequest.url()); Presigned URL: http://localhost:9000/my-bucket/hello.txt?X-Amz-Algorithm=AWS4-HMAC-SHA256&... ``` -> 🔗 Open the link in browser to access the object. +Open the URL in a browser to access the object. #### 5.1.2 Upload Presigned URL (PUT) -Similarly, you can also generate upload URLs: +You can also generate upload URLs: ```java import software.amazon.awssdk.services.s3.model.PutObjectRequest; @@ -259,7 +259,7 @@ System.out.println("Upload URL: " + presignedPut.url()); ### 5.2 Implement Multipart Upload -> Multipart Upload is the recommended way for large file uploads, enabling resume from breakpoint during network fluctuations. +Multipart upload is the recommended way to upload large files. If the network is interrupted, you can retry failed parts instead of restarting the whole upload. The examples below reuse the `s3` client from section 2 and need these additional imports: @@ -342,4 +342,4 @@ s3.abortMultipartUpload(abortRequest); --- -For other operations (object tagging, bucket policies, and more), see the [AWS SDK for Java v2 documentation](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/) — every S3-compatible call works against RustFS the same way. +For other operations (object tagging, bucket policies, and more), see the [AWS SDK for Java v2 documentation](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/) — most S3 operations work the same way against RustFS; see [S3 compatibility](/reference/s3-compatibility) for exceptions. diff --git a/content/en/developer/sdk/javascript.md b/content/en/developer/sdk/javascript.md index f010b46fa..e2d117df9 100644 --- a/content/en/developer/sdk/javascript.md +++ b/content/en/developer/sdk/javascript.md @@ -3,11 +3,11 @@ title: "JavaScript SDK Guide" description: "Use the official AWS SDK for JavaScript v3 with RustFS." --- -## I. Overview +## Overview RustFS ships no first-party JavaScript SDK — it is S3-compatible, so you use the official AWS SDK for JavaScript (v3) configured to point at your RustFS server. This guide shows how to connect to RustFS and perform common object storage operations. -## II. Prerequisites +## Prerequisites * Node.js 18 or later * A running RustFS instance (see the [Installation Guide](../../installation/index.md)) — the S3 API listens on port `9000`, the Console on port `9001` @@ -19,9 +19,9 @@ If you did not set credentials at install time, the server defaults to `rustfsad ::: -### 2.1 SDK Installation +### 2.1 Install the SDK -Install the required AWS SDK v3 modules with NPM: +Install the required AWS SDK v3 modules with npm: ```bash npm install @aws-sdk/client-s3 @aws-sdk/s3-request-presigner @@ -31,7 +31,7 @@ The examples below use ES modules (`import`). Set `"type": "module"` in your `pa --- -## III. Initializing the Client +## Initialize the client The following is a complete, runnable script. Replace `localhost` with your server's IP address if RustFS runs on another machine, and fill in your own access keys: @@ -67,9 +67,9 @@ All snippets below reuse this `s3` client. --- -## IV. Basic Operations +## Basic operations -### 4.1 Create Bucket +### 4.1 Create a bucket ```js import { CreateBucketCommand } from "@aws-sdk/client-s3"; @@ -84,7 +84,7 @@ Bucket created --- -### 4.2 Upload Object +### 4.2 Upload an object ```js import { PutObjectCommand } from "@aws-sdk/client-s3"; @@ -109,7 +109,7 @@ File uploaded --- -### 4.3 Download Object +### 4.3 Download an object ```js import { GetObjectCommand } from "@aws-sdk/client-s3"; @@ -137,7 +137,7 @@ File downloaded --- -### 4.4 List Objects +### 4.4 List objects ```js import { ListObjectsV2Command } from "@aws-sdk/client-s3"; @@ -152,7 +152,7 @@ hello.txt (12 bytes) --- -### 4.5 Delete Object +### 4.5 Delete an object ```js import { DeleteObjectCommand } from "@aws-sdk/client-s3"; @@ -167,11 +167,11 @@ File deleted --- -## V. Advanced Features +## Advanced features -### 5.1 Generate Presigned URLs +### 5.1 Generate presigned URLs -> Allows frontend or third parties to use temporary links for uploading/downloading files +Presigned URLs let browser clients or third parties upload or download objects through temporary links. #### Download (GET) @@ -209,7 +209,7 @@ console.log("Presigned PUT URL:", url); --- -### 5.2 Multipart Upload +### 5.2 Multipart upload ```js import { @@ -275,11 +275,11 @@ Multipart upload completed --- -## VI. Common Issues and Notes +## Troubleshooting | Problem | Cause | Solution | | --------------------------- | -------------------- | --------------------------------------- | -| SignatureDoesNotMatch | Wrong signature version | JS SDK v3 uses v4 by default, ensure RustFS supports v4 | +| SignatureDoesNotMatch | Signature mismatch | SDK v3 signs with SigV4 by default; check credentials, region, and endpoint | | EndpointConnectionError | Endpoint address misconfigured or not started | Check if RustFS address is accessible | | NoSuchKey | File does not exist | Check if `Key` is spelled correctly | | InvalidAccessKeyId / Secret | Credentials misconfigured | Check `accessKeyId` / `secretAccessKey` configuration | @@ -287,9 +287,9 @@ Multipart upload completed --- -## VII. Appendix: Frontend Upload Adaptation +## Appendix: Browser uploads -Using presigned URLs allows browsers to upload files directly without passing AccessKey. +With presigned URLs, browsers can upload objects directly without access to your credentials. Frontend (HTML+JS) upload example: @@ -312,4 +312,4 @@ Frontend (HTML+JS) upload example: ``` -For other operations (object tagging, bucket policies, and more), see the [AWS SDK for JavaScript v3 documentation](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/) — every S3-compatible call works against RustFS the same way. +For other operations (object tagging, bucket policies, and more), see the [AWS SDK for JavaScript v3 documentation](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/) — most S3 operations work the same way against RustFS; see [S3 compatibility](/reference/s3-compatibility) for exceptions. diff --git a/content/en/developer/sdk/other.md b/content/en/developer/sdk/other.md index 4b4380965..9533fb6aa 100644 --- a/content/en/developer/sdk/other.md +++ b/content/en/developer/sdk/other.md @@ -1,43 +1,43 @@ --- title: "Other SDKs" -description: "This article mainly explains the usage of various other language SDKs in RustFS." +description: "Learn how to connect to RustFS from languages without an official AWS SDK." --- -If AWS S3 doesn't officially support your language, you can adopt the following strategies to integrate with RustFS: +If AWS does not provide an official SDK for your language, you can use one of the following approaches to integrate with RustFS: -## 1. Use HTTP Interface Direct Requests (Based on S3 API Protocol) +## 1. Send HTTP requests directly to the S3 API -The S3 protocol is a standard RESTful API. You can encapsulate access logic yourself using any language that supports HTTP requests (such as C, Rust, Lua, Erlang). +The S3 protocol is a standard RESTful API. You can implement the client logic yourself in any language that can send HTTP requests (such as C, Rust, Lua, Erlang). -### Key points include: +### Key steps -* **Signature Algorithm**: Implement AWS Signature Version 4 signature (more complex) +* **Request signing**: Implement AWS Signature Version 4 (the most complex part). * **Construct correct Headers and Canonical Request** * **Use HTTPS/HTTP client to send requests** -👉 Recommended to reference open-source project signature implementations, for example: +We recommend consulting existing open-source implementations of request signing, such as: * [https://docs.aws.amazon.com/general/latest/gr/sigv4-signed-request-examples.html](https://docs.aws.amazon.com/general/latest/gr/sigv4-signed-request-examples.html) --- -## 2. Call CLI Tools or Middleware Services of Existing SDKs +## 2. Use the AWS CLI or a service built on an existing SDK If you don't want to implement signatures yourself, you can: -### 2.1. Use AWS CLI tools with existing language support: +### 2.1. Call the AWS CLI -For example, call through Shell: +For example, run the following command from your application using a shell: ```bash aws s3 cp local.txt s3://mybucket/myfile.txt --endpoint-url http://rustfs.local:9000 ``` -Or write a simple relay service using Node.js/Python SDK, and your language uploads/downloads by calling this service. +Alternatively, build a small relay service with an SDK for Node.js or Python, then call it from your application to upload or download objects. -### 2.2. Set up a Proxy (such as Flask, FastAPI, Express) +### 2.2. Run a proxy service (for example, Flask, FastAPI, or Express) -Let clients that don't support S3 call your encapsulated HTTP API: +Expose an HTTP API that clients without S3 support can call: ```http POST /upload -> Service internally calls SDK to upload objects to RustFS @@ -48,31 +48,31 @@ GET /presigned-url -> Generate presigned URL for frontend/client use ## 3. Find Third-Party Community SDKs -Although AWS doesn't have official SDKs, some language communities have developed unofficial S3 clients. For example: +For languages without an official AWS SDK, look for community-maintained S3 clients. For example: * Haskell: `amazonka-s3` * Rust: `rusoto` (deprecated) or `aws-sdk-rust` -* OCaml: May implement through `cohttp` yourself -* Delphi: Has commercial libraries supporting S3 protocol +* OCaml: Build your own client on top of `cohttp` +* Delphi: Commercial libraries with S3 support are available Community SDKs vary greatly in stability, so you should evaluate activity, documentation, and compatibility before use. --- -## 4. Delegate Core Upload Logic to Platform Hosting +## 4. Upload directly from clients with presigned URLs For example: -* Delegate frontend (Web/Mobile) upload tasks to browser or App side execution (using presigned URLs) -* Backend uses Node.js/Python/Go and other proxies to implement upload logic +* Use presigned URLs to upload directly from a browser or mobile app. +* Implement the upload logic in a backend service (for example, Node.js, Python, or Go). --- -## Summary Recommendations +## Summary -| Scenario | Recommended Solution | +| Situation | Recommended approach | | ------------- | ---------------------------------- | -| Need complete control/embedded environment | Implement Signature V4 self-signing | -| Weak language support but has Shell | Call upload through AWS CLI | -| Can deploy relay service | Use Python/Node to build S3 API gateway | +| You need full control, or you target an embedded environment | Implement SigV4 signing yourself | +| Limited SDK support, but a shell is available | Upload with the AWS CLI | +| You can deploy a relay service | Build a small S3 gateway with Python or Node.js | | Frontend upload | Use presigned URLs | diff --git a/content/en/developer/sdk/python.md b/content/en/developer/sdk/python.md index 672504524..5e831c261 100644 --- a/content/en/developer/sdk/python.md +++ b/content/en/developer/sdk/python.md @@ -204,7 +204,7 @@ curl -X PUT --upload-file /path/to/hello.txt "http://localhost:9000/my-bucket/up ### 5.2 Multipart Upload -Suitable for files larger than 10 MB, allows manual control of each part. +Use multipart upload for files larger than 10 MB when you need control over each part. ```python file_path = 'largefile.bin' @@ -260,13 +260,13 @@ Multipart upload complete. --- -## 6. Common Issue Troubleshooting +## 6. Troubleshooting | Issue | Cause | Solution | | ------------------------- | ----------------- | -------------------------------------------------------------- | | `SignatureDoesNotMatch` | Not using v4 signature | Set `signature_version='s3v4'` | | `EndpointConnectionError` | Wrong RustFS address or service not started | Check endpoint and RustFS service status | -| `AccessDenied` | Wrong credentials or insufficient permissions | Check AccessKey/SecretKey or bucket policies | +| `AccessDenied` | Wrong credentials or insufficient permissions | Check the access key, secret key, and bucket policies | | `PermanentRedirect` / wrong bucket URL | Path-style not enabled | Set `s3={'addressing_style': 'path'}` in the `Config` | --- @@ -284,6 +284,6 @@ def download_file(bucket, object_key, local_path): print(f"Downloaded s3://{bucket}/{object_key} to {local_path}") ``` -For other operations (object tagging, bucket policies, and more), see the [Boto3 S3 documentation](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/s3.html) — every S3-compatible call works against RustFS the same way. +For other operations (object tagging, bucket policies, and more), see the [Boto3 S3 documentation](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/s3.html) — most S3 operations work the same way against RustFS; see [S3 compatibility](/reference/s3-compatibility) for exceptions. If you prefer native async support and full type hints, the community-driven [capo](https://github.com/kap-sh/capo) SDK also works with RustFS — see the [capo (Python) integration guide](../integration/others/capo.md). diff --git a/content/en/developer/sdk/rust.md b/content/en/developer/sdk/rust.md index 9d8181348..8b6d7ebdc 100644 --- a/content/en/developer/sdk/rust.md +++ b/content/en/developer/sdk/rust.md @@ -1,9 +1,9 @@ --- title: "Rust SDK Guide" -description: "Operate RustFS instances through the AWS SDK for Rust, including creation and deletion of buckets and objects." +description: "Use the AWS SDK for Rust to create and delete buckets and objects in RustFS." --- -RustFS ships no first-party Rust client crate — it is fully S3-compatible, so you use the official AWS SDK for Rust (`aws-sdk-s3`) configured to point at your RustFS server. Through the SDK, you can operate RustFS, including creation and deletion of buckets/objects, file upload and download, etc. +RustFS ships no first-party Rust client crate — it is S3-compatible, so you use the official AWS SDK for Rust (`aws-sdk-s3`) configured to point at your RustFS server. With the SDK, you can create and delete buckets and upload, download, and delete objects. ## Prerequisites @@ -284,4 +284,4 @@ match rustfs_client Object content: hello rustfs ``` -For other operations (presigned URLs, multipart uploads, and more), see the [AWS SDK for Rust documentation](https://docs.aws.amazon.com/sdk-for-rust/latest/dg/) — every S3-compatible call works against RustFS the same way. +For other operations (presigned URLs, multipart uploads, and more), see the [AWS SDK for Rust documentation](https://docs.aws.amazon.com/sdk-for-rust/latest/dg/) — most S3 operations work the same way against RustFS; see [S3 compatibility](/reference/s3-compatibility) for exceptions. diff --git a/content/en/developer/sdk/typescript.md b/content/en/developer/sdk/typescript.md index d26b7a938..0ecf279f5 100644 --- a/content/en/developer/sdk/typescript.md +++ b/content/en/developer/sdk/typescript.md @@ -1,14 +1,14 @@ --- -title: "RustFS TypeScript SDK Usage Guide" +title: "TypeScript SDK Guide" description: "Operate RustFS from TypeScript with the AWS SDK for JavaScript v3, including creation and deletion of buckets and objects." --- -RustFS ships no first-party TypeScript SDK — it is fully S3-compatible, so you use the official AWS SDK for JavaScript v3 (which ships its own TypeScript type definitions) configured to point at your RustFS server. Through the SDK, you can operate RustFS, including creation and deletion of buckets/objects, file upload and download, etc. +RustFS ships no first-party TypeScript SDK — it is S3-compatible, so you use the official AWS SDK for JavaScript v3 (which includes TypeScript type definitions) configured to point at your RustFS server. With the SDK, you can create and delete buckets and upload, download, and delete objects. ## Prerequisites - Node.js 18 or later (the examples use ES modules — set `"type": "module"` in your `package.json`) -- An available RustFS instance (refer to [Installation Guide](../../installation/index.md) for installation) — the S3 API listens on port `9000`, the Console on port `9001` +- A running RustFS instance (see the [Installation Guide](../../installation/index.md)) — the S3 API listens on port `9000`, the Console on port `9001` - Access keys, set at install time via the `RUSTFS_ACCESS_KEY` / `RUSTFS_SECRET_KEY` environment variables (refer to [Access Key Management](../../security-compliance/iam/access-token.md) for creation) :::tip[Local test] @@ -201,4 +201,4 @@ async function getObject() { Object content: hello rustfs ``` -For other operations (presigned URLs, multipart uploads, and more), see the [AWS SDK for JavaScript v3 documentation](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/) — every S3-compatible call works against RustFS the same way. +For other operations (presigned URLs, multipart uploads, and more), see the [AWS SDK for JavaScript v3 documentation](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/) — most S3 operations work the same way against RustFS; see [S3 compatibility](/reference/s3-compatibility) for exceptions. diff --git a/content/en/index.mdx b/content/en/index.mdx index da087cfc6..aa0e7f4ec 100644 --- a/content/en/index.mdx +++ b/content/en/index.mdx @@ -6,8 +6,8 @@ description: "Install RustFS on Linux, containers, Kubernetes, macOS, or Windows
- RustFS is a distributed object storage system written in Rust and built - for S3-compatible workloads. This documentation covers installation, + RustFS is a distributed, S3-compatible object storage system written in Rust. + This documentation covers installation, administration, security, and operations for RustFS clusters.
diff --git a/content/en/installation/cloud-native/index.md b/content/en/installation/cloud-native/index.md index ef338b581..3d7b9dc04 100644 --- a/content/en/installation/cloud-native/index.md +++ b/content/en/installation/cloud-native/index.md @@ -106,7 +106,7 @@ The chart templates HTTP probes on the S3 port (9000) out of the box, matching t - **Liveness**: `GET /health` (`livenessProbe.httpGet.path`), initial delay 30s, period 5s - **Readiness**: `GET /health/ready` (`readinessProbe.httpGet.path`), initial delay 10s, period 5s -A pod is only added to the Service endpoints once `/health/ready` returns `200`, which in distributed mode requires the storage quorum to be met. Thresholds and timings are tunable via the `livenessProbe.*` and `readinessProbe.*` values. +A Pod is added to the Service endpoints only after `/health/ready` returns `200`, which in distributed mode requires the storage quorum to be met. Thresholds and timings are tunable via the `livenessProbe.*` and `readinessProbe.*` values. ## 5. Production hardening @@ -147,7 +147,7 @@ Log in to the Console with the access key and secret key you set at install time ## 7. Scaling out with server pools -In distributed mode the chart can run multiple **server pools** — independent StatefulSets whose drives together form one cluster. This is the chart-level equivalent of adding a Server Pool as described in [Pool Expansion](../../operations/scaling/storage-pool-expansion.md). +In distributed mode the chart can run multiple **server pools** — independent StatefulSets whose drives together form one cluster. This is the chart-level equivalent of adding a server pool as described in [Pool Expansion](../../operations/scaling/storage-pool-expansion.md). To expand an existing deployment, enable pools and describe the current layout as pool 0 plus your new capacity: @@ -172,7 +172,7 @@ The list index determines the StatefulSet name — never remove or reorder entri What to expect during the rollout, per the chart's documentation: -- **Crash/restart cycles are normal.** Pods restart until every pod of every pool is resolvable — the server refuses to start with unresolvable peers, so expect a few crash loops before the cluster converges. This is harmless. +- **Expect restarts.** Pods restart until every Pod in every pool is resolvable — the server refuses to start with unresolvable peers, so expect a few crash loops before the cluster converges. This is harmless. - **Rebalance afterwards.** After the cluster converges, run `rc admin rebalance start ` to spread existing objects across the new pool. - The PodDisruptionBudget spans all pools: with the default `pdb.maxUnavailable: 1`, at most one pod of the whole cluster may be evicted at a time. diff --git a/content/en/installation/container/docker.md b/content/en/installation/container/docker.md index c88d61007..e139b39d9 100644 --- a/content/en/installation/container/docker.md +++ b/content/en/installation/container/docker.md @@ -7,8 +7,8 @@ This page covers running the official RustFS image with Docker: a single-node in ## 1. Prerequisites -* Docker Engine (≥ 20.10) installed and able to pull images and run containers normally -* Host ports 9000 (S3 API) and 9001 (Console) available, or consistent with your custom ports +* Docker Engine (≥ 20.10) installed, with the ability to pull images and run containers +* Host ports 9000 (S3 API) and 9001 (Console) available, or the custom ports you plan to use * If you bind-mount a host directory, the directory owner must match the container user — see [Bind-mount a host directory](#bind-mount-a-host-directory) ## 2. Pull the image @@ -186,7 +186,7 @@ If [using TLS](../../integration/tls-configured.md), mount the certificate direc ## Before production -Work through the [Pre-Installation Checklists](../requirement/checklists/index.md) — hardware, network, software, and security — before deploying to production. Use a multi-node deployment architecture, [enable TLS encrypted communication](../../integration/tls-configured.md), configure a log rotation strategy, and set up a regular backup strategy. +Work through the [Pre-Installation Checklists](../requirement/checklists/index.md) — hardware, network, software, and security — before deploying to production. Use a multi-node deployment, [enable TLS](../../integration/tls-configured.md), configure log rotation, and schedule regular backups. ## Next steps diff --git a/content/en/installation/container/index.md b/content/en/installation/container/index.md index 4ee47b47d..2f076e392 100644 --- a/content/en/installation/container/index.md +++ b/content/en/installation/container/index.md @@ -3,7 +3,7 @@ title: "Container" description: "Run the official RustFS container image with Docker or Podman." --- -RustFS is a high-performance, S3-compatible open-source distributed object storage system. In single-node single-disk (SNSD) deployment mode, the backend uses zero erasure coding without additional data redundancy, which makes it suitable for local testing and small-scale scenarios. The official RustFS image packages the RustFS binary and its runtime environment into a container, so you can start a service with a single command and persistent storage. +RustFS is an open-source, S3-compatible distributed object storage system. In single-node single-disk (SNSD) mode, RustFS does not use erasure coding and stores no redundant data, so this mode is suitable only for local testing and small workloads. The official RustFS image packages the RustFS binary and its runtime environment into a container, so you can start RustFS with persistent storage by running a single command. The container runs as non-root user `rustfs` with id `10001`, so a bind-mounted host directory must be owned by `10001` to avoid permission denied errors. diff --git a/content/en/installation/index.md b/content/en/installation/index.md index 4d8361f57..bba99c111 100644 --- a/content/en/installation/index.md +++ b/content/en/installation/index.md @@ -14,24 +14,24 @@ After installation, set unique values for `RUSTFS_ACCESS_KEY` and `RUSTFS_SECRET ::: -## Choose Your Path +## Choose your path | Your goal | Recommended path | Guide | | - | - | - | | Try RustFS on a local machine | One-command install script, or a container | [Linux Quick Start](./linux/quick-start.md) · [Container](./container/index.md) | | Single-server production | SNSD (one disk) or SNMD (multiple disks) | [Installing RustFS on Linux](./linux/index.md) | | Multi-server production cluster | MNMD, after completing the production checklists | [Multiple Node Multiple Disk](./linux/multiple-node-multiple-disk.md) · [Checklists](./requirement/checklists/index.md) | -| Kubernetes / cloud-native | Container orchestration deployment | [Cloud Native](./cloud-native/index.md) | +| Kubernetes / cloud-native | Deploy with the Helm chart | [Cloud Native](./cloud-native/index.md) | | Windows or macOS host | Native installation | [Windows](./windows/index.md) · [macOS](./macos/index.md) | ## Deployment Mode Comparison | Mode | Nodes | Disks | Fault Tolerance | Typical Use | | - | - | - | - | - | -| [SNSD](./linux/single-node-single-disk.md) | 1 | 1 | None — rely on backups | Development, testing, low-density non-critical business | -| [SNMD](./linux/single-node-multiple-disk.md) | 1 | Multiple | Up to M parity disks within the node | Medium, non-critical business on a single server | +| [SNSD](./linux/single-node-single-disk.md) | 1 | 1 | None — rely on backups | Development, testing, and small non-critical workloads | +| [SNMD](./linux/single-node-multiple-disk.md) | 1 | Multiple | Up to M parity disks within the node | Mid-sized, non-critical workloads on a single server | | [MNMD](./linux/multiple-node-multiple-disk.md) | 4+ | Multiple per node | Disk- and node-level via erasure coding across servers | Production workloads | ## Checklist -Before any production deployment, work through the [Pre-Installation Checklists](./requirement/checklists/index.md) — hardware, network, software, and security — to make sure your environment meets production guidance. +Before any production deployment, work through the [Pre-Installation Checklists](./requirement/checklists/index.md) — hardware, network, software, and security — to make sure your environment meets production requirements. diff --git a/content/en/installation/linux/index.md b/content/en/installation/linux/index.md index 8f9f4f1be..174723344 100644 --- a/content/en/installation/linux/index.md +++ b/content/en/installation/linux/index.md @@ -13,13 +13,13 @@ After installation, set unique `RUSTFS_ACCESS_KEY` and `RUSTFS_SECRET_KEY` value ## Single Node Single Disk (SNSD) -One server, one data disk. The simplest mode, with no redundancy — a disk failure means data loss, so rely on backups. Suitable for development, testing, and low-density non-critical business. +One server, one data disk. The simplest mode, with no redundancy — a disk failure means data loss, so rely on backups. Suitable for development, testing, and small non-critical workloads. → [Single Node Single Disk installation](./single-node-single-disk.md) ## Single Node Multiple Disk (SNMD) -One server, multiple data disks. Erasure coding shards data across the disks, so the node tolerates a limited number of disk failures, but a whole-server failure still means data loss. Suitable for medium, non-critical business on a single machine. +One server, multiple data disks. Erasure coding shards data across the disks, so the node tolerates a limited number of disk failures, but a whole-server failure still means data loss. Suitable for mid-sized, non-critical workloads on a single machine. → [Single Node Multiple Disk installation](./single-node-multiple-disk.md) @@ -31,4 +31,4 @@ Four or more servers, each with one or more disks. Erasure coding spans servers, ## Before Production -Work through the [Pre-Installation Checklists](../requirement/checklists/index.md) — hardware, network, software, and security — before deploying to production. If you don't need production standards, you can skip them. +Work through the [Pre-Installation Checklists](../requirement/checklists/index.md) — hardware, network, software, and security — before deploying to production. You can skip them for non-production deployments. diff --git a/content/en/installation/linux/multiple-node-multiple-disk.md b/content/en/installation/linux/multiple-node-multiple-disk.md index 797c9cd9e..4f1548f72 100644 --- a/content/en/installation/linux/multiple-node-multiple-disk.md +++ b/content/en/installation/linux/multiple-node-multiple-disk.md @@ -1,16 +1,16 @@ --- title: "RustFS Multiple Node Multiple Disk Installation" -description: "Install RustFS on multiple servers with multiple disks, data will be stored on multiple disks across multiple servers." +description: "Install a distributed RustFS cluster across multiple servers, each with multiple disks." --- -Multiple Node Multiple Disk (MNMD) mode is the deployment mode for production workloads, providing enterprise-grade performance, security, and scalability. A minimum of **4 servers** is required, each with at least 1 disk, to safely start a distributed object storage cluster. +Multiple Node Multiple Disk (MNMD) mode is used for production workloads. It provides node-level fault tolerance and horizontal scalability. A minimum of **4 servers** is required, each with at least 1 disk, to safely start a distributed object storage cluster. ## Topology and Planning In the following architecture, requests are distributed to the servers through load balancing. With the default 12 + 4 erasure coding layout, each object is split into 12 data shards and 4 parity shards stored on different disks across different servers: -- Any single server failure or maintenance does not affect data security. -- Corruption of up to 4 disks does not affect data security. +- The cluster stays available and loses no data if any single server fails or is taken down for maintenance. +- The cluster can tolerate the loss of up to 4 disks without data loss. ```mermaid flowchart TD @@ -29,19 +29,19 @@ flowchart TD class N1D1,N1D2,N1D3,N1D4,N2D1,N2D2,N2D3,N2D4,N3D1,N3D2,N3D3,N3D4,N4D1,N4D2,N4D3,N4D4 disk ``` -Before installation, review the [Pre-Installation Checklists](../requirement/checklists/index.md) and ensure all items meet production guidance. +Before installation, review the [Pre-Installation Checklists](../requirement/checklists/index.md) and make sure that every item meets production requirements. ## Hostnames -Creating a RustFS cluster requires **identical, sequential** hostnames. There are two ways to achieve sequential hostnames: +A RustFS cluster requires hostnames that follow a consistent, sequentially numbered pattern (for example, `node1` through `node4`). There are two ways to achieve sequential hostnames: **1. DNS Configuration:** -Configure your DNS resolution server to ensure name continuity. +Create DNS records so that each sequential hostname resolves to the correct node. -**2. HOSTS Configuration:** +**2. `/etc/hosts` configuration:** -Modify the local alias settings in `/etc/hosts` as follows: +Add the following entries to `/etc/hosts` on every node: ```bash title="/etc/hosts" vim /etc/hosts @@ -86,7 +86,7 @@ sudo mkdir -p /data/rustfs{0..3} /var/log/rustfs /opt/tls sudo chmod -R 750 /data/rustfs* /var/log/rustfs ``` -## Start Service and Verification +## Start and Verify the Service 1. Start the service on every node and enable auto-start on boot: diff --git a/content/en/installation/linux/prerequisites-and-service.md b/content/en/installation/linux/prerequisites-and-service.md index 184bd2259..b526b20d0 100644 --- a/content/en/installation/linux/prerequisites-and-service.md +++ b/content/en/installation/linux/prerequisites-and-service.md @@ -5,13 +5,13 @@ description: "Common prerequisites, disk preparation, binary installation, and s This page contains the prerequisites and service setup steps shared by all three Linux deployment modes — [SNSD](./single-node-single-disk.md), [SNMD](./single-node-multiple-disk.md), and [MNMD](./multiple-node-multiple-disk.md). Complete these steps first, then return to your mode page to configure the environment file and start the service. -## Operating System Version +## Operating system version We recommend Linux kernel version 4.x or later; versions 5.x/6.x achieve better I/O throughput and network performance. Ubuntu 22.04 and RHEL 8.x are both suitable for installing RustFS. ## Firewall -Linux systems have firewalls enabled by default. Check the firewall status with: +Many Linux distributions enable a firewall by default. Check the firewall status with: ```bash systemctl status firewalld @@ -196,36 +196,36 @@ The difference between any two nodes should be negligible (under 1 millisecond i When planning object storage capacity, we recommend considering: - Initial data volume: How much data do you plan to migrate or store at once? (e.g., 500 TB) -- Data growth volume: Daily/weekly/monthly data growth capacity -- Planning cycle: How long should this hardware planning last? (recommended: 3 years) -- Your company's hardware iteration and update cycles. +- Data growth rate: expected daily, weekly, or monthly growth +- Planning horizon: How long should this hardware last? (We recommend 3 years.) +- Your organization's hardware refresh cycle. Review [EC Configuration](../requirement/ec-configuration.md) to calculate usable capacity, understand the automatic parity defaults, and validate any explicit parity or erasure-set width before deployment. ## Disk Planning -Because NFS generates phantom writes and lock issues under high I/O, **NFS is prohibited** as the underlying storage medium for RustFS. We strongly recommend **JBOD (Just a Bunch of Disks)** mode: expose physical disks directly and independently to the operating system, and let the RustFS software layer handle data redundancy and protection. +**Do not use NFS** as the underlying storage for RustFS: under heavy I/O, NFS can cause phantom writes and locking problems. We strongly recommend **JBOD (Just a Bunch of Disks)** mode: expose physical disks directly and independently to the operating system, and let the RustFS software layer handle data redundancy and protection. -The reasons are as follows: +This approach has several advantages: -- **Better Performance:** RustFS's Erasure Coding engine is highly optimized and reads/writes multiple disks concurrently, achieving higher throughput than hardware RAID controllers. Hardware RAID becomes a performance bottleneck. +- **Better Performance:** The RustFS erasure coding engine is highly optimized and reads/writes multiple disks concurrently, achieving higher throughput than hardware RAID controllers. Hardware RAID becomes a performance bottleneck. - **Lower Cost:** No expensive RAID cards needed, reducing hardware procurement costs. -- **Simpler Management:** RustFS manages disks uniformly, simplifying storage layer operations and maintenance. +- **Simpler Management:** RustFS manages disks uniformly, simplifying storage operations. - **Faster Fault Recovery:** The RustFS healing process is faster than a traditional RAID rebuild and has less impact on cluster performance. We recommend NVMe SSDs as the storage medium for higher performance and throughput. ## File System Selection -RustFS strongly recommends formatting all storage disks with the XFS file system. RustFS development and testing are based on XFS, ensuring optimal performance and stability. Avoid other file systems such as ext4, BTRFS, or ZFS, as they may cause performance degradation or unpredictable issues. +We strongly recommend formatting all data disks with XFS. RustFS is developed and tested on XFS. Avoid other file systems such as ext4, Btrfs, or ZFS, as they may cause performance degradation or unpredictable issues. XFS suits RustFS's workload for three reasons: - **High-concurrency I/O:** XFS was designed for high performance and scalability. Its internal journaling and data structures (such as B+ trees) efficiently handle large numbers of parallel read/write requests, matching how RustFS shards large objects and reads/writes multiple disks in an erasure set in parallel. -- **Massive files and large file sizes:** XFS is a 64-bit file system supporting extremely large files (up to 8 EB). Its metadata management stays efficient even with millions of files in a single directory — important because RustFS stores each object (or object version) as an independent file. +- **Many files and very large files:** XFS is a 64-bit file system supporting extremely large files (up to 8 EB). Its metadata management stays efficient even with millions of files in a single directory — important because RustFS stores each object (or object version) as an independent file. - **Space reservation:** XFS provides an efficient `fallocate` API. RustFS uses it to reserve contiguous disk space before writing objects, avoiding the overhead of dynamic expansion and metadata updates during writes and minimizing file fragmentation. -For better disk discovery, we recommend using **Label** tags when formatting XFS file systems. +To make disks easier to identify and mount, we recommend assigning a file system label (`-L`) when you format each disk. First, check the disk layout: @@ -250,7 +250,7 @@ sudo mkfs.xfs -i size=512 -n ftype=1 -L RUSTFS0 /dev/sdb Formatting options: - `-L -### Unmount Failed Disk +### Unmount the failed disk -Before replacing the physical hard drive, you need to safely unmount the failed disk from the operating system level to avoid I/O errors in the file system or RustFS during the replacement process. +Before replacing the physical hard drive, unmount the failed disk at the operating system level to prevent I/O errors in the file system or RustFS during replacement. ```bash # Assume the failed disk is /dev/sdb @@ -27,8 +18,8 @@ umount /dev/sdb :::note[Notes] -* If there are multiple mount points, execute `umount` separately. -* If encountering "device is busy", you can first stop the RustFS service: +* If the disk has multiple mount points, run `umount` on each one. +* If you see a "device is busy" error, stop the RustFS service first: ```bash systemctl stop rustfs @@ -38,7 +29,7 @@ systemctl stop rustfs -### Replace Failed Disk +### Replace the failed disk After physically replacing the failed disk, you need to partition and format the new disk, and apply the same label as the original disk. @@ -49,15 +40,15 @@ mkfs.xfs -L DISK1 /dev/sdb > **Requirements** > -> * New disk capacity ≥ original disk capacity; +> * The new disk is at least as large as the original disk. > * File system type consistent with other disks (XFS, per the [installation guide](../installation/linux/index.md)); -> * Recommend using labels (LABEL) or UUID for mounting to ensure disk order is not affected by system restarts. +> * We recommend mounting by label (LABEL) or UUID so that disk order is not affected by a system restart. -### Update `/etc/fstab` or RustFS Configuration +### Update `/etc/fstab` or the RustFS configuration -Confirm that the mount item labels or UUIDs in `/etc/fstab` point to the new disk. The mount point must stay identical to the one listed in `RUSTFS_VOLUMES` (in `/etc/default/rustfs`), so the healed disk rejoins the cluster at the same path. +Confirm that the labels or UUIDs in the `/etc/fstab` entries point to the new disk. The mount point must stay identical to the one listed in `RUSTFS_VOLUMES` (in `/etc/default/rustfs`), so the healed disk rejoins the cluster at the same path. ```bash # View current fstab @@ -76,7 +67,7 @@ blkid /dev/sdb # Get the new partition's UUID, then replace the corresponding field in fstab ``` -* After modifying fstab, be sure to validate syntax: +* After you edit `/etc/fstab`, validate the syntax: ```bash mount -a # If no errors, configuration is correct @@ -86,30 +77,30 @@ mount -a # If no errors, configuration is correct -### Remount New Disk +### Remount the new disk -Execute the following commands to batch mount all disks and start the RustFS service: +Run the following commands to mount all configured file systems and start RustFS: ```bash mount -a systemctl start rustfs ``` -Confirm all disks are mounted normally: +Verify that all expected file systems are mounted: ```bash df -h | grep /data/rustfs ``` -:::note +:::note[If a mount fails] -If some mounts fail, please check if fstab entries are consistent with disk labels/UUIDs. +If a mount fails, check that the labels or UUIDs in `/etc/fstab` match those on the target file system. ::: -### Trigger and Monitor Data Healing +### Trigger and monitor data healing Once RustFS detects a freshly formatted disk at a known mount point, its background scanner heals the missing data onto it automatically — no manual command is required. Confirm that recovery has started and track its progress through the service logs: @@ -125,24 +116,24 @@ You can also open the RustFS Console and check the disk status of the affected n :::note[Notes] -* The healing process will complete in the background, usually with minimal impact on online access; -* After healing is complete, the tool will report success or list failed objects. +* Healing runs in the background and usually has little impact on client requests. +* After healing completes, the tool reports success or lists the objects that failed. ::: -### Follow-up Checks and Notes +### Follow-up checks and notes 1. **Performance Monitoring** - * I/O may fluctuate slightly during healing, recommend monitoring disk and network load. + * I/O load may fluctuate during healing. We recommend monitoring disk and network utilization. 2. **Batch Failures** - * If multiple failures occur in the same batch of disks, consider more frequent hardware inspections. -3. **Regular Drills** + * If several disks from the same manufacturing batch fail, inspect the remaining disks from that batch more often. +3. **Regular failure tests** - * Regularly simulate disk failure drills to ensure team familiarity with recovery processes. + * Run regular disk failure drills so your team can practice the recovery procedure. 4. **Maintenance Windows** - * When failure rates are high, arrange dedicated maintenance windows to speed up replacement and healing. + * When failure rates are high, schedule dedicated maintenance windows to speed up replacement and healing. diff --git a/content/en/troubleshooting/index.md b/content/en/troubleshooting/index.md index 2d67143db..56ba12d31 100644 --- a/content/en/troubleshooting/index.md +++ b/content/en/troubleshooting/index.md @@ -3,9 +3,9 @@ title: "Troubleshooting" description: "Diagnose and resolve RustFS issues." --- -Contents: +This section covers: - [Node Failures](./node.md) -- [Driver Failures](./driver.md) +- [Drive Failures](./driver.md) - [Node Healing](../operations/high-availability/node-healing.md) diff --git a/content/en/troubleshooting/node.md b/content/en/troubleshooting/node.md index 34f8fe953..859437d43 100644 --- a/content/en/troubleshooting/node.md +++ b/content/en/troubleshooting/node.md @@ -1,48 +1,48 @@ --- title: "Node Failures" -description: "Complete steps for handling node failures in RustFS clusters. Mainly includes: replacement node hardware preparation, configuration updates, service deployment, rejoining the cluster, data healing, and subsequent checks and best practices." +description: "Prepare a replacement node, update its configuration, restore cluster membership, and verify data healing." --- -In distributed RustFS clusters, erasure coding mechanisms are adopted to ensure read/write access can still be provided when some nodes fail, and automatic data healing occurs after nodes rejoin. This document will guide you through the following process: +A distributed RustFS cluster uses erasure coding to stay readable and writable when some nodes fail, and it heals data automatically when a node rejoins. This guide walks you through the following steps: -1. Start replacement node and synchronize environment -2. Update DNS/hostname to point old node identifiers to new nodes -3. Download and deploy RustFS services consistent with the cluster -4. Rejoin new nodes to the cluster and trigger data healing -5. Monitor healing progress and perform subsequent checks and optimization +1. Start the replacement node and match its software environment to the cluster. +2. Update DNS or `/etc/hosts` so the old hostname resolves to the new node. +3. Install the same RustFS version the cluster is already running. +4. Start the replacement node so it rejoins the cluster and begins data healing. +5. Monitor healing and finish the follow-up checks. -## 1) Start Replacement Node +## 1. Prepare the replacement node * **Hardware and System Preparation** - Ensure the replacement node server hardware is roughly consistent with the failed node, including CPU, memory, network configuration, and disk type; even using higher configurations won't affect cluster performance. - Software environment needs to maintain version consistency with other nodes (operating system, kernel, dependency libraries, etc.) to avoid cluster abnormal behavior caused by environment differences. + Make sure the replacement node's hardware roughly matches the failed node, including CPU, memory, network, and disk type. Using a higher-spec configuration does not affect cluster performance. + Use software versions that match the other nodes, including the operating system, kernel, and dependencies, to avoid problems caused by inconsistent environments. -* **Drive Exclusive Access** - As with physical drive operations, RustFS requires exclusive access to storage volumes, prohibiting any other processes or scripts from directly modifying data within storage volumes, otherwise data corruption or redundancy loss can easily occur. +* Exclusive access to drives + As with physical drive operations, RustFS requires exclusive access to its storage volumes. Do not let other processes or scripts modify data on these volumes directly, as this can corrupt data or reduce redundancy. -## 2) Update Hostname and Network Resolution +## 2. Update hostname resolution * **DNS/Hosts Configuration** - If the replacement node's IP address differs from the failed node, you need to re-resolve the old node's hostname (such as `rustfs-node-2.example.net`) to the new node to ensure nodes within the cluster discover each other through the same address. + If the replacement node's IP address differs from the failed node, point the old node's hostname (for example, `rustfs-node-2.example.net`) to the new node's IP address so that cluster nodes can still reach each other by the same name. ```bash # Example: Add or modify line in /etc/hosts 192.168.1.12 rustfs-node-2.example.net ``` - After correct resolution, you can verify the hostname points to the new node through `ping` or `nslookup`. + Use `ping` or `nslookup` to verify that the hostname resolves to the new node. -## 3) Deploy and Configure RustFS Services +## 3. Deploy and configure RustFS * **Download and Installation** - Follow the same version deployment process as RustFS official, download binaries or installation packages consistent with existing nodes, and extract to a unified directory. Ensure startup scripts, environment variables, and configuration files (such as `/etc/default/rustfs`) are completely consistent with other nodes in the cluster. + Install the same RustFS version as the existing nodes, using the same installation method and directory. Make sure that startup scripts, environment variables, and configuration files (such as `/etc/default/rustfs`) are identical to those on the other nodes. * **Configuration Verification** * Check that `RUSTFS_VOLUMES` in `/etc/default/rustfs` is byte-for-byte identical to the other nodes, and that it covers the replacement node's hostname and port. - * Ensure all nodes have the same access keys and permission configurations to avoid new nodes being unable to join due to authentication failures. + * Make sure that all nodes use the same access keys and permission settings; otherwise, the new node fails to authenticate and cannot join the cluster. -## 4) Rejoin Cluster and Trigger Data Healing +## 4. Rejoin the cluster and start healing * **Start Service** @@ -50,7 +50,7 @@ In distributed RustFS clusters, erasure coding mechanisms are adopted to ensure systemctl start rustfs ``` - Or use your custom startup script to start RustFS services, and view startup logs through `journalctl -u rustfs -f` to confirm the new node has detected other online nodes and started the data healing process. + Alternatively, start RustFS with your own startup script. Then run `journalctl -u rustfs -f` to confirm that the new node has detected the other nodes and started healing. * **Monitor Healing Status** Healing runs in the background once the node rejoins; no manual command is required. Watch its progress through the service logs on the replacement node, and check node and disk status in the RustFS Console: @@ -59,25 +59,25 @@ In distributed RustFS clusters, erasure coding mechanisms are adopted to ensure journalctl -u rustfs -f ``` -* **Community Experience Reference** - Community testing shows that when nodes go offline and rejoin, RustFS will only perform healing operations on new nodes, not fully rebalance the cluster, thus avoiding unnecessary network and I/O peaks. +* **Community observations** + In community testing, when a node goes offline and rejoins, RustFS heals only that node instead of rebalancing the entire cluster. This avoids unnecessary network and I/O spikes. -## 5) Subsequent Checks and Best Practices +## 5. Follow-up checks and best practices * **Monitoring and Alerts** - * During healing, monitor disk and network load to ensure the cluster meets read/write and network bandwidth requirements. + * During healing, monitor disk and network load to make sure the cluster still meets its read, write, and bandwidth requirements. * Set up alerts to notify operations teams when node healing fails or progress stalls beyond thresholds. -* **Repeated Failure Drills** - Regularly simulate node failures and drill the entire recovery process to ensure team familiarity with operation commands and emergency procedures. +* **Regular failure testing** + Run regular node failure drills and practice the full recovery procedure so your team is familiar with the commands and incident response process. * **Root Cause Analysis** - Conduct in-depth hardware health diagnostics (SMART, BIOS logs, etc.) on frequently failing nodes or disks, and implement preventive maintenance plans. + Run detailed hardware diagnostics (for example, SMART data and BIOS logs) on nodes or disks that fail repeatedly, and put a preventive maintenance plan in place. * **Professional Support** - If deeper-level fault location and recovery guidance is needed, contact the RustFS development team or community for help. + For help diagnosing the cause of a failure or recovering the cluster, contact the RustFS development team or community. --- -**Summary**: Through the above process, RustFS can quickly and safely replace nodes and complete data healing after node hardware completely fails, minimizing cluster availability interruptions. Be sure to cross-reference with your own environment and specific command-line tools to ensure configuration consistency and correct operation sequence. +Following these steps lets you replace a failed node and heal its data with minimal disruption. Adapt the commands to your environment, and keep the configuration identical across nodes. From c175eb045bbefc8e7b53fe91a99e46e76448a919 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Wed, 14 Oct 2026 04:24:42 +0000 Subject: [PATCH 2/2] docs: document default ports 9000 and 9001 Replace the outdated launcher port 7001 with the confirmed defaults: S3 API on 9000 and the Console on 9001. Co-authored-by: RustFS --- content/en/administration/console/index.md | 2 +- content/en/installation/windows/index.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/content/en/administration/console/index.md b/content/en/administration/console/index.md index e8af749ff..0877c14cf 100644 --- a/content/en/administration/console/index.md +++ b/content/en/administration/console/index.md @@ -31,7 +31,7 @@ http://:9001 ![RustFS Console login page with key, STS, and OIDC sign-in options](./images/rustfs-console-login.png) -For a local deployment, use `http://localhost:9001`. Windows and macOS desktop launchers use port `7001` instead. +For a local deployment, including the Windows and macOS desktop launchers, open `http://localhost:9001`. The S3 API listens on port `9000`. If the login page cannot reach the target RustFS service, select **Server Configuration** or open `/config`. Enter the externally reachable RustFS service address and save it after the health check succeeds. **Reset** clears the saved address; **Skip** returns to login without changing it. diff --git a/content/en/installation/windows/index.md b/content/en/installation/windows/index.md index f95b47e6f..1612217f6 100644 --- a/content/en/installation/windows/index.md +++ b/content/en/installation/windows/index.md @@ -173,7 +173,7 @@ Stop the conflicting application or select unused ports, then start RustFS again ### The Console does not open -For Launcher, confirm that **Console Endpoint** is enabled. For the standalone binary, confirm that the process is still running and that `--console-enable true` is present. The current Console default is port `9001`; port `7001` is not used by the current Launcher configuration. +For Launcher, confirm that **Console Endpoint** is enabled. For the standalone binary, confirm that the process is still running and that `--console-enable true` is present. The S3 API listens on port `9000` and the Console on port `9001`. ### Launcher reports an external RustFS process