快速开始

本文面向首次启动商业版后端的研发人员，解决“如何在新环境中完整启动服务，并达到可联调状态”。

如果你是第一次接手项目，建议按本文顺序执行，不要跳过数据库和初始化步骤。

启动前置说明

当前后端不能只通过执行 pnpm start:dev 完成配置验证。它依赖：

• 数据库
• 环境变量
• Prisma Client
• 数据迁移
• 默认数据初始化

所以更稳妥的流程是：

1. 准备环境变量
2. 准备数据库
3. 执行初始化脚本
4. 补默认数据
5. 启动服务

环境要求

INFO

推荐环境

• Node.js 22
• pnpm 9
• PostgreSQL 16

第一步：准备环境变量

项目已经提供模板：

.env.default.example

开发环境建议至少准备：

• .env.development
• 可选 .env.development.local

如果你执行 pnpm setup:dev 时本地还没有 .env.development，脚本会自动从模板复制一份。

第二步：准备数据库

如果你本地用 Docker，最方便的方式是直接启动仓库自带 PostgreSQL：

docker compose up -d postgres

默认本地映射：

127.0.0.1:5432

第三步：执行开发环境初始化

pnpm setup:dev

这条命令会自动完成：

1. 安装依赖
2. 生成 Prisma Client
3. 执行 prisma migrate deploy
4. 构建项目
5. 自动补齐 .env.development

第四步：初始化默认数据

首次启动、空库启动或新环境启动时，建议继续执行：

pnpm seed:dev

这样可以得到一个具备登录、联调、菜单和角色权限基础数据的开发环境。

第五步：启动服务

pnpm start:dev

默认关键地址如下：

项目	默认地址
服务端口	13000
API 根路径	http://localhost:13000/api/v1
Swagger	http://localhost:13000/docs
Health	http://localhost:13000/api/health

第六步：做一次最小链路验证

建议至少验证下面 5 件事：

1. docs 能正常打开
2. health 正常返回
3. 登录接口能用
4. 用户信息接口能返回
5. 前端可以通过 13000 成功联调

推荐的检查顺序

1. 先检查服务是否起来

看：

• 启动日志
• health 地址
• Swagger 页面

2. 再检查数据库是否正常

确认：

• 迁移已执行
• 表结构已存在
• 默认数据已初始化

3. 最后检查前后端联调

重点看：

• 登录
• 刷新令牌
• 菜单
• 站点配置

常用命令

pnpm setup:dev
pnpm start:dev
pnpm build
pnpm seed:dev
pnpm prisma:generate
pnpm prisma:migrate:dev
pnpm prisma:migrate:deploy
pnpm test
pnpm test:e2e

开发前提交规范

如果你准备基于商业版后端继续做扩展开发或团队协作，建议先阅读 规范。

虽然这份规范文档是开源文档中的通用章节，但当前后端仓库本身已经接入了：

• ESLint
• Prettier
• Husky
• Lint-staged
• Commitizen

这些工具链是当前项目已经在使用的开发约束，建议在扩展开发开始前纳入团队流程。

最常见的启动问题

数据库连不上

优先检查：

• DATABASE_URL
• PostgreSQL 是否启动
• 用户名密码是否一致

Swagger 打不开

优先检查：

• 服务是否真的监听在 13000
• SWAGGER_ENABLED 是否关闭

前端登录失败

优先检查：

• 登录账号是否存在
• 管理员是否已初始化
• Cookie 和端口是否正确

检查清单

完成本页后，建议确认：

• health、Swagger、登录和用户信息接口均可访问。
• 数据库迁移已执行，默认角色、管理员、菜单和权限数据已初始化。
• 前端能通过 http://localhost:13000 完成登录、刷新令牌和菜单加载联调。