做联调接口最怕什么无非是文档过期、字段对不上、Mock 数据没人维护。我们把接口管理迁到一个可视化接口管理平台上之后后端写清楚接口前端随时看更新测试人员直接在平台里跑用例整体协作效率好了非常多。这个平台就是 YApi。它是一个基于 Node.js 和 MongoDB 的开源接口管理工具部署在 Linux 服务器上后可以集中管理项目接口、自动生成 Mock、支持 Swagger 导入还能做简单的权限分配。本篇文章按我实际部署 Linux 服务器的流程来写目标很明确在一台干净的 CentOS 或 Ubuntu 机器上把 YApi 可视化接口管理平台完整部署起来并且配置后台自动运行保证服务器重启之后服务能自己恢复。内容既包含环境准备、编译安装也包含 pm2 和 systemd 两种守护方式还有部署过程中常见的坑和解决方案。不管是刚接手 Linux 服务器的初级工程师还是想快速搭建内部研发平台的全栈开发者这份过程应该都能直接参考。1. 部署前先想清楚YApi 能解决什么问题部署又需要哪些组件1.1 接口文档为什么需要集中管理很多小团队最初用在线文档或者本地 Markdown 维护接口。接口少的时候还行接口数量一多问题立刻暴露字段改了一处文档没同步后端调试用的接口地址和处理逻辑脱节前端拿到的 Mock 数据跟真实响应格式不一致。这些问题表面上是“文档问题”本质上是缺少一个能承载接口生命周期的管理工具。YApi 这类可视化接口管理平台相当于给接口做了统一的“台账”。项目、分组、接口、状态、权限都放在同一个后台里后端写完接口定义前端和测试直接在同一个地址查看。接口变动有迹可循Mock 数据可以根据接口定义自动生成甚至能配合自动化测试做回归检查。部署它的核心价值不在于“有一个好看的网页”而是让接口信息从个人手里沉淀为团队资产。1.2 YApi 在同类工具里的定位和优势同类型工具有不少比如国产的 Apifox、RAP2、ShowDoc商业的 SwaggerHub 等。YApi 的优势主要在于三点一是开源可私有化部署接口数据完全在自己服务器上不需要上传第三方平台这对很多重视数据合规的团队是刚需二是插件机制和扩展脚本做得好除了基础接口管理还可以自定义 mock 规则甚至利用开放接口把 YApi 接入到内部的 CI/CD 流程里三是操作界面更贴近国内开发者的使用习惯创建项目、导入 Swagger、维护枚举字段的流程都很直接。选型时也要注意它的短板YApi 的自动化测试能力没有商业工具那么完善权限控制比较基础多人同时编辑时偶尔会有冲突。如果你的团队主要需求是“接口文档 Mock 简单的流程测试”YApi 完全够用如果还需要复杂的压测、P2P Mock 环境编排可能要考虑其他工具。没有万能工具关键是先明确自己的场景。1.3 架构组成与环境需求YApi 本身是一个典型的 Node.js Web 应用数据持久化依赖 MongoDB所以部署环境最少需要两个核心组件Node.js 运行时提供 Web 服务负责接口管理后台、Mock 服务、Swagger 导入解析。MongoDB 数据库保存项目、分组、接口、用户、日志等所有结构化数据。对于 Linux 服务器还需要考虑 Node.js 版本兼容性、MongoDB 版本稳定性、系统用户权限、防火墙安全策略。我的建议是尽量用系统包管理去安装依赖避免源码编译过程中出现网络或依赖问题。如果你只是在内网环境做快速验证甚至可以把 MongoDB 和 YApi 部署在同一台 4C8G 的机器上生产环境建议拆分MongoDB 单独一台YApi 应用一台前面再加一层 Nginx 做 HTTPS 和反向代理。下面先从单机部署开始这种方式最容易排查问题。2. 准备 Linux 环境Node.js 与 MongoDB 的版本选择和安装2.1 版本选择Node.js 16 与 MongoDB 4.4YApi 对 Node.js 的最低要求是 7.6但现代系统中不要选择过老的版本。我实际用的是 Node.js 16 LTS这个版本对 npm 生态兼容性较好也没有暴露过跟 YApi 相关的运行时问题。不建议直接上 Node.js 20 或更新的版本部分依赖编译时可能出现兼容性报错。MongoDB 我选择 4.4 系列这是经过较多生产环境验证的版本稳定性和内存占用都相对可控。MongoDB 5.x 和 6.x 也不是不能用但 YApi 本身的数据库操作很简单没必要追新版本给自己增加排错成本。安装前要确认服务器时间同步否则后面 MongoDB 和 YApi 的日志时间会乱排查问题比较痛苦。建议执行sudo apt install ntpdate或sudo yum install ntpdate再ntpdate ntp.aliyun.com同步一次时间。2.2 安装 Node.js 的两种方式CentOS 和 Ubuntu 的包管理器仓库里 Node.js 版本通常偏老所以更推荐用 NodeSource 源或者 nvm 安装。nvm 的好处是可以用普通用户安装不需要动系统全局环境坏处是每次开新终端要执行source ~/.bashrc加载环境变量对新手不太友好。我一般选择 NodeSource 源的方式例如在 CentOS 上执行curl -fsSL https://rpm.nodesource.com/setup_16.x | sudo bash - sudo yum install -y nodejsUbuntu 上则是curl -fsSL https://deb.nodesource.com/setup_16.x | sudo bash - sudo apt install -y nodejs安装完成后执行node -v和npm -v确认版本。如果服务器无法访问外网就需要先把 Node.js 的二进制包下载后上传到内网解压再把/usr/local/node/bin加到 PATH 里。npm 也建议配置国内镜像部署 YApi 时安装依赖会快很多npm config set registry https://registry.npmmirror.com2.3 安装 MongoDB 并完成基本安全配置CentOS 7 上安装 MongoDB 4.4 的过程比较直观先添加官方 repo 文件。不过官方 repo 地址拉取可能不稳定实际工作中如果下载失败我会直接把 mongodb-org-4.4 的 rpm 包下载好传到服务器进行本地安装避免长时间卡在源上。这里以正常添加官方源为例cat /etc/yum.repos.d/mongodb-org-4.4.repo EOF [mongodb-org-4.4] nameMongoDB Repository baseurlhttps://repo.mongodb.org/yum/redhat/\$releasever/mongodb-org/4.4/x86_64/ gpgcheck1 enabled1 gpgkeyhttps://www.mongodb.org/static/pgp/server-4.4.asc EOF sudo yum install -y mongodb-org启动并设置开机自启sudo systemctl start mongod sudo systemctl enable mongod检查是否正常sudo systemctl status mongod如果是在 Ubuntu 上用apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 --recv 9DA31620334BD75D9AEA95FB93BCB4D42添加密钥的方式也可以这里不再展开。MongoDB 安装完成后默认只监听本机 127.0.0.1这对单机部署反而是安全的不需要额外开启公网访问。如果 MongoDB 和 YApi 分开部署才需要修改 bindIp 和防火墙规则。考虑到 YApi 的数据值得保护我会再开启 MongoDB 的鉴权。开启鉴权前先连上去创建管理员mongo use admin db.createUser({user: yapiAdmin, pwd: YourStrongPassword, roles: [{role: root, db: admin}]}) exit然后修改/etc/mongod.conf把security.authorization设为enabled重启 MongoDB。这一步不是必须的但如果服务器有公网访问强烈建议开启否则 MongoDB 一旦暴露数据就是裸奔状态。3. 部署 YApi源码下载、依赖安装与初始化管理员3.1 获取 YApi 源码YApi 的源码是公开的部署时我建议拉取正式 release 版本而不是直接拉默认分支默认分支可能是开发中的代码稳定性不好保障。在/opt目录下操作cd /opt git clone https://github.com/YMFE/yapi.git yapi cd yapi git checkout tag版本号如果你访问国际网络不稳定可以考虑把源码包下载好再传到服务器上解压或者使用国内的一些代码托管镜像。这里不展开具体镜像实际就是让源码能完整落地、git status正常即可。下载源码后还要确认目录权限YApi 启动时会写日志和缓存如果使用yapi用户运行要给所属用户读写权限。如果只是测试环境直接修改目录 owner 为当前用户也行但生产环境建议单独建一个系统用户来跑服务sudo useradd -M -s /usr/sbin/nologin yapi sudo chown -R yapi:yapi /opt/yapi3.2 安装依赖和配置 config.json进入项目目录执行cd /opt/yapi npm install --production --registry https://registry.npmmirror.com这里有个常见问题node-sass和phantomjs等二进制依赖包安装时经常失败。如果国内镜像下还是失败可以设置sass_binary_site环境变量export SASS_BINARY_SITEhttps://npmmirror.com/mirrors/node-sass/ export PHANTOMJS_CDNURLhttps://npmmirror.com/mirrors/phantomjs/ npm install --production安装完成后修改 YApi 的配置文件。不同版本的路径略有不同但一般都在项目根目录的config.json里。核心配置项如下{ port: 3000, mongo: { host: 127.0.0.1, port: 27017, db: yapi, user: yapiAdmin, pass: YourStrongPassword, authSource: admin }, mail: { enable: false } }portYApi 服务监听端口默认 3000。如果服务器上已经有其他应用占用可以改 8001 或 8080。mongo数据库连接配置。开启鉴权后user和pass要填刚才创建的账号密码特别要注意authSource必须指定为admin否则 MongoClient 默认会去yapi库里找用户导致认证失败。mail如果不需要邮件通知保持enable: false即可这能省掉很多 SMTP 配置的麻烦。3.3 首次启动与初始化管理员账号配置写好之后不要直接上 pm2先在前台启动一次方便看启动日志cd /opt/yapi node server/app.js看到类似log: 服务已启动的输出后打开浏览器访问http://服务器IP:3000。首次访问会进入安装引导页面要求初始化管理员账号。填写一个真实可用的邮箱地址作为管理员登录名设置密码并创建这一步完成后 YApi 会自动在 MongoDB 中创建集合并写入初始数据。初始化完成后使用管理员账号登录就可以创建项目、导入接口、配置成员权限了。这里要提醒一点安装引导页只有在数据库为空时会出现如果你清空过yapi库或改错了库名重新打开可能需要先删除数据库再重新启动服务所以数据库名和连接串尽量一次写对。3.4 验证核心功能是否正常工作登录后建议先做两个功能验证。第一新建一个测试项目手动创建一个 GET 接口和一个 POST 接口确认保存后接口列表能正常展示字段可编辑。第二打开文档详情页确认 Mock 地址能生成响应数据。打开接口详情中的“ Mock ”地址返回的内容应该和接口定义中的返回字段保持一致。如果这两个功能正常说明环境基本可用再继续做后台守护。4. 配置后台自动运行pm2 和 systemd 两种方案4.1 为什么推荐 pm2 而不是 nohup把 YApi 进程挂到后台很多人第一反应是nohup node server/app.js 。这种方式虽然能让进程在终端关闭后继续跑但节点一旦崩溃服务就没人拉起服务器重启也不会自动恢复。真实生产环境根本不敢用这种方式托底。我更推荐用 pm2 进程守护工具它可以监听进程状态崩溃后自动重启还能设置开机自启日志统一管理资源占用情况一目了然。pm2 的另一个优势是可以通过pm2 start server/app.js -i max开启 Cluster 模式利用多核 CPU 提高并发处理能力。YApi 在单机场景下占用资源不高但如果你团队内部访问人数较多Cluster 模式能明显提升响应稳定性。4.2 安装 pm2 并托管 YApi全局安装 pm2npm install -g pm2 --registryhttps://registry.npmmirror.com在 YApi 项目目录启动cd /opt/yapi pm2 start server/app.js --name yapi执行pm2 status应该能看到 yapi 处于 online 状态。接着保存当前进程列表并生成开机自启脚本pm2 save pm2 startup systemd -u yapi --hp /opt/yapi执行最后一条命令时pm2 会输出一段完整的命令让你用管理权限执行一次比如sudo env PATH$PATH:/usr/local/bin pm2 startup systemd -u yapi --hp /opt/yapi这个步骤不能跳过否则“开机自启”不会真正生效。执行完成后再执行一次pm2 save确保已保存当前状态。为了验证开机自启是否生效可以执行pm2 restart yapi后重启服务器等系统起来再登录服务器执行pm2 status如果 yapi 还是 online说明配置成功。我建议在新服务器上做一次这样的“破坏性测试”否则一旦你换了运行用户很容易出现开机后 pm2 存在但进程没有接管的情况。4.3 使用 systemd 创建 YApi 服务如果不想依赖 pm2也可以直接用 systemd 守护 YApi。创建一个服务文件sudo vi /etc/systemd/system/yapi.service内容如下[Unit] DescriptionYApi Service Afternetwork.target mongod.service [Service] Useryapi Groupyapi WorkingDirectory/opt/yapi EnvironmentPORT3000 ExecStart/usr/local/bin/node /opt/yapi/server/app.js Restartalways RestartSec5 [Install] WantedBymulti-user.target然后执行sudo systemctl daemon-reload sudo systemctl enable yapi.service sudo systemctl start yapi.service这里有一个容易忽略的细节ExecStart里的 Node.js 路径必须写绝对路径不能用node。用which node查看真实路径否则启动服务时 systemd 找不到命令。Aftermongod.service表示等 MongoDB 启动完成后再启动 YApi避免数据库还没起来导致连接重试的噪音。两种方案选哪个我的习惯是如果服务器上已经有 pm2 在管理其他 Node 服务就统一用 pm2如果这是一个独立服务、希望尽量少装东西用 systemd 更轻量。两者都能实现开机自动运行效果没有本质差别。4.4 日志处理与进程监控后台运行之后日志管理必须跟上。pm2 可以查看实时日志pm2 logs yapi --lines 100 --format如果日志文件越来越大可以用 pm2 自带日志回滚pm2 install pm2-logrotate pm2 set pm2-logrotate:max_size 10M pm2 set pm2-logrotate:retain 7systemd 方案则通过journalctl -u yapi -f查看日志系统默认按大小滚动基本不用额外配置。监控方面建议接入一个简单的进程告警用 crontab 每分钟检查一次端口状态如果不通就执行 systemctl restart或者用 nginx 的健康检查配合邮件告警。这些属于运维基建这里不展开但先做到“进程能自启”只是底线。5. 部署过程中最常见的问题与排错实录5.1 高频问题对照表下表是我在多个环境中部署 YApi 时遇到的问题以及对应处理方式按出现概率排列问题现象根本原因解决办法首次打开页面白屏或后端一直转圈MongoDB 没有启动或连接串认证失败检查systemctl status mongod确认 config.json 的用户、密码、authSourcenpm install卡在 node-sass / phantomjs源码安装依赖时二进制包下载失败配置SASS_BINARY_SITE和PHANTOMJS_CDNURL环境变量后重试服务启动后马上退出无错误日志端口被占用执行lsof -i:3000找到占用进程杀掉或修改 YApi 端口pm2 开机自启后进程不在没有执行pm2 startup输出的命令或运行用户不对按提示完整执行 sudo 命令确认启动用户和 project 路径MongoDB 开启鉴权后启动失败配置安全认证后未设置授权模型或密码字符有问题清空密码中的特殊字符重启 mongod 后使用db.auth验证接口 Mock 返回 504 或超时内存不足或 Node 进程并发设置过高检查 free -m添加 swap调低 pm2 实例数上传 Swagger 时解析失败JSON 结构不规范或字段类型缺失先用 Swagger 官方校验工具校验原文件再重新导入提示排查问题时不要只看 YApi 的日志MongoDB 的日志也要看。很多时候表面是接口写不进去真实原因却是 MySQL 连接过期的同款问题长连接时间过长被 MongoDB 断开了。5.2 数据库备份、恢复与版本升级YApi 里所有接口信息都在 MongoDB 中所以数据备份等价于备份 MongoDB。最省心的方式是定时执行mongodumpmongodump --host 127.0.0.1 --port 27017 -d yapi -o /data/backup/yapi_$(date %Y%m%d)恢复时使用mongorestoremongorestore --host 127.0.0.1 --port 27017 -d yapi /data/backup/yapi_20240101/yapi最好写一个脚本挂到 crontab 里每天凌晨备份一次并保留最近一段时间。数据库不要直接复制数据目录文件除非数据库完全停掉否则容易造成数据不一致。升级 YApi 时不要直接删除项目目录更不要动 MongoDB。我的步骤是先备份数据库然后pm2 stop yapi把新版本的源码包解压到新目录安装依赖修改 config.json用同一数据库启动服务。如果版本跨度不大界面数据基本能自动兼容如果出现了数据字段迁移失败就用最新版本官方文档检查是否有额外迁移脚本。切忌在旧版本上暴力覆盖文件否则配置和源码混在一起出问题很难定位。5.3 资源规划与安全加固心得单机部署 YApi 时内存是最容易忽略的资源。Node.js 默认小内存机器上容易进程退出MongoDB 也很吃内存。如果服务器只有 2G 内存建议先加 swapsudo dd if/dev/zero of/swapfile bs1G count2 sudo chmod 600 /swapfile sudo mkswap /swapfile sudo swapon /swapfile往/etc/fstab里加一行/swapfile swap swap defaults 0 0保证重启后交换分区还在。设置完可以观察pm2 status里 yapi 的内存占用通常稳定在 300MB 以下配合 1G swap 基本不会出现 OOM。安全方面除了 MongoDB 要开启鉴权建议通过 Nginx 为 YApi 启用 HTTPS并在防火墙规则里只放行 80/443 和远程管理端口完全不放行 MongoDB 的 27017 端口。这样即使后面出现代码漏洞被攻击的暴露面也会小很多。5.4 我的一些实操习惯最后分享几个我在日常维护中养成的习惯。每次修改 config.json 前先复制一份原文件做好记录用 pm2 跑服务时把项目的环境变量尽量集中放在ecosystem.config.js这样团队成员接手时能快速了解配置定期清理 MongoDB 中日志集合的数据防止日志导致的库体积膨胀升级前先查看官方版本的更新说明看看有没有涉及数据结构变更。这些习惯不复杂但能省掉不少半夜被叫起来排查问题的时间。无论你是第一次在 Linux 上部署 YApi还是之前用过其他接口管理工具想替换过来按上面这套流程走完系统基本可以稳定运行。部署过程中最花时间的往往不是命令本身而是环境差异造成的依赖问题。遇到困难时多看看日志少凭空猜测问题基本都能定位。