开源的在线接口文档wiki工具Mindoc的介绍与使用原创
# 1,前言少叙。
突然感觉到渴,就一下子醒了,起来喝了口凉水,躺下后便再也没办法入眠,哎,那就不耗着啦,起来学会儿习呗。手机开开机,看了一眼时间,也才五点而已,此刻,一切都是静寂的,瞬间让自己仿佛有一点超然的感觉,于是,在这样的时刻里,我用着MinDoc,打算写写与它之间的故事。
我之所以在博客里边单独开出一个开源wiki的分类,是因为在市场上相关的,类似的实在太多太多,我个人也体验过不少,像什么confluence啦,showdoc啦,yapi啦(大家有没有什么特别好的工具推荐呢),但最终也都落脚到MinDoc来了,随着使用的越来越深入,一边使用一边又与开发的作者沟通一些功能的建议,就越发觉得这就是寻觅已久,最好用的个人知识管理工具的了。
注意,这里我说的是个人知识管理工具,比较偏私人一些,因为MinDoc的使用以及整体的项目风格,都与国内的两大知识平台有一些相近,这两个分别是看云与W3Cschool,我们也完全可以使用这些在线的工具进行个人文档的梳理与编写,只不过如果需求是在私人内部这一块儿,那么MinDoc就非常合适了。
忽然看到官网的介绍:
MinDoc 是一款针对IT团队开发的简单好用的文档管理系统。
MinDoc 的前身是 SmartWiki 文档系统。SmartWiki 是基于 PHP 框架 laravel 开发的一款文档管理系统。因 PHP 的部署对普通用户来说太复杂,所以改用 Golang 开发。可以方便用户部署和实用,同时增加Markdown和HTML两种编辑器。
开发缘起是公司IT部门需要一款简单实用的项目接口文档管理和分享的系统。其功能和界面源于 kancloud 。
可以用来储存日常接口文档,数据库字典,手册说明等文档。内置项目管理,用户管理,权限管理等功能,能够满足大部分中小团队的文档管理需求。
如果你的需求基本上也是这些,那么不妨试试这款工具。
# 2,官网等信息
1,官网 (opens new window) 2,项目地址 (opens new window) 3,下载地址 (opens new window) 4,官方文档地址 (opens new window) 5,在线演示地址 (opens new window)
# 3,部署安装
此开源工具的部署真的非常非常简单以及方便。注意,我这里仅仅分享在CentOs7上部署的经验。
MinDoc采用go语言开发,不过不用担心,作者上传的都是已经打包好了的安装包,我们只用下载之后解压,接着直接安装即可。
# 1,下载安装包。
首先通过上边的下载地址下载最新的包。
wget https://github.com/lifei6671/mindoc/releases/download/v0.13.2/mindoc_linux_amd64.zip
# 2,解压安装包。
然后上传到服务器上,解压配置。
mv mindoc_linux_amd64.zip /opt
unzip mindoc_linux_amd64.zip
2
# 3,配置数据库。
此程序使用MySQL或者sqlite作为存储库,两者任选其一即可。
MySQL:
CREATE DATABASE mindoc_db DEFAULT CHARSET utf8mb4 COLLATE utf8mb4_general_ci;
sqlite
2
3
如果使用的是sqlite,可以直接在程序的conf/app.conf文件里进行配置,之后程序会自动创建。
db_adapter=sqlite3
db_database=mindoc_db
2
# 4,修改主配置文件。
主配置文件就是刚说的conf/app.conf。
主要配置的就是与数据库的连接,以及其他一些关于上传下载或者邮件功能缓存功能等的配置。
数据库的配置如下:
####################MySQL 数据库配置###########################
#支持MySQL和sqlite3两种数据库,如果是sqlite3 则 db_database 标识数据库的物理目录
db_adapter="${MINDOC_DB_ADAPTER||mysql}" #数据库类型
db_host="${MINDOC_DB_HOST||127.0.0.1}" #此处默认即可。
db_port="${MINDOC_DB_PORT||3306}" #如果端口没有修改,也用默认的。
db_database="${MINDOC_DB_DATABASE||mindoc_db}" #填入前边创建的库名称。
db_username="${MINDOC_DB_USERNAME||root}" #数据库用户名。
db_password="${MINDOC_DB_PASSWORD||123456}" #数据库密码。
2
3
4
5
6
7
8
配置完成之后,需要初始化一下数据,如果缺少此步骤,则将会影响使用。
./mindoc_linux_amd64 install
稍等一分钟,看到success即表示成功。程序会自动初始化数据库,并创建一个超级管理员账号:admin 密码:123456
# 5,启动。
因为程序是一个前台程序,所以启动的时候放入后台。
nohup ./mindoc_linux_amd64 &
此时访问 http://localhost:8181 (opens new window) 就能访问 MinDoc 了。
或者使用systemd进行管理:
$ cat /usr/lib/systemd/system/mindoc.service
[Unit]
Description=Mindoc
After=network.target
[Service]
Type=simple
ExecStart=/home/min-wiki/mindoc_linux_amd64
Restart=on-failure
[Install]
WantedBy=multi-user.target
2
3
4
5
6
7
8
9
10
11
12
# 4,配置NGINX代理。
如果你还想配置一下域名方便使用,那么可以通过如下配置进行代理设置。
server {
listen 80;
#此处应该配置你的域名:
server_name doc.eryajf.net;
charset utf-8;
#此处配置你的访问日志,请手动创建该目录:
access_log /var/log/nginx/webhook.iminho.me/access.log;
location / {
try_files /_not_exists_ @backend;
}
# 这里为具体的服务代理配置
location @backend {
proxy_set_header X-Forwarded-For $remote_addr;
proxy_set_header Host $http_host;
proxy_set_header X-Forwarded-Proto $scheme;
#此处配置 MinDoc 程序的地址和端口号
proxy_pass http://127.0.0.1:8181;
}
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
# 5,备份与迁移。
备份非常简单,只用对前边定义的数据库进行备份,然后将整个项目目录进行打包,如果需要迁移,直接按原有部署思路进行恢复即可。
# 6,版本升级。
因为这是个人开发者进行开发的产品,因此作者经常根据每个体验者给出的一些问题建议就进行更新了,因此版本更迭挺多,所以如何升级也是一个需要面对的问题。
1,下载新的安装包,传到服务器上,进行解压。 2,实际的更新操作。
比如我之前的文件是在doc目录下,现在更新解压出来是在mindoc目录下。
此时:
1,先删除mindoc目录下的upload目录,然后将doc目录下的upload目录cp -a 过来。
2,如果两个版本更新不大的话,那么可以直接用老的配置。进入到mindoc目录下的conf目录中,删除app.conf,将doc目录下对应的conf文件拷过来。
一般第二种操作只能在版本升级不大情况下用,如果内容更新大,要重新配置里边的内容。
2
3
4
5
6
7
3,安装。
cd mindoc && ./mindoc_linux_amd64 install
如果看到success则安装成功。
2
3
4,启动。
nohup ./mindoc_linux_amd64 &
这个时候可以访问以下看看新功能是否出来了。
# 7,使用建议。
感觉上好像使用建议是不需要写的,毕竟每个人有每个人使用的方式,直接体验就行了,但是之所以想写一下,还是因为,个人的markdown编写习惯,就是在这款工具里边养成的,现在写文档的主力战场就转移到了个人的在线doc工具上来了,各种快捷键用的那叫一个嗨皮。
所以关于项目如何规划之类的,我就不多说了,这里只列一下个人编写的时候常用的一些快捷键吧。 当然这些快捷键大家也可以通过右上角的帮主页面看到。
Ctrl + 1~6 #插入标题1~6
Ctrl + A #全选
Ctrl + C #复制
Ctrl + V #粘贴
Ctrl + B #加粗
Ctrl + I #斜体
Ctrl + K #行内代码
Ctrl + Shift + C #插入代码块
2
3
4
5
6
7
8
基本上个人常用的就是这些,当然编写的时候还经常使用无序有序列表,以及插入图片表格等的操作,这些就不再说了。
最后,感谢作者的无私奉献与付出,让我们体验到这么好的开源工具!
另:本文教程处编写有参考原官方文档。
← 我对爱情的理解(其一) 有一种人→