开源的在线接口文档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

1
2

# 3，配置数据库。

此程序使用MySQL或者sqlite作为存储库，两者任选其一即可。

MySQL：
CREATE DATABASE mindoc_db  DEFAULT CHARSET utf8mb4 COLLATE utf8mb4_general_ci;
sqlite

1
2
3

如果使用的是sqlite，可以直接在程序的conf/app.conf文件里进行配置，之后程序会自动创建。

db_adapter=sqlite3
db_database=mindoc_db

1
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}"        #数据库密码。

1
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

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

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

# 5，备份与迁移。

备份非常简单，只用对前边定义的数据库进行备份，然后将整个项目目录进行打包，如果需要迁移，直接按原有部署思路进行恢复即可。

# 6，版本升级。

因为这是个人开发者进行开发的产品，因此作者经常根据每个体验者给出的一些问题建议就进行更新了，因此版本更迭挺多，所以如何升级也是一个需要面对的问题。

1，下载新的安装包，传到服务器上，进行解压。 2，实际的更新操作。

比如我之前的文件是在doc目录下，现在更新解压出来是在mindoc目录下。

此时：
1，先删除mindoc目录下的upload目录，然后将doc目录下的upload目录cp -a 过来。
2，如果两个版本更新不大的话，那么可以直接用老的配置。进入到mindoc目录下的conf目录中，删除app.conf，将doc目录下对应的conf文件拷过来。

一般第二种操作只能在版本升级不大情况下用，如果内容更新大，要重新配置里边的内容。

1
2
3
4
5
6
7

3，安装。

cd mindoc && ./mindoc_linux_amd64 install

如果看到success则安装成功。

1
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    #插入代码块