Nexus/docs/design/specs/2026-05-17-server-add-optimize-design.md

servers.php 添加服务器优化 — 设计规格

⚠️ 已归档 — 2026-05-22 本文档引用的文件结构已过时：web/servers.php 已迁移到 web/app/servers.html (Tailwind CSS v4 + Alpine.js)；server/services/agent_installer.py 未独立创建，安装逻辑集成在 server_service.py 中。功能已实现，保留本文档供历史参考。

日期: 2026-05-17 状态: 已确认

一、需求

1. Agent API 密钥自动生成，不显示在表单
2. 密码预设下拉联动修复
3. 添加服务器后自动 SSH 安装 Agent，实时回传日志
4. 表单新增目标路径字段（必填）
5. 目标路径在列表可快速编辑

二、表单改造

字段变更

字段	变更
名称	保持
域名/IP	保持，必填
SSH端口	保持，默认22
SSH用户名	保持，默认root
认证方式	保持（密码/密钥）
密码预设	保持，修复 datalist 联动
SSH密码	必填（需要 SSH 安装 Agent）
SSH密钥路径	保持（认证方式=密钥时显示）
目标路径	新增，必填，target_path
Agent端口	隐藏，默认8601
Agent密钥	隐藏，后端自动生成 bin2hex(random_bytes(16))

移除字段

• agent_api_key 输入框 — 从表单移除

三、提交流程

3.1 后端 — POST /api/servers/

def create_server(server_data):
    # 1. 自动生成 agent_api_key
    server_data.agent_api_key = secrets.token_hex(16)  # 32 位 hex
    
    # 2. 创建 server 记录
    server = Server(**server_data.model_dump())
    db.add(server); db.commit()
    
    # 3. 后台异步安装 Agent
    asyncio.create_task(install_agent_async(server.id))
    
    return server

3.2 异步安装 — install_agent_async()

1. 从 DB 读取 server 信息（IP/端口/用户名/密码/目标路径）
2. SSH 连接子服务器
3. 执行命令（通过 Redis pub/sub 逐行回传）：
   curl -fsSL https://${NEXUS_DOMAIN}/agent/install.sh | bash -s -- \
     --url http://${NEXUS_DOMAIN}:8600 \
     --key <agent_api_key> \
     --dirs <target_path>
4. 安装完成 → 更新 server.is_online 状态
5. Redis PUBLISH install:{server_id}:done {"ok": true}

3.3 进度传输

SSH exec_command(install_cmd)
  → stdout.readline() 逐行
  → Redis PUBLISH install:{id}:log {percent: N, line: "..."}
  → WebSocket → 前端渲染

Redis key 设计：

• install:{server_id}:log — pub/sub 频道，逐行日志
• install:{server_id}:state — JSON {percent, status: "running|done|failed", error}

四、前端 — 服务器列表

4.1 安装进度显示

◐ web-02  [安装中 ████████░░ 80%]
          ↑ 点击弹出日志对话框

• is_online == false && install_state == "running" → 显示进度条
• 点击进度/状态 → install_dialog 弹出，显示实时日志
• 安装完成 → is_online = true，进度条消失，显示绿点
• WebSocket 监听 install:{id}:log，无需轮询

4.2 日志对话框

┌─ 安装日志: web-02 ──────────────────┐
│ [1/5] 安装依赖... ✓                  │
│ [2/5] 创建目录... ✓                  │
│ [3/5] 下载 Agent... ✓               │
│ [4/5] 配置 systemd... ✓             │
│ [5/5] 启动 Agent... ✓               │
│ ✅ 安装完成！                        │
│                          [关闭]      │
└──────────────────────────────────────┘

4.3 目标路径快速编辑

每行 target_path 旁 ✏️ 按钮：

点击 ✏️ → target_path 变为 input → 回车 → PUT /api/servers/{id} {target_path: "新路径"}

五、涉及文件

文件	变更
web/servers.php	表单字段调整 + 安装进度 + 快捷编辑
server/api/servers.py	create_server 自动生成密钥 + 异步安装入口
server/services/agent_installer.py	新建 — SSH 安装 Agent + Redis 进度推送
server/main.py	WebSocket 转发 install:{id}:log → 前端

六、错误处理

场景	处理
SSH 连接失败	install_state = "failed", 显示红色错误，可手动重试
安装超时(120s)	超时自动标记失败
密钥冲突	重新生成，重试一次
WebSocket 断开	重连后从 Redis 读取当前状态恢复

七、安装进度状态机

pending → running → done
                  → failed → （手动重试）→ pending