优化体验，新增多项功能，美化界面
This commit is contained in:
eafonyang
@@ -1,257 +1,268 @@
|
||||
# 前端部署指南
|
||||
# 部署指南
|
||||
|
||||
## 📦 部署方式
|
||||
Audio Dashboard 使用 **Docker Compose** 部署：前端为 Nginx 静态站点，后端为 **Node.js** 服务。
|
||||
|
||||
### 方式一：本地构建后上传（推荐）
|
||||
## 架构概览
|
||||
|
||||
#### 1. 本地构建
|
||||
| 服务 | 说明 | 宿主机端口 | 容器内端口 |
|
||||
|------|------|-----------|-----------|
|
||||
| frontend | Nginx 托管 `frontend/dist` | 8082 | 80 |
|
||||
| backend | Node.js API | 8083 | 8000 |
|
||||
|
||||
- 前端通过 Nginx 将 `/api` 代理到 `http://backend:8000`
|
||||
- 环境变量统一使用项目根目录 **`.env`**（与 `docker-compose.yml` 同级）
|
||||
- **不要**再使用 `backend/.env` 或 Python 虚拟环境
|
||||
|
||||
---
|
||||
|
||||
## 首次部署（服务器准备）
|
||||
|
||||
### 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/
|
||||
sudo mkdir -p /data/projects/source # X9 OTA 升级包存储
|
||||
```
|
||||
|
||||
#### 3. 修改 docker-compose.yml
|
||||
### 2. 配置环境变量
|
||||
|
||||
确保使用简单的 Nginx 配置（不构建镜像）：
|
||||
在服务器 `/data/project/dashboard/` 创建 `.env`（参考 `.env.example`）：
|
||||
|
||||
```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
|
||||
```bash
|
||||
cp .env.example .env
|
||||
# 编辑 .env，填写数据库、JWT、Meilisearch、Redis、AWS 等配置
|
||||
```
|
||||
|
||||
#### 4. 启动服务
|
||||
重要说明：
|
||||
|
||||
- Docker 部署时，Compose 会将容器内 `PORT` 固定为 **8000**，与 Nginx 一致
|
||||
- 正式环境请修改 `JWT_SECRET`、`DASHBOARD_ADMIN_PASSWORD`
|
||||
- 正式环境 S3 通常通过 EC2 **IAM 角色**访问，无需配置 `AWS_ACCESS_KEY_ID`
|
||||
- `.env` **不会**被 `upload.sh` 上传，需在服务器单独维护
|
||||
|
||||
### 3. 上传代码并启动
|
||||
|
||||
见下方「本地构建 + 上传」章节。
|
||||
|
||||
---
|
||||
|
||||
## 本地构建 + 上传（推荐）
|
||||
|
||||
### 1. 本地构建前端
|
||||
|
||||
```bash
|
||||
cd frontend
|
||||
pnpm install
|
||||
pnpm build
|
||||
```
|
||||
|
||||
构建产物位于 `frontend/dist/`。
|
||||
|
||||
### 2. 上传到服务器
|
||||
|
||||
**方式 A：使用上传脚本（推荐）**
|
||||
|
||||
```bash
|
||||
# 上传前端 dist、nginx.conf、后端代码、docker-compose.yml
|
||||
./scripts/upload.sh all
|
||||
|
||||
# 或分别上传
|
||||
./scripts/upload.sh frontend
|
||||
./scripts/upload.sh backend
|
||||
./scripts/upload.sh compose
|
||||
```
|
||||
|
||||
脚本默认上传到 `ubuntu@<服务器>:/data/project/dashboard/`。可在 `scripts/upload.sh` 中修改 `SERVER`、`REMOTE_ROOT`、`SSH_KEY`。
|
||||
|
||||
**方式 B：手动 rsync**
|
||||
|
||||
```bash
|
||||
# 前端
|
||||
rsync -avz --progress frontend/dist/ user@server:/data/project/dashboard/frontend/dist/
|
||||
scp frontend/nginx.conf user@server:/data/project/dashboard/frontend/
|
||||
|
||||
# 后端（Docker 构建所需文件）
|
||||
rsync -avz backend/src/ user@server:/data/project/dashboard/backend/src/
|
||||
scp backend/Dockerfile backend/package.json backend/pnpm-lock.yaml user@server:/data/project/dashboard/backend/
|
||||
|
||||
# Compose
|
||||
scp docker-compose.yml user@server:/data/project/dashboard/
|
||||
```
|
||||
|
||||
### 3. 服务器上构建并启动
|
||||
|
||||
在服务器上执行：
|
||||
```bash
|
||||
cd /data/project/dashboard
|
||||
|
||||
# 首次或依赖变更时
|
||||
docker compose build --no-cache backend
|
||||
|
||||
# 启动 / 更新
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
#### 5. 查看日志
|
||||
### 4. 验证
|
||||
|
||||
```bash
|
||||
# 查看所有服务日志
|
||||
docker compose logs -f
|
||||
|
||||
# 查看前端日志
|
||||
docker compose logs -f frontend
|
||||
|
||||
# 查看后端日志
|
||||
docker compose ps
|
||||
docker compose logs -f backend
|
||||
|
||||
# 健康检查
|
||||
curl http://localhost:8083/health
|
||||
```
|
||||
|
||||
#### 6. 访问应用
|
||||
访问地址：
|
||||
|
||||
- 前端地址：http://服务器 IP:8082
|
||||
- 后端 API：http://服务器 IP:8083
|
||||
- API 文档：http://服务器 IP:8083/docs
|
||||
- 前端：http://服务器 IP:8082
|
||||
- 后端 API：http://服务器 IP:8083/api/...
|
||||
- 健康检查：http://服务器 IP:8083/health
|
||||
|
||||
---
|
||||
|
||||
### 方式二：使用 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
|
||||
# 本地
|
||||
cd frontend && pnpm build
|
||||
./scripts/upload.sh frontend
|
||||
|
||||
# 2. 上传 dist 目录到服务器
|
||||
rsync -avz --progress dist/ user@server:/data/project/dashboard/frontend/dist/
|
||||
|
||||
# 3. 重启前端容器
|
||||
# 服务器
|
||||
docker compose restart frontend
|
||||
```
|
||||
|
||||
### 仅更新后端
|
||||
|
||||
```bash
|
||||
# 1. 上传修改的后端文件到服务器
|
||||
# 本地
|
||||
./scripts/upload.sh backend
|
||||
|
||||
# 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
|
||||
pnpm --dir frontend build && ./scripts/upload.sh all
|
||||
|
||||
# 停止并删除数据卷（谨慎使用）
|
||||
docker compose down -v
|
||||
```
|
||||
|
||||
### Q: 如何查看服务状态
|
||||
A:
|
||||
```bash
|
||||
# 查看运行状态
|
||||
docker compose ps
|
||||
|
||||
# 查看磁盘使用
|
||||
docker system df
|
||||
# 服务器上执行
|
||||
cd /data/project/dashboard && docker compose build --no-cache backend && docker compose up -d
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📂 目录结构
|
||||
## docker-compose.yml 说明
|
||||
|
||||
当前配置要点：
|
||||
|
||||
- **backend**：`env_file: .env` 读取根目录环境变量；`PORT=8000` 覆盖容器内端口
|
||||
- **frontend**：挂载服务器上的 `dist` 与 `nginx.conf`，不构建前端镜像
|
||||
- **日志轮转**：每个服务 `max-size: 10m`，`max-file: 5`
|
||||
- **OTA 卷**：`/data/projects/source` 挂载到后端容器，供 X9 升级包本地存储
|
||||
|
||||
```bash
|
||||
# 修改 compose 后
|
||||
./scripts/upload.sh compose
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 后端部署文件清单
|
||||
|
||||
`docker compose build backend` 需要以下文件：
|
||||
|
||||
```
|
||||
backend/
|
||||
├── Dockerfile
|
||||
├── package.json
|
||||
├── pnpm-lock.yaml
|
||||
└── src/
|
||||
```
|
||||
|
||||
`upload.sh backend` 已包含上述全部文件。
|
||||
|
||||
---
|
||||
|
||||
## 环境变量参考
|
||||
|
||||
完整示例见项目根目录 `.env.example`，主要包括：
|
||||
|
||||
| 分类 | 变量 |
|
||||
|------|------|
|
||||
| 数据库 | `DATABASE_HOST`、`DATABASE_PORT`、`DATABASE_NAME`、`DATABASE_USER`、`DATABASE_PASSWORD` |
|
||||
| 应用 | `APP_NAME`、`APP_ENV` |
|
||||
| 认证 | `JWT_SECRET`、`DASHBOARD_ADMIN_USERNAME`、`DASHBOARD_ADMIN_PASSWORD` |
|
||||
| 搜索 | `MEILISEARCH_URL`、`MEILISEARCH_API_KEY`、`MEILISEARCH_INDEX` |
|
||||
| S3 | `AWS_REGION`、`AWS_S3_OTA_BUCKET`、`AWS_S3_MEASUREMENT_BUCKET` |
|
||||
| OTA | `OTA_X8_PUBLIC_BASE`、`OTA_X9_URL_BASE`、`OTA_UPLOAD_DIR` |
|
||||
| Redis EQ | `REDIS_HOST`、`REDIS_PORT`、`REDIS_PASSWORD`、`REDIS_EQ_DB` |
|
||||
|
||||
---
|
||||
|
||||
## 目录结构（服务器）
|
||||
|
||||
```
|
||||
/data/project/dashboard/
|
||||
├── docker-compose.yml # Docker 编排配置
|
||||
├── .env # 环境变量（仅服务器维护，勿提交 Git）
|
||||
├── docker-compose.yml
|
||||
├── backend/
|
||||
│ ├── Dockerfile # 后端镜像配置
|
||||
│ ├── main.py # 后端主程序
|
||||
│ ├── requirements.txt # Python 依赖
|
||||
│ └── ...
|
||||
│ ├── Dockerfile
|
||||
│ ├── package.json
|
||||
│ ├── pnpm-lock.yaml
|
||||
│ └── src/
|
||||
└── frontend/
|
||||
├── dist/ # 构建产物（上传到这里）
|
||||
│ ├── index.html
|
||||
│ ├── assets/
|
||||
│ └── ...
|
||||
└── nginx.conf # Nginx 配置
|
||||
├── dist/ # 前端构建产物
|
||||
└── nginx.conf
|
||||
|
||||
/data/projects/source/ # X9 OTA 包存储（宿主机）
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🚀 快速部署命令汇总
|
||||
## 常见问题
|
||||
|
||||
### 前端页面空白
|
||||
|
||||
- 检查 `frontend/dist` 是否已上传且路径正确
|
||||
- 浏览器控制台是否有 404 / API 错误
|
||||
- `docker compose logs frontend`
|
||||
|
||||
### API 请求失败
|
||||
|
||||
- `docker compose ps` 确认 backend 为 running
|
||||
- `docker compose logs backend` 查看数据库、Redis、Meilisearch 连接错误
|
||||
- 确认 Nginx 代理目标为 `http://backend:8000`（见 `frontend/nginx.conf`）
|
||||
|
||||
### 后端构建失败（pnpm / Node 版本）
|
||||
|
||||
- 后端镜像基于 `node:22-alpine`，`package.json` 中已固定 `packageManager: pnpm@11.5.2`
|
||||
- 确保上传了 `package.json` 和 `pnpm-lock.yaml`
|
||||
|
||||
### 修改 .env 后不生效
|
||||
|
||||
```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
|
||||
docker compose up -d --force-recreate backend
|
||||
```
|
||||
|
||||
### 停止服务
|
||||
|
||||
```bash
|
||||
docker compose down
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 本地开发（非 Docker）
|
||||
|
||||
```bash
|
||||
# 根目录配置 .env 后
|
||||
cd backend && pnpm install && pnpm start # http://localhost:8083
|
||||
|
||||
cd frontend && pnpm install && pnpm dev # http://localhost:3000，/api 代理到 8083
|
||||
```
|
||||
|
||||
本地开发使用根目录 `.env` 中的 `PORT=8083`；Docker 部署时由 Compose 覆盖为容器内 `8000`。
|
||||
|
||||
Reference in New Issue
Block a user