Hugo + Papermod主题 – 搭建博客

0.简述

写作方式

  1. 本地电脑通过 Visual Studio Code 的 Remote SSH 连接服务器,然后在 Visual Studio Code 里写博客,完成后通过 hugo 编译
  2. 有时候也会在本地电脑写,写完后推送到 github ,然后在服务器端拉取代码再通过 hugo 编译

简略的画了个图,大致顺序如下:

Writing Style
Writing Style

1.环境信息

分类/环境 本地电脑 服务器(2G2C)
系统 Window 11 Debian 12
软件 (1) Visual Studio Code
(2) Git
(3) Hugo
(1) 1Panel面板
(2) Git
(3) Hugo

2.部署方式

通过 1Panel 面板傻瓜式建站

关于更新

本地电脑和服务器都安装 SSH,通过本地电脑 Visual Studio Code + SSH 调整网站(新添/更新)

3.关于备份

备份主要是通过 Github 私仓,博客图片存储在服务器,然后设定每周自动备份一次

4.建站前序(准备)

4.1 Github

  1. 访问 Github ,注册账号
  2. 新建个人仓库(建议创建私人仓库)

4.2 本地电脑

序号 软件/工具 下载地址
1 Git 下载
2 Visual Studio Code 下载
3 SSH Windows 11 已默认安装
4 Hugo(扩展版)

4.2.1 SSH

Windows 11 默认是安装 SSH ,如果不确定的话可以使用下面的命令进行确认。

以管理员身份打开 PowerShell 并运行

(鼠标右击屏幕左下角的 Win 图标就能看到 “终端管理员”)

BASH
# 检查 OpenSSH 的安装状态
Get-WindowsCapability -Online | Where-Object Name -like  'OpenSSH*'
点击展开查看更多

如果已经安装 SSH ,终端将会打印:

BASH
# OpenSSH.Client 的状态为 Installed,则表示 OpenSSH 客户端已成功安装,
# 如果状态为 NotPresent,则表示尚未安装
Name  : OpenSSH.Client~~~~0.0.1.0
State : Installed

Name  : OpenSSH.Server~~~~0.0.1.0
State : NotPresent
点击展开查看更多

如果未安装,可以通过以下命令安装

BASH
Add-WindowsCapability -Online -Name OpenSSH.Client~~~~0.0.1.0
点击展开查看更多

4.2.2 Hugo

Hugo 的安装方式 有很多种,这里我选择的是的 Prebuilt binaries 安装方式

  1. 下载 hugo_extended_withdeploy_0.145.0_windows-amd64.zip
  2. 将压缩包解压到 D:/hugo/hugo_extended_withdeploy_0.145.0,没有的话新建
  3. 将目录添加到 PATH 环境变量中
  4. 打开终端,输入 hugo version 验证是否安装成功
BASH
hugo version
点击展开查看更多

如果安装成功,将打印:

BASH
hugo v0.145.0-666444f0a52132f9fec9f71cf25b441cc6a4f355+extended+withdeploy windows/amd64...
点击展开查看更多

多说一句,如果没有特别的 Hugo BUG,建议不要去升级 Hugo 版本。因为 Hugo 的作者在迭代 Hugo 时不会考虑是否与市面上的主题 “适配” ,如果你更新了 Hugo 的版本,可能会出现博客无法编译(生成 public 文件夹)

4.2.3 Github 密钥对

(1)打开终端,输入下面的命令,生成密钥

BASH
ssh-keygen -t ed25519 -C "your-email@example.com"
点击展开查看更多

(2)查看并复制公钥(复制里面那一长串内容)

(3)登录 GitHub 添加 SSH Key –> 点击 New SSH key –> 填个名字(比如: mykey),然后把刚才复制的公钥内容粘贴进去,保存

(4)打开终端,输入下面命令,验证是否完成

BASH
ssh -T git@github.com
点击展开查看更多

如果配置的没问题,会打印类似的内容:

BASH
Hi 你的GitHub用户名! You've successfully authenticated, but ...
点击展开查看更多

4.3 服务器

4.3.1 安装 1Panel

1Panel 官方的文档 写的蛮清楚,可以去查阅,如果你和我一样是 Dabian 12 系统,可以直接参考下面安装步骤

(1)确保 Debian 12 系统是全新的(已重装过)

(2)命令控制台输入如下安装命令,然后耐心等待

BASH
curl -sSL https://resource.fit2cloud.com/1panel/package/quick_start.sh -o quick_start.sh && bash quick_start.sh
点击展开查看更多

debian os install 1panel

安装过程中,会让你选择语言,选择 Chinese 中文(简体) 即可,其余的可以直接默认(按回车)

安装成功后,请把登录信息(地址、面板用户、面板密码)记录下来

BASH
[1Panel 2025-04-27 09:01:50 install Log]: ======感谢您的耐心等待,安装已完成====== 
[1Panel 2025-04-27 09:01:50 install Log]:  
[1Panel 2025-04-27 09:01:50 install Log]: 请使用您的浏览器访问面板:  
[1Panel 2025-04-27 09:01:50 install Log]: 外部地址:  http://199.245.100.177:27951/97c02939d9 
[1Panel 2025-04-27 09:01:50 install Log]: 内部地址:  http://199.245.100.177:27951/97c02939d9 
[1Panel 2025-04-27 09:01:50 install Log]: 面板用户:  2cc9b06c55 
[1Panel 2025-04-27 09:01:50 install Log]: 面板密码:  2538407029 
[1Panel 2025-04-27 09:01:50 install Log]:  
[1Panel 2025-04-27 09:01:50 install Log]: 官方网站: https://1panel.cn 
[1Panel 2025-04-27 09:01:50 install Log]: 项目文档: https://1panel.cn/docs 
[1Panel 2025-04-27 09:01:50 install Log]: 代码仓库: https://github.com/1Panel-dev/1Panel 

[1Panel 2025-04-27 09:01:50 install Log]:  
[1Panel 2025-04-27 09:01:50 install Log]: 如果您使用的是云服务器,请在安全组中打开端口 27951 
[1Panel 2025-04-27 09:01:50 install Log]:  
[1Panel 2025-04-27 09:01:50 install Log]: 为了您的服务器安全,离开此屏幕后您...
[1Panel 2025-04-27 09:01:50 install Log]:  
[1Panel 2025-04-27 09:01:50 install Log]: ======
点击展开查看更多

(3)(按需)开放外部访问端口,比如上面的端口是 27951

(4)登录 1Panel 面板,安装 OpenResty

install openresty 1

默认即可,点击 确认,等待安装完成…

install openresty 2

4.3.2 安装 SSH

(1)打开终端,更新软件源

BASH
sudo apt update
点击展开查看更多

(2)安装 OpenSSH Server

BASH
sudo apt install openssh-server
点击展开查看更多

(3)查看 SSH 状态(确认 SSH 服务是否运行中)

BASH
sudo systemctl status ssh
点击展开查看更多

(4)启动 SSH

BASH
sudo systemctl enable ssh
点击展开查看更多

(5)设置开机自启

BASH
sudo systemctl enable ssh
点击展开查看更多

其他命令

BASH
# 重启服务(修改配置后使用)
sudo systemctl restart ssh
点击展开查看更多

4.3.3 安装 Git

(1)打开终端,更新软件源

BASH
sudo apt update
点击展开查看更多

(2)安装 Git

BASH
sudo apt install git
点击展开查看更多

(3)验证安装

BASH
git --version
点击展开查看更多

(4)配置 Git(用户名、电子邮件)

BASH
git config --global user.name "你的名字"
git config --global user.email "你的邮件@example.com"
点击展开查看更多

debian os install git

4.3.4 安装 Hugo

(1)安装

BASE
wget https://github.com/gohugoio/hugo/releases/download/v0.145.0/hugo_extended_0.145.0_Linux-64bit.tar.gz
点击展开查看更多

(2)解压

BASH
tar -xzf hugo_extended_0.145.0_Linux-64bit.tar.gz
点击展开查看更多

(3)安装到系统路径

BASH
sudo mv hugo /usr/local/bin/
点击展开查看更多

(4)验证安装是否成功

BASH
hugo version
点击展开查看更多

debian os install hugo

4.3.5 Github 密钥对

参考 4.2.3 配置即可,一样的

提示:如果你是 root 账号,生成的密钥对路径一般在 /root/.ssh

4.4 vscode SSH 登录

这里做的是通过密钥对实现免密登录

4.4.1 本地电脑

(1)vscode 安装 remote ssh 扩展

vscode install remote ssh

(2)PowerShell 生成密钥对

BASH
ssh-keygen -t rsa -b 4096 -C "my_hugo_papermod_blog"
点击展开查看更多

说明:

系统会提示你输入保存路径:

Enter file in which to save the key (/home/youruser/.ssh/id_rsa):

直接回车使用默认路径(建议使用默认)

然后会提示设置密钥口令(可以空着,方便免密登录)

Enter passphrase (empty for no passphrase):

(3)生成后的文件

# 文件 描述
1 ~/.ssh/id_rsa 私钥,不要泄露
2 ~/.ssh/id_rsa.pub 公钥,可分发给远程服务器

(建议修改文件名,因为以后可能其他的应用你会生成密钥对,避免混淆)

vscode install remote ssh

4.4.2 服务器

上传公钥:

  1. 进入 /root/.ssh,新建 authorized_keys 文件
  2. 打开 authorized_keys 文件 ,将 公钥 复制粘贴进去,保存

4.4.3 vscode ssh 连接测试

(1)本地电脑打开 vscode ,点击 左下角图标,选择 连接到主机

vscode conn remote ssh 1

(2)选项 +添加新的 SSH 主机 ,然后输入 服务器IP

vscode conn remote ssh 2

(3)选择 ssh 配置文件,打开配置文件,修改配置文件

BASH
Host 1.1.1.1
  HostName 1.1.1.1
  User root
  IdentityFile "C:/Users/donghai/.ssh/id_rsa_my_hugo_papermod_blog"
点击展开查看更多

(4)点击 左下角图标,选择 连接到主机,选择刚才添加的主机

如果出现 “xxx 指纹”,选择【是】即可

如果一切顺利,左下角图标会显示你当前连接的主机 IP 地址

vscode conn remote ssh 3

5. 建站

5.1 Github 建私仓

(1)登录 Github,创建 私仓

create github rep 1

(2)填写仓库名称,勾选 private,勾选 README.md 文件,最后点击 Create repository

create github rep 2

(3)克隆到本地电脑

D 盘目录下,运行 “终端” 克隆项目(在其他盘也行,看自己需求)

BASH
# 填写你自己的仓库地址
git clone https://github.com/rickeygong/gdh-papermod-blog.git
点击展开查看更多

拷贝仓库地址:

get github rep url

5.2 Hugo new site

(1)在 D 盘目录下,运行 “终端”,输入如下命令创建博客

BASH
# gdh-papermod-blog --> 写你自己的仓库名称
hugo new site gdh-papermod-blog
点击展开查看更多

(2)参考 hugo-PaperMod 安装文档 进行安装(很详细)

(3)博客准备好后,提交到 GitHub 仓库

BASH
git add .
git commit -m "Feat: Blog build"
git push origin main
点击展开查看更多

5.3 服务器添加博客

(1)登录 1Panel 面板 –> 菜单栏点击 网站 –> 点击 创建 –> 选择 静态网站 –> 填写 主域名(有域名填域名,没域名填IP)–> 填写 描述(按需) –> 点击 确认

1Panel create static site 1

(2)打开 网站目录 –> 删除目录下所有文件(正常只有 2 个文件:404.html 和 index.html)

1Panel create static site 2

将路径记录下来,一会我们要将博客克隆到这个路径下

我的站点路径是 /opt/1panel/apps/openresty/openresty/www/sites/199.245.100.177/index

1Panel create static site 3

(3)设置主机,填写 IP 和 root 密码 –> 点击 连接测试 –> 点击 确认

1Panel create static site 4

(4)打开 终端

1Panel create static site 5

(5)进入网站路径 –> 输入命令克隆博客项目(5.2 已经上传 Github)

BASH
# 进入网站路径
cd /opt/1panel/apps/openresty/openresty/www/sites/199.245.100.177/index

# 克隆项目(替换成你自己的项目克隆地址)
git clone https://github.com/rickeygong/gdh-papermod-blog.git
点击展开查看更多

(6)新添 blog-imgs 文件夹,用于存放博文使用的图片

1Panel create static site 6

(7)编译博客:生成 public 文件 ,打开终端 –> 进入博客项目 –> 输入 hugo

BASH
# 进入博客项目
cd /opt/1panel/apps/openresty/openresty/www/sites/199.245.100.177/index/gdh-papermod-blog

# 输入 `hugo`
hugo
点击展开查看更多

1Panel create static site 7

(8)配置 “网站目录” 路径(重要)

点击 配置

1Panel create static site 8

在 “运行目录” 选择 gdh-papermod-blog/public –> 点击 保存重载

1Panel create static site 9

(9)配置 “blog-imgs” 映射(重要)

因为服务器只暴露了 public 文件夹,而 blog-imgs 文件夹是跟 public 并列的,所以服务器访问的时候根本找不到 blog-imgs,导致 404,所以我们需要修改服务器配置,单独映射

  1. 点击 网站
  2. 在 “操作” 列中 点击 配置
  3. 点击 配置文件
  4. 在 server 配置块里,在 root 那一行后面添加 location /blog-imgs/ 配置
BASH
root /www/sites/199.245.100.177/index/gdh-papermod-blog/public; 
location /blog-imgs/ {
  alias /www/sites/199.245.100.177/index/blog-imgs/;
}
error_page 404 /404.html; 
点击展开查看更多

1Panel create static site 10

1Panel create static site 11

6.访问

如果一切顺利,在浏览器访问设定的地址,就能看到自己的博客

my hugo paperomd blog

7.关于优化/调整

由于篇幅原因,往后每个优化或调整我会另起一篇文章记录,请参考:

# 优化/调整 访问链接
1 添加页面、多语言、表格样式、设置字体等 posts/hugo-papermod/adjustments-record
2 添加友情链接页面 posts/hugo-papermod/add-friend-links-page
3 目录在左侧悬浮 posts/hugo-papermod/sidebar-float-left
4 文章底部添加文档信息 posts/hugo-papermod/add-document-info-footer
5 设置外链在新标签页打开 posts/hugo-papermod/set-external-links-to-open..
6 文章底部添加相关文章 posts/hugo-papermod/add-related-posts
7 添加 Giscus 评论 posts/hugo-papermod/add-giscus-comment
8 添加不蒜子记录站点和文章浏览量 posts/hugo-papermod/add-busuanzi-views

8. 结语

如果你部署过程中遇到了问题不知道如何解决(前提是你已思考过),可以通过微信、QQ、邮件联系我,建站嘛,图一乐,交个朋友。

版权声明

作者: Donghai

链接: https://mgrowup.com/posts/hugo-papermod/create-blog/

许可证: CC BY-NC-SA 4.0

文章已根据知识共享署名-非商业性使用-相同方式共享4.0国际许可协议授权。请注明来源,仅非商业使用,并保持相同的许可协议。

评论

开始搜索

输入关键词搜索文章内容

↑↓
ESC
⌘K 快捷键