Hugo 是一个用 Go 编写的开源静态网站生成器,一般只需几秒钟就能生成一个网站,被称为“世界上最快的网站构建框架”。用户可以使用 markdown 语法编写博客内容,结合 Github Page 可以无需服务器部署自己的博客,同时也支持采用 Nginx 、Apache 等 HTTP 服务器的私有化部署方式。本文结合本博客的部署过程,详细叙述以上两种部署方式,以及 CI/CD 自动化部署、国际化配置等过程。
英文站点 - Github Page 访问地址:
中文站点 - Nginx 私有化部署访问地址:
Hugo 安装
hugo 本地安装,建议首次使用时在本地安装好 hugo 客户端,方便调试。后续使用过程中,可脱离 hugo 客户端使用,在本地编辑好 markdown 文件上传至 github,即可触发自动化部署,详见 Github Pages 自动化部署与私有化自动化部署章节
-
hugo 安装
安装过程 - 以 windows winget 为例,安装 Extended 版本
1 2 3 4 5
//安装 winget install Hugo.Hugo.Extended //卸载 winget uninstall --name "Hugo (Extended)"
其它系统及安装方式,可查看 官方文档
-
新建站点
执行以下命令,即可在当前文件夹下新建站点 mysite
1
hugo new site mysite
-
预览
执行成功,可以在本地 1313 端口下,预览网站
1
hugo server
-
打包
打包完成,在 public 目录下生成静态网站
1
hugo
-
环境配置
hugo 在 config 文件夹下对环境配置文件进行管理(默认不存在该目录,需要用户自己新建),目录结构如下所示
1 2 3 4 5 6 7
mysite ├── config.toml └── config ├── development │ └── config.toml └── production └── config.toml
如上,新建了 development 与 production 环境配置,可以通过
--environment development
指定配置文件,若无指定,则hugo server
预览命令,默认使用 development 环境hugo
打包命令,默认使用 production 环境指定配置文件的启动命令:
1 2 3 4 5
//预览 hugo server --environment development //打包 hugo --environment development
主题配置
得益于 hugo 丰富的主题库,我们可以简单快捷地获取到许多个性化 hugo 主题,可以预览 官网主题库 挑选自己喜欢的主题
以下,将采用 hugo-theme-stack 主题为例进行说明
-
git 初始化
1 2 3 4 5
//进入所在目录 cd mysite //git初始化 git init
-
添加子模块,方便后续主题更新
1 2
//在 mysite/themes 目录下,拉取 hugo-theme-stack 并创建名为 stack 的主题 git submodule add https://github.com/CaiJimmy/hugo-theme-stack.git themes/stack
-
配置主题
打开刚刚下载的主题文件,将 themes/stack/exampleSite 目录下的配置文件复制到根目录,覆盖原先的配置文件,编辑配置文件,将 theme 字段配置为上述步骤创建的主题名称,即 stack
hugo-theme-stack 部分配置说明
1 2 3 4 5 6 7 8 9 10 11
//访问url,页面跳转时用到 baseurl: https://example.com/ //主题名称,在此处应为 stack theme: hugo-theme-stack //网站名称 title: Example Site //网站说明 copyright: Example Person
配置完成重启即可看到主题改动
hugo-theme-stack 其他配置可至 官网查询
Github Pages 自动化部署 CI/CD
GitHub Pages 是 GitHub 提供的一个网页寄存服务,可以用于存放静态网页,包括博客、项目文档等,hugo 可以快速构建静态网站,天然支持使用 GitHub Pages 部署
-
GitHub Pages 配置
使用 Github Pages 需要创建一个以 Github 用户名开头,
.github.io
结尾的 repository,并且必须为公开仓库。具体流程为:-
New repository
-
Repository name: xxxx(用户名).github.io
-
Public
-
Create repository
创建完成,打开仓库的 Settings 配置,修改 Default branch 可以修改默认展示的分支。
上传静态页面 index.html 文件至仓库指定分支
1 2 3 4 5 6 7 8 9 10
<!DOCTYPE html> <html> <head> <meta charset="utf-8"> <title>Hello World</title> </head> <body> <h1>Hello World</h1> </body> </html>
打开 https://用户名.github.io/ 即可看到刚刚上传的静态页面。
-
-
关联 Hugo 仓库自动化部署
在这里,我们采用两个不同的 Github 仓库
-
blog 仓库 – 用来存放原始的博客文件,主要格式为 Mrakdown
-
GitHub Pages 仓库 – 即上一个步骤创建的仓库,用来存放打包后的静态网站
具体流程如下:
-
打通两个仓库的权限
-
打开 Github 全局配置(非仓库配置)Settings / Settings / Personal access tokens / Fine-grained tokens / Generate new token
-
Token name 可随意填写
-
Expiration 过期时间建议选择 No expiration,避免过期后无法使用
-
Repository access 安全考虑建议选择 Only select repositories,只选择刚刚创建的 GitHub Pages 仓库仓库
-
Permissions 权限配置将 Contents 修改为 Read and write
-
保存并复制好自动生成的 token
-
在 blog 仓库增加 token 配置,路径为:blog 仓库 / Settings / Security / Secrets and variables / Actions / Repository secrets / New repository secret,Name 命名为 PERSONAL_TOKEN,并将上述步骤复制的 token 粘贴到 Secret 中保存
-
-
hugo 自动打包、发布
在 blog 仓库的
.github/workflows
目录下,创建deploy.yml
,配置内容如下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 38
name: deploy on: # git push时执行 action push: workflow_dispatch: schedule: # Runs everyday at 8:00 AM - cron: "0 0 * * *" jobs: build: runs-on: ubuntu-latest steps: - name: Checkout uses: actions/checkout@v2 with: submodules: true fetch-depth: 0 - name: Setup Hugo uses: peaceiris/actions-hugo@v2 with: hugo-version: "latest" # hugo 打包 - name: Build Web run: hugo # 打包完成推送至指定仓库 - name: Deploy Web uses: peaceiris/actions-gh-pages@v3 with: PERSONAL_TOKEN: ${{ secrets.PERSONAL_TOKEN }} EXTERNAL_REPOSITORY: zoyao/zoyao.github.io PUBLISH_BRANCH: master PUBLISH_DIR: ./public commit_message: ${{ github.event.head_commit.message }}
配置完成之后,当执行 git push 之后,即触发自动化部署,可在 blog 仓库的 action 中,看到相关流程
-
私有化自动化部署 CI/CD
采用 GitHub Pages 可以很方便的完成自动化部署,但是 GitHub 域名在部分网络环境下访问较慢,如果有这部分需求的童鞋,可以采用私有化部署,部署到自己的服务器上。
-
私有化部署
这里采用 Nginx 进行私有化部署
-
将打包后的博客静态文件复制到私有服务器,
/app/blog/
目录下 -
配置 Nginx,在 Nginx 的
./nginx/conf.d
目录下,新建配置文件,这里命名为blog-8888.conf
1 2 3 4 5 6 7 8 9 10 11 12 13
server { # 监听8888端口 listen 8888; # 这里先采用IP访问,后续 HTTPS 配置再修改为域名 server_name 服务器公网IP; # server_name www.zoyao.top; # 指定静态资源位置 location / { root /app/blog; index index.html index.htm; } }
-
更新 Nginx 配置之后,访问 http://服务器公网IP:8888/ 即可看到博客首页
-
-
自动化部署
使用自动化部署,需要先配置 ssh key 登录,建议先新建用户,做好权限隔离
-
使用
adduser
命令创建新用户,这里命名为 git,可自定义sudo adduser git
-
目录授权,需要将
/app/blog
授权给上一步骤新建的用户,切换到git用户执行sudo chmod -R 777 /app/blog
-