安装吞吞

环境要求

服务端是单个 Rust 二进制，元数据落在 SQLite。生产部署建议 Linux x86_64 或 arm64，至少 2 GB 内存，数据盘按业务容量准备。

• Docker 路径：Docker Engine 与 Compose v2。
• 源码路径：Rust 1.89 或更新版本，以及 protoc。
• 客户端：aws-cli、rclone 或任意支持自定义 endpoint 的 S3 SDK。

Docker Compose

仓库自带单机 compose，包含 oss-server 与控制台。数据与暂存放在具名卷，首次启动会生成管理员口令。

git clone https://github.com/erikwang2013/oss.git
cd oss
docker compose up -d --build

# 查看自动生成的管理员账号与口令
cat docker/secrets/generated.env

默认端口：S3 与控制面在 9000，控制台在 8080。配置文件只读挂载自 docker/oss.toml，改完重启容器即可。

源码构建

源码模式需要 protoc，因为节点间 gRPC 协议在构建期生成。构建完成后直接运行 oss-server serve。

git clone https://github.com/erikwang2013/oss.git
cd oss
cargo build --release -p oss-server

OSS_ADMIN_USER=admin \
OSS_ADMIN_PASSWORD='change-me-please' \
./target/release/oss-server serve

开发控制台时另开一个终端：

cd web
npm ci
npm run dev

首次启动

首次启动会自动创建数据目录、暂存目录与桶目录，并用环境变量或密钥文件初始化管理员。建议把口令放进密钥文件，不要写进 shell 历史。

服务端加密需在启动前配置密钥库：OSS_MASTER_KEY_FILE 提供 SSE-S3 主密钥，OSS_KMS_DIR 提供 SSE-KMS/命名 CMK 环（v1.16 起支持显式 CMK、轮换、安全删除与逐版本 rewrap）。未配置时对应 SSE 写入 fail-closed 返回 500，不会降级明文。

• OSS_ADMIN_USER：管理员用户名。
• OSS_ADMIN_PASSWORD：管理员口令。
• OSS_SECRETS_FILE：可选，密钥文件路径，适合 Docker 自动生成与复用。

启动后打开控制台，使用管理员账号登录。控制台默认在开发模式的 5173，Compose 模式在 8080。

创建访问密钥

找到控制台右上角的访问密钥入口，创建一对 AK/SK。也可以用管理员 token 调控制台 API：

# 登录拿 JWT
curl -s -X POST http://127.0.0.1:9000/api/v1/login \
  -H 'content-type: application/json' \
  -d '{"username":"admin","password":"change-me-please"}'

# 用返回的 token 创建访问密钥
curl -s -X POST http://127.0.0.1:9000/api/v1/access-keys \
  -H "authorization: Bearer <token>" \
  -H 'content-type: application/json' -d '{}'

连接 S3

把 endpoint 指向 oss，region 任意填写，认证用刚创建的 AK/SK。aws-cli 会自动处理 multipart 与签名。

export AWS_ACCESS_KEY_ID=...
export AWS_SECRET_ACCESS_KEY=...
export AWS_DEFAULT_REGION=us-east-1
E=http://127.0.0.1:9000

aws --endpoint-url $E s3 mb s3://demo
aws --endpoint-url $E s3 cp ./file.bin s3://demo/file.bin
aws --endpoint-url $E s3 ls s3://demo/

TLS 传输

默认仍是明文；配置 [tls.server] 后，S3/控制台监听器、witness、Raft RPC、节点间 gRPC mesh、site/repl/tier 出站与 Kafka 一起启用 TLS——没有半 TLS 模式。v1.15 起私钥强制 0600、CA 支持双信任轮换、主监听器与出站客户端热加载；v1.16 起 mesh gRPC 客户端与 Kafka TLS 客户端也按成功 reload 重建。mesh 入站监听器与 Kafka SASL 仍是启动期配置，变更需重启。

[tls.server]
cert = "/etc/oss/server.crt"
key  = "/etc/oss/server.key"
# 可选：要求并校验客户端证书（mTLS）
client_ca = "/etc/oss/ca.crt"

[tls.client]
# 出站额外信任根（自签/私有 CA 部署时配置）
ca_cert = "/etc/oss/ca.crt"

对端地址仍可写 http://，连接时按 [tls.server] 升级为 https；未启用 TLS 时写 https:// 会在启动期拒绝。Kafka 的 SASL/SSL 配置与 mTLS 细节见 README 的 TLS 章节（随发布同步）。

集群与强一致

单机跑起来后，可以继续加盘、加节点或配置多站点。控制面提供三种模式：

完整的节点拓扑、witness、sync 写语义、cutover 与 force recovery 步骤在 README 的强一致章节（随发布同步）。

控制面支持滚动升级窗口：先保持 [raft].feature_level = 1（默认），逐个替换节点；全部 voter/learner 都升级后再按需改为 2 或 3（范围 1..=3）并重启。激活后不可回滚到旧版。数据面自 v1.19.0 起提供 DP-1 混版门控：节点宣告 wire/epoch/hash，不兼容对端 fail-closed，ListObjects V1 与 ListMultipartUploads 会带降级头。v1.20.0 起补充 mesh gRPC 入站 TLS 物料热轮换（新连接取新配置，旧连接保持旧物料）与真实二进制滚动 e2e（同版本 3 节点、v1.13.1 旧二进制滚动）。v1.20.1 新增软配额命令（level-3），混版窗口内使用 `PUT /accounts/{id}/soft-quota` 前需先升级全部节点。生产升级仍建议按 README 的「升级顺序」执行并保留维护窗口；升级步骤与自动拒绝条件以 README 为准（随发布同步）。

下载与版本

当前 Release 提供源码归档，没有预编译二进制。推荐 Docker Compose 或按本文源码构建。当前最新发布 v1.24.0；v1.20.0 的源码归档因 Cargo.lock 错误（either 被标为 1.20.0）无法构建，请使用 v1.24.0（或 v1.23.0）。

打开 v1.24.0 Release 下载源码包 版本日志