update disk caching zh_CN document. (minio#10472)

add disk caching DESIGN zh_CN document.
beykery · Sep 18, 2020 · dff37aa · dff37aa
1 parent d12831e
commit dff37aa
Show file tree

Hide file tree

Showing 2 changed files with 106 additions and 24 deletions.
diff --git a/docs/zh_CN/disk-caching/DESIGN.md b/docs/zh_CN/disk-caching/DESIGN.md
@@ -0,0 +1,81 @@
+# 磁盘缓存设计 [![Slack](https://slack.min.io/slack?type=svg)](https://slack.min.io)
+
+本文档介绍了一些基本假设和设计方法，以及磁盘缓存功能的限制。如果您希望入门使用磁盘缓存，建议您先阅读[入门文档](https://github.com/minio/minio/blob/master/docs/zh_CN/disk-caching/README.md)。
+
+## 命令行
+
+```
+minio gateway <name> -h
+...
+...
+  CACHE:
+     MINIO_CACHE_DRIVES: List of mounted cache drives or directories delimited by ","
+     MINIO_CACHE_EXCLUDE: List of cache exclusion patterns delimited by ","
+     MINIO_CACHE_QUOTA: Maximum permitted usage of the cache in percentage (0-100).
+     MINIO_CACHE_AFTER: Minimum number of access before caching an object.
+     MINIO_CACHE_WATERMARK_LOW: % of cache quota at which cache eviction stops
+     MINIO_CACHE_WATERMARK_HIGH: % of cache quota at which cache eviction starts
+     MINIO_CACHE_RANGE: set to "on" or "off" caching of independent range requests per object, defaults to "on"
+
+
+...
+...
+
+  Start MinIO gateway to s3 with edge caching enabled on '/mnt/drive1', '/mnt/drive2' and '/mnt/export1 ... /mnt/export24',
+     exclude all objects under 'mybucket', exclude all objects with '.pdf' as extension. Cache only those objects accessed atleast 3 times. Garbage collection triggers in at high water mark (i.e. cache disk usage reaches 90% of cache quota) or at 72% and evicts oldest objects by access time until low watermark is reached ( 70% of cache quota) , i.e. 63% of disk usage.
+     $ export MINIO_CACHE_DRIVES="/mnt/drive1,/mnt/drive2,/mnt/export{1..24}"
+     $ export MINIO_CACHE_EXCLUDE="mybucket/*,*.pdf"
+     $ export MINIO_CACHE_QUOTA=80
+     $ export MINIO_CACHE_AFTER=3
+     $ export MINIO_CACHE_WATERMARK_LOW=70
+     $ export MINIO_CACHE_WATERMARK_HIGH=90
+
+     $ minio gateway s3
+```
+
+### 在Docker容器上运行具有缓存的MinIO网关
+### Stable
+缓存驱动器需要为磁盘缓存功能启用`strictatime` 或者 `relatime`。在此示例中，在启用了`strictatime`或者`relatime`的情况下，将xfs文件系统挂载在/mnt/cache上。
+
+```
+truncate -s 4G /tmp/data
+mkfs.xfs /tmp/data     # build xfs filesystem on /tmp/data
+sudo mkdir /mnt/cache  # create mount dir
+sudo mount -o relatime /tmp/data /mnt/cache # mount xfs on /mnt/cache with atime.
+docker pull minio/minio
+docker run --net=host -e MINIO_ACCESS_KEY={s3-access-key} -e MINIO_SECRET_KEY={s3-secret-key} -e MINIO_CACHE_DRIVES=/cache -e MINIO_CACHE_QUOTA=99 -e MINIO_CACHE_AFTER=0 -e MINIO_CACHE_WATERMARK_LOW=90 -e MINIO_CACHE_WATERMARK_HIGH=95  -v /mnt/cache:/cache  minio/minio:latest gateway s3
+
+```
+
+## 假设
+
+- 磁盘缓存配额默认为驱动器容量的80％。
+- 缓存驱动器必须是启用[`atime`](http://kerolasa.github.io/filetimes.html)支持的文件系统挂载点。另外，可以在MINIO_CACHE_DRIVES中指定具有atime支持的可写目录。
+- 每当缓存磁盘使用率相对于配置的缓存配额达到高水位线时，就会发生垃圾收集扫描，GC会清理最近访问最少的对象，直到达到相对于配置的缓存配额的低水位线为止。垃圾收集每隔30分钟运行一次缓存清理扫描。
+- 仅在驱动器具有足够的磁盘空间时才缓存对象。
+
+## 行为
+
+磁盘缓存为**下载的**对象缓存，即
+
+- 下载时如果在缓存中找不到的该条目，则缓存为新对象，否则从缓存中获取。
+- 当从缓存中获取对象时，也会将Bitrot保护添加到缓存的内容中并进行验证。
+- 删除对象时，也会删除缓存中的相应条目（如果有）。
+- 后端离线时，缓存可继续用于诸如GET，HEAD之类的只读操作。
+- Cache-Control和Expires头信息可用于控制对象在缓存中保留的时间。直到满足Cache-Control或Expires的到期时间，才会使用后端验证缓存对象的ETag。
+- 默认情况下，所有range GET请求都会单独缓存 ，但是这并不适用于所有情形，比如当缓存存储受到限制时，因为这种情形下一次性下载整个对象才是最佳选择。 可以选择通过`export MINIO_CACHE_RANGE=off`关闭此功能，以便可以在后台下载整个对象。
+- 为了确保安全性，通常不缓存加密对象。但是，如果希望加密磁盘上的缓存内容，则可以通过MINIO_CACHE_ENCRYPTION_MASTER_KEY环境变量设置一个缓存KMS主密钥，以自动加密所有缓存内容。
+
+  请注意，不建议将缓存KMS主密钥用于生产部署中。如果MinIO server/gateway 机器曾经遭到破解，则缓存KMS主密钥也必须被视为受到破解。
+  支持外部KMS来管理缓存KMS密钥已经在计划中，这对于生产部署而言将是理想的选择。
+
+> 注意：根据上述配置的间隔，过期会自动发生，经常访问的对象在缓存中的存活时间会更长。
+
+### Crash 恢复
+
+minio进程被杀死或者崩溃后重启minio网关，磁盘缓存将自动恢复。垃圾回收周期将恢复，并且任何先前缓存的条目都可以正常使用。
+
+## 限制
+
+- 存储桶策略未缓存，因此后端离线时不支持匿名操作。
+- 使用确定性的散列，对象会被分配到已配置的缓存驱动器上。如果一个或多个驱动器离线，或者更改了缓存驱动器配置，则性能可能会降低到线性查找时间，具体取决于缓存中的磁盘数量。
diff --git a/docs/zh_CN/disk-caching/README.md b/docs/zh_CN/disk-caching/README.md
@@ -1,41 +1,42 @@
 # 磁盘缓存快速入门 [![Slack](https://slack.min.io/slack?type=svg)](https://slack.min.io)
 
-这里的磁盘缓存功能是指使用缓存磁盘来存储租户常用的一些数据。例如，假设你通过`gateway azure`设置访问一个对象并下载下来进行缓存，那接下来的请求都会直接访问缓存磁盘上的对象，直至其过期失效。此功能允许Minio用户：
+这里的磁盘缓存功能是指使用缓存磁盘将内容存储在更靠近租户的地方。例如，假设你通过`gateway azure`设置访问一个对象并下载下来进行缓存，那接下来的请求都会直接访问缓存磁盘上的对象，直至其过期失效。此功能允许MinIO用户：
 - 对象的读取速度性能最佳。
 - 任何对象的首字节时间得到显著改善。
 
 ## 开始
 
-### 1. 前期条件
-安装Minio - [Minio快速入门](https://docs.min.io/docs/minio-quickstart-guide)。
+### 1. 前置条件
+安装MinIO - [MinIO快速入门](https://docs.min.io/cn/minio-quickstart-guide)。
 
-### 2. 运行Minio缓存
-磁盘缓存可以通过修改Minio服务的`cache`配置来进行开启。配置`cache`设置需要指定磁盘路径、缓存过期时间（以天为单位）以及使用统配符方式指定的不需要进行缓存的对象。
+### 2. 运行带缓存的MinIO网关
+可以通过设置`cache`环境变量为MinIO网关启用磁盘缓存。配置`cache`环境变量需要指定磁盘路径、使用通配符方式指定的不需要进行缓存的对象、用于缓存垃圾回收的高低水位线以及缓存一个对象前的最小访问次数（译者注：就是对象被访问多少次后才缓存它）。
 
-```json
-"cache": {
-	"drives": ["/mnt/drive1", "/mnt/drive2", "/mnt/drive3"],
-	"expiry": 90,
-	"exclude": ["*.pdf","mybucket/*"]
-},
-```
-
-缓存设置也可以通过环境变量设置。设置后，环境变量会覆盖任何`cache`配置中的值。下面示例使用`/mnt/drive1`, `/mnt/drive2` 和 `/mnt/drive3`来做缓存，90天失效，并且`mybucket`下的所有对象以及后缀名为`.pdf`的对象不做缓存。
+下面示例使用`/mnt/drive1`, `/mnt/drive2` ,`/mnt/cache1` ... `/mnt/cache3`来做缓存，并且`mybucket`下的所有对象以及后缀名为`.pdf`的对象不做缓存。如果对象被访问过三次及以上，则将其缓存。在此示例中，缓存最大使用量限制为磁盘容量的80％。当达到高水位线的时候垃圾回收会被触发（即缓存磁盘使用率达到72%的时候），这时候会清理最近最少使用的条目直到磁盘使用率降到低水位线为止（即缓存磁盘使用率降到56%）。
 
 ```bash
-export MINIO_CACHE_DRIVES="/mnt/drive1,/mnt/drive2,/mnt/drive3"
-export MINIO_CACHE_EXPIRY=90
+export MINIO_CACHE="on"
+export MINIO_CACHE_DRIVES="/mnt/drive1,/mnt/drive2,/mnt/cache{1...3}"
 export MINIO_CACHE_EXCLUDE="*.pdf,mybucket/*"
-minio server /export{1...24}
+export MINIO_CACHE_QUOTA=80
+export MINIO_CACHE_AFTER=3
+export MINIO_CACHE_WATERMARK_LOW=70
+export MINIO_CACHE_WATERMARK_HIGH=90
+
+minio gateway s3
 ```
 
+`CACHE_WATERMARK`的值是`CACHE_QUOTA`的百分比。
+在上面的示例中，`MINIO_CACHE_WATERMARK_LOW`实际上是磁盘总空间的`0.8 * 0.7 * 100 = 56%`，`MINIO_CACHE_WATERMARK_LOW`实际上是磁盘总空间的`0.8 * 0.9 * 100 = 72%`。
+
+
 ### 3. 验证设置是否成功
-要验证是否部署成功，你可以通过浏览器或者[`mc`](https://docs.min.io/docs/minio-client-quickstart-guide)来访问刚刚部署的Minio服务。你应该可以看到上传的文件在所有Minio节点上都可以访问。
+要验证是否部署成功，你可以通过浏览器或者[`mc`](https://docs.min.io/cn/minio-client-quickstart-guide)来访问刚刚部署的MinIO网关。你应该可以看到上传的文件在所有MinIO节点上都可以访问。
 
 # 了解更多
-- [磁盘缓存设计](https://github.com/minio/minio/blob/master/docs/disk-caching/DESIGN.md)
-- [mc快速入门](https://docs.min.io/docs/minio-client-quickstart-guide)
-- [使用 aws-cli](https://docs.min.io/docs/aws-cli-with-minio)
-- [使用 s3cmd](https://docs.min.io/docs/s3cmd-with-minio)
-- [使用 minio-go SDK](https://docs.min.io/docs/golang-client-quickstart-guide)
-- [Minio文档](https://docs.min.io)
+- [磁盘缓存设计](https://github.com/minio/minio/blob/master/docs/zh_CN/disk-caching/DESIGN.md)
+- [`mc`快速入门](https://docs.min.io/cn/minio-client-quickstart-guide)
+- [使用 `aws-cli`](https://docs.min.io/cn/aws-cli-with-minio)
+- [使用 `s3cmd`](https://docs.min.io/cn/s3cmd-with-minio)
+- [使用 `minio-go` SDK](https://docs.min.io/cn/golang-client-quickstart-guide)
+- [MinIO文档](https://docs.min.io/cn/)