88 lines
4.4 KiB
Markdown
88 lines
4.4 KiB
Markdown
---
|
||
title: SeaweedFS S3 使用指南
|
||
lifecycle: active
|
||
evidence: documented
|
||
last_reviewed: 2026-09-16
|
||
last_verified: null
|
||
---
|
||
|
||
# SeaweedFS 对象存储
|
||
|
||
SeaweedFS 为应用提供 S3 兼容对象存储，zot Registry 是它的消费者之一。
|
||
普通应用使用自己的 bucket 和 S3 身份；容器镜像通过 [zot](zot.md) 发布与拉取。
|
||
|
||
本页依据 homelab-infra 工作区 `apps/seaweedfs/README.md` 和 `apps/zot/README.md` 整理，
|
||
客户端语法参考 AWS CLI 官方文档。本轮未查询现场或读写对象。
|
||
|
||
## 连接入口与身份
|
||
|
||
| 场景 | endpoint |
|
||
|---|---|
|
||
| LAN 客户端的 HTTPS S3 入口 | `https://s3.ad.ddupan.top` |
|
||
| Kubernetes 集群内 Service | `http://seaweedfs-s3.seaweedfs.svc.cluster.local:8333` |
|
||
|
||
首次接入先明确自己的 bucket、需要的 Read/Write/List 等权限及凭据获取方式。
|
||
当前所读配置使用静态 S3 AK/SK，由 OpenBao 管理；SeaweedFS OIDC/STS 尚未接入。
|
||
zot 前端的 SPIFFE 登录不代表通用 S3 客户端已经能用 SPIFFE 换取 S3 凭据。
|
||
|
||
应用使用专属身份，不复用 zot 或 Terraform 的存储凭据。
|
||
Kubernetes Secret 是 ESO 生成的消费副本，身份或凭据变更应修改受管来源，不能手工改副本。
|
||
|
||
## 用 AWS CLI 查看自己的对象
|
||
|
||
前提：已安装 AWS CLI，并由既有授权流程将本应用的凭据注入当前进程环境
|
||
（`AWS_ACCESS_KEY_ID`、`AWS_SECRET_ACCESS_KEY`），或配置受保护的专用 CLI profile。
|
||
不要把实际 AK/SK 复制到命令示例、仓库或日志中。
|
||
|
||
将下例 bucket 替换为自己的已授权 bucket，先只读列出少量对象：
|
||
|
||
```bash
|
||
aws --endpoint-url https://s3.ad.ddupan.top s3api list-objects-v2 \
|
||
--bucket YOUR_APP_BUCKET --max-items 10 --no-cli-pager
|
||
```
|
||
|
||
预期返回对象信息或空 bucket 的结果。只具有指定 bucket 权限的身份，不必拥有列举所有 bucket 的权限；
|
||
因此不以全局 `aws s3 ls` 是否成功作为接入的唯一标准。
|
||
`--max-items` 控制返回条数，具体行为见
|
||
[AWS CLI list-objects-v2](https://docs.aws.amazon.com/cli/latest/reference/s3api/list-objects-v2.html)。
|
||
|
||
## 上传和下载一个测试文件
|
||
|
||
仅在自己的测试 bucket/prefix 以及具备写权限时操作。替换占位符，并使用尚未占用的 key：
|
||
|
||
```bash
|
||
aws --endpoint-url https://s3.ad.ddupan.top s3 cp ./hello.txt \
|
||
s3://YOUR_APP_BUCKET/YOUR_UNUSED_TEST_KEY
|
||
aws --endpoint-url https://s3.ad.ddupan.top s3 cp \
|
||
s3://YOUR_APP_BUCKET/YOUR_UNUSED_TEST_KEY ./hello.downloaded.txt
|
||
cmp ./hello.txt ./hello.downloaded.txt
|
||
```
|
||
|
||
本地先准备 `hello.txt`。预期上传与下载成功，`cmp` 无输出且退出码为 0。
|
||
这会在目标 bucket 留下测试对象，是否清理由该 bucket 的所有者决定。
|
||
语法参考 [AWS CLI cp](https://docs.aws.amazon.com/cli/latest/reference/s3/cp.html)。
|
||
上游 S3 客户端文档用于解释命令，不代表 SeaweedFS 实现了全部 AWS S3 功能。
|
||
|
||
## zot 数据与维护边界
|
||
|
||
zot 专用数据位于 `zot` bucket 的 `registry/` 前缀，由 Registry 管理 OCI layout。
|
||
不要把普通文件直接写入该前缀，也不要用 S3 客户端手工删除镜像内部对象。
|
||
|
||
zot 的 S3 身份只允许相应 bucket 的 Read/Write/List/Tagging，不能访问 `tfstate`。
|
||
其凭据唯一来源为 OpenBao `kv/k8s/zot-s3`，由 ESO 同步给 zot 和 SeaweedFS；
|
||
基础 S3 身份配置在 `kv/k8s/seaweedfs-s3`，两份配置的合成及轮换见源码 README。
|
||
轮换不仅是改一个值，还需协调服务端重新加载和消费者更新，避免两端配置不一致。
|
||
|
||
## 遇到问题先看哪里
|
||
|
||
- 域名或连接失败：确认当前使用的是 LAN endpoint 还是仅集群内可达的 Service。
|
||
- 访问被拒绝：核对使用的应用身份、bucket/key 与所需动作权限，不直接扩大为管理员权限。
|
||
- 签名或凭据错误：核对凭据来源、同步情况和客户端配置；不要打印 AK/SK 排障。
|
||
- Registry 不可用：区分 zot 的 SPIFFE 客户端认证与它到 S3 的后端认证。
|
||
|
||
部署与配置来源：homelab-infra `apps/seaweedfs/README.md`、`apps/zot/README.md`。
|
||
单一存储系统内的数据副本不等于独立备份；zot 源文档尚未记录已建立独立异机/离线备份。
|
||
其他应用的数据保留与恢复策略应由各自用途明确，不能从“已接入 S3”推断已经完成备份。
|
||
|
||
来源文件的固定版本与工作区差异见[来源追溯](../sources.md#seaweedfs)。
|