Hexo：语雀云端写作，Github Actions持续集成

本是古典何须时尚 2023-07-10 14:26 25阅读 0赞

本文章为原创内容，只发布于[我的私人博客][Link 1]、[我的 Django 博客][Django] 和 [本博客][Link 2] ，转载请注明，谢谢

--------------------

本文已被 yuque-hexo 的开发作者列为最佳实践典型

--------------------

使用 Hexo 静态博客网站发表文章，需要

1.  本地以Markdown的形式写好文章
2.  借助 Hexo 生成静态页面
3.  部署到云主机或者通过 git 到托管平台

既然要本地借助 [Hexo][] 生成静态页面，那就需要设置 [Node.js][] 环境和博客源码，虽然环境设置简单，源码从Github、coding、gitee、gitlab等地方下载方便，但是在换电脑之后，又要重复相同的事情，还是比较麻烦，前一阵我用 [docker][] 将我的博客源码打包成镜像留存下来，也是面临同样的问题，就是换电脑后还要安装 `docker` 和 `docker-compose`，也是麻烦。

当我遇见了 [Github Actions][] 和 [yuque-hexo][] 后，一切都发生了变化

简单来说就是

> 由 Hexo + 语雀 + yuque-hexo + Github Actions + web hook + severless 打造的持续集成个人博客

> 至于托管平台，Github Pages or Coding Pages or VPS or Other，自行选择。

*  Github 保存博客源码，私有库已经免费，还在用`Travis CI`？非开源的私有项目想在 `Travis CI` 上构建价格还是非常感人的!
 *  [Github Actions][Github Actions 1] 是 [Github][] 推出的一款持续集成工具，**完全免费**
 *  [语雀][Link 3] 是阿里人都在用的笔记与文档知识库，专业的云端知识库，支持`web hook`
 *  [yuque-hexo][] 是 [Github][] 上开源的一款语雀知识库同步工具
 *  `severless` 是云函数，当前 [腾讯云函数][Link 4] 和 [阿里云函数][Link 5]都可以免费提供，对于博客，免费额度足够了，可以对比一下费用自行选择

# 关于 Hexo #

[Hexo][] 是一款基于 [Node.js][] 的静态博客框架，其快速、简洁且高效。没有数据库和后台的概念。

*  超快速度，`Node.js` 所带来的超快生成速度，让上百个页面在几秒内瞬间完成渲染。
 *  `Hexo` 支持 `GitHub` `Flavored` `Markdown` 的所有功能，甚至可以整合 `Octopress` 的大多数插件。
 *  一键部署，只需一条指令即可部署到 GitHub Pages, Heroku 或其他平台。
 *  插件和可扩展性，强大的 API 带来无限的可能，与数种模板引擎（EJS，Pug，Nunjucks）和工具（Babel，PostCSS，Less/Sass）轻易集成

# 关于 Github Actions #

不妨先去了解一下

[About GitHub Actions][Github Actions 1]

[GitHub Actions 入门教程][GitHub Actions]

[\[译\] GitHub Actions 介绍，了解一下？][GitHub Actions 1]

我的[博客 持续集成和交付 专栏][Link 6] 有实例可以去参考一下，后续还会继续更新。

或者 [我的 CSDN 博客][CSDN]

## repository\_dispatch ##

**之所以有了这篇文章是因为我看到了`Github Actions`中的外部事件`repository_dispatch`**

*  [Github Help 关于 repository\_dispatch][Github Help _ repository_dispatch]
 *  [RepositoryDispatchEvent][]
 *  [Create a repository dispatch event][]
 *  [Triggering GitHub Actions across different repositories][]
 *  [How to run GitHub Actions manually][]
 *  [Setting up Webhooks for Github Actions][]

`GitHub Actions` 支持的外部事件`repository_dispatch` 必须具有以下请求头：

curl -X POST https://api.github.com/repos/:owner/:repo/dispatches \
        -H 'Accept: application/vnd.github.everest-preview+json' \
        -H "Authorization: token GITHUB_PERSONAL_ACCESS_TOKEN" \
        -d '{"event_type":"start"}'

如果返回的 Response 是 `Status: 204 No Content`，那就是成功了，去 Github 中看一看，事件已经被触发，这个可以使用 postman 测试一下  
![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3pfam9obm55_size_16_color_FFFFFF_t_70]  
注意，Accept 具有`application/vnd.github.everest-preview+json`自定义媒体类型值。

语雀中的`Web Hook`是不能添加请求头的，所有我们就需要一个中间件把他们连接起来，这个就是`serverless云函数`

# 具体流程 #

1.  Hexo 博客搭建好，将源码上传到 Github，私有还是公有库都可以
2.  在 Github 中开启 Github Actions 服务，配置 yaml 格式的deploy脚本
3.  注册语雀，创建知识库并发布一篇文章，必须发布过文章，因为 yuque-hexo 会删除 \_posts 文件夹
4.  编写 serverless函数 ，测试可以触发 Github Actions，获取触发地址
5.  配置语雀的 webhook，使其可调用 serverless 函数
6.  触发 Github Actions 实现 Hexo 的自动部署，生成静态文件并发布  
    ![format_png][]

**下面以Github Actions将Hexo生成的静态页面推送到Github Pages举例**

## 创建 Github Pages ##

1.  登录github
2.  创建项目，项目名字`username.github.io`，必须为公开库

## 创建 Hexo 博客并配置 ##

可参考：

*  [超详细Hexo+Github Page搭建技术博客教程【持续更新】][Hexo_Github Page]
 *  [Hexo + GitHub 搭建个人博客][Hexo _ GitHub]
 *  教程非常多，善用搜索

配置完成，本地预览达到自己满意，编写文章发布一切搞定后就能继续了。

## 创建 Github 源码仓库 ##

在github上创建存放 Hexo源码 的仓库，此仓库和 Pages 不是一个仓库，并将源码push到此仓库

> 私有库和公开库都可以，放在 Pages 仓库其他分支也行，本教程是基于单独的 Hexo 源码仓库

## 配置 Github Actions 脚本 ##

两种方法配置，内容一样

1.  在Hexo源码仓库的页面选择`Actions-->Set up a workflow yourself`，进行网页编写
2.  在本地环境根目录创建`.github/workflows`文件夹，里面放写好的 yaml 脚本

脚本我以一种举例，其他方法同样可以实现，请查看[我的博客][Link 1]

如

*  [Github Actions：通过 SSH 自动部署 Hexo][Github Actions_ SSH _ Hexo]
 *  [Github Actions：通过 API 自动部署 Hexo][Github Actions_ API _ Hexo]

# workflow name
    name: Deploy To Github Pages
    
    # 当有 push 到仓库和外部触发的时候就运行
    on: [push, repository_dispatch]
    
    # YUQUE_TOKEN
    # Github_SSH_PRIVATE_KEY
    jobs:
      deploy: 
        name: Deploy Hexo Public To Pages
        runs-on: ubuntu-latest 
        env:
          TZ: Asia/Shanghai    
            
        steps:
        # check it to your workflow can access it
        # from: https://github.com/actions/checkout
        - name: Checkout Repository master branch
          uses: actions/checkout@master 
          
        # from: https://github.com/actions/setup-node 
        - name: Setup Node.js 10.x 
          uses: actions/setup-node@master
          with:
            node-version: "10.x"
        
        # from https://github.com/x-cold/yuque-hexo
        - name: Setup Hexo Dependencies and Generate Public Files
          env:
            YUQUE_TOKEN: ${ {  secrets.YUQUE_TOKEN }}
          run: | npm install hexo-cli -g npm install yuque-hexo -g npm install npm run start
            
        # from https://github.com/peaceiris/actions-gh-pages 
        - name: Deploy
          uses: peaceiris/actions-gh-pages@v3
            with:
              deploy_key: ${ {  secrets.Github_SSH_PRIVATE_KEY }}
              external_repository: 用户名/仓库
              publish_branch: master
              publish_dir: ./public
              commit_message: ${ {  github.event.head_commit.message }}

这个脚本实现了发布 Hexo 的 Public 到 Pages，这只是一种方法，你也可以使用 [hexo d][Github Actions_ SSH _ Hexo] 、[API][Github Actions_ API _ Hexo]、[github-pages-deploy-action][]等形式进行发布。

但是现在你还不能运行，因为里面的隐藏参数还没有设置  
![format_png 1][]

<table> 
 <thead> 
  <tr> 
   <th align="center">参数</th> 
   <th align="left">说明</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td align="center">YUQUE_TOKEN</td> 
   <td align="left">从语雀获取的TOKEN，语雀上点击个人头像 --&gt; 设置 --&gt; Token 即可获取，要在Hexo源仓库的Settings–&gt;Secrets中进行添加，对重要信息进行保密</td> 
  </tr> 
  <tr> 
   <td align="center">Github_API_Token</td> 
   <td align="left">是<code>SSH-Key</code>密钥中的私钥，需要在<code>Secrets</code>中进行添加，公钥（.pub）已经存储在 Github 中</td> 
  </tr> 
 </tbody> 
</table>

## 配置腾讯云函数 ##

1.  登录腾讯云，搜索云函数，创建
2.  选择 `python`，2.7和3.6都行，空白函数
3.  运行角色，`SCF_QcsRole` 即可
4.  注意执行方法，有强制要求

![format_png 2][]  
![format_png 3][]

这里我使用的是python 2.7

# -*- coding: utf8 -*-
    import requests
    
    def main_handler(event, context):
        r = requests.post("https://api.github.com/repos/用户名/仓库名/dispatches",
        json = { "event_type": "start"},
        headers = { "User-Agent":'curl/7.52.1',
                  'Content-Type': 'application/json',
                  'Accept': 'application/vnd.github.everest-preview+json',
                  'Authorization': 'token Github访问Token'})
    
        if r.status_code == 204:
            return "This's OK!" 
        else:
            return r.status_code

在函数代码中测试一下，如果Actions正常触发，大功告成

1.  配置触发方式，保存，获取到**访问路径**

*  触发方式：API网关触发器
 *  API服务类型：新建API服务
 *  API服务：SCF\_API\_SERVICE
 *  请求方法：ANY
 *  发布环境：发布
 *  鉴权方法：免鉴权
 *  启动集成响应：未启用  
    ![format_png 4][]

## 配置语雀 ##

### 语雀上 ###

1.  注册，登录
2.  创建知识库–>文档知识库–>可见范围为互联网可见
3.  工作台–>知识库–>找到新创建的知识库，管理–>设置–>路径进行自定义，后面有用  
    ![format_png 5][]
4.  工作台–>知识库–>找到新创建的知识库，管理–>设置–>开发者–>名称任意。URL为云函数的地址，即上面获取到的访问路径  
    ![format_png 6][]

权限建议选择

*  仅主动推送更新触发（强烈建议）
 *  发布文档
 *  更新文档
 *  删除文档

### hexo源码上 ###

可本地更新后push或者直接github网页修改

先安装 [yuque-hexo][]

npm install yuque-hexo --save

编辑package.json文件，添加以下内容

Npm Scripts “start” 和 yuqueConfig，将操作命令合并为一个脚本，只需要执行`npm run start`即可完成语雀的同步和Hexo的清理和静态文件生成，yueque记得要用最新版本

{ 
    
     ...
     
      "scripts": { 
        "start": "yuque-hexo clean && yuque-hexo sync && hexo clean && hexo generate",
        "build": "hexo generate",
        "clean": "hexo clean",
        "deploy": "hexo deploy",
        "server": "hexo server"
      },
      
     ...
     
      "yuqueConfig": { 
        "baseUrl": "https://www.yuque.com/api/v2",
        "login": "语雀个人路径",
        "repo": "知识库名称",
        "mdNameFormat": "title",
        "postPath": "source/_posts",
        "onlyPublished": false
      }
    }

# Come on 发布文章 #

无论是发布新文章还是更新删除等等操作，只要选择“文档有较大更新，推送给关注知识库的人”即可自动触发  
![format_png 7][]

--------------------

**下面推荐了一下我的博客主题，算是广告吧~！！**

# 关于 halo #

本人目前使用的主题是 [hexo-theme-halo][] ，这是一个采用 [Material Design][] 和响应式设计的 Hexo 博客主题。 是博主基于 [hexo-theme-matery][] 主题修改而来。

[主题演示][Link 1]

## 特性 ##

*  简单漂亮，文章内容美观易读
 *  [Material Design][] 设计
 *  博客名字动态显示，文章信息统计统页面展示
 *  响应式设计，博客在桌面端、平板、手机等设备上均能很好的展现
 *  首页轮播文章及每天动态切换 `Banner` 图片，首页轮播图设置为70%页面高度
 *  首页`subtitle`替换打字效果，添加动态诗词自动切换，
 *  瀑布流式的博客文章列表（文章无特色图片时会有 `24` 张漂亮的图片代替）
 *  时间轴式的归档页，`增加简约风归档页面`
 *  分类页、标签页和`标签云`同一页面显示，集中展示
 *  丰富的关于我页面（包括关于我、文章统计图、我的项目、我的技能、相册等可自定义）
 *  可自定义的数据的友情链接页面
 *  支持文章置顶和文章打赏
 *  类似于Python Django中`SLUG`用法的urlname
 *  支持 `MathJax`
 *  `TOC` 目录
 *  可设置复制文章内容时追加版权信息
 *  可设置阅读文章时做密码验证
 *  [Gitalk][]、[Gitment][]、[Valine][] 和 [Disqus][] 评论模块（推荐使用 `Gitalk`）
 *  集成了[不蒜子统计][Link 7]、谷歌分析（`Google Analytics`）和文章字数统计等功能
 *  支持在首页的音乐播放和视频播放功能
 *  支持`emoji`表情，用`markdown emoji`语法书写直接生成对应的能**跳跃**的表情。
 *  支持 [DaoVoice][]、[Tidio][] 在线聊天功能。

## 下载 ##

当你看到这里的时候，应该已经有一个自己的 [Hexo][Hexo 1] 博客了。如果还没有的话，不妨使用 `Hexo` 和 [Markdown][] 来写博客和文章。

点击 [这里][Link 8] 下载 `master` 分支的最新稳定版的代码，解压缩后，将 `hexo-theme-halo` 的文件夹复制到你 Hexo 的 `themes` 文件夹中，并修改主题配置项即可。

当然你也可以在你的 `themes` 文件夹下使用 `git clone` 命令来下载:

git clone https://github.com/hongweifuture/hexo-theme-halo.git themes/halo

## 配置 ##

详情请参照 [hexo-theme-halo][]

[Link 1]: https://www.zhwei.cn/
[Django]: https://blog.zhwei.cn/
[Link 2]: https://blog.csdn.net/z_johnny
[Hexo]: https://hexo.io/
[Node.js]: https://nodejs.org/
[docker]: https://www.docker.com/
[Github Actions]: https://help.github.com/en/actions/getting-started-with-github-actions/about-github-actions
[yuque-hexo]: https://github.com/x-cold/yuque-hexo
[Github Actions 1]: https://help.github.com/cn/actions/getting-started-with-github-actions/about-github-actions
[Github]: https://github.com/
[Link 3]: https://www.yuque.com/
[Link 4]: https://cloud.tencent.com/product/scf/
[Link 5]: https://www.aliyun.com/ss/?k=serverless
[GitHub Actions]: http://www.ruanyifeng.com/blog/2019/09/getting-started-with-github-actions.html
[GitHub Actions 1]: https://juejin.im/post/5be191736fb9a049de6cd463
[Link 6]: https://www.zhwei.cn/categories/%E6%8C%81%E7%BB%AD%E9%9B%86%E6%88%90%E5%92%8C%E4%BA%A4%E4%BB%98
[CSDN]: https://blog.csdn.net/z_johnny/category_6218500.html
[Github Help _ repository_dispatch]: https://help.github.com/en/actions/reference/events-that-trigger-workflows
[RepositoryDispatchEvent]: https://developer.github.com/v3/activity/events/types/#repositorydispatchevent
[Create a repository dispatch event]: https://developer.github.com/v3/repos/#create-a-repository-dispatch-event
[Triggering GitHub Actions across different repositories]: https://blog.marcnuri.com/triggering-github-actions-across-different-repositories/
[How to run GitHub Actions manually]: https://medium.com/@christinavhastenrath/how-to-run-github-actions-manually-afebbe77d325
[Setting up Webhooks for Github Actions]: http://www.btellez.com/posts/triggering-github-actions-with-webhooks.html
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3pfam9obm55_size_16_color_FFFFFF_t_70]: https://img-blog.csdnimg.cn/20200311115250758.png?x-oss-process=image/watermark,type_ZmFuZ3poZW5naGVpdGk,shadow_10,text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3pfam9obm55,size_16,color_FFFFFF,t_70
[format_png]: https://imgconvert.csdnimg.cn/aHR0cHM6Ly9jZG4uanNkZWxpdnIubmV0L2doL2hvbmd3ZWlmdXR1cmUvanNEZWxpdnJDRE4vaW1nL0c0LnBuZw?x-oss-process=image/format,png
[Hexo_Github Page]: https://segmentfault.com/a/1190000017986794
[Hexo _ GitHub]: https://www.jianshu.com/p/23e9e27eb437
[Github Actions_ SSH _ Hexo]: https://www.zhwei.cn/github-actions-deploy-hexo-ssh/
[Github Actions_ API _ Hexo]: https://www.zhwei.cn/github-actions-deploy-hexo-api/
[github-pages-deploy-action]: https://github.com/JamesIves/github-pages-deploy-action
[format_png 1]: https://imgconvert.csdnimg.cn/aHR0cHM6Ly9jZG4uanNkZWxpdnIubmV0L2doL2hvbmd3ZWlmdXR1cmUvanNEZWxpdnJDRE4vaW1nL0c3LnBuZw?x-oss-process=image/format,png
[format_png 2]: https://imgconvert.csdnimg.cn/aHR0cHM6Ly9jZG4uanNkZWxpdnIubmV0L2doL2hvbmd3ZWlmdXR1cmUvanNEZWxpdnJDRE4vaW1nL0cxLnBuZw?x-oss-process=image/format,png
[format_png 3]: https://imgconvert.csdnimg.cn/aHR0cHM6Ly9jZG4uanNkZWxpdnIubmV0L2doL2hvbmd3ZWlmdXR1cmUvanNEZWxpdnJDRE4vaW1nL0cyLnBuZw?x-oss-process=image/format,png
[format_png 4]: https://imgconvert.csdnimg.cn/aHR0cHM6Ly9jZG4uanNkZWxpdnIubmV0L2doL2hvbmd3ZWlmdXR1cmUvanNEZWxpdnJDRE4vaW1nL0czLnBuZw?x-oss-process=image/format,png
[format_png 5]: https://imgconvert.csdnimg.cn/aHR0cHM6Ly9jZG4uanNkZWxpdnIubmV0L2doL2hvbmd3ZWlmdXR1cmUvanNEZWxpdnJDRE4vaW1nL0c1LnBuZw?x-oss-process=image/format,png
[format_png 6]: https://imgconvert.csdnimg.cn/aHR0cHM6Ly9jZG4uanNkZWxpdnIubmV0L2doL2hvbmd3ZWlmdXR1cmUvanNEZWxpdnJDRE4vaW1nL0c2LnBuZw?x-oss-process=image/format,png
[format_png 7]: https://imgconvert.csdnimg.cn/aHR0cHM6Ly9jZG4uanNkZWxpdnIubmV0L2doL2hvbmd3ZWlmdXR1cmUvanNEZWxpdnJDRE4vaW1nL0c4LnBuZw?x-oss-process=image/format,png
[hexo-theme-halo]: https://github.com/hongweifuture/hexo-theme-halo
[Material Design]: https://material.io/
[hexo-theme-matery]: https://github.com/blinkfox/hexo-theme-matery
[Gitalk]: https://gitalk.github.io/
[Gitment]: https://imsun.github.io/gitment/
[Valine]: https://valine.js.org/
[Disqus]: https://disqus.com/
[Link 7]: http://busuanzi.ibruce.info/
[DaoVoice]: http://www.daovoice.io/
[Tidio]: https://www.tidio.com/
[Hexo 1]: https://hexo.io/zh-cn/
[Markdown]: https://www.appinn.com/markdown/
[Link 8]: https://codeload.github.com/hongweifuture/hexo-theme-halo/zip/master