PostIn是一款国产开源免费的接口管理工具，包含项目管理、接口调试、接口文档设计、接口数据MOCK等模块，支持常见的HTTP协议、websocket协议等，支持免登陆本地接口调试，本文将介绍如何快速安装配置及入门使用教程。
1、安装
私有部署版本支持多种操作系统，包括 Linux、Docker、Windows及macOS，方便团队根据自身环境灵活选择下载、安装方式。
1.1 Linux 安装
- 下载，Linux 安装包下载地址：PostIn下载，点击Linux下载，下载安装包如tiklab-postin-x.x.x.rpm。
- 安装，将安装包上传到服务器，使用 rpm 命令安装，默认安装目录在/opt下。
rpm -ivh --nodeps tiklab-postin-x.x.x-1.x86_64.rpm
- 启动，进入安装目录/opt/postin-ee/bin目录下，执行sh startup.sh即可启动成功。
sh startup.sh
1.2 Docker 安装
- 下载，Docker安装包下载地址：PostIn下载，下载Docker安装包。下载完成后，得到 tiklab-postin-x.x.x.tar.gz 的文件。
- 安装，在执行以下命令加载镜像。
docker load -i tiklab-postin-x.x.x.tar.gz
- 启动，执行以下镜像启动即可。
docker run -itd -p 9300:9300 tiklab-postin-x.x.x
1.3 Windows 安装
➢ 服务器安装
- 下载，Windows安装包下载地址：PostIn下载，下载Windows安装包。下载完成后，获取名为 tiklab-postin-.x.x.x.exe 的可执行文件。
- 安装，双击运行可执行文件，选择安装位置并点击安装。
- 启动，点击桌面快捷方式启动 PostIn 服务。
➢ 桌面端安装
- 下载，Postin桌面端支持Window。安装包下载地址：PostIn桌面版下载，下载Windows桌面端，下载安装包如 tiklab-postin-client-x.x.x.exe 。
- 安装，双击运行可执行文件，选择安装位置并点击 安装。
- 启动，安装完成后，点击桌面快捷方式启动 PostIn 。
1.4 macOS 安装
➢ 服务器安装
- 下载，Mac安装包下载地址：PostIn下载，下载Mac安装包，下载完成后，获取名为 tiklab-postin-.x.x.x.dmg 的可执行文件。
- 安装，双击打开 .dmg 文件，将 Postin 拖入 应用程序 文件夹。
- 启动，点击 应用程序 文件夹中的 PostIn 快捷方式启动服务。
➢ 桌面端安装
- 下载，Postin桌面端支持Mac，Mac安装包下载地址：PostIn桌面版下载，下载Mac桌面端，下载安装包名称如tiklab-postin-client-x.x.x.dmg 。
- 安装，双击打开 .dmg 文件，将 PostIn 拖入 应用程序 文件夹。
- 启动，点击 应用程序 文件夹中的 PostIn 快捷方式启动桌面端。
2、登录
启动后，默认可以通过 http://ip:9300 访问，默认用户名/密码为admin/123456。
默认支持通过账号密码登录，满足基础登录需求。若需要使用企业微信、钉钉或 LDAP 等高级登录方式，可参阅TesHubo文档获取相关配置说明。
3、配置
允许自定义端口、数据存放目录、数据库连接、数据库备份策略和统一登录设置，以满足特定个性化需求。配置文件yaml文件默认位置：
| 系统 | 默认位置 |
| Windows | 默认在安装目录 --> conf目录下application.yaml文件 |
| Mac | 默认在app下的Contents --> conf 目录下application.yaml文件 |
| Linux | 默认在/opt/postin-ee/conf 目录下application.yaml文件 |
| Docker | 默认在镜像文件内/usr/local/postin-ee/conf 目录下application.yaml文件 |
3.1 自定义端口
允许用户自定义应用的启动端口，以便在特定网络环境下避免端口冲突或满足其他配置需求。
| 属性 | 说明 |
| serer.port | 系统启动的端口号（可更改）。 |
3.2 自定义数据库
支持自定义数据库连接方式，用户可以选择使用内嵌数据库或指定外部数据库地址。根据需求配置数据库连接。
| 属性 | 说明 |
| postgresql.embbed.enable | 是否使用内嵌数据库，true:使用 false:不使用。如果配置为false，需要把该文件中jdbc下的数据库连接信息更改为自己的数据库地址，用户名以及密码。 |
| postgresql.database | 是否使用内嵌数据库默认连接的数据库，默认为tiklab_postin如果更改次默认值需要把jdbc下的数据库连接信息更改为新的数据地址。 |
| postgresql.db.port | 使用内嵌数据库的启动端口，默认为9301，如果更改需要同时把jdbc.url中的数据库连接地址端口更改。 |
| postgresql.db.username | 使用内嵌数据库的用户名，默认为postgres，如果更改需要同时把jdbc.username中的数据库连接地址用户名更改。 |
| postgresql.db.password | 使用内嵌数据库的密码，默认为darth2020，如果更改需要同时把jdbc.password中的数据库连接地址密码更改。 |
| postgresql.db.address | 使用内嵌数据库的数据库文件保存位置，默认为${DATA_HOME}/postgresql，即默认的应用数据目录下的postgresql目录。注：如果更改该目录，该路径目录必须为空目录，否则会导致数据库无法启动。 |
| jdbc.url | 默认是：jdbc:postgresql://localhost:9301/tiklab_postin?stringtype=unspecified 其中 9301 为端口号，postin_db为数据库名字，这两个可更改。 但是端口号必须与postgresql.db.port 保持一致。 数据库名字必须与postgresql.database 保持一致。 |
| jdbc.username | 数据库登录名，必须与postgresql.db.username一致。 |
| jdbc.password | 数据库登录密码，必须与postgresql.db.password一致。 |
3.3 自定义数据目录
支持用户自定义数据存放目录的位置，帮助用户根据需要选择存储路径。
| 属性 | 说明 |
| DATA_HOME | 数据文件存放地址。 |
4、快速入门
PostIn安装结束后，登录系统进入PostIn首页。首页显示常用项目和PostIn接口各状态统计。
4.1 创建空间
PostIn安装结束并登录后，需要创建空间来对接口分项目进行管理，空间是 Postin 中最高级别的项目管理单元，用于帮助团队高效地组织和管理 API 资源。它作为一个独立的容器，可以容纳项目的所有 API 接口、文档、测试等资源。
- 创建空间
点击空间→添加空间，可添加公共或者私密的空间，其中公共空间所有用户可浏览，私密空间仅选择的用户可浏览。
| 属性 | 是否必填 | 描述 |
| 空间名称 | 必填 | 为项目设置一个简洁明了的名称，便于识别和管理。 |
| 可见范围 | 必填 | 设定空间的可见性，如“私密”或“公共”，以控制项目的访问权限，选择“私密”可限制特定成员进入空间。
|
| 成员选取 | 选填 | 可见范围选择“私密”才展示成员选取选择框，从系统用户中添空间成员，并为成员分配适当的角色和权限，确保协作效率。 |
| 描述 | 选填 | 提供简短的描述，说明空间的目标或关键内容，帮助团队成员快速了解空间。 |
空间创建完成之后，在空间页面“所有空间”，或者“我创建的”找到创建的空间。点击空间名称，进入空间详情。
- 添加成员
空间创建成功之后，根据空间的属性（可见范围）对访问项目的成员进行管理。在空间页面找到空间，点击“成员”，对访问空间的成员进行管理。
想要添加空间成员，需要添加系统用户，依次点击系统设置->用户与权限->用户，在用户页面对系统用户进行管理。
点击“添加用户”，添加系统用户。可以对账号进行编辑、修改密码、重置密码、删除等操作。
系统用户添加完成之后，可以对空间成员进行添加，在空间详情→设置→空间，进入空间成员编辑页面。
如果用户在创建空间未选成员，那么空间默认有创建人和admin两个成员。点击添加用户，添加的成员列表从系统用户列表获取。点击添加用户，勾选添加用户，点击确定即可成功添加空间成员。
添加空间成员后，可以对成员分配权限、修改角色，点击项目详情→设置→权限，可浏览到内置角色。
| 内置角色 | 属性 |
| 项目超级管理员 | 权限最大，不可指定普通成员，成员有且只有admin。 |
| 项目管理员 | 项目管理员，可对项目基本信息进行编辑，可添加多名成员。 |
| 项目普通角色 | 普通项目成员，权限最低，可添加多名成员。 |
在空间详情→设置→成员，点击“角色修改”，对成员角色进行修改。成员角色可多选。
4.2 接口调试
Postin 提供快速便捷的接口调试功能，与接口管理中的接口区别在于需要手动输入参数，用于临时测试不需要管理的接口。支持 HTTP 和 WebSocket 协议，帮助开发者验证 API 接口的功能和行为，确保接口按预期工作。
HTTP和WebSocket协议在接口调试页面区别。
| 协议 | 区别 |
| HTTP |
|
| WebSocket |
|
- 调试操作
➢ 输入请求地址
在地址栏中输入需要测试的接口地址，包括主机和路径等信息。这是发送测试请求的第一步，确定要测试的接口地址。
➢ 输入请求参数
在相应的输入框或表单中输入需要传递给接口的请求参数。这些参数可以包括查询参数、请求体参数、请求头等，根据接口的需求进行输入。
➢ 发送测试
点击界面上的发送按钮，将测试请求发送给目标接口。系统将会使用输入的请求地址和参数发送请求，并等待接收到服务器的响应。
➢ 查看测试结果
在接收到服务器的响应后，系统会将响应结果显示在界面上，包括响应状态码、响应体内容等信息。用户可以在界面上直接查看测试结果，以便进行验证和调试。
接口调试支持设置前置脚本、后置脚本、断言。
- 调试历史
接口每一次调试都会记录在左侧接口调试历史列表，点击调试历史列表，右侧显示调试时设置的参数。
4.3 接口管理
空间、成员创建成功之后，进入空间详情，在空间详情对接口进行管理、统计。
- 添加接口
在接口页面，点击列表右上角的“+”，添加接口目录，或者通过Postman/OpenAPI V3/Swagger V2的json格式导入。
在目录右侧点击“+”添加接口，包含添加HTTP或者WebSocket协议接口，选择添加HTTP协议接口，输入接口的基本信息接口名称、请求类型、接口路径。
接口添加完成之后，点击接口右侧“…”，对接口进行编辑、删除。
- 设计接口
接口设计通过设置基础信息、请求和输出结果的参数，来构造当前接口的具体使用方式。支持多种协议，包括 HTTP 和 WebSocket，灵活适应不同应用需求。
- 设置环境
Postin 测试调试接口支持管理多个环境配置（如开发、测试、生产），便于在不同环境中测试和验证 API。
在测试API接口之前，点击空间详情→设置→环境，进入环境配置。
点击添加环境，需要输入环境名称、环境地址。注意：环境地址尾部不需要带“/”
环境配置结束后，还可以对环境进行编辑、删除。
环境配置结束后，在接口测试页面，点击右上角环境下拉框，选择测试接口所用的环境。
- 测试接口
Postin 测试调试接口，提供环境选择，一键切换测试、预发布、生产等环境，快速验证接口。
在测试页面，点击环境下拉框，弹出环境选择，点击需要测试的环境，点击发送，进行接口测试。
- 查看接口文档
接口文档基于接口设计自动生成，确保接口信息实时更新，便于团队随时查阅和对接，支持 HTTP 和 WebSocket 协议，方便共享给其他开发者或团队成员。
- 分享接口
在接口页面选择需要分享的接口，点击右上角分享按钮。
接口分享支持公开分享和密码分享两种方式。
在分享弹窗选择公开，在浏览器中打开分享界面的链接，直接可以打开分享的接口。
- 分享管理
点击左侧“分享”按钮，在分享页面显示分享过的接口列表。在分享页面，可以查看接口分享的链接、修改分享密码、取消分享
4.4 MOCK数据
Postin 提供内置的 HTTP 协议 MOCK 数据生成功能，支持前端在后端未完成时进行独立开发和测试，减少依赖，提升开发效率。
- 添加MOCK
在接口点击Mock，进入Mock页面，显示内置Mock环境地址。
添加MOCK字段属性说明：
| 属性 | 是否必填 | 描述 |
| MOCK名称 | 必填 | 为MOCK设置一个简洁明了的名称，便于识别和管理。 |
| 描述 | 选填 | 提供MOCK简短的描述，说明MOCK的目标或关键内容,帮助团队成员快速了解MOCK的作用。 |
- 编辑MOCK
点击添加MOCK，输入MOCK的名称后，点击提交，添加一条MOCK虚拟响应。
点击MOCK名称，进入详细MOCK虚拟请求、响应配置。
- 使用MOCK环境
配置MOCK虚拟请求后，使用MOCK环境，点击测试，如果请求和MOCK一致，则接口响应也会和MOCK设置的一致。
例如配置如下MOCK：
| MOCK名称 | 请求 | 响应 |
| 查询成功 | {"startTime":"2025-03-08","endTime":"2025-03-15"} | 响应code:200 响应体：{"msg": "查询成功"} |
| 查询失败 | {"startTime":"","endTime":""} | 响应code:201 响应体：{"msg": "请输入日期进行查询"} |
配置结束后，在接口→测试页面，选择MOCK环境，当请求参数符合MOCK“查询成功”的请求参数，则显示响应code:200，响应体：{"msg": "查询成功"}
同理，当请求参数符合MOCK“查询失败”的请求参数，则显示响应code:201，响应体：{"msg": "请输入日期进行查询"}
