From 9d2ad3c2b179ff89de4a8a29951b106f44a70faf Mon Sep 17 00:00:00 2001 From: Yash Date: Thu, 30 Jul 2026 10:48:18 -0400 Subject: [PATCH] docs(i18n): add missing Simplified Chinese translations for docs Signed-off-by: Yash --- .../application-layer/circuit-breaker.md | 152 +++++++ .../application-layer/rate-limiting.md | 416 ++++++++++++++++++ .../Kmesh-daemon-map-upgarde.md | 36 ++ .../Kmeshctl-usage/kmeshctl-monitoring.md | 50 +++ .../developer-guide/Tests/e2e-quickstart.md | 129 ++++++ .../Tests/ipsec-auth-e2e-test.md | 319 ++++++++++++++ .../developer-guide/website/create-blog.md | 240 ++++++++++ .../developer-guide/website/create-doc.md | 248 +++++++++++ .../developer-guide/website/versioning-doc.md | 361 +++++++++++++++ .../workflow-automation-guide.md | 68 +++ .../current/kmeshctl/kmeshctl.md | 19 + .../current/kmeshctl/kmeshctl_accesslog.md | 27 ++ .../current/kmeshctl/kmeshctl_authz.md | 16 + .../kmeshctl/kmeshctl_authz_disable.md | 24 + .../current/kmeshctl/kmeshctl_authz_enable.md | 24 + .../current/kmeshctl/kmeshctl_authz_status.md | 24 + .../current/kmeshctl/kmeshctl_dump.md | 31 ++ .../current/kmeshctl/kmeshctl_log.md | 31 ++ .../current/kmeshctl/kmeshctl_monitoring.md | 50 +++ .../current/kmeshctl/kmeshctl_secret.md | 30 ++ .../kmeshctl/kmeshctl_secret_create.md | 27 ++ .../kmeshctl/kmeshctl_secret_delete.md | 23 + .../current/kmeshctl/kmeshctl_secret_get.md | 24 + .../current/kmeshctl/kmeshctl_version.md | 27 ++ .../current/kmeshctl/kmeshctl_waypoint.md | 42 ++ .../kmeshctl/kmeshctl_waypoint_apply.md | 47 ++ .../kmeshctl/kmeshctl_waypoint_delete.md | 46 ++ .../kmeshctl/kmeshctl_waypoint_generate.md | 41 ++ .../kmeshctl/kmeshctl_waypoint_list.md | 40 ++ .../kmeshctl/kmeshctl_waypoint_status.md | 39 ++ .../current/transpot-layer/accesslog.md | 40 ++ 31 files changed, 2691 insertions(+) create mode 100644 i18n/zh/docusaurus-plugin-content-docs/current/application-layer/circuit-breaker.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/current/application-layer/rate-limiting.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/current/developer-guide/Kmesh-daemon-map-upgarde.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/current/developer-guide/Kmeshctl-usage/kmeshctl-monitoring.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/current/developer-guide/Tests/e2e-quickstart.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/current/developer-guide/Tests/ipsec-auth-e2e-test.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/current/developer-guide/website/create-blog.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/current/developer-guide/website/create-doc.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/current/developer-guide/website/versioning-doc.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/current/developer-guide/workflow-automation-guide.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/current/kmeshctl/kmeshctl.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/current/kmeshctl/kmeshctl_accesslog.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/current/kmeshctl/kmeshctl_authz.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/current/kmeshctl/kmeshctl_authz_disable.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/current/kmeshctl/kmeshctl_authz_enable.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/current/kmeshctl/kmeshctl_authz_status.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/current/kmeshctl/kmeshctl_dump.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/current/kmeshctl/kmeshctl_log.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/current/kmeshctl/kmeshctl_monitoring.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/current/kmeshctl/kmeshctl_secret.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/current/kmeshctl/kmeshctl_secret_create.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/current/kmeshctl/kmeshctl_secret_delete.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/current/kmeshctl/kmeshctl_secret_get.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/current/kmeshctl/kmeshctl_version.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/current/kmeshctl/kmeshctl_waypoint.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/current/kmeshctl/kmeshctl_waypoint_apply.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/current/kmeshctl/kmeshctl_waypoint_delete.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/current/kmeshctl/kmeshctl_waypoint_generate.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/current/kmeshctl/kmeshctl_waypoint_list.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/current/kmeshctl/kmeshctl_waypoint_status.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/current/transpot-layer/accesslog.md diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/application-layer/circuit-breaker.md b/i18n/zh/docusaurus-plugin-content-docs/current/application-layer/circuit-breaker.md new file mode 100644 index 000000000..62a5e4deb --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/current/application-layer/circuit-breaker.md @@ -0,0 +1,152 @@ +--- +title: 熔断器 +sidebar_position: 10 +--- + +本文档提供逐步指南，介绍如何测试 Kmesh 的熔断功能。内容涵盖部署所需组件、配置流量规则，以及观察熔断行为。 + +## 步骤 1. 部署 Kmesh + +请阅读[快速入门](https://kmesh.net/docs/setup/quick-start)以完成 Kmesh 的部署。 + +## 步骤 2. 部署 fortio 和 httpbin + +``` sh +kubectl apply -f -< /dev/null || \ + { kubectl kustomize "github.com/kubernetes-sigs/gateway-api/config/crd/experimental?ref=444631bfe06f3bcca5d0eadf1857eac1d369421d" | kubectl apply -f -; } +``` + +接下来，为 `httpbin` 服务创建专用的 Waypoint 代理，并为该服务打上标签，使其流量经由该 Waypoint。 + +```sh +kmeshctl waypoint apply -n default --name httpbin-waypoint --image ghcr.io/kmesh-net/waypoint:latest +kubectl label service httpbin istio.io/use-waypoint=httpbin-waypoint +``` + +## 步骤 4. 配置 DestinationRule + +```sh +kubectl apply -f - < /dev/null || \ + { kubectl kustomize "github.com/kubernetes-sigs/gateway-api/config/crd/experimental?ref=v1.4.0" | kubectl create -f -; } +``` + +接下来，为 `httpbin` 服务创建专用的 Waypoint 代理，并为该服务打上标签，使其流量经由该 Waypoint。 + +```sh +kmeshctl waypoint apply -n default --name httpbin-waypoint --image ghcr.io/kmesh-net/waypoint:latest + +kubectl label service httpbin istio.io/use-waypoint=httpbin-waypoint +``` + +### 4. 部署 EnvoyFilter + +此 `EnvoyFilter` 资源会将本地限流过滤器注入到 `httpbin` 服务的 Waypoint 代理中。该过滤器配置了以下规则： + +- 带有请求头 `quota: low` 的请求将被限制为**每 300 秒 1 个请求**。 +- 带有请求头 `quota: medium` 的请求将被限制为**每 300 秒 3 个请求**。 +- 其他请求将受默认限制：**每 300 秒 10 个请求**。 + +`workloadSelector` 确保该过滤器仅应用于 `httpbin-waypoint` 代理。 + +```sh +kubectl apply -f -< --accesslog enable/disable + +# Enable/Disable services' metrics and accesslog generated from bpf: +kmeshctl monitoring --all enable/disable + +# Enable/Disable workload granularity metrics: +kmeshctl monitoring --workloadMetrics enable/disable + +# Enable/Disable connection granularity metrics: +kmeshctl monitoring --connectionMetrics enable/disable + +# If you want to change the monitoring functionality of all kmesh daemons in the cluster +# Enable/Disable Kmesh's accesslog in each node: +kmeshctl monitoring --accesslog enable/disable + +# Enable/Disable workload granularity metrics in each node: +kmeshctl monitoring --workloadMetrics enable/disable + +# Enable/Disable connection granularity metrics in each node: +kmeshctl monitoring --connectionMetrics enable/disable + +#Enable/Disable services', workloads' and 'connections' metrics and accesslog generated from bpf in each node: +kmeshctl monitoring --all enable/disable +``` + +### 选项 + +```bash + --accesslog string Control accesslog enable or disable + --all string Control accesslog and services' and workloads' metrics enable or disable together + + --connectionMetrics string Control connection granularity metrics enable or disable + -h, --help help for monitoring + --workloadMetrics string Control workload granularity metrics enable or disable +``` diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/developer-guide/Tests/e2e-quickstart.md b/i18n/zh/docusaurus-plugin-content-docs/current/developer-guide/Tests/e2e-quickstart.md new file mode 100644 index 000000000..d9a062266 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/current/developer-guide/Tests/e2e-quickstart.md @@ -0,0 +1,129 @@ +# Kmesh E2E 测试快速入门 + +本文档旨在帮助开发者快速上手编写和运行 Kmesh 项目的端到端（E2E）测试。内容涵盖先决条件、测试环境搭建、简单测试函数模板，以及运行测试的说明。按照本指南操作，您将能够高效地编写并执行 E2E 测试，从而保障 Kmesh 功能的稳定性与正确性。 + +## 先决条件 + +开始之前，请确保环境中已安装以下工具： + +- **Go**：用于运行测试框架。 +- **Docker**：用于容器化应用。 +- **kubectl**：用于管理 Kubernetes 集群。 +- **Kind**：用于在本地创建 Kubernetes 集群。 +- **Helm**：用于管理 Kubernetes 应用。 + +## E2E 测试环境 + +Kmesh E2E 测试需要一个双节点 KinD 集群： + +- **Control Node**：管理集群。 +- **Worker Node**：运行测试服务。 + +测试开始时会部署两个服务： + +1. **service-with-waypoint-at-service-granularity**：带有 Waypoint 的服务。 +2. **enrolled-to-kmesh**：不带 Waypoint 的服务。 + +两个服务均使用 Echo Pod，用于测试不同场景。 + +## 编写 E2E 测试 + +以下是一个简单的 E2E 测试函数模板，并附有分步说明： + +```go +func TestEchoCall(t *testing.T) { + // Create a new test suite for the current test + framework.NewTest(t).Run(func(t framework.TestContext) { + // Define a subtest for the Echo Call functionality + t.NewSubTest("Echo Call Test").Run(func(t framework.TestContext) { + // Retrieve the source service (with Waypoint) and destination service (without Waypoint) + src := apps.ServiceWithWaypointAtServiceGranularity[0] + dst := apps.EnrolledToKmesh + + // Define test cases with a name and a checker to validate the response + cases := []struct { + name string + checker echo.Checker + }{ + { + name: "basic call", // Name of the test case + checker: echo.And( + echo.ExpectOK(), // Expect the HTTP call to succeed + echo.ExpectBodyContains("Hello"), // Expect the response body to contain "Hello" + ), + }, + } + + // Iterate over each test case and execute it + for _, c := range cases { + t.NewSubTest(c.name).Run(func(t framework.TestContext) { + // Perform the HTTP call from the source to the destination + src.CallOrFail(t, echo.CallOptions{ + Target: dst[0], // Target service + PortName: "http", // Port name to use for the call + Checker: c.checker, // Checker to validate the response + }) + }) + } + }) + }) +} +``` + +### 步骤说明 + +1. **`framework.NewTest(t).Run`**：为当前测试初始化一个新的测试套件。 +2. **`t.NewSubTest("Echo Call Test").Run`**：为 Echo Call 功能创建一个子测试。 +3. **获取服务**：`src` 变量表示源服务（带 Waypoint），`dst` 变量表示目标服务（不带 Waypoint）。 +4. **定义测试用例**：每个测试用例包含名称以及用于校验 HTTP 响应的 `checker`。例如，`echo.ExpectOK()` 确保 HTTP 调用成功，`echo.ExpectBodyContains("Hello")` 检查响应体内容。 +5. **遍历并执行**：对每个测试用例，`src.CallOrFail` 方法从源向目标发起 HTTP 调用，并使用指定的 `checker` 校验响应。 +6. **`echo.CallOptions`**：指定 HTTP 调用的目标服务、端口名称和 checker。 + +### 资源清理 + +使用 `t.Cleanup` 方法确保测试完成后清理测试资源。例如： + +```go +t.Cleanup(func() { + // Clean up resources +}) +``` + +### 部署策略 + +使用 `t.ConfigIstio` 方法部署测试所需的策略。例如： + +```go +t.ConfigIstio().YAML("test-namespace", ` +apiVersion: security.istio.io/v1beta1 +kind: AuthorizationPolicy +metadata: + name: allow-all +spec: + rules: + - {} +`).ApplyOrFail(t) +``` + +### 使用 echo.Checker + +`echo.Checker` 用于验证测试用例是否通过。例如： + +```go +// Example: Using echo.Checker to validate HTTP response +src.CallOrFail(t, echo.CallOptions{ + Target: dst[0], + PortName: "http", + Checker: echo.And( + echo.ExpectOK(), // Expect the HTTP call to succeed + echo.ExpectBodyContains("Hello"), // Expect the response body to contain "Hello" + echo.ExpectHeaders(map[string]string{ + "Content-Type": "text/plain", // Expect the Content-Type header to be "text/plain" + }), + ), +}) +``` + +## 运行测试 + +有关运行测试的详细说明，请参阅 [E2E 测试指南](https://kmesh.net/docs/developer-guide/Tests/e2e-test)。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/developer-guide/Tests/ipsec-auth-e2e-test.md b/i18n/zh/docusaurus-plugin-content-docs/current/developer-guide/Tests/ipsec-auth-e2e-test.md new file mode 100644 index 000000000..4365766e3 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/current/developer-guide/Tests/ipsec-auth-e2e-test.md @@ -0,0 +1,319 @@ +# IPSec 与 Offload Authorization E2E 测试指南 + +本文档提供执行 Kmesh IPSec 与 Offload Authorization E2E 测试的分步指南。这些测试用于确保 IPSec 功能以及 Offload Authorization 机制的可靠性、安全性与功能性。 + +## 先决条件 + +运行测试前，请确保满足以下条件： + +- **Kubernetes 集群**：已安装 Kmesh 的双节点 Kubernetes 集群。 +- **工具**：`kubectl`、`tcpdump` 和 `kmeshctl`。 +- **应用**：集群中已部署 `echo` 和 `sleep` 应用。 + +## 部署示例 YAML + +**Sleep 应用（保存为 `sleep.yaml`）：** + +```yaml +apiVersion: v1 +kind: Service +metadata: + name: sleep + labels: + app: sleep +spec: + ports: + - port: 80 + name: http + selector: + app: sleep +--- +apiVersion: apps/v1 +kind: Deployment +metadata: + name: sleep +spec: + replicas: 1 + selector: + matchLabels: + app: sleep + template: + metadata: + labels: + app: sleep + spec: + nodeName: kmesh-testing-control-plane + containers: + - name: sleep + image: curlimages/curl + command: ["/bin/sleep", "infinity"] +``` + +**Echo 应用（保存为 `echo.yaml`）：** + +```yaml +apiVersion: v1 +kind: Service +metadata: + name: echo +spec: + ports: + - name: http + port: 80 + targetPort: 8080 + selector: + app: echo +--- +apiVersion: apps/v1 +kind: Deployment +metadata: + name: echo +spec: + replicas: 1 + selector: + matchLabels: + app: echo + template: + metadata: + labels: + app: echo + spec: + containers: + - name: echo + image: gcr.io/istio-testing/app:latest + args: + - --port=8080 + ports: + - containerPort: 8080 +``` + +## IPSec E2E 测试 + +### 1. 基本连通性测试 + +该测试验证 IPSec 隧道的建立以及加密通信的正确性。 + +#### 步骤 + +1. 部署 `sleep` 和 `echo` 应用： + + ```bash + kubectl apply -f sleep.yaml + kubectl apply -f echo.yaml + ``` + +2. 验证应用之间的连通性： + + ```bash + kubectl exec -- curl http:// + ``` + + **预期输出：** + + ```plaintext + Hello version: v1, instance: echo- + ``` + +3. 检查 IPSec 状态： + + ```bash + ip xfrm state show + ``` + + **预期输出：** + + ```plaintext + src {{SRC_IP}} dst {{DST_IP}} + proto esp spi 0x{{SPI}} reqid 1 mode tunnel + replay-window 0 + output-mark 0xd0/0xffffffff + aead rfc4106(gcm(aes)) {{KEY}} 128 + anti-replay context: seq 0x0, oseq 0x0, bitmap 0x00000000 + sel src ::/0 dst ::/0 + ``` + +4. 检查 IPSec 策略： + + ```bash + ip xfrm policy show + ``` + + **预期输出：** + + ```plaintext + src ::/0 dst {{DST_SUBNET}} + dir out priority 0 + mark 0xe0/0xffffffff + tmpl src {{SRC_IP}} dst {{DST_IP}} + proto esp spi 0x{{SPI}} reqid 1 mode tunnel + ``` + +5. 使用 `tcpdump` 验证加密： + + ```bash + tcpdump -i any esp + ``` + + **预期输出：** 通信过程中应能看到 ESP 数据包。 + +### 2. 密钥轮换测试 + +该测试确保 PSK 更新机制的可靠性，并验证密钥变更期间的服务连续性。 + +#### 步骤 + +1. 记录初始 SPI： + + ```bash + ip xfrm state show + ``` + + **预期输出：** + + ```plaintext + src {{SRC_IP}} dst {{DST_IP}} + proto esp spi 0x{{INITIAL_SPI}} reqid 1 mode tunnel + aead rfc4106(gcm(aes)) {{INITIAL_KEY}} 128 + ``` + +2. 在应用之间持续发送流量： + + ```bash + kubectl exec -- curl http:// + ``` + +3. 更新预共享密钥： + + ```bash + kmeshctl secret create --key= + ``` + +4. 验证 xfrm 规则中的 SPI 和密钥已更新： + + ```bash + ip xfrm state show + ``` + + **预期输出：** + + ```plaintext + src {{SRC_IP}} dst {{DST_IP}} + proto esp spi 0x{{INITIAL_SPI + 1}} reqid 1 mode tunnel + aead rfc4106(gcm(aes)) {{NEW_KEY}} 128 + ``` + +5. 确认通信连续性与加密状态。 + +## Offload Authorization E2E 测试 + +### Authorization 测试统一步骤 + +1. 应用策略： + + ```bash + kubectl apply -f .yaml + ``` + +2. 测试连通性： + + ```bash + kubectl exec -- curl http:// + ``` + + **预期输出：** + + - **ALLOW 策略：** curl 命令应成功，HTTP 响应码应为 `200`。 + - **DENY 策略：** curl 命令应失败，且收不到响应。 + +### 策略示例 + +#### IP Authorization 策略 + +```yaml +apiVersion: security.istio.io/v1beta1 +kind: AuthorizationPolicy +metadata: + name: ip-allow-policy + namespace: test-ns1 +spec: + action: ALLOW + rules: + - from: + - source: + ipBlocks: + - "{{ALLOWED_IP}}" +``` + +#### Port Authorization 策略 + +```yaml +apiVersion: security.istio.io/v1beta1 +kind: AuthorizationPolicy +metadata: + name: port-allow-policy + namespace: test-ns1 +spec: + action: ALLOW + rules: + - to: + - operation: + ports: ["{{ALLOWED_PORT}}"] +``` + +#### Header Authorization 策略 + +```yaml +apiVersion: security.istio.io/v1beta1 +kind: AuthorizationPolicy +metadata: + name: header-allow-policy + namespace: test-ns1 +spec: + action: ALLOW + rules: + - when: + - key: request.headers["{{HEADER_NAME}}"] + values: ["{{HEADER_VALUE}}"] +``` + +#### Namespace Authorization 策略 + +```yaml +apiVersion: security.istio.io/v1beta1 +kind: AuthorizationPolicy +metadata: + name: namespace-allow-policy + namespace: test-ns1 +spec: + action: ALLOW + rules: + - from: + - source: + namespaces: ["{{SOURCE_NAMESPACE}}"] +``` + +#### Host Authorization 策略 + +```yaml +apiVersion: security.istio.io/v1beta1 +kind: AuthorizationPolicy +metadata: + name: host-allow-policy + namespace: test-ns1 +spec: + action: ALLOW + rules: + - to: + - operation: + hosts: ["{{TARGET_HOST}}"] +``` + +## 清理 + +测试完成后，清理相关资源： + +```bash +kubectl delete -f sleep.yaml +kubectl delete -f echo.yaml +kubectl delete authorizationpolicy --all -n test-ns1 +``` diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/developer-guide/website/create-blog.md b/i18n/zh/docusaurus-plugin-content-docs/current/developer-guide/website/create-blog.md new file mode 100644 index 000000000..f70250760 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/current/developer-guide/website/create-blog.md @@ -0,0 +1,240 @@ +--- +title: 创建博客 +sidebar_position: 3 +--- + +## 在 Docusaurus 中创建博客：完整指南 + +Docusaurus 是一款强大的静态站点生成器，内置博客功能，便于创建和分享博客文章。本指南将说明如何搭建博客、撰写文章、配置选项以及维护内容——面向初学者，易于上手。 + +### 1. Docusaurus 中的博客功能是什么？ + +Docusaurus 的博客功能允许你： + +- 以 Markdown 文件撰写博客文章。 +- 自动生成列出所有文章的博客索引页。 +- 为每篇博客文章创建独立页面。 +- 自定义博客的外观与行为。 + +非常适合分享项目更新、教程或任何基于时间的内容，且几乎无需额外配置。 + +### 2. 博客目录结构 + +在 Docusaurus 项目中，博客文章存放在 `blog/` 目录下。每篇文章是一个独立的 Markdown 文件，文件名通常包含发布日期和 slug（URL 友好的标题）。示例如下： + +```text +blog/ +├── 2023-10-05-my-first-post.md +└── 2023-10-06-another-post.md +``` + +- **日期**：`YYYY-MM-DD` 部分（例如 `2023-10-05`）决定文章的发布日期与排序。 +- **Slug**：日期之后的部分（例如 `my-first-post`）会成为 URL 的一部分（例如 `/blog/my-first-post`）。 + +你可以将所有文章放在 `blog/` 目录中，也可以使用子目录进行组织（对大多数情况而言，扁平结构已经足够）。 + +### 3. 撰写博客文章：Front Matter + +每篇博客文章都以 **front matter** 部分开头——位于文件顶部、由三连短横线（`---`）包围的 YAML 块。该部分包含文章的元数据。示例如下： + +```yaml +--- +title: My First Blog Post +date: 2023-10-05 +author: John Doe +tags: ["example", "blog"] +--- +``` + +关键字段包括： + +- **`title`**：文章标题，显示在文章页和博客索引中。 +- **`date`**：发布日期（必须与文件名中的日期一致）。 +- **`author`**：作者姓名（可选）。 +- **`tags`**：用于分类的标签列表（可选）。 + +Front matter 对于 Docusaurus 正确识别并展示你的文章至关重要。 + +### 4. 撰写博客正文 + +在 front matter 之后，使用 Markdown 撰写文章内容。Docusaurus 支持标准 Markdown 语法——标题、列表、链接、图片等。示例如下： + +```markdown +# My First Blog Post + +Welcome to my blog! + +## Why I Started This Blog + +I’m excited to share my experiences. Here’s why: + +- To document my progress +- To connect with others +- To learn from feedback + +## What’s Next? + +Look out for posts on: + +1. Project setup tips +2. Coding best practices +3. Fun experiments +``` + +Docusaurus 还支持 MDX，可让你在文章中加入 React 组件以实现交互元素（对初学者而言这是可选的）。 + +### 5. 配置博客 + +你可以通过编辑项目根目录下的 `docusaurus.config.js` 文件来自定义博客。博客设置通常定义在 `presets` 部分。示例如下： + +```javascript +module.exports = { + // ... + presets: [ + [ + "@docusaurus/preset-classic", + { + blog: { + path: "blog", // Directory for blog posts + routeBasePath: "blog", // URL path for the blog + blogTitle: "My Blog", // Blog page title + blogDescription: "Thoughts and updates on my project", // Blog description + postsPerPage: 10, // Posts per index page + showReadingTime: true, // Show reading time for posts + }, + }, + ], + ], +}; +``` + +关键选项： + +- **`path`**：博客文章存放路径（默认：`blog`）。 +- **`routeBasePath`**：博客的 URL 路径（例如 `/blog`）。 +- **`blogTitle`**：博客索引页显示的标题。 +- **`blogDescription`**：用于 SEO 与订阅源的简短描述。 +- **`postsPerPage`**：每个索引页显示的文章数量。 +- **`showReadingTime`**：是否显示每篇文章的预计阅读时间。 + +更多选项请参阅 [Docusaurus 博客文档](https://docusaurus.io/docs/blog)。 + +### 6. 将博客加入站点导航 + +为方便用户找到博客，可通过 `docusaurus.config.js` 在导航栏或页脚添加链接。 + +#### 导航栏示例 + +```javascript +module.exports = { + // ... + themeConfig: { + navbar: { + items: [ + { + to: "/blog", + label: "Blog", + position: "left", + }, + ], + }, + }, +}; +``` + +#### 页脚示例 + +```javascript +module.exports = { + // ... + themeConfig: { + footer: { + links: [ + { + title: "Links", + items: [ + { + label: "Blog", + to: "/blog", + }, + ], + }, + ], + }, + }, +}; +``` + +这样即可从站点任意位置访问博客。 + +### 7. 在本地预览博客 + +要查看博客效果，请启动开发服务器： + +```bash +npm start +``` + +或 + +```bash +yarn start +``` + +在浏览器中打开 `http://localhost:3000/blog` 即可查看博客索引。点击任意文章可查看其独立页面。 + +### 8. 博客管理最佳实践 + +随着博客内容增多，可按以下建议保持条理： + +- **文件命名**：坚持使用 `YYYY-MM-DD-title.md` 这类一致格式，以便按时间排序。 +- **标签**：在 front matter 中使用标签对相关文章分组。Docusaurus 会自动创建标签页（例如 `/blog/tags/example`）。 +- **内容结构**：保持文章主题聚焦，并使用标题提升可读性。 +- **更新维护**：定期检查 front matter（如日期、标签），确保准确无误。 + +### 9. 博客文章完整示例 + +以下是一篇完整的博客文章文件示例： + +```markdown +--- +title: My First Blog Post +date: 2023-10-05 +author: John Doe +tags: ["example", "blog"] +--- + +# My First Blog Post + +Hi everyone! + +## Why I’m Here + +I started this blog to: + +- Share my project journey +- Help others learn +- Get community input + +## Coming Soon + +Next, I’ll write about: + +1. Setting up tools +2. Writing clean code +3. Cool ideas to try + +Thanks for reading! +``` + +该文件包含 front matter 与 Markdown 内容，可直接由 Docusaurus 处理。 + +### 10. 后续步骤与资源 + +你现在已经拥有一个可运行的 Docusaurus 博客！若要进一步完善，可以探索： + +- 为订阅者添加 RSS 源。 +- 使用 CSS 自定义博客设计。 +- 使用 MDX 实现高级功能。 + +更多详情请访问 [Docusaurus 官方博客文档](https://docusaurus.io/docs/blog)。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/developer-guide/website/create-doc.md b/i18n/zh/docusaurus-plugin-content-docs/current/developer-guide/website/create-doc.md new file mode 100644 index 000000000..6874eae34 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/current/developer-guide/website/create-doc.md @@ -0,0 +1,248 @@ +--- +title: 创建文档 +sidebar_position: 1 +--- + +## 在 Docusaurus 中创建文档：初学者指南 + +Docusaurus 是一款可轻松构建文档网站的强大工具。它使用 Markdown 文件生成静态 HTML 页面，便于创建和维护项目文档。本指南将介绍在 Docusaurus 中创建文档所需了解的全部内容，从理解目录结构到配置侧边栏导航。 + +### 1. 理解 Docusaurus 目录结构 + +创建 Docusaurus 项目时，会生成特定的目录结构来组织站点。与文档相关的关键目录和文件包括： + +- **`docs/`**：存放所有文档文件。该目录中的每个文件都是 Markdown 文件（扩展名为 `.md` 或 `.mdx`），将被转换为文档站点上的一个页面。 + +- **`docusaurus.config.js`**：Docusaurus 站点的主配置文件，控制站点标题、导航等设置。 + +- **`sidebars.js`**（可选）：用于手动配置文档的侧边栏导航。 + +- **`static/`**：存放静态资源（如图片），可在文档中引用。 + +例如，典型的 Docusaurus 项目可能如下所示： + +```text +my-docusaurus-site/ +├── docs/ +│ ├── intro.md +│ └── getting-started.md +├── src/ +│ └── pages/ +├── static/ +│ └── img/ +├── docusaurus.config.js +├── package.json +└── sidebars.js +``` + +在此结构中，`docs/` 文件夹是所有文档文件的中心位置。你将在此处创建和存放文档。 + +### 2. 文档开头的参数（Front Matter） + +在 Docusaurus 中，每个 Markdown 文件顶部都可以有可选的 **front matter** 部分。Front matter 使用 YAML 格式，并由三连短横线（`---`）包围。它提供文档的元数据，便于自定义行为与外观。Front matter 中常见的参数（字段）包括： + +- **`id`**：文档的唯一标识符。未指定时，默认为不含扩展名的文件名（例如 `my-doc.md` 对应 `my-doc`）。 +- **`title`**：文档标题，显示在侧边栏和页面标题中。若省略，Docusaurus 会使用文件中的第一个标题。 +- **`slug`**：文档的自定义 URL 路径（例如 `/my-custom-url`）。 +- **`tags`**：用于分类文档的关键词。 + +以下是 front matter 示例： + +```yaml +--- +id: my-doc +title: My Document +slug: /my-custom-url +tags: + - example + - documentation +--- +``` + +该 front matter 告诉 Docusaurus： + +- 文档的唯一 ID 为 `my-doc`。 +- 标题为 “My Document”。 +- URL 路径为 `/my-custom-url`，而非默认的 `/docs/my-doc`。 +- 标签为 “example” 和 “documentation”。 + +Front matter 是可选的，但强烈建议使用，以便更好地控制文档。 + +### 3. 目录结构如何影响路径与侧边栏导航 + +`docs/` 目录内的文件夹结构同时决定文档的 URL 路径和侧边栏导航。 + +- **URL 路径**：默认情况下，文件夹结构会成为文档 URL 的一部分。例如： + + - `docs/intro.md` → `/docs/intro` + - `docs/architecture/overview.md` → `/docs/architecture/overview` + 你可以通过 front matter 中的 `slug` 参数覆盖该行为。 + +- **侧边栏导航**：Docusaurus 可根据文件夹结构自动生成侧边栏。`docs/` 下的每个子文件夹都会成为侧边栏中的一个分类，该文件夹内的文件则成为该分类下的链接。例如： + + ```text + docs/ + ├── intro.md + └── architecture/ + ├── overview.md + └── components.md + ``` + + 该结构可能生成如下侧边栏： + + - Intro + - Architecture + - Overview + - Components + + 文件夹名称（例如 `architecture`）不会自动成为分类名称，除非另行配置。你可以使用侧边栏配置文件自定义此行为。 + +#### `_category_.json` 文件 + +在子文件夹中，你可以添加名为 `_category_.json` 的文件，以配置该文件夹在侧边栏中的显示方式。该文件定义分类属性。示例如下： + +```json +{ + "label": "Architecture", + "position": 3, + "link": { + "type": "generated-index" + } +} +``` + +- **`label`**：侧边栏中该分类显示的名称（例如 “Architecture”）。 +- **`position`**：该分类在侧边栏中的顺序（例如 3 表示它是第三项）。 +- **`link`**：定义点击分类时的行为。值 `"type": "generated-index"` 告诉 Docusaurus 为该分类自动生成索引页，列出文件夹中的所有文档（例如 `overview.md` 和 `components.md`）。 + +该文件让你能够精细控制该特定文件夹的侧边栏表现。 + +### 4. 创建文档的分步流程（适合初学者） + +如果你是 Docusaurus 新手，请按以下步骤创建第一份文档： + +1. **搭建 Docusaurus**： + + - 在终端中运行以下命令安装 Docusaurus： + + ```bash + npx create-docusaurus@latest my-site classic + ``` + + - 这会使用 classic 模板在 `my-site` 文件夹中创建新的 Docusaurus 站点。 + - 进入项目目录： + + ```bash + cd my-site + ``` + +2. **进入 Docs 文件夹**： + + - 打开项目目录中的 `docs/` 文件夹（例如 `my-site/docs/`）。 + +3. **创建 Markdown 文件**： + + - 使用文本编辑器新建文件，例如 `my-doc.md`。 + +4. **添加 Front Matter（可选）**： + + - 在文件顶部添加如下元数据： + + ```yaml + --- + id: my-doc + title: My Document + --- + ``` + +5. **撰写内容**： + + - 在 front matter 下方使用 Markdown 撰写文档。例如： + + ```markdown + # My Document + + Welcome to my first Docusaurus document! + + ## Features + + - Easy to use + - Highly customizable + ``` + +6. **用文件夹组织（可选）**： + + - 若要归类相关文档，可创建子文件夹（例如 `docs/features/`），并将文件移入或在其中创建（例如 `features/my-doc.md`）。 + +7. **配置侧边栏（可选）**： + + - 若使用自动侧边栏生成，Docusaurus 会依据你的文件夹结构。 + - 若要自定义分类，可在子文件夹中添加 `_category_.json` 文件。例如，在 `docs/features/` 中： + + ```json + { + "label": "Features", + "position": 2, + "link": { + "type": "generated-index" + } + } + ``` + + - 也可以编辑根目录下的 `sidebars.js` 进行手动侧边栏配置。 + +8. **预览站点**： + - 运行以下命令启动开发服务器： + + ```bash + npm start + ``` + + 或 + + ```bash + yarn start + ``` + + - 打开浏览器并访问 `http://localhost:3000` 查看站点。 + - 确认新文档已出现，且侧边栏反映了你的结构。 + +### 5. `.md` 文件示例 + +以下是你可能创建的完整 Markdown 文件示例： + +```markdown +--- +id: architecture-overview +title: Architecture Overview +slug: /architecture +tags: + - architecture + - overview +--- + +# Architecture Overview + +This document provides an overview of the system's architecture. + +## Components + +- **Frontend**: Built with React. +- **Backend**: Powered by Node.js. + +## Design Principles + +- Modularity +- Scalability +``` + +- Front matter 设置了 ID、标题、自定义 URL 和标签。 +- 正文使用 Markdown 组织结构并提升可读性。 + +### 6. 更多资源 + +有关在 Docusaurus 中创建和自定义文档的更多详情，请访问官方文档： + +- [https://docusaurus.io/docs/create-doc](https://docusaurus.io/docs/create-doc) + +本指南涵盖了基础知识，而 Docusaurus 还提供版本管理、多语言支持等高级功能。当你逐渐熟悉后，可以探索这些功能以完善文档站点。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/developer-guide/website/versioning-doc.md b/i18n/zh/docusaurus-plugin-content-docs/current/developer-guide/website/versioning-doc.md new file mode 100644 index 000000000..6890ef7e3 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/current/developer-guide/website/versioning-doc.md @@ -0,0 +1,361 @@ +--- +title: 版本管理 +sidebar_position: 2 +--- + +# 在 Docusaurus 中进行文档版本管理：完整指南 + +Docusaurus 内置了强大的文档版本管理支持，这对持续演进的项目至关重要。版本管理使你能够维护多份文档，确保用户可以访问与其使用的软件版本相对应的信息。本文档将引导你完成在 Docusaurus 中设置、管理和优化版本化文档的全过程。 + +--- + +## 1. 理解 Docusaurus 中的版本管理 + +Docusaurus 提供了一套直观的文档版本管理系统： + +- **当前版本（Current Version）**：这是最新、正在积极维护的文档版本，存放在 `docs/` 文件夹中。它通常代表 “Next” 版本或尚未发布的最新变更。 +- **已版本化文档（Versioned Docs）**：这些是文档在特定时间点的快照，通常与软件发布绑定。它们存放在名为 `versioned_docs/version-/` 的文件夹中，例如版本 1.0 对应 `versioned_docs/version-1.0/`。 + +例如： + +```text +// Project directory structure with versioning +my-docusaurus-project/ +├── docs/ # Current version documentation +├── versioned_docs/ # All versioned documentation +│ ├── version-1.0/ # Version 1.0 documentation +│ └── version-1.1/ # Version 1.1 documentation +├── versioned_sidebars/ # Sidebars for each version +│ ├── version-1.0-sidebars.json +│ └── version-1.1-sidebars.json +└── versions.json # List of all available versions +``` + +每套已版本化文档都是创建该版本时 `docs/` 文件夹的完整副本。 + +--- + +## 2. 设置版本管理 + +要在 Docusaurus 中开始文档版本管理，请按以下步骤操作： + +### 步骤 1：创建第一个版本 + +当你准备发布软件新版本时，为当前文档创建版本化快照： + +- 在终端中运行以下命令： + +```bash +# File: terminal command +npm run docusaurus docs:version +``` + +或 + +```bash +# File: terminal command +yarn docusaurus docs:version +``` + +将 `` 替换为你期望的版本号，例如 `1.0`。 + +- **会发生什么**： + - Docusaurus 将整个 `docs/` 文件夹复制到 `versioned_docs/version-1.0/`。 + - 它会更新跟踪所有已版本化文档的 `versions.json` 文件。 + +创建版本 1.0 后的 `versions.json` 示例： + +```json +// File: versions.json +[ + "1.0" +] +``` + +### 步骤 2：自定义版本标签 + +默认情况下，版本号（例如 “1.0”）会显示在侧边栏和版本选择器中。你可以在 `docusaurus.config.js` 中自定义这些标签： + +```javascript +// File: docusaurus.config.js +module.exports = { + // ... other configuration + themeConfig: { + // ... other theme configuration + docs: { + sidebar: { + versionLabels: { + '1.0': 'Version 1.0 (Legacy)', + '1.1': 'Version 1.1', + 'current': 'Next (Unreleased)' + }, + }, + }, + }, +}; +``` + +--- + +## 3. 管理已版本化文档 + +版本管理设置完成后，可按如下方式管理文档： + +### 更新文档 + +- **当前版本**：编辑 `docs/` 文件夹中的文件，以反映最新变更与功能。 +- **已版本化文档**：若要更新特定版本（例如修正错误或澄清说明），请修改 `versioned_docs/version-/` 中的文件。 + +**注意**：对已版本化文档的修改应限于小幅修复。重大更新应放入当前版本（`docs/`）。 + +### 添加新版本 + +发布新的软件版本时： + +```bash +# File: terminal command +# 1. Update docs/ folder with latest content +# 2. Run the versioning command +npm run docusaurus docs:version 2.0 +``` + +这会在 `versioned_docs/version-2.0/` 中创建新快照，并更新 `versions.json`： + +```json +// File: versions.json (after adding version 2.0) +[ + "2.0", + "1.0" +] +``` + +### 移除版本 + +要删除某个版本： + +```bash +# File: terminal command +# 1. Remove the version folder +rm -rf versioned_docs/version-1.0 +rm -rf versioned_sidebars/version-1.0-sidebars.json + +# 2. Update versions.json manually +``` + +编辑 `versions.json` 以移除该版本： + +```json +// File: versions.json (after removing version 1.0) +[ + "2.0" +] +``` + +--- + +## 4. 为已版本化文档配置侧边栏 + +Docusaurus 会自动处理每个版本的侧边栏，但你也可以按需自定义。 + +### 自动生成侧边栏 + +创建版本时，Docusaurus 会自动创建侧边栏配置： + +```json +// File: versioned_sidebars/version-1.0-sidebars.json (automatically generated) +{ + "version-1.0/docs": [ + { + "type": "category", + "label": "Getting Started", + "items": [ + { + "type": "doc", + "id": "version-1.0/intro" + }, + { + "type": "doc", + "id": "version-1.0/installation" + } + ] + } + ] +} +``` + +### 手动配置侧边栏 + +若需要更多控制，可以直接修改已版本化的侧边栏文件： + +```javascript +// File: versioned_sidebars/version-1.0-sidebars.json (customized) +{ + "version-1.0/docs": [ + { + "type": "category", + "label": "Getting Started", + "items": [ + { + "type": "doc", + "id": "version-1.0/intro" + }, + { + "type": "doc", + "id": "version-1.0/installation" + } + ] + }, + { + "type": "category", + "label": "Advanced Topics", + "items": [ + { + "type": "doc", + "id": "version-1.0/advanced/configuration" + } + ] + } + ] +} +``` + +--- + +## 5. 链接到已版本化文档 + +### 版本下拉组件 + +Docusaurus 会在站点导航中加入版本选择下拉菜单： + +```jsx +// File: src/theme/Navbar.js (automatically handled by Docusaurus) +import React from 'react'; +import VersionsDropdown from '@theme/VersionsDropdown'; + +function Navbar() { + return ( + + ); +} +``` + +### 创建指向特定版本的自定义链接 + +在文档中，你可以链接到特定版本： + +```markdown + + +Check our [installation guide for v1.0](/docs/1.0/installation) or the [latest installation guide](/docs/installation). +``` + +--- + +## 6. 版本管理最佳实践 + +- **版本命名**：使用语义化版本号（例如 1.0、1.1、2.0）以保持清晰。 + + ```text + // Recommended version naming + 1.0, 1.1, 2.0 // ✓ Semantic versioning + + // Not recommended + stable, beta, old // ✗ Ambiguous naming + ``` + +- 管理版本标签与可见性的**配置示例**： + + ```javascript + // File: docusaurus.config.js + module.exports = { + // ... other configuration + presets: [ + [ + '@docusaurus/preset-classic', + { + docs: { + // ... other docs configuration + lastVersion: 'current', + versions: { + current: { + label: 'Next', + path: 'next', + }, + '2.0': { + label: '2.0', + path: '2.0', + }, + '1.0': { + label: '1.0 (Legacy)', + path: '1.0', + banner: 'unmaintained', // Adds a banner indicating this version is no longer maintained + }, + }, + }, + }, + ], + ], + }; + ``` + +--- + +## 7. 示例场景 + +我们以一个有两个发布版本（1.0 和 2.0）的软件项目为例，走一遍版本管理流程。 + +```bash +# File: terminal commands for versioning workflow +# Initial setup - create version 1.0 +npm run docusaurus docs:version 1.0 + +# Result: +# - versioned_docs/version-1.0/ contains a snapshot of docs/ +# - versioned_sidebars/version-1.0-sidebars.json is created +# - versions.json now includes "1.0" + +# Later - update docs/ with changes for version 2.0 and create version 2.0 +npm run docusaurus docs:version 2.0 + +# Result: +# - versioned_docs/version-2.0/ is created +# - versioned_sidebars/version-2.0-sidebars.json is created +# - versions.json now includes "2.0" and "1.0" +# - docs/ becomes the "Next" version +``` + +最终项目结构： + +```text +# File: Project structure after versioning +my-docusaurus-project/ +├── docs/ # Current "Next" version +├── versioned_docs/ +│ ├── version-2.0/ # Version 2.0 documentation +│ └── version-1.0/ # Version 1.0 documentation +├── versioned_sidebars/ +│ ├── version-2.0-sidebars.json +│ └── version-1.0-sidebars.json +└── versions.json # ["2.0", "1.0"] +``` + +结果是用户可以通过下拉菜单轻松在版本间导航的站点： + +- **Next**：最新未发布变更 +- **2.0**：版本 2.0 的文档 +- **1.0 (Legacy)**：版本 1.0 的文档 + +--- + +## 8. 更多资源 + +更多深入信息，请参阅 Docusaurus 官方文档： + +- [https://docusaurus.io/docs/versioning](https://docusaurus.io/docs/versioning) + +--- + +本指南提供了在 Docusaurus 中创建和管理版本化文档所需的全部内容。遵循这些步骤，即可确保用户能够访问与其软件版本匹配的正确文档。祝文档编写顺利！ diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/developer-guide/workflow-automation-guide.md b/i18n/zh/docusaurus-plugin-content-docs/current/developer-guide/workflow-automation-guide.md new file mode 100644 index 000000000..f27cb5e02 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/current/developer-guide/workflow-automation-guide.md @@ -0,0 +1,68 @@ +--- +sidebar_position: 3 +title: 自动化工作流 +--- + +# 项目文档：自动化工作流 + +本文档概述 Kmesh 项目的自动化工作流，旨在提升文档质量并简化版本管理流程。 + +## 1. kmeshctl 同步工作流 + +**目的：** 通过 Pull Request（PR）自动将 kmeshctl CLI 文档从 kmesh 仓库同步到 kmesh-website 仓库。 + +**工作流触发条件：** 向 kmesh 仓库的 main 分支推送，且变更发生在 `docs/ctl/` 目录时。 + +### 步骤 + +1. **检出仓库：** 工作流会检出 kmesh-website 和 kmesh 两个仓库。 +2. **使用 rsync 同步：** 使用 rsync 命令将 kmesh 中的 `docs/ctl/` 目录同步到 kmesh-website 的 docs/kmeshctl/ 目录。`--delete` 标志确保已删除的文件也会被移除。 +3. **创建 Pull Request：** 若检测到变更，工作流会提交这些变更，并使用 `peter-evans/create-pull-request` action 在 kmesh-website 仓库中创建 PR。分支名包含时间戳，以确保唯一性并避免冲突。 + +### 维护说明 + +- **Secrets：** `WEBSITE_PAT` secret 必须对 `kmesh-net/kmesh` 和 kmesh-net/website 仓库都具有写权限。 +- **路径变更：** 若源目录或目标目录路径发生变化，请更新工作流中的 `KMESH_CTL_DIR` 和 `WEBSITE_KMESHCTL_DIR` 变量。 + +## 2. Docusaurus 版本管理与 i18n（中文）处理 + +Docusaurus 版本管理系统会基于源 docs/ 目录的内容创建新版本。执行 docusaurus docs:version 命令时，它会自动生成一个新的版本化文件夹（例如 `versioned_docs/version-X.Y.Z/`），其中包含全部英文文档。 + +### 中文文档（i18n）版本管理 + +- Docusaurus 版本管理命令不会自动为位于 `i18n/zh/docusaurus-plugin-content-docs/` 的中文翻译创建对应的版本化文件夹。 +- 因此，创建新版本后，不会存在 `i18n/zh/docusaurus-plugin-content-docs/version-X.Y.Z/` 文件夹。 +- 这会导致已选择中文语言的用户在导航到新版本时出现 “Page Not Found” 错误。 + +### 解决方案：自定义 404 页面 + +- 为提供流畅的用户体验，已实现自定义 404 页面。 +- 当中文用户遇到新版本缺失页面时，会看到一个有用的错误页面。 +- 该页面包含醒目按钮，方便用户跳转到所请求文档的英文版，或返回首页。 +- 此方法确保即使用户所需的最新版本中文翻译尚未提供，也始终能够获取所需信息。 + +该方案在保持文档及时更新与多语言站点实际约束之间取得平衡——翻译工作可能落后于英文新内容的发布。 + +### 维护说明 + +- 该工作流依赖 `GITHUB_TOKEN` 创建 PR。 +- 请确保使用 `npm install` 命令，因为没有可用的 `package-lock.json` 文件。 + +## 3. 中文语法检查工作流 + +**目的：** 自动检查中文文档的语法与拼写。 + +**工作流触发条件：** 向 main 分支推送或发起 pull request，且变更发生在 `docs/cn/zh/` 目录下的文件时。 + +### 步骤 + +- **检出与设置：** 工作流检出代码并设置 Python 环境。 +- **安装依赖：** 安装 language-tool-python 包。 +- **运行语法检查：** 使用 LanguageTool 库仅扫描 `docs/cn/zh/` 目录及其子目录中的 .md 文件，检查中文（zh-CN）内容。 +- **报告问题：** 脚本会针对发现的问题提供详细、带颜色标记的输出，包括文件、行号、错误类型（拼写、语法、风格）、上下文与建议，并创建 GitHub warning 注解。 + +### 维护说明 + +- 该工作流较为稳健，并包含初始化 LanguageTool 服务时的重试机制。 +- 能妥善处理编码错误。 +- 输出设计便于开发者阅读，会对错误进行分类并提供可操作的反馈。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/kmeshctl/kmeshctl.md b/i18n/zh/docusaurus-plugin-content-docs/current/kmeshctl/kmeshctl.md new file mode 100644 index 000000000..62752670d --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/current/kmeshctl/kmeshctl.md @@ -0,0 +1,19 @@ +## kmeshctl + +用于运维和调试 Kmesh 的命令行工具 + +### 选项 + +```bash + -h, --help help for kmeshctl +``` + +### 另请参阅 + +* [kmeshctl authz](kmeshctl_authz.md) - 管理用于 Kmesh 授权卸载的 xdp authz eBPF 程序 +* [kmeshctl dump](kmeshctl_dump.md) - 转储内核原生模式或双引擎模式的配置 +* [kmeshctl log](kmeshctl_log.md) - 获取或设置 kmesh-daemon 的日志级别 +* [kmeshctl monitoring](kmeshctl_monitoring.md) - 按需控制 Kmesh 监控功能的开启与关闭 +* [kmeshctl secret](kmeshctl_secret.md) - 使用 secrets 管理 IPsec 的密钥配置数据 +* [kmeshctl version](kmeshctl_version.md) - 打印构建版本信息 +* [kmeshctl waypoint](kmeshctl_waypoint.md) - 管理 waypoint 配置 diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/kmeshctl/kmeshctl_accesslog.md b/i18n/zh/docusaurus-plugin-content-docs/current/kmeshctl/kmeshctl_accesslog.md new file mode 100644 index 000000000..32976e624 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/current/kmeshctl/kmeshctl_accesslog.md @@ -0,0 +1,27 @@ +## kmeshctl accesslog + +启用或禁用 Kmesh 的访问日志（accesslog） + +```bash +kmeshctl accesslog [flags] +``` + +### 示例 + +```bash +# 启用 Kmesh 的访问日志： +kmeshctl accesslog enable + +# 禁用 Kmesh 的访问日志： +kmeshctl accesslog disable +``` + +### 选项 + +```bash + -h, --help help for accesslog +``` + +### 另请参阅 + +* [kmeshctl](kmeshctl.md) - 用于运维和调试 Kmesh 的命令行工具 diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/kmeshctl/kmeshctl_authz.md b/i18n/zh/docusaurus-plugin-content-docs/current/kmeshctl/kmeshctl_authz.md new file mode 100644 index 000000000..35796cf4d --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/current/kmeshctl/kmeshctl_authz.md @@ -0,0 +1,16 @@ +## kmeshctl authz + +管理用于 Kmesh 授权卸载的 xdp authz eBPF 程序 + +### 选项 + +```bash + -h, --help help for authz +``` + +### 另请参阅 + +* [kmeshctl](kmeshctl.md) - 用于运维和调试 Kmesh 的命令行工具 +* [kmeshctl authz disable](kmeshctl_authz_disable.md) - 禁用用于 Kmesh 授权卸载的 xdp authz eBPF 程序 +* [kmeshctl authz enable](kmeshctl_authz_enable.md) - 启用用于 Kmesh 授权卸载的 xdp authz eBPF 程序 +* [kmeshctl authz status](kmeshctl_authz_status.md) - 显示当前授权状态 diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/kmeshctl/kmeshctl_authz_disable.md b/i18n/zh/docusaurus-plugin-content-docs/current/kmeshctl/kmeshctl_authz_disable.md new file mode 100644 index 000000000..da180c196 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/current/kmeshctl/kmeshctl_authz_disable.md @@ -0,0 +1,24 @@ +## kmeshctl authz disable + +禁用用于 Kmesh 授权卸载的 xdp authz eBPF 程序 + +```bash +kmeshctl authz disable [podNames...] [flags] +``` + +### 示例 + +```bash +kmeshctl authz disable +kmeshctl authz disable pod1 pod2 +``` + +### 选项 + +```bash + -h, --help help for disable +``` + +### 另请参阅 + +* [kmeshctl authz](kmeshctl_authz.md) - 管理用于 Kmesh 授权卸载的 xdp authz eBPF 程序 diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/kmeshctl/kmeshctl_authz_enable.md b/i18n/zh/docusaurus-plugin-content-docs/current/kmeshctl/kmeshctl_authz_enable.md new file mode 100644 index 000000000..af45d1a54 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/current/kmeshctl/kmeshctl_authz_enable.md @@ -0,0 +1,24 @@ +## kmeshctl authz enable + +启用用于 Kmesh 授权卸载的 xdp authz eBPF 程序 + +```bash +kmeshctl authz enable [podNames...] [flags] +``` + +### 示例 + +```bash +kmeshctl authz enable +kmeshctl authz enable pod1 pod2 +``` + +### 选项 + +```bash + -h, --help help for enable +``` + +### 另请参阅 + +* [kmeshctl authz](kmeshctl_authz.md) - 管理用于 Kmesh 授权卸载的 xdp authz eBPF 程序 diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/kmeshctl/kmeshctl_authz_status.md b/i18n/zh/docusaurus-plugin-content-docs/current/kmeshctl/kmeshctl_authz_status.md new file mode 100644 index 000000000..a3536fb7b --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/current/kmeshctl/kmeshctl_authz_status.md @@ -0,0 +1,24 @@ +## kmeshctl authz status + +显示当前授权状态 + +```bash +kmeshctl authz status [podNames...] [flags] +``` + +### 示例 + +```bash +kmeshctl authz status +kmeshctl authz status pod1 pod2 +``` + +### 选项 + +```bash + -h, --help help for status +``` + +### 另请参阅 + +* [kmeshctl authz](kmeshctl_authz.md) - 管理用于 Kmesh 授权卸载的 xdp authz eBPF 程序 diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/kmeshctl/kmeshctl_dump.md b/i18n/zh/docusaurus-plugin-content-docs/current/kmeshctl/kmeshctl_dump.md new file mode 100644 index 000000000..9ab6c6a7e --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/current/kmeshctl/kmeshctl_dump.md @@ -0,0 +1,31 @@ +## kmeshctl dump + +转储内核原生模式或双引擎模式的配置 + +```bash +kmeshctl dump [flags] +``` + +### 示例 + +```bash +# 内核原生模式（表格输出）： +kmeshctl dump kernel-native + +# 双引擎模式（表格输出）： +kmeshctl dump dual-engine + +# 以原始 JSON 输出： +kmeshctl dump kernel-native -o json +``` + +### 选项 + +```bash + -h, --help help for dump + -o, --output string Output format: table or json (default "table") +``` + +### 另请参阅 + +* [kmeshctl](kmeshctl.md) - 用于运维和调试 Kmesh 的命令行工具 diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/kmeshctl/kmeshctl_log.md b/i18n/zh/docusaurus-plugin-content-docs/current/kmeshctl/kmeshctl_log.md new file mode 100644 index 000000000..0370e83a5 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/current/kmeshctl/kmeshctl_log.md @@ -0,0 +1,31 @@ +## kmeshctl log + +获取或设置 kmesh-daemon 的日志级别 + +```bash +kmeshctl log [flags] +``` + +### 示例 + +```bash +# 将默认日志记录器的级别设置为 "debug"： +kmeshctl log --set default:debug + +# 获取所有日志记录器的名称 +kmeshctl log + +# 获取默认日志记录器的级别： +kmeshctl log default +``` + +### 选项 + +```bash + -h, --help help for log + --set string Set the logger level (e.g., default:debug) +``` + +### 另请参阅 + +* [kmeshctl](kmeshctl.md) - 用于运维和调试 Kmesh 的命令行工具 diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/kmeshctl/kmeshctl_monitoring.md b/i18n/zh/docusaurus-plugin-content-docs/current/kmeshctl/kmeshctl_monitoring.md new file mode 100644 index 000000000..d40a60527 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/current/kmeshctl/kmeshctl_monitoring.md @@ -0,0 +1,50 @@ +## kmeshctl monitoring + +按需控制 Kmesh 监控功能的开启与关闭 + +```bash +kmeshctl monitoring [flags] +``` + +### 示例 + +```bash +# 启用/禁用 Kmesh 的访问日志： +kmeshctl monitoring --accesslog enable/disable + +# 启用/禁用由 bpf 生成的服务指标与访问日志： +kmeshctl monitoring --all enable/disable + +# 启用/禁用 workload 粒度指标： +kmeshctl monitoring --workloadMetrics enable/disable + +# 启用/禁用连接粒度指标： +kmeshctl monitoring --connectionMetrics enable/disable + +# 若要更改集群中所有 kmesh daemon 的监控功能： +# 在每个节点启用/禁用 Kmesh 的访问日志： +kmeshctl monitoring --accesslog enable/disable + +# 在每个节点启用/禁用 workload 粒度指标： +kmeshctl monitoring --workloadMetrics enable/disable + +# 在每个节点启用/禁用连接粒度指标： +kmeshctl monitoring --connectionMetrics enable/disable + +# 在每个节点启用/禁用由 bpf 生成的服务、workload 与连接指标及访问日志： +kmeshctl monitoring --all enable/disable +``` + +### 选项 + +```bash + --accesslog string Control accesslog enable or disable + --all string Control accesslog and services' and workloads' metrics enable or disable together + --connectionMetrics string Control connection granularity metrics enable or disable + -h, --help help for monitoring + --workloadMetrics string Control workload granularity metrics enable or disable +``` + +### 另请参阅 + +* [kmeshctl](kmeshctl.md) - 用于运维和调试 Kmesh 的命令行工具 diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/kmeshctl/kmeshctl_secret.md b/i18n/zh/docusaurus-plugin-content-docs/current/kmeshctl/kmeshctl_secret.md new file mode 100644 index 000000000..2010596b1 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/current/kmeshctl/kmeshctl_secret.md @@ -0,0 +1,30 @@ +## kmeshctl secret + +使用 secrets 管理 IPsec 的密钥配置数据 + +```bash +kmeshctl secret [flags] +``` + +### 示例 + +```bash +# 使用 kmeshctl secret 管理 IPsec 的密钥配置数据： +kmeshctl secret create or kmeshctl secret create --key=$(echo -n "{36-character user-defined key here}" | xxd -p -c 64) +kmeshctl secret get +kmeshctl secret delete + +``` + +### 选项 + +```bash + -h, --help help for secret +``` + +### 另请参阅 + +* [kmeshctl](kmeshctl.md) - 用于运维和调试 Kmesh 的命令行工具 +* [kmeshctl secret create](kmeshctl_secret_create.md) - 通过 kmeshctl 生成 IPsec 密钥与配置 +* [kmeshctl secret delete](kmeshctl_secret_delete.md) - 通过 kmeshctl 删除 IPsec 密钥与配置 +* [kmeshctl secret get](kmeshctl_secret_get.md) - 通过 kmeshctl 获取 IPsec 密钥与配置 diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/kmeshctl/kmeshctl_secret_create.md b/i18n/zh/docusaurus-plugin-content-docs/current/kmeshctl/kmeshctl_secret_create.md new file mode 100644 index 000000000..f680a894e --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/current/kmeshctl/kmeshctl_secret_create.md @@ -0,0 +1,27 @@ +## kmeshctl secret create + +通过 kmeshctl 生成 IPsec 密钥与配置 + +```bash +kmeshctl secret create [flags] +``` + +### 示例 + +```bash +# 使用随机 IPsec 密钥生成 IPsec 配置： +kmeshctl secret create +# 使用用户自定义密钥生成 IPsec 配置： +kmeshctl secret create --key=$(echo -n "{36-character user-defined key here}" | xxd -p -c 64) +``` + +### 选项 + +```bash + -h, --help help for create + -k, --key string key of the encryption +``` + +### 另请参阅 + +* [kmeshctl secret](kmeshctl_secret.md) - 使用 secrets 管理 IPsec 的密钥配置数据 diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/kmeshctl/kmeshctl_secret_delete.md b/i18n/zh/docusaurus-plugin-content-docs/current/kmeshctl/kmeshctl_secret_delete.md new file mode 100644 index 000000000..05aa39aa3 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/current/kmeshctl/kmeshctl_secret_delete.md @@ -0,0 +1,23 @@ +## kmeshctl secret delete + +通过 kmeshctl 删除 IPsec 密钥与配置 + +```bash +kmeshctl secret delete [flags] +``` + +### 示例 + +```bash +kmeshctl secret delete +``` + +### 选项 + +```bash + -h, --help help for delete +``` + +### 另请参阅 + +* [kmeshctl secret](kmeshctl_secret.md) - 使用 secrets 管理 IPsec 的密钥配置数据 diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/kmeshctl/kmeshctl_secret_get.md b/i18n/zh/docusaurus-plugin-content-docs/current/kmeshctl/kmeshctl_secret_get.md new file mode 100644 index 000000000..ec7ff80a5 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/current/kmeshctl/kmeshctl_secret_get.md @@ -0,0 +1,24 @@ +## kmeshctl secret get + +通过 kmeshctl 获取 IPsec 密钥与配置 + +```bash +kmeshctl secret get [flags] +``` + +### 示例 + +```bash +# 通过 kmeshctl 获取 IPsec 密钥与配置。结果将以 JSON 格式显示。 +kmeshctl secret get +``` + +### 选项 + +```bash + -h, --help help for get +``` + +### 另请参阅 + +* [kmeshctl secret](kmeshctl_secret.md) - 使用 secrets 管理 IPsec 的密钥配置数据 diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/kmeshctl/kmeshctl_version.md b/i18n/zh/docusaurus-plugin-content-docs/current/kmeshctl/kmeshctl_version.md new file mode 100644 index 000000000..10c6ee820 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/current/kmeshctl/kmeshctl_version.md @@ -0,0 +1,27 @@ +## kmeshctl version + +打印构建版本信息 + +```bash +kmeshctl version [flags] +``` + +### 示例 + +```bash +# 显示所有 kmesh 组件的版本 +kmeshctl version + +# 显示特定 kmesh daemon 的版本信息 +kmeshctl version +``` + +### 选项 + +```bash + -h, --help help for version +``` + +### 另请参阅 + +* [kmeshctl](kmeshctl.md) - 用于运维和调试 Kmesh 的命令行工具 diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/kmeshctl/kmeshctl_waypoint.md b/i18n/zh/docusaurus-plugin-content-docs/current/kmeshctl/kmeshctl_waypoint.md new file mode 100644 index 000000000..e3d20d97a --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/current/kmeshctl/kmeshctl_waypoint.md @@ -0,0 +1,42 @@ +## kmeshctl waypoint + +管理 waypoint 配置 + +### 简介 + +一组用于管理 waypoint 配置的命令 + +```bash +kmeshctl waypoint [flags] +``` + +### 示例 + +```bash + # 将 waypoint 应用到当前命名空间 + kmeshctl waypoint apply + + # 以 yaml 形式生成 waypoint + kmeshctl waypoint generate --namespace default + + # 列出指定命名空间中的所有 waypoint + kmeshctl waypoint list --namespace default +``` + +### 选项 + +```bash + -h, --help help for waypoint + --image string image of the waypoint + --name string name of the waypoint (default "waypoint") + -n, --namespace string Kubernetes namespace +``` + +### 另请参阅 + +* [kmeshctl](kmeshctl.md) - 用于运维和调试 Kmesh 的命令行工具 +* [kmeshctl waypoint apply](kmeshctl_waypoint_apply.md) - 应用 waypoint 配置 +* [kmeshctl waypoint delete](kmeshctl_waypoint_delete.md) - 删除 waypoint 配置 +* [kmeshctl waypoint generate](kmeshctl_waypoint_generate.md) - 生成 waypoint 配置 +* [kmeshctl waypoint list](kmeshctl_waypoint_list.md) - 列出受管的 waypoint 配置 +* [kmeshctl waypoint status](kmeshctl_waypoint_status.md) - 显示命名空间中 waypoint 的状态 diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/kmeshctl/kmeshctl_waypoint_apply.md b/i18n/zh/docusaurus-plugin-content-docs/current/kmeshctl/kmeshctl_waypoint_apply.md new file mode 100644 index 000000000..592d9d62d --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/current/kmeshctl/kmeshctl_waypoint_apply.md @@ -0,0 +1,47 @@ +## kmeshctl waypoint apply + +应用 waypoint 配置 + +### 简介 + +将 waypoint 配置应用到集群 + +```bash +kmeshctl waypoint apply [flags] +``` + +### 示例 + +```bash + # 将 waypoint 应用到当前命名空间 + kmeshctl waypoint apply + + # 将 waypoint 应用到指定命名空间并等待其就绪 + kmeshctl waypoint apply --namespace default --wait + + # 将 waypoint 应用到指定 pod + kmeshctl waypoint apply -n default --name reviews-v2-pod-waypoint --for workload +``` + +### 选项 + +```bash + --enroll-namespace If set, the namespace will be labeled with the waypoint name + --for string Specify the traffic type [all none service workload] for the waypoint + -h, --help help for apply + --overwrite Overwrite the existing Waypoint used by the namespace + -r, --revision string The revision to label the waypoint with + -w, --wait Wait for the waypoint to be ready +``` + +### 继承自父命令的选项 + +```bash + --image string image of the waypoint + --name string name of the waypoint (default "waypoint") + -n, --namespace string Kubernetes namespace +``` + +### 另请参阅 + +* [kmeshctl waypoint](kmeshctl_waypoint.md) - 管理 waypoint 配置 diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/kmeshctl/kmeshctl_waypoint_delete.md b/i18n/zh/docusaurus-plugin-content-docs/current/kmeshctl/kmeshctl_waypoint_delete.md new file mode 100644 index 000000000..e1c70c084 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/current/kmeshctl/kmeshctl_waypoint_delete.md @@ -0,0 +1,46 @@ +## kmeshctl waypoint delete + +删除 waypoint 配置 + +### 简介 + +从集群中删除 waypoint 配置 + +```bash +kmeshctl waypoint delete [flags] +``` + +### 示例 + +```bash + # 从默认命名空间删除 waypoint + kmeshctl waypoint delete + + # 按名称删除 waypoint（名称可通过 kmeshctl waypoint list 获取） + kmeshctl waypoint delete waypoint-name --namespace default + + # 按名称删除多个 waypoint + kmeshctl waypoint delete waypoint-name1 waypoint-name2 --namespace default + + # 删除指定命名空间中的所有 waypoint + kmeshctl waypoint delete --all --namespace default +``` + +### 选项 + +```bash + --all Delete all waypoints in the namespace + -h, --help help for delete +``` + +### 继承自父命令的选项 + +```bash + --image string image of the waypoint + --name string name of the waypoint (default "waypoint") + -n, --namespace string Kubernetes namespace +``` + +### 另请参阅 + +* [kmeshctl waypoint](kmeshctl_waypoint.md) - 管理 waypoint 配置 diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/kmeshctl/kmeshctl_waypoint_generate.md b/i18n/zh/docusaurus-plugin-content-docs/current/kmeshctl/kmeshctl_waypoint_generate.md new file mode 100644 index 000000000..e209bfdfd --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/current/kmeshctl/kmeshctl_waypoint_generate.md @@ -0,0 +1,41 @@ +## kmeshctl waypoint generate + +生成 waypoint 配置 + +### 简介 + +以 YAML 形式生成 waypoint 配置 + +```bash +kmeshctl waypoint generate [flags] +``` + +### 示例 + +```bash + # 以 yaml 形式生成 waypoint + kmeshctl waypoint generate --namespace default + + # 生成可为 default 命名空间中 service 流量处理的 waypoint + kmeshctl waypoint generate --for service -n default +``` + +### 选项 + +```bash + --for string Specify the traffic type [all none service workload] for the waypoint + -h, --help help for generate + -r, --revision string The revision to label the waypoint with +``` + +### 继承自父命令的选项 + +```bash + --image string image of the waypoint + --name string name of the waypoint (default "waypoint") + -n, --namespace string Kubernetes namespace +``` + +### 另请参阅 + +* [kmeshctl waypoint](kmeshctl_waypoint.md) - 管理 waypoint 配置 diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/kmeshctl/kmeshctl_waypoint_list.md b/i18n/zh/docusaurus-plugin-content-docs/current/kmeshctl/kmeshctl_waypoint_list.md new file mode 100644 index 000000000..02df9de8d --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/current/kmeshctl/kmeshctl_waypoint_list.md @@ -0,0 +1,40 @@ +## kmeshctl waypoint list + +列出受管的 waypoint 配置 + +### 简介 + +列出集群中受管的 waypoint 配置 + +```bash +kmeshctl waypoint list [flags] +``` + +### 示例 + +```bash + # 列出指定命名空间中的所有 waypoint + kmeshctl waypoint list --namespace default + + # 列出集群中的所有 waypoint + kmeshctl waypoint list -A +``` + +### 选项 + +```bash + -A, --all-namespaces List all waypoints in all namespaces + -h, --help help for list +``` + +### 继承自父命令的选项 + +```bash + --image string image of the waypoint + --name string name of the waypoint (default "waypoint") + -n, --namespace string Kubernetes namespace +``` + +### 另请参阅 + +* [kmeshctl waypoint](kmeshctl_waypoint.md) - 管理 waypoint 配置 diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/kmeshctl/kmeshctl_waypoint_status.md b/i18n/zh/docusaurus-plugin-content-docs/current/kmeshctl/kmeshctl_waypoint_status.md new file mode 100644 index 000000000..d664400df --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/current/kmeshctl/kmeshctl_waypoint_status.md @@ -0,0 +1,39 @@ +## kmeshctl waypoint status + +显示命名空间中 waypoint 的状态 + +### 简介 + +显示指定命名空间（未指定时为默认命名空间）中 waypoint 的状态 + +```bash +kmeshctl waypoint status [flags] +``` + +### 示例 + +```bash + # 显示默认命名空间中 waypoint 的状态 + kmeshctl waypoint status + + # 显示指定命名空间中 waypoint 的状态 + kmeshctl waypoint status --namespace foo +``` + +### 选项 + +```bash + -h, --help help for status +``` + +### 继承自父命令的选项 + +```bash + --image string image of the waypoint + --name string name of the waypoint (default "waypoint") + -n, --namespace string Kubernetes namespace +``` + +### 另请参阅 + +* [kmeshctl waypoint](kmeshctl_waypoint.md) - 管理 waypoint 配置 diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/transpot-layer/accesslog.md b/i18n/zh/docusaurus-plugin-content-docs/current/transpot-layer/accesslog.md new file mode 100644 index 000000000..f96fabe7e --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/current/transpot-layer/accesslog.md @@ -0,0 +1,40 @@ +--- +sidebar_position: 6 +title: 访问日志 +--- + +## 启用 Kmesh 访问日志 + +可使用 kmeshctl 启用或禁用 Kmesh accesslog。 + +请参阅 [Kmeshctl 监控指南](../developer-guide/Kmeshctl-usage/kmeshctl-monitoring.md) + +## Kmesh 生成的 TCP 访问日志详解 + +日志由 Kmesh daemon 在 TCP 连接生命周期的关键阶段生成： + +- 若启用了 `connectionMetrics`，则在连接处于活跃状态时按固定的 5 秒间隔生成。 + +- 在连接关闭时生成 + +访问日志字段说明： + +| 名称 | 描述 | +| -------------- | ---------------------------------------------------------------------------------------------- | +| src.addr | 源地址与端口，请求的源工作负载 | +| src.workload | 发起请求的 Pod 名称 | +| src.namespace | 源工作负载所属命名空间 | +| dst.addr | 目标地址与端口，请求的目标工作负载 | +| dst.service | 目标服务的主机名 | +| dst.workload | 接收请求的 Pod 名称 | +| dst.namespace | 目标工作负载所属命名空间 | +| direction | 流量方向。INBOUND 表示进入目标服务，OUTBOUND 表示离开源服务 | +| sent_bytes | 此连接发送的字节数 | +| received_bytes | 此连接接收的字节数 | +| duration | 此连接的持续时间 | + +示例如下： + +```bash +accesslog: 2025-04-24 08:54:40.971980208 +0000 UTC src.addr=10.244.2.79:41978, src.workload=ws-client, src.namespace=default, dst.addr=10.244.2.78:8080, dst.service=ws-server-service.default.svc.cluster.local, dst.workload=ws-server, dst.namespace=default, start_time=2025-04-24 08:53:50.919245381 +0000 UTC, direction=OUTBOUND, state=BPF_TCP_ESTABLISHED, sent_bytes=3, received_bytes=227, packet_loss=0, retransmissions=0, srtt=40515us, min_rtt=34us, duration=50052.734827ms +```