VaultS3 部署教程：轻量级 S3 兼容对象存储

本教程将指导你部署 VaultS3——一个轻量级、S3 兼容的对象存储服务器。它有着极小的资源占用（空闲时仅 17MB 内存），并内置了 Web 仪表盘、加密、版本控制、IAM 等特性。

📋 准备工作

1. 硬件与系统要求

操作系统：Linux、macOS 或 Windows。项目提供静态二进制文件、DEB/RPM/APK 包以及 Docker 镜像。
资源：最低 256MB 内存（推荐 1GB 以上），存储空间取决于你的数据量。
网络：如果需要从外部访问，确保 9000 端口（默认）在防火墙中开放。

2. 选择部署方式

VaultS3 提供多种安装路径，选择最适合你的环境：

Docker（推荐）：最快速、隔离性最好。
系统包（DEB/RPM/APK）：适合生产服务器，便于系统管理。
静态二进制：适合自定义环境或嵌入式场景。
从源码构建：适合开发者或需要定制编译选项的用户。

🚀 快速启动

方式一：使用 Docker（通用推荐）

docker run -d --name vaults3 -p 9000:9000 \
  -e VAULTS3_ACCESS_KEY=myadmin \
  -e VAULTS3_SECRET_KEY=mysupersecret \
  -v vaults3-data:/data -v vaults3-meta:/metadata \
  eniz1806/vaults3

参数说明：

-p 9000:9000：将容器的 9000 端口映射到宿主机。
-e VAULTS3_ACCESS_KEY 和 VAULTS3_SECRET_KEY：设置管理员凭证（生产环境务必修改）。
-v：挂载数据 (/data) 和元数据 (/metadata) 目录到持久卷。

启动后，S3 API 和 Web 仪表盘都监听在 9000 端口：

# 使用 AWS CLI 测试（需提前安装 awscli）
aws --endpoint-url http://localhost:9000 s3 mb s3://my-bucket
aws --endpoint-url http://localhost:9000 s3 cp ./file.txt s3://my-bucket/

# 在浏览器中打开仪表盘
open http://localhost:9000/dashboard/

方式二：使用系统包（DEB/RPM/APK）

从 Releases 页面下载对应系统的包文件（如 .deb）。
安装包并启动服务：

# Debian/Ubuntu
sudo apt install ./vaults3_4.4.68_amd64.deb
sudo systemctl enable --now vaults3

# RHEL/CentOS/Fedora
sudo rpm -ivh vaults3_4.4.68_amd64.rpm
sudo systemctl enable --now vaults3

默认配置下，服务监听 9000 端口。首次启动会在日志中打印自动生成的 admin 凭证，请及时记录。

方式三：使用静态二进制

下载对应平台的二进制文件（如 vaults3-linux-amd64），赋予执行权限并运行：

chmod +x vaults3-linux-amd64
./vaults3-linux-amd64 serve \
  --access-key=myadmin \
  --secret-key=mysupersecret \
  --data-dir=/path/to/data \
  --meta-dir=/path/to/meta

🔧 基本配置与管理

1. 环境变量与默认值

VaultS3 主要通过环境变量配置，无需配置文件。常用变量如下：

环境变量	说明	默认值
`VAULTS3_ACCESS_KEY`	管理员 Access Key	首次启动自动生成
`VAULTS3_SECRET_KEY`	管理员 Secret Key	首次启动自动生成
`VAULTS3_DATA_DIR`	数据文件存储路径	`./data`
`VAULTS3_META_DIR`	元数据（索引）存储路径	`./metadata`
`VAULTS3_LISTEN_ADDR`	监听地址和端口	`:9000`
`VAULTS3_REGION`	S3 区域名称	`us-east-1`

2. 使用 Web 仪表盘

仪表盘是 VaultS3 的核心管理界面，提供了：

文件浏览器：上传、下载、预览、删除对象。
用户与权限管理 (IAM)：创建用户、组和自定义策略。
存储桶管理：创建/删除存储桶，配置版本控制、加密、生命周期规则。
审计与监控：查看操作日志和系统统计信息。
备份与恢复：配置和执行数据备份任务。

3. 配置 IAM 和访问控制

VaultS3 支持完整的 IAM 模型：

创建用户：为每个应用或人员分配独立的 Access Key/Secret Key。
定义策略：使用 JSON 格式策略精细控制对存储桶和对象的操作权限（例如 s3:GetObject、s3:PutObject）。
附加策略：将策略附加给用户或用户组。
IP 白名单：限制特定 IP 地址段的访问。
OIDC/JWT SSO：支持通过 OIDC 提供商进行单点登录。

⚙️ 高级功能与运维

1. 启用数据加密

VaultS3 支持多种加密方式，保障数据静态安全：

SSE-S3（默认）：使用平台管理的 AES-256-GCM 密钥自动加密每个对象。
SSE-KMS：使用用户通过 KMS 接口管理的密钥。
SSE-C：由客户端提供加密密钥。
存储桶默认加密：为存储桶设置默认加密配置，所有上传的对象自动加密。

2. 设置版本控制与对象锁定

版本控制是数据保护的关键：

为存储桶启用版本控制，保留对象的每个历史版本。
支持在仪表盘或通过 API 查看对象历史版本、比较差异（diff）和回滚。
对象锁定 (Object Lock)：可设置 WORM（一次写入多次读取）策略，满足合规要求。

3. 配置多节点集群（Beta 功能）

VaultS4 支持基于 Raft 共识算法的元数据复制和一致性哈希数据分布。

多节点复制：元数据跨节点复制，提供高可用性。
自动故障转移：节点故障时，请求自动路由到健康节点。
部署建议：此功能仍处于 Beta 阶段，建议在非生产环境或对数据丢失风险容忍的场景下测试。生产环境单节点仍是稳定首选。

4. 数据备份与迁移

VaultS3 提供了灵活的备份和迁移路径：

内置备份：支持全量和增量备份到本地或远程存储。
从其他存储迁移：内置导入工具，可从 MinIO、SeaweedFS、AWS S3、R2 等迁移数据，并保留元数据、标签和策略。
标准数据格式：对象以普通文件形式存储在磁盘上，元数据使用 BoltDB 文件，你可以随时使用 rclone 或 aws s3 sync 将数据迁移到任何其他 S3 兼容服务，不会被锁定。

❓ 常见问题排查

无法访问 Dashboard 或 API：检查防火墙是否放行 9000 端口。确认容器或进程是否正常运行（docker ps 或 systemctl status vaults3）。
忘记管理员密码：如果使用 Docker，可以通过进入容器重新设置环境变量后重启。如果使用系统包，可以停止服务，使用 --access-key 和 --secret-key 参数手动启动服务来重置，然后更新配置并重启服务。
磁盘空间不足：检查 /data 和 /metadata 挂载点的剩余空间。使用 vaults3-cli storage reclaim 命令清理可能因版本控制等留下的孤儿数据。配置生命周期策略以自动删除过期对象。
上传大文件失败：检查客户端的超时设置。VaultS3 支持分片上传 (Multipart Upload)，确保客户端正确使用。对于超大文件，考虑调整网络或代理配置。