Nexus/docs/design/specs/2026-05-16-simplified-push-design.md

简化推送模型 — 设计规格

⚠️ 已归档 — 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 表新增字段：

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

删除 SyncTask 表及其所有关联。

SyncLog 保留并调整：

# 移除 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	追加本次迭代记录

规格自检

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