{"id":21520730,"url":"https://github.com/re-zero-khis/gitbook-server-docker","last_synced_at":"2025-04-09T22:17:31.306Z","repository":{"id":45694364,"uuid":"218995912","full_name":"re-zero-khis/gitbook-server-docker","owner":"re-zero-khis","description":"docker 一键部署 GitBook 服务器","archived":false,"fork":false,"pushed_at":"2023-04-23T11:12:18.000Z","size":1667,"stargazers_count":22,"open_issues_count":0,"forks_count":8,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-04-09T22:17:22.194Z","etag":null,"topics":["docker","gitbook","learning"],"latest_commit_sha":null,"homepage":"http://127.0.0.1:4000/","language":"Dockerfile","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/re-zero-khis.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null},"funding":{"github":null,"patreon":null,"open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"otechie":null,"lfx_crowdfunding":null,"custom":["https://lyy289065406.github.io/sponsor/"]}},"created_at":"2019-11-01T13:59:46.000Z","updated_at":"2025-03-21T08:02:40.000Z","dependencies_parsed_at":"2023-02-10T05:16:03.428Z","dependency_job_id":null,"html_url":"https://github.com/re-zero-khis/gitbook-server-docker","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/re-zero-khis%2Fgitbook-server-docker","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/re-zero-khis%2Fgitbook-server-docker/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/re-zero-khis%2Fgitbook-server-docker/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/re-zero-khis%2Fgitbook-server-docker/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/re-zero-khis","download_url":"https://codeload.github.com/re-zero-khis/gitbook-server-docker/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248119286,"owners_count":21050755,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["docker","gitbook","learning"],"created_at":"2024-11-24T01:03:33.928Z","updated_at":"2025-04-09T22:17:31.276Z","avatar_url":"https://github.com/re-zero-khis.png","language":"Dockerfile","funding_links":["https://lyy289065406.github.io/sponsor/"],"categories":[],"sub_categories":[],"readme":"# GitBook-Server-Docker\n\n\u003e docker 一键部署 GitBook 服务器\n\n------\n\n## 简介\n\n使用 [GitBook](https://docs.gitbook.com/) 的初衷主要是为了可以利用 Github 为数据载体，在线上和线下同时搭建个人博客。\n\n但是在线下搭建 GitBook 服务器最大的问题是环境部署复杂，因此本文利用 Docker 实现一键部署服务器。\n\n\u003e 在线上部署的方法则比较多：\n\u003cbr/\u003e　利用 [GitBook](http://app.gitbook.com/) 官方提供的免费空间\n\u003cbr/\u003e　利用 GitHub Pages （有 300M 免费空间）\n\u003cbr/\u003e　租用个人云服务器，同样可以用 Docker 搭建\n\n------\n## 运行环境\n\n　![](https://img.shields.io/badge/Platform-Windows%2010%20x64-brightgreen.svg) ![](https://img.shields.io/badge/Platform-Linux%20x64-brightgreen.svg) ![](https://img.shields.io/badge/Platform-Mac%20x64-brightgreen.svg) \n\n\n\u003e 注：\n\u003cbr/\u003e　因为 gitbook 服务是运行在 Docker 中，所以不论使用哪个平台，都要预装好 Docker 环境\n\u003cbr/\u003e　但是本文所使用的基础镜像是基于 Linux 的，因此 Docker in Windows 是无法直接安装的\n\u003cbr/\u003e　所以针对 Windows 10 ，推荐使用 WSL ( Windows Subsystem for Linux )\n\u003cbr/\u003e　通过 WSL 安装 Ubuntu 系统，然后再[在 Ubuntu 里面安装 Docker Deamon](https://docs.docker.com/install/linux/docker-ce/ubuntu/)\n\u003cbr/\u003e　最后 Docker in Windows 做端口映射，就可以实现 Windows 到 Linux 的无缝对接\n\u003cbr/\u003e　具体的 Windows Docker 环境部署方法可参考 《[简书： Win10 内置 Ubuntu 完美使用 Docker in Windows](https://www.jianshu.com/p/97d16b68045f)》\n\u003cbr/\u003e　至于 Linux 和 Mac 则简单得多，直接安装 Docker Deamon 即可使用，具体方法自行谷歌\n\n\n\u003cdetails\u003e\n\u003csummary\u003e展开查看图片\u003c/summary\u003e\n\u003cbr/\u003e\n\n![](https://github.com/lyy289065406/gitbook-server-docker/blob/master/img/00.png)\n\n\u003c/details\u003e\n\n\n------\n## 使用方法\n\n### 构建 GitBook 镜像\n\n首先安装 `git` 命令行工具，然后 `clone` 本仓库到本地：\n\n`git clone https://github.com/lyy289065406/gitbook-server-docker`\n\n\n在命令行环境下 **打开本地仓库目录** 。 Docker 脚本已经编排好在 [`./Dockerfile`](https://github.com/lyy289065406/gitbook-server-docker/blob/master/Dockerfile) 中，可以不修改直接使用。\n\n构建 Docker 镜像（镜像名称 `exp/gitbook-server` 可根据 Docker 规范自定义修改）：\n\n`docker build . -t exp/gitbook-server:latest`\n\n![](https://github.com/lyy289065406/gitbook-server-docker/blob/master/img/01.png)\n\n\n至此镜像已经安装完毕，下文主要是测试 GitBook 镜像是否可用。\n\n\n\n### 初始化 GitBook 项目\n\n在 Docker 镜像中执行命令 `gitbook init`：\n\n`docker run --rm -v \"$PWD/gitbook:/gitbook\" exp/gitbook-server gitbook init`\n\n\u003e　该命令会自动创建用于 **示例** 的 GitBook 文件 。\n\u003cbr/\u003e　实际效果就是在工作目录 `./gitbook` 下创建两个符合 GitBook 语法的文件 `README.md` 和 `SUMMARY.md` 。\n\u003cbr/\u003e　*更多的 GitBook 语法详见 《[GitBook 学习笔记](https://yangjh.oschina.io/gitbook/)》*\n\n![](https://github.com/lyy289065406/gitbook-server-docker/blob/master/img/02.png)\n\n\n\n\n### 构建 GitBook 项目\n\n在 Docker 镜像中执行命令 `gitbook build`：\n\n`docker run --rm -v \"$PWD/gitbook:/gitbook\" exp/gitbook-server gitbook build`\n\n\u003e　该命令会根据 GitBook 文件 `README.md` 和 `SUMMARY.md` 构建 html 项目 。\n\u003cbr/\u003e　实际效果就是在工作目录 `./gitbook` 下构建目录名为 `_book` 的静态网页文件 。\n\u003cbr/\u003e　本地可以通过 `./gitbook/_book/index.html` 测试访问 。\n\n![](https://github.com/lyy289065406/gitbook-server-docker/blob/master/img/03.png)\n\n\n\n\n### 启动 GitBook 服务\n\n\n在 Docker 镜像中执行命令 `gitbook serve`：\n\n`docker run --rm -v \"$PWD/gitbook:/gitbook\" -p 4000:4000 exp/gitbook-server gitbook serve`\n\n\u003e 该命令效果就是构建一个可以访问 `./gitbook/_book/index.html` 的 Web 服务。\n\n![](https://github.com/lyy289065406/gitbook-server-docker/blob/master/img/04.png)\n\n\n\n------\n## FAQ\n\n\n### 0x01 前文中 Docker 命令的参数是什么含义？\n\n`docker run --rm -v \"$PWD/gitbook:/gitbook\" -p 4000:4000 exp/gitbook-server \u003cCommand\u003e`\n\n- `docker run`：运行镜像\n- `--rm`：退出镜像后自动删除运行时产生的数据（此镜像目的是提供 GitBook 服务的运行环境，因此没必要保留数据）\n- `-v \"$PWD/gitbook:/gitbook\"`：把本地工作目录 `$PWD/gitbook` 挂载到镜像的工作目录 `/gitbook` （这样运行 GitBook 期间的工作数据就会从本地映射到镜像内，即使镜像退出运行，数据依旧会保留在本地）\n- `-p 4000:4000`：把镜像内 GitBook 的 4000 服务端口暴露到本地物理机的 4000 端口\n- `exp/gitbook-server`：目标镜像名称\n- `\u003cCommand\u003e`：要在镜像内执行的命令，如 `gitbook serve` 等，更多命令可见 [gitbook-cli](https://github.com/GitbookIO/gitbook-cli)\n\n\n\n### 0x02 怎样以后台运行方式启动 GitBook 服务？\n\n增加 `-d` 参数即可：\n\n`docker run -d --rm -v \"$PWD/gitbook:/gitbook\" -p 4000:4000 exp/gitbook-server gitbook serve`\n\n\n\n### 0x03 怎样停止 GitBook 服务？\n\n先用 `docker ps` 命令查看正在运行的 GitBook 容器，然后执行命令 `docker stop \u003cCONTAINER ID\u003e` 即可 。\n\n![](https://github.com/lyy289065406/gitbook-server-docker/blob/master/img/05.png)\n\n\n\n### 0x04 怎样进入这个 Docker 镜像？\n\n执行下面命令即可：\n\n`docker run --rm -v \"$PWD/gitbook:/gitbook\" -it exp/gitbook-server /bin/sh`\n\n- `-it`：表示以交互方式运行\n- `/bin/sh`：此镜像的基础镜像是 `node:8.5-alpine` ，shell 只支持 `/bin/sh`\n\n\n\n### 0x05 怎样安装 GitBook 插件？\n\nGitBook 的精粹在于丰富的插件以扩展其功能，插件可通过工作目录下的 [`book.json`](https://github.com/lyy289065406/exp-blog/blob/master/gitbook/book.json) 配置并控制，相关说明见 [官方文档](https://docs.gitbook.com/v2-changes/important-differences#plugins)。\n\n推荐 GitBook 安装的插件可参考 [这份清单](http://gitbook.zhangjikai.com/plugins.html) 。\n\n根据插件命名约定，若 **插件名称** 为 `prism` ，则其对应 **安装包名称** 为 `gitbook-plugin-prism` 。\n\n以 `prism` 插件为例，安装方式有两种：\n\n- 通过 GitBook 安装：把插件名称 `prism` 添加到 `book.json` 的 `plugins` 列表，执行 `gitbook install` 命令\n- 通过 nodejs 安装：执行 `npm install gitbook-plugin-prism` 命令安装指定插件，然后把插件名称 `prism` 配置到 `book.json` 的 `plugins` 列表使其生效\n\n\u003e　方法一每次执行都会检查现有插件是否需要更新。 \n\u003cbr/\u003e　方法二只有特定插件受影响，适合于存在自定义修改过插件代码的情况。\n\n\n注意， Guthub Pages 不支持使用了 Octopress 框架的插件，详见 《[About GitHub Pages and Jekyll](https://help.github.com/en/github/working-with-github-pages/about-github-pages-and-jekyll)》 。\n\n若使用了这类插件，Guthub Pages 是无法发布成功的。 判定是不是使用了这类插件的方法也很简单：\n\n- 提交变更内容后，点击 Github 仓库下的 branch 查看 master 分支\n- master 分支会提示最近提交内容的 Guthub Pages 构建情况\n- 若构建失败，可以点击 Details 查看详情\n- 假如提示 `is not a recognised Liquid tag` 说明就是采用了 Octopress 框架的插件\n\n![](https://github.com/lyy289065406/gitbook-server-docker/blob/master/img/08.png)\n![](https://github.com/lyy289065406/gitbook-server-docker/blob/master/img/09.png)\n![](https://github.com/lyy289065406/gitbook-server-docker/blob/master/img/10.png)\n\n\n\n### 0x06 怎样开发 GitBook 自定义插件？\n\n\u003e 参考[这里](https://github.com/iuap-design/blog/issues/11)\n\n\n\n### 0x07 怎样共享这个 Docker 镜像？\n\n先执行 `docker login` 命令登陆，然后提交到个人的 Docker Hub 仓库：\n\n`docker push exp/gitbook-server:latest`\n\n\n若提示 *denied: requested access to the resource is denied* 提交失败，是因为镜像 tag 名称 `/` 前面部分的空间名不是个人的用户名，先修改 tag 名称即可（例如我的用户名是 *expm02* ）：\n\n`docker tag fdc060ba7253 expm02/gitbook-server:latest`\n\n![](https://github.com/lyy289065406/gitbook-server-docker/blob/master/img/06.png)\n\n\n\n### 0x08 怎样获取共享的 Docker 镜像？\n\n直接执行以下命令即可（这样就不用执行前文的安装步骤了）：\n\n`docker pull expm02/gitbook-server:latest`\n\n![](https://github.com/lyy289065406/gitbook-server-docker/blob/master/img/07.png)\n\n\n### 0x09 Github Page 构建超时？\n\nGitBook 构建的仓库有个问题，会随着内容增多、构建次数增加，变得越来越大。\n\n当仓库超过一定大小时， Github Page 会因为超时而构建失败。\n\n此时最有效的做法就是清洗仓库历史记录，按顺序执行以下命令即可：\n\n```\nrm -rf .git\ngit init\ngit add -A\ngit commit -m \"clear history\"\ngit remote add origin \u003cGITHUB_REPO_URL\u003e\ngit push -f -u origin master\n```\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fre-zero-khis%2Fgitbook-server-docker","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fre-zero-khis%2Fgitbook-server-docker","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fre-zero-khis%2Fgitbook-server-docker/lists"}