通过 Git Hook 自动部署 Hexo 博客到 1Panel 站点

阳小楊2025-12-062025-04-29

通过 Git Hook 自动部署 Hexo 博客到 1Panel 站点

作者： fan

本文将介绍如何配置服务器端的 Git 仓库和钩子（Hook），以实现在本地执行 hexo deploy 命令时，自动将 Hexo 生成的静态文件部署到由 1Panel 面板管理的网站目录中。这种方法避免了手动上传文件的繁琐过程，实现了类似 CI/CD 的自动化部署流程。

前提条件

在开始之前，请确保你已满足以下条件：

服务器

安装了 1Panel 面板的 Linux 服务器。
拥有服务器的 SSH 访问权限（本文示例将使用 root 用户，你可以根据实际情况替换为其他有权限的用户）。
服务器上已安装 Git。

1Panel 配置

已通过 1Panel 创建了一个网站（例如 blog.yourdomain.com），并记下该网站的 根目录（Document Root）。通常在 1Panel 中，路径类似于 /opt/1panel/apps/openresty/openresty/www/sites/你的网站目录/index。请务必替换为你的实际路径。

本地环境

你的电脑上已安装并配置好 Hexo 博客环境。
你的电脑上已安装 Git。
已安装 Hexo Git 部署插件：

npm install hexo-deployer-git --save

SSH 密钥认证（关键）

你需要在本地电脑生成 SSH 密钥对（如果还没有的话）。
必须将你的本地电脑的 SSH 公钥添加到服务器上对应用户（如 root）的 ~/.ssh/authorized_keys 文件中。这样可以确保 hexo deploy 时 Git PUSH 操作无需输入密码即可完成。

配置步骤

步骤一：在服务器上安装 Git

如果你的服务器尚未安装 Git，请根据你的 Linux 发行版执行相应命令：

Debian/Ubuntu:

sudo apt-get update
sudo apt-get install git -y

Fedora/RedHat/CentOS:

sudo yum install git -y

步骤二：在服务器上创建 Git 裸仓库（Bare Repository）

我们需要在服务器上创建一个 Git “裸仓库”。裸仓库不包含工作目录（即你看不到项目文件），只存储 Git 的版本历史和对象数据，非常适合作为中心仓库或中转仓库。

选择一个路径来存放你的 Git 仓库。例如，我们选择放在 /root/git/ 目录下（你可以自定义路径）。

# 创建目录 (如果父目录不存在，也一并创建)
mkdir -p /root/git/

如果你不是一直使用 root 用户，或者希望更精细地控制权限，可以修改目录所有者和权限。如果使用 root，此步通常可以跳过。

# 将目录所有者改为当前用户 (如果用 root 执行，则为 root)
# chown -R $USER:$USER /root/git/
# 设置权限 (所有者完全控制，同组用户读取执行，其他用户读取执行)
# chmod -R 755 /root/git/

初始化裸仓库

进入你选择的目录，并初始化一个裸仓库。我们将仓库命名为 blog.git（你也可以自定义）。

cd /root/git
git init --bare blog.git

执行后，你会在 /root/git/ 目录下看到一个名为 blog.git 的文件夹。

步骤三：在服务器上配置 Git 钩子（post-receive）

Git 钩子是在 Git 操作过程中的特定时间点自动执行的脚本。post-receive 钩子在服务器成功接收到推送（push）后执行。我们将利用这个钩子将推送过来的 Hexo 文件检出（checkout）到 1Panel 的网站根目录。

创建钩子文件

进入裸仓库的 hooks 目录，并创建一个名为 post-receive 的文件。

vim /root/git/blog.git/hooks/post-receive

编辑钩子内容

在 vim 编辑器中，按 i 进入插入模式，然后粘贴以下脚本内容：

#!/bin/bash
# 指定 Hexo 网站文件存放的目录 (!!!!务必替换为你的 1Panel 网站实际根目录!!!!)
WORK_TREE="/opt/1panel/apps/openresty/openresty/www/sites/blog/index"
# 指定 Git 裸仓库的路径 (!!!!务必替换为你的裸仓库实际路径!!!!)
GIT_DIR="/root/git/blog.git"
# 执行 Git checkout 命令，强制将内容检出到工作目录
git --work-tree=${WORK_TREE} --git-dir=${GIT_DIR} checkout -f
echo "Hexo blog deployed to ${WORK_TREE}"

重要说明：

--work-tree：必须修改为你在 1Panel 中创建的那个网站的实际根目录路径。
--git-dir：必须修改为你刚刚创建的 Git 裸仓库的路径（blog.git）。
checkout -f：-f 参数表示强制检出，会覆盖目标目录中已有的文件。

保存并退出 Vim

按下 ESC 键退出插入模式，然后输入 :wq! 并按回车键，强制保存并退出 Vim。

赋予钩子执行权限

新创建的钩子文件默认没有执行权限，需要添加：

chmod +x /root/git/blog.git/hooks/post-receive

步骤四：修改本地 Hexo 配置

现在，配置你本地 Hexo 博客的 _config.yml 文件，告诉它如何部署。

打开你本地 Hexo 项目根目录下的 _config.yml 文件。

找到 deploy 部分（如果不存在，请添加）。

修改或添加 git 部署配置，如下所示：

deploy:
  type: git
  repo: ssh://root@YOUR_SERVER_IP:22/root/git/blog.git # !!! 修改 IP 和路径 !!!
  branch: main # 或者 master，取决于你希望推送的分支
  # message: "Site updated: {{ now('YYYY-MM-DD HH:mm:ss') }}" # 可选的提交信息

请务必修改：

root：替换为你配置了 SSH 免密登录的服务器用户名。
YOUR_SERVER_IP：替换为你的服务器公网 IP 地址或域名。
22：如果你的 SSH 端口不是默认的 22，请修改。
/root/git/blog.git：替换为你在服务器上创建的裸仓库的绝对路径。
branch：确保这个分支名（main 或 master）与你的 post-receive 钩子期望检出的分支一致（默认情况下 checkout -f 会检出仓库的 HEAD 指向的分支，通常是 master 或 main）。

步骤五：部署你的 Hexo 博客

一切配置完成后，部署就非常简单了：

在本地 Hexo 项目目录下，执行标准的生成和部署命令：

hexo clean && hexo generate && hexo deploy

或者直接：

hexo d

工作流程

hexo g 生成静态文件到 public 目录。
hexo d 使用 hexo-deployer-git 插件：
- 将 public 目录的内容提交到一个临时 Git 分支。
- 通过 SSH 将这个分支强制推送到你配置的服务器裸仓库（ssh://root@YOUR_SERVER_IP:22/root/git/blog.git）。
服务器上的 Git 仓库接收到推送后，自动触发 post-receive 钩子脚本。
钩子脚本执行 git checkout -f，将最新的网站文件强制检出（部署）到 1Panel 网站的根目录（/opt/1panel/apps/openresty/openresty/www/sites/blog/index）。

验证

部署命令执行成功后，稍等片刻，然后访问你的博客域名（http://blog.yourdomain.com 或 https://blog.yourdomain.com），应该就能看到更新后的内容了。

故障排除提示

权限问题：检查服务器上 Git 仓库目录、网站根目录以及钩子文件的权限是否正确。钩子脚本需要有权限写入网站根目录。
SSH 密钥问题：确保本地 SSH 公钥已正确添加到服务器的 authorized_keys 文件中，并且本地 SSH 私钥可用。尝试手动 ssh root@YOUR_SERVER_IP 看是否能免密登录。
路径错误：仔细核对 post-receive 脚本中的 --work-tree 和 --git-dir 路径，以及本地 _config.yml 中的 repo 路径是否完全正确。
钩子未执行：检查钩子文件是否有执行权限（chmod +x），文件名是否精确为 post-receive（没有扩展名）。
查看日志：如果部署失败，可以尝试在服务器上查看 SSH 或 Git 相关日志，或者在钩子脚本中添加一些 echo 输出到日志文件来调试。

通过以上配置，你就实现了一个高效、自动化的 Hexo 博客部署流程！