★ FEATURED ARTICLE 前阵子帮 A同学他们的团队部署 YApi那个场景我太熟悉了接口文档散落在共享文档、聊天记录和个人笔记里后端改个字段前端全靠猜联调效率低得让人想摔键盘。我在 Linux 服务器上把 YApi 可视化接口管理平台部署起来顺手配置了后台自动运行接口这件事才算理顺。这篇文章就把我在 Linux 上部署 YApi、并让它稳定在后台运行的完整过程写下来包括环境版本选择、部署步骤、三种进程守护方案以及几个非常有代表性的坑。如果你所在团队同样面临接口文档管理混乱、Mock 数据靠手写、接口变更通知全靠吼的问题这篇文章可以直接照抄。1. 部署前先搞清楚YApi 到底解决什么问题1.1 接口协作的痛点从哪来很多小团队最初用 Postman 管理接口但 Postman 更适合个人调试团队协作要么买付费版要么导出一份 JSON 扔到群里没过几天就分不清哪个是最新版。后来有人用在线文档维护接口写着写着又发现文档更新不及时、路径写错、参数漏标前端照着文档调接口十个里有三个对不上。YApi 这类可视化接口管理平台解决的正是这个接口全生命周期管理问题。它把接口的创建、编辑、文档展示、Mock 数据生成、接口测试全部集中到一个 Web 平台上。后端把接口定义录入平台前端直接从这里看文档、拿 Mock 数据联调测试也可以直接在平台里跑接口断言。1.2 YApi 的核心能力拆解很多人以为 YApi 只是个在线文档工具其实它做了四件事接口文档管理按分组和项目组织接口每个接口可以维护请求方法、路径、请求参数、返回示例、状态码说明支持 Markdown 格式备注。可视化 Mock后端还没实现接口时前端就能基于接口定义拿到模拟数据。YApi 会根据参数定义自动生成随机 Mock 数据也支持自定义 Mock 脚本。接口测试平台内置了接口测试工具可以配置测试环境地址批量执行接口并校验返回结果做基本回归测试很方便。权限与协作支持创建团队、项目成员权限管理、接口变更记录团队多人协作时能看清楚谁改了什么。它的架构也简单就两个核心组件一个是 MongoDB 负责存储项目、接口、用户等所有数据另一个是 Node.js 编写的 Web 服务负责提供管理界面和 API。没有额外的消息队列、Redis 之类的依赖部署负担比较轻。1.3 选型前先泼点冷水YApi 不是万能的。如果你的团队需要严格的接口变更审批流程、接口文档与代码仓库强绑定、自动化测试深度接入 CI/CDYApi 就不够用了这种情况更该考虑商业 API 管理平台或者自研系统。另外 YApi 默认不具备复杂的企业级权限体系公网部署一定要谨慎别把管理端口裸奔到公网上。但如果你只是想要一个靠谱的内部接口管理工具让前后端协作顺畅一点YApi 的性价比在开源方案里几乎是第一梯队。下面正式开始部署。2. 部署前环境准备Node.js 与 MongoDB 的版本选择2.1 服务器规格与操作系统YApi 的负载并不高一个几十人团队使用1 核 2G 内存的云服务器完全够用。不过要注意 MongoDB 本身比较吃内存默认配置下会占用大量系统内存作为缓存所以 1G 内存的小机器建议直接加 2G 左右的 swap否则跑一段时间后进程容易变得卡顿。操作系统方面CentOS 7/RHEL 系和 Ubuntu 20.04/Debian 系都很常见。本文命令以 CentOS 系为主Ubuntu 只需把包管理器从 yum 换成 aptMongoDB 的官方源写法略有差异我会在对应位置点出来。2.2 MongoDB 安装为什么推荐 4.4YApi 官方文档要求 MongoDB 2.6 以上但实际部署我不建议用太老的版本也不建议盲目追新。我推荐 MongoDB 4.4原因是这个版本稳定性和兼容性都成熟YApi 的连接驱动和 4.4 配合非常顺畅。MongoDB 5.0 之后的版本在用户认证机制和连接串行为上有变化YApi 这类老牌 Node.js 应用偶尔会踩坑没必要给自己找麻烦。CentOS 7 安装 MongoDB 4.4 的步骤# 添加 MongoDB 官方源 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 # 安装并启动 yum install -y mongodb-org systemctl start mongod systemctl enable mongod # 验证状态 systemctl status mongodUbuntu 用户按官方文档添加 apt 源即可注意系统版本代号要对应focal、jammy 等。安装完先别急着做鉴权配置YApi 部署文档默认用无鉴权的 MongoDB 连接串等平台跑起来之后再加账号也可以见第 6.1 节。2.3 Node.js 版本选定用 nvm 锁住环境YApi 官方要求 Node.js 7.6 以上因为代码里用了 async/await。但版本不是越高越好我实际部署发现 Node.js 18 以上的某些新版本在安装 YApi 依赖时偶尔会遇到原生模块编译问题。稳妥起见推荐 Node.js 14.21.x LTS 版本这个版本经历过多轮修复兼容性最好也足够跑 YApi 的所有功能。服务器上建议用 nvm 管理 Node 版本避免因为其他项目干扰全局环境# 安装 nvm curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash source ~/.bashrc # 安装并锁定 Node 14 nvm install 14.21.3 nvm alias default 14.21.3 node -v设置 default 的目的是让新开的 SSH 会话自动使用 Node 14否则登录服务器后找不到 node 命令后面配置 pm2 和 systemd 服务时会出现 ExecStart 里 node 路径不对的问题。3. 完整部署流程CLI 引导加手动启动3.1 安装 yapi-cliYApi 提供两种部署方式一种是手动 clone 源码仓库再安装依赖另一种是官方推荐的 yapi-cli 命令行工具。我强烈建议用 yapi-cli它会自动从仓库拉取代码、安装依赖、生成配置文件还带一个可视化部署引导页大幅减少手工操作出错的可能。# 全局安装 yapi-cli国内服务器建议指定镜像源 npm install -g yapi-cli --registryhttps://registry.npmmirror.com # 验证安装 yapi --version3.2 yapi server 可视化部署引导安装完成后运行yapi server这个命令会启动一个临时 Web 服务默认监听 9090 端口。浏览器访问http://服务器IP:9090就能看到 YApi 的部署引导页面。这一步有个容易混淆的点9090 只是部署引导页不是 YApi 最终的服务端口后面启动成功后访问的是 3000 端口。在引导页面里需要填写四类信息配置项建议值说明MongoDB 地址mongodb://127.0.0.1:27017本地安装的 MongoDB 默认端口数据库名称yapi建议单独用一个库方便备份管理员邮箱自己团队的管理员邮箱用于初始化管理员账号管理员密码自己设置后续登录管理后台用填写后点击部署终端会开始拉取代码、安装 npm 依赖这个过程可能持续几分钟耐心等待。部署完成后终端会打印部署路径、启动命令和日志文件位置这些信息记得保存下来。3.3 部署完成后的目录结构与启动验证yapi-cli 默认把代码部署到~/my-yapi目录结构大概是config.jsonYApi 的配置文件包含数据库连接、服务端口等关键参数。vendors/YApi 主程序及相关依赖。logs/运行日志目录。先手动启动一次确认没有任何问题cd ~/my-yapi node vendors/server/app.js看到类似log: 服务已启动请访问 http://0.0.0.0:3000的输出说明服务正常。此时访问http://服务器IP:3000就能看到 YApi 的登录页面。确认没问题后用 CtrlC 停掉进程进入下一步的守护配置。4. 后台自动运行三种守护方案的选型与配置直接运行node vendors/server/app.js有个致命问题进程挂在当前 SSH 会话下终端一关、SSH 一断YApi 就跟着没了。用nohup可以临时解决但进程意外崩溃后不会自动拉起服务器重启也不会自启。要把 YApi 当作正规服务来跑必须交给进程守护工具管理。这里分享三种方案。4.1 方案一pm2 进程守护推荐pm2 是 Node.js 生态最常用的进程管理工具YApi 本身就是 Node 服务用 pm2 管理最顺手。pm2 的守护逻辑是如果进程崩溃它会自动重新拉起重启服务器后也能通过保存的启动配置自动恢复。安装并启动# 全局安装 pm2 npm install -g pm2 # 启动 YApi 服务指定进程名为 yapi pm2 start ~/my-yapi/vendors/server/app.js --name yapi # 查看运行状态 pm2 status此时pm2 status应该能看到 yapi 进程处于 online 状态。关键的一步是设置开机自启# 保存当前进程列表 pm2 save # 生成开机自启脚本 pm2 startup执行pm2 startup后终端会输出一条包含sudo env PATH...的命令你需要用 root 权限执行它这样 pm2 及其管理的进程才会在服务器重启后自动启动。之后重启服务器验证一下发现 yapi 进程自动恢复说明配置成功。pm2 的日志管理也很方便pm2 logs yapi可以实时查看 YApi 输出排查问题时非常有用。这是我最推荐的方式没有之一。4.2 方案二systemd 系统服务如果你不想在服务器上多装一个 pm2用 Linux 自带的 systemd 也是完全可行的。systemd 的优点是系统级集成开机自启由系统统一管理日志通过 journalctl 查看不需要额外的守护进程常驻内存。新建服务文件vim /etc/systemd/system/yapi.service写入以下内容[Unit] DescriptionYApi Server Afternetwork.target mongod.service [Service] Typesimple User你的用户名 WorkingDirectory/home/你的用户名/my-yapi ExecStart/usr/bin/node /home/你的用户名/my-yapi/vendors/server/app.js Restartalways RestartSec10 [Install] WantedBymulti-user.target注意几点Afternetwork.target mongod.service保证网络和 MongoDB 先启动避免 YApi 起来后连不上数据库。Restartalways表示进程意外退出时自动重启RestartSec10是重启前等待 10 秒避免频繁重启。ExecStart里的 node 路径用绝对路径可以通过which node查询。启动服务systemctl daemon-reload systemctl start yapi systemctl enable yapi # 查看状态 systemctl status yapi # 查看日志 journalctl -u yapi -fsystemd 这种方式的好处是配置即文件方便团队内部统一管理服务器服务清单。4.3 方案三supervisor 备用supervisor 是 Python 生态的老牌进程管理工具如果你的服务器上本来就在用 supervisor 管理其他服务把 YApi 纳入统一管理也合理。配置如下[program:yapi] commandnode /home/你的用户名/my-yapi/vendors/server/app.js directory/home/你的用户名/my-yapi autostarttrue autorestarttrue user你的用户名 redirect_stderrtrue stdout_logfile/var/log/yapi.log然后执行supervisorctl update supervisorctl start yapi不过单独为了一个 YApi 去安装 supervisor属于额外引入一个常驻内存的 Python 进程没必要。只有原本就在用 supervisor 管理多个服务时才推荐。4.4 三种方案的对比与选择方案安装成本崩溃自愈开机自启日志查看适用场景pm2低npm 一条命令支持支持支持Node 项目统一管理推荐首选systemd零系统自带支持支持journalctl不想装额外工具系统级管理supervisor中支持支持日志文件服务器已有 supervisor 生态就我个人经验一台服务器上如果只跑 YApi 这一个 Node 服务systemd 和 pm2 都很好。但如果之后还会部署其他 Node 服务pm2 的进程列表一眼扫过去非常直观所以我最终选择了 pm2。方案确定后后续的维护命令都以 pm2 为例。5. 部署完成后的初始化配置与日常维护5.1 管理员注册与团队结构设置YApi 部署完成后访问http://服务器IP:3000点击注册页注册第一个账号。这个第一个注册的账号就是系统管理员后续注册的用户默认是普通成员需要管理员在后台调整权限。登录后建议立即做几件事完善个人资料确认管理员身份。在用户管理里熟悉成员列表后续给不同成员分配角色。在系统设置里确认注册方式如果部署在公网建议关闭开放注册避免陌生人注册账号。团队结构上YApi 的逻辑是分组 - 项目 - 接口三层。一个团队建一个分组每个项目对应一个独立的应用或服务接口再按模块分类录入。比如一个电商项目可以分为用户服务、订单服务、支付服务三个项目。5.2 项目创建、接口导入与 Mock 设置项目创建后建议直接用导入功能而不是手工一个个录入接口。YApi 支持导入 Postman、Swagger/OpenAPI、HAR 等格式的数据。对于已有接口文档的服务用 Swagger 格式导入能在一分钟内把整个服务的接口全部拉进来字段描述、请求参数、返回结构都会完整保留。导入完成后记得检查每个接口的 Mock 开关。YApi 会根据接口返回示例自动生成 Mock 数据前端联调时把请求地址改成http://服务器IP:3000/mock/项目ID/接口路径项目 ID 可以在项目设置里看到。Mock 数据里的随机字段类型也可以自定义比如日期、手机号、枚举值都在 Mock 配置里可以调整。这个能力对前端提前开发特别有用后端接口没写好前端也能拿到像样的数据继续干活。5.3 数据备份与恢复YApi 的所有数据都在 MongoDB 里备份非常简单# 备份整个 yapi 库到指定目录 mongodump --db yapi --out /data/backup/yapi_$(date %Y%m%d)恢复时用mongorestore --db yapi /data/backup/yapi_20240101/yapi建议把备份命令写进 crontab每天凌晨执行一次crontab -e # 每天凌晨 2 点备份保留最近 7 天数据 0 2 * * * mongodump --db yapi --out /data/backup/yapi_$(date \%Y\%m\%d) --quiet find /data/backup -name yapi_* -mtime 7 -exec rm -rf {} \;5.4 服务器重启后的检查清单配置了开机自启后服务器重启完 YApi 应该自动恢复。但为了保险重启之后我习惯按照这个顺序检查# 1. MongoDB 是否正常 systemctl status mongod # 2. YApi 进程是否在线 pm2 status # 3. 接口服务是否响应 curl -I http://127.0.0.1:3000这个清单看起来简单但能帮你快速区分问题出在数据库还是应用层。很多YApi 打不开的问题最终都是 MongoDB 没启动YApi 进程反复重启失败。6. 实际部署中踩过的坑与排查链路6.1 坑一MongoDB 鉴权导致的初始化失败有一种极其常见的场景服务器上 MongoDB 之前已经开启过鉴权或者运维直接在配置里加了--auth导致 YApi 部署引导页面里填的mongodb://127.0.0.1:27017连接串无法通过认证部署显示成功但运行时一直连不上数据库。排查链路是这样的先看 YApi 日志~/my-yapi/logs会发现重复出现类似MongoNetworkError: Authentication failed的错误。再去 MongoDB 手动连接验证mongo --host 127.0.0.1 --port 27017如果有鉴权直接连接会弹出未授权错误。解决方案是给 YApi 单独建一个数据库用户并把连接串改成带用户名密码的形式// 在 mongo shell 里执行 use yapi; db.createUser({ user: yapi_user, pwd: 你的密码, roles: [{ role: dbOwner, db: yapi }] });然后修改~/my-yapi/config.json里的数据库连接串db: { connectString: mongodb://yapi_user:你的密码127.0.0.1:27017/yapi }改完重启 YApi 进程。注意 MongoDB 的用户名密码尽量不要出现在公网可访问的文档里内部团队环境也要控制可见范围。6.2 坑二Node.js 版本太新导致依赖安装失败某次我在一台新服务器上部署直接装了当时最新的 Node.js 18结果yapi server部署阶段 npm 安装依赖时某个原生模块编译失败错误信息一堆关于 python 和 binding.gyp 的内容。虽然 Node 18 理论上兼容大部分生态但 YApi 依赖里的部分旧版本原生模块没有跟上。排查链路看部署日志定位到是node-gyp编译某个依赖失败。解决方式不是去修依赖而是直接把 Node 版本切换到推荐版本。用 nvm 重装 Node 14 后重新执行yapi server部署一次性通过。结论YApi 部署环境的 Node 版本别用太新的Node 14/16 是最省心的区间。已经踩过坑的不要跟 Node 最新版死磕换版本是最快的。6.3 坑三9090 和 3000 端口混淆防火墙只开了一个我第一次部署 YApi 时就闹过这出部署引导页面yapi server起的 9090 端口可以正常访问配置完一切正常但最后访问 3000 端口怎么都打不开。排查了半天发现云服务商的安全组只开放了 9090 端口3000 端口根本没放行。这个问题的排查思路很简单先确认服务进程本身在运行再用curl http://127.0.0.1:3000从服务器本地访问。如果本机能通、外网不通那就是防火墙和安全组的问题。在云控制台安全组里放行 3000 端口或者干脆加一层 Nginx 反向代理用 80/443 端口对外提供服务再把内网端口封闭起来。顺带一提如果服务器上 3000 端口已经被其他服务占用可以直接修改~/my-yapi/config.json里的port字段改成其他端口然后重启 YApi。6.4 坑四内存与磁盘吃紧引发的慢性故障低配服务器上 YApi 跑着跑着突然挂了pm2 status显示进程反复重启。看日志没发现应用报错但系统日志里有 OOMOut Of Memory记录。这就是典型的内存不足问题。解决思路# 查看内存 free -h # 查看 YApi 和 MongoDB 的内存占用 ps aux --sort-%mem | head -10处理方法是给系统加 swap# 创建 2G swap 文件 fallocate -l 2G /swapfile chmod 600 /swapfile mkswap /swapfile swapon /swapfile # 写入 /etc/fstab 使其开机生效 echo /swapfile none swap sw 0 0 /etc/fstab另外 MongoDB 默认绑定所有 IP 且未开启认证如果部署在公网服务器上一定要尽早启用鉴权和访问控制这一步在安全上不能省。MongoDB 监听地址建议只保留127.0.0.1除非有明确的远程访问需求。6.5 坑五服务器重启后 YApi 启动顺序问题配置了 pm2 或 systemd 自启后有一种现象会让你怀疑人生服务器重启后YApi 起不来或者起来了但连不上数据库。原因大概率是 MongoDB 比 YApi 晚启动YApi 启动时建立数据库连接失败虽然服务本身起来了但一直处于连接重试状态。pm2 场景下可以通过 pm2 的依赖启动配置解决或者写一个启动延迟脚本。更简单的做法是把 MongoDB 也交给 systemd 管理并设置开机自启然后给 YApi 的 systemd 服务文件里加上Aftermongod.service确保数据库先就绪。用 pm2 的朋友我建议把 MongoDB 也改成 systemd 管理并且在 pm2 启动参数里加上--restart-delay10000给数据库留出启动时间# 重启现有 yapi 进程并设置延迟 pm2 restart yapi --restart-delay 10000 pm2 save这样重启服务器后即便 MongoDB 起来得慢一点Yapi 进程也会等待一段时间再拉起不会因为抢跑而反复崩溃。最后再补充一个我自己常用的技巧部署完成后写一个简单的一键状态检查脚本把第 5.4 节的检查项串起来每天定时执行。YApi 这种内部工具稳定运行不折腾就是最大的价值。希望这篇文章能帮你一次把 YApi 在 Linux 服务器上部署到位少走我刚才说的这些弯路。
阅读完成 · 觉得有帮助？
