YAPI这名字用过的人都知道是国内接口管理工具里少有的既轻量又功能完整的方案。去年年中有个新项目前后端分离接口量大团队又分散在好几个城市靠文档表格和在线协作文档根本顶不住。当时选型对比了市面上几个开源工具最后还是定了YAPI原因无非三点一是部署轻一个Node服务加一个MongoDB就能跑二是它的接口调试、Mock、自动化测试能力够用三是源码开放遇到不满足的地方可以自己改这正是二次开发的价值所在。这篇文章不打算只讲安装完能跑起来这种入门级内容。我的目标是把从零开始部署到理解源码结构到实际做二次开发改动再到覆盖式升级维护这一整条链路讲清楚。重点放在那些官方文档没写、但实际操作中几乎必然遇到的坑。适合谁看准备在团队内部搭建接口管理平台的技术负责人或者接了类似的安装定制任务、需要自己折腾一遍的开发工程师。基础的Linux和Node知识假设你有纯粹的界面操作不多说。1. 动手安装之前先搞清楚二次开发需要什么很多人装YAPI上来就抄一段Docker命令跑通了才开始想我要改什么东西结果发现容器里的文件和宿主隔离改起来特别别扭。我的建议是先想明白二次开发的范围再决定用哪种安装方式。1.1 源码安装和容器安装怎么选YAPI的部署方式大体分三类官方提供的可视化安装、Docker容器、源码手动部署。如果只是临时试用官方脚本或Docker最省事。但只要动了二次开发的念头——比如改前端Logo、加一个内部登录接口、调整自动化测试的逻辑——就必须走源码手动部署这条路原因很实际容器相当于一个封闭盒子你改宿主上的文件它不一定进得去就算用volume挂载YAPI的前端是构建产物改完还得重新编译在容器里做这些事很绕。我做这次部署时一开始也图省事用Docker跑了一个测试环境后面要改前端样式的时候后悔了重新回滚到源码部署重来了一遍。所以如果你想二次开发或者未来大概率会做定制直接源码部署是唯一理性的选择。部署前最好先盘一下团队的能力。YAPI前端基于React后端是Node.js的Express框架数据库用MongoDB。团队有没有会Node的人、有没有人写过React这决定了后续能改到什么程度。还有一个核心问题你们的接口数据流和团队权限体系是什么样的这直接影响你是否要改后端权限模块。把这些想清楚再动手比装完再返工强太多。1.2 版本搭配与基础环境要求我第一次部署时在版本上踩了坑这里直接给出一组实测稳定的组合组件版本说明Node.js12.x 或 14.x LTS后续编译前端时兼容性最好MongoDB4.x3.x 也没问题但建议4.xRedis不需要YAPI默认不用Redis操作系统CentOS 7 / Ubuntu 20.04Linux环境最稳构建工具npm 6.x与Node 12/14匹配Node版本这里要特别强调。有一个很隐蔽的坑YAPI的源码拉下来后npm install时某些依赖在Node 17以上会报编译错误主要是node-gyp相关的原生模块。这个报错很迷惑ERR! gyp ERR!刷一大屏我刚开始以为是网络问题。后来把Node从16降到14装的时候一路顺利。MongoDB如果选4.x要注意服务器的Linux发行版能不能装对应源。CentOS 7默认源里只有3.6需要手动添加MongoDB官方源。装完后设置开机自启很关键服务器的防火墙要放开27017端口内网环境的话建议不要对外暴露。2. 从源码拉取到YAPI跑起来的完整过程我以CentOS 7环境为例把实际操作步骤展开写一遍。这一步的意义不只是跑起来更是为了后面二次开发建立可控的环境所以要特别注意每个操作的实际作用而不是机械地敲命令。2.1 获取源码并准备配置YAPI的源码托管在GitHub上仓库名称记住两个关键词就行YMFE和yapi。我通常是直接clone主干代码因为很多修复和功能更新都在master上。clone下来之后会看到根目录下有一个package.json和api/子目录真正的后端代码在api这个目录里。# 拉取源码 git clone https://github.com/YMFE/yapi.git cd yapi # 安装依赖 # 注意在根目录和api目录下都需要执行一次 npm install --registryhttps://registry.npmmirror.com cd api npm install --registryhttps://registry.npmmirror.comnpm install如果网速慢或失败换个镜像源能省去大量时间。国内环境用npmmirror这个镜像一般没问题。接下来是配置文件。YAPI支持两种方式一种是通过可视化页面在浏览器里配置数据库和账号另一种是直接在config.json里写好配置。二次开发场景下推荐用配置文件方式因为可以版本化团队拿到后直接改配置就能复现环境。在api/目录下创建config.json内容样例{ port: 3000, adminAccount: adminexample.com, timeout: 120000, db: { connectString: mongodb://127.0.0.1:27017/yapi, servername: 127.0.0.1, DATABASE: yapi, port: 27017 }, mail: { enable: true, host: smtp.example.com, port: 465, from: no-replyexample.com, auth: { user: no-replyexample.com, pass: your-password } } }adminAccount就是你登录后的管理员账号推荐配一个真实邮箱因为YAPI的部分通知功能会用到邮件。如果你在纯内网环境mail部分直接设enable为false不影响核心使用。2.2 启动时需要紧盯的校验点配置写好后在api/目录下执行node server/app.js第一次启动会做两件事初始化数据库索引创建管理员账号。日志里看到web和server两个服务都起来了就说明启动基本成功。需要注意YAPI会启动两个服务进程一个是API服务一个是静态资源服务。默认都在3000端口。启动日志中如果出现MongoError: connect ETIMEDOUT之类的报错多半是MongoDB没起来或者连接串写错。浏览器访问http://服务器IP:3000如果看到登录页面就说明前端资源也正常。用config.json里adminAccount配的邮箱登录初始密码是yapi.admin登录后建议立即修改密码。提示如果你是二次开发之后再来启动建议第一次初始化完成后先不要急着登录操作。先把数据库备份一份干净的初始状态后面改坏了可以随时恢复。这个习惯能救你很多次。2.3 项目初始化与成员管理的直观认知登录进去后先把项目这个概念理解清楚。YAPI里的组织架构是分组可以理解成目录项目挂在分组下项目里的内容主要是接口分类分类下是具体接口。多人协作时先建一个测试分组把一个项目分配给指定成员。这块不在二次开发范围内但部署完必须做因为它会影响你对权限数据结构的理解而权限模型恰恰是二次开发时绕不开的东西。以管理员身份创建一个分组再在分组里创建项目然后把团队成员加进来分配不同角色。至此基础环境就算完全跑通了。接下来才是重头戏看源码改想要的功能。3. 前端目录结构与常见改造切入点YAPI的前端代码是React技术栈跟一般的React项目一样有清晰的目录划分。二次开发大多数需求都集中在前端比如换Logo、调整页面文案、隐藏菜单、改造布局。这部分不涉及后端接口最快也最容易出效果。3.1 前端资源放在哪里源码根目录下的static/目录就是前端资源所在。里面结构大概是这样的static/ /src React源码目录 /node_modules 依赖包目录 /build 编译后的静态文件目录默认访问时YAPI用的是不带src的静态目录也就是编译后的build产物。如果你改了src里的代码不重新编译页面不会生效。这导致很多人刚开始改完发现没变化以为没改对。实际上必须执行前端构建命令cd static npm install npm run build执行完build目录下的文件更新重启服务修改才会出现。构建过程比较慢内存小的服务器可能执行到一半报错这时候增加swap分区是一个有效的办法。3.2 三个最常见的二次开发小改造改造一换掉Logo和站点标题这个需求几乎每个公司在内部部署时都会有。YAPI的界面顶部有一个默认Logo和默认的YAPI接口管理平台标题要改成自己的品牌。Logo文件通常放在static/src/yapi/Logo目录下直接替换同名文件即可。标题则在static/src/目录下找到包含siteName或title字样的配置文件修改。改完重新构建。改造二隐藏某些入口菜单比如有些公司希望隐藏数据导出功能或者不想让普通成员看到自动化测试配置入口。前端菜单配置通常集中在static/src/的导航文件里找到包含菜单项数组的代码注释掉或删除对应项。我改过一次发现菜单list里每一项是对象直接注释掉要隐藏的那一项构建完就生效。改造三对接公司内部登录体系这个需求比较复杂先说思路。YAPI前端在请求后端时带有一个token机制登录成功后后端返回token前端存在localStorage里。如果要对接自己的单点登录就是在登录页面做跳转或调内部登录接口登录成功后再调用一次后端登录接口获取token。听起来复杂但实际改的仅仅是登录跳转逻辑和新增一个登录接口后续后端二次开发的部分我会再说。需求前端改动点是否涉及后端工作成本换Logo、改标题Logo文件、站点配置否小菜单隐藏/权限控制导航配置轻微小对接统一登录登录页、token管理需要较大自定义接口请求头请求封装文件需要中前端二次开发有个容易被忽略的细节cookie的跨域和sameSite策略。如果YAPI部署在一个域名下你的前端请求跨域到后端时浏览器的sameSite策略会拦截cookie。YAPI本身不重度依赖cookie但部分登录场景会用到。遇到登录状态丢失、持续重定向的问题时第一个先查这个。4. 后端扩展接口鉴权、自动化交底与脚本安全性相比于前端的看得见摸得着后端二次开发是真正决定YAPI能否贴合团队流程的关键。做这一层开发之前必须先花时间读一遍后端代码结构否则就是在迷宫里乱撞。4.1 后端启动流程与代码目录功能速览YAPI后端主入口在api/server/app.jsExpress的配置和路由挂载都在里面。开发时经常要动的是以下几个目录api/server/ /controllers 接口的具体逻辑 /middlewares 中间件身份校验、请求日志等 /models 数据模型MongoDB集合的结构定义 /routes 路由定义URL路径与controller的映射 /utils 工具函数 /cron 定时任务初次读这个项目时建议从routes目录入手因为你最先想改的接口通常都能在routes里找到映射关系。比如登录相关的逻辑在controllers/下的user.js里。了解了路由映射也就明白了一个请求从前端发起、经过路由、命中controller的完整链路。4.2 实战一新增一个内部鉴权接口当时我的团队有一个具体的需求YAPI要对接公司内部的统一权限服务实现只要内部系统登录过打开YAPI就自动登录。实现思路是在前端加一个使用内部账号快速登录的按钮点击后请求一个自定义后端接口。这个接口接收内部系统传来的token验证通过后直接生成YAPI的有效token并返回。新增一个自定义接口需要两步第一步在routes/下新增一个文件例如custom.jsconst { login } require(../controllers/user.js); const { verifyToken } require(../utils/xxx.js); // 自定义的token校验工具 module.exports function(router) { router.post(/custom/login, async function(req, res) { try { const token req.body.token; const userInfo await verifyToken(token); if (!userInfo) { return res.json({ errcode: 403, errmsg: 内部鉴权失败 }); } const result await login(userInfo.email, userInfo.password); res.json(result); } catch (e) { res.json({ errcode: 500, errmsg: e.message }); } }); };第二步在app.js中挂载这个路由文件。通常app.js里有类似这样的一段路由挂载逻辑const customRouter require(./routes/custom.js); customRouter(router);这里有个经验YAPI内部登录controller返回的result包含token字段前端拿到后直接存入localStorage之后所有请求都会自动带token。这个登录流程等于绕过了YAPI的密码校验只做了内部系统的token验证。4.3 实战二自动化测试引擎的扩展思路YAPI自带的自动化测试支持在接口用例中编写断言脚本这部分脚本在前端运行。默认的断言能力有限我做过一次扩展主要替团队实现了对上游接口的结果做二次校验后再传给依赖它的接口。核心思路是在自动化测试的执行器文件中找到一个skip和过滤器之类的扩展点在接口执行前注入自定义逻辑。以YAPI的底层实现来看它有自定义断言脚本入口通常允许在before和after钩子里调用自定义函数。实际改动不复杂只要理解了YAPI测试脚本的执行顺序——请求前、请求后、断言——自定义逻辑就能插进去。我通常是直接把这些逻辑写在测试用例对应的脚本里而不是动框架源码。这个做法的好处是后续YAPI版本升级不用再改框架层代码。4.4 公共脚本的安全隐患——最容易翻车的点这个必须单独拿出来说。YAPI的接口测试脚本可以保存公共脚本一般在自动化测试-公共脚本里维护。由于这些脚本执行时能够调用Node的全局对象如果没有安全限制恶意脚本可以访问服务器的文件系统。这在跨部门多人使用的大团队里尤其危险。如果你负责YAPI的部署维护必须检查是否有人创建了包含fs或child_process的公共脚本。我给过自己团队一个硬性规定公共脚本只允许对响应数据进行截取和断言严禁访问系统级对象。同时建议在服务端点做一层请求过滤或安全凭证管理防止未授权用户利用脚本获取敏感信息。5. 从开发到线上覆盖式升级与日常维护经验二次开发完成后面临的下一个问题是如何把改动后的YAPI稳定地跑在线上并持续升级。很多时候开发环境跑得好好的一上生产就各种问题。这里分享一下我惯用的升级流程和数据备份策略。5.1 覆盖式升级旧配置如何安全保留YAPI源码升级时最怕的是配置文件被覆盖。官方源码在更新过程中不会动你创建的config.json但如果你改了源码目录下的公共文件更新时就有冲突风险。我的处理方式是把整个api/下的config.json单独备份一份升级流程如下# 备份配置 cp -r yapi/api/config.json /data/backup/ # 拉取新代码 cd /data/yapi git pull origin master # 重新安装依赖 npm install --registryhttps://registry.npmmirror.com cd api npm install --registryhttps://registry.npmmirror.com # 覆盖式替换自定义的路由和自定义controller具体文件看你的改动 cp /data/backup/custom.js api/server/routes/ # 重新构建前端 cd static npm run build # 重启服务 pm2 restart yapi这里有个技术点YAPI官方没有明确的数据库迁移工具概念MongoDB的数据结构在升级时通常不用手动迁移。但如果跨大版本升级比如从1.x到新版本数据库结构变化后有可能会出现某些字段缺失。遇到这种情况在备份后先起一个临时实例连接旧数据库测试一下确认没报错再切流量。这个步骤不要省我就吃过一次亏——跨版本升级后原来是字符串的字段变成了数组格式老数据查询直接报错。5.2 数据备份与快速恢复的实际操作YAPI的数据全部在MongoDB里备份就是对MongoDB做dump。我的备份策略是每天凌晨3点做一次全量备份保留最近7天。备份命令mongodump --host 127.0.0.1 --port 27017 --db yapi --out /data/backup/yapi_$(date %Y%m%d)恢复时执行mongorestore --host 127.0.0.1 --port 27017 --db yapi /data/backup/yapi_20240101/yapi这里有个micro-tipmongorestore恢复的db名称默认取备份目录的db名如果原库名不叫yapi你可能要把目录名改一下或者用--nsInclude指定命名空间。我一般在备份脚本里就把命名空间写死避免恢复时搞错。验证备份不能等到出事才想起。我每个月会实际做一次恢复演练起一个临时Mongo实例然后执行mongorestore再启动YAPI连接这个临时库确认登录、项目、接口数据都在。这个预演能在真正故障时省下大量抢救时间谁做谁知道。5.3 pm2守护进程与开机自启管理YAPI进程我不建议直接nohup挂后台而是用pm2做进程守护。配置很简单pm2 start process.jsonprocess.json的关键内容{ apps: [{ name: yapi, script: api/server/app.js, cwd: /data/yapi, instances: 1, watch: false, max_memory_restart: 1G, env: { NODE_ENV: production } }] }这里注意instances务必设为1。YAPI内置了两个进程相互配合如果你用pm2开多个实例反而会引起端口冲突或数据不一致。watch建议关闭避免源码变更后自动重启导致服务中断。开机自启用pm2自带能力pm2 startup pm2 save这样服务器重启后YAPI会自动拉起省去人为介入。6. 那些安装和二次开发后的真实体验感悟这次YAPI部署加定制改造我走完了从需求梳理、环境选型、源码阅读、前后端改造到最终上线维护的完整闭环。如果让我再从头做一次有一件事一定会提前做先把要改什么列成清单逐一标出需要动到前端还是后端再决定代码改造的优先级。这样能避免来回切环境、反复构建前端框架的时间浪费。有两点想特意强调。第一YAPI前端构建非常吃机器内存如果你的服务器只有2G内存构建时极容易卡死。要么增加swap空间要么把构建放到本地开发机完成后把build目录产物直接上传到服务器。这个做法也能作为团队协作标准开发机负责构建服务器只跑可用产物。第二依赖版本锁定非常关键。YAPI的依赖包虽然有package.json但部分依赖没有锁版本。两周后重新npm install可能装出不同版本导致某些功能异常。建议把package-lock.json纳入版本管理明确作为还原依赖的唯一依据。这能避免在我机器上没问题服务器上就出错的尴尬。二次开发的边界也要心里有数。YAPI的核心架构到今天已经比较稳定但前端框架和内部模块的组织方式并不算现代。如果需要做深度定制尽量把自定义逻辑模块化、独立化——要么新增路由文件要么以公共脚本的形式扩展不要直接修改它的核心业务文件。尽量通过外挂而非改造的思路去解决问题能让后续升级省力太多。最后提醒一句团队里一定要提前约定YAPI的管理规范比如谁来维护公共脚本、谁有管理员权限、接口数据变更时如何同步。平台工具通常是越用越乱趁早立规矩比以后费力清理更划算。