详细koa2+ts+prisma+swagger的后端项目部署（部署到宝塔面板）

概要

利用koa2+ts+prisma+swagger的完成的后端项目，在本地成功运行后部署到云服务器，选择了宝塔面板

整体架构流程

web框架: koa2 + ts
热更新：ts-node-dev + ts-node
orm：prisma
接口生成与调试：swagger
token生成：JSON Web Token（JWT）

技术名词解释

• Koa2：Koa2是一个基于Node.js的Web框架，它使用了ES6的语法和async/await特性，使得编写异步代码更加简单和优雅。Koa2的核心思想是中间件，它允许开发者将应用程序拆分成小的、可重用的部分，从而使得代码更加模块化和易于维护。Koa2还提供了一些常用的中间件，如路由、静态文件服务、错误处理等，使得开发者可以更加快速地构建Web应用程序。总的来说，Koa2是一个轻量级、灵活、易于扩展的Web框架，适合用于构建中小型的Web应用程序。
• ts-node-dev + ts-node：ts-node 是一个 TypeScript 执行引擎，能让我们在 Node.js 环境下直接运行 TypeScript 代码。

摘抄自 ts-node 官网： ts-node is a TypeScript execution engine and REPL for
Node.js. It JIT transforms TypeScript into JavaScript, enabling you to
directly execute TypeScript on Node.js without precompiling. This is
accomplished by hooking node’s module loading APIs, enabling it to be
used seamlessly alongside other Node.js tools and libraries.

• Prisma：Prisma是一个开源的数据库工具链项目，帮助开发人员更快地构建应用程序并减少错误，支持PostgreSQL、MySQL、MongoDB、SQL Server和SQLite。
• Swagger：Swagger是一个开放源代码软件框架，用于设计、构建、文档化和使用RESTful Web服务。它提供了一种规范的方式来描述和可视化API，使得开发人员能够更轻松地理解和使用接口。Swagger支持多种编程语言和框架，如Java、Python、Node.js等。
• JSON Web Token（JWT）：JSON Web Token（JWT）的作用是在客户端和服务器之间传递身份验证信息，并支持授权和信息交换。

技术细节

一，服务器的系统选择与宝塔面板的安装

服务器我选择的是移动云的免费服务器作为调试，服务器安装的系统为ubunto 22最高版本，因为centos 7.x无法安装node 18.x以上的高版本，本项目需要至少18.0.0的node版本，视情况而定。

宝塔面板的安装，连接服务器终端后，输入下面面命令进行安装

wget -O install.sh https://download.bt.cn/install/install_lts.sh && sudo bash install.sh ed8484bec

二，宝塔页面的部署

在软件安装页面可以安装，也可以一键部署

三，项目的部署

1.上传文件

首先将项目文件上传至

/www/wwwroot

路径之下，推荐用压缩包的方式上传，项目启动位置和项目上传的路径有关，如图

2.配置数据库

创建一个数据库，访问设置为所有ip，接着配置.env文件

双击打开，按照图片进行设置

3.添加node项目

注意，我在上传项目的时候上传了依赖文件，如果没有上传，请在项目目录下的终端运行

npm i

进行安装依赖。

在添加项目后启动的时候，如果遇到了报错

启动失败node-koa-templates@1.0.0 dev > ts-node-dev --respawn
–transpile-only src/app.ts sh: /www/wwwroot/node_modules/.bin/ts-node-dev: /bin/sh^M: bad
interpreter: No such file or directory

原因：
该问题通常是因为脚本的行结尾符导致的。在 Windows 上创建的文件使用 CRLF，而在 Unix/Linux 环境中需要 LF。

解决方法：
转换行结尾符： 使用 dos2unix 工具来转换行结尾符。在终端安装并运行：

sudo apt-get install dos2unix  //安装dos2unix 工具
dos2unix /www/wwwroot/node_modules/.bin/ts-node-dev

之后就可以成功启动项目了

4.运行后项目日志报错处理

在项目日志中如果报错以下内容

npm ERR! code EACCES
npm ERR! syscall mkdir
npm ERR! path/www/server/nodejs/cache/_cacache
npm ERR! errno -13
npm ERR! npm ERR! Your cache folder contains root-owned files, due to a bug in
npm ERR! previous versions of npm which has since been addressed.
npm ERR!
npm ERR! To permanently fix this problem, please run:
npm ERR! sudo chown -R 1000:1000 “/www/server/nodejs/cache”

npm ERR! Log files were not written due to an error writing to the directory: /www/server/nodejs/cache/_logs
npm ERR! You can rerun thecommand with --loglevel=verbose to see the logs in your terminal
[INFO] 00:44:23 ts-node-dev ver. 2.0.0 (using ts-node ver. 10.9.2,typescript ver. 5.3.3)
app started at address:http://localhost:3000 orhttp://192.168.0.2:3000
app started at address:https://localhost:3001 or https://192.168.0.2:3001
PrismaClientInitializationError: Prisma
Client could not locate the Query Engine for runtime “debian-openssl-3.0.x”.

第一个报错内容：

npm ERR! code EACCES
npm ERR! syscall mkdir
npm ERR! path/www/server/nodejs/cache/_cacache
npm ERR! errno -13
npm ERR! npm ERR! Your cache folder contains root-owned files, due to a bug in
npm ERR! previous versions of npm which has since been addressed.
npm ERR!
npm ERR! To permanently fix this problem, please run:
npm ERR! sudo chown -R 1000:1000 “/www/server/nodejs/cache”

原因：缓存文件夹权限问题
解决方法：在终端运行

sudo chown -R 1000:1000 "/www/server/nodejs/cache"

即可，此时如果报错

sudo: unable to resolve host name Name or service not known

请参考

https://blog.csdn.net/qq_42820307/article/details/141355655?spm=1001.2014.3001.5502

之后再次执行即可。

第二个报错内容

npm ERR! Log files were not written due to an error writing to the directory: /www/server/nodejs/cache/_logs
npm ERR! You can rerun thecommand with --loglevel=verbose to see the logs in your terminal
[INFO] 00:44:23 ts-node-dev ver. 2.0.0 (using ts-node ver. 10.9.2,typescript ver. 5.3.3)
app started at address:http://localhost:3000 orhttp://192.168.0.2:3000
app started at address:https://localhost:3001 or https://192.168.0.2:3001 PrismaClientInitializationError: Prisma
Client could not locate the Query Engine for runtime
“debian-openssl-3.0.x”.

原因：Prisma 配置问题
解决方法：
1.修改 schema.prisma 文件： 在 schema.prisma 文件的 generator 部分，添加 debian-openssl-3.0.x 到 binaryTargets：

generator client {
  provider = "prisma-client-js"
  binaryTargets = ["native", "debian-openssl-3.0.x"]
}

2.重新生成 Prisma Client： 运行以下命令重新生成 Prisma Client：

cd /www/wwwroot/src/prisma  //切换至prisma路径下，这里按照你的实际项目来
npx prisma generate  //在prisma路径终端下执行

5.使用域名进行访问

在这里我直接绑定了我的公网IP作为域名

配置app.ts

把这里的ip换成服务器的公网IP，记得运行后查看项目日志，查看启动成功的端口，需要在服务器安全组和宝塔面板进行放行，至此已经可以通过域名加上httpPort（设定的服务端口）进行访问，接下来配置swagger

swagger配置

url填入你的域名，具体的swagger接口配置请查看官方文档。

小结

如遇到其他问题请在评论区留言。