docs: update troubleshooting case (#1056)

--------- Signed-off-by: Xuhui zhang <[email protected]> Co-authored-by: timfeirg <[email protected]> Co-authored-by: Changjian Gao <[email protected]>
juicedata · Aug 1, 2024 · 178fc2f · 178fc2f
1 parent 484beb8
commit 178fc2f
Show file tree

Hide file tree

Showing 9 changed files with 288 additions and 192 deletions.
diff --git a/.markdownlint-cli2.jsonc b/.markdownlint-cli2.jsonc
@@ -23,10 +23,12 @@
         "TabItem",
         "Tabs",
         "br",
+        "details",
         "div",
         "iframe",
         "kbd",
         "span",
+        "summary",
         "sup"
       ]
     },

diff --git a/docs/en/FAQs.md b/docs/en/FAQs.md
@@ -7,7 +7,8 @@ slug: /faq
 
 Try searching for your problems in the top right corner, using different keywords. If nothing comes up:
 
-* For JuiceFS Community Edition users, join [the JuiceFS Community](https://juicefs.com/en/community) and seek for help.
+* Use [troubleshooting tools](./administration/troubleshooting.md#tools) to self-troubleshoot problems;
+* For JuiceFS Community Edition users, join [the JuiceFS Community](https://juicefs.com/en/community) and seek for help;
 * For JuiceFS Cloud Service users, reach the Juicedata team using Intercom by clicking the bottom right button in [the JuiceFS Web Console](https://juicefs.com/console).
 
 ## How to seamlessly remount JuiceFS file system? {#seamless-remount}

diff --git a/docs/en/administration/troubleshooting-cases.md b/docs/en/administration/troubleshooting-cases.md
diff --git a/docs/en/administration/troubleshooting.md b/docs/en/administration/troubleshooting.md
@@ -6,7 +6,9 @@ sidebar_position: 6
 
 Read this chapter to learn how to troubleshoot JuiceFS CSI Driver, to continue, you should already be familiar with [the JuiceFS CSI Architecture](../introduction.md#architecture), i.e. have a basic understanding of the roles of each CSI Driver component.
 
-## CSI dashboard {#csi-dashboard}
+## Troubleshooting tools {#tools}
+
+### CSI dashboard {#csi-dashboard}
 
 CSI dashboard is installed along with JuiceFS CSI Driver, it provides a web interface to view the status of JuiceFS CSI Driver components. Also, you can see all PVs, PVCs, and Pods that are using JuiceFS PVs. With CSI dashboard, you can easily debug and troubleshoot. Strongly recommended to use dashboard.
 
@@ -16,11 +18,11 @@ Access the dashboard and you can see the following interface:
 
 As shown in the figure, all the related resources are displayed in the dashboard, you can click on the resource to view detailed information.
 
-## kubectl plugin {#kubectl-plugin}
+### kubectl plugin {#kubectl-plugin}
 
 JuiceFS provides a kubectl plugin to help you easily debug and troubleshoot in Kubernetes.
 
-### Installation {#kubectl-jfs-plugin-installation}
+#### Installation {#kubectl-jfs-plugin-installation}
 
 The one-click installation script is available for Linux and macOS systems. It automatically downloads and installs the latest version of the plugin based on your hardware architecture. Here is how to use it:
 
@@ -29,7 +31,7 @@ The one-click installation script is available for Linux and macOS systems. It a
 curl -sSL https://d.juicefs.com/kubectl-jfs-install | sh -
 ```
 
-### Usage {#kubectl-jfs-plugin-usage}
+#### Usage {#kubectl-jfs-plugin-usage}
 
 ```shell
 # show all application pods using JuiceFS PV quickly
@@ -86,26 +88,30 @@ Mount Pods:
   juicefs-cn-hangzhou.10.0.1.84-wrong-nvblwj  kube-system  Error
 Failed Reason:
   Mount pod [juicefs-cn-hangzhou.10.0.1.84-wrong-nvblwj] is not ready, please check its log.
-  
+
 # troubleshooting JuiceFS PVC
 $ kubectl jfs debug pvc <pvcName>
 $ kubectl jfs debug pv <pvName>
 ```
 
-Furthermore, there are quick ways to obtain accesslog of Mount Pod and warmup volumes:
+Furthermore, there are quick ways to obtain access log of Mount Pod and warmup cache:
 
 ```shell
-# get Mount Pod accesslog: kubectl jfs accesslog <pod-name> -m <mount-namespace> 
+# Get Mount Pod access log: kubectl jfs accesslog <pod-name> -m <mount-namespace>
 $ kubectl jfs accesslog juicefs-cn-hangzhou.10.0.1.84-ce-static-handle-qhuuvh
 2024.07.05 14:09:57.392403 [uid:0,gid:0,pid:201] open (9223372032559808513): OK [fh:25] <0.000054>
 #
 
-# warmup quickly: kubectl jfs warmup <pod-name> <subpath> -m <mount-namespace> 
+# Warmup cache: kubectl jfs warmup <pod-name> <subpath> -m <mount-namespace>
 $ kubectl jfs warmup juicefs-cn-hangzhou.10.0.1.84-ce-static-handle-qhuuvh
 2024/07/05 14:10:52.628976 juicefs[207] <INFO>: Successfully warmed up 2 files (1090721713 bytes) [warmup.go:226]
 ```
 
-## Diagnostic script {#csi-doctor}
+### Diagnostic script {#csi-doctor}
+
+:::note
+Please use [kubectl plugin](#kubectl-plugin) first. If it cannot meet your needs, try using the diagnostic script again.
+:::
 
 It is recommended to use the diagnostic script [`csi-doctor.sh`](https://github.com/juicedata/juicefs-csi-driver/blob/master/scripts/csi-doctor.sh) to collect logs and related information, without this script, you'll have to manually execute a series of commands (introduced in other sections in this chapter) to obtain information.
 

diff --git a/docs/en/guide/pv.md b/docs/en/guide/pv.md
@@ -337,7 +337,7 @@ After pod is up and running, you'll see `out.txt` being created by the container
 
 [StorageClass](https://kubernetes.io/docs/concepts/storage/storage-classes) handles configurations to create different PVs, think of it as a profile for dynamic provisioning: each StorageClass may contain different volume credentials and mount options, so that you can use multiple settings under dynamic provisioning. Thus if you decide to use JuiceFS CSI Driver via [dynamic provisioning](#dynamic-provisioning), you'll need to create a StorageClass in advance.
 
-Due to StorageClass being the template used for creating PVs, **modifying mount options in StorageClass will not affect existing PVs**, if you need to adjust mount options under dynamic provisioning, you'll have to delete existing PVCs, or [directly modify mount options in existing PVs](./configurations.md#static-mount-options).
+Due to StorageClass being the template used for creating PVs, **modifying mount options in StorageClass will not affect existing PVs,** if you need to adjust mount options under dynamic provisioning, you'll have to delete existing PVCs, or [directly modify mount options in existing PVs](./configurations.md#static-mount-options).
 
 ### Create via Helm {#helm-sc}
 

diff --git a/docs/zh_cn/FAQs.md b/docs/zh_cn/FAQs.md
@@ -7,7 +7,8 @@ slug: /faq
 
 请首先尝试使用站内搜索功能（右上角），尝试用不同的关键词进行检索，如果文档始终未能解决你的疑问，你可以：
 
-* 如果你使用 JuiceFS 社区版，加入 [JuiceFS 开源社区](https://juicefs.com/zh-cn/community)以寻求帮助。
+* 使用[排查工具](./administration/troubleshooting.md#tools)自助排查问题；
+* 如果你使用 JuiceFS 社区版，加入 [JuiceFS 开源社区](https://juicefs.com/zh-cn/community)以寻求帮助；
 * 如果你使用 JuiceFS 云服务，请通过[控制台](https://juicefs.com/console)右下角的 Intercom 会话联系 Juicedata 团队。
 
 ## 如何平滑重新挂载 JuiceFS 文件系统？ {#seamless-remount}