# Spug 自动部署配置指南

## 🚀 快速开始（10 分钟完成）

### 步骤 1: 上传脚本到 Spug 服务器

```bash
# 从本地上传
scp spug/deploy.sh user@spug-server:/opt/spug/scripts/
scp spug/deploy.py user@spug-server:/opt/spug/scripts/optional/
scp spug/hospital-backend.service user@target-server:/tmp/

# 设置权限
ssh user@spug-server "chmod +x /opt/spug/scripts/deploy.sh"
```

### 步骤 2: 在目标服务器配置 systemd 服务

登录目标服务器（`user@target-server`）:

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

# 重新加载 systemd
sudo systemctl daemon-reload

# 启用服务（先不启动，等部署后再启动）
sudo systemctl enable hospital-backend

# 创建部署目录
sudo mkdir -p /var/www/hospital-performance
sudo chown -R $USER:$USER /var/www/hospital-performance
```

### 步骤 3: 在 Spug Web 界面配置

#### 3.1 添加主机

路径：**系统管理** -> **主机管理** -> **创建主机**

```
名称：production
IP: <你的目标服务器 IP>
端口：22
认证方式：密钥 或 密码
```

#### 3.2 创建应用

路径：**应用管理** -> **创建应用**

```
应用名称：hospital-performance
应用类型：其他
Git 仓库：https://gitea.gentronhealth.com/chenqi/hospital_performance.git
分支：main
```

#### 3.3 配置环境变量

在应用详情页的 **环境变量** 标签页，添加以下变量：

**必需配置：**
```
SPUG_DEPLOY_DIR=/var/www/hospital-performance
SPUG_GIT_BRANCH=main
```

**可选配置：**
```
PYTHON_VERSION=python3.10
BACKEND_SERVICE=hospital-backend
BACKEND_PORT=8000
FRONTEND_SERVICE=nginx
LOG_FILE=/var/log/spug/deploy.log
```

**数据库配置（如果需要在部署时修改）：**
```
DATABASE_HOST=192.168.110.252
DATABASE_PORT=15432
DATABASE_USER=postgresql
DATABASE_PASSWORD=Jchl1528
DATABASE_NAME=hospital_performance
SECRET_KEY=<生成一个随机密钥>
DEBUG=False
```

#### 3.4 配置发布设置

在应用的 **发布配置** 标签页：

```
构建类型：跳过构建
发布脚本：/opt/spug/scripts/deploy.sh
```

### 步骤 4: 执行首次发布

路径：**发布管理** -> **创建发布单**

1. 选择应用：`hospital-performance`
2. 选择版本：选择最新的 commit
3. 选择主机：`production`
4. 点击 **立即发布**

---

## 📋 验证部署

### 查看部署日志

在目标服务器上：

```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

# 前端 Nginx
systemctl status nginx

# 查看进程
ps aux | grep uvicorn
ps aux | grep nginx
```

### 测试 API

```bash
# 健康检查
curl http://localhost:8000/api/v1/health

# 登录测试
curl -X POST http://localhost:8000/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"admin123"}'
```

### 访问前端

浏览器访问：`http://<服务器 IP>`

应该能看到登录页面。

---

## 🔧 常见问题排查

### 问题 1: 环境变量为空

**现象：** 日志显示 `PROJECT_NAME:` 和 `DEPLOY_DIR:` 为空

**原因：** Spug 没有正确传递环境变量

**解决：**
1. 检查应用的"环境变量"是否正确配置
2. 确保 `SPUG_DEPLOY_DIR` 不为空
3. 脚本已做容错处理，会自动使用默认值

### 问题 2: Git 克隆失败

**现象：** `fatal: destination path '.' already exists and is not an empty directory.`

**原因：** 部署目录非空且没有 .git 目录

**解决：**
- 脚本已自动处理，会备份现有文件后克隆
- 或者手动清理部署目录：`rm -rf /var/www/hospital-performance/*`

### 问题 3: 权限错误

**现象：** `Permission denied`

**解决：**
```bash
# 修复目录权限
sudo chown -R $USER:$USER /var/www/hospital-performance
sudo chmod -R 755 /var/www/hospital-performance
```

### 问题 4: 服务启动失败

**现象：** `systemctl restart hospital-backend` 失败

**排查：**
```bash
# 查看详细日志
journalctl -u hospital-backend -n 50

# 检查端口占用
sudo lsof -i :8000

# 手动测试启动
cd /var/www/hospital-performance/backend
source venv/bin/activate
uvicorn app.main:app --host 0.0.0.0 --port 8000
```

### 问题 5: 数据库连接失败

**现象：** `asyncpg.exceptions.ConnectionRefusedError`

**解决：**
```bash
# 测试数据库连接
psql -h 192.168.110.252 -p 15432 -U postgres -d hospital_performance

# 如果连不上，检查防火墙
sudo ufw status
sudo telnet 192.168.110.252 15432
```

---

## 🎯 自动化流程说明

### 完整部署流程

```
Spug 触发发布
    ↓
1. 前置检查（命令、磁盘空间）
    ↓
2. 代码更新（Git clone/pull）
    ↓
3. 备份旧版本（保留 30 天）
    ↓
4. 后端部署
   ├─ 创建/激活虚拟环境
   ├─ 安装 Python 依赖
   ├─ 数据库迁移
   ├─ 重启 systemd 服务
    ↓
5. 前端部署
   ├─ 安装 Node 依赖
   ├─ 构建前端
   ├─ 重载 Nginx
    ↓
6. 健康检查
   ├─ API 可用性
   ├─ 前端文件完整性
    ↓
7. 清理临时文件
    ↓
部署成功！
```

### 回滚流程

如果部署失败，可以：

```bash
# 1. 停止服务
systemctl stop hospital-backend

# 2. 恢复代码
cd /var/www/hospital-performance
cp -r backups/backup_YYYYMMDD_HHMMSS_backend backend
cp -r backups/backup_YYYYMMDD_HHMMSS_frontend_dist frontend/dist

# 3. 恢复数据库（如果需要）
psql -h 192.168.110.252 -p 15432 -U postgres hospital_performance < backup.sql

# 4. 重启服务
systemctl start hospital-backend
systemctl reload nginx
```

---

## 📊 监控与告警

### 关键指标

- **API 响应时间**: < 200ms
- **页面加载时间**: < 3s
- **服务可用性**: > 99.9%
- **错误率**: < 0.1%

### 监控命令

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

# 内存使用
free -h

# 磁盘 IO
iostat -x 1

# 网络流量
iftop -P -n

# 数据库连接数
psql -h 192.168.110.252 -p 15432 -U postgres -d hospital_performance -c "SELECT count(*) FROM pg_stat_activity;"
```

### 日志聚合

```bash
# 后端日志
journalctl -u hospital-backend -f

# Nginx 访问日志
tail -f /var/log/nginx/access.log

# Nginx 错误日志
tail -f /var/log/nginx/error.log

# Spug 部署日志
tail -f /var/log/spug/deploy.log
```

---

## 🔄 持续集成建议

### Git 工作流

```
main 分支（生产）
  ↑
develop 分支（测试）
  ↑
feature/* 分支（开发）
```

### 发布频率

- **小功能/修复**: 每天 1-2 次
- **大版本**: 每周或每两周一次
- **紧急修复**: 随时发布

### 最佳实践

1. ✅ **代码审查**: 所有合并到 main 的代码必须经过 review
2. ✅ **测试环境**: 先在 develop 分支测试，再发布到生产
3. ✅ **备份策略**: 数据库每天自动备份
4. ✅ **灰度发布**: 重要变更先在小范围测试
5. ✅ **监控告警**: 配置钉钉/企业微信通知

---

## 📞 技术支持

遇到问题时：

1. 查看部署日志：`/var/log/spug/deploy.log`
2. 查看服务日志：`journalctl -u hospital-backend`
3. 联系开发团队或查看项目文档

---

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