部署指南

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

> **搜索标签**: 部署, 部署指南, 上线, 生产环境
---

# 部署运维指南

## 概述

本文档提供了企业管理数字化中台的完整部署和运维指南，包括环境准备、安装部署、配置说明、性能优化和故障排查。

## 环境准备

### 系统要求

**操作系统**:
- Linux (推荐 Ubuntu 22.04 / CentOS 8+)
- macOS 12+
- Windows 10/11 (开发环境)

**软件要求**:
- Node.js 24 LTS
- PostgreSQL 16
- Redis 7.0+
- Git 2.30+

**硬件要求**:
- CPU: 2 核心及以上
- 内存: 4GB 及以上
- 存储: 20GB 及以上

### 安装 Node.js

#### Ubuntu/Debian

```bash
# 使用 NodeSource 仓库
curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash -
sudo apt-get install -y nodejs

# 验证安装
node -v
npm -v
```

#### macOS

```bash
# 使用 Homebrew
brew install node@24

# 验证安装
node -v
npm -v
```

### 安装 PostgreSQL

#### Ubuntu/Debian

```bash
# 添加 PostgreSQL 仓库
sudo sh -c 'echo "deb http://apt.postgresql.org/pub/repos/apt $(lsb_release -cs)-pgdg main" > /etc/apt/sources.list.d/pgdg.list'
curl -fsSL https://www.postgresql.org/media/keys/ACCC4CF8.asc | sudo apt-key add -
sudo apt-get update
sudo apt-get install -y postgresql-16 postgresql-contrib-16

# 启动服务
sudo systemctl start postgresql
sudo systemctl enable postgresql

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

#### 创建数据库和用户

```bash
# 切换到 postgres 用户
sudo -u postgres psql

# 创建数据库
CREATE DATABASE salary_system;

# 创建用户
CREATE USER salary_user WITH PASSWORD 'your_password';

# 授权
GRANT ALL PRIVILEGES ON DATABASE salary_system TO salary_user;

# 退出
\q
```

### 安装 Redis

#### Ubuntu/Debian

```bash
# 安装 Redis
sudo apt-get install -y redis-server

# 启动服务
sudo systemctl start redis-server
sudo systemctl enable redis-server

# 验证安装
redis-cli ping
# 应返回: PONG
```

## 项目安装

### 克隆项目

```bash
git clone https://github.com/your-org/salary-system.git
cd salary-system
```

### 安装依赖

```bash
# 使用 pnpm
pnpm install

# 或使用 npm
npm install
```

### 环境变量配置

创建 `.env` 文件：

```bash
cp .env.example .env
```

编辑 `.env` 文件：

```env
# 应用配置
NODE_ENV=production
PORT=5000
BASE_URL=https://your-domain.com

# 数据库配置
DATABASE_URL=postgresql://salary_user:password@localhost:5432/salary_system

# Redis 配置
REDIS_URL=redis://localhost:6379

# JWT 配置
JWT_SECRET=your-secret-key
JWT_EXPIRES_IN=24h

# 对象存储配置（七牛云）
QINIU_ACCESS_KEY=your-access-key
QINIU_SECRET_KEY=your-secret-key
QINIU_BUCKET=your-bucket
QINIU_DOMAIN=your-domain

# 短信配置（阿里云）
ALIYUN_SMS_ACCESS_KEY_ID=your-access-key
ALIYUN_SMS_SECRET_KEY=your-secret-key
ALIYUN_SMS_SIGN_NAME=your-sign-name

# 邮件配置
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_SECURE=true
SMTP_USER=your-email@gmail.com
SMTP_PASSWORD=your-password
EMAIL_FROM=your-email@gmail.com

# 微信配置
WECHAT_APP_ID=your-app-id
WECHAT_APP_SECRET=your-app-secret

# 支付配置
WECHAT_PAY_APP_ID=your-wechat-pay-app-id
WECHAT_PAY_APP_SECRET=your-wechat-pay-app-secret
ALIPAY_APP_ID=your-alipay-app-id
ALIPAY_APP_SECRET=your-alipay-app-secret
```

### 数据库迁移

```bash
# 运行迁移
pnpm db:push

# 或使用 Drizzle
pnpm drizzle-kit push
```

### 初始化数据

```bash
# 初始化管理员账号
pnpm db:init

# 或调用 API
curl -X POST http://localhost:5000/api/v1/database/init
```

## 构建部署

### 开发环境

```bash
# 启动开发服务器（支持 HMR）
pnpm dev

# 或使用 FutureBirdAadminAi CLI
FutureBirdAadminAi dev
```

### 生产环境构建

```bash
# 构建生产版本
pnpm build

# 预览生产构建
pnpm preview
```

### 生产环境启动

```bash
# 使用 PM2
pm2 start npm --name "salary-system" -- start

# 或使用 systemd
sudo systemctl start salary-system
```

## 服务配置

### systemd 服务配置

创建 `/etc/systemd/system/salary-system.service`:

```ini
[Unit]
Description=Salary System
After=network.target

[Service]
Type=simple
User=www-data
WorkingDirectory=/var/www/salary-system
ExecStart=/usr/bin/node /var/www/salary-system/.next/standalone/server.js
Restart=on-failure
RestartSec=10
Environment=NODE_ENV=production
EnvironmentFile=/var/www/salary-system/.env

[Install]
WantedBy=multi-user.target
```

启动服务：

```bash
sudo systemctl daemon-reload
sudo systemctl start salary-system
sudo systemctl enable salary-system
sudo systemctl status salary-system
```

### Nginx 反向代理配置

创建 `/etc/nginx/sites-available/salary-system`:

```nginx
upstream salary_system {
    server localhost:5000;
}

server {
    listen 80;
    server_name your-domain.com;

# 重定向到 HTTPS
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    server_name your-domain.com;

# SSL 证书配置
    ssl_certificate /path/to/your/cert.pem;
    ssl_certificate_key /path/to/your/key.pem;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers HIGH:!aNULL:!MD5;

# 上传文件大小限制
    client_max_body_size 50M;

# 代理配置
    location / {
        proxy_pass http://salary_system;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_cache_bypass $http_upgrade;
    }

# 静态文件缓存
    location /_next/static {
        proxy_pass http://salary_system;
        proxy_cache_valid 200 60m;
        add_header Cache-Control "public, immutable, max-age=31536000";
    }

# 日志
    access_log /var/log/nginx/salary-system.access.log;
    error_log /var/log/nginx/salary-system.error.log;
}
```

启用配置：

```bash
sudo ln -s /etc/nginx/sites-available/salary-system /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx
```

## 性能优化

### 数据库优化

#### 索引优化

```sql
-- 查看慢查询
SELECT * FROM pg_stat_statements ORDER BY total_time DESC LIMIT 10;

-- 创建必要的索引
CREATE INDEX CONCURRENTLY idx_salary_slips_period_company ON salary_slips(salary_period, company_id);
CREATE INDEX CONCURRENTLY idx_users_tenant_company ON saas_users(tenant_id, company_id);
```

#### 查询优化

```sql
-- 更新统计信息
ANALYZE;

-- 清理死锁
VACUUM FULL;
```

#### 连接池配置

在 `.env` 中配置：

```env
DATABASE_POOL_MIN=2
DATABASE_POOL_MAX=20
DATABASE_POOL_IDLE_TIMEOUT=30000
```

### 缓存优化

#### Redis 配置

编辑 `/etc/redis/redis.conf`:

```conf
# 最大内存
maxmemory 2gb

# 内存淘汰策略
maxmemory-policy allkeys-lru

# 持久化
save 900 1
save 300 10
save 60 10000
```

#### 应用缓存

```typescript
// 启用查询结果缓存
const result = await cache.get(`query:${queryKey}`);
if (result) {
  return result;
}
```

### 应用优化

#### Next.js 配置

```javascript
// next.config.js
module.exports = {
  // 启用压缩
  compress: true,

// 优化图片
  images: {
    domains: ['your-cdn-domain.com'],
    formats: ['image/avif', 'image/webp'],
  },

// 生产环境优化
  swcMinify: true,

// 输出模式
  output: 'standalone',
};
```

#### 启用 CDN

配置对象存储的 CDN 域名：

```env
QINIU_DOMAIN=https://cdn.your-domain.com
```

## 监控和日志

### 应用日志

查看日志：

```bash
# 应用日志
tail -f /app/work/logs/bypass/app.log

# 开发日志
tail -f /app/work/logs/bypass/dev.log

# 控制台日志
tail -f /app/work/logs/bypass/console.log
```

### PM2 监控

```bash
# 查看进程状态
pm2 status

# 查看日志
pm2 logs salary-system

# 监控
pm2 monit
```

### 系统监控

```bash
# CPU 和内存
top
htop

# 磁盘使用
df -h

# 网络连接
netstat -tuln

# 进程监控
ps aux | grep node
```

## 故障排查

### 常见问题

#### 1. 数据库连接失败

**症状**:
```
Error: Connection refused
```

**解决方案**:
```bash
# 检查 PostgreSQL 状态
sudo systemctl status postgresql

# 检查连接
psql -U salary_user -d salary_system

# 检查防火墙
sudo ufw allow 5432
```

#### 2. Redis 连接失败

**症状**:
```
Error: Redis connection failed
```

**解决方案**:
```bash
# 检查 Redis 状态
sudo systemctl status redis-server

# 测试连接
redis-cli ping

# 检查配置
netstat -tuln | grep 6379
```

#### 3. 内存不足

**症状**:
```
JavaScript heap out of memory
```

**解决方案**:
```bash
# 增加 Node.js 内存限制
export NODE_OPTIONS="--max-old-space-size=4096"

# 或在 PM2 配置中
pm2 start npm --name "salary-system" -- start --node-args="--max-old-space-size=4096"
```

#### 4. 端口被占用

**症状**:
```
Error: Port 5000 is already in use
```

**解决方案**:
```bash
# 查找占用端口的进程
lsof -i :5000

# 或使用 ss
ss -tuln | grep 5000

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

### 日志分析

```bash
# 查看错误日志
grep -i error /app/work/logs/bypass/app.log

# 查看最近的错误
tail -n 100 /app/work/logs/bypass/app.log | grep -i error

# 统计错误类型
grep -i error /app/work/logs/bypass/app.log | awk '{print $NF}' | sort | uniq -c
```

## 备份和恢复

### 数据库备份

```bash
# 备份数据库
pg_dump -U salary_user salary_system > backup_$(date +%Y%m%d).sql

# 压缩备份
gzip backup_$(date +%Y%m%d).sql

# 定时备份（cron）
0 2 * * * pg_dump -U salary_user salary_system | gzip > /backup/salary_$(date +\%Y\%m\%d).sql.gz
```

### 数据库恢复

```bash
# 解压备份
gunzip backup_20240101.sql.gz

# 恢复数据库
psql -U salary_user salary_system < backup_20240101.sql
```

### 文件备份

```bash
# 备份上传文件
tar -czf uploads_$(date +%Y%m%d).tar.gz /var/www/salary-system/public/uploads

# 备份配置文件
tar -czf config_$(date +%Y%m%d).tar.gz /var/www/salary-system/.env
```

## 安全加固

### 防火墙配置

```bash
# UFW 防火墙
sudo ufw allow 22    # SSH
sudo ufw allow 80    # HTTP
sudo ufw allow 443   # HTTPS
sudo ufw enable
```

### SSL/TLS 配置

使用 Let's Encrypt 免费证书：

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

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

# 自动续期
sudo certbot renew --dry-run
```

### 安全最佳实践

1. 定期更新系统和依赖
2. 使用强密码
3. 启用双因素认证
4. 定期备份数据
5. 监控异常访问
6. 限制 API 请求频率

## 更新升级

### 更新依赖

```bash
# 更新依赖
pnpm update

# 检查过时的依赖
pnpm outdated

# 更新 Next.js
pnpm add next@latest
```

### 数据库迁移

```bash
# 生成迁移文件
pnpm drizzle-kit generate

# 应用迁移
pnpm drizzle-kit push

# 或使用自定义脚本
pnpm db:migrate
```

### 滚动更新

```bash
# 更新代码
git pull origin main

# 安装依赖
pnpm install

# 构建
pnpm build

# 重启服务
pm2 restart salary-system
```

## 监控告警

### 健康检查

```bash
# 应用健康检查
curl http://localhost:5000/api/v1/health

# 数据库健康检查
pg_isready -U salary_user -d salary_system

# Redis 健康检查
redis-cli ping
```

### 告警配置

配置监控工具（如 Prometheus + Grafana）：

```yaml
# prometheus.yml
scrape_configs:
  - job_name: 'salary-system'
    static_configs:
      - targets: ['localhost:5000']
    metrics_path: '/api/v1/metrics'
```

## 参考文档

- [系统架构](../06-架构设计/系统架构.md)
- [技术栈说明](../06-架构设计/系统架构.md#技术栈)
- [API 接口文档](../04-API文档/API接口文档.md)
- [数据库字典](../05-数据库/数据库字典.md)
- [开发规范](../03-开发指南/开发指南.md)