ball-tracking-cv/DEPLOYMENT.md

部署指南

📋 部署前准备

系统要求

• Ubuntu 20.04+ / CentOS 8+ / Debian 11+
• Python 3.8+
• Node.js 16+ 或 Bun
• Nginx
• Supervisor 或 systemd

安装依赖

# Ubuntu/Debian
sudo apt update
sudo apt install python3 python3-venv python3-pip nginx supervisor

# 安装 Bun (推荐)
curl -fsSL https://bun.sh/install | bash

# 或者安装 Node.js
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt-get install -y nodejs

🚀 部署步骤

1. 克隆项目

cd /var/www
sudo git clone <your-repo-url> ball-tracking-server
cd ball-tracking-server

2. 修改配置文件路径

编辑以下文件，将路径替换为实际路径：

• deploy.sh - 第6行 PROJECT_ROOT
• supervisor.conf - command, directory, stdout_logfile, environment 中的路径
• gunicorn.conf.py - 如果需要修改用户
• ball-tracking-server.service - WorkingDirectory, Environment, ExecStart 中的路径
• nginx.conf - root, server_name 等配置

3. 运行部署脚本

# 给脚本执行权限
chmod +x deploy.sh start.sh stop.sh

# 运行部署
sudo ./deploy.sh

4. 配置 Nginx

# 复制 Nginx 配置
sudo cp nginx.conf /etc/nginx/sites-available/ball-tracking-server

# 启用站点
sudo ln -s /etc/nginx/sites-available/ball-tracking-server /etc/nginx/sites-enabled/

# 测试配置
sudo nginx -t

# 重启 Nginx
sudo systemctl restart nginx

🔧 服务管理

使用 Supervisor（推荐）

# 查看状态
sudo supervisorctl status ball-tracking-server

# 启动服务
sudo supervisorctl start ball-tracking-server

# 停止服务
sudo supervisorctl stop ball-tracking-server

# 重启服务
sudo supervisorctl restart ball-tracking-server

# 查看日志
sudo supervisorctl tail -f ball-tracking-server

# 或者使用脚本
./start.sh    # 启动
./stop.sh     # 停止

使用 systemd（备选方案）

# 复制服务文件
sudo cp ball-tracking-server.service /etc/systemd/system/

# 重载服务配置
sudo systemctl daemon-reload

# 启用开机自启
sudo systemctl enable ball-tracking-server

# 启动服务
sudo systemctl start ball-tracking-server

# 查看状态
sudo systemctl status ball-tracking-server

# 查看日志
sudo journalctl -u ball-tracking-server -f

📝 日志文件位置

• Supervisor 日志: logs/supervisor.log
• Gunicorn 访问日志: logs/gunicorn_access.log
• Gunicorn 错误日志: logs/gunicorn_error.log
• Nginx 访问日志: /var/log/nginx/ball-tracking-server_access.log
• Nginx 错误日志: /var/log/nginx/ball-tracking-server_error.log

🔍 故障排查

检查端口占用

sudo netstat -tulpn | grep :5000

检查进程

ps aux | grep gunicorn
ps aux | grep supervisord

检查防火墙

sudo ufw status
sudo ufw allow 80
sudo ufw allow 443

权限问题

sudo chown -R www-data:www-data /var/www/ball-tracking-server
sudo chmod -R 755 /var/www/ball-tracking-server

🔄 更新部署

# 简单更新（自动构建前端）
sudo ./deploy.sh

# 手动更新
git pull origin main
cd app/web && bun run build && cd ../..
sudo supervisorctl restart ball-tracking-server

🌐 域名和 HTTPS

配置域名

1. 修改 nginx.conf 中的 server_name
2. 重启 Nginx

启用 HTTPS (Let's Encrypt)

# 安装 Certbot
sudo apt install certbot python3-certbot-nginx

# 获取证书
sudo certbot --nginx -d your-domain.com -d www.your-domain.com

# 自动续期
sudo crontab -e
# 添加: 0 12 * * * /usr/bin/certbot renew --quiet

📊 监控建议

• 使用 htop 或 glances 监控系统资源
• 设置日志轮转避免磁盘空间不足
• 配置监控告警（如 Zabbix、Prometheus）
• 定期备份数据目录

🚨 安全建议

• 关闭不必要的端口
• 启用防火墙
• 定期更新系统和依赖
• 使用 HTTPS
• 设置强密码和 SSH 密钥登录