Eason Yang's Blog

再见Hexo——从Hexo迁移至Hugo

16 年的时候，博客使用的虚拟主机需要做迁移，当时所使用的 Typecho 是一个依赖于数据库的 PHP 博客系统，数据导出过程很艰辛。彼时 Gihub Pages 正大火，我也就跟风转投了静态博客系统 Hexo 。七年过去了，博客还在，但折腾 Hexo 的人是越来越少了。如今我也要和 Hexo 说声再见，拥抱 Hugo 的怀抱了。 <h2 id="为什么改用hugo">为什么改用Hugo</h2> <h3 id="依赖管理问题">依赖管理问题</h3> 在<a href="https://easonyang.com/2021/07/10/how-to-sync-and-backup-a-static-blog/">静态博客的同步和备份方案</a>一文中，我分享了基于 Github 和 iCloud 的同步备份方案，期望在保证数据安全的同时，写作环境可以在我的两台电脑上无缝切换。 然而实际上，由于 Hexo 依赖于 Node.js ，庞大的 node_modules 并不能直接同步而是需要分别安装和更新，如果忘了运行 <code>npm install -S</code> ，那报错和渲染异常就是家常便饭的事。而 node-sass 这样的库还对 node 版本做了显式要求，导致如果哪台设备改了 nvm 中 node 的版本就会报错。但偏偏又有大量的主题和插件都依赖于 node-sass 。 而 Hugo 是基于 Golang 的二进制程序，安装和升级都很简单。由于内置功能足够多，插件（模块）不再是必需的了，如果有需要，其也都是通过 go mod 管理，轻量而简洁。虽然大部分主题仍然依赖于 Node.js ，但那只是创建和修改主题时的事情，不会影响到写作流程。 诚然，这并不能算作 Hexo 本身的问题，但由于底层的技术选型，导致 Hexo 必然和各类主题及插件的耦合较为严重。在三方组件实现和依赖复杂的情况下，整体的复杂度也就必然会成倍地上涨。 <h3 id="网页生成速度">网页生成速度</h3> Hexo 裸安装后的网页生成速度并不算不可接受，和 Hugo 比起来也就几秒到十几秒的差异，没有网上传得那么夸张。但多加了几个像 <a href="https://github.com/chenzhutian/hexo-all-minifier">hexo-all-minifier</a> 这样生命周期靠后的插件后，生成速度确实会肉眼可见地下降。而 Hugo 的网页生成速度则非常稳定，总是保持在秒级别甚至毫秒级别，因此也可以真正意义上地实现本地实时预览。 <h3 id="hugo的特性">Hugo的特性</h3> Hugo 对 org-mode 、pandoc 等提供了原生支持，轻度使用体验也不错（深度使用也会遇到坑）。虽然 Hexo 等也可以通过安装插件和转换器等方式来实现，但这又会回到上面的依赖复杂的问题之中。此外，Hugo 的 <a href="https://gohugo.io/content-management/shortcodes/">shortcode</a> 功能也非常强大，如果不考虑 md 文件的通用性，那结合 shortcodes 可以轻松实现很多本需要依赖于插件（模块）才能做到的功能。 <h2 id="快速上手">快速上手</h2> 首先安装 Hugo 并创建站点，以 macOS 系统为例： <div class="highlight"><div class="chroma"> <table class="lntable"><tr><td class="lntd"> <pre tabindex="0" class="chroma"><code>1 2 </code></pre></td> <td class="lntd"> <pre tabindex="0" class="chroma"><code class="language-shell" data-lang="shell">brew install hugo # For macOS hugo new site sample </code></pre></td></tr></table> </div> </div>这里需要注意的是，如果此前系统中已经安装过旧版本的 Go ，那有可能需要升级后才能使用 homebrew 完成安装。随后选一个喜欢的主题拉取到 <code>/themes</code> 目录，以 even 主题为例： <div class="highlight"><div class="chroma"> <table class="lntable"><tr><td class="lntd"> <pre tabindex="0" class="chroma"><code>1 </code></pre></td> <td class="lntd"> <pre tabindex="0" class="chroma"><code class="language-shell" data-lang="shell">git clone https://github.com/olOwOlo/hugo-theme-even themes/even </code></pre></td></tr></table> </div> </div>主题通常会带有示例配置文件 <code>config.toml</code> ，将其复制到站点的根目录下覆盖默认配置文件，并完成相应配置后，运行 <code>hugo new post/test.md</code> 新建文章，随后运行 <code>hugo server -D</code> 即可查看站点。对于存量的文章，需要将其复制到主题 <code>/content/</code> 目录下，其中文章类的需要按主题的设计来放置于具体目录，如 even 主题使用 post 目录，则需要将文章复制到 <code>/content/posts</code> 目录下，重新执行上面的命令就能在站点里看到文章了。 如果运行命令时报错，则可能是存量文章的 front matter 格式有不符合 Hugo 要求的情况，此时需要按<a href="https://gohugo.io/content-management/front-matter/">官方文档</a>进行修改适配。 <h2 id="写作习惯的变化">写作习惯的变化</h2> 整体写作习惯其实和 Hexo 的体验差别不大。不过 Hugo 提供了比 Hexo 更丰富的 front matter 默认配置，同时还支持 org-mode 等玩法，所以写作方式上的可玩性会更高些。 <h2 id="主题自定义方式的变化">主题自定义方式的变化</h2> 与 Hexo 主题的完全前端实现不同，Hugo 的主题使用了 Go 的模板语言，有点类似于 PHP 和 JSP ，并向主题暴露了一系列的全局变量和函数，所以其实主题和 Hugo 或 Golang 还是有一定的耦合的。 不过这也使得我们可以通过自定义模板覆盖主题默认模板的方式，来既实现自己的需求，又能最低限度地避免修改主题源代码导致的升级困难。但很多主题没有提供关键位置的钩子模板（也可以说是接口），导致我们经常需要拷贝一部分主题的源代码到自定义模板中，这又对主题的升级造成了一定的影响，可以说是有得必有失了。 <h2 id="向前兼容">向前兼容</h2> 迁移工作的一个核心要求就是尽量避免引入 breaking change 。首先要保证存量页面的链接不发生变化，以避免出现 404 的情况。其次要尽量对此前在 Hexo 中使用的各项功能进行支持。 <h3 id="永久链接格式兼容">永久链接格式兼容</h3> 在 Hexo 中，通常有以下三种 URL 永久链接路径格式： <ol> <li>日期前缀+英文别称或文件名：<code>/2021/07/06/a-better-hexo-theme-even/</code></li> <li>固定前缀+英文别称或文件名：<code>/posts/slidev-tutorial/</code></li> <li>使用了 abbrlink 等插件生成 CRC/Hash 值作为路径：<code>/posts/8ccq01298/</code></li> </ol> 而 Hugo 默认的永久链接格式为 <code>/{{ 文章目录 }}/{{ 文章文件名 }}</code> ，和上面第二种比较相似但又有所不同。那么我们该如何实现兼容呢？ 首先我们要了解 Hugo 可以在根目录的 <code>config.toml</code> 中对永久链接进行自定义配置，例如： <div class="highlight"><div class="chroma"> <table class="lntable"><tr><td class="lntd"> <pre tabindex="0" class="chroma"><code>1 2 </code></pre></td> <td class="lntd"> <pre tabindex="0" class="chroma"><code class="language-toml" data-lang="toml">[permalinks] '/' = "/posts/:slug" </code></pre></td></tr></table> </div> </div>因此我们只需要针对不同情况，对该配置进行自定义即可。 <ol> <li>日期前缀+英文别称或文件名：仿照 Hexo 的日期格式，将值配置为 <code>/:year/:month/:day/:title/</code> 。</li> <li>固定前缀+英文别称或文件名：将值改为 <code>/posts/:title</code> 即可。 Hugo front matter 中的 <code>slug</code> 变量表示自定义别名，所以如果此前在 Hexo 使用了自定义的变量，只要仿照此前的配置将 title 改为 slug 即可，例如 <code>/posts/:title</code> 。</li> <li>使用 abbrlink 等插件生成的 CRC/Hash 值作为路径：Hugo 似乎没有 abbrlink 这类插件，不过我们可以仿照<a href="https://blog.lxdlam.com/post/9cc3283b/">这篇文章</a>，在默认内容模板 <code>archetypes/default.md</code> ，再将其中的 slug 配置为一段具备哈希或 CRC 功能的表达式即可。不过存量文章可能需要通过 front-matter 中的 <code>url</code> 变量进行完整路径的显式声明，不然如果表达式的处理结果和 Hexo 中的不同，那链接可就变了。</li> </ol> 上面说明了 <code>permalinks </code> 的值，那 key 该如何配置呢？与 Hexo 不同，Hugo 中永久链接的固定前缀（对应上文的情况 2 和情况 3）是根据目录位置生成的，该位置的选择又与主题有关。有的主题使用的是 <code>/content/post/</code> 目录，有的主题使用的又是 <code>/content/posts</code> 目录，同时这个路径在很多主题的实现中是写死的。因此如果此前你在 Hexo 中所使用的固定前缀和所选 Hugo 主题的不同（如 <code>/articles/</code>），那就会造成链接发生变化的问题。 所以我们需要在 <code>permalinks </code> 配置的 key 上做些文章，把主题所用的路径做一层指定映射，保证最终的路径以我们期望的前缀输出。以主题使用 <code>/content/post/</code> 作为内容目录、原 Hexo 文章的永久链接格式为 <code>/posts/:slug</code> 为例，对 <code>permalinks </code> 进行以下配置即可： <div class="highlight"><div class="chroma"> <table class="lntable"><tr><td class="lntd"> <pre tabindex="0" class="chroma"><code>1 2 </code></pre></td> <td class="lntd"> <pre tabindex="0" class="chroma"><code class="language-toml" data-lang="toml">[permalinks] post = "/posts/:slug" </code></pre></td></tr></table> </div> </div>另外，对于此前在 Hexo 中配置了 html 后缀等情况，可以开启 Hugo 的 Ugly URLs 来实现兼容，细节可以参考<a href="https://gohugo.io/content-management/urls/#ugly-urls">官方文档</a>。 <h3 id="归档页面路径链接的兼容">归档页面路径链接的兼容</h3> 前一节提到了主题对内容目录路径的选择可能是不同的，而这也会影响到归档页面的路径。在 Hugo 的大部分主题中，如果主题使用 <code>/content/post/</code> 作为内容目录，那归档页面路径则默认为 <code>/post/</code> 且不支持配置。而我们在 Hexo 中通常会使用 <code>/archives/</code> 作为归档页面的路径，如何才能保持不变呢？ 虽然绝大部分主题（也可能是所有）都没有此项配置，但我们可以通过自定义一套模板和页面的方式来绕过主题的限制。以 even 主题的模板和 CSS 样式为例，在 <code>/layouts/_default/</code> 目录下新建 <code>archives.html</code> 模板，随后填充以下内容，用于按年分组遍历所有文章，并在原主题的框架下输出文章标题列表： <div class="highlight"><div class="chroma"> <table class="lntable"><tr><td class="lntd"> <pre tabindex="0" class="chroma"><code> 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 </code></pre></td> <td class="lntd"> <pre tabindex="0" class="chroma"><code class="language-html" data-lang="html">{{- define "title" }}{{ T "archive" }} - {{ .Site.Title }}{{ end -}} {{- define "content" }} {{ $pageList := (where .Site.RegularPages "Type" "post") }} <section id="archive" class="archive"> {{- if .Site.Params.showArchiveCount }} <div class="archive-title"> <span class="archive-post-counter"> {{ T "archiveCounter" (len $pageList) }} </span> </div> {{- end -}} {{ range ($pageList.GroupByDate "2006") }} <div class="collection-title"> <h2 class="archive-year">{{ .Key }}</h2> </div> <ul class="archive-list"> {{ range (where .Pages "Type" "post") }} <div class="archive-post"> <span class="archive-post-time"> {{ .PublishDate.Format "01-02" }} </span> <span class="archive-post-title"> <a href="{{ .RelPermalink }}" class="archive-post-link"> {{ .Title }} </a> </span> </div> {{ end }} </ul> {{ end }} </section> {{ end }} </code></pre></td></tr></table> </div> </div>随后在 <code>/content/</code> 目录下新建 <code>archives.md</code> 页面，将 <code>type</code> 指定为刚刚定义的 <code>archives</code> ： <div class="highlight"><div class="chroma"> <table class="lntable"><tr><td class="lntd"> <pre tabindex="0" class="chroma"><code>1 2 3 4 5 6 7 8 </code></pre></td> <td class="lntd"> <pre tabindex="0" class="chroma"><code class="language-markdown" data-lang="markdown">--- title: "归档" layout: "archives" url: "/archives/" comment: false hidden: true type: archives --- </code></pre></td></tr></table> </div> </div>这时我们就已经可以通过访问 <code>/archives/</code> 路径来进入到归档页面了，接下来只要在 <code>config.toml</code> 中再将导航栏中的对应按钮指定为预期链接即可。 <div class="highlight"><div class="chroma"> <table class="lntable"><tr><td class="lntd"> <pre tabindex="0" class="chroma"><code>1 2 3 4 5 </code></pre></td> <td class="lntd"> <pre tabindex="0" class="chroma"><code class="language-toml" data-lang="toml">[[menu.main]] name = "归档" weight = 20 identifier = "archives" url = "/archives/" </code></pre></td></tr></table> </div> </div>上文这种实现的效果和很多主题的归档页面相比，主要区别在于单页面内罗列了所有文章，即缺少分页。由于大部分主题的分页逻辑和其内部的其他模板耦合较为严重，同时 Hugo 的分页相关变量被限制不能用于自定义模板之中，所以如果希望自定义的归档页能支持分类，则可能需要对 Hugo 的原生逻辑进行包装即额外实现一套分页能力才行。这里不做展开讲述。 <h3 id="友情链接和自我介绍">友情链接和自我介绍</h3> 和 Hexo 一样，Hugo 也没有直接支持友情链接和自我介绍这类常用页面。在实现上我们要么在 <code>/content/</code> 目录下自定义页面也就是在页面内维护内容，要么如归档页面一般，通过自定义模板的方式来加载 <code>config.toml</code> 中的配置。两种实现都比较简单，我也更倾向于前者，毕竟这些是低频修改页面，是否可配置区别都不大。 <h3 id="标签和分类的中英文问题">标签和分类的中英文问题</h3> 在 Hexo 中，我们通常会在 <code>_config.yml</code> 中配置标签和分类的中英文映射，这样我们在 front matter 中可以使用任意语言标识标签和分类，但生成后两者的 URI 都是英文。然而在 Hugo 中却没有这类简易设置，也许我们可以通过修改主题和永久链接的方式来间接支持，但估计成本较高。所以如果对 URI 有强迫症的读者，还是建议把存量文章的标签和分类改为英文。而如果对此没有特殊需求，那使用中文也可。除了 URL 的分享可读性可能较差外，在 2022 年的今天其实已经不会影响搜索引擎的 SEO 效果了。 <h3 id="支持git与vps部署">支持Git与VPS部署</h3> 不知为何 Hugo 官方没有直接支持使用 Git 搭配 Git Hooks 部署站点，对于我这种把博客部署在 VPS 的用户给出的建议方案是 rsync 。其实 rsync 方案是完全可行且成本不高的，不过本着尽量兼容的原则我还是决定在部署时执行以下 shell 脚本来通过 Git 推送生成的 <code>/public/</code> 目录至 VPS ，而 VPS 上的 Git 库和 Git Hooks 配置则无需改动： <div class="highlight"><div class="chroma"> <table class="lntable"><tr><td class="lntd"> <pre tabindex="0" class="chroma"><code> 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 </code></pre></td> <td class="lntd"> <pre tabindex="0" class="chroma"><code class="language-shell" data-lang="shell">#! /bin/bash rm -rf ./public hugo rm -rf ./.deploy_git mkdir .deploy_git cp -r public/* ./.deploy_git cd .deploy_git git init --initial-branch=master git add -A git commit -m 'Deploy commit.' --quiet git push -u foo@bar-server:/var/blog.git HEAD:master --force cd .. rm -rf ./.deploy_git </code></pre></td></tr></table> </div> </div><h3 id="兼容hexo的rss形式">兼容Hexo的RSS形式</h3> 使用 Hexo 时博客的 RSS 是全文输出，而换到 Hugo 后 RSS 却变为了输出摘要。作为一个重度 RSS 用户，我自然是深知拉取到的文章还要二次跳转到浏览器才能看原文的体验有多差，所以还是要让 RSS 的表现和此前一致才行。 Hugo 的 RSS 是基于默认 RSS 模板生成的，所以我们只要重新定义一个模板并改为全文输出即可。<a href="https://github.com/gohugoio/hugo/blob/master/tpl/tplimpl/embedded/templates/_default/rss.xml">Hugo 的默认实现</a>中，决定输出内容的是如下这行代码： <div class="highlight"><div class="chroma"> <table class="lntable"><tr><td class="lntd"> <pre tabindex="0" class="chroma"><code>1 </code></pre></td> <td class="lntd"> <pre tabindex="0" class="chroma"><code class="language-xml" data-lang="xml"> <description>{{ .Summary | html }}</description> </code></pre></td></tr></table> </div> </div>我们只需要在 <code>/layouts/</code> 目录新建 <code>index.rss.xml</code> 覆盖默认模版并将原实现拷贝至其中，接着把代码中的 <code>{{ .Summary | html }}</code> 替换为代表全文内容的表达式 <code>{{ .Content | html }}</code> 即可： <div class="highlight"><div class="chroma"> <table class="lntable"><tr><td class="lntd"> <pre tabindex="0" class="chroma"><code>1 </code></pre></td> <td class="lntd"> <pre tabindex="0" class="chroma"><code class="language-xml" data-lang="xml"> <description>{{ .Content | html }}</description> </code></pre></td></tr></table> </div> </div><h2 id="even主题迁移">even主题迁移</h2> 由于此前一直在使用<a href="https://easonyang.com/2021/08/01/enhanced-hexo-theme-even/">修改过的 Hexo even 主题</a>，为保证前端效果不变，所以主题方面也采用了 Hugo 下的 even 主题，因此会有很多主题层面的额外适配工作。 <h3 id="自定义导航栏">自定义导航栏</h3> 此前使用 Hexo 下 even 主题时自定义了一个用于引导用户的导航栏，那么如何在 Hugo 的 even 主题中实现兼容呢？ 首先我们在 <code>/layouts/partials/header/</code> 下新建 <code>top-nav.html</code> 模板，按需填充内容，如增加 Newsletter 、Telegram Channel 等引导： <div class="highlight"><div class="chroma"> <table class="lntable"><tr><td class="lntd"> <pre tabindex="0" class="chroma"><code> 1 2 3 4 5 6 7 8 9 10 11 12 13 </code></pre></td> <td class="lntd"> <pre tabindex="0" class="chroma"><code class="language-html" data-lang="html">{{- if .Site.Params.enableTopNav }} <div class="top-nav"> {{- if .Site.Params.revue.enabled -}} <a href="{{ .Site.Params.revue.home }}" href="_blank" class="top-nav-button">Newsletter</a> {{- end -}} {{- if .Site.Params.telegram.enabled -}} <a href="{{ .Site.Params.telegram.link }}" href="_blank" class="top-nav-button">电报频道</a> {{- end -}} {{- if .Site.Params.wxOfficialAccount.enabled -}} <a href="{{ .Site.Params.wxOfficialAccount.url }}" href="_blank" class="top-nav-button">微信公众号</a> {{- end -}} </div> {{- end -}} </code></pre></td></tr></table> </div> </div>随后我们需要找个位置引入该模板。受 even 主题实现的限制，我们需要将该模板放置于 header 块之后才能最低成本地保留原布局。因此我们只有一个选择，那就是将 <code>baseof.html</code> 这个基础模板进行覆盖。拷贝原模板内容至 <code>/layouts/_default/baseof.html</code> 中，并在 <code>header</code> 块之后、<code>main</code> 块之前引入此前定义的 <code>top-nav.html</code> ： <div class="highlight"><div class="chroma"> <table class="lntable"><tr><td class="lntd"> <pre tabindex="0" class="chroma"><code> 1 2 3 4 5 6 7 8 9 10 11 12 </code></pre></td> <td class="lntd"> <pre tabindex="0" class="chroma"><code class="language-html" data-lang="html">... <div class="container" id="mobile-panel"> {{ if not .Params.hideHeaderAndFooter -}} <header id="header" class="header"> {{ partial "header.html" . }} </header> {{- end }} {{- partial "header/top-nav.html" . -}} <main id="main" class="main"> ... </code></pre></td></tr></table> </div> </div>最后在 <code>config.toml</code> 中完成相关参数配置即可： <div class="highlight"><div class="chroma"> <table class="lntable"><tr><td class="lntd"> <pre tabindex="0" class="chroma"><code> 1 2 3 4 5 6 7 8 9 10 11 </code></pre></td> <td class="lntd"> <pre tabindex="0" class="chroma"><code class="language-toml" data-lang="toml"> [params.wxOfficialAccount] enabled = true url = "" [params.telegram] enabled = true link = "" [params.revue] enabled = true home = "" </code></pre></td></tr></table> </div> </div><h3 id="支持umami访问统计">支持umami访问统计</h3> 博客之前一直按「<a href="https://easonyang.com/2016/11/04/google-analytics-via-nginx/">使用Nginx将请求转发至Google Analytics实现后端统计</a>」一文的方式来实现请求统计。但这个方式的问题在于，由于不要求加载 JS ，很多非真实流量（主要为 RSS 阅读器的抓取）也会被统计进来。后来看到「<a href="https://reorx.com/blog/deploy-umami-for-personal-website/">搭建 umami 收集个人网站统计数据</a>」这篇文章，便也用 umami 搭建了一个轻量的统计能力。 even 主题自然没有对 umami 进行原生支持，我们需要做的是先找到一个包含 head 的模版并在 <code><head/></code> 标签中添加以下内容： <div class="highlight"><div class="chroma"> <table class="lntable"><tr><td class="lntd"> <pre tabindex="0" class="chroma"><code>1 2 3 </code></pre></td> <td class="lntd"> <pre tabindex="0" class="chroma"><code class="language-html" data-lang="html"> {{- if (in (slice (getenv "HUGO_ENV") hugo.Environment) "production") | and .Site.Params.umami.enabled -}} <script async defer data-website-id="{{ .Site.Params.umami.id }}" src="{{ .Site.Params.umami.js }}"></script> {{- end -}} </code></pre></td></tr></table> </div> </div>然后在配置中完成定义即可： <div class="highlight"><div class="chroma"> <table class="lntable"><tr><td class="lntd"> <pre tabindex="0" class="chroma"><code>1 2 3 4 </code></pre></td> <td class="lntd"> <pre tabindex="0" class="chroma"><code class="language-toml" data-lang="toml"> [params.umami] enabled = true id = "" # umami 统计 id js = "" # umami 的 JS 地址 </code></pre></td></tr></table> </div> </div>由于 even 主题没有提供可以直接拓展 <code><head/></code> 标签的模板，我的选择是将代码加到此前不得不重写的 <code>baseof.html</code> 中。不得不说，这个实现很丑陋，但成本确实也是最低的。 此外，为了避免本地启动时 umami 将本地请求也进行了统计并将 Referrer 识别为 localhost ，上文的实现中对环境做了判断，即正式生成站点时才会引入 JS 依赖来上报 umami ，本地运行则不引入。 <h3 id="自定义文章末尾页脚">自定义文章末尾页脚</h3> 此前在 Hexo 的 even 下我也对文章末尾进行了自定义。对于 Hugo 的 even 主题，改造成本最低的方式为重写 <code>/layouts/partials/post/copyright.html</code> 模板。 首先要和此前展现形式对齐的是「原文链接」。even 主题本身只支持将 Markdown 原文件地址作为文章链接，所以我们需要在该模板中仿照 <code>lionToMarkDown</code> 部分添加以下内容： <div class="highlight"><div class="chroma"> <table class="lntable"><tr><td class="lntd"> <pre tabindex="0" class="chroma"><code>1 2 3 4 5 6 </code></pre></td> <td class="lntd"> <pre tabindex="0" class="chroma"><code class="language-html" data-lang="html"> {{ if $.Site.Params.copyrightLink -}} <p class="copyright-item"> <span class="item-title">文章链接</span> <span class="item-content"><a class="link-to-markdown" href="{{ .Permalink }}" target="_blank">{{ .Permalink }}</a></span> </p> {{- end }} </code></pre></td></tr></table> </div> </div>因为暂时没有国际化需要所以文案是固定的中文，如果想更灵活些也可以仿照原实现中的 Markdown link 来做 i18n 。 随后只要在 <code>copyright.html</code> 的最后引入我们自定义的文末模板即可： <div class="highlight"><div class="chroma"> <table class="lntable"><tr><td class="lntd"> <pre tabindex="0" class="chroma"><code>1 </code></pre></td> <td class="lntd"> <pre tabindex="0" class="chroma"><code class="language-html" data-lang="html">{{- partial "post/post-footer.html" . -}} </code></pre></td></tr></table> </div> </div><h3 id="utterances适配">utterances适配</h3> even 主题本身是支持 utterances 的，但用于生成 issue 的唯一标识参数被主题写死为了 <code>issue-term="pathname"</code> 即根据 URI 路径生成，并没有暴露配置。而我在使用 Hexo 时该参数的值是 <code>issueTerm="title"</code> 即根据文章标题生成，不进行适配的话会丢失存量评论。 所以我们需要在 <code>/layouts/partials/</code> 目录下新建 <code>comments.html</code> 覆盖主题原实现。顺便地，我们可以把另一个参数 label 也改为可配置的，这样一来，生成的 Github issues 便可以自动加上 utterances 标签方便分类： <div class="highlight"><div class="chroma"> <table class="lntable"><tr><td class="lntd"> <pre tabindex="0" class="chroma"><code> 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 </code></pre></td> <td class="lntd"> <pre tabindex="0" class="chroma"><code class="language-html" data-lang="html">{{ if and .IsPage (ne .Params.comment false) -}}  {{- if .Site.Params.utterances.owner}} <script src="https://utteranc.es/client.js" repo="{{ .Site.Params.utterances.owner }}/{{ .Site.Params.utterances.repo }}" issue-term="{{ .Site.Params.utterances.issueTerm }}" label="{{ .Site.Params.utterances.label }}" theme="github-light" crossorigin="anonymous" async> </script> <noscript>Please enable JavaScript to view the <a href="https://github.com/utterance">comments powered by utterances.</a></noscript> {{- end }} {{- end }} </code></pre></td></tr></table> </div> </div>随后我们便可以在 <code>config.toml</code> 中对 utterances 按需进行配置： <div class="highlight"><div class="chroma"> <table class="lntable"><tr><td class="lntd"> <pre tabindex="0" class="chroma"><code>1 2 3 4 5 </code></pre></td> <td class="lntd"> <pre tabindex="0" class="chroma"><code class="language-toml" data-lang="toml"> [params.utterances] # https://utteranc.es/ owner = "" # Your GitHub ID repo = "" # The repo to store comments issueTerm = "title" # 新增配置，可按需选择 issue 生成时的唯一标识方式 label = "utterances" # 新增配置，可按需指定 issue label </code></pre></td></tr></table> </div> </div><h3 id="补齐底部社交图标">补齐底部社交图标</h3> 主题的社交图标使用的是托管于 iconfont 的私有实现所以直接拓展未支持的新图标较为困难。我在<a href="https://easonyang.com/2021/07/06/a-better-hexo-theme-even/">记hexo-theme-even主题优化</a>一文中提到了相同的问题，文中最终选择了使用 Font Awesome 来解决，对于 Hugo 的 even 主题我们也如法炮制进行处理。 首先，在 <a href="https://fontawesome.com/start">Font Awesome</a> 官网下载依赖并放置于 <code>/static</code> 目录下。例如我使用的是引入所有图标 JS 的方式，则最终路径为 <code>/static/js/fontawesome.all.min.js</code> 。然后在 <code>config.toml</code> 配置中引入该 JS 文件： <div class="highlight"><div class="chroma"> <table class="lntable"><tr><td class="lntd"> <pre tabindex="0" class="chroma"><code>1 2 </code></pre></td> <td class="lntd"> <pre tabindex="0" class="chroma"><code class="language-toml" data-lang="toml">[params] customJS = ["fontawesome.all.min.js"] </code></pre></td></tr></table> </div> </div>接着，我们在 <code>/layouts/partials/</code> 目录下新建 <code>footer.html</code> 覆盖主题原实现并保留原实现的其他代码，只对 <code>social-links</code> 部分进行如下修改： <div class="highlight"><div class="chroma"> <table class="lntable"><tr><td class="lntd"> <pre tabindex="0" class="chroma"><code> 1 2 3 4 5 6 7 8 9 10 11 12 </code></pre></td> <td class="lntd"> <pre tabindex="0" class="chroma"><code class="language-html" data-lang="html"><div class="social-links"> {{- range $name, $config := .Site.Params.social }} {{- if $config.path }} <a href="{{ $config.path | safeURL }}" class="iconfont" title="{{ $name }}"><i class="{{ $config.icon }}"></i></a> {{- end }} {{- end }} {{ if .Site.LanguagePrefix -}} <a href="{{ .Site.LanguagePrefix | absURL }}/index.xml" type="application/rss+xml" class="iconfont" title="rss"><i class="fas fa-rss"></i></a> {{- else -}} <a href="{{ .Site.RSSLink }}" type="application/rss+xml" class="iconfont" title="rss"><i class="fas fa-rss"></i></a> {{- end }} </div> </code></pre></td></tr></table> </div> </div>最后在 <code>config.toml</code> 中添加需要的图标配置即可。<code>icon</code> 即图标的完整 <code>class</code> 属性，<code>path</code> 即需要跳转的链接地址。需要注意的是，主题的原逻辑为了实现多语言，将 RSS 图标的逻辑隔离在了通用逻辑之外。这里也保留了原实现，即 RSS 图标是默认出现且不可去除的。如果不需要 RSS 则可以对上面的代码再进行修改，以删除独立的 RSS 逻辑。 <div class="highlight"><div class="chroma"> <table class="lntable"><tr><td class="lntd"> <pre tabindex="0" class="chroma"><code>1 2 3 4 5 6 7 </code></pre></td> <td class="lntd"> <pre tabindex="0" class="chroma"><code class="language-toml" data-lang="toml"> [params.social] a-email = { title = "Email", icon = "fas fa-envelope", path = "" } b-twitter = { title = "Twitter", icon = "fab fa-twitter", path = "" } c-github = { title = "Github", icon = "fab fa-github", path = "" } d-weixinOfficialAccount = { title = "微信公众号", icon = "fab fa-weixin", path = "" } e-telegram = { title = "Telegram", icon = "fab fa-telegram", path = "" } f-search = { title = "Search", icon = "fas fa-search", path = "" } </code></pre></td></tr></table> </div> </div>除了 Font Awesome ，最近我还看到了<a href="https://tabler-icons.io/">tabler ICONS</a>这个库，直接支持 SVG 同时还是 MIT 协议的开源项目，也值得一试。 此外，由于我们已经覆盖了 footer 模板，那我们也可以对其他内容也进行自定义，比如将友情链接放置于 footer 等，下文的总字数统计也同样均基于自定义的 <code>footer.html</code> 进行处理。 <h3 id="支持总字数统计">支持总字数统计</h3> even 主题自带每篇文章的字数和预计阅读时间统计，但却没有之前我借助 <a href="https://github.com/willin/hexo-wordcount">hexo-wordcount</a> 所实现的全站文章字数统计。检索网络后找到了这么一篇文章 <a href="https://immmmm.com/hugo-total-count/">Hugo 总文章数和总字数</a> ，照猫画虎在 <code>footer.html</code> 中添加以下内容： <div class="highlight"><div class="chroma"> <table class="lntable"><tr><td class="lntd"> <pre tabindex="0" class="chroma"><code> 1 2 3 4 5 6 7 8 9 10 </code></pre></td> <td class="lntd"> <pre tabindex="0" class="chroma"><code class="language-html" data-lang="html"> {{ if .Site.Params.countAllWords.enabled }} {{$scratch := newScratch}} {{ range (where .Site.Pages "Kind" "page" )}} {{$scratch.Add "total" .WordCount}} {{ end }} <span style="display: block;"> {{ .Site.Params.countAllWords.prefix }} {{$scratch.Get "total" }} {{ .Site.Params.countAllWords.suffix }} </span> {{ end }} </code></pre></td></tr></table> </div> </div>随后在 <code>config.toml</code> 中对相关参数进行配置即可： <div class="highlight"><div class="chroma"> <table class="lntable"><tr><td class="lntd"> <pre tabindex="0" class="chroma"><code>1 2 3 4 </code></pre></td> <td class="lntd"> <pre tabindex="0" class="chroma"><code class="language-toml" data-lang="toml"> [params.countAllWords] enabled = true prefix = "共计" suffix = "字" </code></pre></td></tr></table> </div> </div>除了以上逻辑，还可以通过改变 <code>range</code> 的查询范围来按需限定需要进行总字数统计的页面集合。另外配置中的固定文案比较生硬，可以考虑加入 i18n 相关实现来满足多语言切换的需要。 <h2 id="总结">总结</h2> 天下武功，唯快不破，Hugo 的速度确实让我印象深刻。但对于从 Hexo 迁移而来，同时还对 Hexo 有很多自定义配置的用户来说，迁移过程中的兼容和适配的成本其实是不低的，实际上目前的迁移仍未实现「基于 LeanCloud 的阅读计数」和「推荐阅读」两项功能的兼容。此外，无论是 Hexo 还是 Hugo ，其主题的深度自定义修改都比较麻烦，以后还是要考虑自己实现一套主题（明年一定）。

2022/8/9

旁路由的原理与配置一文通

最早听到旁路由这个词是在 2020 年折腾 N1 的时候，这台单网口的小盒子只能用网上所说的旁路由方案接入局域网来实现期望的功能。现在回想起来，旁路由这个词有可能就是在那个发烧友大量折腾斐讯 N1/P1/T1 的时期被发明出来的。你没办法在发烧友圈子外的互联网及各种学术材料中找到对旁路由的描述和定义，当然也找不到合适的英文翻译（导致这篇文章的 slug 定义困难）；从拓扑上看，旁路由更像是杂糅了二级路由和透明网关的概念，除了实体确实多接了根网线放在主路由旁边，其本身并没有真正地开启一条旁路，做的事情也基本可以和网关的定义对齐。 不过，由于这个说法主要集中于网友的交流讨论之中，而且几年来在有相关需求的广大用户中被广为接受，所以只要这个词不变为一个学术概念，那我倒也不觉得有什么不妥。下文也仍然会用「旁路由」一词来指代在此类拓扑结构中担任代理网关角色的路由器。 此外，本文对于原理的解释偏多且为新手向，对于已经熟知相关概念的读者则可以将本文作为 cheat sheet 食用。 <h2 id="旁路由的适用场景">旁路由的适用场景</h2> 有人认为旁路由的加入（手动指定方式）不会在其出现问题时影响整个网络的可用性，所以应该把非路由功能都交给旁路由来实现。但实际上如果仅仅是为了达成这个目标，那在主路由上直接分流会是个更好的方案，因为这样不仅会大量减少疑难杂症的出现，而且还可以通过设置 fallback 的方式进一步提升网络的可用性。 所以我认为旁路由实际上只适用于一个场景，那就是出于某种考虑，主路由不能被替换或被大量修改，而主路由的固件又不能满足功能诉求，这时候旁路由便是一个可选的解决方案。 <h2 id="旁路由的原理">旁路由的原理</h2> 网上关于旁路由的配置教程多如牛毛，其中大部分是基于 F 大的 N1 OpenWrt 固件使用教程来写的，也有很多是结合了自己的踩坑经验的细化版本。由于版本太多、完整的说明太少，而且大部分没有讲清楚教程的环境上下文和原理，导致按照这些教程来配置的用户往往不得不一遍遍地折腾重试，甚至会遇到逐步配置最终却断网、访问不了部分网站等令人头疼的问题。 授之以鱼不如授之以渔，为了能彻底讲清楚旁路由该如何配置，我们暂且不谈具体步骤，而是先搞明白旁路由的运作原理。 <h3 id="名词解释">名词解释</h3> 由于计算机网络的术语在不同时期、不同环境下，对于细节的含义其实有比较大的差异，故首先我们先定义好下文中将使用到的各类专有名词的含义，以免出现信息不对称的情况。同时为了方便理解，我们也尽量和 OpenWrt 的名词对齐，并尝试与现实生活场景进行类比。 <ol> <li>路由：将数据从源地址传输到目的地址的行为。可以看出，这个行为抽象涵盖了两个动作，一是找到地址、二是转发数据。可以类比为网购时快递公司将商品从卖家发送给买家的过程。</li> <li>路由表：可以简单理解为路由过程中的地址关联信息的合集，也就是现实中发货地址和收货地址的映射关系。</li> <li>路由器：本文中指家用的、具备路由功能的实体网络设备，其本身并不一定需要真的承担或只承担路由功能，可以抽象理解为就是一台普通的电脑或服务器。当然，它也可以是一个容器实例、一个虚拟机。对应到现实中就是快递公司。</li> <li>接口：这里特指网络接口，指两个网络设备或协议层的连接点。现实中连接路由器时，wan/lan 不同的网线插槽其实就可以理解为接口。只不过接口并不一定是物理实体，所以我们才会在 OpenWrt 的接口设置里看到甚至新增许多物理设备上所没有的接口。</li> <li>网关：这里特指网络中的网关，负责执行数据转发的某个抽象设备。这里可能容易与路由器的功能混淆，毕竟路由器如果用来做路由似乎也是在做转发的工作。实际上这是由于术语的历史使用缺少规范导致的边界不够清晰，可以粗略理解为承担路由功能的路由器就是网关，但网关不一定是只能由路由器担任。</li> <li>IP：本身指 IP 协议，本文为方便也可能将其作为 IP 地址的简称，且默认为 IPv4 。本节所有的名词其实都是基于 IP 协议运作的，而 IP 地址即上文各类「地址」的实际值。可以理解为你用于发送和接收快递的门牌号。</li> <li>DHCP：IP 地址的管理和分配协议，本文中不单单指协议本身，还指负责执行该协议的设备。可以理解为给你分配门牌号的物业，只不过这个门牌号是动态变化的。</li> <li>DNS：上文说到数据的传输需要源地址和目的地址，而这个地址就是 IP 地址。但由于 IP 地址难以记忆，所以才会有了可以作为 IP 地址别名的域名，而 DNS 就是负责进行域名和 IP 地址映射转换的系统。本文中 DNS 也指代负责运行该系统的设备。</li> <li>NAT：出于各种考虑，局域网与因特网的 IP 地址是隔离的，NAT 可以理解为内外网 IP 地址转换的流程。类比网购，相当于快递公司把快递送到附近快递站，快递站的快递员再把货物送到你家门口的流程。</li> <li>SNAT：NAT 的一种，本质上是在修改网络包的源地址，目的是可以强制网络包返回时经过期望的地址。可以理解为支付宝的作用，即钱虽然表面上是点对点转账的，但经过支付宝后，支付宝就要求相关转账信息的回执必须由它中转一次再告知转账发起人。</li> </ol> <h3 id="网络拓扑">网络拓扑</h3> <img src="https://gmiimg.com/ee0724cd54a8e17f32a0971e2f4969fc.png" alt="旁路由架构的网络拓扑图"> 可以看到，无论如何配置，我们都需要保证数据按图中的拓扑进行流转，才能实现我们所希望的只在旁路由增加功能而不修改主路由的目的。由于流量（至少上行流量）总会流经旁路由，所以旁路由实质上就是一层透明代理。 <h3 id="工作原理">工作原理</h3> 那么我们该怎么实现这样的网络拓扑呢？让我们先来看下数据在网络的更底层是如何流转的。 <img src="https://gmiimg.com/d247c8b3d92cd3990245b622d5e7aa56.png" alt="旁路由架构的数据流转示意图"> 从图中可以看到，当我们从手机等终端设备发出一个数据包时，数据包总是由我们的终端设备经由网关路由至目的地址，目的地址返回数据时也是相同的路径。这是因为终端设备本身通常是不具备路由功能的，单单一个路由表终端设备就搞不定。 既然数据必然经过网关，那么我们只要强制把旁路由作为终端设备对外数据交互的第一层网关即可。至此旁路由的工作原理其实就已经解释清楚了，即在另一台路由器上实现的基于网关的透明代理。而网上各式各样的教程其实都是在教我们解决如何配置网关的问题。 在这一章节还需要说明的是为什么各个教程都要求我们把旁路由的 IP 配置在和主路由相同的 IP 网段。所谓的 IP 网段实际上就是子网，同一子网下的主机（设备）可以直接通信，跨子网则需要通过某种形式转换后才能通信，而这些转换虽然可行但比较复杂，在旁路由这个场景下显然是没有必要的。本着不改变原有网络拓扑的原则，旁路由自然也要配置在和主路由及其他设备相同的子网才行。 <h2 id="旁路由的配置">旁路由的配置</h2> 那么我们该如何配置网关以让数据按上文的工作原理进行流转呢？ <h3 id="一旁路由的网关设置">（一）旁路由的网关设置</h3> 首先我们先来解决旁路由的网关问题。在上文的拓扑图中我们可以看到，旁路由虽然挂着路由器的名字，但它本质上也是网络链路中的一个节点，因此它也需要请求上层网关才能完成数据流转。而主路由是这个网络拓扑的出口，所以旁路由的网关自然要配置为主路由的 IP 地址。这一项配置是必须且不会随终端网关配置方式的变化而改变的，无论如何指定网关请求旁路由，旁路由本身都要依赖此配置才能完成正常的流量转发。 此外，还有子网掩码需要进行配置。前面有提到，在同一子网内的主机之间才能直接通信，而 IP 和子网掩码相组合便能确定设备当前所在的子网。旁路由并不改变网络拓扑，所以需要和主路由在同一子网内。因此将旁路由的子网掩码配置设置为主路由的子网掩码即可。同理，下文的所有子网掩码配置也均需要与主路由的保持一致。 <h3 id="二旁路由的dhcp配置">（二）旁路由的DHCP配置</h3> 虽然配置了网关后数据流转图中的左半边已经成型，但如果不对旁路由的 DHCP 进行配置，实际上会导致各种各样的疑难杂症或直接无法联网。 原因在于 DHCP 使用了 UDP 协议，UDP 是没有连接的，如果主路由和旁路由同时开启 DHCP，则任意一个 DHCP 服务器都可能会应答终端的申请，进而导致 IP 下发和路由表的混乱造成各种无法连接的疑难杂症。当然，我们可以将两个 DHCP 的子网网段拆分开来解决共存问题，但这个行为在旁路由场景下并没有实际意义。 因此我们需要保证网络中只有一个设备承担 DHCP 功能，出于不改变原网络拓扑和避免无意义 NAT 的考虑，我们通常选择关闭旁路由的 DHCP 功能（对应到 OpenWrt 则选择「忽略此接口」）。 <h3 id="三终端网关配置">（三）终端网关配置</h3> 对于手机、电脑等终端，我们的目标是将其网关配置为旁路由的 IP 。实现方案很多，成本较低的主要为以下两种。 <h4 id="手动指定">手动指定</h4> 顾名思义，只需要在终端设备的网络设置中将网关手动配置为旁路由即可。以 iOS 系统为例： <img src="https://gmiimg.com/3f58fee3de6f48c714173df4f26aac2e.jpg" alt="iOS 网络配置界面"> 手动填写一个网络上未被占用的 IP 地址，而子网掩码以主路由为准，网关则填写旁路由的 IP 地址。 手动指定的好处在于完全不影响原网络的使用，设备按需配置是否使用旁路由作为网关以实现特定功能。当旁路由故障时，未手动指定的设备仍能正常上网。 缺点在于操作烦琐。手机、电脑还好，但电视或根本没有屏幕的设备设置起来就会很麻烦。 <h4 id="依赖dhcp指定">依赖DHCP指定</h4> DHCP 除了可以管理 IP 的分配，还会下发网关和 DNS 服务器信息，因此我们还可以借助 DHCP 的这一机制来为所有终端统一设置网关，而不再需要逐个手动修改。 前面提到，我们关闭了旁路由的 DHCP 功能，因此这个统一下发的工作就要交给主路由来完成。只需要在主路由的 DHCP 配置中将网关配置为旁路由的 IP 地址即可。 <img src="https://gmiimg.com/fc7f640460453d3eb1b6aa3d5c849c5c.png" alt="OpenWrt 的 DHCP 配置界面"> 以 OpenWrt 为例，将主路由 DHCP 下发的网关配置为旁路由 IP 地址即可（3 表示网关，6 表示 DNS 服务器地址）。 不过有些路由器的默认固件没有开放该配置项，对于这些设备，除非可以 SSH 连接后手动改配置，不然无法使用此种指定方式。 这种方式的好处显而易见，一次配置全家受用；缺点在于当旁路由出现故障时，所有连接的设备都会无法上网。 <h3 id="四dns的配置">（四）DNS的配置</h3> 细心的读者可能发现了上文只提到了网关的配置，但未提到很多教程中的 DNS 配置。实际上单单就旁路由本身来说，网关配置完成后整个网络拓扑就已经搭建完毕了。但对于一些特定诉求，比如依赖旁路由进行统一的 DNS 劫持（很多功能的底层都依赖于此），则需要将对应位置的 DNS 也配置为旁路由的 IP 以将域名解析工作也完全交由旁路由处理。 <h2 id="配置步骤总结">配置步骤总结</h2> <h3 id="手动指定方案">手动指定方案</h3> <ol> <li>为旁路由配置和主路由同网段的静态 IP 地址，同时将旁路由的网关和 DNS 指向主路由，子网掩码与主路由保持一致。</li> <li>旁路由关闭 DHCP 服务。</li> <li>在主路由防火墙开启 SYN-flood 防御的情况下，关闭旁路由防火墙的 SYN-flood 防御（可选）。</li> <li>在需要接入旁路由的终端设备中，将网关和 DNS 配置为旁路由 IP 地址，配置同网段的 IP 地址和与主路由相同的子网掩码。</li> </ol> <h3 id="dhcp下发方案">DHCP下发方案</h3> <ol> <li>为旁路由配置和主路由同网段的静态 IP 地址，同时将旁路由的网关和 DNS 指向主路由，子网掩码与主路由保持一致。</li> <li>旁路由关闭 DHCP 服务。</li> <li>在主路由防火墙开启 SYN-flood 防御的情况下，关闭旁路由防火墙的 SYN-flood 防御（可选）。</li> <li>在主路由的 DHCP 配置中，将其下发的网关和 DNS 配置为旁路由的 IP 地址。</li> </ol> <h2 id="疑难杂症的解决">疑难杂症的解决</h2> 虽然配置步骤看上去很简单，但很多人在实际使用中都会遇到逐步配置却上不了网或网络慢的问题，这里挑几个典型案例来解析。 <h3 id="一该不该设置iptables的masquerade">（一）该不该设置iptables的MASQUERADE</h3> 这可能是争议最大的一条，有人说这条规则加上后影响性能而且没意义，但也有很多人表示不配这条就是连不上网（大多为连接不上国内网络）。 这条规则的作用本质上是在旁路由上做 SNAT，只不过修改的地址不需要指定而是动态获取旁路由对应接口网卡的 IP 地址，在 OpenWrt 里被称为「IP 伪装」。 <img src="https://gmiimg.com/2d0c6641e3f951044153129b3176ab66.png" alt="配置 MASQUERADE 后的数据流转示意图"> 单从旁路由的网络拓扑来说，这条规则确实没意义，因为主路由作为对外出口必做 NAT，但旁路由本身就在局域网内且只是链路上的一环，没有必要再对内网 IP 进行耗费性能的 NAT 操作。 但不要忘了，理论和现实是两回事，物理网络拓扑中的不同设备、不同固件都有可能产生各种奇怪的兼容问题。我自己倒是没有遇到过该问题，但检索网友们的各种帖子，大概可以分为以下几种原因： <ol> <li>主路由固件数据包处理问题：部分路由器（似乎主要为国产品牌）的无线网在桥接和 iptables 处理过程中，当旁路由将国内流量重新转发回主路由时，主路由根据流中的首个数据包的状态做判断导致后续数据包未进行 NAT 就直接访问了互联网。<a href="https://blog.csdn.net/qq1337715208/article/details/122271608">这篇文章</a>对此有比较详细的讲解（CSDN 也是有很多好文章的）。</li> <li>主路由 NAT 硬件加速导致的问题：可能是由于硬件加速流程对数据包的处理出现了类似于原因 1 的问题导致无法正确完成数据交互。由于硬件加速本质上是在运行特殊驱动，而各家厂商的该驱动几乎都是闭源的，所以网上也没见到有探究深层原因的资料。这种情况下把硬件加速关闭即可（会一定程度牺牲主路由 NAT 性能）。</li> <li>IP 和 MAC 校验机制导致包被丢弃的推论：由旁路由的网络拓扑可知，配置网关后上行流量必然经过旁路由，但在旁路由不进行 NAT 时数据包中的 IP 仍然是终端设备的，所以理论上下行数据并不会经过旁路由而是由主路由直接转发至终端。显然，由于旁路由的存在，IP 地址和 MAC 地址在某个环节会有不匹配的情况，如果主路由对此有校验，那数据包就会被丢弃掉。但这也只是个推论没有证据佐证，同时由于网络可能的复杂性，主路由通常也不会主动做这种校验。</li> </ol> MASQUERADE 配置其实并没有定向地去解决上面这些具体问题，而是通过 NAT 来隐藏终端设备、只向主路由暴露旁路由 IP 的方式，一刀切地避免了上述原因导致的问题。但由于上下行流量都会经过旁路由，所有流量都会被二次 NAT 和二次转发，网络的吞吐会有不小的下降，直观感受就是下载速度变慢了。 所以比较理想的策略是，先不加 MASQUERADE 规则观察是否有问题（尤其是国内流量），如果确实有问题，在权衡可以接受性能的损失后再配上该规则。 <h3 id="二lan和wan是否需要绑定">（二）LAN和WAN是否需要绑定</h3> 具体操作是取消桥接，再设置 WAN 和 LAN 共用同一个网卡（如 eth0 ）。这个操作其实和 MASQUERADE 规则的效果类似，因为绑定后经过 WAN 的流量必然会被 SNAT 。适用于确实遇到了疑难杂症且能接受性能损失场景下的备选方案。 <h3 id="三是否需要关闭旁路由桥接">（三）是否需要关闭旁路由桥接</h3> 在许多教程里，这个操作和添加 MASQUERADE 规则是配套的。但桥接与否实际上并不会影响整体的网络拓扑，这看上去又是一项没有意义的配置。我猜测可能是网上流传的添加 MASQUERADE 规则的方式是下面这条固定命令： <div class="highlight"><div class="chroma"> <table class="lntable"><tr><td class="lntd"> <pre tabindex="0" class="chroma"><code>1 </code></pre></td> <td class="lntd"> <pre tabindex="0" class="chroma"><code class="language-shell" data-lang="shell">iptables -t nat -I POSTROUTING -o eth0 -j MASQUERADE </code></pre></td></tr></table> </div> </div>也就是要求 SNAT 时从 eth0 网卡动态获取 IP 。而在桥接模式下，MASQUERADE 时是需要从 br-lan （常见的桥接后的默认网卡名称，也可能是其他名称，要视实际情况而定）获取 IP 的，直接复制粘贴上面的命令会导致 IP 伪装失败。所以只要把 -o 参数的值改为 br-lan 即可： <div class="highlight"><div class="chroma"> <table class="lntable"><tr><td class="lntd"> <pre tabindex="0" class="chroma"><code>1 </code></pre></td> <td class="lntd"> <pre tabindex="0" class="chroma"><code class="language-shell" data-lang="shell">iptables -t nat -I POSTROUTING -o br-lan -j MASQUERADE </code></pre></td></tr></table> </div> </div>但似乎确实有网友不取消桥接就无法联网，这种情况大概率是旁路由固件对桥接模式的处理有问题（多见于 ARM 架构的固件，这类固件通常要做很多的魔改适配），如果真的遇到这种情况的话则确实可以取消桥接尝试下，毕竟大多数情况下旁路由内部的桥接也没什么实际意义，去掉后由于少了流量判断流程可能还会有非常微小的性能提升。 至于 N1 这种自带无线功能但实际上没人用的设备，在关掉无线后，确实可以顺便取消掉没有意义的桥接。只是在 OpenWrt 取消桥接保存配置时，要确定选中了有线网卡对应的接口比如 LAN/eth0 ，不然如果后台的前端存在体验问题自动选择了 wlan ，那保存后路由器可就直接失联了。 <h3 id="四是否需要设置dhcp强制">（四）是否需要设置DHCP强制</h3> 如果我想通过 DHCP 下发网关但又不想改变主路由的原配置该怎么办呢？在 OpenWrt 的接口 DHCP 配置中有一个选项叫做「强制」，勾选后，此设备会忽略网络上已经存在的 DHCP 服务，强制启动本机的 DHCP 服务，所以似乎我们只需要在旁路由上配置此选项，并在旁路由 DHCP 中配置好网关，主路由不做任何变更，即可实现本段开头的诉求。 但上文提到同一子网中只能有一个用于分配指定网段的 DHCP 服务，因此旁路由强制开启 DHCP 后，还需要主路由具备主动判断网络情况停止提供 DHCP 服务的能力，这个流程才能真正运转起来。但并不是所有的路由器和固件都支持这个能力，目前来看 OpenWrt 作为主路由固件时可以正确检测并停用 DHCP ，其他固件则需要在使用时做下兼容性测试。从工程角度上讲，由于这样的操作过于依赖外部能力，属于和外部组件产生了强耦合，不利于未来维护，故不太推荐此种方案。 <h3 id="五旁路由的某些功能无法使用">（五）旁路由的某些功能无法使用</h3> 各种组件内部实现大不相同，如果某个组件的代码对网络结构做了强限定（如上文所说的校验 IP 和 MAC 的匹配关系），那旁路由的加入可能就会打破组件预期的网络结构导致其无法运行。这种情况在组件本身不做适配时基本无解，只能尝试下开启 MASQUERADE 等配置，看看多加一层 NAT 后的网络拓扑是否能符合组件要求，但代价同样是会牺牲性能。 <h3 id="六是否应该关闭旁路由防火墙的syn-flood防御">（六）是否应该关闭旁路由防火墙的SYN-flood防御</h3> SYN-flood 是一种常见的攻击方式，SYN 指 TCP 建连三次握手中的第一步报文，flood 指大量发起该步骤的报文。由于 TCP 的实现原理要求服务端接收到 SYN 报文后回复客户端 SYN+ACK 报文表明请求被接受，并在一段时间内等待客户端回复最终的 ACK 报文，那么大量的 SYN 报文就会导致服务端出现大量等待最终资源耗尽挂掉，而攻击者并不需要真的完成建连，只要持续发送 ACK 包即可。 那路由器的防火墙又是如何作防御的呢？以 OpenWrt 为例，虽然 OpenWrt 的防火墙配置已经迁移到了 fw3 ，但翻看代码历史我们就会看到当时 OpenWrt 直接基于 iptables 的早期实现： <div class="highlight"><div class="chroma"> <table class="lntable"><tr><td class="lntd"> <pre tabindex="0" class="chroma"><code>1 2 3 4 </code></pre></td> <td class="lntd"> <pre tabindex="0" class="chroma"><code class="language-shell" data-lang="shell">$IPTABLES -N syn_flood $IPTABLES -A syn_flood -p tcp --syn -m limit --limit $rate/second --limit-burst $burst -j RETURN $IPTABLES -A syn_flood -j DROP $IPTABLES -A INPUT -p tcp --syn -j syn_flood </code></pre></td></tr></table> </div> </div>即借助 iptables 的 SYN 限流能力进行防御，同时此配置位于 default 配置中，会在 NAT 等具体网络操作之前执行。 对应到主路由，wan 口接收到攻击流量后便会进行限流，攻击者无法直接向后攻击到内网主机，那么同样为内网主机的旁路由自然理论上也就不会被攻击到。 但对于旁路由来说，理论上网络中的所有上行流量都会通过它来转发，那当流量超过防火墙的限流阈值时便会触发拦截，进而在终端上表现为网络时断时续。所以在主路由已开启 SYN-flood 防御的情况下，旁路由关闭该配置可以避免出现可能的网络不稳定问题。 <h2 id="旁路由与ipv6">旁路由与IPv6</h2> IPv6 在家用网络中通常默认是没有 NAT 转换流程的，同时其动态地址配置方案比 IPv4 要复杂得多，比如 SLAAC 和之前的 DHCP 可以说完全不是一套机制，而 DHCPv6 又分有状态和无状态两类。而前面提到，我们实现旁路由网络拓扑的过程，其实就是在指定一个具备透明代理功能的网关的过程，但 SLAAC/DHCPv6 都没有提供网关下发能力，终端设备总是会以其所交互的主机作为网关，同时大多也不支持直接修改网关。此外，运营商不支持 DHCPv6-PD 、IPv6 子网限定范围等情况，都使得旁路由支持 IPv6 非常困难，在不同场景、不同网络下要面临不同的配置，甚至无方案可配置。 网上比较流行的旁路由 IPv6 实现是个曲线救国的折中方案，即先开启主路由的内网的 IPv6 地址分配进而让旁路由获得内网 IPv6 地址，随后再通过在旁路由开启一个 DHCPv6-Client 的方式获取到公网的 IPv6 地址，这样便可以将主路由的 DHCPv6 下发的 DNSv6 配置为旁路由的 IPv6 地址。此时除了 DNSv6 的解析是在旁路由进行，其他流程仍按原链路直连。而在需要分流的场景中，OpenWrt 的相关组件可以选择在解析域名时放过不需要处理的 IPv6 流量让其正常解析出 AAAA 记录，而对域名名单中的流量强制解析为 A 记录以继续走 IPv4 协议，从而实现和此前的类似的旁路由功能。 当然，这种解析实际上依赖于组件的能力。如果组件并不支持，那通过各种方式强制定义 IPv6 的路由表保证相关 IPv6 流量必然经过旁路由也是一种解决方案。不过无论哪种实现，由于不借助网关配置，其实都已经和本文的旁路由不相关了。 此外，还有种方案是通过 radvd 等支持配置路由单播和优先级的工具，用更高的优先级来指定终端的 IPv6 路由（可以简单理解为 IPv4 的网关），这样就替代了 IPv4 下手动配置或 DHCP 下发网关对应的功能，完美满足本文所说的旁路由网络拓扑，同时对 IPv6 动态地址配置方案的要求很低，但要求终端设备支持路由优先级配置。 <h2 id="总结">总结</h2> 旁路由实际上是运行透明代理功能的网关，有人认为这个概念很民科，但我并不认同，毕竟它只是在通过已有的能力来解决特定场景的问题，和我们写代码、做产品没有本质区别，而「旁路由」这个名词也不过是个约定俗成的叫法而已，不应该被批判。 另一方面，由于旁路由在不同设备、不同网络环境有可能遇到很多奇怪问题，其实对于非专业用户来说付出的时间成本很有可能会远大于直接替换主路由的成本。但生命不息，折腾不止，如果是为了收获折腾的快乐、学习到新的知识，那又有何不可呢？

2022/8/2

Eason Yang's Blog

2022年终总结

把Notion变为个人网站

再见Hexo——从Hexo迁移至Hugo

旁路由的原理与配置一文通

2021数码消费年终总结

该不该使用关系型数据库的物理外键

公司基因与工作选择

如何辨别KPI驱动的技术项目

基于Revue建立个人Newsletter

重新定义PPT的Slidev

故障处理SOP是废话吗？

Gracias Messi

投资、投机与赌博——我的韭菜经历回忆

如何避免被老代码坑

简易增强版hexo-theme-even

2021常用临时网盘汇总

为何后端限流如此之难

flomo-cli中文说明

静态博客的同步和备份方案

记hexo-theme-even主题优化