eafonyang
269 lines
6.4 KiB
Markdown
269 lines
6.4 KiB
Markdown
# 部署指南
|
||
|
||
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
|
||
../deploy/upload.sh all
|
||
|
||
# 或分别上传
|
||
../deploy/upload.sh frontend
|
||
../deploy/upload.sh backend
|
||
../deploy/upload.sh compose
|
||
```
|
||
|
||
脚本默认上传到 `ubuntu@<服务器>:/data/project/dashboard/`。可在仓库根目录 `deploy/upload.sh` 中修改 `SERVER`、`REMOTE_ROOT`、`SSH_KEY`（www 产物用同一脚本的 `www` 目标上传）。
|
||
|
||
**方式 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
|
||
../deploy/upload.sh frontend
|
||
|
||
# 服务器
|
||
docker compose restart frontend
|
||
```
|
||
|
||
### 仅更新后端
|
||
|
||
```bash
|
||
# 本地
|
||
../deploy/upload.sh backend
|
||
|
||
# 服务器
|
||
docker compose build --no-cache backend
|
||
docker compose up -d backend
|
||
```
|
||
|
||
### 一键：构建前端 + 上传 + 服务器部署
|
||
|
||
```bash
|
||
pnpm --dir frontend build && ../deploy/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 后
|
||
../deploy/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`。
|