RustFS 部署与 Python 调用指南

一、RustFS 部署文档

本章节将指导您如何在 Linux 服务器上通过 Docker 快速部署 RustFS 服务，并完成基础配置。

环境准备

• 操作系统：Linux (推荐 Ubuntu 20.04+ / CentOS 7+)

• 软件依赖：Docker 20.10+ 和 Docker Compose (可选)

• 硬件建议：2核CPU / 4GB内存 / SSD存储

Docker 快速部署 拉取镜像并启动容器

# 创建数据存储目录
mkdir -p /opt/rustfs/data
chmod 777 /opt/rustfs/data

# mac中只有User目录下有权限故而修改
mkdir -p ~/rustfs/data
chmod 777 ~/rustfs/data

# 启动 RustFS 容器
docker run -d \
  --name rustfs \
  -p 9000:9000 \
  -p 9001:9001 \
  -e RUSTFS_ACCESS_KEY=admin \
  -e RUSTFS_SECRET_KEY=password123 \
  -v ~/rustfs/data:/data \
  rustfs/rustfs:latest

参数说明

• -p 9000:9000：API 服务端口（用于 SDK 连接）

• -p 9001:9001：Web 控制台端口

• -e RUSTFS_ACCESS_KEY：设置访问密钥（请修改为强密码）

• -e RUSTFS_SECRET_KEY：设置访问密钥（请修改为强密码）

• -v /opt/rustfs/data:/data：数据持久化目录, macbook上这里路径，我进行了修改

验证服务状态

# 查看容器日志
docker logs -f rustfs

# 预期输出包含 "API: http://0.0.0.0:9000" 和 "Console: http://0.0.0.0:9001"

Web 控制台配置

1. 访问 http://<服务器IP>:9001

2. 使用设置的 RUSTFS_ACCESS_KEY 和 RUSTFS_SECRET_KEY 登录

3. 创建存储桶（Bucket）：

   • 点击 "Create Bucket"

   • 输入名称（如 images）

   • 选择版本控制（可选）

4. 设置访问策略（重要）：

   • 进入存储桶详情页

   • 点击 "Access Rules" → "Add Access Rule"

   • 前缀：*

   • 权限：public（公开读）或 private（私有）

安全加固建议

• 修改默认端口：通过 -p 参数映射非标准端口

• 启用 HTTPS：使用 Nginx 反向代理配置 SSL 证书

• 防火墙配置：仅开放必要端口（9000/9001）

# UFW 防火墙示例
ufw allow 9000/tcp
ufw allow 9001/tcp

二、Python 调用方式

本章节将介绍如何使用 Python SDK 连接 RustFS，实现文件上传、下载等操作。

🛠️ 1. 安装依赖

首先，确保你的 Python 环境中安装了 boto3：

pip install boto3

🚀 2. 完整代码示例 (适配你的环境)

这段代码封装了一个简单的客户端，专门针对你本地的 Docker RustFS 环境（端口 9000，默认账号密码）。

import boto3
from botocore.client import Config
from botocore.exceptions import ClientError

class RustFSClient:
    def __init__(self):
        # 这里的配置完全对应你找到的文档，但修改了 endpoint 和 key
        self.client = boto3.client(
            's3',
            endpoint_url='http://localhost:9000',  # 你的 Docker 地址
            aws_access_key_id='rustfsadmin',       # 你的 Access Key
            aws_secret_access_key='rustfsadmin',   # 你的 Secret Key (如果你没改过)
            config=Config(signature_version='s3v4'), # 必须使用 v4 签名
            region_name='us-east-1'                # 任意填写，RustFS 不校验
        )

    def create_bucket(self, bucket_name):
        """创建存储桶（如 user-avatars, project-images）"""
        try:
            self.client.create_bucket(Bucket=bucket_name)
            print(f"✅ 存储桶 '{bucket_name}' 创建成功！")
        except ClientError as e:
            if e.response['Error']['Code'] == 'BucketAlreadyOwnedByYou':
                print(f"ℹ️ 存储桶 '{bucket_name}' 已存在，跳过创建。")
            else:
                print(f"❌ 创建失败: {e}")

    def upload_image(self, bucket_name, file_path, object_name=None):
        """上传图片"""
        if not object_name:
            object_name = file_path.split('/')[-1] # 默认使用文件名
            
        try:
            self.client.upload_file(file_path, bucket_name, object_name)
            print(f"✅ 上传成功: {file_path} -> s3://{bucket_name}/{object_name}")
            
            # 生成公开访问链接 (假设桶是公开的)
            public_url = f"{self.client.meta.endpoint_url}/{bucket_name}/{object_name}"
            return public_url
        except ClientError as e:
            print(f"❌ 上传失败: {e}")
            return None

    def get_presigned_url(self, bucket_name, object_name, expiration=3600):
        """生成私有文件的临时访问链接 (如头像)"""
        try:
            url = self.client.generate_presigned_url(
                'get_object',
                Params={'Bucket': bucket_name, 'Key': object_name},
                ExpiresIn=expiration
            )
            return url
        except ClientError as e:
            print(f"❌ 生成链接失败: {e}")
            return None

# --- 测试运行 ---
if __name__ == "__main__":
    # 1. 初始化
    fs = RustFSClient()
    
    # 2. 创建两个桶 (对应你之前的需求)
    fs.create_bucket("user-avatars")
    fs.create_bucket("project-images")
    
    # 3. 模拟上传 (请确保你当前目录下有个 test.jpg，或者修改文件名)
    # 假设你有一个 test.jpg 文件
    # url = fs.upload_image("project-images", "test.jpg")
    # if url: print(f"公开访问地址: {url}")

💡 3. 关键点解析 (基于文档)

这份文档里有几个配置是必须的，否则连不上 RustFS：

1. signature_version='s3v4':

   • 这是最重要的配置。如果不加这一行，Boto3 可能会尝试使用旧版签名，导致报错 SignatureDoesNotMatch。

2. endpoint_url:

   • 这是 RustFS 的地址。如果你在 Mac 本地运行，就是 http://localhost:9000。

   • 如果你的 Python 代码是在另一个 Docker 容器里运行，这里需要填 http://host.docker.internal:9000 (Mac 特有) 或者局域网 IP。

3. region_name:

   • RustFS 其实不在乎你填什么区域，但 Boto3 强制要求填一个，填 'us-east-1' 是惯例。

🛡️ 4. 关于权限的补充

文档中提到了“生成预签名 URL”（5.1 节），这对你存储用户头像非常有用：

• 场景：用户上传头像，你存进 user-avatars 桶。这个桶是私有的（为了安全）。

• 展示：当其他用户访问这个人的主页时，你的后端代码调用 get_presigned_url 生成一个带签名的临时链接（比如有效期 1 小时），返回给前端展示。

而对于项目图片，你可以像文档 4.2 节那样直接上传，只要你在 RustFS 控制台把 project-images 桶设为公开（Public），就可以直接用 http://IP:9000/project-images/xxx.jpg 访问了。