hospital_performance/spug/README.md

Spug 自动部署脚本说明

📁 文件说明

1. deploy.sh - Bash 版本

适用于 Linux/Unix 系统的 Shell 脚本，可在 Spug 的"执行任务"中直接调用。

特点：

• 轻量级，无需额外依赖
• 直接在目标服务器上执行
• 适合简单的部署场景

2. deploy.py - Python 版本

使用 Python 编写的部署脚本，功能更强大，错误处理更完善。

特点：

• 更好的错误处理和日志记录
• 支持健康检查（需要 requests 库）
• 更适合复杂的部署逻辑

---

🚀 在 Spug 中的配置步骤

方案一：使用 Bash 脚本（推荐）

1. 上传脚本到服务器

# 将 deploy.sh 上传到 Spug 服务器
scp deploy.sh spug-server:/opt/spug/scripts/
chmod +x /opt/spug/scripts/deploy.sh

2. 在 Spug 创建应用

• 进入 应用管理 -> 创建应用
• 填写基本信息：
  • 应用名称：hospital-performance
  • 应用类型：其他
  • 部署方式：自定义

3. 配置发布设置

在应用的 发布配置 中：

• 构建类型：选择 本地构建 或 跳过构建
• 发布脚本：填写 /opt/spug/scripts/deploy.sh

4. 设置环境变量

在 Spug 应用的 环境变量 中添加：

# 项目配置
SPUG_APP_NAME=hospital-performance
SPUG_DEPLOY_DIR=/var/www/hospital-performance

# Git 配置
SPUG_GIT_REPO=https://gitea.gentronhealth.com/chenqi/hospital_performance.git
SPUG_GIT_BRANCH=main

# Python 配置
PYTHON_VERSION=python3.10

# Node.js 配置
NODE_VERSION=18

# 服务配置
BACKEND_SERVICE=hospital-backend
BACKEND_PORT=8000
FRONTEND_SERVICE=nginx

# 日志配置
LOG_FILE=/var/log/spug/deploy.log

5. 配置 SSH 连接

在 Spug 的 主机管理 中添加目标服务器：

• 主机名：例如 production-server
• IP 地址：你的服务器 IP
• SSH 端口：22（默认）
• 认证方式：密钥或密码

6. 创建发布单

• 进入 发布管理 -> 创建发布单
• 选择应用和要发布的版本
• 选择目标主机
• 执行发布

---

方案二：使用 Python 脚本

1. 安装依赖

在 Spug 服务器上安装 Python 依赖：

pip3 install requests

2. 上传脚本

scp deploy.py spug-server:/opt/spug/scripts/
chmod +x /opt/spug/scripts/deploy.py

3. Spug 配置

与 Bash 脚本类似，只需将发布脚本改为：

/opt/spug/scripts/deploy.py

或在 Spug 执行任务中配置：

python3 /opt/spug/scripts/deploy.py

---

🔧 systemd 服务配置

后端服务配置示例

创建 /etc/systemd/system/hospital-backend.service：

[Unit]
Description=Hospital Performance Backend Service
After=network.target postgresql.service

[Service]
Type=simple
User=www-data
Group=www-data
WorkingDirectory=/var/www/hospital-performance/backend
Environment="PATH=/var/www/hospital-performance/venv/bin"
ExecStart=/var/www/hospital-performance/venv/bin/uvicorn app.main:app --host 0.0.0.0 --port 8000
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

启用服务：

sudo systemctl daemon-reload
sudo systemctl enable hospital-backend
sudo systemctl start hospital-backend

---

📝 环境变量说明

变量名	说明	默认值
SPUG_APP_NAME	应用名称	hospital-performance
SPUG_DEPLOY_DIR	部署目录	/var/www/hospital-performance
SPUG_GIT_REPO	Git 仓库地址	Gitea 地址
SPUG_GIT_BRANCH	Git 分支	main
PYTHON_VERSION	Python 版本	python3.10
NODE_VERSION	Node.js 版本	18
BACKEND_SERVICE	后端服务名	hospital-backend
BACKEND_PORT	后端端口	8000
FRONTEND_SERVICE	前端服务名	nginx
LOG_FILE	日志文件	/var/log/spug/deploy.log

---

🔍 故障排查

查看部署日志

tail -f /var/log/spug/deploy.log

手动执行脚本测试

cd /opt/spug/scripts
./deploy.sh

检查服务状态

systemctl status hospital-backend
systemctl status nginx

常见问题

1. 权限问题

确保脚本有执行权限：

chmod +x /opt/spug/scripts/deploy.sh

2. Python 虚拟环境问题

删除并重建虚拟环境：

rm -rf /var/www/hospital-performance/venv
python3.10 -m venv /var/www/hospital-performance/venv

3. 数据库迁移失败

手动执行迁移：

cd /var/www/hospital-performance/backend
source venv/bin/activate
alembic upgrade head

4. 前端构建失败

检查 Node.js 版本：

node -v
npm -v

清理后重新构建：

cd frontend
rm -rf node_modules package-lock.json
npm install
npm run build

---

🎯 最佳实践

1. 灰度发布

先在测试环境验证，再发布到生产环境。

2. 备份策略

脚本会自动保留 30 天备份，重要发布前建议手动备份数据库：

pg_dump -h localhost -U postgres hospital_performance > backup_$(date +%Y%m%d).sql

3. 回滚方案

如果发布失败，从备份恢复：

# 停止服务
systemctl stop hospital-backend

# 恢复代码
cp -r /var/www/hospital-performance/backups/backup_20260228_120000_backend /var/www/hospital-performance/backend

# 重启服务
systemctl start hospital-backend

4. 监控告警

结合 Spug 的监控功能，配置服务健康检查和告警通知。

---

📞 技术支持

如有问题，请联系开发团队或查看项目文档。