cherry pick #4464 to release-4.0 (#4786)

Signed-off-by: ti-srebot <ti-srebot@pingcap.com> Co-authored-by: Keke Yi <40977455+yikeke@users.noreply.github.com>
pingcap · Nov 2, 2020 · 3150e41 · 3150e41
1 parent 7d75f9a
commit 3150e41
Show file tree

Hide file tree

Showing 6 changed files with 49 additions and 24 deletions.
diff --git a/.circleci/config.yml b/.circleci/config.yml
@@ -34,12 +34,12 @@ jobs:
             markdownlint $(git diff-tree --name-only --no-commit-id -r upstream/release-4.0..HEAD -- '*.md' ':(exclude).github/*')
 
       - run:
-          name: "Check links"
+          name: "Check internal links"
           command: |
             scripts/verify-links.sh
 
       - run:
-          name: "Check link anchors"
+          name: "Check internal link anchors"
           command: |
             scripts/verify-link-anchors.sh
 

diff --git a/.github/workflows/link-check.yaml b/.github/workflows/link-check.yaml
@@ -0,0 +1,31 @@
+name: external-link-check
+
+on: [pull_request]
+
+jobs:
+  base:
+    runs-on: ubuntu-18.04
+    steps:
+      - name: Check out code
+        uses: actions/checkout@v2
+
+      # NOTE:
+      #  - the check process can be very fast,
+      #    but if `-c` is too large then `Too Many Requests (HTTP error 429)` may be reported from `https://github.com/*`.
+      #  - we hardcode `--document-root` to `/github/workspace` in the container now.
+      #  - we use `http://172.*` as sample addresses in some docs, so we need to exclude them.
+      - name: Check external links
+        id: lc
+        uses: peter-evans/link-checker@v1
+        with:
+          args: -c 32 -d /github/workspace -r -x "http://172.*|https://github.com/.*/pull/.*|https://github.com/.*/issues/.*|https://github.com/[^.\n]*$|http://127.0.0.1.*|http://localhost.*|http://.*:.*|https://static.googleusercontent.com/media/research.google.com/.*|.*.md" .
+
+      - name: Fail if there were external link errors
+        if: ${{ steps.lc.outputs.exit_code }}
+        run: |
+          echo "Please check the broken links reported in the previous step \"Check external links\"."
+          exit ${{ steps.lc.outputs.exit_code }}
+      # Debug via SSH if previous steps failed
+      #- name: Set up tmate session
+      #  if: ${{ failure() }}
+      #  uses: mxschmitt/action-tmate@v2
diff --git a/connectors-and-apis.md b/connectors-and-apis.md
@@ -14,7 +14,7 @@ TiDB 兼容 MySQL(5.6、5.7) 的所有连接器和 API，包括：
 + [MySQL Connector/Net](https://dev.mysql.com/doc/refman/5.7/en/connector-net-info.html)
 + [MySQL Connector/ODBC](https://dev.mysql.com/doc/refman/5.7/en/connector-odbc-info.html)
 + [MySQL Connector/Python](https://dev.mysql.com/doc/refman/5.7/en/connector-python-info.html)
-+ [MySQL C API](https://dev.mysql.com/doc/refman/5.7/en/c-api.html)
++ [MySQL C API](https://dev.mysql.com/doc/refman/5.7/en/c-api-info.html)
 + [MySQL PHP API](https://dev.mysql.com/doc/refman/5.7/en/apis-php-info.html)
 + [MySQL Perl API](https://dev.mysql.com/doc/refman/5.7/en/apis-perl.html)
 + [MySQL Python API](https://dev.mysql.com/doc/refman/5.7/en/apis-python.html)
@@ -35,7 +35,7 @@ Oracle 官方提供了以下 API，TiDB 可以兼容所有这些 API。
 
 ## 使用 MySQL C API 连接 TiDB
 
-如果使用 C 语言程序直接连接 TiDB，可以直接链接 libmysqlclient 库，使用 MySQL 的 [C API](https://dev.mysql.com/doc/refman/5.7/en/c-api.html)，这是最主要的一种 C 语言连接方式，被各种客户端和 API 广泛使用，包括 Connector/C。
+如果使用 C 语言程序直接连接 TiDB，可以直接链接 libmysqlclient 库，使用 MySQL 的 [C API](https://dev.mysql.com/doc/refman/5.7/en/c-api-info.html)，这是最主要的一种 C 语言连接方式，被各种客户端和 API 广泛使用，包括 Connector/C。
 
 ## 使用 MySQL 第三方 API 连接 TiDB
 
@@ -44,7 +44,7 @@ Oracle 官方提供了以下 API，TiDB 可以兼容所有这些 API。
 | Environment    | API                                      | Type                             | Notes                                    |
 | -------------- | ---------------------------------------- | -------------------------------- | ---------------------------------------- |
 | Ada            | GNU Ada MySQL Bindings                   | `libmysqlclient`                 | See [MySQL Bindings for GNU Ada](http://gnade.sourceforge.net/) |
-| C              | C API                                    | `libmysqlclient`                 | See [Section 27.8, “MySQL C API”](https://dev.mysql.com/doc/refman/5.7/en/c-api.html). |
+| C              | C API                                    | `libmysqlclient`                 | See [MySQL C API](https://dev.mysql.com/doc/refman/5.7/en/c-api-info.html). |
 | C++            | Connector/C++                            | `libmysqlclient`                 | See [MySQL Connector/C++ Developer Guide](https://dev.mysql.com/doc/connector-cpp/en/). |
 |                | MySQL++                                  | `libmysqlclient`                 | See [MySQL++ Web site](http://tangentsoft.net/mysql++/doc/). |
 |                | MySQL wrapped                            | `libmysqlclient`                 | See [MySQL wrapped](http://www.alhem.net/project/mysql/). |

diff --git a/resources/figma-quick-start-guide.md b/resources/figma-quick-start-guide.md
@@ -7,10 +7,6 @@ summary: 本文档介绍如何使用 Figma 绘制图片。
 
 [Figma](https://www.figma.com/) 是一款免费的在线绘图工具，支持多人实时协作，简单实用、易于上手，Windows 和 macOS 等平台均可使用。本文档介绍如何使用 Figma 绘制图片。
 
-## Figma 界面
-
-详情参见 [Figma 教程](https://help.figma.com/article/12-getting-familiar-with-figma)。
-
 ## Figma 快速上手
 
 执行以下步骤可使用 Figma 快速绘制图片。
@@ -70,7 +66,7 @@ summary: 本文档介绍如何使用 Figma 绘制图片。
 
 之后便可在这个 Frame 中开始绘图。
 
-### 第 4 步骤：绘制图片
+### 第 4 步：绘制图片
 
 建议将其他 Frame 中已有的图形复制、粘贴到新的 Frame 中，以便快速绘制图片。
 
@@ -114,10 +110,6 @@ summary: 本文档介绍如何使用 Figma 绘制图片。
 
 ![Corner Radius](/media/figma-guide/corner-radius.png)
 
-#### 其他操作
-
-参见 [Figma 用户指南](https://help.figma.com/category/9-getting-started)。
-
 ### 第 5 步：导出图片
 
 1. 选中待导出的 Frame，点击 **Export** 一栏的 **+**。
@@ -137,3 +129,5 @@ summary: 本文档介绍如何使用 Figma 绘制图片。
     ![Export Frame X](/media/figma-guide/export-frame-x.png)
 
 4. 设置图片名称时，使用**描述性**名称。名称中可包含小写字母、数字及短连线 `-`。**请勿使用大写字母、空格、下划线**。
+
+更多步骤见 Figma 官方文档。
diff --git a/sql-statements/sql-statement-admin.md b/sql-statements/sql-statement-admin.md
@@ -270,7 +270,7 @@ admin show ddl jobs 5 where state!='synced' and db_name='test';
 * `JOB_TYPE`：DDL 操作的类型。
 * `SCHEMA_STATE`：schema 的当前状态。如果 `JOB_TYPE` 是 `add index`，则为 index 的状态；如果是 `add column`，则为 column 的状态，如果是 `create table`，则为 table 的状态。常见的状态有以下几种：
     * `none`：表示不存在。一般 `drop` 操作或者 `create` 操作失败回滚后，会变为 `none` 状态。
-    * `delete only`、`write only`、`delete reorganization`、`write reorganization`：这四种状态是中间状态，在[Online, Asynchronous Schema Change in F1](http://static.googleusercontent.com/media/research.google.com/zh-CN//pubs/archive/41376.pdf) 论文中有详细说明，在此不再赘述。由于中间状态转换很快，一般操作中看不到这几种状态，只有执行 `add index` 操作时能看到处于 `write reorganization` 状态，表示正在添加索引数据。
+    * `delete only`、`write only`、`delete reorganization`、`write reorganization`：这四种状态是中间状态，在[Online, Asynchronous Schema Change in F1](https://static.googleusercontent.com/media/research.google.com/zh-CN//pubs/archive/41376.pdf) 论文中有详细说明，在此不再赘述。由于中间状态转换很快，一般操作中看不到这几种状态，只有执行 `add index` 操作时能看到处于 `write reorganization` 状态，表示正在添加索引数据。
     * `public`：表示存在且可用。一般 `create table` 和 `add index/column` 等操作完成后，会变为 `public` 状态，表示新建的 table/column/index 可以正常读写了。
 * `SCHEMA_ID`：执行 DDL 操作的数据库的 ID。
 * `TABLE_ID`：执行 DDL 操作的表的 ID。

diff --git a/tidb-troubleshooting-map.md b/tidb-troubleshooting-map.md
@@ -187,7 +187,7 @@ aliases: ['/docs-cn/stable/tidb-troubleshooting-map/','/docs-cn/v4.0/tidb-troubl
 - 4.2.1 `block-cache` 配置太大导致 OOM：
 
     - 在监控 **Grafana** -> **TiKV-details** 选中对应的 instance 后，查看 RocksDB 的 `block cache size` 监控来确认是否是该问题。
-    
+
     - 同时，请检查 `[storage.block-cache] capacity = # "1GB"` 参数是否设置合理，默认情况下 TiKV 的 `block-cache` 设置为机器总内存的 `45%`；在 container 部署时，需要显式指定该参数，因为 TiKV 获取的是物理机的内存，可能会超出 container 的内存限制。
 
 - 4.2.2 Coprocessor 收到大量大查询，返回的数据量太大，gRPC 的发送速度跟不上 Coprocessor 往外输出数据的速度，导致 OOM：
@@ -205,13 +205,13 @@ aliases: ['/docs-cn/stable/tidb-troubleshooting-map/','/docs-cn/v4.0/tidb-troubl
     - `level0 sst` 太多导致 stall，可以添加参数 `[rocksdb] max-sub-compactions = 2`（或者 `3`），加快 level0 sst 往下 compact 的速度。该参数的意思是将从 level0 到 level1 的 compaction 任务最多切成 `max-sub-compactions` 个子任务交给多线程并发执行，见案例 [case-815](https://github.com/pingcap/tidb-map/blob/master/maps/diagnose-case-study/case815.md)。
 
     - `pending compaction bytes` 太多导致 stall，磁盘 I/O 能力在业务高峰跟不上写入，可以通过调大对应 Column Family (CF) 的 `soft-pending-compaction-bytes-limit` 和 `hard-pending-compaction-bytes-limit` 参数来缓解：
-    
+
         - 如果 `pending compaction bytes` 达到该阈值，RocksDB 会放慢写入速度。默认值 64GB，`[rocksdb.defaultcf] soft-pending-compaction-bytes-limit = "128GB"`。
-        
+
         - 如果 `pending compaction bytes` 达到该阈值，RocksDB 会 stop 写入，通常不太可能触发该情况，因为在达到 `soft-pending-compaction-bytes-limit` 的阈值之后会放慢写入速度。默认值 256GB，`hard-pending-compaction-bytes-limit = "512GB"`<!--见案例 [case-275](https://github.com/pingcap/tidb-map/blob/master/maps/diagnose-case-study/case275.md) -->。
-        
+
         - 如果磁盘 IO 能力持续跟不上写入，建议扩容。如果磁盘的吞吐达到了上限（例如 SATA SSD 的吞吐相对 NVME SSD 会低很多）导致 write stall，但是 CPU 资源又比较充足，可以尝试采用压缩率更高的压缩算法来缓解磁盘的压力，用 CPU 资源换磁盘资源。
-        
+
         - 比如 default cf compaction 压力比较大，调整参数 `[rocksdb.defaultcf] compression-per-level = ["no", "no", "lz4", "lz4", "lz4", "zstd", "zstd"]` 改成 `compression-per-level = ["no", "no", "zstd", "zstd", "zstd", "zstd", "zstd"]`。
 
     - memtable 太多导致 stall。该问题一般发生在瞬间写入量比较大，并且 memtable flush 到磁盘的速度比较慢的情况下。如果磁盘写入速度不能改善，并且只有业务峰值会出现这种情况，可以通过调大对应 CF 的 `max-write-buffer-number` 来缓解：
@@ -252,7 +252,7 @@ aliases: ['/docs-cn/stable/tidb-troubleshooting-map/','/docs-cn/v4.0/tidb-troubl
 
 - 4.5.3 Append log 慢。TiKV Grafana 的 **Raft IO**/`append log duration` 比较高，通常情况下是由于写盘慢了，可以检查 RocksDB - Raft 的 `WAL Sync Duration max` 值来确认，否则可能[需要报 bug](https://github.com/tikv/tikv/issues/new?template=bug-report.md)。
 
-- 4.5.4 Raftstore 线程繁忙。TiKV Grafana 的 **Raft Propose**/`propose wait duration` 明显高于 `append log duration`。请查看以下情况： 
+- 4.5.4 Raftstore 线程繁忙。TiKV Grafana 的 **Raft Propose**/`propose wait duration` 明显高于 `append log duration`。请查看以下情况：
 
     - `[raftstore] store-pool-size` 配置是否过小（该值建议在 [1,5] 之间，不建议太大）。
     - 机器的 CPU 是不是不够。
@@ -392,7 +392,7 @@ aliases: ['/docs-cn/stable/tidb-troubleshooting-map/','/docs-cn/v4.0/tidb-troubl
 - 6.1.8 Pump 启动时报错 `fail to notify all living drainer`。
 
     - Pump 启动时需要通知所有 Online 状态的 Drainer，如果通知失败则会打印该错误日志。
-    
+
     - 可以使用 binlogctl 工具查看所有 Drainer 的状态是否有异常，保证 Online 状态的 Drainer 都在正常工作。如果某个 Drainer 的状态和实际运行情况不一致，则使用 binlogctl 修改状态，然后再重启 Pump。见案例 [fail-to-notify-all-living-drainer](/tidb-binlog/handle-tidb-binlog-errors.md#pump-启动时报错-fail-to-notify-all-living-drainer)。
 
 - 6.1.9 Drainer 报错 `gen update sqls failed: table xxx: row data is corruption []`。
@@ -480,7 +480,7 @@ aliases: ['/docs-cn/stable/tidb-troubleshooting-map/','/docs-cn/v4.0/tidb-troubl
     - 原因 2：如果目标数据库的校验和全是 0，表示没有发生任何导入，有可能是集群太忙无法接收任何数据。
 
     - 原因 3：如果数据源是由机器生成而不是从 Mydumper 备份的，需确保数据符合表的限制，例如：
-    
+
         - 自增 (AUTO_INCREMENT) 的列需要为正数，不能为 0。
         - 单一键和主键 (UNIQUE and PRIMARY KEYs) 不能有重复的值。
 
@@ -527,7 +527,7 @@ aliases: ['/docs-cn/stable/tidb-troubleshooting-map/','/docs-cn/v4.0/tidb-troubl
     - `wait response is cancelled`。请求发送到 TiKV 后超时未收到 TiKV 响应。需要排查对应地址 TiKV 的响应时间和对应 Region 在当时的 PD 和 KV 日志，确定为什么 KV 未及时响应。
 
 - 7.1.5 distsql.go 报 `inconsistent index`。数据索引疑似发生不一致，首先对报错的信息中 index 所在表执行 `admin check table <TableName>` 命令，如果检查失败，则先通过命令关闭 GC，然后[报 bug](https://github.com/pingcap/tidb/issues/new?labels=type%2Fbug&template=bug-report.md)。
-   
+
     ```sql
     begin;
     update mysql.tidb set variable_value='72h' where variable_name='tikv_gc_life_time';