349 lines
6.4 KiB
Markdown
349 lines
6.4 KiB
Markdown
# AIGC 前端部署指南
|
||
|
||
## 环境配置说明
|
||
|
||
项目已配置开发和生产环境自动切换：
|
||
|
||
- **开发环境**: 使用 `.env.development`，API 地址为 `http://localhost:20006`
|
||
- **生产环境**: 使用 `.env.production`，需要配置实际服务器地址
|
||
|
||
## 部署前准备
|
||
|
||
### 1. 修改生产环境配置
|
||
|
||
编辑 `.env.production` 文件，修改为实际的服务器地址：
|
||
|
||
```bash
|
||
# 修改为你的服务器地址
|
||
VITE_API_BASE_URL=http://your-server-ip:20006
|
||
|
||
# 或使用域名
|
||
VITE_API_BASE_URL=https://api.yourdomain.com
|
||
```
|
||
|
||
### 2. 确保后端服务已启动
|
||
|
||
确保后端服务在服务器上运行在 20006 端口（或你配置的端口）。
|
||
|
||
## 部署方式
|
||
|
||
### 方式一：本地构建 + 手动上传（推荐新手）
|
||
|
||
#### 1. 本地构建
|
||
|
||
```bash
|
||
# 安装依赖
|
||
npm install
|
||
|
||
# 构建生产版本
|
||
npm run build
|
||
```
|
||
|
||
构建完成后，会在项目根目录生成 `dist` 文件夹。
|
||
|
||
#### 2. 上传到服务器
|
||
|
||
```bash
|
||
# 打包 dist 目录
|
||
tar -czf aigc-ui.tar.gz dist/
|
||
|
||
# 上传到服务器
|
||
scp aigc-ui.tar.gz user@server:/var/www/
|
||
|
||
# 在服务器上解压
|
||
ssh user@server
|
||
cd /var/www/
|
||
tar -xzf aigc-ui.tar.gz
|
||
```
|
||
|
||
### 方式二：使用部署脚本（推荐）
|
||
|
||
#### 1. 本地构建并打包
|
||
|
||
```bash
|
||
chmod +x deploy.sh
|
||
./deploy.sh
|
||
```
|
||
|
||
这会生成一个带时间戳的压缩包，例如 `aigc-ui-20231209_143022.tar.gz`。
|
||
|
||
#### 2. 上传并部署
|
||
|
||
手动上传压缩包到服务器，或使用自动部署脚本：
|
||
|
||
```bash
|
||
chmod +x deploy-to-server.sh
|
||
./deploy-to-server.sh user@server-ip /var/www/aigc
|
||
```
|
||
|
||
### 方式三：服务器上直接构建
|
||
|
||
```bash
|
||
# 在服务器上克隆代码
|
||
git clone your-repo-url /var/www/aigc
|
||
cd /var/www/aigc/aigc-ui
|
||
|
||
# 修改生产环境配置
|
||
vim .env.production
|
||
|
||
# 安装依赖并构建
|
||
npm install
|
||
npm run build
|
||
|
||
# dist 目录即为最终部署文件
|
||
```
|
||
|
||
## Nginx 配置
|
||
|
||
### 1. 安装 Nginx
|
||
|
||
```bash
|
||
# Ubuntu/Debian
|
||
sudo apt update
|
||
sudo apt install nginx
|
||
|
||
# CentOS/RHEL
|
||
sudo yum install nginx
|
||
```
|
||
|
||
### 2. 配置 Nginx
|
||
|
||
复制示例配置文件：
|
||
|
||
```bash
|
||
sudo cp nginx.conf.example /etc/nginx/sites-available/aigc
|
||
```
|
||
|
||
编辑配置文件：
|
||
|
||
```bash
|
||
sudo vim /etc/nginx/sites-available/aigc
|
||
```
|
||
|
||
修改以下内容：
|
||
- `server_name`: 改为你的域名或服务器 IP
|
||
- `root`: 改为实际的 dist 目录路径
|
||
- `proxy_pass`: 确保后端地址正确
|
||
|
||
### 3. 启用配置
|
||
|
||
```bash
|
||
# 创建软链接
|
||
sudo ln -s /etc/nginx/sites-available/aigc /etc/nginx/sites-enabled/
|
||
|
||
# 测试配置
|
||
sudo nginx -t
|
||
|
||
# 重启 Nginx
|
||
sudo systemctl restart nginx
|
||
```
|
||
|
||
### 4. 配置防火墙
|
||
|
||
```bash
|
||
# 允许 HTTP 和 HTTPS
|
||
sudo ufw allow 'Nginx Full'
|
||
|
||
# 或手动开放端口
|
||
sudo ufw allow 80/tcp
|
||
sudo ufw allow 443/tcp
|
||
```
|
||
|
||
## 目录结构
|
||
|
||
部署后的目录结构：
|
||
|
||
```
|
||
/var/www/aigc/
|
||
├── dist/ # 前端静态文件
|
||
│ ├── index.html
|
||
│ ├── assets/
|
||
│ │ ├── index-xxx.js
|
||
│ │ └── index-xxx.css
|
||
│ └── ...
|
||
└── dist.backup.xxx/ # 备份的旧版本（如果有）
|
||
```
|
||
|
||
## 常见问题
|
||
|
||
### 1. API 请求跨域问题
|
||
|
||
**方案一：使用 Nginx 代理（推荐）**
|
||
|
||
在 Nginx 配置中添加：
|
||
|
||
```nginx
|
||
location /api/ {
|
||
proxy_pass http://localhost:20006;
|
||
# ... 其他配置
|
||
}
|
||
```
|
||
|
||
这样前端访问 `/api/xxx` 会自动代理到后端。
|
||
|
||
**方案二：后端配置 CORS**
|
||
|
||
如果前后端分离部署，需要在后端添加 CORS 支持。
|
||
|
||
### 2. 刷新页面 404
|
||
|
||
这是 SPA 应用的常见问题，需要配置 Nginx：
|
||
|
||
```nginx
|
||
location / {
|
||
try_files $uri $uri/ /index.html;
|
||
}
|
||
```
|
||
|
||
### 3. 静态资源加载失败
|
||
|
||
检查 `vite.config.ts` 中的 `base` 配置：
|
||
|
||
```typescript
|
||
export default defineConfig({
|
||
plugins: [vue()],
|
||
base: '/', // 根据实际部署路径调整
|
||
})
|
||
```
|
||
|
||
### 4. 环境变量不生效
|
||
|
||
确保：
|
||
- 环境变量以 `VITE_` 开头
|
||
- 构建时使用正确的环境：`npm run build` 会自动使用 `.env.production`
|
||
- 修改环境变量后需要重新构建
|
||
|
||
### 5. 后端连接失败
|
||
|
||
检查：
|
||
- 后端服务是否运行：`./startup.sh status`
|
||
- 端口是否正确：默认 20006
|
||
- 防火墙是否开放端口：`sudo ufw allow 20006/tcp`
|
||
- `.env.production` 中的地址是否正确
|
||
|
||
## 更新部署
|
||
|
||
### 快速更新
|
||
|
||
```bash
|
||
# 1. 拉取最新代码
|
||
git pull
|
||
|
||
# 2. 重新构建
|
||
npm run build
|
||
|
||
# 3. Nginx 会自动使用新的 dist 文件
|
||
```
|
||
|
||
### 使用脚本更新
|
||
|
||
```bash
|
||
./deploy-to-server.sh user@server /var/www/aigc
|
||
```
|
||
|
||
脚本会自动备份旧版本。
|
||
|
||
## 性能优化
|
||
|
||
### 1. 启用 Gzip 压缩
|
||
|
||
在 Nginx 配置中已包含 gzip 配置。
|
||
|
||
### 2. 配置缓存
|
||
|
||
静态资源已配置 1 年缓存：
|
||
|
||
```nginx
|
||
location ~* \.(jpg|jpeg|png|gif|ico|css|js)$ {
|
||
expires 1y;
|
||
add_header Cache-Control "public, immutable";
|
||
}
|
||
```
|
||
|
||
### 3. 使用 CDN
|
||
|
||
可以将 `dist/assets/` 下的静态资源上传到 CDN。
|
||
|
||
## HTTPS 配置（推荐）
|
||
|
||
### 使用 Let's Encrypt 免费证书
|
||
|
||
```bash
|
||
# 安装 Certbot
|
||
sudo apt install certbot python3-certbot-nginx
|
||
|
||
# 自动配置 HTTPS
|
||
sudo certbot --nginx -d yourdomain.com
|
||
|
||
# 自动续期
|
||
sudo certbot renew --dry-run
|
||
```
|
||
|
||
## 监控和日志
|
||
|
||
### 查看 Nginx 日志
|
||
|
||
```bash
|
||
# 访问日志
|
||
tail -f /var/log/nginx/aigc_access.log
|
||
|
||
# 错误日志
|
||
tail -f /var/log/nginx/aigc_error.log
|
||
```
|
||
|
||
### 查看后端日志
|
||
|
||
```bash
|
||
cd /path/to/backend
|
||
./startup.sh logs
|
||
```
|
||
|
||
## 回滚
|
||
|
||
如果新版本有问题，可以快速回滚：
|
||
|
||
```bash
|
||
cd /var/www/aigc
|
||
rm -rf dist
|
||
mv dist.backup.20231209_143022 dist
|
||
sudo systemctl reload nginx
|
||
```
|
||
|
||
## 开发环境 vs 生产环境
|
||
|
||
| 项目 | 开发环境 | 生产环境 |
|
||
|------|---------|---------|
|
||
| 命令 | `npm run dev` | `npm run build` |
|
||
| 配置文件 | `.env.development` | `.env.production` |
|
||
| API 地址 | `http://localhost:20006` | 实际服务器地址 |
|
||
| 热更新 | ✅ 支持 | ❌ 不支持 |
|
||
| 代码压缩 | ❌ 不压缩 | ✅ 压缩 |
|
||
| Source Map | ✅ 完整 | ❌ 或简化 |
|
||
|
||
## 安全建议
|
||
|
||
1. ✅ 使用 HTTPS
|
||
2. ✅ 配置安全响应头（已在 nginx.conf.example 中）
|
||
3. ✅ 定期更新依赖：`npm audit fix`
|
||
4. ✅ 不要在前端代码中硬编码敏感信息
|
||
5. ✅ 配置 CSP（内容安全策略）
|
||
6. ✅ 定期备份
|
||
|
||
## 故障排查清单
|
||
|
||
- [ ] 后端服务是否运行？
|
||
- [ ] 端口是否正确？
|
||
- [ ] 防火墙是否开放？
|
||
- [ ] Nginx 配置是否正确？
|
||
- [ ] 环境变量是否配置？
|
||
- [ ] 是否重新构建？
|
||
- [ ] 浏览器控制台有无错误？
|
||
- [ ] 网络请求是否成功？
|
||
|
||
## 联系支持
|
||
|
||
如遇问题，请检查：
|
||
1. 浏览器控制台错误信息
|
||
2. Nginx 错误日志
|
||
3. 后端服务日志
|