Featured image of post Hugo 博客 Github Page /私有化 部署指南

Hugo 博客 Github Page /私有化 部署指南

Hugo CI/CD 自动化部署、国际化配置。

Hugo 是一个用 Go 编写的开源静态网站生成器,一般只需几秒钟就能生成一个网站,被称为“世界上最快的网站构建框架”。用户可以使用 markdown 语法编写博客内容,结合 Github Page 可以无需服务器部署自己的博客,同时也支持采用 Nginx 、Apache 等 HTTP 服务器的私有化部署方式。本文结合本博客的部署过程,详细叙述以上两种部署方式,以及 CI/CD 自动化部署、国际化配置等过程。

英文站点 - Github Page 访问地址:

zoyao.github.io

中文站点 - Nginx 私有化部署访问地址:

zoyao.top

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,并且必须为公开仓库。具体流程为:

    1. New repository

    2. Repository name: xxxx(用户名).github.io

    3. Public

    4. Create repository

    创建完成,打开仓库的 Settings 配置,修改 Default branch 可以修改默认展示的分支。

    当前配置为main分支

    上传静态页面 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 仓库 – 即上一个步骤创建的仓库,用来存放打包后的静态网站

    具体流程如下:

    1. 打通两个仓库的权限

      • 打开 Github 全局配置(非仓库配置)Settings / Settings / Personal access tokens / Fine-grained tokens / Generate new token

        alt text

      • Token name 可随意填写

      • Expiration 过期时间建议选择 No expiration,避免过期后无法使用

      • Repository access 安全考虑建议选择 Only select repositories,只选择刚刚创建的 GitHub Pages 仓库仓库

        alt text

      • Permissions 权限配置将 Contents 修改为 Read and write

        alt text

      • 保存并复制好自动生成的 token

      • 在 blog 仓库增加 token 配置,路径为:blog 仓库 / Settings / Security / Secrets and variables / Actions / Repository secrets / New repository secret,Name 命名为 PERSONAL_TOKEN,并将上述步骤复制的 token 粘贴到 Secret 中保存

        alt text

    2. 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 中,看到相关流程

      alt text

私有化自动化部署 CI/CD

采用 GitHub Pages 可以很方便的完成自动化部署,但是 GitHub 域名在部分网络环境下访问较慢,如果有这部分需求的童鞋,可以采用私有化部署,部署到自己的服务器上。

  • 私有化部署

    这里采用 Nginx 进行私有化部署

    1. 将打包后的博客静态文件复制到私有服务器,/app/blog/目录下

    2. 配置 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;
          }
      }
      
    3. 更新 Nginx 配置之后,访问 http://服务器公网IP:8888/ 即可看到博客首页

  • 自动化部署

    使用自动化部署,需要先配置 ssh key 登录,建议先新建用户,做好权限隔离

    1. 使用 adduser 命令创建新用户,这里命名为 git,可自定义

      sudo adduser git

    2. 目录授权,需要将 /app/blog 授权给上一步骤新建的用户,切换到git用户执行

      sudo chmod -R 777 /app/blog

HTTPS 配置

i18n国际化