library-picturebook-activity/docs/deployment/backend-deployment.md

后端部署文档

一、本地打包

1. 环境准备

cd backend

# 删除 pnpm 的 node_modules（避免软链接问题）
rm -rf node_modules

# 用 npm 安装依赖
npm install

# 构建项目
pnpm build

2. 打包命令

# 测试环境
bash scripts/compress.sh --env test --version 1.0.0 -n

# 生产环境
bash scripts/compress.sh --env production --version 1.0.0 -n

生成文件：competition-management-service-{env}-{version}.tgz

3. 打包注意事项

问题	原因	解决方案
软链接失效	pnpm 使用软链接管理依赖	打包前用 npm install 替代 pnpm install
logs 模块缺失	打包脚本排除了 logs 目录	修改 compress.sh 中 "logs" 为 "./logs"
uuid 版本问题	uuid v9+ 是 ESM 模块	安装 uuid@8.3.2

---

二、服务器部署

1. 上传并解压

# 本地上传
scp competition-management-service-test-1.0.0.tgz root@服务器IP:/data/web-servers/

# 服务器解压
cd /data/web-servers
tar -xzf competition-management-service-test-1.0.0.tgz
cd competition-management-service

2. 配置环境变量

vim .env

修改数据库连接：

DATABASE_URL="mysql://用户名:密码@数据库地址:端口/数据库名"

示例（腾讯云数据库）：

DATABASE_URL="mysql://root:password@gz-cdb-xxx.sql.tencentcdb.com:20704/db_competition_management"

3. 生成 Prisma Client

# 如果遇到 SSL 证书问题
export NODE_TLS_REJECT_UNAUTHORIZED=0

npx prisma generate

4. 创建数据库表

npx prisma db push

5. 启动服务

# 使用 PM2 启动
pm2 start dist/src/main.js --name competition-api-test

# 保存进程列表
pm2 save

# 设置开机自启
pm2 startup

6. 验证服务

# 查看状态
pm2 status

# 查看日志
pm2 logs competition-api-test

# 测试接口
curl -X POST http://localhost:3234/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"123456"}'

---

三、常见问题

1. prisma generate 报 SSL 证书错误

Error: request to https://binaries.prisma.sh/... failed, reason: unable to get local issuer certificate

解决：

export NODE_TLS_REJECT_UNAUTHORIZED=0
npx prisma generate

2. pm2: command not found

原因：/usr/local/bin 不在 PATH 中

解决：

export PATH=$PATH:/usr/local/bin
echo 'export PATH=$PATH:/usr/local/bin' >> ~/.bashrc
source ~/.bashrc

3. MODULE_NOT_FOUND: ./logs/logs.module

原因：打包脚本排除了 logs 目录

解决：修改 compress.sh 第 93 行：

# 修改前
"logs"
# 修改后
"./logs"

4. ERR_REQUIRE_ESM: uuid

原因：uuid v9+ 是 ESM 模块，不支持 CommonJS

解决：

npm install uuid@8.3.2

5. 数据库认证失败

PrismaClientInitializationError: Authentication failed against database server

解决：检查 .env 中 DATABASE_URL 的用户名、密码、地址是否正确

6. 服务启动后无法访问

原因：

• 防火墙未开放端口
• 云服务器安全组未配置

解决：

# 开放防火墙端口
firewall-cmd --permanent --add-port=3234/tcp
firewall-cmd --reload

腾讯云控制台 → 安全组 → 添加入站规则（TCP 3234）

---

四、PM2 常用命令

pm2 start dist/src/main.js --name app-name  # 启动
pm2 stop app-name                            # 停止
pm2 restart app-name                         # 重启
pm2 delete app-name                          # 删除
pm2 status                                   # 查看状态
pm2 logs app-name                            # 查看日志
pm2 logs app-name --lines 100                # 查看最近100行日志
pm2 save                                     # 保存进程列表
pm2 startup                                  # 设置开机自启

---

五、数据初始化

方式1：本地初始化后导出导入

本地操作：

cd backend
pnpm init:super-tenant
pnpm init:admin
pnpm init:menus
pnpm init:roles:all

# 导出数据
mysqldump -u root db_competition_management > init_data.sql

导入到云数据库（使用 DBeaver）：

1. 连接腾讯云数据库
2. 执行 SET FOREIGN_KEY_CHECKS = 0;
3. 执行 SQL 文件
4. 执行 SET FOREIGN_KEY_CHECKS = 1;

方式2：DBeaver 数据传输

1. 连接本地数据库和云数据库
2. 选中本地数据库所有表
3. 右键 → 导出数据 → 数据库表
4. 选择云数据库作为目标
5. 执行传输

---

六、目录结构

/data/web-servers/competition-management-service/
├── dist/                 # 编译后的代码
│   └── src/
│       └── main.js       # 入口文件
├── node_modules/         # 依赖
├── prisma/               # Prisma schema
├── .env                  # 环境配置
├── .env.test             # 测试环境配置
├── .env.production       # 生产环境配置
├── ecosystem.config.js   # PM2 配置
└── package.json