★ FEATURED ARTICLE 1. 先搞清楚RAP2解决了什么问题有段时间我手上同时推进三个前后端并行开发的小项目后端接口还没完全定义好前端已经进入联调期。每天都有人来问这个接口到底返回什么结构字段名是id还是_id分页参数叫page还是currentPage。等接口文档终于更新一版前端代码又要跟着改一遍。后来把一个叫 RAP2 的开源 API 管理部署到本地才真正把这个流程理顺了。RAP2 是一套开源的接口管理平台把 API 文档维护、Mock 数据生成、团队协作集中在一个 Web 系统里。它的核心工作方式是后端在系统里维护接口定义包括请求方法、URL、请求参数、响应结构前端依托这些定义生成 Mock 数据在无后端联调的情况下先把页面跑起来等真实接口可用时只需要把 Mock 开关关掉或切换请求地址代码基本不用改动。这个思路和很多商业协作平台相似但 RAP2 胜在开源、可控、可私有化部署。之所以要把这套环境部署到本地通常有三个原因。第一公共服务意味着数据要和外部共享存储而团队内部的接口定义往往能逆向推导出业务结构和数据模型这类信息不适合放公共环境。第二线下联调需要频繁调整 Mock 数据自建一套环境想怎么改都行没有人打扰也没有网络波动。第三部分团队有内部单点登录、权限审计或网络隔离要求公共版本改不了登录逻辑本地部署之后可以针对性地做定制。这篇文章会把整套本地部署流程拆开讲一遍从依赖准备到前后端分别部署再到 Nginx 反向代理配置最后整理我在实际部署里踩过的坑和排查方法。如果你也打算在公司内网搭一套接口管理工具或者想在自己电脑上跑一套完整环境研究这篇可以直接照着操作。2. 部署前先理清架构和依赖2.1 RAP2 的两个工程分别是什么RAP2 由两个独立工程组成这个结构在部署时特别容易忽略提前讲清楚能省很多时间。后端工程叫rap2-delos负责所有数据处理逻辑。接口文档的增删改查、Mock 模板的存储、用户权限校验、登录态管理等都在这一层。它跑在 Node.js 环境里使用 Koa 框架开发启动后默认监听 3800 端口提供全套 RESTful API。前端所有请求都打在 3800 端口上包括登录、文档列表、Mock 数据拉取。前端工程叫rap2-dolores是一个 React 单页应用。它负责页面展示和交互用户看到的接口列表、接口详情、Mock 编辑界面都是这个工程渲染出来的。构建完成之后会生成一批静态文件本身不监听端口只要能通过 Nginx 或任意静态文件服务托管起来就能访问。后端负责逻辑前端负责展示两者通过 HTTP 接口通信。很多人在部署时只拉了一个仓库折腾半天发现页面起不来就是因为漏掉了另一半。2.2 基础依赖版本选择梳理清楚两个工程之后再来看运行环境。部署一套完整的 RAP2 本地环境至少需要以下四类组件组件版本建议用途Node.js12.x 至 14.x运行后端 delos 服务MySQL5.7 或 8.0持久化存储接口定义、用户、Mock 模板Redis4.x 及以上缓存用户会话、临时 Mock 数据Nginx任意稳定版本托管前端静态文件、反向代理 API 请求版本选择上我多说几句。Node.js 版本不必追新12 到 14 是最稳的区间我在 16 和 18 上都遇到过依赖编译报错虽然可以手动修复但没必要给自己加工作量。MySQL 5.7 部署最省心8.0 也能用但后面会提到一个认证插件兼容性问题需要额外处理。Redis 只要不是太老的版本问题都不大默认配置即可。另外要确认服务器上可以直接访问外网包源部署过程中需要执行多次npm install会从 npm 仓库拉取大量依赖包。如果服务器是内网隔离环境需要提前配置好私有镜像源否则第一关就卡住了。2.3 数据库初始化依赖装好之后先初始化 MySQL 数据库。RAP2 后端启动时不会自动建库建表需要手动处理数据库这一层。用 MySQL 客户端登录执行以下操作CREATE DATABASE rap2_delos DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci; CREATE USER rap2localhost IDENTIFIED BY 你的密码; GRANT ALL PRIVILEGES ON rap2_delos.* TO rap2localhost; FLUSH PRIVILEGES;字符集这里我用的是utf8mb4而不是默认的utf8。接口定义里经常出现中文描述、emoji 标记、特殊符号utf8在部分场景下存不了四字节字符会出现Incorrect string value报错。实际项目里我们甚至会在接口备注里贴截图链接和临时标记用utf8mb4是最稳妥的。建完库之后进入 rap2-delos 工程目录里面有现成的建表脚本。执行npm run create-db会自动读取配置里的数据库连接信息并创建所有数据表。这一步执行完可以用SHOW TABLES确认一下正常情况下能看到用户表、接口表、mock 相关表等十几张数据表。3. 后端部署其实就三步3.1 拉取代码并安装依赖数据库就绪后开始处理后端工程。git clone rap2-delos 仓库地址 cd rap2-delos npm install依赖安装这一步需要一点耐心这个工程依赖包非常多尤其是node-sass这类涉及原生编译的包可能需要几分钟。如果安装中途报错常见原因是 Node 版本过高或网络中断切回 12.x 版本重试基本能解决。3.2 修改配置文件安装完成后进入config目录你会看到默认配置。实际操作中建议复制一份config.example.js为config.js在副本上修改。需要确认的核心配置项有五个服务监听地址默认是0.0.0.0如果只想本机访问可以改成127.0.0.1服务端口默认3800一般不需要改MySQL 连接信息主机、端口、用户名、密码、数据库名Redis 连接信息主机和端口会话密钥这个要改成一个足够长的随机字符串用于登录态签名MySQL 连接这一项特别容易写错。我遇到过一次连接串里密码包含特殊字符没有做 URL 编码解析时密码被截断一直报连接被拒绝。排查了很久才发现是配置文件解析的问题。密码里有特殊字符时尽量改成纯数字字母组合或者确认配置文件原样读取不做二次解析。服务监听地址也提醒一句。默认0.0.0.0意味着局域网内其他机器也能访问这个端口。如果数据库密码设得比较弱建议把服务监听限制在127.0.0.1Nginx 做反向代理时走本机回环地址即可不影响功能。3.3 启动后端服务配置完成以后启动服务node bin/www看到类似listening on port 3800的日志输出说明后端已经起来了。这时候可以先用 curl 做一个最基本的健康检查curl http://127.0.0.1:3800/如果返回类似Not Found的 JSON 响应不用紧张根路径本来就没有内容只要请求能到服务就说明进程活着。更准确的方式是访问登录接口用 POST 提交一个请求体看是否返回业务层面的错误信息。后端启动过程中最常见的错误是ECONNREFUSED连接被拒基本都是 MySQL 或 Redis 没起来或者连接信息配错了。逐个确认这两个服务的进程状态就能定位。4. 前端构建与 Nginx 配置4.1 构建前端静态资源后端跑通之后处理前端页面。前端工程是标准的 React 应用构建过程比后端简单很多git clone rap2-dolores 仓库地址 cd rap2-dolores npm install npm run build构建成功后build目录下会生成整套静态文件包括index.html、static目录下的 JS 和 CSS。这些文件就是用户访问时的页面资源。需要注意构建前检查前端工程里配置的 API 请求地址。默认情况下前端会把请求发到当前域名下的/api路径通过反向代理转发到后端。如果你的后端不在本机需要找到前端的配置文件把请求地址改成实际的后端入口。改完之后重新执行npm run build让新的请求地址进到打包产物里。这个步骤我吃过亏。第一次部署时没有检查前端的 API 地址配置构建完直接扔到 Nginx 上页面能打开但登录请求全部发送到前端服务器的 80 端口后端 3800 端口一个请求都没有收到。后来逐个检查 Nginx 访问日志才定位到前端打出来的请求路径根本不是预期的那条。所以构建前先看配置文件里请求前缀对不对能省掉后面一堆排查时间。4.2 Nginx 配置域名和路由静态文件准备好之后用 Nginx 把它们托管起来同时把 API 请求反向代理到后端。下面是一份可以直接用的 Nginx 配置模板核心逻辑就是静态资源直接读文件返回/api路径的请求转发到后端 3800 端口。server { listen 80; server_name rap2.example.local; root /data/www/rap2-front; index index.html; location / { try_files $uri $uri/ /index.html; } location /api { proxy_pass http://127.0.0.1:3800; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; } }try_files $uri $uri/ /index.html这一行是单页应用的核心配置。React 路由在浏览器端切换时URL 路径会变化但如果刷新页面Nginx 会拿这个路径去磁盘找文件找不到就 404 了。加上try_files之后所有找不到的路径都会回退到index.html由前端路由接管刷新就不会断。反向代理的proxy_pass我建议直接写http://127.0.0.1:3800不要写localhost。在某些系统上localhost会被解析成 IPv6 地址::1而后端服务监听的是 IPv4 的127.0.0.1连接就会被拒绝。这种情况 SSH 登录服务器排查时不会报错但页面访问一直在转圈最后看 Nginx 错误日志才发现问题。4.3 启动验证与全链路检查Nginx 配置保存之后执行nginx -t检查语法确认无误后nginx -s reload让配置生效。然后打开浏览器访问配置的域名或 IP。全链路验证我一般按以下顺序去测每一步都确认正常再走下一步打开首页确认页面能加载控制台没有 JS 报错用管理员账号登录确认登录成功且跳转到项目列表页新建一个项目进入项目空间创建一条接口定义打开接口详情页尝试编辑并保存确认刷新后数据还在打开 Mock 请求地址确认能返回符合模版的假数据这五步全部通过说明从浏览器到 Nginx 到前端静态文件到后端 API 到 MySQL 的完整链路都是通的。任何一步失败就按链路逐层往上排查。5. 日常使用里必须避开的几个坑5.1 登录态失效的根源在 RedisRAP2 的用户登录态和验证码信息存放在 Redis 里Redis 一旦出现问题最直接的表现就是登录不上或者刷新后登录态丢失。我记得有一次部署完成后管理员账号登录很快就成功了但页面一刷新又跳回登录页。当时第一反应是 Cookie 配置问题检查了一圈 Nginx 代理头也都正常。后来发现 Redis 运行时的内存上限设置得太小大量 Mock 数据写入时触发了内存淘汰策略把会话缓存挤出去了。回头调整 Redis 的maxmemory配置并设置合理的内存淘汰策略为allkeys-lru之后问题就不复现了。所以部署完成后建议第一时间检查 Redis 的内存上限别用默认配置硬扛。另外Redis 的protected-mode在本地环境无所谓但如果部署在公司内网建议给 Redis 设置密码避免内网其他机器直接连上来。5.2 MySQL 8.0 的认证插件兼容问题部署时如果选用的是 MySQL 8.0需要关注一个认证插件兼容问题。MySQL 8.0 默认使用caching_sha2_password作为用户认证方式而较老版本的 Node.js MySQL 客户端驱动可能不支持这个新认证协议连接时会直接报错。解决方案有两种。一种是调整 MySQL 用户认证方式执行ALTER USER rap2localhost IDENTIFIED WITH mysql_native_password BY 你的密码; FLUSH PRIVILEGES;另一种是升级后端依赖中的 MySQL 驱动版本。我更推荐第一种简单直接不会引入依赖变更风险。如果用 Docker 方式部署 MySQL记得把建用户和修改认证方式的语句都放进初始化脚本里否则容器重建后问题还会复现。5.3 跨域问题的正确打开方式因为前端和后端通过 Nginx 同一个域名暴露解决了跨域问题这是最标准的部署方式。但如果你偷懒直接用两个端口分别访问前端和后端浏览器请求 API 时必然触发跨域拦截。我之前为了图省事直接用http://192.168.1.10:8080访问前端页面而前端请求发到了http://192.168.1.10:3800浏览器直接报 CORS 错误。RAP2 后端虽然做了跨域处理但涉及到 Cookie 传递时还是麻烦。老老实实走 Nginx 反向代理所有请求都用同一个域名和端口才是干净的做法。5.4 常见问题速查表现象可能原因排查思路后端启动报ECONNREFUSEDMySQL 或 Redis 未启动确认两个服务进程是否存在端口是否被占用登录时一直转圈前端请求地址配置错误打开浏览器控制台看请求 URL 发到了哪页面刷新跳登录页Redis 会话被清检查 Redis 内存上限和淘汰策略保存接口时报数据库错误字符集设置为utf8确认库表字符集为utf8mb4Nginx 转发请求 502后端服务未启动在本机 curl 后端端口确认服务存活构建前端时内存溢出Node 内存不足设置NODE_OPTIONS--max-old-space-size4096后重试5.5 数据备份与迁移本地环境部署好之后数据就是团队资产了。接口文档、Mock 模板、项目权限关系都保存在 MySQL 里备份策略不能省。我现在的做法是写一个简单的每日备份脚本用mysqldump将rap2_delos数据库导出为 SQL 文件保留最近七天mysqldump -u rap2 -p密码 rap2_delos /data/backup/rap2_delos_$(date %Y%m%d).sql find /data/backup -name rap2_delos_*.sql -mtime 7 -delete备分文件建议放在独立磁盘目录避免和数据库文件在同一块盘上防止磁盘故障时备份也跟着丢。恢复时直接mysql -u rap2 -p密码 rap2_delos 备份文件.sql即可RAP2 的表结构相对稳定跨版本恢复基本没有兼容性问题。6. 本地部署后的团队协作配置心得6.1 用户权限与项目隔离部署完成后接下来最重要的事情是规划账号体系。RAP2 支持团队和项目两层权限用户可以创建团队团队下可以创建多个项目项目成员细分管理员和普通成员。默认注册接口是开放的这意味着任何能访问到页面的人都能注册账号。公司内网环境下建议修改后端配置关闭开放注册改成管理员代创建账号避免出现陌生账号和数据混乱。我的做法是保留一个管理员账号项目成员由管理员统一创建并分配团队。项目敏感程度高的话可以在后端再加一层访问控制按来源 IP 段限制非办公网段一律拒绝虽然防御能力有限但能杜绝绝大部分误访问。6.2 多人协作时 Mock 数据的使用规范工具本身只是工具但多人一起使用时要约定使用规范。我们团队使用 RAP2 时定了三条规则实测让协作顺畅很多接口定义以 RAP2 为主禁止仅在聊天工具里发接口文档截图避免多份文档状态不一致Mock 数据尽量贴近真实结构尤其是枚举值、状态码、分页字段减少前端写死逻辑后返工的情况接口变更时先更新 RAP2再同步代码保证文档和实现的时间差最短这三条规则看起来简单但确实让联调阶段的沟通成本降了不少。以前天天有同事来问接口字段现在直接甩一个 RAP2 页面链接过去自己对照数据结构写代码就行。6.3 值得尝试的二次开发方向本地部署的一个隐藏价值是你可以改代码。围绕 RAP2 我们团队后续做过几个小的定制虽然都不是大改动但确实解决了实际痛处。其中一个比较实用的改动是扩展了 Mock 数据生成规则。RAP2 内置的基础 Mock 规则比较有限我们遇到一个需求某个接口的响应列表必须按日期倒序生成字段格式要和线上完全一致。直接在代码里加了一个自定义 Mock 生成模板配合拿线上真实数据的脱敏样本Mock 数据的可用性一下子提高了很多。如果你也打算二次开发建议先从前端的接口类型和 Mock 模板生成规则入手。这两个地方逻辑相对独立改动影响面小验证效果也直观。而且前端是 React 应用组件化程度高基本不会越改越南。7. 几个提升效率的小动作文章末尾再补充几个我踩过坑之后形成的小习惯谈不上多高深但确实能省时间。第一后端服务用 pm2 守护进程管理而不是裸跑node bin/www。pm2 可以在进程崩溃后自动重启开机自启日志写入文件方便排查。实际部署中 Node 进程半夜被 OOM 干掉的情况并不少见没有守护进程的话第二天团队全员都会发现服务挂了。第二本地部署环境单独使用域名不要用 IP 加端口的方案。项目团队里新同事入职给一个形如rap2.team.local的地址简单好记后续如果要加 HTTPS 证书域名方案也更容易接入。配置 Nginx 时在 server_name 里写明域名再在本地 DNS 或hosts里做一下映射就行。第三RAP2 页面里能导出的数据比想象的多接口定义、项目数据、Mock 规则都支持 JSON 导出。迁移环境或者做存档时先用导出功能生成一份 JSON再用 SQL 备份兜底两层保障。我们有一次 MySQL 误操作导致部分表数据被清掉就是靠早前导出的 JSON 数据重建了关键接口定义。第四升级依赖包前先备份数据和当前可用版本。有一次我为了去掉一个安全公告里的漏洞顺手升级了后端某个依赖包结果启动时引入了一个行为变更列表接口的排序参数被改了。折腾了小半天才回退版本。工具链稳定比追新重要本地环境不是生产环境但也不是拿来练手的。把 RAP2 完整部署好之后前后端并行开发的节奏确实顺畅了很多。这个工具本身不复杂但把流程跑通还是需要一些细节上的耐心。希望上面这些步骤和踩坑记录能让你少走几趟弯路。
阅读完成 · 觉得有帮助？
