From ce9348d7644bc7a1c87862f398021aaf70d58d92 Mon Sep 17 00:00:00 2001 From: hanshiyang Date: Tue, 27 Jan 2026 15:54:36 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=B7=BB=E5=8A=A0=E9=9D=9E=20Docker=20?= =?UTF-8?q?=E9=83=A8=E7=BD=B2=E8=AF=B4=E6=98=8E=E5=B9=B6=E6=9B=B4=E6=96=B0?= =?UTF-8?q?=E7=BC=96=E6=8E=92=E6=96=87=E4=BB=B6?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 在 docker-compose.yml 中为 crm-backend 服务添加 image 标签，以便在服务器上直接使用预构建的镜像 - 新增部署说明文档，详细描述了前端静态文件部署、后端镜像构建与导入、服务器容器更新以及升级回滚流程 - 文档提供了完整的目录结构、命令示例和注意事项，便于生产环境运维 --- docker-compose.yml | 1 + 部署说明.md | 188 +++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 189 insertions(+) create mode 100644 部署说明.md diff --git a/docker-compose.yml b/docker-compose.yml index e5b2348..edd56c8 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -37,6 +37,7 @@ services: # 后端服务 crm-backend: + image: by-crm/crm-backend:2026.01.27 build: context: ./backend dockerfile: Dockerfile diff --git a/部署说明.md b/部署说明.md new file mode 100644 index 0000000..5706108 --- /dev/null +++ b/部署说明.md @@ -0,0 +1,188 @@ +# BY-CRM 部署说明（前端非 Docker，后端镜像导入更新） + +本文档描述：前端仅构建出静态文件 dist 部署到服务器；后端在本地构建 Docker 镜像，导出传到服务器并更新运行容器。不使用前端 Docker。 + +## 前置条件 +- 本地开发机：安装 Docker（可使用 Docker Desktop）；可执行 `docker build`、`docker save`。 +- 服务器： + - 已安装 Docker（可执行 `docker load`、`docker run`）。 + - 已安装并运行 Nginx（用于前端静态资源与反向代理后端）。 + - 可访问的 MySQL 数据库（本机或外部），并记录连接信息。 +- 项目结构参考： + - Compose 编排与环境变量见 [docker-compose.yml](file:///e:/EduWeb/by-crm/docker-compose.yml)，后端环境变量在 [L49-L61](file:///e:/EduWeb/by-crm/docker-compose.yml#L49-L61)，日志挂载在 [L63-L65](file:///e:/EduWeb/by-crm/docker-compose.yml#L63-L65)。 + - 后端镜像构建规则见 [backend/Dockerfile](file:///e:/EduWeb/by-crm/backend/Dockerfile)。 + +## 目标机器目录与文件放置 +- 目标主机：`root@1.192.190.177` +- 统一目录：`/boyun/crm` +- 目录结构建议： + - `/boyun/crm/web/`：前端静态文件（dist） + - `/boyun/crm/images/`：后端镜像 tar 包 + - `/boyun/crm/sql/`：MySQL 初始化脚本（来自本项目 `sql` 目录） + - `/boyun/crm/mysql/data/`：MySQL 数据持久化目录（首次为空，便于初始化） + - `/boyun/crm/docker-compose.yml`：编排文件副本（可选，用于参考或后续切换为 Compose） + - `/boyun/crm/部署说明.md`：本文档副本，便于现场运维 + - `/boyun/crm/backend/logs/`：后端日志挂载目录 + - `/boyun/crm/backend/.env`：后端环境变量文件（可选） + - 初始化目录创建： +```bash +ssh root@1.192.190.177 'mkdir -p /boyun/crm/web /boyun/crm/images /boyun/crm/backend/logs /boyun/crm/sql /boyun/crm/mysql/data' +``` + - 同步部署文件： +```bash +scp docker-compose.yml root@1.192.190.177:/boyun/crm/ +scp 部署说明.md root@1.192.190.177:/boyun/crm/ +scp -r sql/* root@1.192.190.177:/boyun/crm/sql/ +``` + +## 一、前端构建与部署（非 Docker） +1. 在本地生成前端静态文件： +```bash +cd frontend +pnpm i # 或 pnpm install +pnpm run build +``` + - 构建产物目录：`frontend/dist/` +2. 将 `dist` 上传到服务器指定目录：`/boyun/crm/web/` + - Windows 可用 `scp` 或图形化工具（WinSCP），示例： +```bash +scp -r frontend/dist/* root@1.192.190.177:/boyun/crm/web/ +``` +3. Nginx 配置（示例）：将静态文件目录作为根目录，并将 `/api` 反向代理到后端容器端口 +```nginx + 详见天翼云 conf.d/nginxeducation-crm.conf +``` + - 重载 Nginx： +```bash +sudo nginx -t && sudo systemctl reload nginx +``` +4. 前端请求后端的地址请与 Nginx 约定一致（推荐前端以 `/api` 为基准路径，避免跨域问题）。 + +## 二、后端：本地构建镜像并导出 +1. 在本地构建后端镜像（建议固定仓库名与版本标签，便于管理与回滚）： +```bash +cd e:/EduWeb/by-crm +docker build -t by-crm/crm-backend:2026.01.27 -f backend/Dockerfile ./backend +``` + - 可将版本号替换为语义化版本（如 `v1.2.3`）或日期。 +2. 导出镜像为 tar： +```bash +docker save -o by-crm-crm-backend-2026.01.27.tar by-crm/crm-backend:2026.01.27 +``` +3. 传输到服务器： +```bash +scp by-crm-crm-backend-2026.01.27.tar root@1.192.190.177:/boyun/crm/images/ +``` + +## 三、服务器：导入镜像并更新容器 +1. 导入镜像： +```bash +docker load -i /boyun/crm/images/by-crm-crm-backend-2026.01.27.tar +docker image ls by-crm/crm-backend +``` +2. 使用 docker-compose.yml 运行（无需在服务器构建）： + - 推荐为 `crm-backend` 指定镜像标签（便于复用已导入镜像），在 `docker-compose.yml` 的该服务中增加： +```yaml +services: + crm-backend: + image: by-crm/crm-backend:2026.01.27 + # build 可保留用于本地开发构建；服务器运行时不构建 + # build: + # context: ./backend + # dockerfile: Dockerfile +``` + - 如不修改仓库文件，亦可在服务器本地编辑 `/boyun/crm/docker-compose.yml` 添加上述 `image` 字段。 + - 运行数据库与后端（前端不使用容器）： +```bash +cd /boyun/crm +docker compose up -d --no-build crm-mysql crm-backend +``` + - `--no-build` 确保服务器不上构建流程，直接使用已导入镜像。 + - 首次启动数据库时，`./sql` 中的脚本会自动执行（取决于 `mysql/data` 是否为空）。 +3. 准备日志目录（与镜像内 `/app/logs` 对应）： +```bash +sudo mkdir -p /boyun/crm/backend/logs +sudo chown -R $(id -u):$(id -g) /boyun/crm/backend/logs +``` +4. 停止并移除旧容器（如存在）： +```bash +docker stop crm-backend || true +docker rm crm-backend || true +``` +5. 运行新容器（示例端口映射为 `9948:8080`，按需调整；环境变量与 Compose 保持一致）： +```bash +docker run -d \ + --name crm-backend \ + --restart always \ + -p 9948:8080 \ + -v /boyun/crm/backend/logs:/app/logs \ + -e SPRING_DATASOURCE_URL="jdbc:mysql://:/crm_db?useUnicode=true&characterEncoding=utf8&serverTimezone=Asia/Shanghai" \ + -e SPRING_DATASOURCE_USERNAME="root" \ + -e SPRING_DATASOURCE_PASSWORD="MySQL123s56" \ + -e JWT_SECRET="请替换为生产环境安全随机密钥" \ + -e JWT_EXPIRATION="86400000" \ + -e SERVER_PORT="8080" \ + -e TZ="Asia/Shanghai" \ + by-crm/crm-backend:2026.01.27 +``` + - 如使用服务器上的 MySQL 容器或托管 MySQL，请将 ``、`` 替换为实际值（例如 `127.0.0.1:3306`）。 + - 后端健康检查地址：`http://127.0.0.1:9948/actuator/health`。 +6. 验证运行状态： +```bash +docker ps +curl -fsSL http://127.0.0.1:9948/actuator/health +docker logs -f crm-backend +``` + - 验证数据库： +```bash +docker logs -f crm-mysql +mysql -h 127.0.0.1 -P 39948 -u root -p +``` + - 确认初始化脚本（位于 `/boyun/crm/sql`）是否执行成功（仅在数据目录为空时）。 + +## 四、升级与回滚流程 +- 升级： + 1) 本地重新 `docker build` 生成新标签镜像 + 2) `docker save` 导出并传输到服务器 + 3) 服务器 `docker load` 导入 + 4) 停掉旧容器，按新标签重新 `docker run` +- 回滚： + - 保留上一版本 tar 文件或确保服务器仍保留旧标签镜像： + ```bash + docker stop crm-backend && docker rm crm-backend + docker run -d ... by-crm/crm-backend: + ``` + +## 五、可选优化 +- 使用 `--env-file` 管理环境变量（避免明文写在命令行）： + - 创建 `/boyun/crm/backend/.env`： +``` +SPRING_DATASOURCE_URL=jdbc:mysql://127.0.0.1:3306/crm_db?useUnicode=true&characterEncoding=utf8&serverTimezone=Asia/Shanghai +SPRING_DATASOURCE_USERNAME=root +SPRING_DATASOURCE_PASSWORD=请替换 +JWT_SECRET=请替换为安全足够的随机字符串 +JWT_EXPIRATION=86400000 +SERVER_PORT=8080 +TZ=Asia/Shanghai +``` + - 运行容器： +```bash +docker run -d --name crm-backend --restart always -p 9948:8080 \ + --env-file /boyun/crm/backend/.env \ + -v /boyun/crm/backend/logs:/app/logs \ + by-crm/crm-backend:2026.01.27 +``` +- 日志轮转：使用 `logrotate` 对 `/boyun/crm/backend/logs` 做轮转。 +- 镜像命名约定：`by-crm/crm-backend:` 或 ``，保持稳定仓库名。 + +## 六、注意事项 +- 安全：严禁将生产环境密钥与数据库密码提交到仓库。使用环境变量或外部密钥管理。 +- 端口：前端 Nginx 默认 `80`；后端容器示例映射 `9948:8080`。如端口冲突，请调整 `-p` 或 Nginx 监听端口。 +- CORS：推荐前端通过 Nginx 将 API 代理为同源路径 `/api`，避免跨域问题。 +- 数据库初始化：若需要初始化脚本，可参考 Compose 的挂载方式 [docker-compose.yml:L27-L33](file:///e:/EduWeb/by-crm/docker-compose.yml#L27-L33)，在服务器上独立管理数据库初始化。 +- 使用 Compose 启动数据库时必须将本项目的 `sql` 目录内容同步到服务器路径 `/boyun/crm/sql/`，并保证 `/boyun/crm/mysql/data/` 在首次启动时为空，以便初始化脚本生效。后续运行不再重复执行。 + +--- +参考文件： +- [docker-compose.yml](file:///e:/EduWeb/by-crm/docker-compose.yml) +- [backend/Dockerfile](file:///e:/EduWeb/by-crm/backend/Dockerfile)