257 lines
5.7 KiB
Markdown
257 lines
5.7 KiB
Markdown
# Spug 自动部署脚本说明
|
||
|
||
## 📁 文件说明
|
||
|
||
### 1. `deploy.sh` - Bash 版本
|
||
适用于 Linux/Unix 系统的 Shell 脚本，可在 Spug 的"执行任务"中直接调用。
|
||
|
||
**特点：**
|
||
- 轻量级，无需额外依赖
|
||
- 直接在目标服务器上执行
|
||
- 适合简单的部署场景
|
||
|
||
### 2. `deploy.py` - Python 版本
|
||
使用 Python 编写的部署脚本，功能更强大，错误处理更完善。
|
||
|
||
**特点：**
|
||
- 更好的错误处理和日志记录
|
||
- 支持健康检查（需要 requests 库）
|
||
- 更适合复杂的部署逻辑
|
||
|
||
---
|
||
|
||
## 🚀 在 Spug 中的配置步骤
|
||
|
||
### 方案一：使用 Bash 脚本（推荐）
|
||
|
||
#### 1. 上传脚本到服务器
|
||
```bash
|
||
# 将 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 应用的 **环境变量** 中添加：
|
||
|
||
```bash
|
||
# 项目配置
|
||
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 依赖：
|
||
```bash
|
||
pip3 install requests
|
||
```
|
||
|
||
#### 2. 上传脚本
|
||
```bash
|
||
scp deploy.py spug-server:/opt/spug/scripts/
|
||
chmod +x /opt/spug/scripts/deploy.py
|
||
```
|
||
|
||
#### 3. Spug 配置
|
||
与 Bash 脚本类似，只需将发布脚本改为：
|
||
```bash
|
||
/opt/spug/scripts/deploy.py
|
||
```
|
||
|
||
或在 Spug 执行任务中配置：
|
||
```bash
|
||
python3 /opt/spug/scripts/deploy.py
|
||
```
|
||
|
||
---
|
||
|
||
## 🔧 systemd 服务配置
|
||
|
||
### 后端服务配置示例
|
||
|
||
创建 `/etc/systemd/system/hospital-backend.service`：
|
||
|
||
```ini
|
||
[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
|
||
```
|
||
|
||
启用服务：
|
||
```bash
|
||
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` |
|
||
|
||
---
|
||
|
||
## 🔍 故障排查
|
||
|
||
### 查看部署日志
|
||
```bash
|
||
tail -f /var/log/spug/deploy.log
|
||
```
|
||
|
||
### 手动执行脚本测试
|
||
```bash
|
||
cd /opt/spug/scripts
|
||
./deploy.sh
|
||
```
|
||
|
||
### 检查服务状态
|
||
```bash
|
||
systemctl status hospital-backend
|
||
systemctl status nginx
|
||
```
|
||
|
||
### 常见问题
|
||
|
||
#### 1. 权限问题
|
||
确保脚本有执行权限：
|
||
```bash
|
||
chmod +x /opt/spug/scripts/deploy.sh
|
||
```
|
||
|
||
#### 2. Python 虚拟环境问题
|
||
删除并重建虚拟环境：
|
||
```bash
|
||
rm -rf /var/www/hospital-performance/venv
|
||
python3.10 -m venv /var/www/hospital-performance/venv
|
||
```
|
||
|
||
#### 3. 数据库迁移失败
|
||
手动执行迁移：
|
||
```bash
|
||
cd /var/www/hospital-performance/backend
|
||
source venv/bin/activate
|
||
alembic upgrade head
|
||
```
|
||
|
||
#### 4. 前端构建失败
|
||
检查 Node.js 版本：
|
||
```bash
|
||
node -v
|
||
npm -v
|
||
```
|
||
|
||
清理后重新构建：
|
||
```bash
|
||
cd frontend
|
||
rm -rf node_modules package-lock.json
|
||
npm install
|
||
npm run build
|
||
```
|
||
|
||
---
|
||
|
||
## 🎯 最佳实践
|
||
|
||
### 1. 灰度发布
|
||
先在测试环境验证，再发布到生产环境。
|
||
|
||
### 2. 备份策略
|
||
脚本会自动保留 30 天备份，重要发布前建议手动备份数据库：
|
||
```bash
|
||
pg_dump -h localhost -U postgres hospital_performance > backup_$(date +%Y%m%d).sql
|
||
```
|
||
|
||
### 3. 回滚方案
|
||
如果发布失败，从备份恢复：
|
||
```bash
|
||
# 停止服务
|
||
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 的监控功能，配置服务健康检查和告警通知。
|
||
|
||
---
|
||
|
||
## 📞 技术支持
|
||
|
||
如有问题，请联系开发团队或查看项目文档。
|