补充 zot 镜像发布与 SeaweedFS S3 客户端使用指南

README.md

@@ -7,6 +7,8 @@
 - [服务总览](services/index.md)：有什么、有什么用、在哪里、状态依据是什么。
 - [Gitea / Actions 入门](services/gitea.md)：登录、创建仓库、运行第一个 CI 与选择 runner。
 - [Grafana 使用指南](services/grafana.md)：内存看板、指标查询和日志搜索。
+- [zot 使用指南](services/zot.md)：匿名拉取、SPIFFE 发布身份与仓库授权。
+- [SeaweedFS 使用指南](services/seaweedfs.md)：S3 客户端接入、对象读写与存储边界。
 - [SPIFFE/SPIRE](services/spire.md)：按 #34 整理的阶段状态、使用与 runbook 入口。
 - [PostgreSQL Tenant Operator](services/postgresql-tenant-operator.md)：计划在共享 PostgreSQL 上提供的 DBaaS 中间层。
 - [Gitea Dynamic Runner](services/gitea-dynamic-runner.md)：原 microVM runner，现支持 Pod/VM 两种一次性执行环境。

documentation-backlog.md

@@ -7,15 +7,16 @@
 
 - [Gitea / Actions](services/gitea.md)：登录、建仓库、最小 CI、runner 选择和常见问题。
 - [Grafana](services/grafana.md)：内存看板、指标查询、日志搜索和数据源用途。
+- [zot](services/zot.md)：拉取、发布授权、workflow 身份职责与后端数据恢复边界。
+- [SeaweedFS](services/seaweedfs.md)：S3 入口、专用凭据、列举与上传下载示例。
 
 以上依据源码文档和上游说明整理，示例未在本轮执行，不作为现场验收记录。
 
 ## 后续使用说明
 
-1. zot / SeaweedFS：拉取、发布授权、S3 客户端接入，以及数据备份边界。
+1. OpenBao：日常登录、按权限取用秘密、申请权限；与灾难恢复分开说明。
-2. OpenBao：日常登录、按权限取用秘密、申请权限；与灾难恢复分开说明。
+2. NetBox：查看拓扑与 IPAM 的路径，强调目前是评估镜像，改动入口在 Git。
-3. NetBox：查看拓扑与 IPAM 的路径，强调目前是评估镜像，改动入口在 Git。
+3. codex-proxy、LiteLLM gateway、shared PostgreSQL、Tailscale、ps3netsrv、vlmcsd、k3s：整理用途和已知状态；这些目录缺少根 README。
-4. codex-proxy、LiteLLM gateway、shared PostgreSQL、Tailscale、ps3netsrv、vlmcsd、k3s：整理用途和已知状态；这些目录缺少根 README。
 
 ## 文档同步与来源链接
 

services/index.md

@@ -25,12 +25,12 @@ SPIFFE/SPIRE 已按维护者授权补读 #34；LAN DNS 与 Authelia 已按维护
 | netbox | 网络资产与地址管理评估 | `netbox.ad.ddupan.top` | 记录已部署；评估用途 | `apps/netbox/README.md` | 补面向浏览者的使用路径 |
 | openviking | 上下文检索服务 | `记录端口 1933 / 8020` | 配置与部署指南；未附上线记录 | `apps/openviking/README.md` | 缺导入、查询的完整例子 |
 | ps3netsrv | PS3 网络内容服务 | `未记录` | Docker 运维文档记录运行 | `apps/ps3netsrv/docker-compose.yml` | 缺客户端使用与挂载说明 |
-| seaweedfs | S3 对象存储 | `s3.ad.ddupan.top` | zot 文档记录已使用 | `apps/seaweedfs/README.md` | 补客户端接入、备份与恢复 |
+| [seaweedfs](seaweedfs.md) | S3 对象存储 | `s3.ad.ddupan.top` | zot 文档记录已使用 | `apps/seaweedfs/README.md` | 已有客户端读写指南与备份边界说明 |
 | shared-postgresql | 共享 PostgreSQL / CNPG | `shared-db namespace` | 历史迁移记录已完成 | `apps/shared-postgresql/migration.md` | 缺服务首页、租户接入说明 |
 | smtp-relay | 应用经 Microsoft 365 发信 | `smtp-relay.smtp-relay.svc.cluster.local:25` | 有配置与测试指南；未附上线记录 | `apps/smtp-relay/README.md` | 补发信链路与消费者说明 |
 | tailscale | 远程网络与子网路由 | `Tailscale 网络` | 有配置；本轮未读敏感安装脚本 | `apps/tailscale/subnet-routes.sh` | 缺 README、路由与客户端说明 |
 | vlmcsd | KMS 兼容服务，使用范围未记录 | `未记录` | 仅发现配置 | `apps/vlmcsd/compose.yaml` | 缺 README 与状态说明 |
-| zot | OCI 镜像与制品仓库 | `zot.ad.ddupan.top / zot-push.ad.ddupan.top` | 文档记录 9 月 16 日验收 | `apps/zot/README.md` | 已有拉取示例；长期 CI 发布仍待接入 |
+| [zot](zot.md) | OCI 镜像与制品仓库 | `zot.ad.ddupan.top / zot-push.ad.ddupan.top` | 文档记录 9 月 16 日验收 | `apps/zot/README.md` | 已有拉取与发布模板；实际 publisher 授权以项目配置为准 |
 
 ## 平台
 

services/seaweedfs.md

@@ -0,0 +1,85 @@
+---
+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”推断已经完成备份。

services/zot.md

@@ -0,0 +1,83 @@
+---
+title: zot 镜像与制品仓库使用指南
+lifecycle: active
+evidence: documented
+last_reviewed: 2026-09-16
+last_verified: null
+---
+
+# zot 镜像与制品仓库
+
+zot 保存容器镜像与 OCI 制品，底层数据存放于 [SeaweedFS](seaweedfs.md)。
+客户端使用 Registry API，不需要直接访问 S3 bucket。
+
+本页依据 homelab-infra 工作区 `apps/zot/README.md` 的 2026-09-16 记录整理。
+源文档记录双入口已上线并验收、由 Flux 管理；本轮未查询现场或执行下面的示例。
+
+## 两个入口
+
+| 入口 | 用途 | 认证 |
+|---|---|---|
+| `zot.ad.ddupan.top` | 内网拉取镜像或制品 | 匿名只读 |
+| `zot-push.ad.ddupan.top` | 鉴权访问及已授权发布 | SPIRE JWT-SVID，audience 为 `zot`；写权限按 SPIFFE ID 和 repository 分配 |
+
+需要到 LAN 的路由与内网 DNS。两个入口对应相同制品数据，例如推送
+`zot-push.ad.ddupan.top/team/image:tag` 后，可从
+`zot.ad.ddupan.top/team/image:tag` 拉取，无需再复制一份镜像。
+
+## 第一次拉取
+
+安装 crane 后，在可写的工作目录执行源码文档提供的只读示例：
+
+```bash
+crane pull zot.ad.ddupan.top/verification/anonymous-spire:smoke image.tar --format oci
+```
+
+预期得到本地 `image.tar` OCI archive。该验证制品仅含测试内容，没有可执行入口，
+用于验证拉取链路，不要把它当作能运行的业务镜像。
+日常部署使用发布方提供的真实镜像路径和 tag/digest；匿名拉取不需要登录推送入口。
+
+## 发布自己的镜像
+
+发布前需要同时具备：
+
+1. 执行环境能通过 Workload API 获取自己的 SPIFFE 身份。
+2. workflow 获取 `aud=zot` 的短期 JWT-SVID。
+3. zot 已为该 SPIFFE ID 授予目标 repository 所需的 `read/create/update` 权限。
+
+根据所读源文档，当前持久配置没有常驻 publisher 或删除授权，曾用于验收的临时写权限
+已经撤回。因此以下是获授权后的使用模板，不能仅登录成功就假定可以推送。
+
+假定 workflow 已将 JWT-SVID 放入当前进程的 `ZOT_JWT`，准备好自己的 `image.tar`，
+并将示例目标替换为已授权的 repository/tag，在 Bash 中执行：
+
+```bash
+(
+  set +x
+  set -euo pipefail
+  : "${ZOT_JWT:?workflow 必须先取得 aud=zot 的 JWT-SVID}"
+  export DOCKER_CONFIG="$(mktemp -d)"
+  trap 'rm -rf -- "$DOCKER_CONFIG"' EXIT
+  printf '%s' "$ZOT_JWT" | crane auth login zot-push.ad.ddupan.top \
+    --username zot --password-stdin
+  crane push image.tar zot-push.ad.ddupan.top/team/image:tag
+)
+unset ZOT_JWT
+```
+
+临时配置目录退出时删除。登录、token 获取和刷新由 workflow 负责，
+[Dynamic Runner](gitea-dynamic-runner.md) 提供环境和身份能力，不代办这些业务流程。
+这里的 token 交换不会延长原 SVID 的有效期。
+
+## 常见问题与数据边界
+
+- 拉取域名不能推送：它只提供匿名读取，发布应使用推送域名。
+- 401：检查 issuer、audience、有效期，以及 workflow 是否实际取得了 JWT-SVID。
+- 登录成功但推送被拒绝：检查具体 SPIFFE ID 的 repository policy；身份与写权限分开配置。
+- S3 后端报错：检查 zot 到 SeaweedFS 的连接与受管凭据，不能用客户端的 JWT 代替后端 AK/SK。
+
+zot 的持久数据在 SeaweedFS `zot` bucket 的 `registry/` 前缀；zot Pod 的临时目录不是备份。
+恢复需要完整 bucket 数据、OpenBao 专用凭据与部署配置。源文档记录独立异机/离线备份尚未建立，
+不能将同一 SeaweedFS 的副本视为独立灾备；重装 zot 不得删除该 bucket。
+
+部署、授权变更、凭据轮换及验收细节以 homelab-infra `apps/zot/README.md` 为准。