292 lines
5.7 KiB
Markdown
292 lines
5.7 KiB
Markdown
# 后端服务守护进程配置指南
|
||
|
||
**配置时间**: 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 服务（备选）
|
||
- [ ] 日志轮转配置
|
||
- [ ] 监控告警配置
|
||
|
||
---
|
||
|
||
**配置完成！后端服务现在具有自动恢复能力！** 🎉
|