---
name: webapp-remote-deploy
title: Web 应用完整部署工具包
description: 通过 SSH 将任意 Web 应用及全部辅助系统部署到远程目标系统 — 支持多种数据库、自动端口分配、Nginx/SSL、防火墙、Fail2ban、自动备份、健康守护、告警
tags: [deployment, webapp, ssh, remote, production, devops, monitoring, backup, security]
related_skills: [hermes-app-deploy, ssh-password-auth]
version: 2.0.0
---

# Web 应用完整部署工具包

## 概述

通用生产级 Web 应用部署工具包。支持任意 Web 框架（Python/Node/Java/Go 等），自动配置全套基础设施。

## 辅助系统清单

| 类别 | 系统 | 作用 | 生产必需 |
|------|------|------|----------|
| 数据层 | MariaDB/PostgreSQL/MySQL | 持久存储，调优 | ★★★★★ |
| 缓存层 | Redis | Session + 缓存 | ★★★★★ |
| 接入层 | Nginx | 反向代理 + SSL 终结 | ★★★★★ |
| 安全层 | SSL/Certbot | HTTPS 自动续期 | ★★★★★ |
| 安全层 | UFW 防火墙 | 端口白名单 | ★★★★☆ |
| 安全层 | Fail2ban | 暴力破解防护 | ★★★★☆ |
| 运维层 | 自动备份 | 数据库每日全量 | ★★★★★ |
| 运维层 | 日志轮转 | 应用日志切割 | ★★★★☆ |
| 运维层 | 健康守护 | 进程存活 + 自动重启 | ★★★★★ |
| 运维层 | 告警系统 | 磁盘/内存/CPU 阈值告警 | ★★★☆☆ |
| 基础层 | NTP 时间同步 | 日志/计费时间准确 | ★★★★★ |

## 工具包结构

```
webapp-remote-deploy/
├── SKILL.md              (本文档)
└── scripts/
    ├── deploy_all.sh     主入口：一键部署全部
    ├── 01-firewall.sh    UFW 防火墙配置
    ├── 02-database.sh    数据库安装 + 生产调优 (MariaDB/PostgreSQL/MySQL)
    ├── 03-redis.sh       Redis 安装 + 生产调优
    ├── 04-backup.sh      自动备份 + 保留策略
    ├── 05-logrotate.sh   日志轮转配置
    ├── 06-watchdog.sh    健康守护 + 自动重启
    ├── 07-fail2ban.sh    暴力破解防护
    ├── 08-alerts.sh      系统告警
    └── 09-nginx.sh       Nginx + SSL
```

## 部署顺序

```
Phase 0: 环境探测 + 系统依赖
Phase 1: 防火墙 (01-firewall.sh)        ← 最先，缩小攻击面
Phase 2: 数据库 (02-database.sh)        ← 按选择安装 MariaDB/PostgreSQL/MySQL
Phase 3: Redis (03-redis.sh)            ← 缓存层
Phase 4: 应用部署                       ← 核心应用 (用户提供部署脚本或手动)
Phase 5: 备份系统 (04-backup.sh)        ← 数据保护
Phase 6: 日志轮转 (05-logrotate.sh)     ← 日志管理
Phase 7: 健康守护 (06-watchdog.sh)      ← 进程保活 (systemd 自动启动)
Phase 8: Fail2ban (07-fail2ban.sh)      ← 入侵防护
Phase 9: 告警系统 (08-alerts.sh)        ← 异常告警
Phase 10: Nginx + SSL (09-nginx.sh)     ← 最后，确保应用已就绪
```

## Support Files

- `references/gpu-async-service-pattern.md` — ahserver + longtasks + Redis pattern for GPU inference services (8×4090 server deployment conventions, .dspy routes, config.json, Nginx routing)
- `references/pipeline-server.md` — Pipeline 服务器拓扑: 应用/pipeline@pipeline.opencomputing.cn, git/gateway, GPU服务器角色分工
- `scripts/01-firewall.sh` through `scripts/09-nginx.sh` — deployment phase scripts

## 关键特性

### 1. 数据库选择
支持三种主流数据库，自动调优：
- **MariaDB** (默认) — innodb_buffer_pool_size 自动设为内存 50-70%
- **PostgreSQL** — shared_buffers 自动设为内存 25%
- **MySQL** — 同 MariaDB 调优策略

### 2. 自动端口分配
自动检测目标机器未占用端口 (8000-9999 范围)，避免冲突。应用和 Nginx upstream 保持一致。

### 3. 系统重启自动启动
- 应用通过 systemd service 管理，`systemctl enable` 开机自启
- 健康守护 watchdog 也是 systemd timer，开机自启
- 所有辅助系统 (Redis/DB/Nginx/Fail2ban) 均 enable

### 4. 通用性
- 不绑定特定框架或语言
- 应用部署部分由用户提供脚本或手动操作
- 所有脚本通过环境变量参数化，高度可定制

## SSH 自动化 (Hermes Agent 执行)

```python
import paramiko

ssh = paramiko.SSHClient()
ssh.set_missing_host_key_policy(paramiko.AutoAddPolicy())
ssh.connect(HOST, port=22, username=USER, password=PASS)

def run(cmd, timeout=600):
    stdin, stdout, stderr = ssh.exec_command(cmd, timeout=timeout)
    out = stdout.read().decode()
    err = stderr.read().decode()
    code = stdout.channel.recv_exit_status()
    return {'output': out, 'error': err, 'code': code}

# 逐脚本上传并执行...
```

## 一键部署

```bash
bash deploy_all.sh
```

交互式输入：域名、数据库类型、密码、邮箱等。自动分配端口。

## 回滚方案

```bash
sudo systemctl stop <app>-watchdog
sudo systemctl stop <app>
# 数据库回滚
<db-client> -u <user> -p <db> < ~/backups/<db>_YYYYMMDD.sql.gz
# 代码回滚
cd ~/apps/<app> && git checkout <commit>
sudo systemctl start <app>
```

## SSH 限流 (MaxStartups/Fail2ban)

部分云服务器 SSH 配置了严格的连接限流（MaxStartups 或 Fail2ban），连续快速 SSH 调用会被 `kex_exchange_identification: Connection closed by remote host` 拒绝。

**症状**: 第一次 SSH 成功，后续连续调用在同一分钟内被拒绝。
**解决**: 每次 SSH 调用前 `sleep 12`（或更长）。在 Hermes agent 中用 `sleep N && ssh ...` 包裹命令。
**诊断**: `ssh -vvv host` 看是否在 kex 阶段被断连。

## 常见陷阱

1. **数据库默认参数太小** — 生产必须调优 (工具包自动处理)
2. **Redis 无 maxmemory** — OOM 时系统 kill 进程
3. **无防火墙** — 应用端口暴露公网
4. **无日志轮转** — 日志无限增长撑爆磁盘
5. **watchdog 重启风暴** — 必须设上限
6. **Fail2ban 误封自己** — 必须配白名单
7. **端口冲突** — 工具包自动检测未用端口
8. **忘记 enable service** — 重启后应用不启动