dashboard/DEPLOY.md

# 部署指南

Audio Dashboard 使用 **Docker Compose** 部署：前端为 Nginx 静态站点，后端为 **Node.js** 服务。

## 架构概览

| 服务 | 说明 | 宿主机端口 | 容器内端口 |
|------|------|-----------|-----------|
| 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. 创建目录

```bash
sudo mkdir -p /data/project/dashboard/frontend/dist
sudo mkdir -p /data/projects/source    # X9 OTA 升级包存储
```

### 2. 配置环境变量

在服务器 `/data/project/dashboard/` 创建 `.env`（参考 `.env.example`）：

```bash
cp .env.example .env
# 编辑 .env，填写数据库、JWT、Meilisearch、Redis、AWS 等配置
```

重要说明：

- 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
```

### 4. 验证

```bash
docker compose ps
docker compose logs -f backend

# 健康检查
curl http://localhost:8083/health
```

访问地址：

- 前端：http://服务器 IP:8082
- 后端 API：http://服务器 IP:8083/api/...
- 健康检查：http://服务器 IP:8083/health

---

## 更新部署

### 仅更新前端

```bash
# 本地
cd frontend && pnpm build
./scripts/upload.sh frontend

# 服务器
docker compose restart frontend
```

### 仅更新后端

```bash
# 本地
./scripts/upload.sh backend

# 服务器
docker compose build --no-cache backend
docker compose up -d backend
```

### 一键：构建前端 + 上传 + 服务器部署

```bash
pnpm --dir frontend build && ./scripts/upload.sh all

# 服务器上执行
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/
├── .env                        # 环境变量（仅服务器维护，勿提交 Git）
├── docker-compose.yml
├── backend/
│   ├── Dockerfile
│   ├── package.json
│   ├── pnpm-lock.yaml
│   └── src/
└── frontend/
    ├── 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
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`。