# 简化推送模型 — 设计规格

> ⚠️ **已归档** — 2026-05-22
> 本文档引用的文件结构已过时：`server/database.py` 已拆分为 `server/domain/models/`；`server/api/tasks.py` 已删除；PHP 前端 (`servers.php`/`tasks.php`) 已迁移到 Tailwind CSS v4 + Alpine.js。功能已实现，保留本文档供历史参考。

## 背景

当前 SyncTask 模型为"一个任务=一个源→一个服务器→一个目标"，支持 push/pull/bidirectional + 触发文件 + cron 定时 + 差异对比。实际需求只需要：**主服务器单向推送到多台子服务器，直接覆盖（rsync 不含 --delete）**。

## 核心变更

### 数据模型

**Server 表新增字段：**

```python
target_path = Column(String(500), nullable=True, comment="推送目标路径")
category    = Column(String(100), nullable=True, comment="服务器分类")
```

**删除 SyncTask 表及其所有关联。**

**SyncLog 保留并调整：**

```python
# 移除 task_id，改为直接记录推送信息
source_path      = Column(String(500), nullable=False, comment="源目录")
target_path      = Column(String(500), nullable=False, comment="目标目录")
server_id        = Column(Integer, ForeignKey("servers.id"), nullable=False)
status           = Column(String(20))   # pending/running/success/failed
files_total      = Column(Integer)
files_transferred = Column(Integer)
bytes_transferred = Column(Integer)
duration_seconds  = Column(Integer)
error_message    = Column(Text)
started_at       = Column(DateTime)
finished_at      = Column(DateTime)
```

### 操作模型

```
主服务器 源目录 /www/wwwroot/my-project
   │
   ├─ rsync → 子服务器 A  /var/www/siteA   (分类: Web服务器)
   ├─ rsync → 子服务器 B  /var/www/siteB   (分类: Web服务器)
   └─ rsync → 子服务器 C  /opt/api         (分类: API服务器)
```

### API 端点

**新增：**

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/api/servers/push` | 批量推送。Body: `{source_path, server_ids: [1,2,3]}` |

**删除：**

| 路径 | 说明 |
|------|------|
| `/api/tasks/*` | 全部删除 |
| `/api/agent/trigger` | 删除触发通知 |

**保留并调整：**

| 路径 | 调整 |
|------|------|
| `/api/servers/{id}` | ServerUpdate 加 target_path, category |
| `/api/logs` | 改为按 server_id 筛选 |

### 前端页面

**servers.php — 服务器管理页增强：**

- 列表显示：名称、域名、分类、目标路径、状态、操作
- 编辑表单：加分类下拉 + 目标路径输入框
- 新增「推送」按钮：弹出推送对话框

**推送对话框（新组件）：**

```
┌──────────────────────────────────────────────┐
│ 推送文件                                      │
│                                              │
│ 源目录: [/www/wwwroot/my-project     ] [📁]  │
│                                              │
│ ☑ 全选 (共 5 台)                              │
│                                              │
│ ▸ Web服务器 (3 台)     [全选此分类]            │
│   ☑ 服务器-A → /var/www/siteA                │
│   ☑ 服务器-B → /var/www/siteB                │
│   ☐ 服务器-C → /var/www/siteC                │
│                                              │
│ ▸ API服务器 (2 台)     [全选此分类]            │
│   ☑ 服务器-D → /opt/api/instance1             │
│   ☑ 服务器-E → /opt/api/instance2             │
│                                              │
│                    [取消]  [推送到 4 台服务器]   │
└──────────────────────────────────────────────┘
```

**tasks.php → 改名 push.php 或合并进 servers.php：**

- 原 tasks.php 改为「推送管理」页
- 显示推送历史（SyncLog 列表）
- 保留手动推送入口

### rsync 参数

```
rsync -avz --stats --progress
  -a  归档模式（保留权限/时间/符号链接）
  -v  详细输出
  -z  压缩传输
  --stats  统计信息
  --progress  进度显示
  不加 --delete（源删了目标保留）
```

### 删除的代码

| 文件 | 删除内容 |
|------|---------|
| `server/database.py` | SyncTask 模型 |
| `server/api/tasks.py` | 整个文件 |
| `server/api/agent.py` | `/trigger` 端点 |
| `server/services/sync_engine.py` | compute_diff、direction 逻辑、cron 逻辑 |
| `server/services/ssh_direct.py` | trigger_poll_loop、触发文件轮询相关 |
| `server/services/trigger_poller.py` | 整个文件（agent 模式触发文件轮询） |
| `web/tasks.php` | 改为推送历史页 |
| `web/api_client.php` | 删 task 相关方法 |
| `web/api_proxy.php` | 删 task 相关 action |

### 保留的代码

| 文件 | 保留原因 |
|------|---------|
| `server/api/agent.py` heartbeat | Agent 心跳仍需要 |
| `server/services/health_checker.py` | 健康检测保留 |
| `server/services/ssh_direct.py` health_check | 健康检测保留 |
| `database.py` Server/SyncLog/Admin/LoginAttempt | 核心模型 |
| 所有 Web 页面（除 tasks.php 改造） | 登录/仪表盘/服务器/设置等 |

### 文件统计预估

```
修改: ~18 个文件
删除: ~3 个文件
新增代码: ~350 行
删除代码: ~650 行
净减少: ~300 行
```

### 脚本与配置文件更新

| 文件 | 改动 |
|------|------|
| `.env.example` | 删 `SYNC_INTERVAL_SECONDS`、`TRIGGER_FILENAME`；保留 `HEALTH_CHECK_INTERVAL`、`HEALTH_CHECK_TIMEOUT` |
| `install.sh` | 删 sync_tasks/cron 相关注释和参数；删 `--db-path` 参数；保留 `--mode` |
| `deploy/install_central.sh` | 删 trigger/sync 相关 echo 提示 |
| `deploy/install_agent.sh` | 删 `trigger_file` 配置项 |
| `deploy/supervisor.ini` | 无需改（不涉及 tasks） |
| `deploy/nexus.service` | 无需改 |
| `deploy/nginx_webui.conf` | 无需改 |
| `deploy/firewall.sh` | 无需改 |
| `agent/install.sh` | 删 `NEXUS_TRIGGER_FILE` 环境变量 |
| `agent/agent.sh` | 删 `notify_central` 触发通知函数；保留 heartbeat |
| `agent/config.example.yaml` | 删 `trigger_file` 字段 |
| `web/agent/install.sh` | 同 agent/install.sh |
| `web/agent/agent.sh` | 同 agent/agent.sh |
| `web/deploy.php` | 删 `.sync-trigger` 示例命令 |
| `web/api_client.php` | 删 `getTasks/createTask/updateTask/deleteTask/triggerSync/getTaskDiff` 方法；新增 `pushServers` 方法 |
| `web/api_proxy.php` | 删 task 相关 case；`browse` 等文件管理 action 保留 |
| `web/index.php` | 仪表盘删"活跃同步任务"卡片，改为"推送服务器"统计 |
| `web/logs.php` | 删 task 筛选，保留 server/status 筛选 |
| `docs/python-backend-install.md` | 删 sync_tasks/trigger_file/cron 相关章节 |
| `README.md` | 更新系统架构图/特性列表 |
| `宝塔部署指南.md` | 更新使用说明 |
| `docs/CHANGELOG.md` | 追加本次迭代记录 |

## 规格自检

- [x] 无占位符/TODO
- [x] 数据模型与 API 一致（Server.target_path ↔ push 端点）
- [x] 范围聚焦：仅涉及推送模型简化
- [x] 无模糊需求：rsync 参数明确，UI 布局明确
- [x] 删除项已明确列出
