494 lines
8.6 KiB
Markdown
494 lines
8.6 KiB
Markdown
# 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 部署
|