370 lines
7.5 KiB
Markdown
370 lines
7.5 KiB
Markdown
# Spug 自动部署配置指南
|
||
|
||
## 🚀 快速开始（10 分钟完成）
|
||
|
||
### 步骤 1: 上传脚本到 Spug 服务器
|
||
|
||
```bash
|
||
# 从本地上传
|
||
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`）:
|
||
|
||
```bash
|
||
# 复制服务文件
|
||
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. 点击 **立即发布**
|
||
|
||
---
|
||
|
||
## 📋 验证部署
|
||
|
||
### 查看部署日志
|
||
|
||
在目标服务器上：
|
||
|
||
```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
|
||
|
||
# 前端 Nginx
|
||
systemctl status nginx
|
||
|
||
# 查看进程
|
||
ps aux | grep uvicorn
|
||
ps aux | grep nginx
|
||
```
|
||
|
||
### 测试 API
|
||
|
||
```bash
|
||
# 健康检查
|
||
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`
|
||
|
||
**解决：**
|
||
```bash
|
||
# 修复目录权限
|
||
sudo chown -R $USER:$USER /var/www/hospital-performance
|
||
sudo chmod -R 755 /var/www/hospital-performance
|
||
```
|
||
|
||
### 问题 4: 服务启动失败
|
||
|
||
**现象：** `systemctl restart hospital-backend` 失败
|
||
|
||
**排查：**
|
||
```bash
|
||
# 查看详细日志
|
||
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`
|
||
|
||
**解决：**
|
||
```bash
|
||
# 测试数据库连接
|
||
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. 清理临时文件
|
||
↓
|
||
部署成功！
|
||
```
|
||
|
||
### 回滚流程
|
||
|
||
如果部署失败，可以：
|
||
|
||
```bash
|
||
# 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%
|
||
|
||
### 监控命令
|
||
|
||
```bash
|
||
# 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;"
|
||
```
|
||
|
||
### 日志聚合
|
||
|
||
```bash
|
||
# 后端日志
|
||
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. 联系开发团队或查看项目文档
|
||
|
||
---
|
||
|
||
**提示**: 将此文档保存为书签，便于快速查阅！
|