dashboard/DEPLOY.md

# 前端部署指南

## 📦 部署方式

### 方式一：本地构建后上传（推荐）

#### 1. 本地构建

**Windows:**
```bash
cd frontend
pnpm build
```

**或者使用脚本:**
```bash
cd frontend
.\build-and-deploy.bat
```

**Linux/Mac:**
```bash
cd frontend
pnpm build
```

构建完成后会在 `frontend/dist` 目录生成静态文件。

#### 2. 上传到服务器

将 `dist` 文件夹上传到服务器的指定目录，例如：
```bash
# 在服务器上创建目录
sudo mkdir -p /data/project/dashboard/frontend/dist

# 上传文件（使用 scp、rsync 或 FTP 工具）
# 示例：使用 scp
scp -r dist/* user@server:/data/project/dashboard/frontend/dist/

# 或使用 rsync（推荐）
rsync -avz --progress dist/ user@server:/data/project/dashboard/frontend/dist/
```

#### 3. 修改 docker-compose.yml

确保使用简单的 Nginx 配置（不构建镜像）：

```yaml
version: '3.8'

services:
  backend:
    build:
      context: ./backend
      dockerfile: Dockerfile
    container_name: audio-dashboard-backend
    environment:
      - DATABASE_HOST=${DATABASE_HOST:-localhost}
      - DATABASE_PORT=${DATABASE_PORT:-3306}
      - DATABASE_NAME=${DATABASE_NAME:-audio}
      - DATABASE_USER=${DATABASE_USER:-root}
      - DATABASE_PASSWORD=${DATABASE_PASSWORD:-root123}
      - APP_NAME=${APP_NAME:-Audio Dashboard API}
      - DEBUG=${DEBUG:-True}
      - MEILISEARCH_URL=${MEILISEARCH_URL:-http://ec2-18-184-205-87.eu-central-1.compute.amazonaws.com:7700}
      - MEILISEARCH_API_KEY=${MEILISEARCH_API_KEY:-young9#!UJsD219921031}
      - MEILISEARCH_INDEX=${MEILISEARCH_INDEX:-models}
    ports:
      - "8083:8000"
    restart: unless-stopped
    networks:
      - audio-network

  frontend:
    image: nginx:alpine
    container_name: audio-dashboard-frontend
    ports:
      - "8082:80"
    volumes:
      - ./frontend/dist:/usr/share/nginx/html:ro
      - ./frontend/nginx.conf:/etc/nginx/conf.d/default.conf:ro
    depends_on:
      - backend
    restart: unless-stopped
    networks:
      - audio-network

networks:
  audio-network:
    driver: bridge
```

#### 4. 启动服务

在服务器上执行：
```bash
cd /data/project/dashboard
docker compose up -d
```

#### 5. 查看日志

```bash
# 查看所有服务日志
docker compose logs -f

# 查看前端日志
docker compose logs -f frontend

# 查看后端日志
docker compose logs -f backend
```

#### 6. 访问应用

- 前端地址：http://服务器 IP:8082
- 后端 API：http://服务器 IP:8083
- API 文档：http://服务器 IP:8083/docs

---

### 方式二：使用 Docker 构建（备选）

如果你想让 Docker 自动构建前端：

1. 上传整个 `frontend` 目录到服务器
2. 使用原始的 `docker-compose.yml`（包含 `build` 配置）
3. 执行 `docker compose build --no-cache frontend`
4. 执行 `docker compose up -d`

---

## 🔄 更新部署

### 仅更新前端

```bash
# 1. 本地重新构建
cd frontend
pnpm build

# 2. 上传 dist 目录到服务器
rsync -avz --progress dist/ user@server:/data/project/dashboard/frontend/dist/

# 3. 重启前端容器
docker compose restart frontend
```

### 仅更新后端

```bash
# 1. 上传修改的后端文件到服务器

# 2. 重新构建后端镜像
docker compose build --no-cache backend

# 3. 重启后端容器
docker compose up -d backend
```

---

## 📝 注意事项

1. **确保后端端口正确**
   - 后端服务运行在 8083 端口
   - Nginx 配置中已设置代理到 `http://backend:8000`（容器内部）

2. **文件权限**
   - 确保 dist 目录有读取权限
   - Nginx 容器需要能读取 dist 目录中的文件

3. **跨域问题**
   - Nginx 已配置 `/api` 代理，前端请求会自动转发到后端
   - 不需要额外配置 CORS

4. **缓存问题**
   - 静态资源已配置长期缓存（1 年）
   - 更新后如果浏览器缓存未更新，可以强制刷新（Ctrl+F5）

---

## 🛠️ 常见问题

### Q: 前端页面空白
A: 打开浏览器控制台查看错误，可能是：
- 后端服务未启动
- API 代理配置错误
- 静态文件路径错误

### Q: API 请求失败
A: 检查：
- 后端容器是否正常运行：`docker compose ps`
- 后端日志是否有错误：`docker compose logs backend`
- 网络连接是否正常

### Q: 如何停止服务
A: 
```bash
# 停止所有服务
docker compose down

# 停止并删除数据卷（谨慎使用）
docker compose down -v
```

### Q: 如何查看服务状态
A:
```bash
# 查看运行状态
docker compose ps

# 查看磁盘使用
docker system df
```

---

## 📂 目录结构

```
/data/project/dashboard/
├── docker-compose.yml          # Docker 编排配置
├── backend/
│   ├── Dockerfile              # 后端镜像配置
│   ├── main.py                 # 后端主程序
│   ├── requirements.txt        # Python 依赖
│   └── ...
└── frontend/
    ├── dist/                   # 构建产物（上传到这里）
    │   ├── index.html
    │   ├── assets/
    │   └── ...
    └── nginx.conf              # Nginx 配置
```

---

## 🚀 快速部署命令汇总

```bash
# 1. 本地构建
cd frontend && pnpm build

# 2. 上传到服务器
rsync -avz --progress dist/ user@server:/data/project/dashboard/frontend/dist/

# 3. 在服务器上启动
cd /data/project/dashboard
docker compose up -d

# 4. 查看状态
docker compose ps

# 5. 查看日志
docker compose logs -f
```