nex_design/DEPLOYMENT.md

# Nex Design 部署文档

## 概述

本文档介绍如何使用 Docker + PM2 在服务器上部署 Nex Design 项目。

## 技术栈

- Docker: 容器化部署
- PM2: Node.js 进程管理
- Nginx serve: 静态文件服务器
- Node.js 18: 运行环境

## 项目构建说明

### 文档目录处理

本项目的 `/design` 路由会加载项目根目录下的 `docs/` 文件夹中的 Markdown 文档。通过 Docker 卷挂载方式，将宿主机的 `docs/` 目录映射到容器内的 `/app/dist/docs/`。

**优势：**
- ✅ 实时更新：修改 MD 文件后无需重新构建镜像
- ✅ 方便维护：在宿主机直接编辑文档
- ✅ 轻量镜像：Docker 镜像不包含文档，体积更小
- ✅ 灵活部署：可以独立管理文档版本

**配置方式：**
```yaml
# docker-compose.yml
volumes:
  - ./docs:/app/dist/docs:ro  # :ro 表示只读挂载，提高安全性
```

**注意事项：**
- 部署时需要确保 `docs/` 目录存在于项目根目录
- 如需制作完全自包含的镜像，可以在 Dockerfile 中 COPY docs 目录

## 文件说明

### 1. ecosystem.config.js

PM2 进程管理配置文件，定义了应用的运行参数：

- **name**: 应用名称 `nex-design`
- **script**: 使用 `npx serve` 提供静态文件服务
- **args**: 指定服务 `dist` 目录，端口 3000
- **instances**: 单实例运行
- **max_memory_restart**: 内存超过 500MB 自动重启
- **日志配置**: 输出到 `logs` 目录

### 2. Dockerfile

多阶段构建的 Docker 镜像配置：

**构建阶段 (builder)**:
- 基于 `node:18-alpine`
- 安装依赖并构建项目

**生产阶段**:
- 轻量级 Alpine 镜像
- 全局安装 PM2 和 serve
- 复制构建产物和配置
- 暴露 3000 端口
- 使用 `pm2-runtime` 启动

### 3. docker-compose.yml

Docker Compose 编排配置：

- 服务名称: `nex-design`
- 端口映射: `3000:3000`
- 自动重启策略
- 日志卷挂载
- 健康检查配置

### 4. .dockerignore

定义 Docker 构建时忽略的文件，减小镜像体积。

## 部署步骤

### 前置要求

确保服务器已安装：
- Docker (>= 20.10)
- Docker Compose (>= 2.0)

```bash
# 检查 Docker 版本
docker --version
docker-compose --version
```

### 1. 上传代码到服务器

```bash
# 方式一：使用 git
git clone <your-repository-url>
cd nex-design

# 方式二：使用 scp
scp -r ./nex-design user@server:/path/to/deploy/
```

### 2. 构建 Docker 镜像

```bash
# 构建镜像
docker-compose build

# 或使用 Docker 直接构建
docker build -t nex-design:latest .
```

### 3. 启动服务

```bash
# 启动服务（后台运行）
docker-compose up -d

# 查看日志
docker-compose logs -f

# 查看服务状态
docker-compose ps
```

### 4. 验证部署

```bash
# 检查容器状态
docker ps

# 检查健康状态
docker inspect --format='{{.State.Health.Status}}' nex-design-app

# 访问应用
curl http://localhost:3000
```

浏览器访问: `http://your-server-ip:3000`

## 常用命令

### Docker Compose 命令

```bash
# 启动服务
docker-compose up -d

# 停止服务
docker-compose stop

# 重启服务
docker-compose restart

# 停止并删除容器
docker-compose down

# 查看日志
docker-compose logs -f nex-design

# 重新构建并启动
docker-compose up -d --build
```

### Docker 命令

```bash
# 查看运行中的容器
docker ps

# 查看所有容器
docker ps -a

# 进入容器
docker exec -it nex-design-app sh

# 查看容器日志
docker logs -f nex-design-app

# 删除容器
docker rm -f nex-design-app

# 删除镜像
docker rmi nex-design:latest
```

### PM2 命令（容器内）

```bash
# 进入容器
docker exec -it nex-design-app sh

# 查看 PM2 进程列表
pm2 list

# 查看日志
pm2 logs

# 查看监控信息
pm2 monit

# 重启应用
pm2 restart nex-design

# 查看详细信息
pm2 show nex-design
```

## 生产环境优化

### 1. 使用 Nginx 反向代理

创建 `nginx.conf`:

```nginx
upstream nex_design {
    server localhost:3000;
}

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

    location / {
        proxy_pass http://nex_design;
        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_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }

    # 静态资源缓存
    location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2|ttf|eot)$ {
        proxy_pass http://nex_design;
        expires 1y;
        add_header Cache-Control "public, immutable";
    }
}
```

### 2. 添加 SSL 证书

```bash
# 使用 Let's Encrypt
sudo certbot --nginx -d your-domain.com
```

### 3. 修改 docker-compose.yml 添加 Nginx

```yaml
version: '3.8'

services:
  nex-design:
    build:
      context: .
      dockerfile: Dockerfile
    container_name: nex-design-app
    restart: unless-stopped
    expose:
      - "3000"
    environment:
      - NODE_ENV=production
    volumes:
      - ./logs:/app/logs
    networks:
      - nex-network

  nginx:
    image: nginx:alpine
    container_name: nex-design-nginx
    restart: unless-stopped
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./nginx.conf:/etc/nginx/conf.d/default.conf
      - ./ssl:/etc/nginx/ssl
    depends_on:
      - nex-design
    networks:
      - nex-network

networks:
  nex-network:
    driver: bridge
```

### 4. 环境变量配置

创建 `.env` 文件：

```env
NODE_ENV=production
PORT=3000
```

修改 `docker-compose.yml`:

```yaml
services:
  nex-design:
    env_file:
      - .env
```

## 日志管理

### 查看日志

```bash
# Docker 日志
docker-compose logs -f --tail=100 nex-design

# PM2 日志（在容器内）
docker exec nex-design-app pm2 logs --lines 100

# 宿主机日志文件
tail -f ./logs/pm2-out.log
tail -f ./logs/pm2-error.log
```

### 日志轮转

安装 `pm2-logrotate`:

```bash
docker exec nex-design-app pm2 install pm2-logrotate
docker exec nex-design-app pm2 set pm2-logrotate:max_size 10M
docker exec nex-design-app pm2 set pm2-logrotate:retain 7
```

## 监控和维护

### 1. 资源监控

```bash
# 查看容器资源使用
docker stats nex-design-app

# 查看 PM2 监控
docker exec nex-design-app pm2 monit
```

### 2. 健康检查

```bash
# 检查健康状态
docker inspect --format='{{json .State.Health}}' nex-design-app | jq
```

### 3. 自动更新部署

创建 `deploy.sh`:

```bash
#!/bin/bash

echo "开始部署 Nex Design..."

# 拉取最新代码
git pull origin main

# 重新构建镜像
docker-compose build

# 重启服务
docker-compose up -d

# 清理旧镜像
docker image prune -f

echo "部署完成！"
echo "查看日志: docker-compose logs -f"
```

赋予执行权限：

```bash
chmod +x deploy.sh
```

## 故障排查

### 容器无法启动

```bash
# 查看详细错误
docker-compose logs nex-design

# 检查镜像是否构建成功
docker images | grep nex-design

# 检查端口占用
netstat -tlnp | grep 3000
```

### PM2 进程异常

```bash
# 进入容器
docker exec -it nex-design-app sh

# 查看 PM2 状态
pm2 status

# 重启进程
pm2 restart nex-design

# 查看错误日志
pm2 logs --err
```

### 内存占用过高

```bash
# 查看内存使用
docker stats nex-design-app

# 调整 PM2 内存限制
# 修改 ecosystem.config.js 中的 max_memory_restart
```

## 备份与恢复

### 备份

```bash
# 备份日志
tar -czf logs-backup-$(date +%Y%m%d).tar.gz logs/

# 备份配置
tar -czf config-backup-$(date +%Y%m%d).tar.gz \
  ecosystem.config.js \
  Dockerfile \
  docker-compose.yml \
  .dockerignore
```

### 恢复

```bash
# 恢复配置
tar -xzf config-backup-20250101.tar.gz

# 重新部署
docker-compose up -d --build
```

## 安全建议

1. **最小权限原则**: 使用非 root 用户运行容器
2. **定期更新**: 及时更新基础镜像和依赖包
3. **网络隔离**: 使用 Docker 网络隔离服务
4. **日志审计**: 定期检查日志文件
5. **资源限制**: 在 docker-compose.yml 中添加资源限制

```yaml
services:
  nex-design:
    deploy:
      resources:
        limits:
          cpus: '1'
          memory: 512M
        reservations:
          memory: 256M
```

## 性能优化

1. **启用 Gzip 压缩**: 在 Nginx 中配置
2. **静态资源缓存**: 设置合理的缓存策略
3. **CDN 加速**: 将静态资源托管到 CDN
4. **镜像优化**: 使用 Alpine 基础镜像，减小体积
5. **构建缓存**: 利用 Docker 层缓存加速构建

## 技术支持

如遇问题，请检查：

1. Docker 和 Docker Compose 版本
2. 服务器资源（CPU、内存、磁盘）
3. 防火墙和端口配置
4. 日志文件中的错误信息

## 更新日志

- **v1.0.0** (2025-11-05): 初始版本，支持 Docker + PM2 部署