audio/admin

Fork 0

Files

T

eafonyang d01b0c8f47 优化项目结构

2026-08-13 14:23:01 +08:00

6.4 KiB

Raw Blame History

部署指南

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. 创建目录

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

2. 配置环境变量

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

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. 本地构建前端

cd frontend
pnpm install
pnpm build

构建产物位于 frontend/dist/。

2. 上传到服务器

方式 A：使用上传脚本（推荐）

# 上传前端 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

# 前端
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. 服务器上构建并启动

cd /data/project/dashboard

# 首次或依赖变更时
docker compose build --no-cache backend

# 启动 / 更新
docker compose up -d

4. 验证

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

更新部署

仅更新前端

# 本地
cd frontend && pnpm build
../deploy/upload.sh frontend

# 服务器
docker compose restart frontend

仅更新后端

# 本地
../deploy/upload.sh backend

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

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

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 升级包本地存储

# 修改 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 后不生效

docker compose up -d --force-recreate backend

停止服务

docker compose down

本地开发（非 Docker）

# 根目录配置 .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。

6.4 KiB Raw Blame History Unescape Escape