211 lines
6.7 KiB
Markdown
211 lines
6.7 KiB
Markdown
# 部署指南 (Deployment Guide)
|
||
|
||
本指南将指导您将应用部署到已安装 iPanel/宝塔面板 和 Node.js 环境的 Linux 服务器上。
|
||
|
||
## 1. 准备工作
|
||
|
||
### 启用 Standalone 模式 (已自动配置)
|
||
为了减小服务器上的文件体积，我们已经在 `next.config.ts` 中启用了 `output: 'standalone'` 模式。这会创建一个包含所有必要依赖的精简构建包。
|
||
|
||
### 检查环境
|
||
确保您的服务器已安装：
|
||
- **Node.js**: 版本需 >= 18.0.0 (推荐 v20 LTS)
|
||
- **Nginx**: 用于反向代理
|
||
- **PM2**: 用于进程守护 (通常面板可以一键安装，或通过 `npm install -g pm2` 安装)
|
||
- **Database**: 您的代码目前使用 SQLite (本地文件)，部署非常简单。
|
||
|
||
## 2. 构建项目
|
||
|
||
在**本地电脑**上执行构建命令：
|
||
|
||
```bash
|
||
# 1. 安装依赖 (仅当添加了新包时需要)
|
||
npm install
|
||
|
||
# 2. 生成 Prisma 客户端 (仅当修改了数据库结构时需要)
|
||
npx prisma generate
|
||
|
||
# 3. 构建项目
|
||
npm run build
|
||
```
|
||
|
||
构建完成后，您会看到一个 `.next` 文件夹。
|
||
|
||
## 3. 打包发布 (推荐方式)
|
||
|
||
我们已经将繁琐的文件复制步骤自动化了。请按照以下“标准流程”进行部署：
|
||
|
||
### 3.1 本地构建 & 打包
|
||
|
||
1. **构建**:
|
||
```bash
|
||
npm run build
|
||
```
|
||
|
||
2. **打包** (运行自动化脚本):
|
||
在 PowerShell 中执行：
|
||
```powershell
|
||
./scripts/build-dockerapp.ps1
|
||
```
|
||
*这个脚本会自动将 `standalone`, `static`, `public`, `prisma`, `docker-compose.yml` 等所有必要文件整理到项目根目录下的 **`dockerapp`** 文件夹中。*
|
||
|
||
### 3.2 上传 & 部署
|
||
|
||
1. **上传**:
|
||
将整个 **`dockerapp`** 文件夹上传到服务器（例如 `/www/wwwroot/wojide/dockerapp`）。
|
||
|
||
2. **启动**:
|
||
进入服务器上的该目录，运行 Docker Compose：
|
||
```bash
|
||
cd dockerapp
|
||
docker-compose up -d --build
|
||
```
|
||
|
||
此方式会自动使用包内的 `Dockerfile` 和 `docker-compose.yml` 构建并启动服务，无需再手动配置 Nginx 或 PM2（Docker 会处理端口映射，通常映射到 3001 或您配置的端口）。
|
||
|
||
**目录结构说明 (`dockerapp` 文件夹内)**:
|
||
```text
|
||
dockerapp/
|
||
├── .next/ <-- 包含 static 和 standalone/server
|
||
├── node_modules/ <-- 最小化依赖
|
||
├── public/ <-- 静态资源
|
||
├── prisma/ <-- 数据库结构
|
||
├── Dockerfile <-- 构建脚本
|
||
├── docker-compose.yml <-- 编排脚本
|
||
└── ...
|
||
```
|
||
## 4. 1Panel 面板配置指南 (图形化界面)
|
||
|
||
根据您提供的 1Panel 创建运行环境截图，请按以下方式填写：
|
||
|
||
- **名称**: `wojide` (或任意您喜欢的名字)
|
||
- **应用**: `Node.js` (版本保持默认或选择 LTS 版本)
|
||
- **项目目录**: 选择您在第 3 步上传文件的目录 (例如 `/www/wwwroot/wojide`)
|
||
- **启动命令**:
|
||
- **开启 [自定义启动命令] 开关** (非常重要!)
|
||
- 输入命令: `node server.js`
|
||
- *解释: Standalone 模式下直接运行 server.js 即可，不需要 npm run start。*
|
||
- **包管理器**: `npm`
|
||
- **端口**: 如果有端口设置，请输入 `3000`
|
||
|
||
点击确认创建后，容器会自动启动。
|
||
|
||
## 5. 服务器端配置 (数据库迁移)
|
||
|
||
登录服务器终端 (SSH) 或使用面板的终端功能。
|
||
|
||
### 5.1 数据库迁移
|
||
进入网站目录并运行迁移，确保 `dev.db` 存在：
|
||
|
||
```bash
|
||
### 5.1 数据库迁移
|
||
进入网站目录并运行迁移，确保 `dev.db` 存在：
|
||
|
||
**情况 A: 直接安装的 Node 环境 (宝塔默认)**
|
||
```bash
|
||
cd /www/wwwroot/wojide
|
||
npx prisma migrate deploy
|
||
```
|
||
|
||
**情况 B: Docker 部署 (1Panel / 容器化)**
|
||
|
||
即使文件在宿主机上，Docker 容器也能通过“挂载”访问它们。您只需**进入容器**并找到那个挂载目录。
|
||
|
||
1. **确定容器**: 在 1Panel 找到您的应用容器 ID。
|
||
2. **进入容器并运行**:
|
||
|
||
```bash
|
||
# 1. 登录容器
|
||
docker exec -it <container_id> sh
|
||
|
||
# 2. 寻找项目目录 (关键步骤!)
|
||
# 在 1Panel 中，网站目录通常也会挂载到容器内的相同路径，或者 /app 目录。
|
||
# 尝试进入：
|
||
cd /www/wwwroot/wojide
|
||
# 或者 ls /app 看看是否有文件
|
||
|
||
# 3. 确认你在正确的目录下 (应该能看到 prisma 文件夹)
|
||
ls
|
||
|
||
# 4. 运行迁移 (更稳妥的方式: 先全局安装指定版本)
|
||
# 先安装 CLI 工具
|
||
npm install -g prisma@5.10.2
|
||
|
||
# 然后运行迁移
|
||
prisma migrate deploy
|
||
|
||
# 5. 退出
|
||
exit
|
||
```
|
||
```
|
||
|
||
### 5.2 启动服务
|
||
|
||
使用 PM2 启动项目：
|
||
|
||
```bash
|
||
# 启动
|
||
pm2 start server.js --name "wojide-app"
|
||
|
||
# 查看状态
|
||
pm2 status
|
||
|
||
# 如果报错，查看日志
|
||
pm2 logs wojide-app
|
||
```
|
||
|
||
此时，项目应该运行在 `http://localhost:3000`。
|
||
|
||
## 6. 初始化配置 (重要!)
|
||
|
||
首次部署后，数据库是空的，还没有设置密码。
|
||
您需要手动调用一次初始化接口来创建默认密码 (`admin`)。
|
||
|
||
**方法 A: 使用 Curl (在服务器终端)**
|
||
```bash
|
||
curl -X POST http://localhost:3000/api/settings/init
|
||
```
|
||
如果成功，会返回 `Initialized default settings`。
|
||
|
||
**方法 B: 使用浏览器控制台**
|
||
如果不方便用 Curl，可以在您的电脑浏览器打开网站登录页，按 `F12` 打开控制台，输入以下代码并回车：
|
||
```js
|
||
fetch('/api/settings/init', { method: 'POST' }).then(r=>r.json()).then(console.log)
|
||
```
|
||
|
||
初始化成功后，您可以使用默认密码 **`admin`** 登录。
|
||
|
||
## 7. 配置 Nginx 反向代理 (通过面板)
|
||
|
||
在面板中找到您的网站设置 -> **反向代理 (Reverse Proxy)**。
|
||
|
||
- **代理名称**: NextJS
|
||
- **目标 URL**: `http://127.0.0.1:3000`
|
||
- **发送域名**: `$host`
|
||
|
||
保存后，您应该可以通过域名访问您的网站了。
|
||
|
||
## 8. 后续更新 (代码修改后)
|
||
|
||
当您修改了代码并想要更新服务器版本时：
|
||
|
||
1. **本地构建**: 运行 `npm run build`。
|
||
2. **上传覆盖**:
|
||
- 上传 `.next/standalone` 中的内容覆盖服务器对应文件。
|
||
- 上传 `.next/static` 覆盖服务器上的 `.next/static`。
|
||
3. **重启服务**:
|
||
- 在 1Panel 容器列表中，点击该容器的 **“重启”** 按钮。
|
||
|
||
**注意**: 如果您修改了数据库结构 (`schema.prisma`)，请在重启前参考第 5.1 步进入容器运行 `npx prisma migrate deploy`。
|
||
|
||
## 常见问题
|
||
|
||
- **样式丢失?**
|
||
请检查步骤 3/4，确保 `.next/static` 文件夹已正确上传到服务器的 `.next/static` 路径。Standalone 模式默认不包含静态资源，需要手动复制。
|
||
|
||
- **数据库报错?**
|
||
确保 `.env` 文件中的 `DATABASE_URL` 路径正确。对于 SQLite，建议使用绝对路径，例如 `file:/www/wwwroot/your-website/prisma/dev.db`。
|
||
|
||
- **权限问题?**
|
||
确保网站目录的所有者是运行 Nginx/Node 的用户 (通常是 `www` 或 `root`，视配置而定)。
|