qiangdanxitong/DEPLOYMENT_GUIDE.md

851 lines
15 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 🚀 DesignHub 部署指南
本文档详细说明如何在本地开发环境和生产环境中部署 DesignHub 系统。
---
## 📋 目录
1. [环境要求](#环境要求)
2. [本地开发环境部署](#本地开发环境部署)
3. [生产环境部署](#生产环境部署)
4. [Docker部署](#docker部署)
5. [常见问题](#常见问题)
6. [维护与监控](#维护与监控)
---
## 🔧 环境要求
### 开发环境
| 组件 | 版本要求 | 说明 |
|------|---------|------|
| JDK | 17+ | 建议使用 OpenJDK 17 |
| Node.js | 18+ | 建议使用 LTS 版本 |
| MySQL | 8.0+ | 必须 |
| Redis | 6.0+ | 建议 7.0+ |
| Maven | 3.6+ | 后端构建工具 |
| pnpm | 8.0+ | 前端包管理器(可选npm/yarn) |
### 生产环境
| 组件 | 版本要求 | 配置建议 |
|------|---------|---------|
| 服务器 | Linux | CentOS 7+, Ubuntu 20.04+ |
| CPU | 4核+ | 推荐 8核 |
| 内存 | 8GB+ | 推荐 16GB |
| 磁盘 | 50GB+ | SSD推荐 |
| 带宽 | 10Mbps+ | 推荐 100Mbps |
---
## 💻 本地开发环境部署
### 1. 克隆项目
```bash
# 克隆代码仓库
cd /Users/lanmu/Desktop/qiangdanxitong
# 或使用 Git
# git clone <repository_url>
```
### 2. 配置数据库
#### 2.1 安装 MySQL 8.0
**macOS**:
```bash
brew install mysql@8.0
brew services start mysql@8.0
```
**Linux**:
```bash
sudo apt update
sudo apt install mysql-server
sudo systemctl start mysql
sudo systemctl enable mysql
```
**Windows**:
- 下载MySQL 8.0安装包
- 运行安装向导
#### 2.2 创建数据库
```sql
-- 登录MySQL
mysql -u root -p
-- 创建数据库
CREATE DATABASE design_hub CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
-- 创建用户(可选)
CREATE USER 'designhub'@'localhost' IDENTIFIED BY 'your_password';
GRANT ALL PRIVILEGES ON design_hub.* TO 'designhub'@'localhost';
FLUSH PRIVILEGES;
```
#### 2.3 导入数据库表
```bash
# 执行数据库脚本(如果有SQL文件)
mysql -u root -p design_hub < database/schema.sql
```
**注意**:项目使用MyBatis Plus,实体类会自动映射到数据库表。确保在启动前,数据库连接配置正确。
### 3. 配置 Redis
#### 3.1 安装 Redis
**macOS**:
```bash
brew install redis
brew services start redis
```
**Linux**:
```bash
sudo apt install redis-server
sudo systemctl start redis
sudo systemctl enable redis
```
**Windows**:
- 下载Redis for Windows
- 解压并运行 `redis-server.exe`
#### 3.2 验证Redis
```bash
redis-cli ping
# 应返回:PONG
```
### 4. 配置后端
#### 4.1 编辑配置文件
编辑 `/backend/src/main/resources/application.yml`:
```yaml
spring:
datasource:
url: jdbc:mysql://localhost:3306/design_hub?useUnicode=true&characterEncoding=utf8&serverTimezone=Asia/Shanghai
username: root # 修改为你的MySQL用户名
password: your_password # 修改为你的MySQL密码
driver-class-name: com.mysql.cj.jdbc.Driver
redis:
host: localhost
port: 6379
password: # 如果Redis没有密码,留空
database: 0
timeout: 3000
jwt:
secret: your-secret-key-change-this-in-production # 生产环境请修改
access-token-expiration: 7200000 # 2小时
refresh-token-expiration: 604800000 # 7天
server:
port: 8080
```
#### 4.2 构建并运行后端
```bash
cd backend
# 使用 Maven 构建
mvn clean install -DskipTests
# 运行后端
mvn spring-boot:run
# 或者使用 JAR 文件
java -jar target/designhub-backend-1.0.0.jar
```
**后端启动成功标志**:
- 控制台输出 `Started DesignHubApplication`
- 访问 http://localhost:8080/swagger-ui.html 查看API文档
### 5. 配置前端
#### 5.1 安装依赖
```bash
cd frontend
# 使用 pnpm(推荐)
pnpm install
# 或使用 npm
npm install
# 或使用 yarn
yarn install
```
#### 5.2 配置环境变量
创建 `/frontend/.env.development`:
```env
# 开发环境配置
VITE_APP_BASE_API=http://localhost:8080/api
VITE_APP_TITLE=DesignHub
VITE_APP_VERSION=6.0
```
#### 5.3 运行前端
```bash
# 开发模式
pnpm dev
# 或
npm run dev
```
**前端启动成功标志**:
- 控制台输出本地访问地址(默认:http://localhost:5173)
- 浏览器自动打开页面
### 6. 访问系统
打开浏览器,访问 `http://localhost:5173`
**默认测试账号**:
- 用户名:`admin`
- 密码:`123456`
---
## 🌐 生产环境部署
### 1. 服务器准备
#### 1.1 更新系统
```bash
# CentOS/RHEL
sudo yum update -y
# Ubuntu/Debian
sudo apt update && sudo apt upgrade -y
```
#### 1.2 安装必要软件
```bash
# 安装 JDK 17
sudo yum install java-17-openjdk -y
# 安装 Nginx
sudo yum install nginx -y
# 安装 Git(如需)
sudo yum install git -y
```
### 2. 部署数据库
#### 2.1 安装 MySQL 8.0
```bash
# 下载MySQL Yum Repository
wget https://dev.mysql.com/get/mysql80-community-release-el7-3.noarch.rpm
# 安装Repository
sudo rpm -ivh mysql80-community-release-el7-3.noarch.rpm
# 安装MySQL
sudo yum install mysql-server -y
# 启动MySQL
sudo systemctl start mysqld
sudo systemctl enable mysqld
# 获取临时密码
sudo grep 'temporary password' /var/log/mysqld.log
# 修改root密码
mysql_secure_installation
```
#### 2.2 创建数据库和用户
```sql
CREATE DATABASE design_hub CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'designhub'@'%' IDENTIFIED BY 'StrongPassword123!';
GRANT ALL PRIVILEGES ON design_hub.* TO 'designhub'@'%';
FLUSH PRIVILEGES;
```
#### 2.3 导入数据
```bash
mysql -u designhub -p design_hub < /path/to/schema.sql
```
### 3. 部署 Redis
```bash
# 安装Redis
sudo yum install redis -y
# 配置Redis(可选设置密码)
sudo vi /etc/redis.conf
# 找到 requirepass,设置密码
requirepass YourStrongPassword
# 启动Redis
sudo systemctl start redis
sudo systemctl enable redis
```
### 4. 部署后端
#### 4.1 上传代码
```bash
# 创建应用目录
sudo mkdir -p /opt/designhub/backend
sudo chown -R $USER:$USER /opt/designhub
# 上传代码(使用scp、rsync或git)
# scp方式
scp -r backend/* user@server:/opt/designhub/backend/
# 或使用git
cd /opt/designhub
git clone <repository_url>
```
#### 4.2 配置生产环境
编辑 `/opt/designhub/backend/src/main/resources/application-prod.yml`:
```yaml
spring:
datasource:
url: jdbc:mysql://localhost:3306/design_hub?useSSL=true
username: designhub
password: StrongPassword123!
redis:
host: localhost
port: 6379
password: YourStrongPassword
jwt:
secret: change-this-to-a-very-strong-secret-key-in-production
logging:
level:
root: INFO
com.designhub: INFO
file:
name: /opt/designhub/logs/application.log
```
#### 4.3 构建后端
```bash
cd /opt/designhub/backend
# 构建
mvn clean package -DskipTests -Pprod
# 移动JAR文件
mv target/designhub-backend-1.0.0.jar /opt/designhub/
```
#### 4.4 创建系统服务
创建 `/etc/systemd/system/designhub-backend.service`:
```ini
[Unit]
Description=DesignHub Backend Service
After=network.target
[Service]
Type=simple
User=designhub
WorkingDirectory=/opt/designhub
ExecStart=/usr/bin/java -jar /opt/designhub/designhub-backend-1.0.0.jar --spring.profiles.active=prod
Restart=on-failure
RestartSec=10
[Install]
WantedBy=multi-user.target
```
#### 4.5 启动后端服务
```bash
# 重新加载systemd
sudo systemctl daemon-reload
# 启动服务
sudo systemctl start designhub-backend
# 设置开机自启
sudo systemctl enable designhub-backend
# 查看状态
sudo systemctl status designhub-backend
# 查看日志
sudo journalctl -u designhub-backend -f
```
### 5. 部署前端
#### 5.1 构建前端
```bash
cd /opt/designhub/frontend
# 安装依赖
pnpm install --production
# 创建生产环境配置
cat > .env.production << EOF
VITE_APP_BASE_API=https://api.yourdomain.com/api
VITE_APP_TITLE=DesignHub
VITE_APP_VERSION=6.0
EOF
# 构建
pnpm build
# 构建产物在 dist/ 目录
```
#### 5.2 配置 Nginx
创建 `/etc/nginx/conf.d/designhub.conf`:
```nginx
server {
listen 80;
server_name yourdomain.com www.yourdomain.com;
# 前端静态资源
root /opt/designhub/frontend/dist;
index index.html;
# 前端路由
location / {
try_files $uri $uri/ /index.html;
}
# API代理
location /api/ {
proxy_pass http://localhost:8080/api/;
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;
# WebSocket支持(如需)
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
}
# Gzip压缩
gzip on;
gzip_types text/plain text/css application/json application/javascript text/xml application/xml application/xml+rss text/javascript;
# 静态资源缓存
location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg)$ {
expires 30d;
add_header Cache-Control "public, immutable";
}
}
```
#### 5.3 配置 HTTPS (Let's Encrypt)
```bash
# 安装certbot
sudo yum install certbot python3-certbot-nginx -y
# 获取SSL证书
sudo certbot --nginx -d yourdomain.com -d www.yourdomain.com
# 自动续期测试
sudo certbot renew --dry-run
```
#### 5.4 启动 Nginx
```bash
# 测试配置
sudo nginx -t
# 启动Nginx
sudo systemctl start nginx
sudo systemctl enable nginx
# 重新加载配置
sudo systemctl reload nginx
```
### 6. 防火墙配置
```bash
# CentOS/RHEL (firewalld)
sudo firewall-cmd --permanent --add-service=http
sudo firewall-cmd --permanent --add-service=https
sudo firewall-cmd --reload
# Ubuntu (ufw)
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable
```
---
## 🐳 Docker 部署
### 1. 后端 Dockerfile
创建 `/backend/Dockerfile`:
```dockerfile
FROM openjdk:17-slim
WORKDIR /app
# 复制JAR文件
COPY target/designhub-backend-1.0.0.jar app.jar
# 设置时区
ENV TZ=Asia/Shanghai
RUN ln -snf /usr/share/zoneinfo/$TZ /etc/localtime && echo $TZ > /etc/timezone
# 暴露端口
EXPOSE 8080
# 启动命令
ENTRYPOINT ["java", "-jar", "app.jar", "--spring.profiles.active=prod"]
```
### 2. 前端 Dockerfile
创建 `/frontend/Dockerfile`:
```dockerfile
FROM node:18-alpine AS builder
WORKDIR /app
# 复制package文件
COPY package*.json ./
COPY pnpm-lock.yaml ./
# 安装依赖
RUN npm install -g pnpm
RUN pnpm install
# 复制源代码
COPY . .
# 构建
RUN pnpm build
# 生产环境
FROM nginx:alpine
# 复制构建产物
COPY --from=builder /app/dist /usr/share/nginx/html
# 复制Nginx配置
COPY nginx.conf /etc/nginx/conf.d/default.conf
EXPOSE 80
CMD ["nginx", "-g", "daemon off;"]
```
### 3. Docker Compose
创建 `/docker-compose.yml`:
```yaml
version: '3.8'
services:
mysql:
image: mysql:8.0
container_name: designhub-mysql
environment:
MYSQL_ROOT_PASSWORD: rootpassword
MYSQL_DATABASE: design_hub
MYSQL_USER: designhub
MYSQL_PASSWORD: designhubpass
ports:
- "3306:3306"
volumes:
- mysql_data:/var/lib/mysql
networks:
- designhub-network
redis:
image: redis:7-alpine
container_name: designhub-redis
command: redis-server --requirepass redispassword
ports:
- "6379:6379"
volumes:
- redis_data:/data
networks:
- designhub-network
backend:
build: ./backend
container_name: designhub-backend
environment:
SPRING_PROFILES_ACTIVE: prod
SPRING_DATASOURCE_URL: jdbc:mysql://mysql:3306/design_hub
SPRING_DATASOURCE_USERNAME: designhub
SPRING_DATASOURCE_PASSWORD: designhubpass
SPRING_REDIS_HOST: redis
SPRING_REDIS_PASSWORD: redispassword
ports:
- "8080:8080"
depends_on:
- mysql
- redis
networks:
- designhub-network
frontend:
build: ./frontend
container_name: designhub-frontend
ports:
- "80:80"
depends_on:
- backend
networks:
- designhub-network
volumes:
mysql_data:
redis_data:
networks:
designhub-network:
driver: bridge
```
### 4. 启动 Docker Compose
```bash
# 构建并启动所有服务
docker-compose up -d
# 查看日志
docker-compose logs -f
# 停止所有服务
docker-compose down
# 重启服务
docker-compose restart
```
---
## ❓ 常见问题
### 1. 后端无法连接数据库
**问题**:`java.sql.SQLException: Access denied for user`
**解决**:
```sql
-- 检查用户权限
SELECT User, Host FROM mysql.user;
-- 重新授权
GRANT ALL PRIVILEGES ON design_hub.* TO 'designhub'@'%' IDENTIFIED BY 'password';
FLUSH PRIVILEGES;
```
### 2. Redis连接失败
**问题**:`Could not connect to Redis at localhost:6379`
**解决**:
```bash
# 检查Redis是否运行
sudo systemctl status redis
# 检查端口
netstat -tuln | grep 6379
# 测试连接
redis-cli -h localhost -p 6379 -a password ping
```
### 3. 前端API请求跨域
**问题**:`CORS policy: No 'Access-Control-Allow-Origin' header`
**解决**:后端添加CORS配置(已在项目中配置)
### 4. JWT Token过期
**问题**:频繁退出登录
**解决**:调整Token过期时间或实现自动刷新机制(已实现)
### 5. 文件上传失败
**问题**:上传大文件失败
**解决**:
```yaml
# application.yml
spring:
servlet:
multipart:
max-file-size: 100MB
max-request-size: 100MB
```
---
## 🛠️ 维护与监控
### 1. 日志管理
#### 后端日志
```bash
# 查看实时日志
tail -f /opt/designhub/logs/application.log
# 按日期查看
less /opt/designhub/logs/application-2025-11-07.log
# 日志清理(保留30天)
find /opt/designhub/logs -name "*.log" -mtime +30 -delete
```
#### Nginx日志
```bash
# 访问日志
tail -f /var/log/nginx/access.log
# 错误日志
tail -f /var/log/nginx/error.log
```
### 2. 数据库备份
#### 自动备份脚本
创建 `/opt/designhub/scripts/backup_db.sh`:
```bash
#!/bin/bash
# 配置
DB_NAME="design_hub"
DB_USER="designhub"
DB_PASS="password"
BACKUP_DIR="/opt/designhub/backups"
DATE=$(date +%Y%m%d_%H%M%S)
# 创建备份目录
mkdir -p $BACKUP_DIR
# 备份数据库
mysqldump -u$DB_USER -p$DB_PASS $DB_NAME > $BACKUP_DIR/backup_$DATE.sql
# 压缩备份
gzip $BACKUP_DIR/backup_$DATE.sql
# 删除7天前的备份
find $BACKUP_DIR -name "backup_*.sql.gz" -mtime +7 -delete
echo "Backup completed: backup_$DATE.sql.gz"
```
#### 设置定时任务
```bash
# 编辑crontab
crontab -e
# 每天凌晨2点备份
0 2 * * * /opt/designhub/scripts/backup_db.sh
```
### 3. 性能监控
#### 系统资源监控
```bash
# CPU和内存
top
# 磁盘使用
df -h
# 网络连接
netstat -tuln
# 进程监控
ps aux | grep java
```
#### 应用监控
**Spring Boot Actuator**(已集成):
- 访问 http://yourdomain.com/actuator/health
- 访问 http://yourdomain.com/actuator/metrics
### 4. 安全加固
#### 系统安全
```bash
# 关闭不必要的服务
sudo systemctl disable bluetooth
sudo systemctl disable cups
# 更新安全补丁
sudo yum update --security -y
# 配置fail2ban
sudo yum install fail2ban -y
sudo systemctl enable fail2ban
sudo systemctl start fail2ban
```
#### 应用安全
- 定期更新依赖版本
- 使用强密码
- 启用HTTPS
- 配置防火墙
- 定期安全审计
---
## 📞 技术支持
如遇到部署问题,请:
1. 查看本文档"常见问题"部分
2. 检查日志文件
3. 联系技术支持团队
---
**祝您部署顺利!** 🎉