feat: add Spug auto-deployment scripts for fullstack project
This commit is contained in:
291
spug/QUICKSTART.md
Normal file
291
spug/QUICKSTART.md
Normal file
@@ -0,0 +1,291 @@
|
||||
# Spug 部署快速参考
|
||||
|
||||
## 🚀 快速开始（5 分钟配置）
|
||||
|
||||
### 1. 上传脚本到 Spug 服务器
|
||||
```bash
|
||||
scp spug/deploy.sh user@spug-server:/opt/spug/scripts/
|
||||
scp spug/hospital-backend.service user@spug-server:/tmp/
|
||||
ssh user@spug-server "chmod +x /opt/spug/scripts/deploy.sh"
|
||||
```
|
||||
|
||||
### 2. 在目标服务器配置 systemd 服务
|
||||
```bash
|
||||
# 登录目标服务器
|
||||
ssh user@target-server
|
||||
|
||||
# 复制服务文件
|
||||
sudo cp /tmp/hospital-backend.service /etc/systemd/system/
|
||||
|
||||
# 启用服务
|
||||
sudo systemctl daemon-reload
|
||||
sudo systemctl enable hospital-backend
|
||||
```
|
||||
|
||||
### 3. 在 Spug Web 界面配置
|
||||
|
||||
#### 步骤 1: 添加主机
|
||||
- 菜单：**系统管理** -> **主机管理** -> **创建主机**
|
||||
- 填写：
|
||||
- 名称：`production`
|
||||
- IP：你的服务器 IP
|
||||
- 端口：22
|
||||
- 认证：选择密钥或密码
|
||||
|
||||
#### 步骤 2: 创建应用
|
||||
- 菜单：**应用管理** -> **创建应用**
|
||||
- 填写：
|
||||
- 名称：`hospital-performance`
|
||||
- 类型：`其他`
|
||||
- 仓库地址：`https://gitea.gentronhealth.com/chenqi/hospital_performance.git`
|
||||
- 分支：`main`
|
||||
|
||||
#### 步骤 3: 配置环境变量
|
||||
在应用详情页的 **环境变量** 标签页添加：
|
||||
```
|
||||
SPUG_DEPLOY_DIR=/var/www/hospital-performance
|
||||
PYTHON_VERSION=python3.10
|
||||
BACKEND_SERVICE=hospital-backend
|
||||
BACKEND_PORT=8000
|
||||
FRONTEND_SERVICE=nginx
|
||||
LOG_FILE=/var/log/spug/deploy.log
|
||||
```
|
||||
|
||||
#### 步骤 4: 配置发布
|
||||
- 进入应用的 **发布配置** 标签页
|
||||
- 构建类型：`跳过构建`
|
||||
- 发布脚本：`/opt/spug/scripts/deploy.sh`
|
||||
- 保存
|
||||
|
||||
#### 步骤 5: 执行发布
|
||||
- 菜单：**发布管理** -> **创建发布单**
|
||||
- 选择应用和版本
|
||||
- 选择主机 `production`
|
||||
- 点击 **立即发布**
|
||||
|
||||
---
|
||||
|
||||
## 📋 常用命令速查
|
||||
|
||||
### 查看部署日志
|
||||
```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
|
||||
systemctl status nginx
|
||||
|
||||
# 重启服务
|
||||
systemctl restart hospital-backend
|
||||
systemctl restart nginx
|
||||
|
||||
# 查看日志
|
||||
journalctl -u hospital-backend -f
|
||||
```
|
||||
|
||||
### Git 操作
|
||||
```bash
|
||||
# 查看当前版本
|
||||
cd /var/www/hospital-performance
|
||||
git log --oneline -5
|
||||
|
||||
# 回退版本
|
||||
git reset --hard <commit-hash>
|
||||
```
|
||||
|
||||
### 数据库操作
|
||||
```bash
|
||||
# 手动迁移
|
||||
cd /var/www/hospital-performance/backend
|
||||
source ../venv/bin/activate
|
||||
alembic upgrade head
|
||||
|
||||
# 查看迁移历史
|
||||
alembic history
|
||||
|
||||
# 数据库备份
|
||||
pg_dump -h 192.168.110.252 -p 15432 -U postgres hospital_performance > backup.sql
|
||||
|
||||
# 数据库恢复
|
||||
psql -h 192.168.110.252 -p 15432 -U postgres hospital_performance < backup.sql
|
||||
```
|
||||
|
||||
### 前端调试
|
||||
```bash
|
||||
# 检查 Node 版本
|
||||
node -v
|
||||
npm -v
|
||||
|
||||
# 清理重建
|
||||
cd /var/www/hospital-performance/frontend
|
||||
rm -rf node_modules dist
|
||||
npm install --production
|
||||
npm run build
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔧 故障排查流程图
|
||||
|
||||
```
|
||||
部署失败
|
||||
├─ 前置检查失败
|
||||
│ ├─ 缺少命令 → 安装 git/python/node/npm
|
||||
│ └─ 磁盘不足 → 清理空间或扩容
|
||||
│
|
||||
├─ 代码更新失败
|
||||
│ ├─ Git 连接失败 → 检查网络和凭证
|
||||
│ └─ 冲突 → 手动解决或重置
|
||||
│
|
||||
├─ 后端部署失败
|
||||
│ ├─ 虚拟环境 → 删除重建 venv
|
||||
│ ├─ 依赖安装 → 检查 requirements.txt
|
||||
│ ├─ 数据库迁移 → 手动执行 alembic
|
||||
│ └─ 服务启动 → 检查 systemd 配置
|
||||
│
|
||||
└─ 前端部署失败
|
||||
├─ npm install 失败 → 清理缓存 npm cache clean
|
||||
├─ 构建失败 → 检查 Node.js 版本
|
||||
└─ Nginx 加载 → systemctl reload nginx
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ 常见问题速查
|
||||
|
||||
### Q1: 权限错误 "Permission denied"
|
||||
```bash
|
||||
# 修复目录权限
|
||||
sudo chown -R www-data:www-data /var/www/hospital-performance
|
||||
sudo chmod -R 755 /var/www/hospital-performance
|
||||
```
|
||||
|
||||
### Q2: 端口被占用
|
||||
```bash
|
||||
# 查看端口占用
|
||||
sudo lsof -i :8000
|
||||
sudo netstat -tlnp | grep 8000
|
||||
|
||||
# 杀死进程
|
||||
sudo kill -9 <PID>
|
||||
```
|
||||
|
||||
### Q3: 数据库连接失败
|
||||
```bash
|
||||
# 测试连接
|
||||
psql -h 192.168.110.252 -p 15432 -U postgres -d hospital_performance
|
||||
|
||||
# 检查防火墙
|
||||
sudo ufw status
|
||||
sudo telnet 192.168.110.252 15432
|
||||
```
|
||||
|
||||
### Q4: Python 模块找不到
|
||||
```bash
|
||||
# 确认虚拟环境激活
|
||||
source /var/www/hospital-performance/venv/bin/activate
|
||||
|
||||
# 重新安装依赖
|
||||
pip install -r requirements.txt --force-reinstall
|
||||
```
|
||||
|
||||
### Q5: 前端页面空白
|
||||
```bash
|
||||
# 检查浏览器控制台错误
|
||||
F12 -> Console
|
||||
|
||||
# 检查 Nginx 配置
|
||||
sudo nginx -t
|
||||
sudo cat /etc/nginx/sites-available/default
|
||||
|
||||
# 检查文件权限
|
||||
ls -la /var/www/hospital-performance/frontend/dist/
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📊 监控指标
|
||||
|
||||
### 关键指标
|
||||
- **API 响应时间**: < 200ms
|
||||
- **页面加载时间**: < 3s
|
||||
- **服务可用性**: > 99.9%
|
||||
- **数据库连接数**: < 100
|
||||
|
||||
### 监控命令
|
||||
```bash
|
||||
# CPU 使用率
|
||||
top -bn1 | grep "Cpu(s)"
|
||||
|
||||
# 内存使用
|
||||
free -h
|
||||
|
||||
# 磁盘 IO
|
||||
iostat -x 1
|
||||
|
||||
# 网络流量
|
||||
iftop -P -n
|
||||
|
||||
# 进程监控
|
||||
ps aux | grep uvicorn
|
||||
ps aux | grep nginx
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🎯 发布清单
|
||||
|
||||
### 发布前检查
|
||||
- [ ] 代码已合并到 main 分支
|
||||
- [ ] 通过所有测试
|
||||
- [ ] 数据库迁移脚本就绪
|
||||
- [ ] 备份策略已配置
|
||||
- [ ] 回滚方案已准备
|
||||
|
||||
### 发布中检查
|
||||
- [ ] 代码更新成功
|
||||
- [ ] 依赖安装完成
|
||||
- [ ] 数据库迁移成功
|
||||
- [ ] 服务启动正常
|
||||
- [ ] 健康检查通过
|
||||
|
||||
### 发布后验证
|
||||
- [ ] 访问前端页面
|
||||
- [ ] 测试登录功能
|
||||
- [ ] 验证核心功能
|
||||
- [ ] 检查错误日志
|
||||
- [ ] 监控系统资源
|
||||
|
||||
---
|
||||
|
||||
## 📞 应急联系
|
||||
|
||||
### 升级流程
|
||||
1. **一级故障**（功能异常）→ 开发团队
|
||||
2. **二级故障**（性能下降）→ 运维团队 + 开发负责人
|
||||
3. **三级故障**（服务中断）→ 紧急响应小组
|
||||
|
||||
### 回滚命令
|
||||
```bash
|
||||
# 快速回滚到上一个版本
|
||||
cd /var/www/hospital-performance
|
||||
git reset --hard HEAD~1
|
||||
|
||||
# 重启服务
|
||||
systemctl restart hospital-backend
|
||||
systemctl restart nginx
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**提示**: 将此文件打印或保存为书签，便于快速查阅！
|
||||
Reference in New Issue
Block a user