# 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. 后端服务日志