HAOVP/docs/DEPLOY_1PANEL.md

HAOVP 1Panel 单机部署指南

本文档面向一台服务器上的 1Panel 部署。目标是用 1Panel 的容器编排启动后端、基础设施、前端 Nginx，并用 1Panel 网站/OpenResty 对外提供域名访问。

1. 部署结构

默认编排文件：

backend/docker-compose.1panel.yml

配套文件：

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	可选监控

生产环境防火墙建议只放行：

80/tcp
443/tcp
1Panel 面板端口
SSH 端口

不要把 MySQL、Redis、Nacos、RocketMQ、MinIO Console 直接暴露到公网。

如确需临时从外部访问前端容器端口，可在 .env.1panel 中把：

FRONTEND_BIND_ADDR=127.0.0.1

改为：

FRONTEND_BIND_ADDR=0.0.0.0

不建议在生产长期这样配置。

4. 上传项目

在服务器上准备项目目录，例如：

cd /opt
git clone <你的仓库地址> HAOVP
cd /opt/HAOVP/backend

如果通过 1Panel 文件管理上传压缩包，保证目录结构仍然是：

/opt/HAOVP/backend
/opt/HAOVP/frontend

因为 docker-compose.1panel.yml 会从 ../frontend/... 构建前端镜像。

5. 配置环境变量

复制示例文件：

cd /opt/HAOVP/backend
cp .env.1panel.example .env.1panel

必须修改这些值：

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：

openssl rand -base64 32

示例值：

NACOS_AUTH_TOKEN=U0VDUkVUS0VZMTIzNDU2Nzg5MDEyMzQ1Njc4OTAxMjM0NTY3ODkw

国内服务器建议保留默认 Maven 镜像：

MAVEN_MIRROR_URL=https://maven.aliyun.com/repository/public

如果服务器网络能稳定访问 Maven Central，也可以改成：

MAVEN_MIRROR_URL=https://repo.maven.apache.org/maven2

首次部署建议保持：

NACOS_USERNAME=nacos
NACOS_PASSWORD=nacos

原因：Nacos 默认初始化用户是 nacos/nacos。如果想改 Nacos 密码，先部署成功，再进入 Nacos 控制台修改用户密码，并同步更新 .env.1panel 后重启后端微服务。

6. 在 1Panel 创建编排

进入 1Panel：

容器 -> 编排 -> 创建编排

推荐配置：

项	值
名称	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 网站反代

推荐用两个域名：

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. 启动验证

在服务器执行：

cd /opt/HAOVP/backend
docker compose --env-file .env.1panel -f docker-compose.1panel.yml ps

查看关键日志：

docker logs -f haovp-mysql
docker logs -f haovp-nacos
docker logs -f haovp-video-gateway
docker logs -f haovp-video-content

本机健康检查：

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

浏览器访问：

https://www.example.com
https://admin.example.com

Nacos 控制台仅建议本机 SSH 隧道或 1Panel 终端访问：

http://127.0.0.1:8848/nacos

9. 可选启用监控

默认不会启动 Prometheus/Grafana，节省单机资源。

命令行启用：

cd /opt/HAOVP/backend
COMPOSE_PROFILES=monitoring docker compose --env-file .env.1panel -f docker-compose.1panel.yml up -d

1Panel 中可在环境变量里增加：

COMPOSE_PROFILES=monitoring

Grafana 默认本机端口：

http://127.0.0.1:3000

不建议直接公网开放 Grafana。

10. 更新部署

拉取代码后重新构建：

cd /opt/HAOVP
git pull
cd backend
docker compose --env-file .env.1panel -f docker-compose.1panel.yml up -d --build

只重启某个服务：

docker compose --env-file .env.1panel -f docker-compose.1panel.yml restart video-gateway

查看资源占用：

docker stats

11. 数据备份

先加载部署环境变量：

cd /opt/HAOVP/backend
set -a
source .env.1panel
set +a

MySQL：

docker exec haovp-mysql mysqldump -uroot -p"$MYSQL_ROOT_PASSWORD" --all-databases > haovp_mysql_$(date +%F).sql

Redis：

docker exec haovp-redis redis-cli -a "$REDIS_PASSWORD" BGSAVE
docker cp haovp-redis:/data/dump.rdb haovp_redis_$(date +%F).rdb

MinIO：

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 依赖下载失败

如果日志里出现：

Unknown host repo.maven.apache.org
Non-resolvable parent POM

说明后端镜像构建阶段无法访问 Maven Central。1Panel 版后端 Dockerfile 已支持 Maven 镜像源，默认：

MAVEN_MIRROR_URL=https://maven.aliyun.com/repository/public

修改 .env.1panel 后，需要在 1Panel 中重新构建编排。

Nacos 显示 unhealthy

如果 1Panel 日志出现：

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 配置。

如果仍失败，优先查看初始化容器日志：

docker logs --tail 200 haovp-nacos-init

再查看 Nacos 容器内部日志：

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

推荐的检查顺序：

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 不会再次自动执行：

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;
"

如果缺库或缺表，手动补执行初始化：

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 中已有的配置内容还是旧的错误引号。检查当前内容：

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'

正确内容应类似：

          mode: response
          response-body: '{"code":500,"message":"服务不可用，请稍后再试"}'

如果不是这个格式，在 Nacos 控制台修正 video-gateway.yaml 后重启网关：

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 报错类似：

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 版已使用单机配置：

backend/config/rocketmq/broker-1panel.conf
NAMESRV_ADDR=rmqnamesrv:9876

如果仍失败，检查：

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 日志：

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 动态解析；同步配置并重建前端，临时恢复可先执行：

docker restart haovp-frontend-web

如果直连网关仍是 404：

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 配置。

图片或视频无法访问

前端使用：

VITE_MEDIA_BASE_URL=/media/video-platform

前端 Nginx 会把 /media/video-platform/... 转发到 MinIO 的 /video-platform/...。确认 minio-init 已成功创建 bucket：

docker logs haovp-minio-init

Nacos 密码修改后服务启动失败

如果在 Nacos 控制台改了 nacos 用户密码，必须同步修改 .env.1panel：

NACOS_PASSWORD=新密码

然后重启后端服务：

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 参数，例如：

CONTENT_JAVA_OPTS=-Xms128m -Xmx384m
AUTH_JAVA_OPTS=-Xms96m -Xmx192m

同时不要启用 monitoring profile。