Jason Pan

手把手带你搭建个人博客

潘忠显 / 2022-10-19


一、背景

为了敦促自己不断学习总结并提高个人影响力,我在 2020 年 5 月搭建起了自己的博客,至今已经两年多了。当前部署方案基于 Markdown 本地编写、迁移、转载到 KM 都非常灵活方便,更新网站内容也只需本地一次 Git Push 操作

方便易用的个人博客方案,能够提高个人分享的积极性,至少不会成为你分享道路上的绊脚石。

最近总结下我个人博客的详细方案,包括部署方式、内容组织、网站被索引等内容,供诸君参考。

*部署过程要求对 Linux 基本操作有些了解。*文末也提供了其他的替代方案简介和对比,也有说明个人为什么选择了当前的方案。

二、Hugo 博客框架

本节介绍 MacBook 上安装 Hugo,创建网站和第一篇博客,编写内容、插入图片,并在本地启动 HTTP 服务可以通过浏览器访问。

2.1 QuickStart

参考 Hugo 官方文档 - Quick Start

# 安装 Hugo
brew install hugo

# 创建一个新的网站(本地)
hugo new site quickstart && cd quickstart

# 拉取并设置主题
git init
git submodule add https://github.com/theNewDynamic/gohugo-theme-ananke.git themes/ananke
echo theme = \"ananke\" >> config.toml

# 创建一篇新文章
hugo new posts/my-first-post.md

# 构建静态网站文件,并启动 HTTP 服务
hugo server -D

执行完上述操作,就可以通过浏览器访问 http://localhost:1313/ 。可以看到自己刚创建的网站与第一篇文章:

first-blog-home-page

2.2 推送到远端仓库

Coding 上创建一个项目,在项目下再创建一个仓库,默认参数即可(私有仓库)。这里会获得一个仓库地址:git@e.coding.net:panzhongxian/blog/quickstart.git

我仓库有多个 remote,一个是 Github,一个是 Gitee,一个 Coding。GitHub 在国内服务器访问速度差;而 Gitee 偶尔会出现故障;目前用的 Coding。

cd quickstart
git remote add origin git@e.coding.net:panzhongxian/blog/blog.git
git push -u origin "master"

2.3 页面中插入图片

以 Markdown 格式插入图片:

wget /images/landscape.png -qO static/landscape.png
echo '![img](/landscape.png)' >> ./content/posts/my-first-post.md

上边的操作分成了两步:先将图片放到了 static 目录下,然后在 Markdown 文件中指定图片,这里是要切掉 static 目录的。

[DIY] 文末提供了一个简单的工具处理图片:使用 Typora 工具可以随便贴图,通过该工具可以将所有图片复制或下载到指定的目录,而无需手动一张张处理。

2.4 使用 HTML 标签

Hugo 使用的 Markdown 引擎是 Goldmark,它默认是不会渲染原始的 HTML 语句的。需要执行在配置文件中打开一个开关:

[markup]
  [markup.goldmark]
    [markup.goldmark.renderer]
      unsafe = true

插入网页图片 + HTML 宽度设置为 50%:

echo '<img src="/images/wxmp/qrcode-search.png" alt="qrcode-search" style="width:50%;" />' >> ./content/posts/my-first-post.md

操作完上边两种方式的图片插入,效果如下:

first-post-page

2.5 Hugo 文件组织形式简要说明

上边的Quick Start 和插入图片的介绍中,文件统一放在了 content/post 目录下,图片统一放在 static 目录下。这种组织方式不是很清晰,比如一篇博客中就可能有很多图片,如果多篇的文章的图片都放在一个目录下,就会很乱。

要理解 Hugo 只是一个静态的网站框架,如果你不指定特殊配置的情况下,他就像个文件系统,在服务器上创建文件夹,就只是对应到网址中的一层地址而已。我自己是这么安排的:

比如本文的地址是 content/cn/log/2022-10-19-build-personal-blog-step-by-step.md ,图片目录是 static/images/build-personal-blog-step-by-step/

三、部署方案

上一节实际已经在个人主机上搭建起了个人博客的服务,通过 http://127.0.0.1:1313 进行本地访问。本节介绍如何将这种服务进行部署,让所有人都能访问到。

我的博客是部署在【腾讯云】(2核2G 低至50元/1年) 的 CVM 上的,使用 HTTPs 服务访问。具体的进程和文件信息如下:

deployment

具体地:

3.1 基本资源购置

这种部署方式,只需要在【腾讯云】 简单购置和配置就能满足需求。

购置 CVM:要让别人能够访问到你的博客内容,不一定非得自己租服务器,但是使用 CVM 是最灵活、最直接的方式。如果后期要执行个相关的脚本,找个远程机器做点别的事,也非常的方便。

购置了 CVM 会有外网 IP,通过外网 IP 我们可以 SSH 上去,后期如果部署了服务,也可以通过 IP 访问。

我之前有使用 CentOS 相关发行版的经历,所以这里的镜像也是选择的 CentOS。选择不同的操作系统,主要区别在包管理软件的使用上,比如是用 yum 还是用 apt-get。

购置域名:如果想被人记住,肯定不能每次都通过 IP 访问,而是需要申请域名。腾讯云上购置域名之后,需要进行实名认证。

如果要搭建自己的博客网站,还需要网站备案,这将耗费1个月左右的时间。备案完成后,会有一个网站备案号,需要在主页下方展示。但是网站备案并不影响你域名的解析和网站上线(不影响域名解析,但是影响访问,详见最后一小节分析)

配置域名解析:配置 A 记录类型,将记录值修改为 CVM 外网地址,TTL 10 分钟,主机记录可以加个 www@ 两种。配置之后,过一会可以通过 nslookup 等指令进行域名解析,看能否解析出自己的地址。

申请免费 SSL 证书:直接通过 HTTP 是没有加密的明文访问,浏览器也会提示不安全。你是不是也不想让自己的网站看上去很 Low?那就为域名申请一个免费的证书。产生的免费证书有多种形式,我这里选择的 Nginx 使用的证书类型,后边配置 HTTPS 服务会用到。

3.2 安装 Git & Docker

前面介绍了,服务器上的文件同步使用 Git,这里也需要安装一下:

yum install git

为了避免后边迁移服务时因为平台差异带来麻烦,所以几个服务都是选择使用 Docker 进行部署。

在安装其他部署之前,就需要先安装 Docker Engine,可以参考官方文档-Install Docker Engine on CentOS,其他的操作系统也有相关的文档。

sudo yum install -y yum-utils
sudo yum-config-manager \
    --add-repo \
    https://download.docker.com/linux/centos/docker-ce.repo
sudo yum install docker-ce docker-ce-cli containerd.io docker-compose-plugin

3.3 Git 定时任务

存储用户凭证,并拉取网站仓库内容:

git config http.postBuffer 524288000
git config --global credential.helper store
git clone git@e.coding.net:panzhongxian/blog/blog.git
## 上边语句 Clone private 仓库需要输入用户名密码
cd blog
git pull

在命令行执行 crontab -e 增加每分钟定时任务:

*/1 * * * * cd /root/blog && git pull

如果确定不会上机器修改什么文件,完全使用 仓库中的内容,可以强制使用远程分支

*/1 * * * * cd /root/blog && git fetch --all && git reset --hard origin/master

这样,一旦你在本地更新了博客文件,并 Push 到主分支上,服务器就会接近实时地拉取到最新内容。

3.4 部署 Hugo 容器

直接使用 Docker 部署 hugo,这里将容器内的 1313 端口映射到主机的 13131 端口。另外,需要手动指定 Blog 的目录(替换下边的 $(blog_path) ):

docker run --rm -v $(blog_path):/src -p 0.0.0.0:13131:1313 klakegg/hugo "server --bind=0.0.0.0"&

拉起服务后可以看看本机的 13131 端口是否正在监听。可以直接通过 {CVM 外网IP}:13131 进行一下访问测试。

3.5 部署 Envoy 容器

我这里用到的 HTTPS 网关选择了 Envoy,选择一个自己熟悉的即可。我将我的 Dockerfile 和配置文件上传到了仓库: https://github.com/panzhongxian/https-blog-envoy-docker

clone 下该仓库之后,需要先替换配置中的 your-site.cn 为你自己的域名,另外有几项配置我这里固定的,如果有需要,可以做手动修改:

最后启动时,指定存储证书文件的文件映射到容器内部的目录:

git clone git@github.com:panzhongxian/https-blog-envoy-docker.git
cd https-blog-envoy-docker
# 替换配置中的网址
sed -i "s/your-site.cn/panzhongxian.cn/g" envoy.yaml

# 构建镜像
docker build -t envoy:v1 .

# 运行容器
docker run -d --add-host host.docker.internal:host-gateway \
  -v /etc/ssl/panzhongxian.cn_nginx:/etc/ssl/panzhongxian.cn \
  -p 9901:9901 -p 443:443 envoy:v1

至此,外网用户已经可以通过 https://www.{你的域名} 访问你的网站了。

3.6 开机启动

CVM 不太容易直接毁掉,但是毕竟还是存在重启的风险。如果期望在重启 CVM 之后,原来拉起的服务能够自动拉起,则需要结合 Linux 的 systemctl 添加开机启动服务。

这里暂时不做具体介绍。

四、辅助工具

4.1 让引擎搜索到

每种静态网站框架都会提供 sitemap 的功能,sitemap 可以提交给主流的搜索引擎,让他们的用户能够搜索到。

配置 Hugo sitemap

在 config.toml 文件中添加以下配置,本地测试的话,会在 http://localhost:1313/sitemap.xml 中展示网站中有哪些页面:

[sitemap]
  changefreq = 'daily'
  filename = 'sitemap.xml'
  priority = 0.5

在 Google / Baidu 中配置和效果

Google 搜索控制台网址是 https://search.google.com/search-console。首先要将自己的域名添加到搜索站点中。该过程中,需要证明这个网站是属于你的,是通过让你给域名 DNS 解析中添加一条特别的记录来实现的。这个过程按照各个搜索引擎的指引即可。

然后,通过【网站地图】页面可以提交我们的 sitemap URL。

google-search-sitemap

添加上自己的网址之后,Google 稍后就会收录,用户搜索、展示、点击的效果也会在 Google 搜索控制台上展示:

google-search-result

Baidu 也有类似的页面进行配置,地址:https://ziyuan.baidu.com/dashboard/index。我博客的访问来源基本都是 Google 过来的,不知道我在百度的配置有什么问题,这里就不列举具体的操作了

4.2 页面访问量统计

页面访问量统计工具的工作原理是:浏览器加载页面,执行页面的 Javascript 脚本,上报相关信息到网站访问量统计的服务。上报的信息包括用户的网址、地区、来源等信息。

看页面访问统计主要是能帮助你了解网站是否健康,哪些页面比较受欢迎,受众主要如何分布等,当然,知道有不少人访问自己的网站,也能带来一些成就感。

各个平台的统计工具类似,不用每个平台都加,不然会给用户加载带来负担。

我这里主要使用的是 https://tongji.baidu.com,可以按照他的指引,添加网站、将需要执行的脚本贴到 Hugo 的模板中即可。

baidu-tongji-report

Google 也有类似的服务叫谷歌分析,地址 https://analytics.google.com/

4.3 自动处理图片路径工具

我平时使用 Typora 编写 Markdown 文档,通常有插入图片的需求,会直接贴进去。这带来了一个问题,图片往往是绝对路径、相对路径或者 HTTP URL 地址,在我正式发布之前需要将这些图片归档到 博客静态目录中,如前边所说,会放到 static/images/{特定文章相关命名文件夹}

我这里用 Python 自己实现了一个工具,可以自动化的下载、拷贝、替换 Markdown 中图片的内容,实现上边的操作。工具托管在 PyPI,使用和安装都非常简单。其中,--dst_md_file 选项如果省略,则默认为替换当前文件,有一定风险,建议产生新文件后比较,没问题再替换:

python3 -m pip install markdown-image-replacer

python3 -m markdown_image_replacer \
   $HOME/quickstart/content/posts/my-first-post.md \
   --src_img_root $HOME/quickstart/static \
   --dst_md_file $HOME/quickstart/content/posts/my-first-post2.md \
   --dst_img_root $HOME/quickstart/static \
   --dst_img_rel_dir images/my-first-post

替换之后,可以查看 my-first-post2.md 文档中内容变化,以及 static 目录的变化。

工具还有很多需要完善的地方,有兴趣的话,可以提 PR 修改。https://github.com/panzhongxian/markdown_image_replacer

4.4 留言工具

国内留言小插件基本都被禁用了,目前只能使用 utterances 利用 GitHub ISSUE 的方式进行,国内用户也是无法使用的。

五、其他部署方式简介与比较

以上五种,我都有折腾过,下面来说说相比于我当前部署,这几种方式的限制

六、网站不备案是否能够访问?

之前的文章被选入了看一看精选,其中关于备案的问题,没有做详细的说明。本文先回答网站不备案是否能够访问,主要篇幅介绍背后隐含的网络知识。

结论先行-国内服务不备案不能访问

如果服务器在国内,比如从腾讯云、阿里云购置的CVM,是必须备案的。两年前搭建博客网站的时候,在未备案阶段还可以访问。最近(2023年1月)刚购买一个新域名,发现如果不备案,HTTP(特指80端口) 和 HTTPS(特指443端口) 两种方式都是无法访问的。

根据国务院令第292号《互联网信息服务管理办法》和《非经营性互联网信息服务备案管理办法》规定,国家对经营性互联网信息服务实行许可制度,对非经营性互联网信息服务实行备案制度。未获取许可或者未履行备案手续的,不得从事互联网信息服务,否则属于违法行为。 – From 腾讯云

接下来通过三个问答的方式,来介绍一下**“不备案无法访问”背后的网络知识**。

Q1: 为什么无法通过未备案的域名进行访问?

从浏览器到服务器之间,会经过不少路由器/交换机,比如云服务商为了符合国家规定,可以在自己的网关入口做一些设置,如果检测到 HTTP/HTTPS 请求,是可以配置一些网络策略,以达到终止的目的的。

从服务端抓包(下边附图),可以清楚地看到:

抓包-HTTP

Q2: 为什么访问未备案域名站点,使用 HTTP/HTTPS 显示不同界面?

以下两张图中,上图是通过 HTTP 协议访问未备案域名的网站(跳转到腾讯云网站),下图是通过 HTTPS 协议访问的结果(ERR_CONNECTION_CLOSED):

网站无法访问-HTTP网站无法访问-HTTPS

我这里从客户端抓包来解释这一现象:

抓包-HTTPS

Q3: 为什么要用 HTTPS 建站?

上边已经简单介绍了 HTTPS 工作原理:使用 SSL/TLS 协议对通信进行加密传输 HTTP 协议。从而防止假冒。通过上边的抓包和分析,你大概也能理解以下几点客户端和服务端都应该选择 HTTPS 的理由:

  1. 服务端提供 HTTPS 服务,在浏览器是可以显示是安全的,让用户觉着这个网站更易信赖
  2. HTTPS 数据在传输的两个方向上都会得到加密,请求和返回中的敏感数据或个人数据不会在传输中被泄漏
  3. SSL/TLS 还可确认网站服务器是其真实身份,从而防止DNS劫持攻击(假冒网站)