194 lines
4.1 KiB
Markdown
194 lines
4.1 KiB
Markdown
# 部署故障排查指南
|
||
|
||
## SSH 连接断开问题
|
||
|
||
### 问题现象
|
||
执行 `scripts/deploy-prod.sh` 后：
|
||
- SSH 连接立即断开
|
||
- 无法重新连接服务器
|
||
- 服务器可能完全无响应
|
||
|
||
### 根本原因
|
||
**Docker 构建过程耗尽服务器内存，导致系统 OOM (Out of Memory) 崩溃**
|
||
|
||
#### 技术细节
|
||
1. **同时构建多个镜像**：原脚本使用 `docker compose up -d --build` 会并行构建 backend 和 frontend
|
||
2. **前端构建超高内存消耗**：Node.js/npm 构建过程可能消耗 1-2GB 内存
|
||
3. **无资源限制**：所有容器没有 memory limit，可无限制消耗系统资源
|
||
4. **连锁反应**：
|
||
- Docker 构建吃满内存
|
||
- Linux OOM Killer 开始杀进程
|
||
- SSH daemon 被杀死 → 连接断开
|
||
- 系统核心服务被杀 → 无法重连
|
||
- 最严重时整个系统死机
|
||
|
||
### 立即恢复方法
|
||
|
||
#### 方法 1：物理/远程控制台重启
|
||
```bash
|
||
# 通过云服务商控制台重启服务器
|
||
# 重启后立即禁用 Docker 自动启动
|
||
sudo systemctl disable docker
|
||
sudo systemctl stop docker
|
||
|
||
# 清理所有容器
|
||
cd /path/to/hfb_sys
|
||
docker compose -f deploy/docker-compose.prod.yml down
|
||
```
|
||
|
||
#### 方法 2：强制重启前快速执行
|
||
如果还能短暂连接，立即执行：
|
||
```bash
|
||
sudo systemctl stop docker
|
||
sudo killall -9 dockerd containerd
|
||
```
|
||
|
||
### 根本解决方案（已修复）
|
||
|
||
#### 1. 添加资源限制（docker-compose.prod.yml）
|
||
所有服务现在都有明确的内存和 CPU 限制：
|
||
- MySQL: 512M memory, 1 CPU
|
||
- Redis: 256M memory, 0.5 CPU
|
||
- MinIO: 512M memory, 0.5 CPU
|
||
- Backend: 512M memory, 1 CPU
|
||
- Frontend: 256M memory, 0.5 CPU
|
||
|
||
总计：~2GB 内存（适合 4GB 服务器）
|
||
|
||
#### 2. 串行构建（deploy-prod.sh）
|
||
修改后的脚本：
|
||
```bash
|
||
# 先构建 backend
|
||
compose build backend
|
||
|
||
# 再构建 frontend
|
||
compose build frontend
|
||
|
||
# 最后启动（不再构建）
|
||
compose up -d --no-build
|
||
```
|
||
|
||
这样可以避免内存峰值，但会增加 1-2 分钟部署时间。
|
||
|
||
### 安全部署流程
|
||
|
||
#### 首次部署
|
||
```bash
|
||
# 1. 在本地或有充足资源的机器上预构建镜像
|
||
docker compose -f deploy/docker-compose.prod.yml build
|
||
|
||
# 2. 保存镜像
|
||
docker save -o backend.tar <image_name>:latest
|
||
docker save -o frontend.tar <image_name>:latest
|
||
|
||
# 3. 上传到服务器
|
||
scp *.tar server:/tmp/
|
||
|
||
# 4. 在服务器上加载
|
||
ssh server
|
||
docker load -i /tmp/backend.tar
|
||
docker load -i /tmp/frontend.tar
|
||
|
||
# 5. 使用 --no-build 启动
|
||
./scripts/deploy-prod.sh --no-build
|
||
```
|
||
|
||
#### 日常更新（推荐）
|
||
```bash
|
||
# 直接使用修复后的脚本
|
||
./scripts/deploy-prod.sh
|
||
|
||
# 或者只更新不重新构建
|
||
./scripts/deploy-prod.sh --no-build
|
||
```
|
||
|
||
### 监控服务器资源
|
||
|
||
#### 部署前检查
|
||
```bash
|
||
# 查看可用内存
|
||
free -h
|
||
|
||
# 查看 CPU 负载
|
||
uptime
|
||
|
||
# 建议：至少保留 1GB 可用内存
|
||
```
|
||
|
||
#### 部署中监控
|
||
```bash
|
||
# 另一个终端实时监控
|
||
watch -n 1 'free -h && docker stats --no-stream'
|
||
```
|
||
|
||
### 服务器配置建议
|
||
|
||
#### 最低配置
|
||
- 内存：4GB
|
||
- CPU：2 核
|
||
- 磁盘：20GB
|
||
|
||
#### 推荐配置
|
||
- 内存：8GB
|
||
- CPU：4 核
|
||
- 磁盘：50GB
|
||
- 启用 Swap：4GB
|
||
|
||
#### 启用 Swap（紧急缓冲）
|
||
```bash
|
||
# 创建 4GB swap
|
||
sudo fallocate -l 4G /swapfile
|
||
sudo chmod 600 /swapfile
|
||
sudo mkswap /swapfile
|
||
sudo swapon /swapfile
|
||
|
||
# 永久启用
|
||
echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab
|
||
```
|
||
|
||
### 其他可能原因
|
||
|
||
#### 1. 网络超时
|
||
```bash
|
||
# 增加 SSH 保活
|
||
# 编辑 ~/.ssh/config
|
||
Host your-server
|
||
ServerAliveInterval 60
|
||
ServerAliveCountMax 3
|
||
```
|
||
|
||
#### 2. Docker daemon 崩溃
|
||
```bash
|
||
# 查看 Docker 日志
|
||
sudo journalctl -u docker -n 100 --no-pager
|
||
|
||
# 重启 Docker
|
||
sudo systemctl restart docker
|
||
```
|
||
|
||
#### 3. 磁盘满
|
||
```bash
|
||
# 检查磁盘空间
|
||
df -h
|
||
|
||
# 清理 Docker 垃圾
|
||
docker system prune -a --volumes -f
|
||
```
|
||
|
||
## 预防措施清单
|
||
|
||
- [x] 所有服务添加 memory/CPU 限制
|
||
- [x] 串行构建避免内存峰值
|
||
- [ ] 启用服务器 Swap
|
||
- [ ] 部署前检查可用内存
|
||
- [ ] 设置 SSH 保活
|
||
- [ ] 定期清理 Docker 磁盘
|
||
- [ ] 监控部署过程资源使用
|
||
|
||
## 紧急联系
|
||
|
||
如果服务器完全无响应：
|
||
1. 联系云服务商客服强制重启
|
||
2. 通过 VNC/控制台登录
|
||
3. 考虑升级服务器配置
|