vault backup: 2026-11-07 16:33:44

2026-11-07 16:33:55 +08:00
commit 7015312702
1208 changed files with 132432 additions and 0 deletions
@@ -0,0 +1,141 @@
+以下是 Mountpoint for Amazon S3 的安装和与 S3 兼容服务（如 RustFS）配合使用的教程。
+
+### 1. 安装 Mountpoint
+
+Mountpoint 提供预编译的安装包，支持多种 Linux 发行版。
+
+*   **Ubuntu / Debian (基于 DEB)**
+    ```bash
+    # 下载适用于 x86_64 架构的 .deb 包
+    wget https://s3.amazonaws.com/mountpoint-s3-release/latest/x86_64/mount-s3.deb
+    # 安装
+    sudo apt-get install -y ./mount-s3.deb
+    ```
+    对于 ARM64 架构，将 URL 中的 `x86_64` 替换为 `arm64`。
+
+*   **Amazon Linux / RHEL / CentOS (基于 RPM)**
+    ```bash
+    # 下载适用于 x86_64 架构的 .rpm 包
+    wget https://s3.amazonaws.com/mountpoint-s3-release/latest/x86_64/mount-s3.rpm
+    # 安装
+    sudo yum install -y ./mount-s3.rpm
+    ```
+    对于 ARM64 架构，将 URL 中的 `x86_64` 替换为 `arm64`。
+
+*   **验证安装**
+    安装完成后，运行以下命令验证是否成功：
+    ```bash
+    mount-s3 --version
+    ```
+    如果安装成功，会输出版本信息，例如 `mount-s3 1.21.0`。
+
+### 2. 配置访问凭证
+
+Mountpoint 使用与 AWS CLI 相同的方式发现凭证。对于自建的 S3 服务，你需要通过环境变量提供访问密钥：
+
+```bash
+export AWS_ACCESS_KEY_ID=myaccesskey
+export AWS_SECRET_ACCESS_KEY=mysecretkey
+export AWS_ENDPOINT_URL=http://你的RustFS服务IP:9000
+```
+Mountpoint 会自动读取这些环境变量。
+
+### 3. 挂载存储桶
+
+#### 3.1 基础挂载（适用于 AWS S3）
+
+如果你的目标是标准的 AWS S3，挂载命令非常简单：
+```bash
+mkdir ~/mnt
+mount-s3 my-bucket ~/mnt
+```
+此时，`~/mnt` 目录就成为了你 S3 存储桶的挂载点。
+
+#### 3.2 挂载到 S3 兼容服务（如 RustFS）
+
+对于非 AWS 的 S3 兼容服务，**必须指定服务端点（Endpoint）**。
+
+Mountpoint 提供两种方式：
+
+*   **方式一：使用命令行参数 `--endpoint-url`**
+    ```bash
+    mount-s3 my-bucket ~/mnt --endpoint-url http://你的RustFS服务IP:9000
+    ```
+
+*   **方式二：使用环境变量 `AWS_ENDPOINT_URL`（推荐）**
+    这种方式更便于在容器或脚本中统一管理配置。
+    ```bash
+    export AWS_ENDPOINT_URL=http://你的RustFS服务IP:9000
+    mount-s3 my-bucket ~/mnt
+    ```
+
+> **注意**：Mountpoint 默认使用 `virtual-hosted-style` 的请求方式。如果你的 S3 服务（如 RustFS）不支持这种样式，可能会遇到 DNS 解析问题。此时，你可能需要在挂载时添加 `--endpoint-url` 参数，并确保其指向正确的服务地址。
+
+### 4. 启用 10GB 本地缓存
+
+Mountpoint 支持可选的本地缓存，用于加速对热点数据的重复读取。它的工作模式是按需加载，只有被访问过的数据才会被缓存。
+
+你可以通过以下参数启用并限制缓存大小：
+
+*   `--cache <目录>`：指定缓存数据存放的本地目录。
+*   `--max-cache-size <大小>`：**以 MiB 为单位**设置缓存的最大容量。缓存淘汰策略为 **LRU（最近最少使用）**。
+
+**挂载命令示例（10GB = 10240 MiB）：**
+
+```bash
+# 创建缓存目录
+mkdir ~/cache
+
+# 挂载并启用缓存，限制最大10GB
+mount-s3 my-bucket ~/mnt \
+  --endpoint-url http://你的RustFS服务IP:9000 \
+  --cache ~/cache \
+  --max-cache-size 10240
+```
+
+当缓存占满后，Mountpoint 会自动淘汰最久未使用的数据以腾出空间。
+
+### 5. 其他常用选项
+
+*   **元数据缓存 (`--metadata-ttl`)**：缓存文件的元数据（如大小、存在性），可减少对 S3 的请求。但需要注意，这可能会使外部对文件的修改无法及时看到。
+*   **后台运行**：`mount-s3` 命令默认在后台运行，不会阻塞终端。
+*   **卸载挂载点**：
+    ```bash
+    umount ~/mnt
+    ```
+    如果权限不足，可能需要使用 `sudo`。
+
+### 6. 核心注意事项
+
+1.  **缓存仅加速读取**：本地缓存**仅对读取操作生效**。所有的写入（创建、修改、删除）操作都会**直接提交到后端的 S3 服务**，不会先写入缓存。
+2.  **非完整 POSIX 兼容**：Mountpoint 并非一个完整的 POSIX 文件系统，它针对高吞吐量的读写访问进行了优化。一些依赖复杂文件系统特性（如文件锁、稀疏文件等）的应用可能无法正常工作。
+3.  **权限问题**：如果遇到权限错误，可以尝试在挂载命令中添加 `--allow-other` 参数，允许其他用户访问挂载点。
+
+### 7. 在 Docker 容器中使用
+
+Mountpoint 也提供了官方 Docker 镜像，方便在容器化环境中使用。
+
+```bash
+# 拉取镜像
+docker pull public.ecr.aws/mountpoint-s3/mountpoint-s3
+
+# 运行容器并挂载
+docker run -it --rm \
+  --cap-add SYS_ADMIN \
+  --device /dev/fuse \
+  -e AWS_ACCESS_KEY_ID=myaccesskey \
+  -e AWS_SECRET_ACCESS_KEY=mysecretkey \
+  -e AWS_ENDPOINT_URL=http://你的RustFS服务IP:9000 \
+  public.ecr.aws/mountpoint-s3/mountpoint-s3 \
+  my-bucket /mnt
+```
+注意，运行需要添加 `--cap-add SYS_ADMIN` 和 `--device /dev/fuse` 权限。
+
+
+
+## 查询所有挂载
+mount | grep mountpoint-s3
+
+
+## 取消挂载
+umount