搭建Gitbook并通过Git推送部署

yoyo 6/8/2021 GitbookGithubGit-Hooks

# 1. Gitbook 简介

# 1.1 Gitbook 是什么

Gitbook (opens new window) 是一个使用 Git 和 Markdown 来构建电子书籍的开源工具。它既可以生成一个静态网站，也可以输出内容作为电子书（ePub，Mobi，PDF）。Gitbook 可以在本地、Github、VPS 等平台上部署，本文采用的是借助 Node.js 在本地部署然后推送到 Github Page 托管的方式，其余的就不再赘述了。

效果展示：本站的 Found (opens new window) 即为Gitbook搭建的。

Found-Gitbook

# 1.2 准备工作

工欲善其事，必先利其器。在开始搭建 Gitbook 电子书籍之前，你需要先了解一下 Markdown 基本语法、Git 及 Github 基本使用，然后作出如下准备：

Node.js 环境：Gitbook 在本地部署时所需要的环境。
Markdown 编辑器：推荐使用 Typora，用来编写 Gitbook 文档的具体内容。
Git 工具 +Github 账号：用于将 Gitbook 托管到 Github 存储库上。
翻墙工具：推荐使用 SSR，本文所提到的部分工具的官网需要翻墙才能打开。

# 2. Gitbook 本地部署

# 2.1 Gitbook 本地安装

Step1：安装 Node.js

因为 GitBook 是基于 Node.js 的，所以我们首先需要下载安装 Node.js (opens new window)（对应平台的.msi版本即可）
测试：打开cmd，输入node -v和npm -v，若显示node和npm的版本号即安装成功。

Step2：安装 gitbook-cli 工具

gitbook-cli 是一个在系统上安装和使用 Gitbook 的工具，它将自动安装所需版本的 Gitbook 来构建一本书。
现在安装 Node.js 都会默认安装 npm（node 包管理工具），所以我们不用单独安装 npm，打开命令行，执行以下命令安装 GitBook
```
npm install -g gitbook-cli
```
1
安装完之后，就会多了一个 gitbook 命令（如果没有，请确认上面的命令是否加了 -g）

Step3：安装 Git

官网下载 Git：https://www.git-scm.com/download/win (opens new window)
安装过程中一路 next 即可，安装成功后桌面右键单击出现 Git GUI Here 以及 Git Bash Here

Step4：安装 Typora

官网下载 Typora：https://www.typora.io/ (opens new window)
说明：Typora 可以配合 pandoc 插件将 Markdown 转换成其他格式的文件

# 2.2 Gitbook 本地使用

Step1：初始化 Gitbook

新建一个存储 Gitbook 的文件夹（即工作区），切换到该目录，然后用如下命令初始化：
```
gitbook init
```
1
执行完后，你会看到多了两个文件 —— README.md 和 SUMMARY.md，它们的作用如下：
```
README.md —— 书籍的介绍写在这个文件里
SUMMARY.md —— 书籍的目录结构在这里配置
```
1
2

Step2：用 Typora 编辑一个示例

编辑 SUMMARY.md 文件，内容修改为：

# 目录

- [前言](README.md)
- [第一章](Chapter1/README.md)
  - [第1节：衣](Chapter1/衣.md)
  - [第2节：食](Chapter1/食.md)
  - [第3节：住](Chapter1/住.md)
  - [第4节：行](Chapter1/行.md)
- [第二章](Chapter2/README.md)
- [第三章](Chapter3/README.md)
- [第四章](Chapter4/README.md)

1
2
3
4
5
6
7
8
9
10
11

Step3：在本地部署 Gitbook

回到命令行，在 Gitbook 的工作区文件夹中再次执行 gitbook init 命令。GitBook 会查找 SUMMARY.md 文件中描述的目录和文件，如果没有则会将其创建。
接着我们再执行 gitbook serve 命令，将其部署在本地，打开 Chrome 访问：http://localhost:4000 (opens new window)，即可看到本地部署的 Gitbook（注：serve 命令可以指定端口 gitbook serve --port 2333）
当你写得差不多，你可以执行 gitbook build 命令构建书籍，默认将生成的静态网站输出到 _book 目录。实际上，这一步也包含在 gitbook serve 里面（注：build 命令可以指定路径 gitbook build [书籍路径] [输出路径]，如果你想查看输出目录详细的记录，可使用 gitbook build ./ --log=debug --debug 来查看）

常见问题：

[1] gitbook编译问题

问题描述：使用 gitbook build 或者 gitbook serve 时偶发出现不规律性编译错误的问题，每次修改要编译屡次才能成功，为后续的 Github page 部署带来了很大的麻烦。
解决办法：修改 C:\Users\xxx\.gitbook\versions\3.2.3\lib\output\website\copyPluginAssets.js 文件中的 112 行（将 confirm: true 改成 confirm: false）

[2] node.js版本问题

问题描述：编译时报错 polyfills.js:287 if (cb) cb.apply(this, arguments) TypeError: cb.apply is not a function
产生原因：因开发前端项目时升级了node.js版本所致，不支持这个版本的gitbook。
解决办法：一种是把node.js降级回去，第二种方式是注释掉报错代码（这个函数的作用是用来修复node.js的一些bug，用处不大）

打开C:\Users\xxx\AppData\Roaming\npm\node_modules\gitbook-cli\node_modules\npm\node_modules\graceful-fs\polyfills.js文件，找到287行的statFix函数，把它的调用处注释掉即可。

# 2.3 Gitbook 导出其他格式

方法一：使用 Typora 导出

使用自带的导出功能即可（配合Pandoc可导出除pdf和html以外的格式、导出的pdf带书签）Pandoc官网 (opens new window)
可能存在“安装完之后，还是提示需要安装pandoc”的问题，此时可重新启动电脑，或者卸载Typora重新安装。

方法二：使用 calibre 导出

Step1：安装 calibre 软件

Gitbook 可以将电子书或文档导出为 PDF、ePub、Mobi 等格式，导出这三种格式需要依赖 calibre 软件提供的 ebook-convert 库。
calibre 官网下载：https://calibre-ebook.com/download (opens new window)，新版本在安装时已自动配置了环境变量，无需手动添加，安装完后在命令行中用 ebook-convert --version 验证一下。

Step2：将 Gitbook 导出其他格式

生成 PDF 格式的电子书：gitbook pdf ./ ./mybook.pdf
生成 epub 格式的电子书：gitbook epub ./ ./mybook.epub
生成 mobi 格式的电子书：gitbook mobi ./ ./mybook.mobi

# 3. Gitbook 配置文件

如果你想对你的网站有更详细的个性化配置或使用插件，那么需要使用配置文件。配置文件写完后，需要重启服务或者重新打包才能应用配置。Gitbook 的配置文件是book.json，请在项目的根目录处自行创建。

# 3.1 配置文件主要参数

title：标题
author：作者
description：描述，对应 Gitbook 网站的 description
language：使用的语言，zh-hans 是简体中文，会对应到页面的<html lang="zh-hans" >
structure：指定 Readme、Summary、Glossary 和 Languages 对应的文件名
plugins：使用的插件列表，所有的插件都在这里写出来，然后使用 gitbook install 来安装。
pluginsConfig：插件的配置信息，如果插件需要配置参数，那么在这里填写。
links：目前可以给侧导航栏添加链接信息
styles：自定义页面样式，各种格式对应各自的 css 文件

# 3.2 Gitbook 的常用插件

# 3.2.1 Gitbook 插件简介

[1] 为什么要用插件？

Gitbook 默认自带以下 5 个插件：highlight：代码高亮、search：导航栏查询功能（不支持中文）、sharing：右上角分享功能、font-settings：字体设置（最上方的"A"符号）、livereload：为 Gitbook 实时重新加载。Gitbook 插件可以解决一些网站不太方便的地方，如侧边栏导航不能收缩，自带搜索不支持中文等问题。

[2] 去哪里找插件？

除了下文推荐的插件之外，Gitbook 还支持许多其他插件，可以从NPM (opens new window) 上搜索 Gitbook 相关的插件。

[3] 插件安装方法：

Step1：在项目的根目录中创建 book.json 文件，然后在 plugins 参数中添加插件名。
Step2：使用 gitbook install 来安装插件，重启服务 gitbook serve 或者重新打包 gitbook build 就能看见效果。

注意：

编写 json 时字符串不能用“单引号”括起，最后的那个不能有“逗号”。
如果要卸载自带的 font-settings，插件处应写成 -fontsettings，中间不要加 -。
gitbook install 命令有时会出现问题，多试几次可能就好了。
gitbook install 命令安装慢，而且是全部插件都安装一遍，如果只安装一个插件的话建议使用npm命令安装。

# 3.2.2 Gitbook 插件推荐

[1] 支持中文的搜索框

{
    "plugins": [
         "-lunr", 
         "-search", 
         "search-pro"
    ],
}

1
2
3
4
5
6
7

[2] 左侧章节目录可折叠

{
    "plugins": [
         "expandable-chapters-small"
    ],
}

1
2
3
4
5

[3] 侧边栏宽度可调节

{
    "plugins": [
    	"splitter"
    ],
}

1
2
3
4
5

[4] 回到顶部按钮

{
    "plugins": [
        "back-to-top-button"
    ],
}

1
2
3
4
5

[5] 右上角添加 github 图标跳转

{
    "plugins": [
        "-sharing",
        "github"
    ],
    "pluginsConfig": {
        "github": {
            "url": "项目仓库地址"
        },
    }
}

1
2
3
4
5
6
7
8
9
10
11

[6] 隐藏元素

可以隐藏不想看到的元素，hide-element 是通过 HTML 元素的 class 名字来查找要隐藏的元素，想要隐藏元素找到元素的样式类名加到插件配置里面就可以隐藏元素了。

{
    "plugins": [
        "hide-element"
    ],
    "pluginsConfig": {
        "hide-element": {
            "elements": [".gitbook-link"]
        },
    }
}

1
2
3
4
5
6
7
8
9
10

经过该配置之后，导航栏中 Published by GitBook 就被隐藏了。

[7] 代码块行号、复制

{
    "plugins": [
        "code"
    ],
}

1
2
3
4
5

[8] 修改标题栏图标

{
    "plugins": [
        "favicon"
    ],
    "pluginsConfig": {
        "favicon": {
            "shortcut": "assets/images/favicon.ico",
            "bookmark": "assets/images/favicon.ico",
            "appleTouch": "assets/images/apple-touch-icon.png",
            "appleTouchMore": {
                "120x120": "assets/images/apple-touch-icon-120x120.png",
                "180x180": "assets/images/apple-touch-icon-180x180.png"
            }
        }
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

shortcut通常可以被所有可以显示favicon的浏览器读取。

bookmark是在收藏夹中显示自己的图标。

apple-touch-icon是一个类似网站favicon的图标文件，用来在iphone和iPad上创建快捷键时使用。apple-touch-icon这个文件应当是png格式，默认：57x57像素大小。如果准备的文件不是57x57的话，它会自己缩放的。

[9] 添加悬浮目录

{
    "plugins" : [ 
        "page-toc-button" 
    ],
    "pluginsConfig": {
        "page-toc-button": {
            "maxTocDepth": 2,
            "minTocSize": 2
        },
    }
}

1
2
3
4
5
6
7
8
9
10
11

maxTocDepth：标题的最大深度（最大支持到 2，即为 h1+h2+h3）

minTocSize：显示 toc 按钮的最小 toc 条目数

[10] 添加版权信息和最后修改时间

{
    "plugins": [
       "tbfed-pagefooter"
    ],
    "pluginsConfig": {
        "tbfed-pagefooter": {
            "copyright":"Copyright &copy 版权信息",
            "modify_label": "该文件修订时间：",
            "modify_format": "YYYY-MM-DD HH:mm:ss"
        },
    }
}

1
2
3
4
5
6
7
8
9
10
11
12

[11] 添加RSS订阅

{
    "plugins": [ 
   		 "rss" 
     ],
    "pluginsConfig": {
        "rss":{
            "title": "标题",
            "description": "描述信息",
            "author": "作者",
            "feed_url": "https://xxx.xxx.xxx/rss",
            "site_url": "https://xxx.xxx.xxx/"
        }
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14

# 3.3 Gitbook 成品配置

以下是我配好的 book.json 文件，仅供参考。

{
    "title": "标题",
    "description": "描述信息",
    "author": "作者",
    "output.name": "site",
    "language": "zh-hans",
    "gitbook": "3.2.3",
    "root": ".",
    "links": {
        "sidebar": {
            "sidebar标题": "sidebar地址"
        }
    },
    "plugins": [
         "-lunr", 
         "-search",
         "-sharing",
         "-fontsettings",
         "highlight",
         "livereload",
         "search-pro",
         "expandable-chapters-small",
         "splitter",
         "back-to-top-button",
         "github",
         "hide-element",
         "code",
         "custom-favicon",
         "page-toc-button",
         "tbfed-pagefooter",
         "rss"
    ],
    "pluginsConfig": {
        "github": {
            "url": "项目仓库地址"
        },
        "hide-element": {
            "elements": [".gitbook-link"]
        },
        "favicon": {
            "shortcut": "assets/images/favicon.ico",
            "bookmark": "assets/images/favicon.ico",
            "appleTouch": "assets/images/apple-touch-icon.png",
            "appleTouchMore": {
                "120x120": "assets/images/apple-touch-icon-120x120.png",
                "180x180": "assets/images/apple-touch-icon-180x180.png"
            }
        },
       "page-toc-button": {
            "maxTocDepth": 2,
            "minTocSize": 2
        },
        "tbfed-pagefooter": {
            "copyright":"Copyright &copy 版权信息",
            "modify_label": "该文件修订时间：",
            "modify_format": "YYYY-MM-DD HH:mm:ss"
        },
        "rss":{
            "title": "标题",
            "description": "描述信息",
            "author": "作者",
            "feed_url": "https://xxx.xxx.xxx/rss",
            "site_url": "https://xxx.xxx.xxx/"
        }
    }
}

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
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66

至此，Gitbook的本地搭建就已经完成了，下面讲述两种部署Gitbook的方式：一种是托管到Github page，另一种是托管到自己的VPS上，如果有服务器的话，建议选择后者。

# 4. 托管到 Github Page

这部分需要使用 Git 和 Github 网站，可以参见我的另一篇博文：Git 及 Github 基本使用 (opens new window)

由于 Gitbook 生成的项目跟文档的源码是两个部分，所以可以把文档放到 master 分支上，部署的网站放到 gh-pages 分支。

# 4.1 本地项目提交到 Github 仓库

[1] 创建git忽略文件

有些文件是不需要纳入到版本控制之中的，在项目根目录创建一个名为.gitignore的git忽略文件，编辑内容如下：

# 忽略gitbook生成的项目目录
_book

1
2

下面是一些.gitignore文件忽略的匹配规则：

*.a       # 忽略所有 .a 结尾的文件
!lib.a    # 但 lib.a 除外
/TODO     # 仅仅忽略项目根目录下的 TODO 文件，不包括 subdir/TODO
build/    # 忽略 build/ 目录下的所有文件
doc/*.txt # 会忽略 doc/notes.txt 但不包括 doc/server/arch.txt

1
2
3
4
5

注意：.gitignore只能忽略那些原来没有被track的文件，如果某些文件已经被纳入了版本管理中，则修改.gitignore文件是无效的。那么解决方法就是先把本地缓存删除（改变成未track状态），然后再提交。

[2] SSH KEY

由于本地 Git 仓库和 Github 仓库之间的传输是通过 SSH 加密的，所以连接时需要设置一下：

Step1：先看一下 C:\Users\xxx 有没有.ssh 目录，有的话看下里面有没有 id_rsa 和 id_rsa.pub 这两个文件，有就跳到下一步，没有就通过下面命令创建:

$ ssh-keygen -t rsa -C "[email protected]"

然后一路回车，这时你就会在用户下的.ssh 目录里找到 id_rsa 和 id_rsa.pub 这两个文件

Step2：登录 Github,找到右上角的图标，打开点进里面的 Settings，再选中里面的 SSH and GPG KEYS，点击右上角的 New SSH key，然后 Title 里面随便填，再把刚才 id_rsa.pub 里面的内容复制到 Title 下面的 Key 内容框里面，最后点击 Add SSH key，这样就完成了 SSH Key 的加密。

[3] 初次部署

[1] 设置用户名和邮箱
git config --global user.name "Your Name"
git config --global user.email "[email protected]"
[2] 连接到远程仓库并设置记住用户名和密码
git remote add origin URL # 连接到远程仓库并创建别名
git config --global credential.helper store # 设置自动记住用户名和密码（第一次push会被记住，后续无需再输入）
[3] 解决使用git add命令时报错LF will be replaced by CRLF的问题
git config auto.crlf true
[4] 将项目从本地提交到仓库
git init # 创建git工作区
git add . # 提交所有文件到暂存区
git status # 查看git状态
git commit -m 'description' # 提交到仓库，''内的是描述信息
[5] 将代码推送至远程仓库
git pull origin master --allow-unrelated-histories # 取回远程仓库分支的更新，再与本地的分支合并
git push -u origin master # 将本地仓库推送至远程仓库

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

说明：

用户名和邮箱设置：在 github 仓库主页显示谁提交了该文件，要根据 github 的注册信息来填写，不要填错了。
git init 后，在文件夹内生成.git 文件（如果没有，则 查看——勾选“隐藏的项目”）
仓库地址可在 clone or download 按钮下取得（即仓库的浏览器地址栏末尾加 .git）
使用 git pull origin master 命令报错：fatal:refusing to merge unrelated histories

错误原因：如果合并了两个不同的开始提交的仓库，在新的 git 会发现这两个仓库可能不是同一个，为了防止开发者上传错误，于是就出现了此提示。
解决办法：如我在 Github 新建一个仓库，写了 License，然后把本地一个写了很久仓库上传。这时会发现 github 的仓库和本地的没有一个共同的 commit 所以 git 不让提交，认为是写错了 origin ，如果开发者确定是这个 origin 就可以使用 --allow-unrelated-histories 告诉 git 允许不相关历史合并

使用 git push origin master 命令报错：error:failed to push some refs to URL

错误原因：直接在 GitHub 上修改后，内容已经和本地不一致了，必须要合并（merge）
解决办法：先使用 git pull origin master 命令下载到本地并合并，自动弹出的 vim 编辑器（按 i 进行编辑，说明为什么合并，可选择不修改，ESC 进入命令行模式然后输入 :wq 退出），再 git push origin master

使用 git add .命令报错：warning: LF will be replaced by CRLF

原因：在 Unix 系统中，行尾用换行（LF）表示。在窗口中，用回车（CR）和换行（LF）（CRLF）表示一行。当您从 unix 系统上载的 git 中获取代码时，它们将只有 LF。
解决办法：如果您是在 Windows 计算机上工作的单个开发人员，并且您不关心 git 自动将 LF 替换为 CRLF，则可以通过在 git 命令行中键入以下内容来关闭此警告
```
git config core.autocrlf true
```
1

[4] 后续使用

git config auto.crlf true # 解决使用git add命令时报错LF will be replaced by CRLF的问题
git add . # 提交所有文件到暂存区
git status # 查看git状态
git commit -m 'description' # 提交到仓库，''内的是描述信息
git pull origin master # 取回远程仓库分支的更新，再与本地的分支合并
git push origin master # 将本地仓库推送至远程仓库

1
2
3
4
5
6

为了提交方便，可以创建一个脚本文件 commit.sh 来自动执行，内容如下：

# 切换到上一级目录
echo '切换到上一级目录\n'
cd ..

# 解决使用git add命令时报错LF will be replaced by CRLF的问题
echo '执行命令：git config auto.crlf true\n'
git config auto.crlf true

# 保存所有的修改
echo '执行命令：git add -A\n'
git add -A

# 把修改的文件提交
echo "执行命令：git commit -m 'update gitbook'\n"
git commit -m 'update gitbook' 

# 将本地仓库推送至远程仓库
echo '执行命令：git push origin master\n'
git push origin master

# 返回到上一次的工作目录
echo "回到刚才工作目录"
cd -

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

编写好后，在终端运行以下命令即可：

$ bash commit.sh

# 4.2 上传到 Github 仓库的 gh-pages 分支

打包命令太多，为了部署方便，可以创建一个脚本文件 deploy.sh 来自动执行，内容如下：

# 切换到上一级目录
echo '切换到上一级目录\n'
cd ..

# 构建Gitbook
echo '执行命令：gitbook build .'
gitbook build .

# 进入生成的文件夹
echo "执行命令：cd ./_book\n"
cd ./_book

# 初始化一个仓库，仅仅是做了一个初始化的操作，项目里的文件还没有被跟踪
echo "执行命令：git init\n"
git init

# 解决使用git add命令时报错LF will be replaced by CRLF的问题
echo '执行命令：git config auto.crlf true\n'
git config auto.crlf true

# 保存所有的修改
echo "执行命令：git add -A"
git add -A

# 把修改的文件提交
echo "执行命令：commit -m 'deploy gitbook'"
git commit -m 'deploy gitbook'

# 发布到 https://<USERNAME>.github.io/<REPO>
echo "执行命令：git push -f 仓库地址.git master:gh-pages"
git push -f 仓库地址.git master:gh-pages

# 返回到上一次的工作目录
echo "回到刚才工作目录"
cd -

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

注意脚本文件代码中仓库地址要替换成你自己的地址。

文件保存后，在终端执行如下命令，把生成的项目推送到 github 仓库上的 gh-pages 分支：

$ bash deploy.sh

执行成功后，打开你的 github 仓库，然后选择 branch 分支，会发现多了一个 gh-pages 分支，打开这个分之后，里面会有一个 index.html 文件，说明部署的代码上传成功了。

# 4.3 查看 GitHub Page 网站

在 Github 网站上的项目仓库右侧，有一个 Environments，点进去之后再点击 View deployment，即可查看部署好的 GitHub Page。至此，我们的 Gitbook 就已经搭建完成了。

# 5. 托管到自己的VPS

以下我将采用Nginx+Docker部署的方式进行搭建，VPS系统用的是Debian 11 x86_64。VPS的购买及配置、域名解析、Docker的概念及使用...这些基本的就不再赘述了，如果不会的话见我的其他博客：VPS基本部署环境的搭建与配置 (opens new window)、Docker容器化及项目环境管理 (opens new window)。

# 5.1 搭建Nginx并进行配置

这里使用OneinStack搭建Nginx并进行配置，具体操作步骤此处不再赘述。

# 5.2 搭建服务器部署环境

# 5.2.1 VPS搭建Git环境

（1）安装配置Git

Step1：下载安装Git服务器

$ apt-get install git

Step2：验证是否安装成功

$ git --version

若显示版本信息则说明安装成功。

（2）创建用户并赋予权限

Step1：创建git用户

$ adduser git

用户名以git为例，根据提示设置密码。

Step2：赋予git用户权限

$ chmod 740 /etc/sudoers
$ nano /etc/sudoers

1
2

在root ALL=(ALL:ALL) ALL这一行下面添加git ALL=(ALL:ALL) ALL

# User privilege specification
root    ALL=(ALL:ALL) ALL
git     ALL=(ALL:ALL) ALL

1
2
3

保存退出后，修改回文件权限

$ chmod 440 /etc/sudoers

Step3：关闭git用户的shell权限

考虑到安全因素，需要禁止git用户ssh登录服务器，设置后git用户可以通过ssh正常使用git服务，但无法登录shell。

$ nano /etc/passwd

将最后一行的bash处改为git-shell

git:x:1001:1001:,,,:/home/git:/bin/bash 改成 git:x:1001:1001:,,,:/home/git:/bin/git-shell

（3）初始化git仓库并配置SSH

Step1：初始化git仓库

$ cd /home/git                    //切换到git用户目录
$ mkdir gitbook.git                  //创建仓库目录，以gitbook.git为例
$ cd gitbook.git                     //进入仓库目录
$ git init --bare                 //使用--bare参数初始化为裸仓库，这样创建的仓库不包含工作区

1
2
3
4

Step2：查看公钥

打开本地的 git bash，输入以下命令查看公钥（前提是本地已经配好了git环境并完成初始化），复制公钥

$ cat ~/.ssh/id_rsa.pub

Step3：配置SSH

$ cd /home/git                   //切换到git用户目录
$ mkdir .ssh                     //创建.ssh目录
$ cd .ssh                        //进入.ssh目录
$ nano authorized_keys           //将本地的公钥复制到authorized_keys文件里

1
2
3
4

Step4：用户组管理

修改/home/git/gitbook.git目录的用户组权限为git:git

$ sudo chown git:git -R /home/git/gitbook.git

修改后执行下列命令后再查看

$ ls -l /home/git

（4）本地连接远程仓库

打开本地的git bash，检出仓库并设置记住用户名和密码，然后我们就可以使用git进行版本控制了，git无需手动设置开机自启。

Step1：本地检出仓库

$ git clone ssh://git@ip:port/home/git/gitbook.git

Step2：设置记住用户名和密码

$ git config --global credential.helper store

# 5.2.2 VPS搭建网站环境

（1）新建网站

Step1：通用的创建网站开启HTTPS见本文5.1节。

Step2：修改网站根目录的用户组权限为git:git

$ sudo chown git:git -R 网站根目录

修改后执行下列命令后再查看

$ ls -l 网站根目录

（2）修改Nginx配置

在Nginx配置文件里注释掉以下代码

  location ~ .*\.(gif|jpg|jpeg|png|bmp|swf|flv|mp4|ico)$ {
    expires 30d;
    access_log off;
  }
  location ~ .*\.(js|css)?$ {
    expires 7d;
    access_log off;
  }

1
2
3
4
5
6
7
8

再添加如下代码（按照自己的网站根目录来）

    location ~* ^.+\.(ico|gif|jpg|jpeg|png)$ {
        root 网站根目录;
        access_log   off;
        expires      1d;
    }

    location ~* ^.+\.(css|js|txt|xml|swf|wav)$ {
        root 网站根目录;
        access_log   off;
        expires      10m;
    }

    location / {
        root 网站根目录;
        if (-f $request_filename) {
        rewrite ^/(.*)$  /$1 break;
        }
    }

    location /nginx_status {
        stub_status on;
        access_log off;
    }

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

检查并重载Nginx配置

$ nginx -t
$ nginx -s reload

1
2

# 5.3 Git Hooks自动部署

# 5.3.1 自动部署原理

在本地编辑Markdown文章，然后使用Git推送到VPS的Git仓库。Git Hooks实际上就是当Git仓库收到最新的push时，将Git仓库接受到的内容复制到VPS上的网站目录内。相当于完成了手动将_book文件夹复制到VPS的网站根目录里的操作。

# 5.3.2 配置Git Hooks

创建post-receive文件

$ cd /home/git/gitbook.git/hooks     //切换到hooks目录下
$ nano post-receive               //创建post-receive文件并编辑

1
2

复制下面的内容到post-receive文件中：

#!/bin/bash
GIT_REPO=/home/git/gitbook.git
TMP_GIT_CLONE=/tmp/gitbook
TMP_GIT_COPY=/tmp/gitbook/_book
PUBLIC_WWW=网站根目录
rm -rf ${TMP_GIT_CLONE}
git clone $GIT_REPO $TMP_GIT_CLONE
rm -rf ${PUBLIC_WWW}/*
cp -rf ${TMP_GIT_COPY}/* ${PUBLIC_WWW}

1
2
3
4
5
6
7
8
9

保存退出后，赋予其执行权限

$ chmod +x post-receive

# 5.3.3 Gitbook提交推送并部署

我们可以写一个shell脚本来完成本地Git提交并推送的操作，然后VPS端通过先前配置好的Git Hooks自动部署。

# 切换到上一级目录
echo '切换到上一级目录\n'
cd ..

# 构建Gitbook
echo '执行命令：gitbook build .'
gitbook build .

# 解决使用git add命令时报错LF will be replaced by CRLF的问题
echo '执行命令：git config auto.crlf true\n'
git config auto.crlf true

# 保存所有的修改
echo "执行命令：git add -A"
git add -A

# 把修改的文件提交
echo "执行命令：commit -m 'deploy gitbook'"
git commit -m 'deploy gitbook'

# 强制推送到远程仓库
echo "执行命令：git push -f origin master"
git push -f origin master

# 返回到上一次的工作目录
echo "回到刚才工作目录"
cd -