宝塔图形化部署教程

# 宝塔图形化部署教程

> &#128161; **提示**: 99% 操作都可以通过宝塔图形界面完成，仅需少量命令行

## 目录

1. [环境要求](#环境要求)
2. [Linux 宝塔部署（生产环境推荐）](#linux-宝塔部署生产环境推荐)
3. [Windows 宝塔部署（测试环境）](#windows-宝塔部署测试环境)
4. [常见问题](#常见问题)

---

## 环境要求

### 最低配置

| 组件 | 最低要求 | 推荐配置 |
|------|---------|---------|
| CPU | 2 核 | 4 核+ |
| 内存 | 4GB | 8GB+ |
| 磁盘 | 40GB | 100GB+ |
| 系统 | Linux/Windows | Linux (推荐) |

### 软件要求

- Node.js 24+
- PostgreSQL 15+
- pnpm 8+
- Nginx (反向代理)
- PM2 (进程管理)

---

## Linux 宝塔部署（生产环境推荐）

### 步骤 1: 宝塔面板安装

```bash
# CentOS
yum install -y wget && wget -O install.sh http://download.bt.cn/install/install_6.0.sh && sh install.sh

# Ubuntu
wget -O install.sh http://download.bt.cn/install/install-ubuntu_6.0.sh && sudo bash install.sh
```

安装完成后，浏览器访问 `http://服务器IP:8888` 进入宝塔面板

### 步骤 2: 软件环境安装（100% 图形化）

**宝塔面板 → 软件商店**：

1. 安装 Node.js 版本管理器
   - 搜索"Node.js"
   - 点击"安装"
   - 安装完成后，点击"设置"
   - 选择 Node.js 24.x 版本，点击"安装"

2. 安装 PostgreSQL 15
   - 搜索"PostgreSQL"
   - 选择 PostgreSQL 15，点击"安装"
   - 安装完成后，点击"设置"
   - 设置 root 密码（记下来，后面要用）

3. 安装 PM2 管理器
   - 搜索"PM2"
   - 点击"安装"

4. 安装 Nginx
   - 搜索"Nginx"
   - 点击"安装"（如果还没装）

### 步骤 3: 创建网站（100% 图形化）

**宝塔面板 → 网站 → 添加站点**：

1. 填写信息：
   - 域名：`yourdomain.com`（如果没有域名，先用服务器IP）
   - 根目录：`/www/wwwroot/your-project`（自动生成）
   - FTP：不创建
   - 数据库：不创建（后面单独建PostgreSQL）
   - PHP版本：纯静态

2. 点击"提交"创建网站

### 步骤 4: 上传代码（100% 图形化）

**方法1：使用宝塔 Git 插件（推荐）

1. 宝塔面板 → 软件商店 → 搜索"Git"
2. 安装 Git 插件
3. 宝塔面板 → 网站 → 点击你的网站 → Git
4. 填写 Git 仓库地址，点击"克隆"
5. 等待代码自动下载完成

**方法2：上传压缩包（最简单）

1. 本地把项目打包成 zip 格式
2. 宝塔面板 → 文件 → 进入 `/www/wwwroot/your-project`
3. 点击"上传"按钮
4. 选择本地的 zip 包，点击"开始上传"
5. 上传完成后，右键 zip 包 → 点击"解压"
6. 确保文件直接在网站根目录下（不要嵌套在子目录里）

### 步骤 5: 安装 pnpm（图形化 + 1条命令）

**宝塔面板 → 终端**：

1. 点击左侧"终端"菜单
2. 在终端中输入以下命令并回车：
```bash
npm install -g pnpm
```
3. 等待安装完成

> &#128161; 就这一条命令，后面都是图形化操作！

### 步骤 6: 安装依赖和构建（图形化脚本执行）

**宝塔面板 → 计划任务**：

1. 添加任务：
   - 任务类型：Shell 脚本
   - 任务名称：安装项目依赖
   - 执行周期：N分钟
   - 脚本内容：
```bash
cd /www/wwwroot/your-project
pnpm install
```
2. 点击"提交"
3. 点击"执行"立即运行一次
4. 等待执行完成后，可以在"日志"中查看结果

5. 再添加一个任务：
   - 任务类型：Shell 脚本
   - 任务名称：构建项目
   - 执行周期：N分钟
   - 脚本内容：
```bash
cd /www/wwwroot/your-project
pnpm build
```
6. 点击"提交"
7. 点击"执行"立即运行一次
8. 等待执行完成，查看日志确认构建成功

> ✅ 构建成功后，会在文件管理器中看到 `.next` 目录

### 步骤 7: 配置环境变量（100% 图形化）

**宝塔面板 → 文件 → 进入网站根目录**：

1. 找到 `.env.example` 文件
2. 右键文件 → 点击"复制"
3. 把复制的文件重命名为 `.env`（右键 → 重命名）
4. 右键 `.env` 文件 → 点击"编辑"
5. 修改以下配置项：
```env
NODE_ENV=production
DATABASE_URL=postgresql://postgres:你的数据库密码@localhost:5432/payroll_prod
NEXTAUTH_URL=https://yourdomain.com
```
6. 点击"保存"按钮

### 步骤 8: 创建 PostgreSQL 数据库（100% 图形化）

**宝塔面板 → 数据库**：

1. 点击"添加数据库"
2. 填写信息：
   - 数据库名：`payroll_prod`
   - 用户名：`payroll_user`
   - 密码：设置一个强密码（记下来）
3. 点击"提交"
4. 回到文件管理器，编辑 `.env` 文件
5. 更新 `DATABASE_URL` 为刚才创建的数据库信息

### 步骤 9: PM2 启动项目（100% 图形化）

**宝塔面板 → 软件商店 → PM2 管理器 → 设置**：

1. 点击"添加项目"
2. 填写项目信息：
   - 项目名称：`payroll`
   - 启动文件：点击"选择"，找到 `/www/wwwroot/your-project/node_modules/.bin/next`
   - 项目目录：点击"选择"，选择 `/www/wwwroot/your-project`
   - 启动参数：`start`
3. 点击"提交"
4. 在 PM2 项目列表中，看到状态显示为"在线"就成功了！
5. 可以点击"日志"查看运行日志

### 步骤 10: Nginx 反向代理配置（100% 图形化）

**宝塔面板 → 网站 → 点击你的网站 → 设置 → 配置文件**：

1. 删除原有的所有配置内容
2. 粘贴以下配置：
```nginx
server {
    listen 80;
    listen 443 ssl http2;
    server_name yourdomain.com;
    
    # SSL 证书配置（后面通过宝塔自动生成）
    
    location / {
        proxy_pass http://127.0.0.1:5000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
        
        proxy_connect_timeout 60s;
        proxy_send_timeout 60s;
        proxy_read_timeout 60s;
    }
}
```
3. 点击"保存"

### 步骤 11: SSL 证书配置（100% 图形化，推荐）

**宝塔面板 → 网站 → 点击你的网站 → 设置 → SSL**：

1. 选择"Let's Encrypt"标签
2. 勾选你的域名
3. 点击"申请"按钮
4. 等待几十秒，证书会自动申请和配置
5. 勾选"强制 HTTPS"选项

> ✅ 完成！现在通过 `https://yourdomain.com` 就可以访问网站了！

---

## Windows 宝塔部署（测试环境）

> &#128161; **提示**: Windows 宝塔同样以图形化操作为主

### 步骤 1: 宝塔面板安装

1. 访问 bt.cn 下载 Windows 版宝塔安装包
2. 运行安装程序，按提示完成安装
3. 安装完成后，浏览器访问 `http://localhost:8888` 进入宝塔面板

### 步骤 2: 软件环境安装（100% 图形化）

**宝塔面板 → 软件商店**：

1. 安装 Node.js 版本管理器
   - 搜索"Node.js"
   - 点击"安装"
   - 安装完成后，点击"设置"
   - 选择 Node.js 24.x 版本并安装

2. 安装 PostgreSQL 15（可选，用外部数据库可跳过）
   - 搜索"PostgreSQL"
   - 点击"安装"
   - 安装完成后设置 root 密码

3. 安装 PM2 管理器
   - 搜索"PM2"
   - 点击"安装"

### 步骤 3: 创建网站（100% 图形化）

**宝塔面板 → 网站 → 添加站点**：

1. 填写信息：
   - 域名：`test.yourdomain.com`（或用 `localhost`）
   - 根目录：`C:\bt_panel\wwwroot\your-project`
   - PHP版本：纯静态

2. 点击"提交"

### 步骤 4: 上传代码（100% 图形化）

1. 本地把项目打包成 zip 格式
2. 宝塔面板 → 文件 → 进入 `C:\bt_panel\wwwroot\your-project`
3. 点击"上传"，选择 zip 包上传
4. 上传完成后右键 zip → 点击"解压"
5. 确保文件在根目录下

### 步骤 5: 安装 pnpm（仅1条命令）

**宝塔面板 → 终端**：

1. 点击"终端"
2. 输入命令并回车：
```batch
npm install -g pnpm
```
3. 等待安装完成

### 步骤 6: 安装依赖和构建（图形化脚本执行）

**宝塔面板 → 计划任务**：

1. 添加任务：
   - 任务类型：Shell 脚本
   - 任务名称：安装依赖
   - 脚本内容：
```batch
cd C:\bt_panel\wwwroot\your-project
pnpm install
```
2. 提交后点击"执行"

3. 再添加任务：
   - 任务类型：Shell 脚本
   - 任务名称：构建项目
   - 脚本内容：
```batch
cd C:\bt_panel\wwwroot\your-project
pnpm build
```
4. 提交后点击"执行"

### 步骤 7: 配置环境变量（100% 图形化）

**宝塔面板 → 文件 → 网站根目录**：

1. 复制 `.env.example` 并重命名为 `.env`
2. 右键 `.env` → 编辑
3. 修改配置：
```env
NODE_ENV=production
DATABASE_URL=postgresql://postgres:密码@localhost:5432/payroll_test
NEXTAUTH_URL=http://test.yourdomain.com
```
4. 保存

### 步骤 8: PM2 启动项目（100% 图形化）

**宝塔面板 → 软件商店 → PM2 管理器 → 设置**：

1. 点击"添加项目"
2. 填写信息：
   - 项目名称：`payroll-test`
   - 启动文件：选择 `C:\bt_panel\wwwroot\your-project\node_modules\.bin\next`
   - 项目目录：选择网站根目录
   - 启动参数：`start`
3. 提交，看到"在线"状态即成功

### 步骤 9: Nginx 配置（100% 图形化）

**宝塔面板 → 网站 → 设置 → 配置文件**：

1. 粘贴配置：
```nginx
server {
    listen 80;
    server_name test.yourdomain.com;
    
    location / {
        proxy_pass http://127.0.0.1:5000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
    }
}
```
2. 保存

### Windows 特别注意事项

⚠️ **路径分隔符**: 代码中尽量用 `path.join()`
⚠️ **大小写**: 文件名统一小写，避免 Linux 部署出问题
⚠️ **端口占用**: 5000 被占用时可在 PM2 中改其他端口

---

## 常见问题

### Q1: pnpm install 失败

**A**（图形化操作）:
1. 宝塔面板 → 终端
2. 输入：`pnpm config set registry https://registry.npmmirror.com`
3. 然后重新在计划任务中执行安装

### Q2: 数据库连接失败

**A**（图形化检查）:
1. 宝塔面板 → 数据库 → 确认 PostgreSQL 状态"运行中"
2. 文件管理器 → 编辑 `.env` → 确认用户名密码正确
3. 宝塔面板 → 安全 → 确认 5432 端口已放行

### Q3: 构建失败

**A**（图形化操作）:
1. 软件商店 → Node.js → 确认版本 >= 24
2. 文件管理器 → 删除 `.next` 和 `node_modules` 文件夹
3. 计划任务中重新执行"安装依赖"和"构建项目"

### Q4: PM2 启动后无法访问

**A**（图形化检查）:
1. PM2 管理器 → 确认状态"在线"
2. PM2 管理器 → 点击"日志"查看错误
3. 宝塔面板 → 安全 → 确认 5000 端口已放行
4. 网站 → 设置 → 配置文件 → 确认 Nginx 配置正确

### Q5: Windows 性能较差

**A**: 正常！Windows 仅用于测试，生产请用 Linux 宝塔。

---

## 部署验证清单

- [ ] 宝塔面板已安装并能访问
- [ ] Node.js 24+ 已在软件商店安装
- [ ] PostgreSQL 15+ 已在软件商店安装
- [ ] PM2 管理器已在软件商店安装
- [ ] 网站已在宝塔创建
- [ ] 代码已上传（Git 或上传压缩包）
- [ ] pnpm 已通过终端安装（就1条命令）
- [ ] 依赖已通过计划任务安装
- [ ] 项目已通过计划任务构建
- [ ] 环境变量已通过文件管理器配置
- [ ] PostgreSQL 数据库已创建
- [ ] PM2 项目已添加并启动
- [ ] Nginx 配置已保存
- [ ] SSL 证书已申请（可选）
- [ ] 宝塔安全组已放行了必要端口
- [ ] 网站可正常访问
- [ ] 登录功能测试正常
- [ ] 数据库读写正常

---

## 联系支持

部署遇到问题？
- PM2 管理器 → 查看日志
- 查看项目 docs 目录
- 提交 Issue 到项目仓库