5.7 KiB

Raw Permalink Blame History

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

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

🔍 后端不稳定原因分析

可能原因

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

日志分析

检查 /tmp/zodiac-backend.log 发现：

✅ 没有 Python 异常
✅ 没有内存溢出
✅ 没有数据库连接错误
✅ 服务正常运行直到意外停止

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

✅ 解决方案：双重守护

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

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

功能:

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

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

*/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

[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

启用命令:

sudo systemctl daemon-reload
sudo systemctl enable zodiac-backend
sudo systemctl start zodiac-backend

📋 使用指南

启动服务

# 方法 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 &

停止服务

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

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

查看状态

# 查看进程
ps aux | grep uvicorn

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

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

重启服务

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

🔧 故障排查

问题 1: 服务无法启动

检查端口占用:

netstat -tlnp | grep 3000
# 如果占用，杀死进程
kill -9 $(lsof -t -i:3000)

检查 Python 路径:

which python3.12
# 应该是：/usr/local/python3.12/bin/python3.12

检查依赖:

cd /home/admin/.openclaw/workspace/zodiac-collector/backend-fastapi
pip3 list | grep -i "fastapi\|uvicorn\|sqlalchemy"

问题 2: 服务频繁重启

查看监控日志:

tail -100 /tmp/backend-watch.log

查看系统日志:

dmesg | grep -i "killed\|oom"

检查资源使用:

free -h
df -h
top -bn1 | head -20

问题 3: Crontab 不执行

检查 crontab 配置:

crontab -l

检查 cron 服务:

systemctl status crond

查看 cron 日志:

tail -f /var/log/cron

📊 监控指标

进程状态

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

服务响应

# 测试 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 '异常')"

日志大小

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

🎯 最佳实践

1. 定期重启

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

# 添加到 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. 监控告警

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

#!/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`	定时任务

✅ 验证清单

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

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

5.7 KiB Raw Permalink Blame History Unescape Escape