因公司服务需要重构,架构也提出了一套自己用markdown写的的开发指南,里面包括一些框架以及各种流程图和一些代码的开发规范,也有一些常用网站供开发者们写代码时进行参考;现在需要运维来将这些markdown文件转换为html文件并使用nginx(web)展示出来;
发布方式分为:
因为使用gitbook进行编译需要依赖于node环境,所以先安装node;
[root@k8s-master ~]# tar -zxf node-v15.14.0-linux-x64.tar.gz
[root@k8s-master ~]# mv node-v15.14.0-linux-x64 /usr/local/node-v15.14.0
[root@k8s-master local]# vim /etc/profile #设置环境变量
##node-v15.14.0##
export NODE_HOME=/usr/local/node-v15.14.0
export PATH=$NODE_HOME/bin:$PATH
[root@k8s-master ~]# source /etc/profile
[root@k8s-master ~]# node -v
v15.14.0
[root@k8s-master ~]# npm -v
7.7.6
安装gitbook-cli
[root@k8s-master ~]# npm install gitbook-cli -g
...
npm notice
npm notice New major version of npm available! 7.7.6 -> 8.12.2
npm notice Changelog: https://github.com/npm/cli/releases/tag/v8.12.2
npm notice Run npm install -g [email protected] to update!
npm notice
在安装完gitbook-cli之后需要执行gitbook -V命令安装gitbook库(gitbook-cli 构建需要依赖gitbook 库)并验证是否安装成功
提示:其实这里不一定要执行gitbook -V命令,后面第4步构建的时候执行gitbook build命令也行;
[root@k8s-master ~]# gitbook -V
CLI version: 2.3.2
Installing GitBook 3.2.3
/usr/local/node-v15.14.0/lib/node_modules/gitbook-cli/node_modules/npm/node_modules/graceful-fs/polyfills.js:287
if (cb) cb.apply(this, arguments)
^
TypeError: cb.apply is not a function
at /usr/local/node-v15.14.0/lib/node_modules/gitbook-cli/node_modules/npm/node_modules/graceful-fs/polyfills.js:287:18
at FSReqCallback.oncomplete (node:fs:194:5)
可用看到在执行gitbook命令的时候报错了,根据报错信息我们可用看到没有找到function这个函数,这个是因为版本问题,我们把有关使用这个函数的代码去掉就可以了;
[root@k8s-master ~]# vim /usr/local/node-v15.14.0/lib/node_modules/gitbook-cli/node_modules/npm/node_modules/graceful-fs/polyfills.js
//fs.stat = statFix(fs.stat) #这三行代码大约在62行,给他注释掉就可以了
//fs.fstat = statFix(fs.fstat)
//fs.lstat = statFix(fs.lstat)
然后再次gitbook -V查看;
[root@k8s-master ~]# gitbook -V
CLI version: 2.3.2
Installing GitBook 3.2.3
[email protected] ../../tmp/tmp-18981Z4Mwyfs1QNRu/node_modules/gitbook
├── [email protected]
├── [email protected]
├── [email protected]
├── [email protected]
├── [email protected]
├── [email protected]
...
└── [email protected]
GitBook version: 3.2.3
安装gitbook完成;
[root@k8s-master ~]# git clone https://gitee.com/xxxx.git
Cloning into 'xxxx'...
Username for 'https://gitee.com': xxxx
Password for 'https://[email protected]':
remote: Enumerating objects: 341, done.
remote: Counting objects: 100% (341/341), done.
remote: Compressing objects: 100% (330/330), done.
remote: Total 341 (delta 193), reused 0 (delta 0), pack-reused 0
Receiving objects: 100% (341/341), 464.85 KiB | 349.00 KiB/s, done.
Resolving deltas: 100% (193/193), done.
[root@k8s-master ~]# ll dev-doc/
total 8
drwxr-xr-x 2 root root 41 Jun 18 19:50 attachment
drwxr-xr-x 2 root root 38 Jun 18 19:50 components
drwxr-xr-x 2 root root 20 Jun 18 19:50 faq
drwxr-xr-x 2 root root 100 Jun 18 19:50 images
drwxr-xr-x 2 root root 101 Jun 18 19:50 introduction
drwxr-xr-x 3 root root 222 Jun 18 19:50 project
-rw-r--r-- 1 root root 185 Jun 18 19:50 README.md
drwxr-xr-x 2 root root 302 Jun 18 19:50 scaffold
-rw-r--r-- 1 root root 2213 Jun 18 19:50 SUMMARY.md
提示:这个SUMMARY.md文件是很重要的,他类似于目录,gitbook编译的时候需要有这个文件
[root@k8s-master ~]# ll dev-doc/introduction/
total 20
-rw-r--r-- 1 root root 81 Jun 18 19:50 arch.md
-rw-r--r-- 1 root root 2198 Jun 18 19:50 framework.md
-rw-r--r-- 1 root root 124 Jun 18 19:50 oauthflow.md
-rw-r--r-- 1 root root 69 Jun 18 19:50 简介.md
-rw-r--r-- 1 root root 1918 Jun 18 19:50 网站地址.md
[root@k8s-master ~]# cd dev-doc/
[root@k8s-master dev-doc]# gitbook build
info: 7 plugins are installed
info: 6 explicitly listed
info: loading plugin "highlight"... OK
info: loading plugin "search"... OK
info: loading plugin "lunr"... OK
info: loading plugin "sharing"... OK
info: loading plugin "fontsettings"... OK
info: loading plugin "theme-default"... OK
info: found 27 pages
info: found 14 asset files
info: >> generation finished with success in 1.8s !
编译完成后会生成一个_book的目录,里面就是编译好了的html文件;
[root@k8s-master dev-doc]# ll
total 16
drwxr-xr-x 2 root root 41 Jun 18 19:50 attachment
drwxr-xr-x 10 root root 239 Jun 18 20:22 _book
drwxr-xr-x 2 root root 38 Jun 18 19:50 components
drwxr-xr-x 2 root root 20 Jun 18 19:50 faq
drwxr-xr-x 2 root root 100 Jun 18 19:50 images
drwxr-xr-x 2 root root 101 Jun 18 19:50 introduction
drwxr-xr-x 3 root root 51 Jun 18 20:10 node_modules
-rw-r--r-- 1 root root 57 Jun 18 20:10 package.json
-rw-r--r-- 1 root root 721 Jun 18 20:10 package-lock.json
drwxr-xr-x 3 root root 222 Jun 18 19:50 project
-rw-r--r-- 1 root root 185 Jun 18 19:50 README.md
drwxr-xr-x 2 root root 302 Jun 18 19:50 scaffold
-rw-r--r-- 1 root root 2213 Jun 18 19:50 SUMMARY.md
[root@k8s-master dev-doc]# cd _book/introduction/
[root@k8s-master introduction]# ll
total 92
-rw-r--r-- 1 root root 19891 Jun 18 20:22 arch.html
-rw-r--r-- 1 root root 24235 Jun 18 20:22 framework.html
-rw-r--r-- 1 root root 20440 Jun 18 20:22 oauthflow.html
-rw-r--r-- 1 root root 69 Jun 18 20:22 简介.md
-rw-r--r-- 1 root root 22509 Jun 18 20:22 网站地址.html##可用对比第三步这里以及变成了html
[root@k8s-master introduction]# pwd
/root/dev-doc/_book/introduction
提示:这里拿安装好的nginx做个简单的示例,只需要把编译好的_book目录放到nginx的网站目录下就行;
[root@k8s-master ~]# cp -pr /root/dev-doc/_book /usr/share/nginx/html/_book
[root@k8s-master ~]# cd /etc/nginx/conf.d/
[root@k8s-master conf.d]# vim dev-doc.conf
server {
listen 80;
server_name www.my-dev-doc.com;
root /usr/share/nginx/html/_book;
index index.html index.htm;
}
[root@k8s-master conf.d]# nginx -t
nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful
[root@k8s-master conf.d]# nginx -s reload
去浏览器访问下ww.my-dev-doc.com看下效果;
发布完成;
以上就是通过手动发布的过程;
①结合jenkins发布的话,我们需要在jenkins的主机上安装npm以及gitbook,也就是手动发布里的第1,2步骤,这里我就省略了,大家可以参考手动发布里的步骤在jenkins主机安装;
②安装Publish Over SSH插件并配置,用于发布文件到远程主机;
在jenkins配置管理处(Manage Jenkins–>System Configuration–>Configure System)配置Publish over SSH(添加远程nginx主机)
提示:在高级里面要设置远程主机的密码,然后可以先点击Test Configuration测试连接;
Remote Directory:远程主机的发布目录,也就是你jenkins将编译好的包放到远程主机的哪个目录下(建议填写发布目录),我这里写的是nginx的网站根目录,一会儿我们要把编译好的_book文件放到这个目录下面;
这里我已经建过这个名称的项目了,所以他会提示已存在;
pipeline {
agent any
//全局变量
environment {
//gitee代码仓库地址;
Gitee_Registry_URL= 'https://gitee.com/xxxx.git'
}
parameters {
gitParameter branch: '', branchFilter: '.*', defaultValue: 'master', description: '选择拉取代码的分支', name: 'Branch', quickFilterEnabled: false, selectedValue: 'NONE', sortMode: 'NONE', tagFilter: '*', type: 'GitParameterDefinition'
}
stages {
stage('拉取代码') {
steps {
checkout([$class: 'GitSCM', branches: [[name: "${params.Branch}"]], extensions: [], userRemoteConfigs: [[credentialsId: 'pull-code_gitee_fandaoshuai', url: "${Gitee_Registry_URL}"]]])
}
}
stage('代码编译') {
steps {
sh """
cd $JENKINS_HOME/workspace/$JOB_NAME/
source /etc/profile
//这里我们进入jenkins当前项目工作空间下进行编译
gitbook build
"""
}
}
stage('部署') {
steps {
sshPublisher(publishers: [sshPublisherDesc(configName: 'web-nginx', transfers: [sshTransfer(cleanRemote: false, excludes: '', execCommand: '''source /etc/profile
nginx -s reload ''', execTimeout: 120000, flatten: false, makeEmptyDirs: false, noDefaultExcludes: false, patternSeparator: '[, ]+', remoteDirectory: '_book/', remoteDirectorySDF: false, removePrefix: '_book/', sourceFiles: '_book/**/*')], usePromotionTimestamp: false, useWorkspaceInPromotion: false, verbose: false)])
}
}
}
}
提示:"拉取代码" 和“部署”处的流水线语句大家可以在片段生成器里生成,然后粘贴到steps里就可以;
最后再给大家看下不用流水线的配置过程:
Send build artifacts over SSH这个模块参数不熟悉的话可参考:jenkins的Send build artifacts over SSh参数详解;
例如:以上就是今天要记录的内容,使用gitbook编译markdown文件为html并发布到nginx;