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

## 🖥️ 远程服务器架构检查

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

```bash
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
- 网络带宽充足
- 快速测试部署

**步骤**:
```bash
cd deploy
./scripts/deploy.sh
```

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

**适用场景**:
- 服务器网络受限
- 需要离线部署
- 多服务器部署
- 网络速度慢

**步骤**:

#### 1. 本地打包镜像
```bash
cd deploy
./scripts/save-images.sh
```

这会创建 `images-archive/` 目录,包含:
- `xlcp-docker-images.tar.gz` (约 2-3GB)
- `upload.sh` (自动上传脚本)
- `README.md` (详细说明)

#### 2. 上传镜像到服务器

**方式 2.1: 使用自动脚本** (最简单)
```bash
cd images-archive
./upload.sh
```

**方式 2.2: 手动上传**
```bash
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. 在服务器加载镜像
```bash
# 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. 部署服务
```bash
# 确保部署文件已上传
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: 在远程服务器直接构建 (推荐)

```bash
# 上传源代码到服务器
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 构建多架构镜像

```bash
# 启用 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)

```bash
# 检查本地架构
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)

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

cd images-archive
./upload.sh
```

## 🆘 常见问题

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

```bash
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 的断点续传功能:
```bash
rsync -avz --partial --progress \
  xlcp-docker-images.tar.gz root@192.168.10.150:/projects/data/xlcp/
```

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

先安装 Docker:
```bash
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`
- **远程构建**: 先上传代码,再远程构建

需要帮助? 查看各脚本的帮助信息:
```bash
./scripts/save-images.sh --help
./scripts/deploy.sh --help
```