共享表格里的接口文档又对不上了，我才决定系统地解决这件事：做一次RAP2本地开发环境部署，把接口定义、Mock数据和文档协作全部收到自己掌控的服务里。RAP2是开源社区里很成熟的API管理与Mock方案，前后端分离，本地跑起来后团队内部随时能用。这篇就把我实测过的部署全过程拆开讲，从环境准备、服务端启动、前端联调到踩坑复盘，按步骤来基本能一次跑通。适合前后端开发、测试同学，也适合想研究开源项目源码的读者。
1. 为什么非要在本地部署一套RAP2
1.1 接口文档与Mock数据的传统痛点
做过前后端并行开发的人应该都有同感：接口还没写好，前端要等；文档放在共享表格里，后端改了字段没人同步；Mock数据各写各的，接口一多容易对不上。我见过最夸张的情况是前端同事自己写了三套不同的Mock服务器，结果联调时发现和真实接口结构完全不一样，返工成本极高。
RAP2这类工具的核心价值，就是把这些分散的东西收拢到一个系统里：接口定义、请求参数、响应结构、Mock模板、在线文档、团队协作全部集中管理。后端定义一次，前端同步看到，双方基于同一份数据对话，联调自然顺畅很多。
1.2 本地实例比公共服务更有优势
其实现在也有不少在线的接口管理平台，但本地部署RAP2有几个公共平台比不了的优势：
- 数据完全在自己掌控中，不依赖外部服务的可用性。
- 公司内部网络隔离、无法访问外部域名时，本地实例几乎是唯一选择。
- 可以离线使用，即使断网也能继续定义接口、生成Mock数据。
- 源码在手上，遇到不满意的地方可以直接改，比如扩展Mock语法、加自定义字段。
- 本地启动一套环境，是深入理解RAP2内部机制最快的方式。
尤其最后一点，我建议至少跑一次从零部署，比只看文档印象深得多。你会真正理解delos、dolores、MySQL、Redis这几块是怎么咬合在一起的。
1.3 本文适合谁来读
如果你属于下面任何一种情况，这篇文章可以直接照着操作：
- 前端开发：需要稳定接口文档和Mock数据，不想自己维护零散的Mock脚本。
- 后端开发：想把接口定义规范化，减少“改了接口忘记同步文档”的问题。
- 测试同学：做接口测试、造数据时需要一个可控环境。
- 开源爱好者：想读RAP2源码，本地起一套环境方便调试。
前置要求比较低：会基本的命令行操作，能看懂简单的JavaScript配置片段就够。数据库、Redis这些只要会安装启动就行，不用深究原理。
2. 部署前先搞懂RAP2的分层结构与依赖关系
2.1 delos与dolores：后端与前端的分工
RAP2不是单个程序，它由两个独立子工程组成。第一次接触的人很容易搞混，我先把分工说清楚。
rap2-delos：后端服务。负责注册登录、项目增删改查、接口定义保存、Mock数据生成、权限管理等所有业务逻辑。它连接MySQL做持久化存储，连接Redis做会话管理。rap2-dolores：前端应用。就是我们看到的操作界面，用户在浏览器里点来点去，它通过HTTP请求调用delos提供的接口，再把界面渲染出来。
一句话概括：delos是大脑加数据库，dolores是脸面加操作台。两者完全分离，意味着你可以只启动后端，用curl直接测接口；也可以只改前端代码，不影响后端数据。
前端和后端之间是标准的HTTP API通信，没有WebSocket等特殊依赖，所以跨端调试、二次开发都比较直接。这也解释了为什么部署时需要同时管理两个进程。
2.2 本地部署必备的三件套
跑一套RAP2，除了两个子工程源码，还必须有三个基础组件：
| 组件 | 版本要求 | 作用 |
|---|---|---|
| Node.js | 建议LTS版本，14或16均可 | 运行delos后端、dolores的开发服务器 |
| MySQL | 5.7及以上 | 保存项目、接口、用户等业务数据 |
| Redis | 3.0及以上 | 保存用户登录会话 |
MySQL和Redis都是必须的，缺哪一个都会导致功能异常。我排过不少“为什么登录不上”的问题，最后发现就是Redis没启动。
2.3 本地端口规划与进程思路
部署前先看端口占用情况，避免启动时才发现冲突。
| 组件 | 默认端口 | 说明 |
|---|---|---|
| rap2-delos | 38080 | 后端API服务端口 |
| rap2-dolores | 38081 | 前端开发服务器端口 |
| MySQL | 3306 | 安装时默认端口 |
| Redis | 6379 | 安装时默认端口 |
本地开发时，习惯上同时开两个终端：一个跑delos，一个跑dolores。如果两个子工程不在同一台机器上，还要注意防火墙放行对应的38080和38081端口。端口其实可以在源码配置里改，但第一次部署建议先用默认值，跑通后再按需调整，减少变量。
3. 环境准备：版本选型与初始化细节
3.1 Node.js版本选择与常见坑
RAP2前后端都是Node.js生态，Node版本对齐很关键。太老的版本（比如8.x）跑新依赖会直接报语法错误；太新的版本（比如20+）又可能遇到某个旧依赖没跟上，导致编译失败。
我在本地用的方案是nvm，安装和使用都很简单。确定一个版本后：
nvm install 16 nvm use 16 node -v npm -v如果不想用nvm，直接装一个Node LTS版本也够用。重点提醒：不要用系统自带的过老版本，也不要盲目追求最新版。遇到node-sass编译类报错时，第一反应应该是检查Node版本，而不是反复重装依赖。实践中，Node 16搭配RAP2两个子工程的依赖树，基本没有编译问题。
3.2 MySQL初始化与账号授权
RAP2需要一个空数据库。先启动MySQL，然后创建库和专用账号。建议不要直接用root账号跑业务，免得权限过大。
CREATE DATABASE IF NOT EXISTS rap2 DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci; CREATE USER 'rap2'@'localhost' IDENTIFIED BY '这里换成你自己的密码'; GRANT ALL PRIVILEGES ON rap2.* TO 'rap2'@'localhost'; FLUSH PRIVILEGES;重点说一下字符集：RAP2的接口描述、字段注释里很可能有中文，接口文档里偶尔还会贴Emoji。utf8mb4是比较稳妥的选择，老式utf8在存四个字节的Emoji时会报数据截断错误。我第一次部署时为了省事用了默认字符集，结果写入一条带表情的接口描述直接报错，非常狼狈。
3.3 Redis的安装与启动
Redis在本地环境通常不需要复杂配置。安装完成后：
redis-cli ping返回PONG就说明服务在运行。如果改了Redis密码，后面配置delos时要把密码填进去。没有密码的话，配置里留空即可。另外，Redis的端口默认6379，如果被其他程序占用，可以临时换端口，但要记得在delos配置中保持一致。
很多初学同学容易忽略Redis，觉得“不就是个缓存吗”。实际上RAP2的会话机制强依赖它，Redis没启动时，登录接口要么报错，要么无限跳回登录页。这点等第6章的验收链路里会更明显。
4. 后端delos的部署步骤与配置解读
4.1 获取源码与安装依赖
后端工程是rap2-delos，从开源仓库拉取后，进入目录安装依赖：
git clone <你的delos仓库地址> cd rap2-delos npm install安装过程可能比较慢，遇到npm install卡住或编译报错时，可以先给npm配置一个镜像源，再重新安装。这是网络环境问题，和源码本身没有关系。
依赖装完后，先别急着启动，因为默认配置指向的服务地址大概率不是本地。除非你运气好，恰好有一台现成的MySQL和Redis在同一台机器、同账号密码。
4.2 数据库连接配置与本地环境变量
delos的配置目录里会有默认配置文件，一般叫config.default.js或config.js。真实项目里，我们通常新建一个config.local.js来覆盖默认值，这样不会污染公共配置。
下面是一个常见的本地配置片段。不同发行版的键名可能略有差异，你拉下来的源码里如果看到的是db、storage、sequelize这类字段，按照它的结构把连接信息替换成自己的即可：
// config.local.js module.exports = { port: 38080, db: { host: '127.0.0.1', port: 3306, username: 'rap2', password: '刚才设置的MySQL密码', database: 'rap2', }, redis: { host: '127.0.0.1', port: 6379, }, };这里有一个非常容易踩的坑，我必须单独说：config.local.js并不是在所有启动方式下都会被加载。如果你直接用npm start启动，底层默认会以production环境运行，这种时候本地配置可能完全不生效，delos仍然去连默认的公共服务地址，然后报错或者行为诡异。
正确做法是第一次部署用开发模式启动：
npm run dev开发模式下会加载本地配置，而且日志更详细，方便看数据库连接、路由挂载等信息。等彻底跑通，再考虑用进程守护工具正式托管。
4.3 启动、日志确认与接口自测
执行npm run dev之后，看到控制台出现类似started on 38080或server started的日志，说明后端进程已经起来。接着观察有没有建表日志。delos底层会用ORM自动同步表结构，首次启动会在MySQL里自动创建一批数据表，包括用户表、项目表、接口表等。
如果启动时报Unknown database，说明第3.2步的建库没成功或库名不一致；如果报connect ECONNREFUSED，基本是MySQL或Redis端口不对。这些都属于环境问题，不用慌，按报错内容反查即可。
一个快速的冒烟测试：
curl http://127.0.0.1:38080/如果返回一段JSON或者HTTP错误码都算正常，说明服务在监听。根路径返回404对于后端框架来说也不奇怪，后面跑通注册登录才是真正的验证。到这里，后端部分就绪。
5. 前端dolores的构建与联调配置
5.1 前端工程初始化
前端工程是rap2-dolores，同样从仓库拉取后安装依赖：
git clone <你的dolores仓库地址> cd rap2-dolores npm install前端依赖通常比后端多，安装时间更久。安装完成后，先不要着急改代码，直接执行：
npm start默认会在38081端口起一个开发服务器。浏览器打开http://127.0.0.1:38081，大概率能看到登录页。但此时登录肯定是失败的，因为前端还不知道去哪里找后端。
5.2 把前端API指向本地后端
dolores源码里会配置后端API地址，常见位置是src/config/config.js，也有版本通过Webpack的proxy配置转发请求。你可以直接在项目目录里搜一下关键词：
grep -r "38080\|apiUrl\|proxy" src/ config/找到API地址配置后，把它改成http://127.0.0.1:38080。如果用的是webpack proxy方案，就把代理目标指向http://127.0.0.1:38080。原理很简单：前端页面发出请求时，开发服务器会把请求转发给delos，避免跨域问题，同时让浏览器看到的还是同源地址。
修改完成后，开发服务器一般会自动热更新。如果没生效，手动重启一下npm start。
5.3 开发模式与生产构建的差异
本地调试建议一直用npm start，好处是前端代码改了立即生效，配合React的调试工具体验很好。但要注意，开发服务器本身不做性能优化，只适合本机或小范围联调。
如果团队想在内网共用一个入口，就需要生产构建：
npm run build构建产物会输出到dist或类似目录。你可以用Nginx托管这些静态文件，同时把/api路径反向代理到delos的38080端口。这种方案的性能和稳定性远好于开发服务器，但配置更复杂，我第一次部署时没有直接上，而是先本地跑通功能，后面再考虑正式托管。
生产构建前，还要记得确认前端代码里的API地址已经被改成生产环境能访问到的后端地址。很多人本地跑得好好的，一build之后发现页面能打开、数据加载不出来，十有八九是API地址没改。
6. 登录、建接口、拿Mock：一条完整的验收链路
6.1 注册登录背后的会话机制
前后端都启动后，打开http://127.0.0.1:38081，首次使用先注册一个账号。注册成功后，delos会把用户信息写入MySQL，同时基于Redis创建一个会话。之后每次请求都会带上会话凭证，后端从Redis读取用户状态。
为什么强调Redis？因为如果Redis没启动，登录时后端可能报错，或者登录成功后刷新页面又变回未登录状态。反过来，如果MySQL建表有问题，注册时就会直接报错。所以“注册登录”这个简单动作，其实是三套组件协作的第一个完整验证。看到能正常注册并保持登录状态，说明delos、MySQL、Redis这条链路是通的。
6.2 创建接口、配置Mock模板并取回数据
登录后，新建一个项目，然后在项目里添加接口。需要填写的核心信息包括接口路径、请求方法、请求参数、返回数据模板等。
Mock模板支持JSON，也支持类似Mock.js风格的动态语法。比如想生成5条列表数据，可以写：
{ "code": 0, "data": { "list|5": [ { "id|+1": 1, "name": "示例数据" } ] } }保存接口后，界面上通常会出现“复制Mock地址”之类的按钮。Mock地址的格式一般是：
http://127.0.0.1:38080/mock/{接口ID}用curl直接验证：
curl http://127.0.0.1:38080/mock/12如果返回的是符合模板的JSON数据，说明Mock能力已经生效。这个动作是整篇部署流程的关键验收点：前端不依赖任何真实后端，就能拿到结构稳定的Mock数据，这是RAP2最核心的价值。
6.3 团队协作中本地实例的用法
本地RAP2跑通后，如果想让同局域网的人一起用，最简单的方式是直接提供本机IP：
http://你的局域网IP:38081对方打开页面后，注册自己的账号，就能创建项目、邀请队友协作。要注意两点：一是本机防火墙需要放行38081和38080两个端口；二是delos的配置里如果绑定了127.0.0.1，外部机器是访问不到的，需要改成0.0.0.0。本地开发时为了安全可以只绑定本机，一旦要团队共用，改绑定后记得重启后端。
另外一个实用技巧：多个项目组同时用同一套RAP2时，数据都在同一份MySQL里，建议按“团队”或“项目”维度做好目录分隔，避免接口重名互相干扰。
7. 本地部署踩坑复盘：从现象到根因
7.1 数据库相关：建表失败、权限不足、字符集乱码
本地部署遇到数据库问题最多。常见报错有几种：
Access denied for user 'rap2'@'localhost'：账号权限没给够，回到第3.2步重新执行授权命令。Unknown database 'rap2'：数据库没建成功，或者连接配置里的库名和实际库名不一致。- 中文乱码：创建数据库时没有指定
utf8mb4，建议删掉重建，或者手动修改字符集。 - 时区导致的时间字段报错：可以在MySQL连接参数里加上
timezone配置，或者修改数据库全局时区。
排查顺序建议是：先看delos启动日志，再确认MySQL是否在运行，最后用客户端工具连接数据库查看表结构。大部分问题在日志里都有直接线索。
这里还衍生出一个经验：不要在还没启动delos的时候就急着导入数据。先用空库跑一次自动建表，再手动检查表是否齐全，比直接导入来历不明的SQL更可控。
7.2 前端白屏、接口502与登录态丢失
前端白屏和“页面能开但数据加载不出来”是两个层面。页面能开说明dolores开发服务器正常；数据加载失败就要查后端链路。
我总结的排查顺序是：
- 先看delos终端日志，有没有接口报错。
- 再确认Redis是否在运行，
redis-cli ping。 - 用curl直接请求delos的接口，比如
curl http://127.0.0.1:38080/，看后端本身通不通。 - 最后检查前端里的API地址或代理配置，确认指向的是
38080而不是其他端口。
有一种很隐蔽的情况：delos是用NODE_ENV=production启动的，导致config.local.js没被加载，连的是默认数据库或者默认Redis。表面看是“服务起来了，数据不对”，实际是环境变量导致配置没生效。遇到这种“逻辑上说不通”的问题，优先检查启动命令和NODE_ENV。
端口占用也是高频情况。直接去看端口状态：
lsof -i :38080 lsof -i :38081如果端口被上一个进程占住，要么停掉旧进程，要么在配置里换新端口。开发模式下如果用了进程守护，还要注意关闭旧服务实例，否则会出现端口冲突，表现为“改完配置重启还是不生效”。
7.3 依赖安装慢与构建内存溢出
依赖阶段的问题处理不好，会让人心态爆炸。npm install慢，大多是网络原因，配置镜像源后通常能解决。如果某个编译型模块（比如sass相关）失败，很可能是Node版本不兼容。我的习惯是先用nvm切换长期支持版本，再重新执行安装。
构建前端时遇到过JavaScript heap out of memory，这是Node默认内存上限不够用。给构建命令加上参数即可：
NODE_OPTIONS=--max-old-space-size=4096 npm run build最后提醒一点：不要一边跑npm run dev一边改配置，改完环境变量或端口后，必须重启对应进程。热更新只管代码，不管进程环境。
我自己现在的习惯是，把MySQL、Redis的启动命令，加上前后端的启动命令，全部写进一个start.sh脚本，一条命令拉起整个环境。踩过几轮坑之后你会发现，RAP2本地部署本身不难，难的永远是那些“配置没生效”“端口被占”“环境变量不一致”的小细节。希望这篇过程记录能帮你少走几步弯路。
