hospital_performance/spug/DEPLOYMENT_GUIDE.md

Spug 自动部署配置指南

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

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

# 从本地上传
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）:

# 复制服务文件
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. 点击 立即发布

---

📋 验证部署

查看部署日志

在目标服务器上：

# 实时查看
tail -f /var/log/spug/deploy.log

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

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

检查服务状态

# 后端服务
systemctl status hospital-backend

# 前端 Nginx
systemctl status nginx

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

测试 API

# 健康检查
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

解决：

# 修复目录权限
sudo chown -R $USER:$USER /var/www/hospital-performance
sudo chmod -R 755 /var/www/hospital-performance

问题 4: 服务启动失败

现象： systemctl restart hospital-backend 失败

排查：

# 查看详细日志
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

解决：

# 测试数据库连接
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. 清理临时文件
    ↓
部署成功！

回滚流程

如果部署失败，可以：

# 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%

监控命令

# 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;"

日志聚合

# 后端日志
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. 联系开发团队或查看项目文档

---

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