feat: add Spug auto-deployment scripts for fullstack project
This commit is contained in:
256
spug/README.md
Normal file
256
spug/README.md
Normal file
@@ -0,0 +1,256 @@
|
||||
# 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 的监控功能，配置服务健康检查和告警通知。
|
||||
|
||||
---
|
||||
|
||||
## 📞 技术支持
|
||||
|
||||
如有问题，请联系开发团队或查看项目文档。
|
||||
Reference in New Issue
Block a user