# Spug 部署快速参考

## 🚀 快速开始（5 分钟配置）

### 1. 上传脚本到 Spug 服务器
```bash
scp spug/deploy.sh user@spug-server:/opt/spug/scripts/
scp spug/hospital-backend.service user@spug-server:/tmp/
ssh user@spug-server "chmod +x /opt/spug/scripts/deploy.sh"
```

### 2. 在目标服务器配置 systemd 服务
```bash
# 登录目标服务器
ssh user@target-server

# 复制服务文件
sudo cp /tmp/hospital-backend.service /etc/systemd/system/

# 启用服务
sudo systemctl daemon-reload
sudo systemctl enable hospital-backend
```

### 3. 在 Spug Web 界面配置

#### 步骤 1: 添加主机
- 菜单：**系统管理** -> **主机管理** -> **创建主机**
- 填写：
  - 名称：`production`
  - IP：你的服务器 IP
  - 端口：22
  - 认证：选择密钥或密码

#### 步骤 2: 创建应用
- 菜单：**应用管理** -> **创建应用**
- 填写：
  - 名称：`hospital-performance`
  - 类型：`其他`
  - 仓库地址：`https://gitea.gentronhealth.com/chenqi/hospital_performance.git`
  - 分支：`main`

#### 步骤 3: 配置环境变量
在应用详情页的 **环境变量** 标签页添加：
```
SPUG_DEPLOY_DIR=/var/www/hospital-performance
PYTHON_VERSION=python3.10
BACKEND_SERVICE=hospital-backend
BACKEND_PORT=8000
FRONTEND_SERVICE=nginx
LOG_FILE=/var/log/spug/deploy.log
```

#### 步骤 4: 配置发布
- 进入应用的 **发布配置** 标签页
- 构建类型：`跳过构建`
- 发布脚本：`/opt/spug/scripts/deploy.sh`
- 保存

#### 步骤 5: 执行发布
- 菜单：**发布管理** -> **创建发布单**
- 选择应用和版本
- 选择主机 `production`
- 点击 **立即发布**

---

## 📋 常用命令速查

### 查看部署日志
```bash
# 实时查看
tail -f /var/log/spug/deploy.log

# 查看最近 100 行
tail -n 100 /var/log/spug/deploy.log

# 搜索错误
grep ERROR /var/log/spug/deploy.log
```

### 服务管理
```bash
# 查看状态
systemctl status hospital-backend
systemctl status nginx

# 重启服务
systemctl restart hospital-backend
systemctl restart nginx

# 查看日志
journalctl -u hospital-backend -f
```

### Git 操作
```bash
# 查看当前版本
cd /var/www/hospital-performance
git log --oneline -5

# 回退版本
git reset --hard <commit-hash>
```

### 数据库操作
```bash
# 手动迁移
cd /var/www/hospital-performance/backend
source ../venv/bin/activate
alembic upgrade head

# 查看迁移历史
alembic history

# 数据库备份
pg_dump -h 192.168.110.252 -p 15432 -U postgres hospital_performance > backup.sql

# 数据库恢复
psql -h 192.168.110.252 -p 15432 -U postgres hospital_performance < backup.sql
```

### 前端调试
```bash
# 检查 Node 版本
node -v
npm -v

# 清理重建
cd /var/www/hospital-performance/frontend
rm -rf node_modules dist
npm install --production
npm run build
```

---

## 🔧 故障排查流程图

```
部署失败
├─ 前置检查失败
│  ├─ 缺少命令 → 安装 git/python/node/npm
│  └─ 磁盘不足 → 清理空间或扩容
│
├─ 代码更新失败
│  ├─ Git 连接失败 → 检查网络和凭证
│  └─ 冲突 → 手动解决或重置
│
├─ 后端部署失败
│  ├─ 虚拟环境 → 删除重建 venv
│  ├─ 依赖安装 → 检查 requirements.txt
│  ├─ 数据库迁移 → 手动执行 alembic
│  └─ 服务启动 → 检查 systemd 配置
│
└─ 前端部署失败
   ├─ npm install 失败 → 清理缓存 npm cache clean
   ├─ 构建失败 → 检查 Node.js 版本
   └─ Nginx 加载 → systemctl reload nginx
```

---

## ⚠️ 常见问题速查

### Q1: 权限错误 "Permission denied"
```bash
# 修复目录权限
sudo chown -R www-data:www-data /var/www/hospital-performance
sudo chmod -R 755 /var/www/hospital-performance
```

### Q2: 端口被占用
```bash
# 查看端口占用
sudo lsof -i :8000
sudo netstat -tlnp | grep 8000

# 杀死进程
sudo kill -9 <PID>
```

### Q3: 数据库连接失败
```bash
# 测试连接
psql -h 192.168.110.252 -p 15432 -U postgres -d hospital_performance

# 检查防火墙
sudo ufw status
sudo telnet 192.168.110.252 15432
```

### Q4: Python 模块找不到
```bash
# 确认虚拟环境激活
source /var/www/hospital-performance/venv/bin/activate

# 重新安装依赖
pip install -r requirements.txt --force-reinstall
```

### Q5: 前端页面空白
```bash
# 检查浏览器控制台错误
F12 -> Console

# 检查 Nginx 配置
sudo nginx -t
sudo cat /etc/nginx/sites-available/default

# 检查文件权限
ls -la /var/www/hospital-performance/frontend/dist/
```

---

## 📊 监控指标

### 关键指标
- **API 响应时间**: < 200ms
- **页面加载时间**: < 3s
- **服务可用性**: > 99.9%
- **数据库连接数**: < 100

### 监控命令
```bash
# CPU 使用率
top -bn1 | grep "Cpu(s)"

# 内存使用
free -h

# 磁盘 IO
iostat -x 1

# 网络流量
iftop -P -n

# 进程监控
ps aux | grep uvicorn
ps aux | grep nginx
```

---

## 🎯 发布清单

### 发布前检查
- [ ] 代码已合并到 main 分支
- [ ] 通过所有测试
- [ ] 数据库迁移脚本就绪
- [ ] 备份策略已配置
- [ ] 回滚方案已准备

### 发布中检查
- [ ] 代码更新成功
- [ ] 依赖安装完成
- [ ] 数据库迁移成功
- [ ] 服务启动正常
- [ ] 健康检查通过

### 发布后验证
- [ ] 访问前端页面
- [ ] 测试登录功能
- [ ] 验证核心功能
- [ ] 检查错误日志
- [ ] 监控系统资源

---

## 📞 应急联系

### 升级流程
1. **一级故障**（功能异常）→ 开发团队
2. **二级故障**（性能下降）→ 运维团队 + 开发负责人
3. **三级故障**（服务中断）→ 紧急响应小组

### 回滚命令
```bash
# 快速回滚到上一个版本
cd /var/www/hospital-performance
git reset --hard HEAD~1

# 重启服务
systemctl restart hospital-backend
systemctl restart nginx
```

---

**提示**: 将此文件打印或保存为书签，便于快速查阅！