Toys-A
30c17f01e9
- Align deployment guidance with the current three-node Compose topology - Document the current frontend architecture and development workflow - Replace the stale API list with a controller-based route index
578 lines
16 KiB
Markdown
578 lines
16 KiB
Markdown
# HAOVP 1Panel 单机部署指南
|
||
|
||
本文档面向一台服务器上的 1Panel 部署。目标是用 1Panel 的容器编排启动后端、基础设施、前端 Nginx，并用 1Panel 网站/OpenResty 对外提供域名访问。
|
||
|
||
## 1. 部署结构
|
||
|
||
默认编排文件：
|
||
|
||
```text
|
||
backend/docker-compose.1panel.yml
|
||
```
|
||
|
||
配套文件：
|
||
|
||
```text
|
||
backend/.env.1panel.example
|
||
backend/Dockerfile.service.1panel
|
||
backend/config/rocketmq/broker-1panel.conf
|
||
frontend/video-frontend-web/Dockerfile.1panel
|
||
frontend/video-frontend-web/deploy/nginx.1panel.conf
|
||
frontend/video-frontend-admin/Dockerfile.1panel
|
||
frontend/video-frontend-admin/deploy/nginx.1panel.conf
|
||
```
|
||
|
||
默认服务分层：
|
||
|
||
| 层级 | 服务 |
|
||
| --- | --- |
|
||
| 基础设施 | MySQL, Redis, Redis Sentinel, Nacos, RocketMQ, MinIO, Sentinel Dashboard |
|
||
| 后端 | video-gateway, video-auth, video-user, video-content, video-comment, video-recommend, video-admin |
|
||
| 前端 | frontend-web, frontend-admin |
|
||
| 可选监控 | Prometheus, Grafana, exporters，默认不启动 |
|
||
|
||
## 2. 服务器要求
|
||
|
||
建议配置：
|
||
|
||
| 用途 | 建议 |
|
||
| --- | --- |
|
||
| CPU | 最低 4 核，建议 8 核 |
|
||
| 内存 | 最低 8 GB，建议 16 GB |
|
||
| 磁盘 | 最低 80 GB，视频上传环境建议更大 |
|
||
| 系统 | Debian 12 / Ubuntu 22.04+ / CentOS Stream 类系统 |
|
||
|
||
1Panel 需已安装 Docker 和 OpenResty。首次构建后端镜像会下载 Maven 依赖，耗时较长。
|
||
|
||
## 3. 端口策略
|
||
|
||
1Panel 版默认不直接占用公网 `80/443`，避免和 1Panel OpenResty 冲突。
|
||
|
||
默认端口绑定：
|
||
|
||
| 服务 | 宿主机绑定 | 说明 |
|
||
| --- | --- | --- |
|
||
| 用户前端 | `127.0.0.1:18080` | 给 1Panel 网站反代 |
|
||
| 管理前端 | `127.0.0.1:18081` | 给 1Panel 网站反代 |
|
||
| API Gateway | `127.0.0.1:9000` | 调试用，不建议公网开放 |
|
||
| Nacos | `127.0.0.1:8848` | 控制台，仅本机 |
|
||
| MinIO API | `127.0.0.1:9100` | 对象存储 API，仅本机 |
|
||
| MinIO Console | `127.0.0.1:9101` | 控制台，仅本机 |
|
||
| Sentinel | `127.0.0.1:8880` | 控制台，仅本机 |
|
||
| Prometheus | `127.0.0.1:9090` | 可选监控 |
|
||
| Grafana | `127.0.0.1:3000` | 可选监控 |
|
||
|
||
生产环境防火墙建议只放行：
|
||
|
||
```text
|
||
80/tcp
|
||
443/tcp
|
||
1Panel 面板端口
|
||
SSH 端口
|
||
```
|
||
|
||
不要把 MySQL、Redis、Nacos、RocketMQ、MinIO Console 直接暴露到公网。
|
||
|
||
如确需临时从外部访问前端容器端口，可在 `.env.1panel` 中把：
|
||
|
||
```env
|
||
FRONTEND_BIND_ADDR=127.0.0.1
|
||
```
|
||
|
||
改为：
|
||
|
||
```env
|
||
FRONTEND_BIND_ADDR=0.0.0.0
|
||
```
|
||
|
||
不建议在生产长期这样配置。
|
||
|
||
## 4. 上传项目
|
||
|
||
在服务器上准备项目目录，例如：
|
||
|
||
```bash
|
||
cd /opt
|
||
git clone <你的仓库地址> HAOVP
|
||
cd /opt/HAOVP/backend
|
||
```
|
||
|
||
如果通过 1Panel 文件管理上传压缩包，保证目录结构仍然是：
|
||
|
||
```text
|
||
/opt/HAOVP/backend
|
||
/opt/HAOVP/frontend
|
||
```
|
||
|
||
因为 `docker-compose.1panel.yml` 会从 `../frontend/...` 构建前端镜像。
|
||
|
||
## 5. 配置环境变量
|
||
|
||
复制示例文件：
|
||
|
||
```bash
|
||
cd /opt/HAOVP/backend
|
||
cp .env.1panel.example .env.1panel
|
||
```
|
||
|
||
必须修改这些值：
|
||
|
||
```env
|
||
MYSQL_ROOT_PASSWORD=强密码
|
||
MYSQL_APP_PASSWORD=强密码
|
||
REDIS_PASSWORD=强密码
|
||
MINIO_SECRET_KEY=强密码
|
||
USER_JWT_SECRET=至少32字节随机字符串
|
||
ADMIN_JWT_SECRET=至少32字节随机字符串
|
||
SERVICE_AUTH_TOKEN=至少32字节随机字符串
|
||
ADMIN_INIT_PASSWORD=后台管理员初始密码
|
||
NACOS_AUTH_TOKEN=Base64编码且解码后至少32字节的随机字符串
|
||
GRAFANA_ADMIN_PASSWORD=强密码
|
||
```
|
||
|
||
生成 Nacos token：
|
||
|
||
```bash
|
||
openssl rand -base64 32
|
||
```
|
||
|
||
示例值：
|
||
|
||
```env
|
||
NACOS_AUTH_TOKEN=U0VDUkVUS0VZMTIzNDU2Nzg5MDEyMzQ1Njc4OTAxMjM0NTY3ODkw
|
||
```
|
||
|
||
国内服务器建议保留默认 Maven 镜像：
|
||
|
||
```env
|
||
MAVEN_MIRROR_URL=https://maven.aliyun.com/repository/public
|
||
```
|
||
|
||
如果服务器网络能稳定访问 Maven Central，也可以改成：
|
||
|
||
```env
|
||
MAVEN_MIRROR_URL=https://repo.maven.apache.org/maven2
|
||
```
|
||
|
||
首次部署建议保持：
|
||
|
||
```env
|
||
NACOS_USERNAME=nacos
|
||
NACOS_PASSWORD=nacos
|
||
```
|
||
|
||
原因：Nacos 默认初始化用户是 `nacos/nacos`。如果想改 Nacos 密码，先部署成功，再进入 Nacos 控制台修改用户密码，并同步更新 `.env.1panel` 后重启后端微服务。
|
||
|
||
## 6. 在 1Panel 创建编排
|
||
|
||
进入 1Panel：
|
||
|
||
```text
|
||
容器 -> 编排 -> 创建编排
|
||
```
|
||
|
||
推荐配置：
|
||
|
||
| 项 | 值 |
|
||
| --- | --- |
|
||
| 名称 | `haovp-1panel` |
|
||
| 工作目录 | `/opt/HAOVP/backend` |
|
||
| Compose 文件 | `docker-compose.1panel.yml` |
|
||
| 环境变量文件 | `.env.1panel` |
|
||
|
||
创建后启动编排。
|
||
|
||
首次构建会执行：
|
||
|
||
| 镜像 | 构建内容 |
|
||
| --- | --- |
|
||
| 后端微服务 | Maven 多阶段构建 |
|
||
| 用户前端 | Node 构建 Vue/Vite，然后 Nginx 托管 |
|
||
| 管理前端 | Node 构建 Vue/Vite，然后 Nginx 托管 |
|
||
| Sentinel Dashboard | 下载并打包 Sentinel Dashboard |
|
||
|
||
如果服务器网络访问 Maven/npm/Docker Hub 较慢，首次构建可能需要较长时间。
|
||
|
||
## 7. 配置 1Panel 网站反代
|
||
|
||
推荐用两个域名：
|
||
|
||
```text
|
||
www.example.com -> 用户端
|
||
admin.example.com -> 管理端
|
||
```
|
||
|
||
### 用户端
|
||
|
||
在 1Panel 创建反向代理网站：
|
||
|
||
| 项 | 值 |
|
||
| --- | --- |
|
||
| 主域名 | `www.example.com` |
|
||
| 代理地址 | `http://127.0.0.1:18080` |
|
||
|
||
### 管理端
|
||
|
||
在 1Panel 创建反向代理网站：
|
||
|
||
| 项 | 值 |
|
||
| --- | --- |
|
||
| 主域名 | `admin.example.com` |
|
||
| 代理地址 | `http://127.0.0.1:18081` |
|
||
|
||
然后在两个网站里申请 HTTPS 证书。
|
||
|
||
前端容器内部已经处理：
|
||
|
||
| 路径 | 转发目标 |
|
||
| --- | --- |
|
||
| 用户端 `/api/*` | `video-gateway:9000/*` |
|
||
| 管理端 `/api/admin/*` | `video-gateway:9000/admin/*` |
|
||
| `/media/*` | `minio:9000/*` |
|
||
|
||
所以 1Panel OpenResty 只需要代理到前端容器端口，不需要再单独配置 `/api`。
|
||
|
||
## 8. 启动验证
|
||
|
||
在服务器执行：
|
||
|
||
```bash
|
||
cd /opt/HAOVP/backend
|
||
docker compose --env-file .env.1panel -f docker-compose.1panel.yml ps
|
||
```
|
||
|
||
查看关键日志：
|
||
|
||
```bash
|
||
docker logs -f haovp-mysql
|
||
docker logs -f haovp-nacos
|
||
docker logs -f haovp-video-gateway
|
||
docker logs -f haovp-video-content
|
||
```
|
||
|
||
本机健康检查：
|
||
|
||
```bash
|
||
curl http://127.0.0.1:18080/health
|
||
curl http://127.0.0.1:18081/health
|
||
curl http://127.0.0.1:9000/actuator/health
|
||
```
|
||
|
||
浏览器访问：
|
||
|
||
```text
|
||
https://www.example.com
|
||
https://admin.example.com
|
||
```
|
||
|
||
Nacos 控制台仅建议本机 SSH 隧道或 1Panel 终端访问：
|
||
|
||
```text
|
||
http://127.0.0.1:8848/nacos
|
||
```
|
||
|
||
## 9. 可选启用监控
|
||
|
||
默认不会启动 Prometheus/Grafana，节省单机资源。
|
||
|
||
命令行启用：
|
||
|
||
```bash
|
||
cd /opt/HAOVP/backend
|
||
COMPOSE_PROFILES=monitoring docker compose --env-file .env.1panel -f docker-compose.1panel.yml up -d
|
||
```
|
||
|
||
1Panel 中可在环境变量里增加：
|
||
|
||
```env
|
||
COMPOSE_PROFILES=monitoring
|
||
```
|
||
|
||
Grafana 默认本机端口：
|
||
|
||
```text
|
||
http://127.0.0.1:3000
|
||
```
|
||
|
||
不建议直接公网开放 Grafana。
|
||
|
||
## 10. 更新部署
|
||
|
||
拉取代码后重新构建：
|
||
|
||
```bash
|
||
cd /opt/HAOVP
|
||
git pull
|
||
cd backend
|
||
docker compose --env-file .env.1panel -f docker-compose.1panel.yml up -d --build
|
||
```
|
||
|
||
只重启某个服务：
|
||
|
||
```bash
|
||
docker compose --env-file .env.1panel -f docker-compose.1panel.yml restart video-gateway
|
||
```
|
||
|
||
查看资源占用：
|
||
|
||
```bash
|
||
docker stats
|
||
```
|
||
|
||
## 11. 数据备份
|
||
|
||
先加载部署环境变量：
|
||
|
||
```bash
|
||
cd /opt/HAOVP/backend
|
||
set -a
|
||
source .env.1panel
|
||
set +a
|
||
```
|
||
|
||
MySQL：
|
||
|
||
```bash
|
||
docker exec haovp-mysql mysqldump -uroot -p"$MYSQL_ROOT_PASSWORD" --all-databases > haovp_mysql_$(date +%F).sql
|
||
```
|
||
|
||
Redis：
|
||
|
||
```bash
|
||
docker exec haovp-redis redis-cli -a "$REDIS_PASSWORD" BGSAVE
|
||
docker cp haovp-redis:/data/dump.rdb haovp_redis_$(date +%F).rdb
|
||
```
|
||
|
||
MinIO：
|
||
|
||
```bash
|
||
docker run --rm --network haovp-1panel_haovp-network -v "$PWD/backup:/backup" minio/mc sh -c \
|
||
"mc alias set local http://minio:9000 $MINIO_ACCESS_KEY $MINIO_SECRET_KEY && mc mirror local/$MINIO_BUCKET /backup/$MINIO_BUCKET"
|
||
```
|
||
|
||
也可以直接备份 Docker volume，但数据库类服务建议优先使用逻辑备份。
|
||
|
||
## 12. 常见问题
|
||
|
||
### 首次启动很慢
|
||
|
||
后端镜像会在 Docker 构建阶段执行 Maven 构建，前端镜像会执行 npm 构建。国内服务器建议提前配置 Docker、Maven、npm 镜像源，或在 CI 中构建镜像后推送到私有镜像仓库。
|
||
|
||
### Maven 依赖下载失败
|
||
|
||
如果日志里出现：
|
||
|
||
```text
|
||
Unknown host repo.maven.apache.org
|
||
Non-resolvable parent POM
|
||
```
|
||
|
||
说明后端镜像构建阶段无法访问 Maven Central。1Panel 版后端 Dockerfile 已支持 Maven 镜像源，默认：
|
||
|
||
```env
|
||
MAVEN_MIRROR_URL=https://maven.aliyun.com/repository/public
|
||
```
|
||
|
||
修改 `.env.1panel` 后，需要在 1Panel 中重新构建编排。
|
||
|
||
### Nacos 显示 unhealthy
|
||
|
||
如果 1Panel 日志出现：
|
||
|
||
```text
|
||
dependency failed to start: container haovp-nacos is unhealthy
|
||
```
|
||
|
||
新版编排不再让业务服务等待 Nacos `healthy`，也不再给 Nacos 配置 Docker healthcheck。这样可以避免 1Panel 因 Nacos 启动慢而判定整个编排失败。同步新版 `docker-compose.1panel.yml` 后，需要删除失败编排或重新创建容器，让新的依赖策略生效。
|
||
|
||
现在编排里新增了 `haovp-nacos-init` 一次性初始化容器。它会先创建 `nacos_config` 库和表，再决定是否导入默认 Nacos 配置。
|
||
|
||
如果仍失败，优先查看初始化容器日志：
|
||
|
||
```bash
|
||
docker logs --tail 200 haovp-nacos-init
|
||
```
|
||
|
||
再查看 Nacos 容器内部日志：
|
||
|
||
```bash
|
||
docker logs --tail 200 haovp-nacos
|
||
```
|
||
|
||
重点检查：
|
||
|
||
| 问题 | 处理 |
|
||
| --- | --- |
|
||
| `NACOS_AUTH_TOKEN` 相关报错 | 确认 `.env.1panel` 中 `NACOS_AUTH_TOKEN` 是 Base64，且解码后至少 32 字节 |
|
||
| `No DataSource set` | 先确认服务器上的 `../backend/config/nacos/application-1panel.properties` 是“文件”而不是目录，再确认它被挂载到 `/home/nacos/conf/application.properties`，然后看 `haovp-nacos-init` 是否成功完成 |
|
||
| 数据库连接失败 | 确认 `haovp-mysql` 正常，且 `haovp-nacos-init` 能连上 MySQL |
|
||
| 业务服务短暂报 `nacos:9848 Connection refused` | Nacos 2.x 客户端会连接 `8848 + 1000 = 9848` 的 gRPC 端口。启动早期短暂失败后出现 `Success to connect a server [nacos:8848]` 即为自动恢复 |
|
||
| 端口占用 | 确认宿主机 `8848` 未被其他服务占用，或修改 `NACOS_HTTP_PORT` |
|
||
|
||
推荐的检查顺序：
|
||
|
||
```bash
|
||
ls -l /opt/HAOVP/backend/config/nacos/application-1panel.properties
|
||
docker inspect haovp-nacos --format '{{range .Mounts}}{{println .Source "->" .Destination}}{{end}}'
|
||
docker logs --tail 200 haovp-nacos-init
|
||
docker rm -f haovp-nacos
|
||
docker rm -f haovp-nacos-init
|
||
docker compose --env-file .env.1panel -f docker-compose.1panel.yml up -d --force-recreate nacos
|
||
docker logs --tail 200 haovp-nacos
|
||
```
|
||
|
||
如果 `application-1panel.properties` 在服务器上不存在，Docker 可能会把挂载源当成目录处理，Nacos 就还是读不到数据源配置。
|
||
|
||
如果使用了编排里的 `JAVA_OPT_EXT` 兜底，Nacos 启动日志的 `exec java ...` 行里应出现 `--nacos.plugin.datasource.db.url.0=jdbc:mysql://mysql:3306/nacos_config...`。Nacos Docker 启动脚本会把 `JAVA_OPT_EXT` 追加到 `-jar nacos-server.jar` 后面，所以这里必须按 Spring Boot 命令行参数传入。
|
||
|
||
如果挂载和启动参数都正确，但仍然是 `No DataSource set`，继续检查 MySQL 里的 Nacos 库表。1Panel 反复创建编排时，`mysql_data` volume 如果已经存在，`/docker-entrypoint-initdb.d/` 下的初始化 SQL 不会再次自动执行：
|
||
|
||
```bash
|
||
cd /opt/HAOVP/backend
|
||
set -a
|
||
source .env.1panel
|
||
set +a
|
||
|
||
docker exec haovp-mysql mysql -uroot -p"$MYSQL_ROOT_PASSWORD" -e "
|
||
SHOW DATABASES LIKE 'nacos_config';
|
||
SELECT TABLE_NAME FROM information_schema.TABLES
|
||
WHERE TABLE_SCHEMA='nacos_config'
|
||
AND TABLE_NAME IN ('config_info','config_info_beta','users','roles');
|
||
SELECT COUNT(*) AS config_count FROM nacos_config.config_info;
|
||
"
|
||
```
|
||
|
||
如果缺库或缺表，手动补执行初始化：
|
||
|
||
```bash
|
||
docker exec -i haovp-mysql mysql --default-character-set=utf8mb4 -uroot -p"$MYSQL_ROOT_PASSWORD" < ./sql/nacos-schema.sql
|
||
docker exec -i haovp-mysql mysql --default-character-set=utf8mb4 -uroot -p"$MYSQL_ROOT_PASSWORD" --force nacos_config < ./sql/nacos-config-init.sql
|
||
docker rm -f haovp-nacos
|
||
docker compose --env-file .env.1panel -f docker-compose.1panel.yml up -d --force-recreate nacos
|
||
```
|
||
|
||
如果业务服务日志出现 `org.yaml.snakeyaml.parser.ParserException`，并指向 `video-gateway.yaml` 的 `response-body`，说明 Nacos 中已有的配置内容还是旧的错误引号。检查当前内容：
|
||
|
||
```bash
|
||
docker exec haovp-mysql mysql --default-character-set=utf8mb4 -uroot -p"$MYSQL_ROOT_PASSWORD" -N -s -e "SELECT content FROM nacos_config.config_info WHERE data_id='video-gateway.yaml';" | sed -n '50,62p'
|
||
```
|
||
|
||
正确内容应类似：
|
||
|
||
```yaml
|
||
mode: response
|
||
response-body: '{"code":500,"message":"服务不可用，请稍后再试"}'
|
||
```
|
||
|
||
如果不是这个格式，在 Nacos 控制台修正 `video-gateway.yaml` 后重启网关：
|
||
|
||
```bash
|
||
docker restart haovp-video-gateway
|
||
curl -i "http://127.0.0.1:${GATEWAY_HTTP_PORT:-9000}/recommend/home?page=1&size=12"
|
||
```
|
||
|
||
### 拉取 `haovp/video-*` 镜像失败
|
||
|
||
如果 1Panel 报错类似：
|
||
|
||
```text
|
||
pull access denied for haovp/video-auth
|
||
```
|
||
|
||
说明当前编排文件里仍然带有旧版本地构建镜像名。1Panel 会先按 `image:` 拉取远程镜像，而 `haovp/video-*` 并不是公开镜像仓库。
|
||
|
||
解决方式：
|
||
|
||
1. 使用新版 `../backend/docker-compose.1panel.yml`。
|
||
2. 确认 `video-auth`、`video-user`、`video-content`、`frontend-web` 等本地构建服务只有 `build:`，没有 `image: haovp/...`。
|
||
3. 在 1Panel 中重新加载编排文件后再启动。
|
||
|
||
### 后端连接 RocketMQ 失败
|
||
|
||
1Panel 版已使用单机配置：
|
||
|
||
```text
|
||
backend/config/rocketmq/broker-1panel.conf
|
||
NAMESRV_ADDR=rmqnamesrv:9876
|
||
```
|
||
|
||
如果仍失败，检查：
|
||
|
||
```bash
|
||
docker logs haovp-rmqnamesrv
|
||
docker logs haovp-rmqbroker
|
||
docker logs haovp-video-content
|
||
```
|
||
|
||
### 前端接口 404
|
||
|
||
确认前端环境变量没有改错：
|
||
|
||
| 前端 | 构建参数 |
|
||
| --- | --- |
|
||
| 用户端 | `VITE_API_BASE_URL=/api` |
|
||
| 管理端 | `VITE_API_BASE_URL=/api/admin` |
|
||
|
||
前端 Nginx 会把用户端 `/api/auth/login` 转发为网关 `/auth/login`，把管理端 `/api/admin/auth/login` 转发为网关 `/admin/auth/login`。
|
||
|
||
### 前端接口 502
|
||
|
||
如果 `curl http://127.0.0.1:${WEB_HTTP_PORT:-18180}/health` 正常，但 `/api/...` 返回 `502 Bad Gateway`，先看前端 Nginx 日志：
|
||
|
||
```bash
|
||
docker logs --tail 120 haovp-frontend-web
|
||
```
|
||
|
||
如果出现 `connect() failed (111: Connection refused) while connecting to upstream`，且 upstream 指向旧的 Docker 内网 IP，说明前端 Nginx 缓存了重建前的 gateway 地址。新版 `nginx.1panel.conf` 已使用 Docker DNS 动态解析；同步配置并重建前端，临时恢复可先执行：
|
||
|
||
```bash
|
||
docker restart haovp-frontend-web
|
||
```
|
||
|
||
如果直连网关仍是 404：
|
||
|
||
```bash
|
||
curl -i "http://127.0.0.1:${GATEWAY_HTTP_PORT:-9000}/recommend/home?page=1&size=12"
|
||
```
|
||
|
||
返回 `No static resource recommend/home` 时，表示 gateway 没加载到 `/recommend/**` 路由，优先按上面的 `video-gateway.yaml` 检查 Nacos 配置。
|
||
|
||
### 图片或视频无法访问
|
||
|
||
前端使用：
|
||
|
||
```text
|
||
VITE_MEDIA_BASE_URL=/media/video-platform
|
||
```
|
||
|
||
前端 Nginx 会把 `/media/video-platform/...` 转发到 MinIO 的 `/video-platform/...`。确认 `minio-init` 已成功创建 bucket：
|
||
|
||
```bash
|
||
docker logs haovp-minio-init
|
||
```
|
||
|
||
### Nacos 密码修改后服务启动失败
|
||
|
||
如果在 Nacos 控制台改了 `nacos` 用户密码，必须同步修改 `.env.1panel`：
|
||
|
||
```env
|
||
NACOS_PASSWORD=新密码
|
||
```
|
||
|
||
然后重启后端服务：
|
||
|
||
```bash
|
||
docker compose --env-file .env.1panel -f docker-compose.1panel.yml restart video-gateway video-auth video-user video-content video-comment video-recommend video-admin
|
||
```
|
||
|
||
### 内存不足
|
||
|
||
降低 `.env.1panel` 中各服务 JVM 参数，例如：
|
||
|
||
```env
|
||
CONTENT_JAVA_OPTS=-Xms128m -Xmx384m
|
||
AUTH_JAVA_OPTS=-Xms96m -Xmx192m
|
||
```
|
||
|
||
同时不要启用 `monitoring` profile。
|