十分钟在自己机器上跑通一个 S3 兼容对象存储（RustFS + Docker）-开发者社区

本地联调代码要一个对象存储、给客户做 POC 要演示、边缘小站想垫一层存储底座，都不值得专门为它采购和运维一套分布式集群。一条 docker run 就能在笔记本或一台小服务器上把 RustFS 跑起来，S3 接口直接可用，代码里把 endpoint 指过来就能测。这篇把从拉镜像到用 aws-cli 建桶的完整路径走一遍，并把几个最容易卡住的点讲清楚。

端口和镜像先到位

Docker Engine 要 20.10 以上，主机上 9000（S3 API）和 9001（控制台）两个端口可用，或者你自己改端口也行。先把镜像拉下来，建个命名卷让容器重建后数据不丢：

dockerpull rustfs/rustfs:latestdockervolume create rustfs-data

一条命令起服务

把占位符换成你自己的密钥再跑，重点是把 access key 和 secret key 都设上，别留空也别用rustfsadmin这种众所周知的值：

dockerrun-d\--namerustfs\--restartunless-stopped\-p9000:9000\-p9001:9001\-vrustfs-data:/data\-eRUSTFS_ACCESS_KEY="<your-access-key>"\-eRUSTFS_SECRET_KEY="<your-secret-key>"\-eRUSTFS_ADDRESS=":9000"\-eRUSTFS_CONSOLE_ADDRESS=":9001"\-eRUSTFS_CONSOLE_ENABLE=true\-eRUSTFS_OBS_LOGGER_LEVEL=error\-eRUSTFS_OBS_LOG_DIRECTORY="/var/log/rustfs/"\rustfs/rustfs:latest\/data

RUSTFS_CONSOLE_ENABLE=true才会开 9001 控制台；RUSTFS_ADDRESS和RUSTFS_CONSOLE_ADDRESS分别管 S3 和控制台的监听地址。同一个配置也能用命令行参数传，--access-key、--address这类，而且命令行参数优先级高于环境变量。

一个权限坑：容器里的用户不是 root

RustFS 容器以非 root 用户rustfs（UID10001）运行。如果你用主机目录挂载（-v /path/on/host:/data）而不是命名卷，目录所有者必须改成10001，否则会权限拒绝：

chown-R10001:10001 /path/to/host_directory

用命名卷就省掉这步，所以本地起服务优先命名卷。

起来先探活，再开控制台

别急着登控制台，先用健康检查端点确认服务在：

dockerps--filtername=rustfscurl--failhttp://localhost:9000/health

curl --fail返回 0 说明 S3 接口已经起来了，控制台在http://localhost:9001，用上面设的密钥登录。

顺手验一下 S3 通路

探活通过后用 aws-cli 建个桶、传个文件，确认整条链路通：

exportAWS_ACCESS_KEY_ID="<your-access-key>"exportAWS_SECRET_ACCESS_KEY="<your-secret-key>"exportAWS_DEFAULT_REGION=us-east-1 aws --endpoint-url http://localhost:9000 s3 mb s3://demo aws --endpoint-url http://localhost:9000 s3cp./local-file.txt s3://demo/

能传能取，本地的对象存储就真的能当 S3 用了。习惯用 MinIO Client 的也可以：mc alias set rustfs http://localhost:9000 <key> <secret>之后mc mb rustfs/demo。停服就docker stop rustfs，重启就docker start rustfs，命名卷里的数据还在。

日志和常见报错

容器日志用docker logs --follow rustfs实时跟。RustFS 自己把运行日志写到RUSTFS_OBS_LOG_DIRECTORY（上面设的是/var/log/rustfs/），这个容器内路径记得挂出来或挂命名卷，否则容器一删日志也没了。想看更细的日志，把RUSTFS_OBS_LOGGER_LEVEL从error临时调到info，能看到更细的启动和请求日志，定位完记得调回去。

起不来和必须处理的情况基本就这几类：端口被占用（bind: address already in use），换-p映射或停掉占端口的进程；权限拒绝，是主机目录没chown 10001（见上）；凭证还留着默认值，容器能起，但官方要求接入网络前就换成唯一密钥，处置办法是停掉容器、带-e凭证参数重建，数据卷不受影响。

命名卷还是绑定挂载

命名卷（rustfs-data）由 Docker 管理，权限和生命周期都省心，本地联调首选。要直接摸到宿主机上的文件（比如把对象导出来看），才用绑定挂载-v /path:/data，代价就是自己管10001那个 UID 的归属。两种方式的 S3 行为完全一致，按你需不需要直接看盘上文件来选。

想顺带看监控？用 Compose 一把拉起可观测栈

官方仓库里的docker-compose.yml除了 RustFS 本身，还带了 grafana、prometheus、otel-collector、jaeger、loki、tempo 等可观测服务（另有 tempo-init 初始化容器和 nginx 反代）。想一起跑：

gitclone https://github.com/rustfs/rustfs.gitcdrustfsdockercompose--profileobservability up-d

只想要对象存储、不要监控栈，就只起 rustfs 服务：

dockercompose-fdocker-compose.yml up-drustfs

注意仓库自带的 compose 里没有权限初始化这一步：官方文档给的 compose 示例里用了一个 init 容器rustfs_perms（基于 alpine），在 RustFS 启动前把挂载卷的所有权改成10001，靠depends_on卡顺序，避免权限问题。自己编排时可以照官方示例把这个服务加进去。单服务场景用一条docker run最轻量；只有当要把对象存储和监控等多个服务一起编排时，compose 才显出价值。

数据怎么备份和迁移

命名卷的数据在 Docker 的 volumes 目录里，整卷打包就能备份：

dockerrun--rm-vrustfs-data:/from-v"$PWD":/to alpine\tarczf /to/rustfs-data.tgz-C/from.

换机器时把这份 tar 在目标主机解回同名卷，再用同样的docker run起服务，数据就跟着过来了。

这是卷级别的冷备，和对象存储自己的版本化、复制是两套不同层级的保障，别互相替代。冷备频率按数据变更节奏定，变化快的桶每天一备，变化慢的每周也够，关键是恢复时这份 tar 能和当时的对象清单对上。

另外分清删容器和删卷：docker rm rustfs只删容器、不动命名卷rustfs-data，数据还在；要彻底清数据才用docker volume rm rustfs-data。

几个边界先说清

单节点 Docker 不是生产形态。官方明确建议生产前走预安装检查清单，上多节点架构、开 TLS、配日志轮转和定期备份。TLS 的接法是挂证书目录再指过去：

-v/path/to/certs:/certs\-eRUSTFS_TLS_PATH=/certs\

这里有个官方的硬约定：证书文件必须命名为rustfs_cert.pem和rustfs_key.pem放进该目录，按别的名字放进去 TLS 起不来。配好后 9000（S3 API）和 9001（控制台）两个监听器都会走 HTTPS。另外容器以rustfs用户跑，这两个文件的属主也要改成10001:10001，不然 RustFS 读不了证书，TLS 同样配失败。

升镜像版本就是重新拉再重建容器，命名卷rustfs-data不动，数据不受影响。镜像 tag 的取舍就一条：rustfs/rustfs:latest会跟到最新，POC 用着方便；要稳就钉一个具体标签，避免某次docker pull把不想要的变更悄悄带进来，升级前先在测试环境跑一遍再上。截至发稿（2026 年 10 月），稳定线最新是 1.0.4（2026-10-25），钉版本可以用rustfs/rustfs:1.0.4。

端口方面，-p 9000:9000默认就绑在0.0.0.0上，局域网联调直接能访问；但别把 9000 裸露到公网，公网前面至少加一层 TLS 和强密钥。

下一步

服务起好、/health通了、aws-cli 也能建桶传文件，本地验证就算闭环。单节点部署的定位就是开发、POC、边缘小站这三件事，它把跑通 S3 接口的门槛压到最低，但不提供盘级容错，一块盘坏了数据就丢。给边缘小站用时，把 data 挂到本地 SSD、把 9000/9001 映射出去，整机重启靠--restart unless-stopped自动拉起，基本免运维，够小站用很久。真要上生产、要冗余，顺着本篇末尾的链接去多节点或 K8s，形态虽然变，S3 接口和密钥这套东西不变，代码几乎不用改。完整安装说明在 RustFS Docker 文档，镜像和 compose 文件在 rustfs/rustfs 。