目录

1. 项目概述
2. 核心特性
3. 架构设计
4. 快速部署
   • 4.1 二进制单机部署
   • 4.2 Docker Compose 部署
   • 4.3 Kubernetes 云原生部署
5. 基础命令操作
6. S3 兼容开发示例
   • Python Boto3
   • Java SpringBoot
7. 集群高可用部署
8. 运维监控
9. 对比 MinIO / Ceph 优势
10. 常见问题 FAQ
11. 许可证与社区

1. 项目概述

RustFS 是基于 Rust 语言开发的高性能分布式对象存储系统，完全兼容 AWS S3 标准协议，主打私有化部署、低延迟、无GC抖动、商用友好 Apache 2.0 开源协议，是 MinIO 国产化替代方案。

定位区分

• 不是本地文件系统（ext4/xfs）：RustFS 是上层对象存储服务，运行在操作系统文件系统之上；
• 对标产品：MinIO（单机对象存储）、Ceph（分布式块/对象存储）；
• 适用场景：AI 模型存储、数据湖、文件备份、IoT 边缘存储、政企私有云、混合云多云架构。

版本信息

• 当前稳定版：v1.0.0-beta.3（2026-05-14）
• 二进制包体积：<100MB，静态编译 musl 无依赖
• 支持架构：x86_64 / aarch64(ARM64)；系统 Linux/macOS/Windows

2. 核心特性

1. 完整 S3 协议兼容
   支持桶管理、分片上传、预签名URL、对象生命周期、存储分层（热/温/冷），所有标准 S3 SDK 无需修改代码即可对接。
2. Rust 原生性能优势
   • 无 GC，不存在内存停顿，P99 延迟稳定 10ms 级；
   • 编译期内存安全，杜绝缓冲区溢出、野指针、数据竞争；
   • 高并发 IO，多路复用异步 IO，同等硬件吞吐高于 Go 实现的 MinIO。
3. 商用友好开源协议
   Apache 2.0，允许商用修改、闭源二次开发，无 AGPL 传染限制（MinIO 商业版收费，开源 AGPL 限制大）。
4. 分布式高可用架构
   去中心化集群，横向扩容，多副本数据容错，支持纠删码，单集群支持百TB~PB级存储。
5. 云原生原生适配
   内置 Docker 镜像、K8s Operator，支持容器化一键部署，适配 ACK/EKS/Tanzu 等云厂商集群。
6. 轻量化易运维
   单二进制程序，无中间件依赖；内置 Web 可视化控制台；提供官方 rustfs-cli 命令行工具。
7. 跨平台与国产化适配
   原生 ARM64 优化，支持国产鲲鹏、飞腾；适配信创服务器操作系统。

3. 架构设计

分层架构

1. 接入层
   HTTP S3 API、Web 控制台、rustfs-cli 客户端、负载均衡/Nginx 反向代理。
2. 核心服务层
   • 认证鉴权：AccessKey/SecretKey、TLS HTTPS、对接 KeyCloak 统一身份；
   • 对象管理：桶、元数据、分片上传、预签名链接；
   • 分布式调度：节点数据分片、副本、纠删码、扩容均衡；
3. 存储层
   分层存储：热层 NVMe SSD、温层 HDD、冷层归档/对象归档；
4. 可观测层
   Prometheus 指标、Grafana 看板、日志采集、审计日志、告警通知。

数据存储机制

• 扁平化对象命名空间，无目录层级限制；
• 默认 3 副本策略，支持自定义纠删码（N+M）节省磁盘空间；
• 元数据与数据分离存储，元数据内存缓存加速查询。

4. 快速部署

4.1 Linux 二进制单机部署

# 1. 下载静态二进制 x86_64
curl -O https://github.com/rustfs/rustfs/releases/download/1.0.0-beta.3/rustfs-linux-x86_64-musl.zip
unzip rustfs-linux-x86_64-musl.zip
chmod +x rustfs

# 2. 创建数据目录
mkdir -p /data/rustfs
chmod 755 /data/rustfs

# 3. 环境变量配置（可选）
export RUSTFS_ADDRESS="0.0.0.0:9000"
export RUSTFS_CONSOLE_ADDRESS="0.0.0.0:9001"
export RUSTFS_ACCESS_KEY="admin"
export RUSTFS_SECRET_KEY="SuperStrongPass123!"

# 4. 启动服务
./rustfs /data/rustfs

# 默认账号（未配置环境变量时）
# AccessKey: rustfsadmin
# SecretKey: rustfsadmin

4.2 Docker Compose 单机部署

docker-compose.yml

version: "3.8"
services:
  rustfs:
    image: rustfs/rustfs:latest
    container_name: rustfs
    restart: always
    environment:
      RUSTFS_ADDRESS: "0.0.0.0:9000"
      RUSTFS_CONSOLE_ENABLE: "true"
      RUSTFS_CONSOLE_ADDRESS: "0.0.0.0:9001"
      RUSTFS_ACCESS_KEY: "admin"
      RUSTFS_SECRET_KEY: "Admin@123456"
    volumes:
      - rustfs_data:/data/rustfs
    ports:
      - "9000:9000" # S3 API端口
      - "9001:9001" # Web控制台端口
volumes:
  rustfs_data:

启动命令：

docker-compose up -d
# 查看日志
docker-compose logs -f rustfs

4.3 Kubernetes Operator 部署

官方提供 rustfs-operator CRD，一键创建分布式集群，支持自动扩缩容、存储卷管理、监控组件自动部署，适配私有云 K8s 集群。

5. 基础命令操作

5.1 官方客户端 rustfs-cli

安装：

# Cargo 安装
cargo install rustfs-cli
# Linux
brew install rustfs/tap/rc

常用操作：

# 1. 配置服务别名
rustfs-cli alias set local http://127.0.0.1:9000 admin Admin@123456

# 2. 创建存储桶
rustfs-cli mb local/test-bucket

# 3. 本地文件上传
rustfs-cli cp ./demo.txt local/test-bucket/demo.txt

# 4. 列出桶内对象
rustfs-cli ls local/test-bucket

# 5. 下载对象到本地
rustfs-cli cp local/test-bucket/demo.txt ./download.txt

# 6. 删除对象
rustfs-cli rm local/test-bucket/demo.txt

# 7. 生成10分钟临时访问链接
rustfs-cli presign local/test-bucket/demo.txt 600

5.2 Web 控制台

访问 http://服务器IP:9001，输入 AccessKey/SecretKey，可视化操作桶、文件、权限、生命周期规则。

6. S3 兼容开发示例

6.1 Python boto3 示例

import boto3
from botocore.config import Config

# 配置RustFS服务
ENDPOINT = "http://127.0.0.1:9000"
AK = "admin"
SK = "Admin@123456"
BUCKET = "test-bucket"

# 初始化S3客户端
client = boto3.client(
    "s3",
    endpoint_url=ENDPOINT,
    aws_access_key_id=AK,
    aws_secret_access_key=SK,
    config=Config(signature_version="s3v4")
)

# 1. 创建桶
client.create_bucket(Bucket=BUCKET)

# 2. 上传文本对象
client.put_object(
    Bucket=BUCKET,
    Key="hello.txt",
    Body=b"Hello RustFS Object Storage"
)

# 3. 读取对象
resp = client.get_object(Bucket=BUCKET, Key="hello.txt")
print(resp["Body"].read().decode())

# 4. 生成临时下载链接
url = client.generate_presigned_url(
    "get_object",
    Params={"Bucket": BUCKET, "Key": "hello.txt"},
    ExpiresIn=600
)
print("临时访问链接：", url)

6.2 SpringBoot Java 集成

配置文件 application.yml

rustfs:
  endpoint: http://127.0.0.1:9000
  access-key: admin
  secret-key: Admin@123456
  bucket-name: test-bucket

配置类

import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.context.annotation.Bean;
import software.amazon.awssdk.auth.credentials.StaticCredentialsProvider;
import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.s3.S3Client;
import java.net.URI;

@Configuration
@ConfigurationProperties(prefix = "rustfs")
public class RustFSConfig {
    private String endpoint;
    private String accessKey;
    private String secretKey;
    private String bucketName;

    @Bean
    public S3Client s3Client() {
        return S3Client.builder()
                .endpointOverride(URI.create(endpoint))
                .region(Region.CN_NORTH_1)
                .credentialsProvider(StaticCredentialsProvider.create(
                        AwsBasicCredentials.create(accessKey, secretKey)
                ))
                .forcePathStyle(true)
                .build();
    }
    // getter/setter
}

7. 集群高可用部署

4节点最小集群示例

# 环境变量统一密钥
export RUSTFS_ACCESS_KEY=cluster-admin
export RUSTFS_SECRET_KEY=Cluster@Pass2026

# 每个节点执行，串联所有节点存储目录
rustfs server http://node1:9000/data1,http://node2:9000/data2,http://node3:9000/data3,http://node4:9000/data4

集群特性：

• 自动数据分片均衡，新增节点自动迁移数据；
• 支持 2~N 副本，磁盘损坏自动修复副本；
• 无中心元数据节点，单节点故障不影响整体服务。

8. 运维监控

1. Prometheus 指标暴露
   默认地址 http://ip:9000/metrics，包含IO吞吐、请求QPS、延迟分位数、磁盘使用率、副本健康状态。
2. Grafana 官方看板
   项目仓库提供预制 Dashboard JSON，一键导入查看集群状态。
3. 日志审计
   记录所有桶增删、文件上传下载、鉴权失败操作日志，支持输出至 ELK。
4. TLS 加密
   启动参数指定证书开启 HTTPS：

   ./rustfs --tls-path /etc/ssl/certs /data/rustfs
   

9. 对比 MinIO / Ceph 优势

维度	RustFS	MinIO	Ceph
开发语言	Rust（无GC）	Go（GC延迟抖动）	C++
开源协议	Apache 2.0（商用自由）	AGPLv3（开源版商用受限）	LGPL
部署复杂度	单二进制，极简	单二进制	极高，运维成本重
内存延迟	稳定无停顿	高并发GC抖动	稳定，资源占用高
二进制体积	<100MB	数百MB	多组件庞大
ARM/国产化优化	原生深度优化	基础支持	适配复杂
适用规模	TB~PB 私有云/边缘	中小规模单机	超大规模数据中心

10. 常见问题 FAQ

Q1：9000端口被占用，如何修改端口？

修改环境变量 RUSTFS_ADDRESS=0.0.0.0:9002，同时同步修改客户端、docker 端口映射。

Q2：原有 MinIO 业务能否无缝迁移 RustFS？

可以，完全兼容 S3 API，无需修改业务代码，仅更换 endpoint、AK/SK。

Q3：单机磁盘损坏，数据是否丢失？

默认3副本策略，单块磁盘损坏数据无损；集群模式多节点冗余，单节点宕机不丢失数据。

Q4：是否支持文件断点续传大文件？

支持 S3 MultipartUpload 分片上传，自动断点续传，支持单文件 TB 级上传。

Q5：如何限制桶访问权限？

Web控制台配置桶策略（私有/公开读/公开读写），支持自定义 JSON 权限策略。

11. 许可证与社区

• 开源协议：Apache License 2.0
• GitHub 仓库：https://github.com/rustfs/rustfs
• 官方文档站：https://docs.rustfs.cn
• 社区支持：Discord、国内技术交流群、企业付费技术支持
• 适用授权场景：企业商用、二次闭源开发、私有化交付、信创项目

附录：启动完整参数列表

./rustfs --help
--address: S3 API监听地址
--console-address: Web控制台地址
--tls-path: TLS证书目录，开启HTTPS
--access-key: 管理员AK
--secret-key: 管理员SK
--obs-endpoint: 监控指标上报地址
--console-enable: 是否开启Web控制台