部署快速开始

> **文档版本**: v1.0.0
> **创建日期**: 2026-02-12
> **最后更新**: 2026-02-12
> **维护人**: 未来鸟FutureBird码巢企业服务引擎开发组
> **状态**: [最新]

> **搜索标签**: 部署, 上线, 生产环境, 发布, 云部署, 服务器部署
---

# &#128640; 快速部署到服务器

本指南帮助你在 10 分钟内将代码部署到自己的 Linux 服务器。

---

## &#128203; 前置要求

- 一台 Linux 服务器（Ubuntu 20.04+ / CentOS 7+）
- 服务器 root 或 sudo 权限
- 已知服务器 IP 地址和登录凭证

---

## ⚡ 方式一：一键部署（推荐）

### 1. 连接到服务器

```bash
ssh username@your-server-ip
```

### 2. 下载并运行部署脚本

```bash
# 克隆仓库
cd /tmp
git clone https://gitee.com/futurebird/oepnmachao.git
cd machao

# 运行快速部署脚本
sudo bash scripts/deploy-quick.sh
```

### 3. 访问应用

部署完成后，访问：
```
http://your-server-ip:5000
```

**✅ 完成！** &#127881;

---

## &#128295; 方式二：手动部署（了解每个步骤）

### 步骤 1: 安装 Node.js 24

```bash
curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash -
sudo apt install -y nodejs

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

### 步骤 2: 安装 pnpm

```bash
npm install -g pnpm

# 验证安装
pnpm --version
```

### 步骤 3: 克隆代码

```bash
cd /var/www
git clone https://gitee.com/futurebird/oepnmachao.git
cd machao
```

### 步骤 4: 安装依赖

```bash
pnpm install
```

### 步骤 5: 配置环境变量

```bash
# 创建 .env 文件
cp .env.example .env

# 编辑环境变量
nano .env
```

示例配置：
```env
NODE_ENV=production
PGDATABASE_URL=postgresql://user:password@localhost:5432/dbname
NEXT_PUBLIC_APP_URL=http://your-server-ip:5000
```

### 步骤 6: 构建项目

```bash
pnpm run build
```

### 步骤 7: 安装 PM2 并启动

```bash
# 安装 PM2
npm install -g pm2

# 启动服务
pm2 start npm --name "payroll-saas" -- start

# 保存 PM2 配置
pm2 save

# 设置开机自启
pm2 startup
```

### 步骤 8: 验证服务

```bash
# 查看服务状态
pm2 status

# 查看日志
pm2 logs payroll-saas

# 测试访问
curl http://localhost:5000
```

---

## &#127760; 配置域名和 HTTPS（可选但推荐）

### 1. 安装 Nginx

```bash
sudo apt install -y nginx
```

### 2. 配置 Nginx

```bash
# 复制示例配置
sudo cp nginx.conf.example /etc/nginx/sites-available/payroll-saas

# 编辑配置
sudo nano /etc/nginx/sites-available/payroll-saas
```

修改以下内容：
- 将 `your-domain.com` 改为你的域名
- 如果没有域名，使用服务器 IP

### 3. 启用配置

```bash
# 创建软链接
sudo ln -s /etc/nginx/sites-available/payroll-saas /etc/nginx/sites-enabled/

# 测试配置
sudo nginx -t

# 重启 Nginx
sudo systemctl restart nginx
```

### 4. 配置 SSL 证书（免费）

```bash
# 安装 Certbot
sudo apt install -y certbot python3-certbot-nginx

# 获取证书
sudo certbot --nginx -d your-domain.com -d www.your-domain.com
```

---

## &#128260; 更新应用

当你在 Gitee 上更新代码后，在服务器上执行：

```bash
cd /var/www/machao

# 拉取最新代码
git pull origin main

# 安装依赖（如果有变化）
pnpm install

# 重新构建
pnpm run build

# 重启服务
pm2 restart payroll-saas
```

---

## &#128202; 服务管理

### PM2 常用命令

```bash
# 查看状态
pm2 status

# 查看日志
pm2 logs payroll-saas

# 重启服务
pm2 restart payroll-saas

# 停止服务
pm2 stop payroll-saas

# 删除服务
pm2 delete payroll-saas

# 监控
pm2 monit
```

### Nginx 常用命令

```bash
# 重启 Nginx
sudo systemctl restart nginx

# 重新加载配置
sudo nginx -s reload

# 测试配置
sudo nginx -t

# 查看状态
sudo systemctl status nginx

# 查看错误日志
sudo tail -f /var/log/nginx/payroll-saas-error.log
```

---

## &#128274; 防火墙配置

```bash
# 查看防火墙状态
sudo ufw status

# 允许 HTTP
sudo ufw allow 80/tcp

# 允许 HTTPS
sudo ufw allow 443/tcp

# 允许 SSH
sudo ufw allow 22/tcp

# 启用防火墙
sudo ufw enable
```

---

## &#128027; 常见问题

### 问题 1: 端口 5000 被占用

```bash
# 查看占用进程
sudo lsof -i :5000

# 杀死进程
sudo kill -9 <PID>
```

### 问题 2: 构建失败

```bash
# 清理缓存
rm -rf .next node_modules

# 重新安装
pnpm install

# 重新构建
pnpm run build
```

### 问题 3: Nginx 502 错误

```bash
# 检查 Next.js 是否运行
pm2 status

# 检查端口是否监听
sudo netstat -tulpn | grep :5000

# 查看 Nginx 错误日志
sudo tail -f /var/log/nginx/payroll-saas-error.log
```

### 问题 4: 数据库连接失败

```bash
# 检查数据库是否运行
sudo systemctl status postgresql

# 测试连接
psql -U username -d dbname -h localhost
```

---

## &#128218; 更多资源

- **完整部署文档**: [docs/DEPLOYMENT.md](docs/DEPLOYMENT.md)
- **Gitee 仓库**: https://gitee.com/futurebird/machao
- **PM2 文档**: https://pm2.keymetrics.io/
- **Nginx 文档**: https://nginx.org/en/docs/

---

## &#128161; 提示

1. **首次部署建议**：使用一键部署脚本，快速上手
2. **生产环境建议**：配置域名、HTTPS、自动备份
3. **团队协作**：设置自动化部署（Webhook）
4. **监控告警**：使用 PM2 监控 + 邮件告警

---

## &#127384; 需要帮助？

- 查看 [docs/DEPLOYMENT.md](docs/DEPLOYMENT.md) 获取详细文档
- 在 Gitee Issues 提问
- 联系技术支持

---

**祝部署顺利！** &#127881;