Hugo & Eureka & Nginx

博客原文地址

Hugo & Eureka & Nginx

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

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

说明

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

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

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

Hugo

参考资料

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

常用命令

hugo new site /path/to/site  # 在指定位置生成 hugo 工程
hugo new about.md            # 生成 about.md 文件，默认在工程子目录 content 内
hugo -D                      # 生成静态页面与 css/js 等文件，将文件拷贝到 web 服务器指定目录下即可访问

重要概念

Tags

Hugo 支持文章 Tags 分类与快速访问，可以参考这里

Draft

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

defaultMarkdownHandler

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

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

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

源码编译 Hugo （添加 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 数学表达式，需添加这个插件并编译，执行过程如下：

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

Eureka

参考资料

  1. 中文官方文档：https://www.wangchucheng.com/zh/docs/eureka/
  2. github：https://github.com/wangchucheng/hugo-eureka
  3. Example：https://gitee.com/hjiahu/hugo_blogs

配置

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 '20210129050031...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     202101290658595xdu8yw836cnpbm0h1lkd7ptgh892qyfwzutg33qfeh7ypsk6s 

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 证书只有一年有效期，过期后需要重新申请

备案

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

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

一些资料

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

其他

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

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

posted @ 2021-01-30 18:59  jiahu  阅读(744)  评论(0)  编辑  收藏  举报