Hugo&Eureka&Nginx

2020-12-17

6 min read

tools , web

当前文章主要介绍使用 Hugo&Nginx 搭建自己静态博客网站的方法。实现可以在公网访问的个人网站至少需要如下工具与流程：

个人域名，直接使用 IP 进行访问相对比较麻烦
个人服务器，比如阿里云的 ECS/虚拟主机；腾讯云服务等等。使用虚拟主机比较划算，但可控性比 ECS 等服务器要差
域名与网站备案，如果个人网站在国内，那么这个过程是必需的。国内未备案的网站一般是不允许访问的，阿里云或者腾讯云等平台如果监测到域名未备案，将会把域名主页重定向到提醒页面，此时网站是无法正常使用的

说明

Hugo 是使用 Golang 编写的静态页面生成工具，其他类似工具还有使用 Ruby 编写的 Jekyll，使用 Python 实现的 Pelican 等。使用 Hugo 可以将 markdown 转换为静态 HTML 页面，然后可以以静态网站的形式发布

Hugo 有着不错的可扩展性且提供了大量网页模板，使用不同网页模板可以生成不同风格的静态页面。Eureka 是我比较喜欢的一个模板

使用 Hugo 生成的静态页面一般在 Hugo 目录下的 pubilc 子目录中，拷贝这个目录中的内容到线上 Nginx 静态页面目录下，然后就可以通过浏览器进行访问了

Hugo

参考资料

hugo 中文文档，https://www.gohugo.org/
官方 quickstart，https://gohugo.io/documentation/

常用命令

hugo new site /path/to/site         # 在指定位置生成 hugo 工程
hugo new about.md                   # 生成 about.md 文件，默认在工程子目录 content 内
hugo -D                             # 生成 draft 为 true 的页面
hugo -d /home/hjiahu/www/static_web # 指定静态文件保存位置

重要概念

Draft

默认 front matter 中的 draft 为 true，使用 Hugo 生成静态页面时 draft 为 true 文章是不会被处理，即发布后是看不到的

defaultMarkdownHandler

Hugo 支持多种不同的 Markdown 解析库，比如 Pandoc/GoldMark 等等，可以通过配置选择

如果使用 Pandoc，需提前安装 Pandoc：sudo apt install pandoc ，并在config.yaml 文件中做如下配置

markup:
  ....
  defaultMarkdownHandler: pandoc
  ...

添加 MathJax 支持

Hugo 默认使用 GoldMark 解析 Markdown 文件，因为 GoldMark 不支持复杂的 Markdown 数学表达式，比如 $\mathbf{v}*_{1}=\left[\begin{array}{r}-1* *\\**1\end{array}\right]$

按照官方的说法，markdown 使用下划线给字符添加黑体与斜体，而 lex 使用下划线表示下标，二者冲突了

Goldmark 有插件可以解决这个问题，但不知为何 0.8 版没有使用 goldmark-mathjax 这个插件，所以为了完美支持 markdown 数学表达式，需添加这个插件并编译，执行过程如下：

修改 go proxy，使用国内的镜像更快：go env -w GOPROXY=https://goproxy.cn,direct
1. 使用这条命令需要 go 版本大于等于 1.13
git clone https://github.com/gohugoio/hugo.git
修改 markup/goldmark/convert.go 文件
1. 添加依赖，在 import 里添加：mathjax "github.com/litao91/goldmark-mathjax"
2. 注册插件，在调用 goldmark.New 之前添加：extensions = append(extensions, mathjax.MathJax)
编译：go build -o hugo main.go
拷贝可执行文件到 PATH 路径下即可

Eureka

参考资料

中文官方文档：https://www.wangchucheng.com/zh/docs/eureka/
github：https://github.com/wangchucheng/hugo-eureka

配置

Eureka 支持一些自定义的配置，这些内容在官方文档中叙述的比较详细，这里就不再重复了。举个例子：

在 markdown 文件的 front matter 中置 toc 为 true，则静态页面会自动显示当前文章的目录

添加 Mermaid 支持

通过修改 themes/eureka/layouts/partials/footer.html 可以使得 Eureka 支持 mermaid，将下面内容添加到 footer.html 中的 </div> 之前：

<script src="https://cdn.bootcdn.net/ajax/libs/jquery/3.5.1/jquery.js"></script>
<script src="https://cdn.bootcdn.net/ajax/libs/mermaid/8.8.3/mermaid.min.js"></script>
<script>
	$(".language-mermaid").addClass("mermaid");
</script>

Nginx

Nginx 是非常著名的 web 工具，其功能多样，这里我们只使用其静态 Web 功能。参考这里可以为部分目录添加登录认证功能

Linux 下 Nginx 可以通过命令行进行安装，请参考其他博文，这里不再重复

使用命令行安装的 Nginx，其配置一般位于 /etc/nginx/nginx.conf，下面是配置示例：

user www-data;
worker_processes auto;
pid /run/nginx.pid;
include /etc/nginx/modules-enabled/*.conf;

events {
    worker_connections 768;
    # multi_accept on;
}

http {

    sendfile on;
    tcp_nopush on;
    tcp_nodelay on;
    keepalive_timeout 65;
    types_hash_max_size 2048;

    include /etc/nginx/mime.types;
    default_type application/octet-stream;

    # SSL Settings
    ssl_protocols TLSv1 TLSv1.1 TLSv1.2; # Dropping SSLv3, ref: POODLE
    ssl_prefer_server_ciphers on;
    access_log /var/log/nginx/access.log;
    error_log /var/log/nginx/error.log;

    gzip on;

    server {  
        listen 443;
        server_name abc.xyz;
        ssl on;
        # 这里是 SSL 本地加密文件的配置，如果不使用 HTTPS 请注释掉下面以 ssl 为前缀的配置
        ssl_certificate /etc/ssl/xyz/1_abc.xyz_bundle.crt;
        ssl_certificate_key /etc/ssl/xyz/2_abc.xyz.key;
        ssl_session_timeout 5m;
        ssl_protocols TLSv1 TLSv1.1 TLSv1.2;
        ssl_ciphers ECDHE-RSA-AES128-GCM-SHA256:HIGH:!aNULL:!MD5:!RC4:!DHE;
        ssl_prefer_server_ciphers on;

        access_log /var/log/nginx/abc_access.log;
        error_log  /var/log/nginx/abc_error.log;

        root /home/xxx/www/static_web; # 静态页面所在目录
        index index.html;

        location / {
            try_files $uri $uri/ =404;
        }
        
        # 这里是 腾讯云 SSL 证书审批时需要配置的部分
        location ~ ^/.well-known/pki-validation/fileauth.txt {
            default_type text/html;
            return 200 '...050031...qoxbwr...9eozlnx';
        }
    }

    server {
        listen      80;
        server_name abc.xyz; 
        rewrite     ^ https://$server_name$request_uri? permanent;                            

        root /home/xxx/www/static_web;
        index index.html;
        location / {
            try_files $uri $uri/ =404;
        }      
    }
    # 下面两行需要删除或者直接注释，不然上面的配置不能生效
    # include /etc/nginx/conf.d/*.conf;
    # include /etc/nginx/sites-enabled/*;
}

HTTPS

国内免费单域名证书

腾讯与阿里都可以申请周期为一年的免费 SSL 证书，腾讯云申请地址

申请过程中请选择文件验证方式

申请之后需要审批，审批前你的域名需要可以访问，也就意味着你需要先搭建后服务，然后申请 SSL 证书。大部分情况下我们也是先让服务可以通过 HTTP 访问，然后再考虑 HTTPS

审批示例如下：

您将有3天时间完成文件解析记录的添加，否则审核将会失败。请您尽快添加文件解析记录，扫描认证通过后即可颁布证书。

请添加如下解析记录 操作指引

文件位置    文件名    文件内容
/.well-known/pki-validation/    fileauth.txt     ...050031...qoxbwr...9eozlnx 

http://steamxyz.cn/.well-known/pki-validation/fileauth.txt
https://steamxyz.cn/.well-known/pki-validation/fileauth.txt
支持 HTTP 和 HTTPS，任意一个可访问均可。文件验证需要直接响应200状态码和文件内容，不支持任何形式的跳转。对于 www 开头的二级域名，例如 www.domain.com ，除了对该域名进行文件验证，还需对其主域名 domain.com 添加文件验证。

申请的 SSL 签名文件可以按照上面 Nginx 配置文件中的方式进行配置与使用

免费 SSL 证书只有一年有效期，过期后需要重新申请

免费 Let’s Encrypt 通配符域名

如果你的域名买自阿里云，获取证书的方法可以参考这里：https://github.com/tengattack/certbot-dns-aliyun，下面是简单的示例：

certbot certonly --authenticator=dns-aliyun --dns-aliyun-credentials=./hjiahu_dns.ini -d "*.yearn.xyz,yearn.xyz"

执行上面命令后 certbot 将把证书放到这里：/etc/letsencrypt/live/yearn.xyz/，nginx 配置方式请参考上文

备案

如果想让自己的网站能在公网正常访问，备案必不可少。备案也是对自己与他人负责

因为我使用的是阿里云的 ECS，所以这里只简述阿里云网站备案的方法。购买阿里云域名服务之后按照后续阿里发送的邮件进行操作即可，一定要注意下面的ICP备案后处理流程，避免不必要的损失

一些资料

关于上海市网站公安联网备案公告
备案的必要性
ICP备案后处理，此项必须处理，且此项包含多个必须步骤，比如为网站添加备案号、添加网站版权（依省份而不同）、公安联网备案等。未在网页底部添加备案号将被处以五千元以上一万元以下罚款

站内搜索

文档与资料一旦多了起来，搜索功能就十分重要。现有很多技术手段实现网站的检索

可以利用第三方搜索软件自己搭建搜索引擎，比如 YaCy。YaCy 是开箱即用的搜索引擎，包括 web 页面、爬虫和文本检索工具（solr）。YaCy 可以检索网页，也可以检索 FTP、SMB 等页面。YaCy 对系统资源占用不大，数 G 磁盘空间和 600MB 内存即可正常运行

如果可以访问外网，那么直接使用 Google CSE 是非常不错的选择（百度类似功能早已废弃），示例配置如下（悬浮在右下角）

<div style="width:300px;position:fixed;bottom:2rem;right:0.5rem;z-index: 9999;">
  <script async src="https://cse.google.com/cse.js?cx=your_own_code"></script>
  <div class="gcse-search"></div>
</div>

可以使用 Typesense/ElasticSearch/MeiliSearch 软件自行实现文档检索，没有 web 页面，访问困难
使用商业搜索工具的免费版本，比如 Algolia/Site Search 360/Fact-Finder 等，挺好用的，只不过搜索次数有限制。选择这类工具时请注意一点，有些搜索工具不支持中文，比如 Site Search 360 （2021 年依旧不支持）。还有就是国外的网站一般比较慢
其他

流量统计

使用百度统计可以实现网站访问流量的统计与分析，百度统计有很多分析功能，具体细节请参考官网，我暂时只使用了免费的流量统计功能。从百度统计官网（网站管理页面）下载类似下面的代码，并将代码拷贝到网站的每一个页面即可实现网站的流量统计，使用 eureka 可以将代码写进 layouts/partials/footer.html

<script>
var _hmt = _hmt || [];
(function() {
  var hm = document.createElement("script");
  hm.src = "https://hm.baidu.com/hm.js?xxxxxxxxx";
  var s = document.getElementsByTagName("script")[0]; 
  s.parentNode.insertBefore(hm, s);
})();
</script>

其他

静态网站的优点是快速方便，缺点是几乎没有互动

Eureka 等主题支持 Disqus/Commento 等评论系统，有兴趣可以给自己的网站添加评论功能

Hugo&Eureka&Nginx

说明

Hugo

参考资料

常用命令

重要概念

Tags

Draft

defaultMarkdownHandler

添加 MathJax 支持

Eureka

参考资料

配置

添加 Mermaid 支持

Nginx

HTTPS

国内免费单域名证书

免费 Let’s Encrypt 通配符域名

备案

一些资料

站内搜索

流量统计

其他

On This Page

See Also