function / 版本管理 - WlAdmin 文档

WlAdmin

正在加载文档...

文档内容较大，正在处理中，请稍候

1. 概述

本文档详细说明了前后端版本管理系统的实现原理和使用方法，涵盖前端软链接机制、后端 Docker 镜像版本管理、版本部署、自动备份、版本回滚、版本清理等核心功能，确保前后端部署的可靠性和可追溯性。

1.1 什么是版本管理？

版本管理系统提供了前后端统一的版本管理方案：

前端版本管理（基于软链接）

前端版本管理系统是一个基于**软链接（Symbolic Link）**的版本管理方案，它提供了：

✅ 零停机部署：通过软链接切换实现无缝版本更新
✅ 自动备份：部署新版本前自动备份当前版本
✅ 快速回滚：支持一键回滚到任意历史版本
✅ 版本隔离：每个版本独立存储，互不影响
✅ 版本清理：自动清理旧版本，节省磁盘空间

后端版本管理（基于 Docker 镜像）

后端版本管理系统基于 Docker 镜像标签进行版本管理，它提供了：

✅ 容器化部署：通过 Docker 镜像保证环境一致性
✅ 版本标签管理：使用语义化版本号作为镜像标签
✅ 快速回滚：通过更新环境变量快速切换版本
✅ 版本隔离：每个版本独立镜像，互不影响
✅ 版本清理：自动清理旧镜像，节省磁盘空间

1.2 为什么需要版本管理？

在生产环境中，前后端版本管理都至关重要：

快速回滚：新版本出现问题时可立即回滚到稳定版本
版本追溯：保留历史版本，便于问题排查和对比
零停机更新：前端通过软链接切换，后端通过容器重启，用户无感知更新
资源管理：自动清理旧版本，避免磁盘空间浪费
环境一致性：后端使用 Docker 镜像，确保开发、测试、生产环境一致

1.3 5分钟上手

步骤 1：部署新版本（前后端）

# 在服务器上执行
cd /opt/docker_project
./scripts/auto-deploy.sh deploy v1.0.0

步骤 2：查看当前版本

# 查看部署状态（包含前后端版本信息）
./scripts/auto-deploy.sh status

# 查看前端软链接
ls -la frontend/current
# 输出: current -> versions/v1.0.0

# 查看后端版本（.env 文件）
grep BACKEND_VERSION .env
# 输出: BACKEND_VERSION=v1.0.0

# 查看后端 Docker 镜像
docker images | grep project-root-backend

步骤 3：回滚到旧版本

# 回滚到最新备份（前后端同时回滚）
./scripts/auto-deploy.sh rollback

# 回滚到指定版本
./scripts/auto-deploy.sh rollback v1.0.0

恭喜！ 你已经掌握了版本管理的基本使用。接下来让我们深入了解各个概念。

2. 核心概念

2.1 软链接（Symbolic Link）

软链接是 Linux/Unix 系统中的一种特殊文件，它指向另一个文件或目录。在前端版本管理中，我们使用软链接来实现零停机部署。

什么是软链接？

软链接类似于 Windows 系统中的"快捷方式"，它不存储实际数据，而是存储指向目标路径的引用。

# 创建软链接
ln -sfn versions/v1.0.0 current

# 查看软链接
ls -la current
# 输出: lrwxrwxrwx 1 root root 18 Dec 24 10:00 current -> versions/v1.0.0

# 访问软链接
cd current  # 实际访问的是 versions/v1.0.0 目录

软链接的优势

快速切换：只需更新软链接指向，无需移动文件
零停机：切换软链接是原子操作，用户无感知
节省空间：软链接本身只占用少量空间（存储路径字符串）
易于管理：可以轻松切换指向不同的版本目录

软链接的工作原理

frontend/
├── versions/           # 版本存储目录
│   ├── v1.0.0/        # 版本 1.0.0 的完整文件
│   ├── v1.0.1/        # 版本 1.0.1 的完整文件
│   └── v1.0.2/        # 版本 1.0.2 的完整文件
├── backups/           # 备份存储目录
│   ├── v1.0.0/        # 版本 1.0.0 的备份
│   └── v1.0.1/        # 版本 1.0.1 的备份
└── current -> versions/v1.0.2  # 软链接，指向当前版本

工作流程：

Nginx 配置指向 frontend/current
current 软链接指向 versions/v1.0.2
用户访问时，实际访问的是 versions/v1.0.2 目录
部署新版本时，只需更新 current 软链接指向 versions/v1.0.3
Nginx 自动读取新版本，无需重启

2.2 目录结构

前端版本管理的目录结构如下：

/opt/docker_project/frontend/
├── versions/              # 版本存储目录
│   ├── v1.0.0/           # 版本 1.0.0 的完整文件
│   │   ├── index.html
│   │   ├── js/
│   │   ├── css/
│   │   └── static/
│   ├── v1.0.1/           # 版本 1.0.1 的完整文件
│   └── v1.0.2/           # 版本 1.0.2 的完整文件
├── backups/              # 备份存储目录
│   ├── v1.0.0/           # 版本 1.0.0 的备份
│   ├── v1.0.1/           # 版本 1.0.1 的备份
│   └── v1.0.2/           # 版本 1.0.2 的备份
├── protect/               # 受保护目录（SSL证书、统计页面等）
│   └── demo.html
├── current -> versions/v1.0.2  # 软链接，指向当前版本
└── version.conf          # 版本配置文件

目录说明

目录/文件	说明	用途
`versions/`	版本存储目录	存储所有部署的版本，每个版本一个子目录
`backups/`	备份存储目录	存储部署前的自动备份，用于回滚
`protect/`	受保护目录	存储 SSL 证书、统计页面等需要保留的文件
`current`	软链接	指向当前生效的版本目录
`version.conf`	版本配置	记录当前版本号和部署时间

2.3 版本号规范

版本号采用**语义化版本（Semantic Versioning）**规范，前后端使用统一的版本号：

v主版本号.次版本号.修订号

示例：

v1.0.0 - 主版本 1，次版本 0，修订号 0
v1.0.1 - 主版本 1，次版本 0，修订号 1（修复 bug）
v1.1.0 - 主版本 1，次版本 1，修订号 0（新增功能）
v2.0.0 - 主版本 2，次版本 0，修订号 0（重大更新）

版本号获取优先级：

命令行指定：./scripts/auto-deploy.sh deploy v1.0.0
version-info.txt：从构建产物中的 version-info.txt 读取
package.json：从 package.json 的 version 字段读取
时间戳：如果以上都不可用，使用时间戳格式 deploy_YYYYMMDD_HHMMSS

前后端版本同步：

前后端使用相同的版本号，便于版本对应和回滚
前端版本存储在 frontend/version.conf 和软链接中
后端版本存储在 .env 文件的 BACKEND_VERSION 变量中
Docker 镜像标签使用版本号：project-root-backend:v1.0.0

2.4 后端版本管理核心概念

Docker 镜像版本管理

后端使用 Docker 镜像标签进行版本管理：

# Docker 镜像命名规范
project-root-backend:v1.0.0

镜像标签说明：

project-root-backend：镜像名称（固定）
v1.0.0：版本标签（语义化版本号）
latest：最新版本标签（自动指向最新版本）

版本配置文件

后端版本信息存储在 .env 文件中：

# .env 文件
BACKEND_VERSION=v1.0.0

Docker Compose 配置：

# docker-compose.yml
services:
  backend:
    image: ${PROJECT_NAME:-project-root}-backend:${BACKEND_VERSION:-latest}

工作原理：

Docker Compose 读取 .env 文件中的 BACKEND_VERSION
使用该版本号构建完整的镜像名称：project-root-backend:v1.0.0
启动容器时使用指定版本的镜像
更新版本只需修改 .env 文件并重启服务

后端版本存储

backup/
└── backend/
    ├── project-root-backend-v1.0.0.tar  # 版本 1.0.0 的镜像文件
    ├── project-root-backend-v1.0.1.tar  # 版本 1.0.1 的镜像文件
    └── project-root-backend-v1.0.2.tar  # 版本 1.0.2 的镜像文件

版本文件说明：

镜像文件：.tar 格式的 Docker 镜像导出文件
命名规范：project-root-backend-版本号.tar
存储位置：backup/backend/ 目录（部署前上传的文件）

3. 版本部署流程

3.1 部署流程概述

前端版本部署流程

前端版本部署的完整流程如下：

1. 检查 backup 目录
   ↓
2. 备份当前版本（如果存在）
   ↓
3. 提取版本号（从 version-info.txt 或 package.json）
   ↓
4. 复制前端文件到 versions/版本号/
   ↓
5. 同步受保护目录内容
   ↓
6. 更新 current 软链接
   ↓
7. 更新版本配置文件
   ↓
8. 清理旧版本（保留最近 5 个）

后端版本部署流程

后端版本部署的完整流程如下：

1. 检查 backup/backend 目录
   ↓
2. 查找 Docker 镜像文件（*.tar）
   ↓
3. 停止当前运行的服务
   ↓
4. 删除旧版本镜像（如果存在）
   ↓
5. 加载新版本镜像（docker load）
   ↓
6. 提取版本号（从镜像文件名）
   ↓
7. 更新 .env 文件中的 BACKEND_VERSION
   ↓
8. 启动 Docker Compose 服务
   ↓
9. 健康检查
   ↓
10. 清理旧镜像（可选）

完整部署流程（前后端）

执行 ./scripts/auto-deploy.sh deploy v1.0.0 时的完整流程：

1. 检查 backup 目录
   ↓
2. 备份当前前端版本
   ↓
3. 加载后端 Docker 镜像
   ├── 停止服务
   ├── 删除旧镜像
   ├── 加载新镜像
   └── 更新 .env 文件
   ↓
4. 部署前端版本
   ├── 复制文件到 versions/
   ├── 更新软链接
   └── 更新版本配置
   ↓
5. 启动 Docker Compose 服务
   ↓
6. 健康检查
   ↓
7. 清理旧版本（前后端）

3.2 自动备份机制

部署新版本前，系统会自动备份当前版本：

备份触发条件

✅ 当前存在 current 软链接
✅ 当前版本目录存在且可访问
✅ 当前版本不是备份版本（避免重复备份）

备份流程

# 1. 读取当前版本
current_version=$(readlink frontend/current)
# 结果: versions/v1.0.1

# 2. 提取版本号
version_name=$(basename "$current_version")
# 结果: v1.0.1

# 3. 备份到 backups 目录
rsync -av --no-links "versions/v1.0.1/" "backups/v1.0.1/"

备份特点

✅ 排除软链接：使用 rsync --no-links 避免软链接嵌套
✅ 自动覆盖：如果备份已存在，自动覆盖旧备份
✅ 完整备份：备份包含所有静态文件和资源

3.3 版本部署步骤

步骤 1：检查版本是否已存在

# 如果版本已存在，先清除旧版本中的软链接
if [ -d "versions/v1.0.0" ]; then
    find "versions/v1.0.0" -type l -delete  # 清除软链接
    rm -rf "versions/v1.0.0"                # 删除旧版本
fi

重要：如果版本相同，覆盖时需要清除旧目录中的所有软链接，避免软链接嵌套问题。

步骤 2：复制前端文件

# 使用 rsync 排除软链接
rsync -av --no-links "backup/frontend/" "versions/v1.0.0/"

# 或使用备用方案
cp -r "backup/frontend/" "versions/v1.0.0/"
find "versions/v1.0.0" -type l -delete  # 清除软链接

步骤 3：同步受保护目录

# 同步 protect 目录内容到新版本
rsync -av --include=".*" --no-links "protect/" "versions/v1.0.0/"

受保护目录包含：

SSL 证书文件
统计页面
其他需要保留的配置文件

步骤 4：更新软链接

# 删除旧的软链接
rm -rf frontend/current

# 创建新的软链接
cd frontend
ln -sfn "versions/v1.0.0" current

步骤 5：更新版本配置

# 更新 version.conf
echo "version=v1.0.0" > frontend/version.conf
echo "deploy_time=$(date '+%Y-%m-%d %H:%M:%S')" >> frontend/version.conf

3.4 后端版本部署步骤

步骤 1：检查 Docker 镜像文件

# 查找 backup/backend 目录中的镜像文件
latest_image=$(find backup/backend -name "*.tar" -type f | sort -r | head -1)

# 提取镜像名称
image_name=$(basename "$latest_image" .tar)
# 结果: project-root-backend-v1.0.0

步骤 2：停止当前服务

# 停止可能使用该镜像的服务
docker compose down

# 确保没有容器在使用该镜像
using_containers=$(docker ps -a --filter "ancestor=$image_name" --format "{{.ID}}")
if [ -n "$using_containers" ]; then
    echo "$using_containers" | xargs docker rm -f
fi

步骤 3：删除旧镜像（如果存在）

# 检查镜像是否已存在
if docker images --format "{{.Repository}}:{{.Tag}}" | grep -q "^${image_name}$"; then
    # 删除旧镜像
    docker rmi "$image_name" --force

    # 清理悬空镜像
    docker image prune -f
fi

步骤 4：加载新镜像

# 加载 Docker 镜像
docker load -i "$latest_image"

# 验证镜像是否正确加载
docker images | grep "$image_name"

步骤 5：提取版本号并更新配置

# 从镜像名称中提取语义版本号
semantic_version=$(echo "$image_name" | grep -o 'v[0-9]\+\.[0-9]\+\.[0-9]\+')
# 结果: v1.0.0

# 更新 .env 文件中的 BACKEND_VERSION
if grep -q "^BACKEND_VERSION=" .env; then
    sed -i "s/^BACKEND_VERSION=.*/BACKEND_VERSION=$semantic_version/" .env
else
    echo "BACKEND_VERSION=$semantic_version" >> .env
fi

步骤 6：启动服务

# 启动 Docker Compose 服务
docker compose up -d

# 等待服务启动
sleep 10

# 验证服务状态
docker compose ps

步骤 7：健康检查

# 检查 API 是否响应
curl -f http://localhost:8888/health

# 检查容器日志
docker compose logs backend

3.5 软链接嵌套问题处理

当新版本与旧版本相同时，如果直接覆盖，可能会导致软链接嵌套问题。系统通过以下方式避免：

问题场景

versions/v1.0.0/
├── index.html
└── static/ -> ../v1.0.0/static  # 软链接嵌套（错误）

解决方案

覆盖前清除软链接：

find "versions/v1.0.0" -type l -delete
rm -rf "versions/v1.0.0"

复制时排除软链接：

rsync -av --no-links "backup/frontend/" "versions/v1.0.0/"

复制后清理软链接：

cp -r "backup/frontend/" "versions/v1.0.0/"
find "versions/v1.0.0" -type l -delete

4. 版本回滚

4.1 回滚概述

版本回滚是指将当前版本切换回之前的某个版本。系统支持：

✅ 自动回滚：回滚到最新的备份版本
✅ 指定回滚：回滚到指定的版本号
✅ 快速切换：通过软链接快速切换，无需重新部署

4.2 回滚流程

前端回滚流程

1. 检查备份目录
   ↓
2. 选择回滚目标版本（最新或指定）
   ↓
3. 删除当前软链接
   ↓
4. 将备份复制到 versions 目录（如果不存在）
   ↓
5. 创建新的软链接指向目标版本
   ↓
6. 更新版本配置文件

后端回滚流程

1. 更新 .env 文件中的 BACKEND_VERSION
   ↓
2. 停止当前服务
   ↓
3. 启动服务（使用新版本镜像）
   ↓
4. 健康检查

完整回滚流程（前后端）

执行 ./scripts/auto-deploy.sh rollback v1.0.0 时的完整流程：

1. 检查前端备份目录
   ↓
2. 选择回滚目标版本
   ↓
3. 前端回滚
   ├── 删除当前软链接
   ├── 复制备份到 versions/
   └── 创建新软链接
   ↓
4. 后端回滚
   ├── 更新 .env 文件中的 BACKEND_VERSION
   └── 重启 Docker Compose 服务
   ↓
5. 健康检查

4.3 回滚命令

回滚到最新备份

cd /opt/docker_project
./scripts/auto-deploy.sh rollback

回滚到指定版本

# 回滚到 v1.0.0
./scripts/auto-deploy.sh rollback v1.0.0

查看可用备份

# 查看所有备份版本
ls -la frontend/backups/

# 查看备份版本列表（仅显示语义化版本）
ls frontend/backups/ | grep -E "^v[0-9]+\.[0-9]+\.[0-9]+" | sort -V

4.4 回滚实现细节

步骤 1：选择回滚目标

# 自动选择最新备份
backup_to_use=$(ls -t frontend/backups/ | grep -E "^v[0-9]+\.[0-9]+\.[0-9]+" | head -1)

# 或使用指定版本
backup_to_use="v1.0.0"

步骤 2：复制备份到 versions 目录

# 如果版本在 versions 目录已存在，先清除软链接
if [ -d "versions/$backup_to_use" ]; then
    find "versions/$backup_to_use" -type l -delete
    rm -rf "versions/$backup_to_use"
fi

# 复制备份到 versions 目录（排除软链接）
rsync -av --no-links "backups/$backup_to_use/" "versions/$backup_to_use/"

步骤 3：更新软链接

# 删除当前软链接
rm -rf frontend/current

# 创建新的软链接
ln -sfn "versions/$backup_to_use" frontend/current

步骤 4：更新后端版本号

# 更新 .env 文件中的 BACKEND_VERSION
sed -i "s/^BACKEND_VERSION=.*/BACKEND_VERSION=$backup_to_use/" .env

# 验证版本号已更新
grep BACKEND_VERSION .env
# 输出: BACKEND_VERSION=v1.0.0

重要说明：

后端回滚依赖于 Docker 镜像是否已加载到系统中
如果目标版本的镜像不存在，需要先加载镜像文件
镜像文件通常存储在 backup/backend/ 目录中

步骤 5：重启服务

# 停止服务
docker compose down

# 启动服务（会读取 .env 文件中的 BACKEND_VERSION）
docker compose up -d

# 等待服务启动
sleep 10

# 验证服务状态
docker compose ps

# 健康检查
curl -f http://localhost:8888/health

4.6 后端回滚实现细节

步骤 1：检查镜像是否存在

# 检查目标版本的镜像是否已加载
target_version="v1.0.0"
image_name="project-root-backend:${target_version}"

if ! docker images --format "{{.Repository}}:{{.Tag}}" | grep -q "^${image_name}$"; then
    # 镜像不存在，需要先加载
    log "镜像不存在，需要从 backup/backend 目录加载"

    # 查找镜像文件
    image_file=$(find backup/backend -name "*${target_version}.tar" | head -1)

    if [ -n "$image_file" ]; then
        # 加载镜像
        docker load -i "$image_file"
    else
        error "找不到版本 ${target_version} 的镜像文件"
        exit 1
    fi
fi

步骤 2：更新环境变量

# 备份当前 .env 文件
cp .env .env.bak

# 更新 BACKEND_VERSION
if grep -q "^BACKEND_VERSION=" .env; then
    sed -i "s/^BACKEND_VERSION=.*/BACKEND_VERSION=$target_version/" .env
else
    echo "BACKEND_VERSION=$target_version" >> .env
fi

步骤 3：重启服务

# 停止服务
docker compose down

# 启动服务（使用新版本）
docker compose up -d

# 等待服务完全启动
sleep 15

# 验证服务状态
docker compose ps

# 检查容器日志
docker compose logs backend --tail 50

4.5 回滚注意事项

⚠️ 重要提示：

备份必须存在：回滚前确保目标版本的备份存在
后端版本同步：回滚前端时，后端版本号也会同步更新
服务重启：回滚后需要重启服务使配置生效
软链接清理：回滚时会自动清除旧版本中的软链接，避免嵌套

5. 版本清理

5.1 自动清理机制

系统会自动清理旧版本，避免磁盘空间浪费：

前端清理策略

保留最近 5 个版本：versions/ 目录保留最近 5 个版本
保留最近 5 个备份：backups/ 目录保留最近 5 个备份
按时间排序：使用 ls -t 按修改时间排序，删除最旧的版本

后端清理策略

清理悬空镜像：自动清理 <none>:<none> 的悬空镜像
保留所有已加载镜像：已加载的镜像会保留，不会自动删除
手动清理旧镜像：可以手动删除不需要的旧版本镜像

清理时机

✅ 部署后自动清理：每次部署完成后自动清理旧版本（前端）和悬空镜像（后端）
✅ 手动清理：可以手动执行清理命令

5.2 清理命令

自动清理（部署后）

部署脚本会在部署完成后自动执行清理：

# 部署时会自动清理
./scripts/auto-deploy.sh deploy v1.0.0
# 部署完成后自动清理旧版本

手动清理

# 清理旧版本（保留最近 5 个）
./scripts/auto-deploy.sh cleanup

# 清理旧版本并清空 backup 目录
./scripts/auto-deploy.sh cleanup --cleanup-backup

5.3 清理实现

清理前端 versions 目录

cd frontend/versions
# 按修改时间排序，删除第 6 个及以后的版本
old_versions=$(ls -t | tail -n +6)
if [ -n "$old_versions" ]; then
    echo "$old_versions" | xargs rm -rf
fi

清理前端 backups 目录

cd frontend/backups
# 按修改时间排序，删除第 6 个及以后的备份
old_backups=$(ls -t | tail -n +6)
if [ -n "$old_backups" ]; then
    echo "$old_backups" | xargs rm -rf
fi

清理后端 Docker 镜像

# 清理悬空镜像（<none>:<none>）
docker image prune -f

# 查看所有后端镜像
docker images | grep project-root-backend

# 手动删除指定版本的镜像
docker rmi project-root-backend:v1.0.0

# 删除所有未使用的镜像（谨慎使用）
docker image prune -a -f

清理 backup 目录中的镜像文件

# 清理 backup/backend 目录中的旧镜像文件
cd backup/backend
# 按修改时间排序，删除第 6 个及以后的镜像文件
old_images=$(ls -t *.tar 2>/dev/null | tail -n +6)
if [ -n "$old_images" ]; then
    echo "$old_images" | xargs rm -f
fi

5.4 清理注意事项

⚠️ 重要提示：

保留数量：默认保留最近 5 个版本，可根据需要调整
备份优先：清理时优先保留备份，确保可以回滚
手动确认：清理前建议先查看要删除的版本
磁盘空间：定期清理可以节省大量磁盘空间

6. Nginx 配置

6.1 Nginx 软链接配置

Nginx 配置中，root 指令指向软链接：

server {
    listen 80;
    server_name your-domain.com;

    # 指向软链接，自动跟随到实际版本目录
    root /opt/docker_project/frontend/current;
    index index.html;

    location / {
        try_files $uri $uri/ /index.html;
    }
}

6.2 软链接的优势

使用软链接的优势：

无需重启 Nginx：更新软链接后，Nginx 自动读取新版本
原子操作：软链接切换是原子操作，不会出现中间状态
快速回滚：只需更新软链接指向，即可快速回滚

6.3 验证软链接

# 查看软链接
ls -la /opt/docker_project/frontend/current
# 输出: lrwxrwxrwx 1 root root 18 Dec 24 10:00 current -> versions/v1.0.2

# 查看软链接指向的实际路径
readlink -f /opt/docker_project/frontend/current
# 输出: /opt/docker_project/frontend/versions/v1.0.2

# 验证文件是否存在
ls /opt/docker_project/frontend/current/index.html
# 应该能正常访问

7. 版本状态查询

7.1 查看部署状态

# 查看完整的部署状态
cd /opt/docker_project
./scripts/auto-deploy.sh status

输出内容：

=== 部署状态 ===
最后后端镜像: project-root-backend-v1.0.0
最后前端版本: v1.0.2

=== 前端版本信息 ===
当前前端版本: versions/v1.0.2
前端文件数量: 1234

=== 后端版本信息 ===
当前后端版本: v1.0.0
后端镜像: project-root-backend:v1.0.0
镜像大小: 450MB
容器状态: Up 2 hours

=== backup 目录状态 ===
后端镜像文件: 1 个 (/opt/docker_project/backup/backend)
前端文件: 567 个 (/opt/docker_project/backup/frontend)

=== 服务状态 ===
NAME                    STATUS              PORTS
project-root-backend    Up 2 hours          0.0.0.0:8888->8888/tcp

=== API 状态 ===
✓ API 正常

=== 前端状态 ===
✓ 前端正常

7.2 查看版本列表

前端版本列表

# 查看所有前端版本
ls -la frontend/versions/

# 查看所有前端备份
ls -la frontend/backups/

# 查看当前前端版本
cat frontend/version.conf
# 输出:
# version=v1.0.2
# deploy_time=2025-12-24 10:00:00

后端版本列表

# 查看所有后端镜像
docker images | grep project-root-backend

# 查看当前后端版本（.env 文件）
grep BACKEND_VERSION .env
# 输出: BACKEND_VERSION=v1.0.0

# 查看 backup 目录中的镜像文件
ls -lh backup/backend/*.tar

# 查看当前运行的容器使用的镜像
docker ps --format "table {{.Names}}\t{{.Image}}\t{{.Status}}"

7.3 查看软链接状态

# 查看软链接
ls -la frontend/current

# 查看软链接指向
readlink frontend/current
# 输出: versions/v1.0.2

# 查看软链接指向的实际路径
readlink -f frontend/current
# 输出: /opt/docker_project/frontend/versions/v1.0.2

7.4 查看后端镜像详细信息

# 查看镜像详细信息
docker inspect project-root-backend:v1.0.0

# 查看镜像历史（构建步骤）
docker history project-root-backend:v1.0.0

# 查看镜像大小
docker images project-root-backend --format "table {{.Repository}}\t{{.Tag}}\t{{.Size}}\t{{.CreatedAt}}"

# 查看容器使用的镜像版本
docker inspect project-root-backend | grep Image

8. 最佳实践

✅ 推荐做法

前端版本管理

使用语义化版本：遵循 v主版本.次版本.修订号 规范
部署前备份：系统会自动备份，但建议重要版本手动备份
测试后再部署：在测试环境验证后再部署到生产环境
保留关键版本：重要版本可以手动复制到其他位置长期保存
定期清理：定期清理旧版本，避免磁盘空间不足
监控磁盘空间：定期检查磁盘使用情况

后端版本管理

使用语义化版本：前后端使用统一的版本号规范
镜像标签管理：确保镜像标签与版本号一致
环境变量同步：确保 .env 文件中的 BACKEND_VERSION 与实际使用的镜像版本一致
镜像文件备份：重要版本的镜像文件建议备份到其他位置
定期清理镜像：定期清理不需要的旧镜像，避免磁盘空间不足
监控磁盘空间：Docker 镜像占用空间较大，需要定期检查

❌ 避免做法

前端版本管理

不要手动修改软链接：使用脚本管理，避免手动操作
不要删除正在使用的版本：确保有备份后再删除
不要跳过备份：备份是回滚的基础，不要跳过
不要使用非语义化版本：避免使用 v1.0、v1 等不规范版本号
不要忽略软链接嵌套：版本相同时要清除旧版本中的软链接

后端版本管理

不要手动修改 .env 文件：使用脚本管理，确保版本号正确更新
不要删除正在使用的镜像：确保有其他版本的镜像可以回滚
不要跳过版本标签：确保镜像有正确的版本标签
不要使用非语义化版本：避免使用 v1.0、v1 等不规范版本号
不要忽略镜像清理：旧镜像占用空间较大，需要定期清理
不要直接删除容器：使用 docker compose down 停止服务

9. 常见问题

Q1: 软链接嵌套问题

问题：部署相同版本时，出现软链接嵌套，导致文件访问异常。

原因：

旧版本目录中存在软链接
复制时没有排除软链接
覆盖时没有清除旧版本中的软链接

解决：

覆盖前清除软链接：

find "versions/v1.0.0" -type l -delete
rm -rf "versions/v1.0.0"

复制时排除软链接：

rsync -av --no-links "backup/frontend/" "versions/v1.0.0/"

系统已自动处理：部署脚本已包含软链接清理逻辑

Q2: 回滚后版本不对

问题：回滚后，前端版本正确，但后端版本号没有更新。

原因：

.env 文件中的 BACKEND_VERSION 没有更新
服务没有重启，配置未生效

解决：

检查 .env 文件：
```
grep BACKEND_VERSION .env
```

手动更新版本号：

sed -i "s/^BACKEND_VERSION=.*/BACKEND_VERSION=v1.0.0/" .env

重启服务：
```
docker compose restart
```

Q3: 备份目录不存在

问题：回滚时提示备份目录不存在。

原因：

首次部署，没有备份
备份被手动删除
备份目录路径错误

解决：

检查备份目录：
```
ls -la frontend/backups/
```
如果没有备份，无法回滚，需要重新部署
重要版本建议手动备份到其他位置

Q4: 磁盘空间不足

问题：部署时提示磁盘空间不足。

原因：

旧版本没有清理
备份文件过多
磁盘空间确实不足

解决：

清理旧版本：
```
./scripts/auto-deploy.sh cleanup
```

清理 backup 目录：

./scripts/auto-deploy.sh cleanup --cleanup-backup

检查磁盘空间：
```
df -h
```

手动删除不需要的版本：

rm -rf frontend/versions/v1.0.0
rm -rf frontend/backups/v1.0.0

Q5: 软链接指向错误

问题：current 软链接指向的版本不存在。

原因：

版本目录被手动删除
软链接创建时路径错误
文件系统问题

解决：

检查软链接：

ls -la frontend/current
readlink frontend/current

检查目标目录：
```
ls -la frontend/versions/v1.0.0
```

重新创建软链接：

rm -f frontend/current
ln -sfn "versions/v1.0.0" frontend/current

或回滚到可用版本：
```
./scripts/auto-deploy.sh rollback
```

Q6: 版本号获取失败

问题：部署时无法获取版本号，使用时间戳作为版本号。

原因：

version-info.txt 文件不存在或格式错误
package.json 中版本号格式不正确
构建脚本未生成版本信息文件

解决：

检查版本信息文件：
```
cat backup/version-info.txt
```
手动指定版本号：
```
./scripts/auto-deploy.sh deploy v1.0.0
```
修复构建脚本，确保生成版本信息文件

Q7: 后端镜像加载失败

问题：部署时 Docker 镜像加载失败。

原因：

镜像文件损坏或不完整
Docker 服务未运行
磁盘空间不足
镜像文件路径错误

解决：

检查 Docker 服务状态：
```
docker info
systemctl status docker
```

检查镜像文件：

ls -lh backup/backend/*.tar
file backup/backend/*.tar

检查磁盘空间：
```
df -h
docker system df
```

手动加载镜像：

docker load -i backup/backend/project-root-backend-v1.0.0.tar

验证镜像是否加载成功：

docker images | grep project-root-backend

Q8: 后端版本回滚失败

问题：回滚后端版本时，容器无法启动。

原因：

目标版本的镜像不存在
.env 文件中的 BACKEND_VERSION 未正确更新
镜像版本与 .env 文件中的版本不一致

解决：

检查目标版本的镜像是否存在：

docker images | grep project-root-backend
grep BACKEND_VERSION .env

如果镜像不存在，需要先加载镜像：

# 查找镜像文件
find backup/backend -name "*v1.0.0.tar"

# 加载镜像
docker load -i backup/backend/project-root-backend-v1.0.0.tar

检查 .env 文件中的版本号：
```
grep BACKEND_VERSION .env
```

手动更新版本号并重启：

sed -i "s/^BACKEND_VERSION=.*/BACKEND_VERSION=v1.0.0/" .env
docker compose down
docker compose up -d

Q9: 后端容器启动失败

问题：后端容器启动后立即退出。

原因：

镜像不存在或版本错误
环境变量配置错误
端口被占用
依赖服务（MySQL、Redis）未启动

解决：

检查容器日志：

docker compose logs backend
docker logs project-root-backend

检查镜像是否存在：

docker images | grep project-root-backend
grep BACKEND_VERSION .env

检查端口是否被占用：
```
netstat -tlnp | grep 8888
```

检查依赖服务状态：

docker compose ps
docker compose logs mysql
docker compose logs redis

重启所有服务：

docker compose down
docker compose up -d

Q10: Docker 镜像占用空间过大

问题：Docker 镜像占用大量磁盘空间。

原因：

保留了多个版本的镜像
悬空镜像未清理
构建缓存未清理

解决：

查看镜像占用空间：
```
docker images
docker system df
```
清理悬空镜像：
```
docker image prune -f
```
删除不需要的旧镜像：
```
docker rmi project-root-backend:v1.0.0
```
清理构建缓存：
```
docker builder prune -f
```
全面清理（谨慎使用）：
```
docker system prune -a -f
```

10. 版本管理命令参考

10.1 部署命令

# 完整部署（前后端，自动检测版本号）
./scripts/auto-deploy.sh deploy

# 部署指定版本（前后端）
./scripts/auto-deploy.sh deploy v1.0.0

# 仅部署前端（自动检测版本号）
./scripts/auto-deploy.sh deploy-frontend

# 仅部署前端（指定版本）
./scripts/auto-deploy.sh deploy-frontend v1.0.1

说明：

deploy：完整部署，包含前后端
deploy-frontend：仅部署前端，不更新后端
前后端使用相同的版本号，确保版本一致

10.2 回滚命令

# 回滚到最新备份
./scripts/auto-deploy.sh rollback

# 回滚到指定版本
./scripts/auto-deploy.sh rollback v1.0.0

10.3 清理命令

# 清理旧版本（保留最近 5 个）
./scripts/auto-deploy.sh cleanup

# 清理旧版本并清空 backup 目录
./scripts/auto-deploy.sh cleanup --cleanup-backup

10.4 状态查询命令

# 查看部署状态
./scripts/auto-deploy.sh status

# 查看部署日志
./scripts/auto-deploy.sh logs

# 查看当前版本
cat frontend/version.conf

# 查看软链接
ls -la frontend/current
readlink frontend/current

10.5 手动操作命令

前端手动操作

# 手动创建软链接
cd /opt/docker_project/frontend
ln -sfn "versions/v1.0.0" current

# 手动删除软链接
rm -f current

# 手动查看软链接指向
readlink current
readlink -f current

后端手动操作

# 手动加载 Docker 镜像
docker load -i backup/backend/project-root-backend-v1.0.0.tar

# 手动更新 .env 文件中的版本号
sed -i "s/^BACKEND_VERSION=.*/BACKEND_VERSION=v1.0.0/" .env

# 手动重启服务
docker compose down
docker compose up -d

# 手动查看镜像列表
docker images | grep project-root-backend

# 手动删除指定版本的镜像
docker rmi project-root-backend:v1.0.0

# 手动查看容器使用的镜像
docker inspect project-root-backend | grep Image

11. 完整部署流程示例

11.1 从构建到部署的完整流程

步骤 1：本地构建

# 进入项目根目录
cd /Volumes/Work/Template/project_root

# 构建指定版本
./scripts/build-for-deploy.sh v1.0.3

# 构建产物会生成在 build-history/日期/时间/ 目录
# 例如: build-history/20251224/143000/

步骤 2：上传到服务器

# 找到最新构建目录
LATEST_BUILD=$(find build-history -name "version-info.txt" -exec dirname {} \; | sort | tail -1)

# 上传到服务器 backup 目录
scp -r "$LATEST_BUILD"/* root@your-server:/opt/docker_project/backup/

步骤 3：服务器部署

# 登录服务器
ssh root@your-server

# 进入项目目录
cd /opt/docker_project

# 执行自动部署
./scripts/auto-deploy.sh deploy v1.0.3

步骤 4：验证部署

# 查看部署状态
./scripts/auto-deploy.sh status

# 查看当前版本
cat frontend/version.conf

# 查看软链接
ls -la frontend/current

11.2 版本信息文件格式

构建脚本会自动生成 version-info.txt 文件，格式如下：

版本: v1.0.3
构建时间: Mon Dec 24 14:30:00 CST 2025
构建模式: production
Git提交: a1b2c3d4
Git分支: main
Git消息: feat: 新增版本管理功能

部署脚本会按以下优先级读取版本号：

命令行指定：./scripts/auto-deploy.sh deploy v1.0.3
version-info.txt：从文件中的 版本: 或 VERSION= 字段读取
package.json：从 package.json 的 version 字段读取
时间戳：如果以上都不可用，使用 deploy_YYYYMMDD_HHMMSS

11.3 前端版本信息文件

前端构建时会生成 version.json 文件，包含详细的版本信息：

{
  "version": "v1.0.3",
  "name": "react-antd-webpack",
  "description": "React + Ant Design前端应用",
  "buildTime": "2025-12-24T14:30:00.000Z",
  "buildTimeFormatted": "2025/12/24 14:30:00",
  "buildEnvironment": "production",
  "git": {
    "commit": "a1b2c3d4",
    "branch": "main"
  },
  "nodeVersion": "v20.19.0",
  "platform": "darwin",
  "features": {
    "typescript": true,
    "antd": true,
    "react": true
  }
}

前端可以通过 /version.json 接口访问版本信息。

12. 软链接深入理解

12.1 软链接 vs 硬链接

特性	软链接（Symbolic Link）	硬链接（Hard Link）
存储方式	存储目标路径的引用	指向同一个 inode
跨文件系统	✅ 支持	❌ 不支持
目录支持	✅ 支持	❌ 不支持
删除目标	软链接失效（悬空链接）	硬链接仍然有效
文件大小	很小（仅存储路径）	与目标文件相同

在前端版本管理中，我们使用软链接，因为：

✅ 支持目录链接（硬链接不支持目录）
✅ 可以跨文件系统（如果需要）
✅ 易于管理和切换

12.2 软链接命令详解

创建软链接

# 基本语法
ln -s 目标路径 链接名称

# 常用选项
ln -sfn "versions/v1.0.0" current
# -s: 创建软链接（symbolic link）
# -f: 强制创建（如果链接已存在，先删除）
# -n: 如果目标是符号链接，跟随到实际目标

查看软链接

# 查看软链接详细信息
ls -la current
# 输出: lrwxrwxrwx 1 root root 18 Dec 24 10:00 current -> versions/v1.0.0

# 查看软链接指向的相对路径
readlink current
# 输出: versions/v1.0.0

# 查看软链接指向的绝对路径
readlink -f current
# 输出: /opt/docker_project/frontend/versions/v1.0.0

删除软链接

# 方法1：使用 rm（推荐）
rm -f current

# 方法2：使用 unlink
unlink current

# ⚠️ 注意：不要使用 rm -rf，可能会删除目标目录

12.3 软链接的原子性

软链接的更新是原子操作，这意味着：

✅ 不会出现中间状态：要么指向旧版本，要么指向新版本
✅ Nginx 自动跟随：Nginx 会自动跟随软链接到实际目录
✅ 无需重启服务：更新软链接后，Nginx 立即读取新版本

工作原理：

# 1. 创建新版本目录
mkdir -p versions/v1.0.3
cp -r backup/frontend/* versions/v1.0.3/

# 2. 原子性更新软链接（使用 -f 选项）
ln -sfn "versions/v1.0.3" current
# 这一步是原子操作，瞬间完成

# 3. Nginx 自动读取新版本（无需重启）
# Nginx 的 root 指令指向 current，会自动跟随到新版本

12.4 软链接嵌套问题详解

问题场景

当新版本与旧版本相同时，如果直接覆盖，可能会出现软链接嵌套：

versions/v1.0.0/
├── index.html
├── static/
│   └── images/ -> ../v1.0.0/static/images  # 软链接嵌套（错误）
└── js/
    └── app.js

问题影响：

❌ 文件访问失败：软链接指向自身，形成循环
❌ 磁盘空间浪费：软链接占用空间
❌ 部署失败：某些操作可能因为软链接而失败

解决方案

系统通过三层防护避免软链接嵌套：

覆盖前清除：

# 清除旧版本目录中的所有软链接
find "versions/v1.0.0" -type l -delete
rm -rf "versions/v1.0.0"

复制时排除：

# 使用 rsync 排除软链接
rsync -av --no-links "backup/frontend/" "versions/v1.0.0/"

复制后清理：

# 如果使用 cp，复制后立即清理
cp -r "backup/frontend/" "versions/v1.0.0/"
find "versions/v1.0.0" -type l -delete

13. 版本管理架构图

13.1 目录结构图

/opt/docker_project/
├── backup/                    # 临时备份目录（部署前上传的文件）
│   ├── backend/              # 后端 Docker 镜像
│   │   └── *.tar
│   └── frontend/             # 前端静态文件
│       ├── index.html
│       ├── js/
│       └── css/
├── frontend/                  # 前端版本管理目录
│   ├── versions/             # 版本存储（所有部署的版本）
│   │   ├── v1.0.0/           # 版本 1.0.0
│   │   ├── v1.0.1/           # 版本 1.0.1
│   │   └── v1.0.2/           # 版本 1.0.2（当前）
│   ├── backups/              # 备份存储（部署前的备份）
│   │   ├── v1.0.0/           # 版本 1.0.0 的备份
│   │   ├── v1.0.1/           # 版本 1.0.1 的备份
│   │   └── v1.0.2/           # 版本 1.0.2 的备份
│   ├── protect/              # 受保护目录
│   │   └── demo.html         # SSL 证书、统计页面等
│   ├── current -> versions/v1.0.2  # 软链接（当前版本）
│   └── version.conf          # 版本配置文件
└── logs/                      # 日志目录
    ├── deploy.log            # 部署日志
    ├── last-backend-image.txt
    └── last-frontend-version.txt

13.2 部署流程图

┌─────────────────────────────────────────────────────────┐
│                   本地构建环境                            │
│  ./scripts/build-for-deploy.sh v1.0.3                   │
│  └──> build-history/20251224/143000/                    │
│       ├── backend/*.tar                                  │
│       ├── frontend/                                     │
│       └── version-info.txt                               │
└──────────────────┬───────────────────────────────────────┘
                   │ scp 上传
                   ▼
┌─────────────────────────────────────────────────────────┐
│                   服务器 backup 目录                     │
│  /opt/docker_project/backup/                            │
│  ├── backend/*.tar                                      │
│  └── frontend/                                          │
└──────────────────┬───────────────────────────────────────┘
                   │ 执行部署脚本
                   ▼
┌─────────────────────────────────────────────────────────┐
│           自动部署脚本处理流程                           │
│  1. 备份当前前端版本 -> frontend/backups/v1.0.2/        │
│  2. 加载后端 Docker 镜像                                 │
│     - docker load -i backup/backend/*.tar               │
│     - 镜像: project-root-backend:v1.0.3                 │
│  3. 更新 .env 文件: BACKEND_VERSION=v1.0.3              │
│  4. 复制前端文件 -> frontend/versions/v1.0.3/           │
│  5. 同步受保护目录                                      │
│  6. 更新前端软链接: current -> versions/v1.0.3          │
│  7. 更新版本配置                                        │
│  8. 启动 Docker Compose 服务                            │
│  9. 清理旧版本（保留最近 5 个）                          │
└──────────────────┬───────────────────────────────────────┘
                   │
                   ├──> Nginx 自动读取
                   │    frontend/current -> versions/v1.0.3
                   │
                   └──> Docker Compose 启动
                        image: project-root-backend:v1.0.3
┌─────────────────────────────────────────────────────────┐
│                   服务运行                               │
│  Nginx: root /opt/docker_project/frontend/current       │
│  Backend: project-root-backend:v1.0.3 (Docker 容器)     │
└─────────────────────────────────────────────────────────┘

13.3 回滚流程图

┌─────────────────────────────────────────────────────────┐
│                   回滚操作                               │
│  ./scripts/auto-deploy.sh rollback v1.0.2               │
└──────────────────┬───────────────────────────────────────┘
                   │
                   ▼
┌─────────────────────────────────────────────────────────┐
│  1. 检查备份目录                                         │
│     frontend/backups/v1.0.2/ 存在？                     │
└──────────────────┬───────────────────────────────────────┘
                   │ 是
                   ▼
┌─────────────────────────────────────────────────────────┐
│  2. 删除当前软链接                                       │
│     rm -rf frontend/current                             │
└──────────────────┬───────────────────────────────────────┘
                   │
                   ▼
┌─────────────────────────────────────────────────────────┐
│  3. 复制备份到 versions 目录                            │
│     rsync backups/v1.0.2/ -> versions/v1.0.2/           │
│     （排除软链接）                                       │
└──────────────────┬───────────────────────────────────────┘
                   │
                   ▼
┌─────────────────────────────────────────────────────────┐
│  4. 创建新软链接                                         │
│     ln -sfn versions/v1.0.2 current                     │
└──────────────────┬───────────────────────────────────────┘
                   │
                   ▼
┌─────────────────────────────────────────────────────────┐
│  5. 更新后端版本号                                       │
│     .env: BACKEND_VERSION=v1.0.2                        │
└──────────────────┬───────────────────────────────────────┘
                   │
                   ▼
┌─────────────────────────────────────────────────────────┐
│  6. 重启服务                                             │
│     docker compose down && docker compose up -d         │
└─────────────────────────────────────────────────────────┘

14. 实际使用场景

14.1 场景一：正常版本更新

# 1. 本地构建新版本
./scripts/build-for-deploy.sh v1.0.3

# 2. 上传到服务器
scp -r build-history/20251224/143000/* root@server:/opt/docker_project/backup/

# 3. 服务器部署
ssh root@server "cd /opt/docker_project && ./scripts/auto-deploy.sh deploy v1.0.3"

# 4. 验证部署
ssh root@server "./scripts/auto-deploy.sh status"

结果：

✅ 当前版本：v1.0.2 → v1.0.3
✅ 自动备份：v1.0.2 已备份到 backups/
✅ 软链接更新：current -> versions/v1.0.3
✅ 零停机：用户无感知更新

14.2 场景二：新版本有问题，快速回滚

# 1. 发现新版本有问题
# 2. 立即回滚到上一版本
ssh root@server "cd /opt/docker_project && ./scripts/auto-deploy.sh rollback"

# 3. 验证回滚
ssh root@server "./scripts/auto-deploy.sh status"

结果：

✅ 当前版本：v1.0.3 → v1.0.2
✅ 软链接更新：current -> versions/v1.0.2
✅ 服务重启：配置已更新
✅ 快速恢复：几分钟内完成回滚

14.3 场景三：版本相同，重新部署

# 1. 修复了 v1.0.3 的问题，重新部署相同版本
./scripts/build-for-deploy.sh v1.0.3

# 2. 上传并部署
scp -r build-history/20251224/150000/* root@server:/opt/docker_project/backup/
ssh root@server "cd /opt/docker_project && ./scripts/auto-deploy.sh deploy v1.0.3"

系统处理：

✅ 检测到版本相同：v1.0.3 已存在
✅ 清除旧版本中的软链接：避免嵌套
✅ 覆盖旧版本：使用新构建的文件
✅ 更新软链接：确保指向最新文件

14.4 场景四：仅更新前端

# 1. 只更新前端，不更新后端
./scripts/build-for-deploy.sh v1.0.3

# 2. 上传前端文件
scp -r build-history/20251224/143000/frontend root@server:/opt/docker_project/backup/

# 3. 仅部署前端
ssh root@server "cd /opt/docker_project && ./scripts/auto-deploy.sh deploy-frontend v1.0.3"

结果：

✅ 前端版本更新：v1.0.2 → v1.0.3
✅ 后端保持不变：不加载新镜像
✅ Nginx 重启：使新版本生效
✅ 快速部署：无需重启后端服务

15. 版本管理最佳实践总结

✅ 推荐做法

通用实践

使用语义化版本：前后端遵循统一的 v主版本.次版本.修订号 规范
部署前测试：在测试环境验证后再部署到生产环境
保留关键版本：重要版本可以手动复制到其他位置长期保存
定期清理：定期清理旧版本和镜像，避免磁盘空间不足
监控磁盘空间：定期检查磁盘使用情况（特别是 Docker 镜像）
使用脚本管理：避免手动操作，使用脚本确保一致性
记录部署日志：重要部署记录到部署日志中

前端特定实践

使用脚本管理软链接：避免手动操作软链接
确保备份存在：部署前确保有备份可用于回滚
版本目录一致性：通过部署脚本管理，确保版本目录结构一致

后端特定实践

镜像标签管理：确保镜像标签与版本号一致
环境变量同步：确保 .env 文件中的版本号与实际使用的镜像版本一致
镜像文件备份：重要版本的镜像文件建议备份到其他位置
定期清理镜像：Docker 镜像占用空间较大，需要定期清理

❌ 避免做法

通用实践

不要使用非语义化版本：避免使用 v1.0、v1 等不规范版本号
不要跳过备份：备份是回滚的基础，不要跳过
不要直接修改配置文件：通过部署脚本管理，确保一致性

前端特定实践

不要手动修改软链接：使用脚本管理，避免手动操作
不要删除正在使用的版本：确保有备份后再删除
不要忽略软链接嵌套：版本相同时要清除旧版本中的软链接

后端特定实践

不要手动修改 .env 文件：使用脚本管理，确保版本号正确更新
不要删除正在使用的镜像：确保有其他版本的镜像可以回滚
不要跳过版本标签：确保镜像有正确的版本标签
不要忽略镜像清理：旧镜像占用空间较大，需要定期清理
不要直接删除容器：使用 docker compose down 停止服务

版本管理是生产环境稳定性的重要保障

1. 概述

1.1 什么是版本管理？

版本管理系统提供了前后端统一的版本管理方案：

前端版本管理（基于软链接）

前端版本管理系统是一个基于**软链接（Symbolic Link）**的版本管理方案，它提供了：

✅ 零停机部署：通过软链接切换实现无缝版本更新
✅ 自动备份：部署新版本前自动备份当前版本
✅ 快速回滚：支持一键回滚到任意历史版本
✅ 版本隔离：每个版本独立存储，互不影响
✅ 版本清理：自动清理旧版本，节省磁盘空间

后端版本管理（基于 Docker 镜像）

后端版本管理系统基于 Docker 镜像标签进行版本管理，它提供了：

✅ 容器化部署：通过 Docker 镜像保证环境一致性
✅ 版本标签管理：使用语义化版本号作为镜像标签
✅ 快速回滚：通过更新环境变量快速切换版本
✅ 版本隔离：每个版本独立镜像，互不影响
✅ 版本清理：自动清理旧镜像，节省磁盘空间

1.2 为什么需要版本管理？

在生产环境中，前后端版本管理都至关重要：

快速回滚：新版本出现问题时可立即回滚到稳定版本
版本追溯：保留历史版本，便于问题排查和对比
零停机更新：前端通过软链接切换，后端通过容器重启，用户无感知更新
资源管理：自动清理旧版本，避免磁盘空间浪费
环境一致性：后端使用 Docker 镜像，确保开发、测试、生产环境一致

1.3 5分钟上手

步骤 1：部署新版本（前后端）

# 在服务器上执行
cd /opt/docker_project
./scripts/auto-deploy.sh deploy v1.0.0

步骤 2：查看当前版本

# 查看部署状态（包含前后端版本信息）
./scripts/auto-deploy.sh status

# 查看前端软链接
ls -la frontend/current
# 输出: current -> versions/v1.0.0

# 查看后端版本（.env 文件）
grep BACKEND_VERSION .env
# 输出: BACKEND_VERSION=v1.0.0

# 查看后端 Docker 镜像
docker images | grep project-root-backend

步骤 3：回滚到旧版本

# 回滚到最新备份（前后端同时回滚）
./scripts/auto-deploy.sh rollback

# 回滚到指定版本
./scripts/auto-deploy.sh rollback v1.0.0

恭喜！ 你已经掌握了版本管理的基本使用。接下来让我们深入了解各个概念。

2. 核心概念

2.1 软链接（Symbolic Link）

软链接是 Linux/Unix 系统中的一种特殊文件，它指向另一个文件或目录。在前端版本管理中，我们使用软链接来实现零停机部署。

什么是软链接？

软链接类似于 Windows 系统中的"快捷方式"，它不存储实际数据，而是存储指向目标路径的引用。

# 创建软链接
ln -sfn versions/v1.0.0 current

# 查看软链接
ls -la current
# 输出: lrwxrwxrwx 1 root root 18 Dec 24 10:00 current -> versions/v1.0.0

# 访问软链接
cd current  # 实际访问的是 versions/v1.0.0 目录

软链接的优势

快速切换：只需更新软链接指向，无需移动文件
零停机：切换软链接是原子操作，用户无感知
节省空间：软链接本身只占用少量空间（存储路径字符串）
易于管理：可以轻松切换指向不同的版本目录

软链接的工作原理

frontend/
├── versions/           # 版本存储目录
│   ├── v1.0.0/        # 版本 1.0.0 的完整文件
│   ├── v1.0.1/        # 版本 1.0.1 的完整文件
│   └── v1.0.2/        # 版本 1.0.2 的完整文件
├── backups/           # 备份存储目录
│   ├── v1.0.0/        # 版本 1.0.0 的备份
│   └── v1.0.1/        # 版本 1.0.1 的备份
└── current -> versions/v1.0.2  # 软链接，指向当前版本

工作流程：

Nginx 配置指向 frontend/current
current 软链接指向 versions/v1.0.2
用户访问时，实际访问的是 versions/v1.0.2 目录
部署新版本时，只需更新 current 软链接指向 versions/v1.0.3
Nginx 自动读取新版本，无需重启

2.2 目录结构

前端版本管理的目录结构如下：

/opt/docker_project/frontend/
├── versions/              # 版本存储目录
│   ├── v1.0.0/           # 版本 1.0.0 的完整文件
│   │   ├── index.html
│   │   ├── js/
│   │   ├── css/
│   │   └── static/
│   ├── v1.0.1/           # 版本 1.0.1 的完整文件
│   └── v1.0.2/           # 版本 1.0.2 的完整文件
├── backups/              # 备份存储目录
│   ├── v1.0.0/           # 版本 1.0.0 的备份
│   ├── v1.0.1/           # 版本 1.0.1 的备份
│   └── v1.0.2/           # 版本 1.0.2 的备份
├── protect/               # 受保护目录（SSL证书、统计页面等）
│   └── demo.html
├── current -> versions/v1.0.2  # 软链接，指向当前版本
└── version.conf          # 版本配置文件

目录说明

目录/文件	说明	用途
`versions/`	版本存储目录	存储所有部署的版本，每个版本一个子目录
`backups/`	备份存储目录	存储部署前的自动备份，用于回滚
`protect/`	受保护目录	存储 SSL 证书、统计页面等需要保留的文件
`current`	软链接	指向当前生效的版本目录
`version.conf`	版本配置	记录当前版本号和部署时间

2.3 版本号规范

版本号采用**语义化版本（Semantic Versioning）**规范，前后端使用统一的版本号：

v主版本号.次版本号.修订号

示例：

v1.0.0 - 主版本 1，次版本 0，修订号 0
v1.0.1 - 主版本 1，次版本 0，修订号 1（修复 bug）
v1.1.0 - 主版本 1，次版本 1，修订号 0（新增功能）
v2.0.0 - 主版本 2，次版本 0，修订号 0（重大更新）

版本号获取优先级：

命令行指定：./scripts/auto-deploy.sh deploy v1.0.0
version-info.txt：从构建产物中的 version-info.txt 读取
package.json：从 package.json 的 version 字段读取
时间戳：如果以上都不可用，使用时间戳格式 deploy_YYYYMMDD_HHMMSS

前后端版本同步：

前后端使用相同的版本号，便于版本对应和回滚
前端版本存储在 frontend/version.conf 和软链接中
后端版本存储在 .env 文件的 BACKEND_VERSION 变量中
Docker 镜像标签使用版本号：project-root-backend:v1.0.0

2.4 后端版本管理核心概念

Docker 镜像版本管理

后端使用 Docker 镜像标签进行版本管理：

# Docker 镜像命名规范
project-root-backend:v1.0.0

镜像标签说明：

project-root-backend：镜像名称（固定）
v1.0.0：版本标签（语义化版本号）
latest：最新版本标签（自动指向最新版本）

版本配置文件

后端版本信息存储在 .env 文件中：

# .env 文件
BACKEND_VERSION=v1.0.0

Docker Compose 配置：

# docker-compose.yml
services:
  backend:
    image: ${PROJECT_NAME:-project-root}-backend:${BACKEND_VERSION:-latest}

工作原理：

Docker Compose 读取 .env 文件中的 BACKEND_VERSION
使用该版本号构建完整的镜像名称：project-root-backend:v1.0.0
启动容器时使用指定版本的镜像
更新版本只需修改 .env 文件并重启服务

后端版本存储

backup/
└── backend/
    ├── project-root-backend-v1.0.0.tar  # 版本 1.0.0 的镜像文件
    ├── project-root-backend-v1.0.1.tar  # 版本 1.0.1 的镜像文件
    └── project-root-backend-v1.0.2.tar  # 版本 1.0.2 的镜像文件

版本文件说明：

镜像文件：.tar 格式的 Docker 镜像导出文件
命名规范：project-root-backend-版本号.tar
存储位置：backup/backend/ 目录（部署前上传的文件）

3. 版本部署流程

3.1 部署流程概述

前端版本部署流程

前端版本部署的完整流程如下：

1. 检查 backup 目录
   ↓
2. 备份当前版本（如果存在）
   ↓
3. 提取版本号（从 version-info.txt 或 package.json）
   ↓
4. 复制前端文件到 versions/版本号/
   ↓
5. 同步受保护目录内容
   ↓
6. 更新 current 软链接
   ↓
7. 更新版本配置文件
   ↓
8. 清理旧版本（保留最近 5 个）

后端版本部署流程

后端版本部署的完整流程如下：

1. 检查 backup/backend 目录
   ↓
2. 查找 Docker 镜像文件（*.tar）
   ↓
3. 停止当前运行的服务
   ↓
4. 删除旧版本镜像（如果存在）
   ↓
5. 加载新版本镜像（docker load）
   ↓
6. 提取版本号（从镜像文件名）
   ↓
7. 更新 .env 文件中的 BACKEND_VERSION
   ↓
8. 启动 Docker Compose 服务
   ↓
9. 健康检查
   ↓
10. 清理旧镜像（可选）

完整部署流程（前后端）

执行 ./scripts/auto-deploy.sh deploy v1.0.0 时的完整流程：

1. 检查 backup 目录
   ↓
2. 备份当前前端版本
   ↓
3. 加载后端 Docker 镜像
   ├── 停止服务
   ├── 删除旧镜像
   ├── 加载新镜像
   └── 更新 .env 文件
   ↓
4. 部署前端版本
   ├── 复制文件到 versions/
   ├── 更新软链接
   └── 更新版本配置
   ↓
5. 启动 Docker Compose 服务
   ↓
6. 健康检查
   ↓
7. 清理旧版本（前后端）

3.2 自动备份机制

部署新版本前，系统会自动备份当前版本：

备份触发条件

✅ 当前存在 current 软链接
✅ 当前版本目录存在且可访问
✅ 当前版本不是备份版本（避免重复备份）

备份流程

# 1. 读取当前版本
current_version=$(readlink frontend/current)
# 结果: versions/v1.0.1

# 2. 提取版本号
version_name=$(basename "$current_version")
# 结果: v1.0.1

# 3. 备份到 backups 目录
rsync -av --no-links "versions/v1.0.1/" "backups/v1.0.1/"

备份特点

✅ 排除软链接：使用 rsync --no-links 避免软链接嵌套
✅ 自动覆盖：如果备份已存在，自动覆盖旧备份
✅ 完整备份：备份包含所有静态文件和资源

3.3 版本部署步骤

步骤 1：检查版本是否已存在

# 如果版本已存在，先清除旧版本中的软链接
if [ -d "versions/v1.0.0" ]; then
    find "versions/v1.0.0" -type l -delete  # 清除软链接
    rm -rf "versions/v1.0.0"                # 删除旧版本
fi

重要：如果版本相同，覆盖时需要清除旧目录中的所有软链接，避免软链接嵌套问题。

步骤 2：复制前端文件

# 使用 rsync 排除软链接
rsync -av --no-links "backup/frontend/" "versions/v1.0.0/"

# 或使用备用方案
cp -r "backup/frontend/" "versions/v1.0.0/"
find "versions/v1.0.0" -type l -delete  # 清除软链接

步骤 3：同步受保护目录

# 同步 protect 目录内容到新版本
rsync -av --include=".*" --no-links "protect/" "versions/v1.0.0/"

受保护目录包含：

SSL 证书文件
统计页面
其他需要保留的配置文件

步骤 4：更新软链接

# 删除旧的软链接
rm -rf frontend/current

# 创建新的软链接
cd frontend
ln -sfn "versions/v1.0.0" current

步骤 5：更新版本配置

# 更新 version.conf
echo "version=v1.0.0" > frontend/version.conf
echo "deploy_time=$(date '+%Y-%m-%d %H:%M:%S')" >> frontend/version.conf

3.4 后端版本部署步骤

步骤 1：检查 Docker 镜像文件

# 查找 backup/backend 目录中的镜像文件
latest_image=$(find backup/backend -name "*.tar" -type f | sort -r | head -1)

# 提取镜像名称
image_name=$(basename "$latest_image" .tar)
# 结果: project-root-backend-v1.0.0

步骤 2：停止当前服务

# 停止可能使用该镜像的服务
docker compose down

# 确保没有容器在使用该镜像
using_containers=$(docker ps -a --filter "ancestor=$image_name" --format "{{.ID}}")
if [ -n "$using_containers" ]; then
    echo "$using_containers" | xargs docker rm -f
fi

步骤 3：删除旧镜像（如果存在）

# 检查镜像是否已存在
if docker images --format "{{.Repository}}:{{.Tag}}" | grep -q "^${image_name}$"; then
    # 删除旧镜像
    docker rmi "$image_name" --force

    # 清理悬空镜像
    docker image prune -f
fi

步骤 4：加载新镜像

# 加载 Docker 镜像
docker load -i "$latest_image"

# 验证镜像是否正确加载
docker images | grep "$image_name"

步骤 5：提取版本号并更新配置

# 从镜像名称中提取语义版本号
semantic_version=$(echo "$image_name" | grep -o 'v[0-9]\+\.[0-9]\+\.[0-9]\+')
# 结果: v1.0.0

# 更新 .env 文件中的 BACKEND_VERSION
if grep -q "^BACKEND_VERSION=" .env; then
    sed -i "s/^BACKEND_VERSION=.*/BACKEND_VERSION=$semantic_version/" .env
else
    echo "BACKEND_VERSION=$semantic_version" >> .env
fi

步骤 6：启动服务

# 启动 Docker Compose 服务
docker compose up -d

# 等待服务启动
sleep 10

# 验证服务状态
docker compose ps

步骤 7：健康检查

# 检查 API 是否响应
curl -f http://localhost:8888/health

# 检查容器日志
docker compose logs backend

3.5 软链接嵌套问题处理

当新版本与旧版本相同时，如果直接覆盖，可能会导致软链接嵌套问题。系统通过以下方式避免：

问题场景

versions/v1.0.0/
├── index.html
└── static/ -> ../v1.0.0/static  # 软链接嵌套（错误）

解决方案

覆盖前清除软链接：

find "versions/v1.0.0" -type l -delete
rm -rf "versions/v1.0.0"

复制时排除软链接：

rsync -av --no-links "backup/frontend/" "versions/v1.0.0/"

复制后清理软链接：

cp -r "backup/frontend/" "versions/v1.0.0/"
find "versions/v1.0.0" -type l -delete

4. 版本回滚

4.1 回滚概述

版本回滚是指将当前版本切换回之前的某个版本。系统支持：

✅ 自动回滚：回滚到最新的备份版本
✅ 指定回滚：回滚到指定的版本号
✅ 快速切换：通过软链接快速切换，无需重新部署

4.2 回滚流程

前端回滚流程

1. 检查备份目录
   ↓
2. 选择回滚目标版本（最新或指定）
   ↓
3. 删除当前软链接
   ↓
4. 将备份复制到 versions 目录（如果不存在）
   ↓
5. 创建新的软链接指向目标版本
   ↓
6. 更新版本配置文件

后端回滚流程

1. 更新 .env 文件中的 BACKEND_VERSION
   ↓
2. 停止当前服务
   ↓
3. 启动服务（使用新版本镜像）
   ↓
4. 健康检查

完整回滚流程（前后端）

执行 ./scripts/auto-deploy.sh rollback v1.0.0 时的完整流程：

1. 检查前端备份目录
   ↓
2. 选择回滚目标版本
   ↓
3. 前端回滚
   ├── 删除当前软链接
   ├── 复制备份到 versions/
   └── 创建新软链接
   ↓
4. 后端回滚
   ├── 更新 .env 文件中的 BACKEND_VERSION
   └── 重启 Docker Compose 服务
   ↓
5. 健康检查

4.3 回滚命令

回滚到最新备份

cd /opt/docker_project
./scripts/auto-deploy.sh rollback

回滚到指定版本

# 回滚到 v1.0.0
./scripts/auto-deploy.sh rollback v1.0.0

查看可用备份

# 查看所有备份版本
ls -la frontend/backups/

# 查看备份版本列表（仅显示语义化版本）
ls frontend/backups/ | grep -E "^v[0-9]+\.[0-9]+\.[0-9]+" | sort -V

4.4 回滚实现细节

步骤 1：选择回滚目标

# 自动选择最新备份
backup_to_use=$(ls -t frontend/backups/ | grep -E "^v[0-9]+\.[0-9]+\.[0-9]+" | head -1)

# 或使用指定版本
backup_to_use="v1.0.0"

步骤 2：复制备份到 versions 目录

# 如果版本在 versions 目录已存在，先清除软链接
if [ -d "versions/$backup_to_use" ]; then
    find "versions/$backup_to_use" -type l -delete
    rm -rf "versions/$backup_to_use"
fi

# 复制备份到 versions 目录（排除软链接）
rsync -av --no-links "backups/$backup_to_use/" "versions/$backup_to_use/"

步骤 3：更新软链接

# 删除当前软链接
rm -rf frontend/current

# 创建新的软链接
ln -sfn "versions/$backup_to_use" frontend/current

步骤 4：更新后端版本号

# 更新 .env 文件中的 BACKEND_VERSION
sed -i "s/^BACKEND_VERSION=.*/BACKEND_VERSION=$backup_to_use/" .env

# 验证版本号已更新
grep BACKEND_VERSION .env
# 输出: BACKEND_VERSION=v1.0.0

重要说明：

后端回滚依赖于 Docker 镜像是否已加载到系统中
如果目标版本的镜像不存在，需要先加载镜像文件
镜像文件通常存储在 backup/backend/ 目录中

步骤 5：重启服务

# 停止服务
docker compose down

# 启动服务（会读取 .env 文件中的 BACKEND_VERSION）
docker compose up -d

# 等待服务启动
sleep 10

# 验证服务状态
docker compose ps

# 健康检查
curl -f http://localhost:8888/health

4.6 后端回滚实现细节

步骤 1：检查镜像是否存在

# 检查目标版本的镜像是否已加载
target_version="v1.0.0"
image_name="project-root-backend:${target_version}"

if ! docker images --format "{{.Repository}}:{{.Tag}}" | grep -q "^${image_name}$"; then
    # 镜像不存在，需要先加载
    log "镜像不存在，需要从 backup/backend 目录加载"

    # 查找镜像文件
    image_file=$(find backup/backend -name "*${target_version}.tar" | head -1)

    if [ -n "$image_file" ]; then
        # 加载镜像
        docker load -i "$image_file"
    else
        error "找不到版本 ${target_version} 的镜像文件"
        exit 1
    fi
fi

步骤 2：更新环境变量

# 备份当前 .env 文件
cp .env .env.bak

# 更新 BACKEND_VERSION
if grep -q "^BACKEND_VERSION=" .env; then
    sed -i "s/^BACKEND_VERSION=.*/BACKEND_VERSION=$target_version/" .env
else
    echo "BACKEND_VERSION=$target_version" >> .env
fi

步骤 3：重启服务

# 停止服务
docker compose down

# 启动服务（使用新版本）
docker compose up -d

# 等待服务完全启动
sleep 15

# 验证服务状态
docker compose ps

# 检查容器日志
docker compose logs backend --tail 50

4.5 回滚注意事项

⚠️ 重要提示：

备份必须存在：回滚前确保目标版本的备份存在
后端版本同步：回滚前端时，后端版本号也会同步更新
服务重启：回滚后需要重启服务使配置生效
软链接清理：回滚时会自动清除旧版本中的软链接，避免嵌套

5. 版本清理

5.1 自动清理机制

系统会自动清理旧版本，避免磁盘空间浪费：

前端清理策略

保留最近 5 个版本：versions/ 目录保留最近 5 个版本
保留最近 5 个备份：backups/ 目录保留最近 5 个备份
按时间排序：使用 ls -t 按修改时间排序，删除最旧的版本

后端清理策略

清理悬空镜像：自动清理 <none>:<none> 的悬空镜像
保留所有已加载镜像：已加载的镜像会保留，不会自动删除
手动清理旧镜像：可以手动删除不需要的旧版本镜像

清理时机

✅ 部署后自动清理：每次部署完成后自动清理旧版本（前端）和悬空镜像（后端）
✅ 手动清理：可以手动执行清理命令

5.2 清理命令

自动清理（部署后）

部署脚本会在部署完成后自动执行清理：

# 部署时会自动清理
./scripts/auto-deploy.sh deploy v1.0.0
# 部署完成后自动清理旧版本

手动清理

# 清理旧版本（保留最近 5 个）
./scripts/auto-deploy.sh cleanup

# 清理旧版本并清空 backup 目录
./scripts/auto-deploy.sh cleanup --cleanup-backup

5.3 清理实现

清理前端 versions 目录

cd frontend/versions
# 按修改时间排序，删除第 6 个及以后的版本
old_versions=$(ls -t | tail -n +6)
if [ -n "$old_versions" ]; then
    echo "$old_versions" | xargs rm -rf
fi

清理前端 backups 目录

cd frontend/backups
# 按修改时间排序，删除第 6 个及以后的备份
old_backups=$(ls -t | tail -n +6)
if [ -n "$old_backups" ]; then
    echo "$old_backups" | xargs rm -rf
fi

清理后端 Docker 镜像

# 清理悬空镜像（<none>:<none>）
docker image prune -f

# 查看所有后端镜像
docker images | grep project-root-backend

# 手动删除指定版本的镜像
docker rmi project-root-backend:v1.0.0

# 删除所有未使用的镜像（谨慎使用）
docker image prune -a -f

清理 backup 目录中的镜像文件

# 清理 backup/backend 目录中的旧镜像文件
cd backup/backend
# 按修改时间排序，删除第 6 个及以后的镜像文件
old_images=$(ls -t *.tar 2>/dev/null | tail -n +6)
if [ -n "$old_images" ]; then
    echo "$old_images" | xargs rm -f
fi

5.4 清理注意事项

⚠️ 重要提示：

保留数量：默认保留最近 5 个版本，可根据需要调整
备份优先：清理时优先保留备份，确保可以回滚
手动确认：清理前建议先查看要删除的版本
磁盘空间：定期清理可以节省大量磁盘空间

6. Nginx 配置

6.1 Nginx 软链接配置

Nginx 配置中，root 指令指向软链接：

server {
    listen 80;
    server_name your-domain.com;

    # 指向软链接，自动跟随到实际版本目录
    root /opt/docker_project/frontend/current;
    index index.html;

    location / {
        try_files $uri $uri/ /index.html;
    }
}

6.2 软链接的优势

使用软链接的优势：

无需重启 Nginx：更新软链接后，Nginx 自动读取新版本
原子操作：软链接切换是原子操作，不会出现中间状态
快速回滚：只需更新软链接指向，即可快速回滚

6.3 验证软链接

# 查看软链接
ls -la /opt/docker_project/frontend/current
# 输出: lrwxrwxrwx 1 root root 18 Dec 24 10:00 current -> versions/v1.0.2

# 查看软链接指向的实际路径
readlink -f /opt/docker_project/frontend/current
# 输出: /opt/docker_project/frontend/versions/v1.0.2

# 验证文件是否存在
ls /opt/docker_project/frontend/current/index.html
# 应该能正常访问

7. 版本状态查询

7.1 查看部署状态

# 查看完整的部署状态
cd /opt/docker_project
./scripts/auto-deploy.sh status

输出内容：

=== 部署状态 ===
最后后端镜像: project-root-backend-v1.0.0
最后前端版本: v1.0.2

=== 前端版本信息 ===
当前前端版本: versions/v1.0.2
前端文件数量: 1234

=== 后端版本信息 ===
当前后端版本: v1.0.0
后端镜像: project-root-backend:v1.0.0
镜像大小: 450MB
容器状态: Up 2 hours

=== backup 目录状态 ===
后端镜像文件: 1 个 (/opt/docker_project/backup/backend)
前端文件: 567 个 (/opt/docker_project/backup/frontend)

=== 服务状态 ===
NAME                    STATUS              PORTS
project-root-backend    Up 2 hours          0.0.0.0:8888->8888/tcp

=== API 状态 ===
✓ API 正常

=== 前端状态 ===
✓ 前端正常

7.2 查看版本列表

前端版本列表

# 查看所有前端版本
ls -la frontend/versions/

# 查看所有前端备份
ls -la frontend/backups/

# 查看当前前端版本
cat frontend/version.conf
# 输出:
# version=v1.0.2
# deploy_time=2025-12-24 10:00:00

后端版本列表

# 查看所有后端镜像
docker images | grep project-root-backend

# 查看当前后端版本（.env 文件）
grep BACKEND_VERSION .env
# 输出: BACKEND_VERSION=v1.0.0

# 查看 backup 目录中的镜像文件
ls -lh backup/backend/*.tar

# 查看当前运行的容器使用的镜像
docker ps --format "table {{.Names}}\t{{.Image}}\t{{.Status}}"

7.3 查看软链接状态

# 查看软链接
ls -la frontend/current

# 查看软链接指向
readlink frontend/current
# 输出: versions/v1.0.2

# 查看软链接指向的实际路径
readlink -f frontend/current
# 输出: /opt/docker_project/frontend/versions/v1.0.2

7.4 查看后端镜像详细信息

# 查看镜像详细信息
docker inspect project-root-backend:v1.0.0

# 查看镜像历史（构建步骤）
docker history project-root-backend:v1.0.0

# 查看镜像大小
docker images project-root-backend --format "table {{.Repository}}\t{{.Tag}}\t{{.Size}}\t{{.CreatedAt}}"

# 查看容器使用的镜像版本
docker inspect project-root-backend | grep Image

8. 最佳实践

✅ 推荐做法

前端版本管理

使用语义化版本：遵循 v主版本.次版本.修订号 规范
部署前备份：系统会自动备份，但建议重要版本手动备份
测试后再部署：在测试环境验证后再部署到生产环境
保留关键版本：重要版本可以手动复制到其他位置长期保存
定期清理：定期清理旧版本，避免磁盘空间不足
监控磁盘空间：定期检查磁盘使用情况

后端版本管理

使用语义化版本：前后端使用统一的版本号规范
镜像标签管理：确保镜像标签与版本号一致
环境变量同步：确保 .env 文件中的 BACKEND_VERSION 与实际使用的镜像版本一致
镜像文件备份：重要版本的镜像文件建议备份到其他位置
定期清理镜像：定期清理不需要的旧镜像，避免磁盘空间不足
监控磁盘空间：Docker 镜像占用空间较大，需要定期检查

❌ 避免做法

前端版本管理

不要手动修改软链接：使用脚本管理，避免手动操作
不要删除正在使用的版本：确保有备份后再删除
不要跳过备份：备份是回滚的基础，不要跳过
不要使用非语义化版本：避免使用 v1.0、v1 等不规范版本号
不要忽略软链接嵌套：版本相同时要清除旧版本中的软链接

后端版本管理

不要手动修改 .env 文件：使用脚本管理，确保版本号正确更新
不要删除正在使用的镜像：确保有其他版本的镜像可以回滚
不要跳过版本标签：确保镜像有正确的版本标签
不要使用非语义化版本：避免使用 v1.0、v1 等不规范版本号
不要忽略镜像清理：旧镜像占用空间较大，需要定期清理
不要直接删除容器：使用 docker compose down 停止服务

9. 常见问题

Q1: 软链接嵌套问题

问题：部署相同版本时，出现软链接嵌套，导致文件访问异常。

原因：

旧版本目录中存在软链接
复制时没有排除软链接
覆盖时没有清除旧版本中的软链接

解决：

覆盖前清除软链接：

find "versions/v1.0.0" -type l -delete
rm -rf "versions/v1.0.0"

复制时排除软链接：

rsync -av --no-links "backup/frontend/" "versions/v1.0.0/"

系统已自动处理：部署脚本已包含软链接清理逻辑

Q2: 回滚后版本不对

问题：回滚后，前端版本正确，但后端版本号没有更新。

原因：

.env 文件中的 BACKEND_VERSION 没有更新
服务没有重启，配置未生效

解决：

检查 .env 文件：
```
grep BACKEND_VERSION .env
```

手动更新版本号：

sed -i "s/^BACKEND_VERSION=.*/BACKEND_VERSION=v1.0.0/" .env

重启服务：
```
docker compose restart
```

Q3: 备份目录不存在

问题：回滚时提示备份目录不存在。

原因：

首次部署，没有备份
备份被手动删除
备份目录路径错误

解决：

检查备份目录：
```
ls -la frontend/backups/
```
如果没有备份，无法回滚，需要重新部署
重要版本建议手动备份到其他位置

Q4: 磁盘空间不足

问题：部署时提示磁盘空间不足。

原因：

旧版本没有清理
备份文件过多
磁盘空间确实不足

解决：

清理旧版本：
```
./scripts/auto-deploy.sh cleanup
```

清理 backup 目录：

./scripts/auto-deploy.sh cleanup --cleanup-backup

检查磁盘空间：
```
df -h
```

手动删除不需要的版本：

rm -rf frontend/versions/v1.0.0
rm -rf frontend/backups/v1.0.0

Q5: 软链接指向错误

问题：current 软链接指向的版本不存在。

原因：

版本目录被手动删除
软链接创建时路径错误
文件系统问题

解决：

检查软链接：

ls -la frontend/current
readlink frontend/current

检查目标目录：
```
ls -la frontend/versions/v1.0.0
```

重新创建软链接：

rm -f frontend/current
ln -sfn "versions/v1.0.0" frontend/current

或回滚到可用版本：
```
./scripts/auto-deploy.sh rollback
```

Q6: 版本号获取失败

问题：部署时无法获取版本号，使用时间戳作为版本号。

原因：

version-info.txt 文件不存在或格式错误
package.json 中版本号格式不正确
构建脚本未生成版本信息文件

解决：

检查版本信息文件：
```
cat backup/version-info.txt
```
手动指定版本号：
```
./scripts/auto-deploy.sh deploy v1.0.0
```
修复构建脚本，确保生成版本信息文件

Q7: 后端镜像加载失败

问题：部署时 Docker 镜像加载失败。

原因：

镜像文件损坏或不完整
Docker 服务未运行
磁盘空间不足
镜像文件路径错误

解决：

检查 Docker 服务状态：
```
docker info
systemctl status docker
```

检查镜像文件：

ls -lh backup/backend/*.tar
file backup/backend/*.tar

检查磁盘空间：
```
df -h
docker system df
```

手动加载镜像：

docker load -i backup/backend/project-root-backend-v1.0.0.tar

验证镜像是否加载成功：

docker images | grep project-root-backend

Q8: 后端版本回滚失败

问题：回滚后端版本时，容器无法启动。

原因：

目标版本的镜像不存在
.env 文件中的 BACKEND_VERSION 未正确更新
镜像版本与 .env 文件中的版本不一致

解决：

检查目标版本的镜像是否存在：

docker images | grep project-root-backend
grep BACKEND_VERSION .env

如果镜像不存在，需要先加载镜像：

# 查找镜像文件
find backup/backend -name "*v1.0.0.tar"

# 加载镜像
docker load -i backup/backend/project-root-backend-v1.0.0.tar

检查 .env 文件中的版本号：
```
grep BACKEND_VERSION .env
```

手动更新版本号并重启：

sed -i "s/^BACKEND_VERSION=.*/BACKEND_VERSION=v1.0.0/" .env
docker compose down
docker compose up -d

Q9: 后端容器启动失败

问题：后端容器启动后立即退出。

原因：

镜像不存在或版本错误
环境变量配置错误
端口被占用
依赖服务（MySQL、Redis）未启动

解决：

检查容器日志：

docker compose logs backend
docker logs project-root-backend

检查镜像是否存在：

docker images | grep project-root-backend
grep BACKEND_VERSION .env

检查端口是否被占用：
```
netstat -tlnp | grep 8888
```

检查依赖服务状态：

docker compose ps
docker compose logs mysql
docker compose logs redis

重启所有服务：

docker compose down
docker compose up -d

Q10: Docker 镜像占用空间过大

问题：Docker 镜像占用大量磁盘空间。

原因：

保留了多个版本的镜像
悬空镜像未清理
构建缓存未清理

解决：

查看镜像占用空间：
```
docker images
docker system df
```
清理悬空镜像：
```
docker image prune -f
```
删除不需要的旧镜像：
```
docker rmi project-root-backend:v1.0.0
```
清理构建缓存：
```
docker builder prune -f
```
全面清理（谨慎使用）：
```
docker system prune -a -f
```

10. 版本管理命令参考

10.1 部署命令

# 完整部署（前后端，自动检测版本号）
./scripts/auto-deploy.sh deploy

# 部署指定版本（前后端）
./scripts/auto-deploy.sh deploy v1.0.0

# 仅部署前端（自动检测版本号）
./scripts/auto-deploy.sh deploy-frontend

# 仅部署前端（指定版本）
./scripts/auto-deploy.sh deploy-frontend v1.0.1

说明：

deploy：完整部署，包含前后端
deploy-frontend：仅部署前端，不更新后端
前后端使用相同的版本号，确保版本一致

10.2 回滚命令

# 回滚到最新备份
./scripts/auto-deploy.sh rollback

# 回滚到指定版本
./scripts/auto-deploy.sh rollback v1.0.0

10.3 清理命令

# 清理旧版本（保留最近 5 个）
./scripts/auto-deploy.sh cleanup

# 清理旧版本并清空 backup 目录
./scripts/auto-deploy.sh cleanup --cleanup-backup

10.4 状态查询命令

# 查看部署状态
./scripts/auto-deploy.sh status

# 查看部署日志
./scripts/auto-deploy.sh logs

# 查看当前版本
cat frontend/version.conf

# 查看软链接
ls -la frontend/current
readlink frontend/current

10.5 手动操作命令

前端手动操作

# 手动创建软链接
cd /opt/docker_project/frontend
ln -sfn "versions/v1.0.0" current

# 手动删除软链接
rm -f current

# 手动查看软链接指向
readlink current
readlink -f current

后端手动操作

# 手动加载 Docker 镜像
docker load -i backup/backend/project-root-backend-v1.0.0.tar

# 手动更新 .env 文件中的版本号
sed -i "s/^BACKEND_VERSION=.*/BACKEND_VERSION=v1.0.0/" .env

# 手动重启服务
docker compose down
docker compose up -d

# 手动查看镜像列表
docker images | grep project-root-backend

# 手动删除指定版本的镜像
docker rmi project-root-backend:v1.0.0

# 手动查看容器使用的镜像
docker inspect project-root-backend | grep Image

11. 完整部署流程示例

11.1 从构建到部署的完整流程

步骤 1：本地构建

# 进入项目根目录
cd /Volumes/Work/Template/project_root

# 构建指定版本
./scripts/build-for-deploy.sh v1.0.3

# 构建产物会生成在 build-history/日期/时间/ 目录
# 例如: build-history/20251224/143000/

步骤 2：上传到服务器

# 找到最新构建目录
LATEST_BUILD=$(find build-history -name "version-info.txt" -exec dirname {} \; | sort | tail -1)

# 上传到服务器 backup 目录
scp -r "$LATEST_BUILD"/* root@your-server:/opt/docker_project/backup/

步骤 3：服务器部署

# 登录服务器
ssh root@your-server

# 进入项目目录
cd /opt/docker_project

# 执行自动部署
./scripts/auto-deploy.sh deploy v1.0.3

步骤 4：验证部署

# 查看部署状态
./scripts/auto-deploy.sh status

# 查看当前版本
cat frontend/version.conf

# 查看软链接
ls -la frontend/current

11.2 版本信息文件格式

构建脚本会自动生成 version-info.txt 文件，格式如下：

版本: v1.0.3
构建时间: Mon Dec 24 14:30:00 CST 2025
构建模式: production
Git提交: a1b2c3d4
Git分支: main
Git消息: feat: 新增版本管理功能

部署脚本会按以下优先级读取版本号：

命令行指定：./scripts/auto-deploy.sh deploy v1.0.3
version-info.txt：从文件中的 版本: 或 VERSION= 字段读取
package.json：从 package.json 的 version 字段读取
时间戳：如果以上都不可用，使用 deploy_YYYYMMDD_HHMMSS

11.3 前端版本信息文件

前端构建时会生成 version.json 文件，包含详细的版本信息：

{
  "version": "v1.0.3",
  "name": "react-antd-webpack",
  "description": "React + Ant Design前端应用",
  "buildTime": "2025-12-24T14:30:00.000Z",
  "buildTimeFormatted": "2025/12/24 14:30:00",
  "buildEnvironment": "production",
  "git": {
    "commit": "a1b2c3d4",
    "branch": "main"
  },
  "nodeVersion": "v20.19.0",
  "platform": "darwin",
  "features": {
    "typescript": true,
    "antd": true,
    "react": true
  }
}

前端可以通过 /version.json 接口访问版本信息。

12. 软链接深入理解

12.1 软链接 vs 硬链接

特性	软链接（Symbolic Link）	硬链接（Hard Link）
存储方式	存储目标路径的引用	指向同一个 inode
跨文件系统	✅ 支持	❌ 不支持
目录支持	✅ 支持	❌ 不支持
删除目标	软链接失效（悬空链接）	硬链接仍然有效
文件大小	很小（仅存储路径）	与目标文件相同

在前端版本管理中，我们使用软链接，因为：

✅ 支持目录链接（硬链接不支持目录）
✅ 可以跨文件系统（如果需要）
✅ 易于管理和切换

12.2 软链接命令详解

创建软链接

# 基本语法
ln -s 目标路径 链接名称

# 常用选项
ln -sfn "versions/v1.0.0" current
# -s: 创建软链接（symbolic link）
# -f: 强制创建（如果链接已存在，先删除）
# -n: 如果目标是符号链接，跟随到实际目标

查看软链接

# 查看软链接详细信息
ls -la current
# 输出: lrwxrwxrwx 1 root root 18 Dec 24 10:00 current -> versions/v1.0.0

# 查看软链接指向的相对路径
readlink current
# 输出: versions/v1.0.0

# 查看软链接指向的绝对路径
readlink -f current
# 输出: /opt/docker_project/frontend/versions/v1.0.0

删除软链接

# 方法1：使用 rm（推荐）
rm -f current

# 方法2：使用 unlink
unlink current

# ⚠️ 注意：不要使用 rm -rf，可能会删除目标目录

12.3 软链接的原子性

软链接的更新是原子操作，这意味着：

✅ 不会出现中间状态：要么指向旧版本，要么指向新版本
✅ Nginx 自动跟随：Nginx 会自动跟随软链接到实际目录
✅ 无需重启服务：更新软链接后，Nginx 立即读取新版本

工作原理：

# 1. 创建新版本目录
mkdir -p versions/v1.0.3
cp -r backup/frontend/* versions/v1.0.3/

# 2. 原子性更新软链接（使用 -f 选项）
ln -sfn "versions/v1.0.3" current
# 这一步是原子操作，瞬间完成

# 3. Nginx 自动读取新版本（无需重启）
# Nginx 的 root 指令指向 current，会自动跟随到新版本

12.4 软链接嵌套问题详解

问题场景

当新版本与旧版本相同时，如果直接覆盖，可能会出现软链接嵌套：

versions/v1.0.0/
├── index.html
├── static/
│   └── images/ -> ../v1.0.0/static/images  # 软链接嵌套（错误）
└── js/
    └── app.js

问题影响：

❌ 文件访问失败：软链接指向自身，形成循环
❌ 磁盘空间浪费：软链接占用空间
❌ 部署失败：某些操作可能因为软链接而失败

解决方案

系统通过三层防护避免软链接嵌套：

覆盖前清除：

# 清除旧版本目录中的所有软链接
find "versions/v1.0.0" -type l -delete
rm -rf "versions/v1.0.0"

复制时排除：

# 使用 rsync 排除软链接
rsync -av --no-links "backup/frontend/" "versions/v1.0.0/"

复制后清理：

# 如果使用 cp，复制后立即清理
cp -r "backup/frontend/" "versions/v1.0.0/"
find "versions/v1.0.0" -type l -delete

13. 版本管理架构图

13.1 目录结构图

/opt/docker_project/
├── backup/                    # 临时备份目录（部署前上传的文件）
│   ├── backend/              # 后端 Docker 镜像
│   │   └── *.tar
│   └── frontend/             # 前端静态文件
│       ├── index.html
│       ├── js/
│       └── css/
├── frontend/                  # 前端版本管理目录
│   ├── versions/             # 版本存储（所有部署的版本）
│   │   ├── v1.0.0/           # 版本 1.0.0
│   │   ├── v1.0.1/           # 版本 1.0.1
│   │   └── v1.0.2/           # 版本 1.0.2（当前）
│   ├── backups/              # 备份存储（部署前的备份）
│   │   ├── v1.0.0/           # 版本 1.0.0 的备份
│   │   ├── v1.0.1/           # 版本 1.0.1 的备份
│   │   └── v1.0.2/           # 版本 1.0.2 的备份
│   ├── protect/              # 受保护目录
│   │   └── demo.html         # SSL 证书、统计页面等
│   ├── current -> versions/v1.0.2  # 软链接（当前版本）
│   └── version.conf          # 版本配置文件
└── logs/                      # 日志目录
    ├── deploy.log            # 部署日志
    ├── last-backend-image.txt
    └── last-frontend-version.txt

13.2 部署流程图

┌─────────────────────────────────────────────────────────┐
│                   本地构建环境                            │
│  ./scripts/build-for-deploy.sh v1.0.3                   │
│  └──> build-history/20251224/143000/                    │
│       ├── backend/*.tar                                  │
│       ├── frontend/                                     │
│       └── version-info.txt                               │
└──────────────────┬───────────────────────────────────────┘
                   │ scp 上传
                   ▼
┌─────────────────────────────────────────────────────────┐
│                   服务器 backup 目录                     │
│  /opt/docker_project/backup/                            │
│  ├── backend/*.tar                                      │
│  └── frontend/                                          │
└──────────────────┬───────────────────────────────────────┘
                   │ 执行部署脚本
                   ▼
┌─────────────────────────────────────────────────────────┐
│           自动部署脚本处理流程                           │
│  1. 备份当前前端版本 -> frontend/backups/v1.0.2/        │
│  2. 加载后端 Docker 镜像                                 │
│     - docker load -i backup/backend/*.tar               │
│     - 镜像: project-root-backend:v1.0.3                 │
│  3. 更新 .env 文件: BACKEND_VERSION=v1.0.3              │
│  4. 复制前端文件 -> frontend/versions/v1.0.3/           │
│  5. 同步受保护目录                                      │
│  6. 更新前端软链接: current -> versions/v1.0.3          │
│  7. 更新版本配置                                        │
│  8. 启动 Docker Compose 服务                            │
│  9. 清理旧版本（保留最近 5 个）                          │
└──────────────────┬───────────────────────────────────────┘
                   │
                   ├──> Nginx 自动读取
                   │    frontend/current -> versions/v1.0.3
                   │
                   └──> Docker Compose 启动
                        image: project-root-backend:v1.0.3
┌─────────────────────────────────────────────────────────┐
│                   服务运行                               │
│  Nginx: root /opt/docker_project/frontend/current       │
│  Backend: project-root-backend:v1.0.3 (Docker 容器)     │
└─────────────────────────────────────────────────────────┘

13.3 回滚流程图

┌─────────────────────────────────────────────────────────┐
│                   回滚操作                               │
│  ./scripts/auto-deploy.sh rollback v1.0.2               │
└──────────────────┬───────────────────────────────────────┘
                   │
                   ▼
┌─────────────────────────────────────────────────────────┐
│  1. 检查备份目录                                         │
│     frontend/backups/v1.0.2/ 存在？                     │
└──────────────────┬───────────────────────────────────────┘
                   │ 是
                   ▼
┌─────────────────────────────────────────────────────────┐
│  2. 删除当前软链接                                       │
│     rm -rf frontend/current                             │
└──────────────────┬───────────────────────────────────────┘
                   │
                   ▼
┌─────────────────────────────────────────────────────────┐
│  3. 复制备份到 versions 目录                            │
│     rsync backups/v1.0.2/ -> versions/v1.0.2/           │
│     （排除软链接）                                       │
└──────────────────┬───────────────────────────────────────┘
                   │
                   ▼
┌─────────────────────────────────────────────────────────┐
│  4. 创建新软链接                                         │
│     ln -sfn versions/v1.0.2 current                     │
└──────────────────┬───────────────────────────────────────┘
                   │
                   ▼
┌─────────────────────────────────────────────────────────┐
│  5. 更新后端版本号                                       │
│     .env: BACKEND_VERSION=v1.0.2                        │
└──────────────────┬───────────────────────────────────────┘
                   │
                   ▼
┌─────────────────────────────────────────────────────────┐
│  6. 重启服务                                             │
│     docker compose down && docker compose up -d         │
└─────────────────────────────────────────────────────────┘

14. 实际使用场景

14.1 场景一：正常版本更新

# 1. 本地构建新版本
./scripts/build-for-deploy.sh v1.0.3

# 2. 上传到服务器
scp -r build-history/20251224/143000/* root@server:/opt/docker_project/backup/

# 3. 服务器部署
ssh root@server "cd /opt/docker_project && ./scripts/auto-deploy.sh deploy v1.0.3"

# 4. 验证部署
ssh root@server "./scripts/auto-deploy.sh status"

结果：

✅ 当前版本：v1.0.2 → v1.0.3
✅ 自动备份：v1.0.2 已备份到 backups/
✅ 软链接更新：current -> versions/v1.0.3
✅ 零停机：用户无感知更新

14.2 场景二：新版本有问题，快速回滚

# 1. 发现新版本有问题
# 2. 立即回滚到上一版本
ssh root@server "cd /opt/docker_project && ./scripts/auto-deploy.sh rollback"

# 3. 验证回滚
ssh root@server "./scripts/auto-deploy.sh status"

结果：

✅ 当前版本：v1.0.3 → v1.0.2
✅ 软链接更新：current -> versions/v1.0.2
✅ 服务重启：配置已更新
✅ 快速恢复：几分钟内完成回滚

14.3 场景三：版本相同，重新部署

# 1. 修复了 v1.0.3 的问题，重新部署相同版本
./scripts/build-for-deploy.sh v1.0.3

# 2. 上传并部署
scp -r build-history/20251224/150000/* root@server:/opt/docker_project/backup/
ssh root@server "cd /opt/docker_project && ./scripts/auto-deploy.sh deploy v1.0.3"

系统处理：

✅ 检测到版本相同：v1.0.3 已存在
✅ 清除旧版本中的软链接：避免嵌套
✅ 覆盖旧版本：使用新构建的文件
✅ 更新软链接：确保指向最新文件

14.4 场景四：仅更新前端

# 1. 只更新前端，不更新后端
./scripts/build-for-deploy.sh v1.0.3

# 2. 上传前端文件
scp -r build-history/20251224/143000/frontend root@server:/opt/docker_project/backup/

# 3. 仅部署前端
ssh root@server "cd /opt/docker_project && ./scripts/auto-deploy.sh deploy-frontend v1.0.3"

结果：

✅ 前端版本更新：v1.0.2 → v1.0.3
✅ 后端保持不变：不加载新镜像
✅ Nginx 重启：使新版本生效
✅ 快速部署：无需重启后端服务

15. 版本管理最佳实践总结

✅ 推荐做法

通用实践

使用语义化版本：前后端遵循统一的 v主版本.次版本.修订号 规范
部署前测试：在测试环境验证后再部署到生产环境
保留关键版本：重要版本可以手动复制到其他位置长期保存
定期清理：定期清理旧版本和镜像，避免磁盘空间不足
监控磁盘空间：定期检查磁盘使用情况（特别是 Docker 镜像）
使用脚本管理：避免手动操作，使用脚本确保一致性
记录部署日志：重要部署记录到部署日志中

前端特定实践

使用脚本管理软链接：避免手动操作软链接
确保备份存在：部署前确保有备份可用于回滚
版本目录一致性：通过部署脚本管理，确保版本目录结构一致

后端特定实践

镜像标签管理：确保镜像标签与版本号一致
环境变量同步：确保 .env 文件中的版本号与实际使用的镜像版本一致
镜像文件备份：重要版本的镜像文件建议备份到其他位置
定期清理镜像：Docker 镜像占用空间较大，需要定期清理

❌ 避免做法

通用实践

不要使用非语义化版本：避免使用 v1.0、v1 等不规范版本号
不要跳过备份：备份是回滚的基础，不要跳过
不要直接修改配置文件：通过部署脚本管理，确保一致性

前端特定实践

不要手动修改软链接：使用脚本管理，避免手动操作
不要删除正在使用的版本：确保有备份后再删除
不要忽略软链接嵌套：版本相同时要清除旧版本中的软链接

后端特定实践

不要手动修改 .env 文件：使用脚本管理，确保版本号正确更新
不要删除正在使用的镜像：确保有其他版本的镜像可以回滚
不要跳过版本标签：确保镜像有正确的版本标签
不要忽略镜像清理：旧镜像占用空间较大，需要定期清理
不要直接删除容器：使用 docker compose down 停止服务

版本管理是生产环境稳定性的重要保障

1. 概述#

1.1 什么是版本管理？#

前端版本管理（基于软链接）#

后端版本管理（基于 Docker 镜像）#

1.2 为什么需要版本管理？#

1.3 5分钟上手#

步骤 1：部署新版本（前后端）#

步骤 2：查看当前版本#

步骤 3：回滚到旧版本#

2. 核心概念#

2.1 软链接（Symbolic Link）#

什么是软链接？#

软链接的优势#

软链接的工作原理#

2.2 目录结构#

目录说明#

2.3 版本号规范#

2.4 后端版本管理核心概念#

Docker 镜像版本管理#

版本配置文件#

后端版本存储#

3. 版本部署流程#

3.1 部署流程概述#

前端版本部署流程#

后端版本部署流程#

完整部署流程（前后端）#

3.2 自动备份机制#

备份触发条件#

备份流程#

备份特点#

3.3 版本部署步骤#

步骤 1：检查版本是否已存在#

步骤 2：复制前端文件#

步骤 3：同步受保护目录#

步骤 4：更新软链接#

步骤 5：更新版本配置#

3.4 后端版本部署步骤#

步骤 1：检查 Docker 镜像文件#

步骤 2：停止当前服务#

步骤 3：删除旧镜像（如果存在）#

步骤 4：加载新镜像#

步骤 5：提取版本号并更新配置#

步骤 6：启动服务#

步骤 7：健康检查#

3.5 软链接嵌套问题处理#

问题场景#

解决方案#

4. 版本回滚#

4.1 回滚概述#

4.2 回滚流程#

前端回滚流程#

后端回滚流程#

完整回滚流程（前后端）#

4.3 回滚命令#

回滚到最新备份#

回滚到指定版本#

查看可用备份#

4.4 回滚实现细节#

步骤 1：选择回滚目标#

步骤 2：复制备份到 versions 目录#

步骤 3：更新软链接#

步骤 4：更新后端版本号#

步骤 5：重启服务#

4.6 后端回滚实现细节#

步骤 1：检查镜像是否存在#

步骤 2：更新环境变量#

步骤 3：重启服务#

4.5 回滚注意事项#

5. 版本清理#

5.1 自动清理机制#

前端清理策略#

后端清理策略#

清理时机#

5.2 清理命令#

自动清理（部署后）#

手动清理#

5.3 清理实现#

清理前端 versions 目录#

清理前端 backups 目录#

清理后端 Docker 镜像#

1. 概述

1.1 什么是版本管理？

前端版本管理（基于软链接）

后端版本管理（基于 Docker 镜像）

1.2 为什么需要版本管理？

1.3 5分钟上手

步骤 1：部署新版本（前后端）

步骤 2：查看当前版本

步骤 3：回滚到旧版本

2. 核心概念

2.1 软链接（Symbolic Link）

什么是软链接？

软链接的优势

软链接的工作原理

2.2 目录结构

目录说明

2.3 版本号规范

2.4 后端版本管理核心概念

Docker 镜像版本管理

版本配置文件

后端版本存储

3. 版本部署流程

3.1 部署流程概述

前端版本部署流程

后端版本部署流程

完整部署流程（前后端）

3.2 自动备份机制

备份触发条件

备份流程

备份特点

3.3 版本部署步骤

步骤 1：检查版本是否已存在

步骤 2：复制前端文件

步骤 3：同步受保护目录

步骤 4：更新软链接

步骤 5：更新版本配置

3.4 后端版本部署步骤

步骤 1：检查 Docker 镜像文件

步骤 2：停止当前服务

步骤 3：删除旧镜像（如果存在）

步骤 4：加载新镜像

步骤 5：提取版本号并更新配置

步骤 6：启动服务

步骤 7：健康检查

3.5 软链接嵌套问题处理

问题场景

解决方案

4. 版本回滚

4.1 回滚概述

4.2 回滚流程

前端回滚流程

后端回滚流程

完整回滚流程（前后端）

4.3 回滚命令

回滚到最新备份

回滚到指定版本

查看可用备份

4.4 回滚实现细节

步骤 1：选择回滚目标

步骤 2：复制备份到 versions 目录

步骤 3：更新软链接

步骤 4：更新后端版本号

步骤 5：重启服务

4.6 后端回滚实现细节

步骤 1：检查镜像是否存在

步骤 2：更新环境变量

步骤 3：重启服务

4.5 回滚注意事项

5. 版本清理

5.1 自动清理机制

前端清理策略

后端清理策略

清理时机

5.2 清理命令

自动清理（部署后）

手动清理

5.3 清理实现

清理前端 versions 目录

清理前端 backups 目录

清理后端 Docker 镜像