如何利用Gitbook部署整本书

💡

GitBook makes it easy to plan, centralize and share knowledge, from start to ship.

Gitbook 是什么

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

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

安装完之后，就会多了一个 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

执行完后，你会看到多了两个文件 —— README.md 和 SUMMARY.md，它们的作用如下：


README.md —— 书籍的介绍写在这个文件里
SUMMARY.md —— 书籍的目录结构在这里配置

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)

1234567891011

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"
    ],
}

1234567

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


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

12345

[3] 侧边栏宽度可调节


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

12345

[4] 回到顶部按钮


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

12345

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


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

1234567891011

[6] 隐藏元素

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


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

12345678910

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

[7] 代码块行号、复制


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

12345

[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"
            }
        }
    }
}

12345678910111213141516

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
        },
    }
}

1234567891011

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"
        },
    }
}

123456789101112

[11] 添加RSS订阅


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

1234567891011121314

#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/"
        }
    }
}

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566

至此，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

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


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

12345

注意：.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 "xxx@xxx.com"

然后一路回车，这时你就会在用户下的.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 "you@example.com"
[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 # 将本地仓库推送至远程仓库

12345678910111213141516

说明：

用户名和邮箱设置：在 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

[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 # 将本地仓库推送至远程仓库

123456

为了提交方便，可以创建一个脚本文件 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 -

1234567891011121314151617181920212223

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


$ 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 -

1234567891011121314151617181920212223242526272829303132333435

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

文件保存后，在终端执行如下命令，把生成的项目推送到 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 使用OneinStack搭建Nginx并进行配置

#5.1.1 OneinStack简介

项目简介：OneinStack是一套部署开发环境的脚本工具，它的部署方式是纯原生部署，我主要使用里面的Nginx，用来辅助生成配置。

项目地址：https://github.com/oneinstack/oneinstack(opens new window)

#5.1.2 使用OneinStack搭建Nginx服务


$ wget -c http://mirrors.linuxeye.com/oneinstack-full.tar.gz && tar xzf oneinstack-full.tar.gz && ./oneinstack/install.sh --nginx_optio

注：OneinStack采用编译安装的方式搭建Nginx服务，速度比较慢，请耐心等待，常用的默认目录有：


Nginx安装目录: /usr/local/nginx
Nginx配置目录：/usr/local/nginx/conf
网站数据目录：/data/wwwroot/域名

123

#5.1.3 创建网站开启HTTPS

OneinStack 内置了 acme.sh，它会自动帮你申请 SSL 证书。


$ cd ./oneinstack
$ ./vhost.sh

配置过程的参考示例如下（示例域名为www.demo.com）：


#######################################################################
#       OneinStack for CentOS/RedHat 7+ Debian 8+ and Ubuntu 16+      #
#       For more information please visit https://oneinstack.com      #
#######################################################################

What Are You Doing?
        1. Use HTTP Only
        2. Use your own SSL Certificate and Key
        3. Use Let's Encrypt to Create SSL Certificate and Key
        q. Exit
Please input the correct option: 2 【选择2】（使用了Cloudfare CDN的话，可以选择自签名证书）

Please input domain(example: www.example.com): www.demo.com 【输入域名】
domain=www.demo.com

Please input the directory for the domain:www.demo.com :
(Default directory: /data/wwwroot/www.demo.com): 【回车，使用默认配置】
Virtual Host Directory=/data/wwwroot/www.demo.com

Create Virtul Host directory......
set permissions of Virtual Host directory......

Do you want to add more domain name? [y/n]: n  【输入n，不添加其他域名了】

Do you want to redirect all HTTP requests to HTTPS? [y/n]: y  【输入y，强制HTTPS】

You are about to be asked to enter information that will be incorporated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.

Country Name (2 letter code) [CN]: 【回车】

State or Province Name (full name) [Shanghai]: 【回车】

Locality Name (eg, city) [Shanghai]: 【回车】

Organization Name (eg, company) [Example Inc.]: 【回车】

Organizational Unit Name (eg, section) [IT Dept.]: 【回车】

Do you want to add hotlink protection? [y/n]: n 【输入n，不需要防盗链保护】

Allow Rewrite rule? [y/n]: y 【输入y，允许重写规则】

Please input the rewrite of programme :
wordpress,opencart,magento2,drupal,joomla,codeigniter,laravel
thinkphp,pathinfo,discuz,typecho,ecshop,nextcloud,zblog,whmcs rewrite was exist.
(Default rewrite: other): 【回车】
You choose rewrite=other

Allow Nginx/Tengine/OpenResty access_log? [y/n]: y  【输入y，允许日志记录】
You access log file=/data/wwwlogs/www.demo.com_nginx.log

#######################################################################
#       OneinStack for CentOS/RedHat 7+ Debian 8+ and Ubuntu 16+      #
#       For more information please visit https://oneinstack.com      #
#######################################################################
Your domain:                  www.demo.com
Virtualhost conf:             /usr/local/nginx/conf/vhost/www.demo.com.conf
Directory of:                 /data/wwwroot/www.demo.com
Rewrite rule:                 /usr/local/nginx/conf/rewrite/other.conf
Self-signed SSL Certificate:  /usr/local/nginx/conf/ssl/www.demo.com.crt
SSL Private Key:              /usr/local/nginx/conf/ssl/www.demo.com.key
SSL CSR File:                 /usr/local/nginx/conf/ssl/www.demo.com.csr

12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758596061626364656667

配置完成后，修改一下配置文件


$ vim /usr/local/nginx/conf/vhost/www.demo.com.conf

server模块删除内容：


  location ~ [^/]\.php(/|$) {
    #fastcgi_pass remote_php_ip:9000;
    fastcgi_pass unix:/dev/shm/php-cgi.sock;
    fastcgi_index index.php;
    include fastcgi.conf;
  }

  location /.well-known {
    allow all;
  }

12345678910

server模块新增内容：


location ^~ /.well-known/acme-challenge/ {
  default_type "text/plain";
  allow all;
  root /data/wwwroot/www.demo.com/;  # 把路径换一下
}

12345

检查并重载Nginx配置


$ nginx -t
$ nginx -s reload

注：使用nginx -t命令可以检查Nginx配置，若出现如下内容则说明配置正确。


nginx: the configuration file /usr/local/nginx/conf/nginx.conf syntax is ok
nginx: configuration file /usr/local/nginx/conf/nginx.conf test is successful

之后把资源文件放置到 /data/wwwroot/www.demo.com 目录即可，打开Chrome浏览器即可访问（如果出现403则需要给这个目录添加一下权限）。

#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

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


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

123

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


$ 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参数初始化为裸仓库，这样创建的仓库不包含工作区

1234

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文件里

1234

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;
  }

12345678

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


    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;
    }

1234567891011121314151617181920212223

检查并重载Nginx配置


$ nginx -t
$ nginx -s reload

#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文件并编辑

复制下面的内容到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}

123456789

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


$ 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 -

123456789101112131415161718192021222324252627

注：部署到自己服务器可以不配置.gitignore忽略文件，不允许访问的资源用Nginx限制，如果要配置注意别忽略_book文件夹了。

部署成功之后，我们访问https://域名地址就可以看到我们的Gitbook网站了。

攻略2：

使用Gitbook生成在线文档的流程本机安装Node.js环境安装GitBook；生成本地文档文件编辑本地文档；

构建静态页面；

将静态页面推送到GitHub Pages服务；

访问对应url。

注：Node.js环境只用于本机生成&编译App和静态页面，如果使用服务端自建git，服务端无需安装Node.js环境，只需同步静态页面后，用其他web容器访问静态页面即可。

配置流程

在 https://nodejs.org/ 下载并安装Node.js

安装GitBook，终端输入

npm install gitbook-cli -g

gitbook init

编辑SUMMARY.md文件，生成目录结构

再次执行gitbook init生成文件目录

编辑其他.md文件，并在编辑结束后，执行gitbook init

编辑中预览效果，执行

gitbook serve

浏览器访问http://localhost:4000

创建静态页

gitbook build

生成_book目录

使用git将所有文件夹/仅_book文件夹同步至网络服务

访问对应url。

注：推荐使用类GitHub Pages服务。

GitBook开源地址：https://github.com/GitbookIO/gitbook
GitBook安装说明：https://github.com/GitbookIO/gitbook/blob/master/docs/setup.md