https://vvsxmja.github.io VVsxmja's Blog Blog 2024-08-26T00:00:00.000Z https://github.com/jpmonette/feed VVsxmja's Blog Blog https://vvsxmja.github.io/img/favicon.ico <![CDATA[用 Giscus 给 Docusaurus 博客增加评论区]]> https://vvsxmja.github.io/2024/08/26/giscus-as-blog-comment-system 2024-08-26T00:00:00.000Z 使用 Giscus 为你在 GitHub 上的博客添加一个评论区，同时尽量少地引入 GitHub 以外的第三方。

顺便介绍了通过 Docusaurus 的 API ，在切换博客的亮/暗模式时，同步切换 Giscus 主题的方式。

我想给我的博客增加一个评论区了。

既然我的博客文章全部存储 GitHub 上，我希望它的评论系统也能尽量基于 GitHub ，尽量不要引入 GitHub 之外的第三方。

选择 Giscus 的原因是 Giscus 以 GitHub Discussion 作为唯一数据源，而且评论者身份和 GitHub 账号绑定，不像其他评论系统可能需要另外部署数据库或者使用第三方 Auth 。

如果能做到纯客户端实现，只在用户侧调用 GitHub API 来实现所有功能，就更好了。可惜 Giscus 仍然需要在第三方 Host 一个服务来做这件事，但是算了，无所谓。

如果你没有听说过 Giscus​

Giscus 是一个基于 GitHub Discussion 的评论系统。而 giscus.app 是 Giscus 的文档兼脚本生成器。

跟随 giscus.app 上的指引，我们最终会得到一个 HTML 元素，将这个元素插入到网页源代码中，Giscus 就出现啦。

如果你不喜欢直接写 HTML 元素，或者正在使用某个前端框架，你也可以使用 Giscus Component 。比如你现在正在看的这个博客使用的框架是 Docusaurus ，而这个框架是基于 React 的，所以我使用了 @giscus/react 。

所以我们总共需要做三件事：

  1. 在 GitHub 上的，我们的博客仓库中，启用 Discussions ，并且（可选）创建一个 Giscus 专属的 Discussion Category 来将 Giscus 发布的内容与其他内容区分开。这个 Category 最好是 Announcement 类型的（其中的内容只能由仓库维护者和 Giscus 创建）。
  2. 使用 giscus.app 来为我们在 GitHub 上的博客仓库生成一个对应的评论区 HTML 元素代码；
  3. 把这个 HTML 代码翻译成对应的 Giscus Component ，嵌入我们的博客中。

Giscus 的配置该怎么选​

giscus.app 上对于每个配置项都有详细的描述，这里就不全部展开了，挑重点说。

页面和 Discussion 的对应关系​

我选择的是 URL ，原因是我的博客可能有多份部署（比如 PR Preview 部署在 Vercel 上），而我希望将不同部署之间的评论区互相隔离。

在 Giscus 提供的选项中，只有 URL 恰好支持了这个需求。不过代价是 GitHub Discussion 的标题会是 Blog Post 的 URL 而不是标题，在 GitHub 里面看起来比较丑（不过又有谁会在 GitHub 中查看博客的评论区，而不是直接在博客中查看呢）。

主题​

这个选项改动之后，在页面下方可以看到实时预览。

我们的博客目前有明亮和暗黑两种颜色模式，我们希望读者切换 Docusaurus 的日夜模式后，Giscus 也能切换到对应的主题。

实现这个功能的方法下文会描述，这里我们先尝试下所有选项，分别为明亮和暗黑模式找到对应的合适的主题，然后记住下面代码中的 theme ，等下要用。

在 Docusaurus 中嵌入我们的评论区组件​

Giscus Component 的文档详细描述了将 HTML 元素翻译成对应组件的方法。

对照着文档和上面生成的 HTML 元素代码填空之后，我们得到了一个 Giscus React 组件：

import Giscus from '@giscus/react';

const GiscusContainer = (
  <Giscus
    {/* ...... */}
    mapping="url"
    theme={/* light or dark_dimmed */}
  />
);

接下来要做的事情就是将这个组件插入到 Docusaurus 中。如果你也在使用 Docusaurus ，并且对于魔改 Docusaurus 组件的方法并不熟悉，你可以参考 Docusaurus 官方魔改教程。

Docusaurus 提供了两种魔改的方式：Ejecting 和 Wrapping 。简单来说就是：

  • Ejecting ：将 Docusaurus 某个组件的代码复制一份，开发者在其上进行修改。这是真正的魔改，自由度最高，但缺点是大量的组件代码被复制出来，会造成代码仓库体积的膨胀。
  • Wrapping ：在 Docusaurus 某个组件的外层创建一个 Wrapper ，比较优雅。大部分时候 Wrapping 就够用了。

这里，我们希望在博客页面的下方添加我们的评论区组件，所以我们可以 Wrap 展示「博客内容」的组件，在博客内容的下方加上 Giscus 的代码。

我们使用的是 Docusaurus 默认的博客插件，需要 Wrap @docusaurus/theme-classic 这个主题的 BlogPostItem 组件。

# 以 npm 为例
npm run -- docusaurus swizzle @docusaurus/theme-classic BlogPostItem --wrap

项目根目录中会出现这些文件：

src
└── theme
    └── BlogPostItem
        └── index.tsx

打开 src/theme/BlogPostItem/index.tsx ，在 BlogPostItem 之后添加我们的 Giscus React 组件，打开我们的 Docusaurus 本地预览，我们就能看到博文下方的评论区啦！

然而预览之后会发现，博文下方确实出现了评论区，但是首页（博文目录）的每一个摘要下方也出现了评论区…… 🤡

限制 Giscus 只在具体博文下方显示​

Docusaurus 默认主题提供了一个 Internal API 叫做 useBlogPost() ，可以用来查询当前页面属于博文目录还是具体的博文页面。

因为是 Internal API ，所以文档里面没有关于这个 API 的描述 🤡 ，我在 Docusaurus 的 GitHub Repo 里面搜罗了一圈才找到相关的内容：

我们通过这个 API 来拿到当前页面所属的类别，并在此基础上控制 Giscus 的显示：

// other imports......
import { useBlogPost } from '@docusaurus/plugin-content-blog/client';

export default function BlogPostItemWrapper(props: Props): JSX.Element {
  const { isBlogPostPage } = useBlogPost();
  const GiscusContainer = (
    <Giscus
      {/* ...... */}
    />
  );
  return (
    <>
      <BlogPostItem {...props} />
      {/* Prevent giscus to show up on blog post menu */}
      {isBlogPostPage && GiscusContainer}
    </>
  );
}

再次打开预览，此时的 Giscus 应该仅在博文页面显示。我们也可以尝试写一些评论，会发现 GitHub 中出现了标题为 http://localhost:3000/...... 的 Discussions ，符合预期。接下来只需要加上我们的日夜模式切换功能，就大功告成啦。

根据当前颜色模式切换 Giscus Theme​

这个方法比较省力。这个博客（20240826）使用的也是这个方法。下文还会介绍一种可能更加优雅的方法。

Docusaurus 提供了 useColorMode() 来获取当前读者选择的颜色模式。

这个 API 的文档藏在默认主题的文档里，而不是默认主题的博客插件的文档里，导致我读的时候直接略过了……最后又是到 Docusaurus 的 GitHub Repo 里找了一通，才找到了相关内容：

我们先定义好 Docusaurus ColorMode和 Giscus Theme 之间的映射，再通过这个 API 来拿到当前读者选择的 ColorMode ，并让 Giscus 使用与之对应 Theme ：

// other imports......
import { useColorMode, ColorMode } from '@docusaurus/theme-common';
import Giscus, { Theme } from '@giscus/react';

const DocusaurusColorModeToGiscusTheme: Record<ColorMode, Theme> = {
  light: 'light',
  dark: 'dark_dimmed'
};

export default function BlogPostItemWrapper(props: Props): JSX.Element {
  // ......

  const { colorMode } = useColorMode();
  const giscusTheme = DocusaurusColorModeToGiscusTheme[colorMode];

  const GiscusContainer = (
    <Giscus
      {/* ...... */}
      theme={giscusTheme}
    />
  );

  // ......
}

再次打开预览测试，此时 Giscus Theme 应该会随着 Docusaurus ColorMode 的切换而切换。唯一的一点小瑕疵是 Giscus 组件的颜色变换是瞬间完成的，不像 Docusaurus 内部其他组件一样有过渡动画。

另一种让 Giscus 变色的方式​

这个方法是我写这篇文章的时候脑补出来的，还没实现过，留作习题供读者尝试（doge）。

简单来说就是 Giscus 的主题可以是自定义的 CSS 。而我们知道在 CSS 中实现日夜切换的常规操作是通过 CSS 变量，让组件在不同模式下继承不同的变量得到不同的前景色和背景色。

那么这里理论上更优雅的实现方式，是我们为 Giscus 编写一套 Docusaurus Theme ，将 Giscus 所有颜色交由 Docusaurus 管理，这样可以让 Giscus 和 Docusaurus 更加融合统一。

结语​

我们使用 Docusaurus Swizzling 将 Giscus 嵌入了 Docusaurus 中，并添加了日夜颜色切换的功能，接下来就可以通过这个评论区愉快地和小伙伴们聊天啦！（现实是根本没有小伙伴 QAQ）

]]> Yikai Cai https://github.com/VVsxmja <![CDATA[使用 Netdata 来监控开发机的系统指标]]> https://vvsxmja.github.io/2024/08/08/use-netdata-to-monitor-your-dev-machine 2024-08-08T00:00:00.000Z Netdata 本来是对标 Prometheus 的监控方案，但日常开发中我们也可以用 Netdata 替代 htop 和 dstat ，除了具备二者几乎所有能力之外，还提供图形化界面，支持回放，并且开箱即用、易于上手。

不知道大伙在 Linux 系统上进行开发的时候，有没有过这样的体验：

  • 我跑的某个工具卡住了，但我不知道它是在计算，还是在进行网络传输，还是挂了。
  • 我的某个程序跑的很慢，但我不知道它 Bound 在 IO 还是 CPU 还是别的地方。

如果你之前只接触过 Windows 系统，那么这时你应该会下意识地寻找「任务管理器」这种东西。你可能会找到 htop ，或者（如果你正在使用图形界面）某个桌面环境的任务管理器。

这些程序提供了最基本的系统指标，例如 CPU 利用率、内存利用率等。但当我们遇到一些比较复杂/玄学的问题时，我们可能会想：如果能看到更详细的系统指标（比如 CPU 中断发生的频率），说不定能找到什么解决问题的线索。

比较有经验的 Linux 用户此时会转而使用 dstat 等工具，这些工具能够看到更加细节、一般的「任务管理器」不会展示的指标。

但这些工具仍然存在「不够开箱即用」，「难以回放历史记录」等问题，例如初次使用 dstat 的用户可能会遇到下面的困难：

  • dstat 的默认输出中是不包含时间信息的，需要通过加上 -t 来在每行输出中附加时间信息。
  • dstat 默认输出到 stdout ，能够回看的长度受限于终端缓冲区大小，需要通过加上 -o ... 来在打印命令行输出的同时输出到 CSV 文件。
  • dstat 不支持在运行时更改采样间隔，只能对着打出来的 CSV 去按不同频率采样/聚合。

另外，相信大伙在项目中工作时，往往会发出「线上环境的基建，如果能在我的开发机上也布一套就好了」的感慨，在 CI 或是在生产部署上可以访问到的详细的监控，和我们开发机上可怜的寥寥几项指标相比，就像是奥迪和奥迪双钻的区别。

那么有没有一套开箱即用的监控服务，能很方便地在我的开发机上布起来，能够解决上面的所有痛点，并且也具备接入其他应用的能力？

答案是有的，请看 Netdata 。

如果你没有听说过 Netdata​

Netdata 是一款很强大的开源监控工具。它开箱即用，除了具备 dstat 的各种能力之外，还提供了非常友好的 Web Dashboard ，对于每一项指标都有很详细的描述，就算是第一次接触的用户，也能快速上手。

Netdata Agent

例如默认配置下，Overview 中第一个 Metric - CPU 利用率的图表上方，就有如下的介绍：

Total CPU utilization (all cores).

100% here means there is no CPU idle time at all. You can get per core usage at the CPUs section and per application usage at the Applications Monitoring section.

Keep an eye on iowait. If it is constantly high, your disks are a bottleneck and they slow your system down.

An important metric worth monitoring, is softirq. A constantly high percentage of softirq may indicate network driver issues. The individual metrics can be found in the kernel documentation.

Netdata 就像是生怕用户看不懂这些 Metrics 一样，在每一个图表的上方都撰写了详细的描述。结合 Netdata 对于系统指标的强大的抓取能力，不管是新手还是老手，都能在 Netdata 中发现查看节点运行状况的一个新的角度。

百闻不如一见，Netdata 官方在世界各地都布了 Netdata Demo ，大伙可以直接点进去看看 Netdata 长什么样。

FRANKFURTNEWYORKATLANTASANFRANCISCOTORONTOSINGAPOREBANGALORE

Netdata 除了自身具有观测系统指标的能力之外，同时也支持接入其他应用（例如 OpenMetrics 和 StatsD）以拓展它的能力。比如，安装了这个插件，你就可以在 Netdata 中查看 systemd 的 Journal Logs 了！

相信你此时已经按耐不住自己的心情，想要自己部署一套 Netdata 实例了！

（如果你还是 Get 不到 Netdata 好用在哪里，你也可以跟随下面的指引，一键启动一个 Netdata 来玩一玩，看看它是不是你的菜）

使用 Docker 启动 Netdata 实例​

以下内容基于 Netdata 官方文档编写。

Netdata 推荐的安装/部署方式是通过容器启动的。只需要一条命令 / 一个配置文件就能快速部署 Netdata ：

（当然在此之前，你需要确认你的网络条件可以让 Docker Engine 访问到 DockerHub ）

docker run -d --name=netdata \
  --pid=host \
  --network=host \
  -v netdataconfig:/etc/netdata \
  -v netdatalib:/var/lib/netdata \
  -v netdatacache:/var/cache/netdata \
  -v /:/host/root:ro,rslave \
  -v /etc/passwd:/host/etc/passwd:ro \
  -v /etc/group:/host/etc/group:ro \
  -v /etc/localtime:/etc/localtime:ro \
  -v /proc:/host/proc:ro \
  -v /sys:/host/sys:ro \
  -v /etc/os-release:/host/etc/os-release:ro \
  -v /var/log:/host/var/log:ro \
  -v /var/run/docker.sock:/var/run/docker.sock:ro \
  --restart unless-stopped \
  --cap-add SYS_PTRACE \
  --cap-add SYS_ADMIN \
  --security-opt apparmor=unconfined \
  netdata/netdata

这里的配置是最简单的开箱即用配置，关于更高级的配置，以及除了 Docker 以外的部署方法，请参考官方文档。

Netdata 会在 19999 端口跑一个 Web Dashboard ，结合 --network=host ，也就是跑在 Host 的 19999 端口上。

通过 SSH Port Forwarding 访问开发机上的 Web Dashboard​

我们可以通过 SSH Tunnel 等方式，将这个端口转发到我们访问开发机的电脑上，然后就可以用浏览器访问啦！

最简单的转发方式，就是开一个 VS Code ，通过 SSH Remote 连接到我们的开发机，在 Panel 里的「端口」标签页中增加一个 19999 端口的转发，然后用浏览器打开 http://localhost:19999 就能访问了。

如果我们希望自动进行这样的操作，可以更改我们的 SSH Config ，使得每次通过 SSH 连接到开发机的时候，自动转发 19999 端口到本地。在上面的 VS Code 文档链接中也有提到。

下面提供我的配置文件作为参考：

Host dev
    # 基础配置
    HostName 开发机的 IP 地址
    User 开发机登陆用户名
    IdentityFile SSH 密钥地址

    # 转发 19999 端口到本地
    LocalForward 19999 127.0.0.1:19999

    # 可选，VS Code 会自动保活，不需要加这个
    ServerAliveInterval 15
    ServerAliveCountMax 240

结语​

Netdata 提供了开箱即用的使用体验，详细、实时的系统指标，以及友好的 Web Dashboard ，值得大家进行尝试。

在具体的开发场景下，结合 Port Forwarding ，可以很方便地随时查看开发机的各项指标。

希望这篇文章有帮到你。

]]> Yikai Cai https://github.com/VVsxmja <![CDATA[Docusaurus 初体验！]]> https://vvsxmja.github.io/2024/05/26/first-blog-in-docusaurus 2024-05-26T00:00:00.000Z Docusaurus 是一个基于 React 的静态站点框架，在开箱即用的同时，提供了优雅的魔改方法。

Docusaurus Introducing

很早就有写博客的想法，但是一直没找到一个很对我胃口的框架。因为除了写博客这件事之外，我还希望能够大力魔改我用的博客框架。

——要开箱即用，又要高可玩性，还要详细的文档，如果能方便地用 JavaScript/TypeScript 添加自己想要的功能，用 CSS 改成自己喜欢的样式，就最好了。

之前用过一段时间的 Mkdocs 和 Hexo ，它们都是很出色的框架，使用体验也很好，但就是不太能满足我的定制化需求：它们的插件系统要不就是用起来很麻烦，要不就是缺少文档。

后来用了一段时间的 VitePress ，当时以为自己找到了命中注定的那个框架：基于 Vue 和 Vite ，极高的可定制性；框架本身也并不复杂，代码不多，很快就能看完。我甚至写了一个 VitePress 的主题。

VitePress 之旅​

VitePress 的可定制性太强了！强的原因是 VitePress 本身的功能并不多。

它只做这么几件事：把 Markdown 用 markdown-it 和 mdit-vue 翻译成 HTML ，处理一下各个文件之间的链接，然后嵌入到默认/自定义 Layout 中的 <Content />元素里，基本上就大功告成了。

而自定义 Layout 更是 100% Hackable 的逆天存在，它就是一个 Vue Component（顺便一提，VitePress 的 Markdown 中也支持插入 Vue Component），可以在运行时做自己想做的任何的事情。

在构建期间也可以通过自定义的 Build-Time Data Loader 构建出任意的自定义数据，例如博客框架里常用的博文列表（一般会加上分页），各篇文章的编辑日期和修改日期，以及各种其他的好玩的东西……

后来放弃 VitePress 的原因有两个，一个是 VitePress 的文档太弱了，另一个是 VitePress 和 Vite 强绑定，但是 Vite 太难懂了（而且文档也比较弱）。为了把我的自定义主题导出成 npm 包，费了九牛二虎之力都没有成功，最后只好作罢。

其实我大概知道问题在哪：因为我用了 UnoCSS 的 Vite 集成，所以除了用 npm 包分发代码之外，用户还需要额外进行 VitePress 的 Vite 配置，但我自己用新的环境尝试了几次，遇到了各种难以描述的奇怪的错误……总之失败了几次之后彻底失去耐心了.

我很热衷于自己造轮子，事实上造这个 VitePress 主题的过程中我已经造出了一个博客框架大部分必要的组成部分了。但是碰到奇怪的问题又找不到文档时，那种挫败感真的令人难受。

图标是一个小恐龙的静态站点框架​

放弃 VitePress 之后决定寻找一个新的框架，网上冲浪了一段时间之后发现了 Docusaurus 这个好东西。基于 React ，文档非常详细（Docusaurus 的官网本身就是使用 Docusaurus 写的文档博客二合一网站），有开箱即用的博客框架，并且也支持定制化，而且这个定制的方式还很神奇……总之被圈粉了。

这个小恐龙的图标真的很魔性，越看越喜欢。

Docusaurus Docusaurus Keytar Docusaurus Speed

简单上手了一下，使用体验非常好：文档很丰富，甚至连 Frontmatter 都有文档。

大悦，遂撰文记之。于是就有了你现在正在看的这篇文章以及这个网站。

]]> Yikai Cai https://github.com/VVsxmja