本地联调代码要一个对象存储、给客户做 POC 要演示、边缘小站想垫一层存储底座都不值得专门为它采购和运维一套分布式集群。一条 docker run 就能在笔记本或一台小服务器上把 RustFS 跑起来S3 接口直接可用代码里把 endpoint 指过来就能测。这篇把从拉镜像到用 aws-cli 建桶的完整路径走一遍并把几个最容易卡住的点讲清楚。端口和镜像先到位Docker Engine 要 20.10 以上主机上 9000S3 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_KEYyour-access-key\-eRUSTFS_SECRET_KEYyour-secret-key\-eRUSTFS_ADDRESS:9000\-eRUSTFS_CONSOLE_ADDRESS:9001\-eRUSTFS_CONSOLE_ENABLEtrue\-eRUSTFS_OBS_LOGGER_LEVELerror\-eRUSTFS_OBS_LOG_DIRECTORY/var/log/rustfs/\rustfs/rustfs:latest\/dataRUSTFS_CONSOLE_ENABLEtrue才会开 9001 控制台RUSTFS_ADDRESS和RUSTFS_CONSOLE_ADDRESS分别管 S3 和控制台的监听地址。同一个配置也能用命令行参数传--access-key、--address这类而且命令行参数优先级高于环境变量。一个权限坑容器里的用户不是 rootRustFS 容器以非 root 用户rustfsUID10001运行。如果你用主机目录挂载-v /path/on/host:/data而不是命名卷目录所有者必须改成10001否则会权限拒绝chown-R10001:10001 /path/to/host_directory用命名卷就省掉这步所以本地起服务优先命名卷。起来先探活再开控制台别急着登控制台先用健康检查端点确认服务在dockerps--filternamerustfscurl--failhttp://localhost:9000/healthcurl --fail返回 0 说明 S3 接口已经起来了控制台在http://localhost:9001用上面设的密钥登录。顺手验一下 S3 通路探活通过后用 aws-cli 建个桶、传个文件确认整条链路通exportAWS_ACCESS_KEY_IDyour-access-keyexportAWS_SECRET_ACCESS_KEYyour-secret-keyexportAWS_DEFAULT_REGIONus-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 起不来。配好后 9000S3 API和 9001控制台两个监听器都会走 HTTPS。另外容器以rustfs用户跑这两个文件的属主也要改成10001:10001不然 RustFS 读不了证书TLS 同样配失败。升镜像版本就是重新拉再重建容器命名卷rustfs-data不动数据不受影响。镜像 tag 的取舍就一条rustfs/rustfs:latest会跟到最新POC 用着方便要稳就钉一个具体标签避免某次docker pull把不想要的变更悄悄带进来升级前先在测试环境跑一遍再上。截至发稿2026 年 10 月稳定线最新是 1.0.42026-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 。
