dashboard/DEPLOY.md

前端部署指南

📦 部署方式

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

1. 本地构建

Windows:

cd frontend
pnpm build

或者使用脚本:

cd frontend
.\build-and-deploy.bat

Linux/Mac:

cd frontend
pnpm build

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

2. 上传到服务器

将 dist 文件夹上传到服务器的指定目录，例如：

# 在服务器上创建目录
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 配置（不构建镜像）：

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. 启动服务

在服务器上执行：

cd /data/project/dashboard
docker compose up -d

5. 查看日志

# 查看所有服务日志
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

---

🔄 更新部署

仅更新前端

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

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

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

仅更新后端

# 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:

# 停止所有服务
docker compose down

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

Q: 如何查看服务状态

A:

# 查看运行状态
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 配置

---

🚀 快速部署命令汇总

# 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