Docs: update posix_acl.md (#4796)

Co-authored-by: jiefenghuang <[email protected]>

docs/en/security/posix_acl.md

@@ -1,54 +1,54 @@
 ---
+title: POSIX ACL
+description: This article introduces the POSIX ACL feature supported by JuiceFS and how to enable and use ACL permissions.
 sidebar_position: 1
 ---
 
-# POSIX ACL
+POSIX ACL (Portable Operating System Interface for Unix - Access Control List) is a type of access control mechanism in Unix-like operating systems that allows for finer-grained control over file and directory access permissions.
 
-Version 1.2 supports POSIX ACL. For detailed rules, please refer to:
+## Versions and Compatibility Requirements
 
-- [POSIX Access Control Lists on Linux](https://www.usenix.org/legacy/publications/library/proceedings/usenix03/tech/freenix03/full_papers/gruenbacher/gruenbacher_html/main.html)
-- [setfacl](https://linux.die.net/man/1/setfacl)
+* JuiceFS supports POSIX ACL from version 1.2 onwards;
+* All versions of the client can mount volumes without ACL enabled, regardless of whether they were created by a new or old version of the client;
+* Once ACL is enabled, it cannot be disabled; therefore, the `--enable-acl` option is tied to the volume.
 
-## Usage
+:::caution
+If you plan to use ACL functionality, it is recommended to upgrade all clients to the latest version to avoid potential issues with older versions affecting the accuracy of ACLs.
+:::
 
-<!-- markdownlint-disable MD044 enhanced-proper-names -->
+## Enabling ACL
 
-Currently, once ACL is enabled, it cannot be disabled.
-Therefore, the --enable-acl flag is associated with the volume.
+As mentioned earlier, you can enable ACL when creating a new volume or on an existing volume using a new version of the client.
 
-### Enable ACL for new volumes
+### Creating a New Volume and Enabling ACL
 
 ```shell
-juicefs format sqlite3://myjfs.db myjfs --enable-acl
+juicefs format --enable-acl sqlite3://myjfs.db myjfs
 ```
 
-### Enable ACl for existing volumes
+### Enabling ACL on an Existing Volume
 
-- Upgrade all old client to v1.2 and remount it.
-- Use the following command with v1.2 client to change the volume configuration.
+Use the `config` command to enable ACL functionality on an existing volume:
 
-```shell
-juicefs config sqlite3://myjfs.db --enable-acl
+```
+juicefs config --enable-acl sqlite3://myjfs.db
 ```
 
-<!-- markdownlint-enable MD044 enhanced-proper-names -->
+## Usage
 
-## Compatibility
+To set ACL permissions for a file or directory, you can use the `setfacl` command, for example:
 
-- New client versions are compatible with old volume versions.
-- Old client versions are compatible with new volume versions (without ACL enabled).
+```
+setfacl -m u:alice:rw- /mnt/jfs/file
+```
 
-:::caution Note
-If ACL is enabled, it is recommended that all clients to be upgraded.
-If an old client mounts a new volume (without ACL enabled),
-and ACL is subsequently enabled on the volume,
-operations by the old client may impact the correctness of ACL.
-:::
+For more detailed rules and guidelines on POSIX ACLs, please refer to:
+
+* [POSIX Access Control Lists on Linux](https://www.usenix.org/legacy/publications/library/proceedings/usenix03/tech/freenix03/full_papers/gruenbacher/gruenbacher_html/main.html)
+* [setfacl](https://linux.die.net/man/1/setfacl)
+* [JuiceFS ACL Functionality: A Detailed Explanation of Fine-Grained Permission Control](https://juicefs.com/en/blog/release-notes/juicefs-12-beta-1)
 
-## Others
+## Notes
 
-- ACL permission checks are supported only in Linux kernel 4.9 and higher versions. You can refer to this [documentation](https://lkml.iu.edu/hypermail/linux/kernel/1610.0/01531.html) for more details.
-- Enabling ACL increases the minimum client version requirement to v1.2.
-- Enabling ACL may have additional performance implications.
-For scenarios with infrequent ACL changes,
-the impact is minimal with memory cache optimization.
+* ACL permission checks require a [Linux kernel 4.9](https://lkml.iu.edu/hypermail/linux/kernel/1610.0/01531.html) or later;
+* Enabling ACL will have an additional performance impact. However, due to memory cache optimization, most usage scenarios experience relatively low performance degradation.

docs/zh_cn/security/posix_acl.md

@@ -1,46 +1,54 @@
 ---
+title: POSIX ACL
+description: 本文介绍了 JuiceFS 支持的 POSIX ACL 功能，以及如何启用和使用 ACL 权限。
 sidebar_position: 3
 ---
-# POSIX ACL
 
-1.2 版本支持 POSIX ACL, 详细规则参考
+POSIX ACL（Portable Operating System Interface for Unix - Access Control List）是 Unix-like 操作系统中的一种访问控制机制，可以对文件和目录的访问权限进行更细粒度的控制。
 
-- [POSIX Access Control Lists on Linux](https://www.usenix.org/legacy/publications/library/proceedings/usenix03/tech/freenix03/full_papers/gruenbacher/gruenbacher_html/main.html)
-- [setfacl](https://linux.die.net/man/1/setfacl)
+## 版本及兼容性要求
 
-## 使用
+- JuiceFS 从 v1.2 版本开始支持 POSIX ACL；
+- 所有版本客户端都可以挂载没有开启 ACL 的卷，不论这些卷是由新版本客户端创建的还是由旧版本客户端创建的；
+- ACL 开启后暂不支持取消，因此 `--enable-acl` 选项是关联到卷的。
 
-<!-- markdownlint-disable MD044 enhanced-proper-names -->
+:::caution 提示
+如果计划使用 ACL 功能，建议将所有客户端升级的最新版，避免旧版本客户端影响 ACL 的正确性。
+:::
 
-目前 ACL 开启后暂不支持取消，所以--enable-acl flag 与卷关联。
+## 启用 ACL
 
-### 新卷创建启用 ACL
+如前所述，可以用新版客户端在创建新卷时开启 ACL，也可以用新版客户端在已创建的卷上开启 ACL。
+
+### 创建新卷并开启 ACL
 
 ```shell
-juicefs format sqlite3://myjfs.db myjfs --enable-acl
+juicefs format --enable-acl sqlite3://myjfs.db myjfs
 ```
 
-### 已有卷启用 ACL
+### 在已有卷上开启 ACL
 
-- 所有旧客户端升级到 v1.2, 并且重新 mount 卷
-- 使用 v1.2 版本客户端执行下面指令进行配置
+使用 `config` 命令为一个已创建的卷开启 ACL 功能：
 
 ```shell
-juicefs config sqlite3://myjfs.db --enable-acl
+juicefs config --enable-acl sqlite3://myjfs.db
 ```
 
-<!-- markdownlint-enable MD044 enhanced-proper-names -->
+## 使用方法
 
-## 兼容
+为一个文件或目录设置 ACL 权限，可以使用 `setfacl` 命令，例如：
 
-- 新版本客户端兼容老版本卷
-- 老版本客户端兼容 (不开启 ACL 的) 新版本卷
-:::caution 提示
-如果启用 ACL 功能，建议所有客户端都升级。老版本客户端挂载了新卷 (没有开启 ACL), 后续如果卷开启 ACL, 老版本客户端的操作会影响 ACL 的正确性
-:::
+```shell
+setfacl -m u:alice:rw- /mnt/jfs/file
+```
+
+更多关于 POSIX ACL 的详细规则，请参考：
+
+- [POSIX Access Control Lists on Linux](https://www.usenix.org/legacy/publications/library/proceedings/usenix03/tech/freenix03/full_papers/gruenbacher/gruenbacher_html/main.html)
+- [setfacl](https://linux.die.net/man/1/setfacl)
+- [JuiceFS ACL 功能全解析，更精细的权限控制](https://juicefs.com/zh-cn/blog/release-notes/juicefs-v12-beta-1-acl)
 
-## 其他
+## 注意事项
 
-- 开启 ACL 后，需要[Linux kernel 4.9](https://lkml.iu.edu/hypermail/linux/kernel/1610.0/01531.html)及以上版本，才支持 ACL 权限检测
-- 开启 ACL 后，客户端版本要求会提升到 v1.2
-- 开启 ACL 会有额外的性能影响，对于 ACL 变动不频繁的场景，有内存 cache 优化影响不大
+- ACL 权限检测需要 [Linux kernel 4.9](https://lkml.iu.edu/hypermail/linux/kernel/1610.0/01531.html) 及以上版本；
+- 启用 ACL 会有额外的性能影响。但因为有内存缓存优化，大部分使用场景性能损耗都较低，可参考[压测结果](https://juicefs.com/zh-cn/blog/release-notes/juicefs-v12-beta-1-acl#03-%E6%80%A7%E8%83%BD)。