后端服务部署与配置

服务器的部署与AI的API配置

私有化部署说明

本工具支持用户私有化部署后端服务和自定义AI模型，下面是部署过程，供需要用户配置参考。部署前，你已经获取了后端程序。

部署前的准备

服务器配置要求

硬件配置

最低配置	推荐配置
- CPU: 2核	- CPU: 4核
- 内存: 2GB	- 内存: 4GB
- 磁盘: 10GB	- 磁盘: 20GB
- 系统: Ubuntu 20.04+ / CentOS 7+ / Windows Server 2016+	- 系统: Ubuntu 20.04+ / CentOS 7+ / Windows Server 2016+

软件环境要求

Linux	Windows
- Node.js 20+ 或 Docker 20.10+	- Node.js 20+ 或 Docker Desktop

本教程环境硬件配置为2c2g ，系统：Ubuntu 24.04 LTS。

生成配置密钥

• 在部署前，生成三个随机密钥并保存，后续配置需要

# 生成 ENCRYPTION_KEY（32字符）
node -e "console.log(require('crypto').randomBytes(16).toString('hex'))"
# 输出示例: 1849b61d856c26a77f50af9948213482
# 生成 JWT_SECRET（Base64格式）
node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"
# 输出示例: 6Brt+Fjq6J3TGptEiRSBzcDyFxDG+bof/f9vN1vjL5k=
# 生成 JWT_REFRESH_SECRET（再生成一个不同的）
node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"
# 输出示例: kLPhyTPtdFPkYv2zMNeYvo5K6YLKPAIN/ZxOpEXLCtw=

  Linux PM2源码部署

步骤一：NODEJS和PM2安装

NODEJS安装

# 1.Ubuntu/Debian:
# 安装 Node.js 20.x
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

# 验证安装
node --version  # 应显示 v20.x.x
npm --version   # 应显示 10.x.x

# 2.CentOS/RHEL:

# 安装 Node.js 20.x
curl -fsSL https://rpm.nodesource.com/setup_20.x | sudo bash -
sudo yum install -y nodejs

# 验证安装
node --version
npm --version

PM2安装

# 全局安装 PM2
sudo npm install -g pm2

# 验证安装
pm2 --version

步骤二：后端项目代码上传到服务器

如果你的服务器安装了宝塔面板或者1panel等管理面板，直接上传解压即可。我这里未安装，所以用命令上传演示。

# 创建项目目录（根据自己实际创建）
sudo mkdir -p /www/hegu-api #你期望的项目目录
cd /www/ hegu-api
# 上传到服务器
scp D:\heguzai\hegu-api.zip root@你的ip地址:/www/hegu-api
# 在服务器上解压
cd /www/hegu-api
unzip hegu-api.zip

步骤三： 安装依赖

npm install --omit=dev # 按装生产依赖

步骤四：配置环境变量

# 复制示例配置
cp .env.example .env
# 编辑配置文件
nano .env
# 保存并退出（Ctrl+O, Enter, Ctrl+X）

步骤五：生成 Prisma 客户端

# 生成 Prisma 客户端
npx prisma generate

# 输出示例

Prisma schema loaded from prisma/schema.prisma.
✔ Generated Prisma Client (7.2.0) to ./src/generated/prisma in 131ms

步骤六：初始化数据库

# 创建数据目录
mkdir -p data logs
# 推送数据库 schema
npx prisma db push
# 验证数据库创建
ls -lh data/database.db

# 输出示例：
✅ 成功标志：
SQLite database database.db created at file:./data/database.db
🚀  Your database is now in sync with your Prisma schema. Done in 82ms

步骤七：使用 PM2 启动服务和设置

# 启动应用
pm2 start npm --name hegu-api -- start
# 查看状态
pm2 status
# 查看日志
pm2 logs excel-api --lines 30
✅ 成功标志：
0|excel-ap | 🚀 服务器启动成功
0|excel-ap | 📡 端口: 3000
0|excel-ap | 🌍 环境: production
0|excel-ap | 🔗 健康检查: http://localhost:3000/health

• 设置开机自启

# 保存 PM2 进程列表
pm2 save
# 生成启动脚本
pm2 startup
# 按照输出的提示执行命令，类似：
# sudo env PATH=$PATH:/usr/bin pm2 startup systemd -u root --hp /root

• 验证部署

# 本地测试
curl http://localhost:3000/health
# 应该返回：
# {" {"success":true,"status":"ok","message":"hegu-api"..."}
# 查看进程状态
pm2 status
# 应该显示 status: online

提示： 可以选择清理devDependencies以节省空间

npm prune --production

步骤八：数据库初始化

• 运行种子数据： 种子数据会创建：管理员账号、系统配置

# 运行种子脚本
npm run db:seed
# 或直接运行
tsx src/scripts/seed.ts
# ✅ 成功标志：
✅ 创建admin管理员账号:
   用户名: admin
   密码: admin123
   权限: 完整版数据库
   强制修改密码: 是
⚠️  密码已保存到以下文件:
   credentials/latest-admin-credentials.txt
   credentials/admin-credentials-20251227-xxxxx.txt
# 查看默认管理员密码
# 方式 1: 查看凭证文件
cat credentials/latest-admin-credentials.txt
# 方式 2: 查看种子脚本
cat src/scripts/seed.ts | grep -A 5 "admin"
# 方式 3: 查看数据库
sqlite3 data/database.db "SELECT email, username, role FROM users WHERE role='admin';"
# 默认账号信息：
- 用户名：`admin`
- 邮箱：`admin@system.local`
- 密码：`admin123`
- 首次登录：需要强制修改密码
### 重置管理员密码
# 使用重置脚本
npm run reset-admin-password
# 或直接运行
tsx src/scripts/reset-admin-password.ts
### 运行种子数据

至此，Linux源码部署演示完毕

  Windows环境源码部署简述

windows部署说明

Windows平台部署基本和Linux部署方法一致，支持Windows + PM2和Windows + NSSM部署，下面以Windows + PM2为例做简要说明。

步骤 1: 安装 Node.js

1. 下载：https://nodejs.org/
2. 安装 LTS 版本（20.x）
3. 验证：打开 PowerShell，运行 node --version

步骤 2: 安装 PM2

# 以管理员身份运行 PowerShell
npm install -g pm2
npm install -g pm2-windows-startup
# 配置开机自启
pm2-startup install

步骤 3: 部署项目

# 解压项目到 C:\hegu-api
cd C:\hegu-api
# 安装依赖
npm install
# 配置 .env（复制 .env.example 并修改）
# 注意：Windows 路径使用正斜杠
# DATABASE_URL="file:C:/ hegu-api/data/database.db"
# 生成 Prisma 客户端
npx prisma generate
# 初始化数据库
npx prisma db push
# 启动服务
pm2 start npm --name hegu-api -- start
# 初始化数据库：参考Linux部署方案

至此，windows源码部署说明完毕

  docker部署(推荐)

步骤一：安装docker（以Linux为例，Windows版本查看官网文档）

• Ubuntu/Debian:

# 安装 Docker
curl -fsSL https://get.docker.com | sh
# 启动 Docker
sudo systemctl start docker
sudo systemctl enable docker
# 验证安装
docker --version
docker-compose --version

• CentOS/RHEL:

# 安装 Docker
sudo yum install -y yum-utils
sudo yum-config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo
sudo yum install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin
# 启动 Docker
sudo systemctl start docker
sudo systemctl enable docker

步骤二：上传项目文件

# 上传压缩包后解压（PM2部署步骤二后端项目代码上传到服务器）
# 在服务器上解压
cd /www/hegu-api
unzip hegu-api.zip

步骤三：环境变量配置

# 复制并编辑 .env
cp .env.example .env
nano .env
# Docker 专用配置：.env
# ⚠️ 注意：Docker 使用绝对路径
DATABASE_URL="file:/app/data/database.db"
# 其他配置同 PM2 部署
JWT_SECRET="..."
JWT_REFRESH_SECRET="..."
ENCRYPTION_KEY="..."
DEEPSEEK_API_KEY="..."

步骤四：拉取环境镜像

# 拉取镜像
docker pull swr.cn-north-4.myhuaweicloud.com/ddn-k8s/docker.io/library/node:22-alpine
# 重命名镜像
docker tag  swr.cn-north-4.myhuaweicloud.com/ddn-k8s/docker.io/library/node:22-alpine  node:22-alpine
# 查看镜像
docker images
# 删除源镜像
docker rmi swr.cn-north-4.myhuaweicloud.com/ddn-k8s/docker.io/library/node:22-alpine

# 输出示例
root@iv-ydwauuh9fkqbxys3d8ie:/www/excel-assistant-server# docker pull swr.cn-north-4.myhuaweicloud.com/ddn-k8s/docker.io/library/node:22-alpine
22-alpine: Pulling from ddn-k8s/docker.io/library/node
f18232174bc9: Already exists
63786652eaff: Already exists
0c2b42acd277: Already exists
4509b69886a5: Already exists
Digest: sha256:a73e7081874832dc455788ba110e31d1278f2352c043e4191f34093d4d7da60e
Status: Downloaded newer image for swr.cn-north-……

步骤五：构建并启动

# 构建镜像并启动
docker-compose up -d --build
# 查看日志
docker-compose logs -f
# 查看容器状态
docker-compose ps

# ✅成功标志
[+] Running 2/2
 ✔  api                            Built
 ✔ Container excel-assistant-api  Started
# 输出示例

至此，docker部署完毕。