1045 字
5 分钟
知识库私有化搭建-ShowDoc
showdoc 功能概览：
Docker安装
- 镜像选择：
star7th/showdoc
- 端口和文件映射配置如下：
- 日志配置:
启动镜像后，打开showdoc页面，选择完成语言后，会给一个默认用户名和密码，登录进去后记得修改哈！
登录后页面默认有如下内容：
我们会看到4个例子，选择 技术团队文档示例 可以查看 markdown语法和plantuml语法。
最新版本支持 - 项目列表卡片视图和列表视图切换了
![[Pasted image 20250423103006.png]]
文档写作
文档协作主要以 markdown 为主，也可以创建Excel表格，同时还支持plantuml，包括时序图、用例图、类图、组件图、状态图等等。
搭建好后，可以看到很多文档的例子，照着看一些就学会了，很简单的！
showDoc管理
团队管理
可以进行以团队为单位的管理，每个团队有不同的文档权限，互不干扰！同时一个用户也可以在某几个团队中任职，管理多个团队的文档数据。
项目管理
将文档以项目的形式进行管理，每个项目可以分配给不用的团队
后台管理
后台管理可以对 人员、项目、附件、站点进行管理和配置
文档生成
API 文档生成
- showdoc 官方提供了一种自动化生成接口和文档的方案。在代码里编写特定格式的程序注释，然后程序就可以通过读取这些注释来自动生成文档。由于这种方式不跟特定的语言耦合，因此它的使用范围相当广泛，可以支持
c++、java、php、node等等常见的主流语言。- 采用这种方式，尽管我们在第一次填写注释的时候可能会有些繁琐，但是它后期带来的可维护性是非常高的。代码变动后，不需要再额外登录 showdoc，直接在代码里修改注释即可。同时自动化的脚本也可以加入持续集成或者某些自动化工程里，让“写接口和文档”这件事如”单元测试”般纳入工程工作流里面。
以 windows 下的操作为例
windows无法直接运行sh脚本，需要额外下载软件。
- 下载
git for windows； - 下载showdoc官方脚本；
- 将
showdoc_api.sh放在项目目录下，编辑脚本中的api_key和api_token，如果自建服务，再编辑一下url地址； - 搞定上面3项后，然后直接双击运行，脚本会自动递归本目录和子目录的所有文本代码文件，生成的文档会放进 api_key 所指向的这个项目里。
==注意：代码注释要使用 showdoc 规范==
/** * showdoc * @catalog 测试文档/用户相关 * @title 用户登录 * @description 用户登录的接口 * @method get * @url https://www.showdoc.cc/home/user/login * @header token 可选 string 设备token * @param username 必选 string 用户名 * @param password 必选 string 密码 * @param name 可选 string 用户昵称 * @return {"error_code":0,"data":{"uid":"1","username":"12154545","name":"吴系挂","groupid":2,"reg_time":"1436864169","last_login_time":"0"}} * @return_param groupid int 用户组id * @return_param name string 用户昵称 * @remark 这里是备注信息 * @number 99 */数据字典生成
和生成API类似，需要先下载指定脚本文件，之后修改配置信息，最后执行脚本命令！
链接分享
可以将单篇文章或者笔记以链接的形式分享给客户，非常方便：
自动更新
![[Pasted image 20250423100037.png]]
问题汇总
在 威联通 下部署可能访问会出现如下 权限 的错误：
NOTICE: PHP message: PHP Warning: PHP Request Startup: Failed to open stream: Permission denied in Unknown on line 0 ERROR: Unable to open primary script: /app/index.php (Permission denied)此时，需要将映射的文件夹权限付给下面的全部子文件夹，具体操作如下：
-
在映射的文件夹上面，单机右键，选择
属性选项：
-
在弹出的对话框中，勾选
将文件权限应用至所有文件：
知识库私有化搭建-ShowDoc
https://blog.qnloft.com/archives/foVGNCzP