跳转至

MkDocs VPS 部署方案

预计阅读时长 : 2 分钟

方案原理

能提升写作效率的最佳方式,就是能够随时随地的写作和发布。为了达成这个目标,真是来回折腾了好久,最后确定的流程是,在 VS Code 中写作完毕之后,以 git push 方式更新线上的 MkDocs 文档。

在折腾的过程中,一直被一个问题所困扰:git 仓库的当前工作分支无法接收 push。最终的解决方案是,使用默认分支来接收推送,然后使用 hook 自动将默认分支的更新 merge 到工作分支,这样 MkDocs 就能检测到 docs 文件夹下的变动自动完成更新。

不得不说,花了这么长时间折腾的主要原因是对 Git 的原理理解不够深刻。等到完全调通了之后,觉得这真的是一个非常优雅的方案啊。

对最终的成果非常的满意,😄 。同时,感谢 GPT-4 的大力协助,真是 10 倍工作效率神器啊。

创建远程仓库

首先,在 VPS 上创建一个仓库,并对其进行初始化:

mkdir -p /path/to/yourgitcd /path/to/yourgitgit init

然后,创建一个文件并提交,用来创建 master 分支。紧接着,再创建 work 分支并切换到 work 分支:

echo "Initial commit" > README.mdgit add README.mdgit commit -m "Initial commit"git checkout -b work

注意:最后一步非常关键,只有将工作分支 checkout 到 work 分支,后续基于 push 至 master 分支而触发的 hook 才能正常工作。

配置 Hook

下一步,我们在 /.git/hooks/ 下创建 post-receive 文件,并添加以下的内容:

#!/bin/sh

export GIT_DIR=$(pwd)
export GIT_WORK_TREE=$(dirname $(pwd)) # (1)

while read oldrev newrev refname # (2)
do
    branch=$(git rev-parse --symbolic --abbrev-ref $refname) # (3)
    if [ "$branch" = "master" ]; then
        if git show-ref --quiet refs/heads/work; then
            git checkout work
            git reset --hard HEAD # (4)
        else
            git checkout -b work # (5)
        fi

        git merge master --allow-unrelated-histories # (6)
    fi
done
  1. 设置 Git 环境变量
  2. 从标准输出获取推送信息
  3. 获取推送发生的分支
  4. 清空 work 分支的工作区
  5. 如果 work 分支不存在,则创建并切换
  6. 合并 master 分支的更改,参数用于解决合并冲突

并为 post-receive 钩子设置执行权限:

chmod +x /path/to/yourgit/.git/hooks/post-receive

本地仓库推送

完成了 VPS 上的配置之后,接下去首先需要为本地仓库上添加远程存储库,具体的操作流程见 SSH 秘钥使用简要说明

# 使用 SSH 连接方式,并使用证书登录,注意仓库地址的格式git remote add tencent git@example.com:/path/to/yourgit

然后,将本地的 main 分支强制推送到远程的 master 分支,并设置它们之间的跟踪关系:

git push -u tencent main:master --force

完成以上步骤之后,后续只需将本地修改后的 main 分支推送至远程的 master 分支,即可触发 post-receive 的 hook,实时更新 MkDocs 文档的内容。