# 部署指南

## 📋 部署前准备

### 系统要求
- Ubuntu 20.04+ / CentOS 8+ / Debian 11+
- Python 3.8+
- Node.js 16+ 或 Bun
- Nginx
- Supervisor 或 systemd

### 安装依赖

```bash
# 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. 克隆项目
```bash
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. 运行部署脚本
```bash
# 给脚本执行权限
chmod +x deploy.sh start.sh stop.sh

# 运行部署
sudo ./deploy.sh
```

### 4. 配置 Nginx
```bash
# 复制 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（推荐）
```bash
# 查看状态
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（备选方案）
```bash
# 复制服务文件
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`

## 🔍 故障排查

### 检查端口占用
```bash
sudo netstat -tulpn | grep :5000
```

### 检查进程
```bash
ps aux | grep gunicorn
ps aux | grep supervisord
```

### 检查防火墙
```bash
sudo ufw status
sudo ufw allow 80
sudo ufw allow 443
```

### 权限问题
```bash
sudo chown -R www-data:www-data /var/www/ball-tracking-server
sudo chmod -R 755 /var/www/ball-tracking-server
```

## 🔄 更新部署

```bash
# 简单更新（自动构建前端）
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)
```bash
# 安装 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 密钥登录