jiachenlong/docs/BACKEND_SERVICE_GUIDE.md

# 后端服务守护进程配置指南

**配置时间**: 2026-03-14  
**版本**: v2.7.4

---

## 🔍 后端不稳定原因分析

### 可能原因

1. **手动启动无守护** - 之前使用 `nohup` 但没有监控
2. **服务器重启** - 服务器重启后需要手动启动
3. **内存不足** - 检查发现内存充足 (3.5GB 可用 1.5GB)
4. **磁盘空间** - 检查发现磁盘充足 (49GB 可用 31GB)
5. **进程意外终止** - 可能因系统资源调度被 kill

### 日志分析

检查 `/tmp/zodiac-backend.log` 发现：
- ✅ 没有 Python 异常
- ✅ 没有内存溢出
- ✅ 没有数据库连接错误
- ✅ 服务正常运行直到意外停止

**结论**: 进程缺少守护机制，意外停止后无法自动恢复

---

## ✅ 解决方案：双重守护

### 方案 1: 启动脚本 + Crontab 监控（已配置）

**启动脚本**: `/home/admin/.openclaw/workspace/zodiac-collector/backend-fastapi/start.sh`

**功能**:
- ✅ 检查进程是否已在运行
- ✅ 停止旧进程
- ✅ 启动新进程
- ✅ 保存 PID 到文件
- ✅ 验证启动是否成功

**Crontab 监控**: 每 2 分钟检查一次

```bash
*/2 * * * * if ! ps aux | grep -v grep | grep 'uvicorn app.main:app' > /dev/null; then 
  /home/admin/.openclaw/workspace/zodiac-collector/backend-fastapi/start.sh >> /tmp/backend-watch.log 2>&1; 
fi
```

**优点**:
- 简单可靠
- 自动恢复
- 日志记录

---

### 方案 2: systemd 服务（备选）

如果 crontab 方案不可靠，可以使用 systemd：

**服务文件**: `/etc/systemd/system/zodiac-backend.service`

```ini
[Unit]
Description=甲辰藏品管理系统 FastAPI 后端服务
After=network.target

[Service]
Type=simple
User=admin
WorkingDirectory=/home/admin/.openclaw/workspace/zodiac-collector/backend-fastapi
ExecStart=/usr/local/python3.12/bin/python3.12 -m uvicorn app.main:app --port 3000 --host 0.0.0.0
Restart=always
RestartSec=3

[Install]
WantedBy=multi-user.target
```

**启用命令**:
```bash
sudo systemctl daemon-reload
sudo systemctl enable zodiac-backend
sudo systemctl start zodiac-backend
```

---

## 📋 使用指南

### 启动服务

```bash
# 方法 1: 使用启动脚本
/home/admin/.openclaw/workspace/zodiac-collector/backend-fastapi/start.sh

# 方法 2: 手动启动
cd /home/admin/.openclaw/workspace/zodiac-collector/backend-fastapi
nohup /usr/local/python3.12/bin/python3.12 -m uvicorn app.main:app --port 3000 --host 0.0.0.0 > /tmp/zodiac-backend.log 2>&1 &
```

### 停止服务

```bash
# 方法 1: 使用 PID 文件
kill $(cat /tmp/zodiac-backend.pid)

# 方法 2: 杀死进程
pkill -f "uvicorn app.main:app"
```

### 查看状态

```bash
# 查看进程
ps aux | grep uvicorn

# 查看日志
tail -f /tmp/zodiac-backend.log

# 查看监控日志
tail -f /tmp/backend-watch.log
```

### 重启服务

```bash
pkill -f "uvicorn app.main:app"
sleep 2
/home/admin/.openclaw/workspace/zodiac-collector/backend-fastapi/start.sh
```

---

## 🔧 故障排查

### 问题 1: 服务无法启动

**检查端口占用**:
```bash
netstat -tlnp | grep 3000
# 如果占用，杀死进程
kill -9 $(lsof -t -i:3000)
```

**检查 Python 路径**:
```bash
which python3.12
# 应该是：/usr/local/python3.12/bin/python3.12
```

**检查依赖**:
```bash
cd /home/admin/.openclaw/workspace/zodiac-collector/backend-fastapi
pip3 list | grep -i "fastapi\|uvicorn\|sqlalchemy"
```

### 问题 2: 服务频繁重启

**查看监控日志**:
```bash
tail -100 /tmp/backend-watch.log
```

**查看系统日志**:
```bash
dmesg | grep -i "killed\|oom"
```

**检查资源使用**:
```bash
free -h
df -h
top -bn1 | head -20
```

### 问题 3: Crontab 不执行

**检查 crontab 配置**:
```bash
crontab -l
```

**检查 cron 服务**:
```bash
systemctl status crond
```

**查看 cron 日志**:
```bash
tail -f /var/log/cron
```

---

## 📊 监控指标

### 进程状态

```bash
# 进程是否在运行
ps aux | grep uvicorn | grep -v grep | wc -l
# 应该返回：1
```

### 服务响应

```bash
# 测试 API 响应
curl -s http://localhost:3000/api/auth/login -X POST \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "username=admin&password=admin123" | python3 -c "import sys,json; d=json.load(sys.stdin); print('正常' if 'access_token' in d else '异常')"
```

### 日志大小

```bash
# 检查日志文件大小
ls -lh /tmp/zodiac-backend.log
# 如果>100MB，考虑轮转
```

---

## 🎯 最佳实践

### 1. 定期重启

建议每周重启一次服务，释放内存：

```bash
# 添加到 crontab
0 3 * * 0 pkill -f "uvicorn app.main:app" && sleep 2 && /home/admin/.openclaw/workspace/zodiac-collector/backend-fastapi/start.sh
```

### 2. 日志轮转

创建 `/etc/logrotate.d/zodiac-backend`:

```
/tmp/zodiac-backend.log {
    daily
    rotate 7
    compress
    delaycompress
    missingok
    notifempty
    create 0644 admin admin
}
```

### 3. 监控告警

可以添加简单的告警脚本：

```bash
#!/bin/bash
if ! curl -s http://localhost:3000/health > /dev/null; then
    echo "后端服务异常！" | mail -s "告警：后端服务宕机" admin@example.com
fi
```

---

## 📝 配置文件清单

| 文件 | 路径 | 说明 |
|------|------|------|
| **启动脚本** | `backend-fastapi/start.sh` | 服务启动脚本 |
| **PID 文件** | `/tmp/zodiac-backend.pid` | 进程 ID |
| **日志文件** | `/tmp/zodiac-backend.log` | 运行日志 |
| **监控日志** | `/tmp/backend-watch.log` | 监控日志 |
| **Crontab** | `crontab -l` | 定时任务 |

---

## ✅ 验证清单

- [x] 启动脚本已创建
- [x] 脚本权限已设置 (chmod +x)
- [x] Crontab 监控已配置
- [x] 服务正在运行
- [x] API 响应正常
- [ ] systemd 服务（备选）
- [ ] 日志轮转配置
- [ ] 监控告警配置

---

**配置完成！后端服务现在具有自动恢复能力！** 🎉