by-crm/部署说明.md

# 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 --no-cache -t by-crm/crm-backend:2026.01.27 -f backend/Dockerfile ./backend
```
   - 可将版本号替换为语义化版本（如 `v1.2.3`）或日期。
   - 应用的数据源配置已改为优先读取环境变量，并默认使用 Docker 服务名 `crm-mysql` 作为主机名（详见 backend/src/main/resources/application.yml）。
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://<db_host>:<db_port>/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，请将 `<db_host>`、`<db_port>` 替换为实际值（例如 `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:<previous-tag>
    ```

## 五、可选优化
- 使用 `--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:<semver>` 或 `<yyyy.mm.dd>`，保持稳定仓库名。

## 六、注意事项
- 安全：严禁将生产环境密钥与数据库密码提交到仓库。使用环境变量或外部密钥管理。
- 端口：前端 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)