xlcp/deploy/DEPLOYMENT_CHECKLIST.md

XL监狱综合管理平台 - 部署前检查清单

🖥️ 远程服务器架构检查

由于无法直接SSH连接,请手动运行以下命令检查远程服务器架构:

ssh root@192.168.10.150 "uname -m && cat /etc/os-release && docker --version && docker compose version"

预期输出示例:

x86_64 架构 (最常见):

x86_64
NAME="CentOS Linux"
VERSION="7 (Core)"
Docker version 24.0.7
Docker Compose version v2.24.0

ARM64 架构 (树莓派、ARM服务器):

aarch64
NAME="Ubuntu"
VERSION="22.04.3 LTS (Jammy Jellyfish)"
Docker version 24.0.7
Docker Compose version v2.24.0

✅ 部署方式选择

方式 A: 在线部署 (服务器网络良好)

适用场景:

• 服务器可以访问 Docker Hub
• 网络带宽充足
• 快速测试部署

步骤:

cd deploy
./scripts/deploy.sh

方式 B: 离线部署 (推荐生产环境) ⭐

适用场景:

• 服务器网络受限
• 需要离线部署
• 多服务器部署
• 网络速度慢

步骤:

1. 本地打包镜像

cd deploy
./scripts/save-images.sh

这会创建 images-archive/ 目录,包含:

• xlcp-docker-images.tar.gz (约 2-3GB)
• upload.sh (自动上传脚本)
• README.md (详细说明)

2. 上传镜像到服务器

方式 2.1: 使用自动脚本 (最简单)

cd images-archive
./upload.sh

方式 2.2: 手动上传

cd images-archive

# 使用 scp
scp xlcp-docker-images.tar.gz root@192.168.10.150:/projects/data/xlcp/

# 或使用 rsync
rsync -avz --progress xlcp-docker-images.tar.gz root@192.168.10.150:/projects/data/xlcp/

3. 在服务器加载镜像

# SSH 到服务器
ssh root@192.168.10.150

# 进入目录
cd /projects/data/xlcp

# 加载镜像
docker load -i xlcp-docker-images.tar.gz

# 验证镜像
docker images | grep -E 'mysql|redis|nginx'

4. 部署服务

# 确保部署文件已上传
cd /projects/data/xlcp

# 启动服务
docker compose up -d

# 查看状态
docker compose ps

📋 镜像兼容性说明

✅ 全平台支持

以下镜像在 x86_64 和 ARM64 上都支持:

镜像	x86_64	ARM64	说明
mysql:8.0	✅	✅	官方支持双架构
redis:7-alpine	✅	✅	官方支持双架构
nginx:1.25-alpine	✅	✅	官方支持双架构
node:20-alpine	✅	✅	官方支持双架构

⚠️ 构建镜像

以下镜像仅在本地构建时使用,不会影响部署:

镜像	用途	x86_64	ARM64
maven:3.9-eclipse-temurin-21	后端编译	✅	✅
eclipse-temurin:21-jre-alpine	后端运行	✅	✅

🔄 架构不兼容怎么办?

如果远程服务器架构与本地不同,有以下解决方案:

方案 1: 在远程服务器直接构建 (推荐)

# 上传源代码到服务器
rsync -avz --exclude node_modules --exclude target \
  ../ root@192.168.10.150:/projects/data/xlcp/

# SSH 到服务器
ssh root@192.168.10.150

# 进入项目目录
cd /projects/data/xlcp

# 构建镜像
cd deploy
docker compose build

方案 2: 使用 buildx 构建多架构镜像

# 启用 buildx
docker buildx create --name multiarch --use

# 构建并导出多架构镜像
docker buildx build --platform linux/amd64,linux/arm64 \
  -t xlcp-backend \
  --load \
  -f docker/backend/Dockerfile \
  ../backend

方案 3: 使用交叉编译 (高级)

需要配置 QEMU 等工具,比较复杂,不推荐。

🎯 快速决策树

检查服务器网络
  |
  ├─ 可以访问 Docker Hub
  |   └─ 使用方式 A (在线部署)
  |
  └─ 无法访问或速度慢
      |
      ├─ 架构相同 (都是 x86_64 或都是 ARM64)
      |   └─ 使用方式 B (离线部署)
      |
      └─ 架构不同
          |
          ├─ 服务器性能好
          |   └─ 方案 1 (远程构建)
          |
          └─ 服务器性能差
              └─ 找一台相同架构的机器做离线包

📝 实际操作示例

示例 1: 本地 Mac (ARM64) -> 远程 Linux (x86_64)

# 检查本地架构
uname -m
# 输出: arm64 (Apple Silicon)

# 检查远程架构
ssh root@192.168.10.150 "uname -m"
# 输出: x86_64

# 由于架构不同,选择在远程服务器构建
rsync -avz --exclude node_modules --exclude target \
  /path/to/xlcp/ root@192.168.10.150:/projects/data/xlcp/

ssh root@192.168.10.150 'cd /projects/data/xlcp/deploy && docker compose up -d --build'

示例 2: 本地 Mac (x86_64) -> 远程 Linux (x86_64)

# 架构相同,可以使用离线部署
cd /path/to/xlcp/deploy
./scripts/save-images.sh

cd images-archive
./upload.sh

🆘 常见问题

Q1: 如何快速查看服务器架构?

ssh root@192.168.10.150 "uname -m"

输出:

• x86_64 = Intel/AMD 64位
• aarch64 = ARM 64位
• armv7l = ARM 32位

Q2: 镜像很大,上传需要多久?

取决于网络速度:

• 100Mbps: 约 3-5 分钟
• 10Mbps: 约 30-50 分钟
• 1Mbps: 约 5-8 小时

建议使用 rsync,支持断点续传。

Q3: 上传中断了怎么办?

使用 rsync 的断点续传功能:

rsync -avz --partial --progress \
  xlcp-docker-images.tar.gz root@192.168.10.150:/projects/data/xlcp/

Q4: 服务器没有 Docker 怎么办?

先安装 Docker:

ssh root@192.168.10.150

# CentOS/RHEL
curl -fsSL https://get.docker.com | sh
systemctl start docker
systemctl enable docker

# Ubuntu/Debian
curl -fsSL https://get.docker.com | sh
systemctl start docker
systemctl enable docker

✅ 推荐的最佳实践

1. 开发环境: 使用在线部署,快速迭代
2. 测试环境: 使用离线部署,模拟生产
3. 生产环境:
   • 准备离线镜像包
   • 多次测试部署流程
   • 准备回滚方案
4. 多环境部署: 建立镜像仓库 (Harbor/Registry)

📞 下一步

完成架构检查后,选择对应的部署方式:

• 在线部署: 直接运行 ./scripts/deploy.sh
• 离线部署: 先运行 ./scripts/save-images.sh
• 远程构建: 先上传代码,再远程构建

需要帮助? 查看各脚本的帮助信息:

./scripts/save-images.sh --help
./scripts/deploy.sh --help