docs: Nexus 6.0 功能说明书 HTML + roadmap stale fix

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-05-23 16:55:24 +08:00
parent 6c5e6a2daa
commit 5a42345bc0
1 changed files with 566 additions and 0 deletions
@@ -0,0 +1,566 @@
+<!DOCTYPE html>
+<html lang="zh-CN">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width,initial-scale=1.0">
+<title>Nexus 6.0 — 功能说明书</title>
+<style>
+*{box-sizing:border-box;margin:0;padding:0}
+body{font-family:-apple-system,BlinkMacSystemFont,'Segoe UI',sans-serif;background:#0f172a;color:#e2e8f0;line-height:1.6}
+a{color:#60a5fa;text-decoration:none}
+a:hover{text-decoration:underline}
+
+/* Layout */
+.wrap{max-width:960px;margin:0 auto;padding:32px 24px 80px}
+
+/* Header */
+.hero{text-align:center;padding:48px 0 40px;border-bottom:1px solid #1e293b;margin-bottom:40px}
+.hero h1{font-size:2.2rem;font-weight:700;color:#f8fafc;letter-spacing:-0.02em}
+.hero .sub{font-size:1rem;color:#64748b;margin-top:8px}
+.badge{display:inline-block;margin:4px;padding:3px 10px;border-radius:999px;font-size:0.72rem;font-weight:600}
+.badge-blue{background:#1e3a5f;color:#60a5fa;border:1px solid #2563eb55}
+.badge-green{background:#14371f;color:#4ade80;border:1px solid #16a34a55}
+.badge-amber{background:#3d2a00;color:#fbbf24;border:1px solid #d9770655}
+.badge-red{background:#3b1212;color:#f87171;border:1px solid #dc262655}
+
+/* TOC */
+.toc{background:#1e293b;border:1px solid #334155;border-radius:12px;padding:20px 24px;margin-bottom:36px}
+.toc h2{font-size:0.85rem;font-weight:700;color:#94a3b8;text-transform:uppercase;letter-spacing:.08em;margin-bottom:12px}
+.toc ol{padding-left:18px;column-count:2;column-gap:24px}
+.toc li{margin:5px 0;font-size:0.88rem}
+
+/* Section */
+.section{margin-bottom:48px}
+.section-title{font-size:1.4rem;font-weight:700;color:#f1f5f9;padding-bottom:10px;border-bottom:2px solid #334155;margin-bottom:24px;display:flex;align-items:center;gap:10px}
+.section-title .icon{font-size:1.2rem}
+
+/* Card */
+.card{background:#1e293b;border:1px solid #334155;border-radius:12px;padding:24px;margin-bottom:16px}
+.card-title{font-size:1.05rem;font-weight:600;color:#f1f5f9;margin-bottom:6px;display:flex;align-items:center;gap-8px:gap:8px}
+.card-title .num{display:inline-flex;align-items:center;justify-content:center;width:22px;height:22px;border-radius:50%;background:#334155;font-size:0.7rem;font-weight:700;color:#94a3b8;margin-right:8px;shrink:0}
+.card-desc{color:#94a3b8;font-size:0.88rem;margin-bottom:14px}
+
+/* Info rows */
+.info-grid{display:grid;grid-template-columns:1fr;gap:10px}
+.info-block{border-radius:8px;padding:12px 14px}
+.info-block.usage{background:#0f2d1f;border:1px solid #166534}
+.info-block.warn{background:#2a1a00;border:1px solid #92400e}
+.info-block.note{background:#1a1f2e;border:1px solid #4338ca}
+.info-title{font-size:0.72rem;font-weight:700;text-transform:uppercase;letter-spacing:.08em;margin-bottom:6px}
+.info-title.u{color:#4ade80}
+.info-title.w{color:#fbbf24}
+.info-title.n{color:#818cf8}
+.info-block ul{padding-left:16px;font-size:0.86rem;color:#cbd5e1}
+.info-block li{margin:4px 0}
+.info-block p{font-size:0.86rem;color:#cbd5e1}
+
+/* Sub table */
+.feat-table{width:100%;border-collapse:collapse;font-size:0.86rem;margin-top:10px}
+.feat-table th{text-align:left;color:#64748b;font-weight:600;font-size:0.75rem;text-transform:uppercase;padding:6px 10px;border-bottom:1px solid #334155}
+.feat-table td{padding:7px 10px;border-bottom:1px solid #1e293b;color:#cbd5e1;vertical-align:top}
+.feat-table tr:last-child td{border-bottom:none}
+
+/* Footer */
+footer{text-align:center;color:#334155;font-size:0.8rem;margin-top:60px;padding-top:24px;border-top:1px solid #1e293b}
+code{background:#334155;color:#7dd3fc;padding:2px 6px;border-radius:4px;font-size:0.83em;font-family:monospace}
+</style>
+</head>
+<body>
+<div class="wrap">
+
+<!-- HERO -->
+<div class="hero">
+  <h1>⚡ Nexus 6.0</h1>
+  <p class="sub">服务器运维管理平台 — 功能说明书 · 2026-05-23</p>
+  <div style="margin-top:14px">
+    <span class="badge badge-blue">FastAPI</span>
+    <span class="badge badge-blue">SQLAlchemy 2.0</span>
+    <span class="badge badge-blue">Redis 7</span>
+    <span class="badge badge-blue">asyncssh</span>
+    <span class="badge badge-blue">Tailwind v4</span>
+    <span class="badge badge-green">2000+ 服务器</span>
+    <span class="badge badge-green">JWT + TOTP</span>
+  </div>
+</div>
+
+<!-- TOC -->
+<div class="toc">
+  <h2>目录</h2>
+  <ol>
+    <li><a href="#auth">认证与访问控制</a></li>
+    <li><a href="#dashboard">仪表盘与实时告警</a></li>
+    <li><a href="#servers">服务器管理</a></li>
+    <li><a href="#webssh">Web SSH 终端</a></li>
+    <li><a href="#push">批量文件推送</a></li>
+    <li><a href="#scripts">脚本批量执行</a></li>
+    <li><a href="#files">远程文件管理</a></li>
+    <li><a href="#schedules">定时调度</a></li>
+    <li><a href="#credentials">凭据管理</a></li>
+    <li><a href="#settings">系统设置</a></li>
+    <li><a href="#audit">审计日志</a></li>
+    <li><a href="#install">安装向导</a></li>
+    <li><a href="#guardian">3 层守护机制</a></li>
+    <li><a href="#agent">子机 Agent</a></li>
+    <li><a href="#notimpl">未实现 / 已否决</a></li>
+  </ol>
+</div>
+
+<!-- 1. AUTH -->
+<div class="section" id="auth">
+  <div class="section-title"><span class="icon">🔒</span> 1. 认证与访问控制</div>
+
+  <div class="card">
+    <div class="card-title"><span class="num">1</span> JWT 登录 + 自动刷新</div>
+    <p class="card-desc">管理员通过用户名+密码登录，获取 Access Token（30 分钟）和 Refresh Token（7 天）。前端到期前 2 分钟自动换新 Token，无感续期。</p>
+    <div class="info-grid">
+      <div class="info-block usage"><div class="info-title u">使用说明</div><ul>
+        <li>访问 <code>/app/login.html</code>，输入管理员账号密码</li>
+        <li>Token 存于 <code>localStorage</code>，关闭浏览器后 7 天内免登录</li>
+        <li>8 小时无操作自动退出</li>
+      </ul></div>
+      <div class="info-block warn"><div class="info-title w">缺点 / 注意</div><ul>
+        <li>JWT 存于 localStorage，XSS 漏洞可能导致 Token 泄露（已做 CSP 缓解）</li>
+        <li>无 RBAC：只有一个管理员角色，鉴权即信任</li>
+        <li>不支持多管理员角色区分</li>
+      </ul></div>
+    </div>
+  </div>
+
+  <div class="card">
+    <div class="card-title"><span class="num">2</span> TOTP 双因素认证</div>
+    <p class="card-desc">可选启用 Google Authenticator 兼容的 TOTP。登录时先验密码，再验 6 位动态码（30 秒窗口）。</p>
+    <div class="info-grid">
+      <div class="info-block usage"><div class="info-title u">使用说明</div><ul>
+        <li>进入「设置」→「安全设置」→「启用 TOTP」，扫描二维码绑定 App</li>
+        <li>禁用 TOTP 需同时提供当前密码 + TOTP 码</li>
+      </ul></div>
+      <div class="info-block warn"><div class="info-title w">缺点 / 注意</div><ul>
+        <li>TOTP 秘钥丢失无法恢复，需提前备份</li>
+        <li>系统时间偏差 &gt;30s 会导致验证失败（接受 ±1 窗口共 90s）</li>
+      </ul></div>
+    </div>
+  </div>
+
+  <div class="card">
+    <div class="card-title"><span class="num">3</span> 登录防暴破</div>
+    <p class="card-desc">同一 IP + 用户名 15 分钟内失败 5 次，账号自动锁定并返回 HTTP 429。</p>
+    <div class="info-block note"><div class="info-title n">注意</div><p>锁定基于 IP + 用户名组合，更换 IP 可绕过。适合防自动化爆破，不防分布式攻击。</p></div>
+  </div>
+</div>
+
+<!-- 2. DASHBOARD -->
+<div class="section" id="dashboard">
+  <div class="section-title"><span class="icon">📊</span> 2. 仪表盘与实时告警</div>
+
+  <div class="card">
+    <div class="card-title"><span class="num">1</span> 实时统计面板</div>
+    <p class="card-desc">首页展示服务器总数、在线数、离线数、告警中台数、最近推送记录。数据来源 Redis（实时）+ MySQL（历史），通过 WebSocket 触发刷新。</p>
+    <div class="info-grid">
+      <div class="info-block usage"><div class="info-title u">使用说明</div><ul>
+        <li>在线状态取自 Redis <code>heartbeat:{id}</code>，子机 60s 上报一次</li>
+        <li>告警计数 = Redis <code>alerts:*</code> key 数量</li>
+        <li>WS 断线会自动重连（3 次指数退避）</li>
+      </ul></div>
+      <div class="info-block warn"><div class="info-title w">缺点 / 注意</div><ul>
+        <li>在线状态最多滞后 60s（子机心跳间隔）</li>
+        <li>Redis 不可用时统计退化为 MySQL 数据，可能不准</li>
+      </ul></div>
+    </div>
+  </div>
+
+  <div class="card">
+    <div class="card-title"><span class="num">2</span> 告警通知（Telegram）</div>
+    <p class="card-desc">CPU / 内存 / 磁盘超过阈值（默认 80%）时，通过 Telegram Bot 推送告警；恢复后发送恢复通知。同服务器同指标 5 分钟内不重复推送。</p>
+    <div class="info-grid">
+      <div class="info-block usage"><div class="info-title u">使用说明</div><ul>
+        <li>「设置」配置 <code>TELEGRAM_BOT_TOKEN</code> + <code>TELEGRAM_CHAT_ID</code></li>
+        <li>阈值可在设置页调整（CPU/内存/磁盘各独立）</li>
+        <li>浏览器仪表盘<strong>只显示计数，不弹窗、不响铃</strong>（设计决策）</li>
+      </ul></div>
+      <div class="info-block warn"><div class="info-title w">缺点 / 注意</div><ul>
+        <li>告警仅 Telegram，浏览器无实时告警列表</li>
+        <li>Telegram Bot 被封或网络不通时告警静默失败（有日志）</li>
+        <li>告警防抖 key 存于进程内存，重启后防抖状态重置</li>
+      </ul></div>
+    </div>
+  </div>
+</div>
+
+<!-- 3. SERVERS -->
+<div class="section" id="servers">
+  <div class="section-title"><span class="icon">🖥</span> 3. 服务器管理</div>
+
+  <div class="card">
+    <div class="card-title"><span class="num">1</span> 服务器 CRUD</div>
+    <p class="card-desc">增删改查服务器配置，支持 SSH 密钥 / 密码双认证，可按平台类型（Platform）和节点（Node 树）分组。</p>
+    <div class="info-grid">
+      <div class="info-block usage"><div class="info-title u">使用说明</div><ul>
+        <li>新增服务器：填写名称、域名/IP、SSH 端口、认证方式</li>
+        <li>认证方式选「密钥」时粘贴私钥内容，自动 Fernet 加密存储</li>
+        <li>支持 <code>platform_id</code> / <code>node_id</code> 分组归类</li>
+        <li>服务器列表分页显示（默认 50 条/页）</li>
+      </ul></div>
+      <div class="info-block warn"><div class="info-title w">缺点 / 注意</div><ul>
+        <li>批量导入（CSV）未实现，2000 台需逐一或通过 API 批量添加</li>
+        <li>删除服务器同时删除关联推送日志（CASCADE）</li>
+      </ul></div>
+    </div>
+  </div>
+
+  <div class="card">
+    <div class="card-title"><span class="num">2</span> 健康检查</div>
+    <p class="card-desc">手动触发对指定服务器列表的连通性测试（通过 Agent HTTP /health 端点），快速判断哪些服务器离线。</p>
+    <div class="info-block warn"><div class="info-title w">注意</div><p>健康检查依赖子机 Agent 运行；Agent 未启动的服务器显示离线（与 SSH 连通无关）。</p></div>
+  </div>
+
+  <div class="card">
+    <div class="card-title"><span class="num">3</span> 每服务器 API Key</div>
+    <p class="card-desc">为每台服务器单独生成 Agent API Key（格式 <code>nxs-xxx</code>），用于该服务器子机与中心通信的专属认证。</p>
+    <div class="info-grid">
+      <div class="info-block usage"><div class="info-title u">使用说明</div><ul>
+        <li>服务器详情 → 「生成 Agent Key」，完整 Key 仅本次显示，立即复制到子机 <code>config.json</code></li>
+        <li>列表页只显示前 8 位用于识别</li>
+      </ul></div>
+      <div class="info-block warn"><div class="info-title w">注意</div><ul>
+        <li>Key 生成后无法再次查看（一次性展示设计）</li>
+        <li>丢失需重新生成并更新子机配置</li>
+      </ul></div>
+    </div>
+  </div>
+</div>
+
+<!-- 4. WEB SSH -->
+<div class="section" id="webssh">
+  <div class="section-title"><span class="icon">💻</span> 4. Web SSH 终端</div>
+
+  <div class="card">
+    <div class="card-title"><span class="num">1</span> 浏览器终端</div>
+    <p class="card-desc">基于 xterm.js + asyncssh，在浏览器内打开远程服务器 SSH 会话，支持全屏、自动 resize、彩色输出。</p>
+    <div class="info-grid">
+      <div class="info-block usage"><div class="info-title u">使用说明</div><ul>
+        <li>服务器列表点击「终端」→ 弹出 <code>/app/terminal.html?server_id=X</code></li>
+        <li>认证：先获取短效 webssh-token（15 分钟），绑定到该服务器，再建 WebSocket</li>
+        <li>支持窗口 resize 自动通知远程 shell</li>
+      </ul></div>
+      <div class="info-block warn"><div class="info-title w">缺点 / 注意</div><ul>
+        <li>Token 通过 URL 参数传递（?token=...），HTTPS 下安全；HTTP 下有风险</li>
+        <li>不支持文件上传 / 拖拽（需用文件管理页）</li>
+        <li>会话不录像（已明确否决）</li>
+        <li>网络中断 WebSocket 不会自动重连，需刷新页面</li>
+      </ul></div>
+    </div>
+  </div>
+
+  <div class="card">
+    <div class="card-title"><span class="num">2</span> 会话追踪 + 命令日志</div>
+    <p class="card-desc">所有 Web SSH 会话记录到 <code>ssh_sessions</code>，每条命令记录到 <code>command_logs</code>，可在「资产」→「命令日志」查询。</p>
+    <div class="info-block note"><div class="info-title n">注意</div><p>命令日志基于 Enter 键分割，多行命令可能分多条记录。仅记录通过 Nexus WebSSH 的命令，直接 SSH 不记录。</p></div>
+  </div>
+</div>
+
+<!-- 5. PUSH -->
+<div class="section" id="push">
+  <div class="section-title"><span class="icon">📤</span> 5. 批量文件推送</div>
+
+  <div class="card">
+    <div class="card-title"><span class="num">1</span> rsync 批量推送</div>
+    <p class="card-desc">将源目录通过 rsync-over-SSH 推送到选定的服务器列表，支持 4 种同步模式，内置分批（50 台/批）并发（10 路）控制。</p>
+    <table class="feat-table">
+      <tr><th>同步模式</th><th>rsync 参数</th><th>适用场景</th></tr>
+      <tr><td>增量同步</td><td><code>-az</code></td><td>日常更新，只同步有变动的文件</td></tr>
+      <tr><td>全量同步</td><td><code>-az --delete</code></td><td>强制目标与源完全一致，会删除目标多余文件</td></tr>
+      <tr><td>校验和</td><td><code>-az --checksum</code></td><td>按文件内容而非时间戳判断差异</td></tr>
+      <tr><td>直接覆盖</td><td><code>-az --inplace</code></td><td>不用临时文件，直接覆盖（大文件节省空间）</td></tr>
+    </table>
+    <div class="info-grid" style="margin-top:12px">
+      <div class="info-block warn"><div class="info-title w">缺点 / 注意</div><ul>
+        <li><strong>全量同步（--delete）会不可逆删除</strong>目标目录多余文件，务必先「预览」</li>
+        <li>rsync 在中心机运行，中心机需能 SSH 到所有子机</li>
+        <li>失败的服务器自动加入重试队列（指数退避，最多 100 次）</li>
+      </ul></div>
+    </div>
+  </div>
+
+  <div class="card">
+    <div class="card-title"><span class="num">2</span> 推送前预览（dry-run）</div>
+    <p class="card-desc">选中全量/覆盖模式时，页面显示橙色警告，引导先对首台服务器运行 <code>rsync --dry-run --stats</code>，查看待传输/删除文件数量后再决定是否推送。</p>
+    <div class="info-grid">
+      <div class="info-block usage"><div class="info-title u">使用说明</div><ul>
+        <li>选择「全量同步」→ 出现橙色预览按钮 → 点击 → 展示首台服务器变动摘要</li>
+        <li>可展开「详细文件列表」（最多 200 行）</li>
+        <li>预览不阻塞推送，看完数据自行决定是否点「开始推送」</li>
+      </ul></div>
+      <div class="info-block warn"><div class="info-title w">注意</div><ul>
+        <li>仅预览第一台选中的服务器，其余服务器可能略有差异</li>
+        <li>预览需 SSH 连通，与真实推送消耗相同时间（通常 &lt;5s）</li>
+      </ul></div>
+    </div>
+  </div>
+
+  <div class="card">
+    <div class="card-title"><span class="num">3</span> 失败自动重试队列</div>
+    <p class="card-desc">推送失败的服务器自动进入 <code>push_retry_jobs</code> 队列，后台每 5 分钟按指数退避重试（60s → 120s → 240s...，最大 64 分钟）。</p>
+    <div class="info-block note"><div class="info-title n">注意</div><p>最多重试 100 次。可在「重试」页手动强制立即重试或删除任务。</p></div>
+  </div>
+</div>
+
+<!-- 6. SCRIPTS -->
+<div class="section" id="scripts">
+  <div class="section-title"><span class="icon">📜</span> 6. 脚本批量执行</div>
+
+  <div class="card">
+    <div class="card-title"><span class="num">1</span> 脚本库管理</div>
+    <p class="card-desc">维护可复用 Shell 脚本库（按 ops/deploy/check/cleanup 分类），一键下发到选定的服务器。</p>
+    <div class="info-block usage"><div class="info-title u">使用说明</div><ul>
+      <li>「脚本」页 → 新建脚本 → 填写名称/类别/内容</li>
+      <li>点击脚本名 → 编辑；点击「执行」→ 选择服务器 → 运行</li>
+      <li>支持直接输入临时命令（无需保存到库）</li>
+    </ul></div>
+  </div>
+
+  <div class="card">
+    <div class="card-title"><span class="num">2</span> 批量执行（短任务 / 长任务）</div>
+    <p class="card-desc">短任务：同步等待结果（默认 30s 超时）。长任务：nohup 后台运行，完成后 curl 回调中心记录结果。</p>
+    <div class="info-grid">
+      <div class="info-block usage"><div class="info-title u">使用说明</div><ul>
+        <li>选择服务器 → 填写命令 → 「执行」</li>
+        <li>长任务选择「后台运行」（nohup 模式），不阻塞 HTTP 请求</li>
+        <li>进度条实时更新（HTTP 轮询，非 WebSocket）</li>
+        <li>「执行历史」页查看所有历史执行结果</li>
+      </ul></div>
+      <div class="info-block warn"><div class="info-title w">缺点 / 注意</div><ul>
+        <li><code>rm -rf /</code> 等危险命令被中心<strong>拦截（400）</strong>，但仅匹配预设规则</li>
+        <li>长任务依赖子机能访问中心 <code>NEXUS_API_BASE_URL</code>（必须配置且使用 HTTPS）</li>
+        <li>执行历史默认保留 2 小时 Redis 热数据，60s 刷入 MySQL</li>
+        <li>执行命令时密码等敏感 $DB_* 变量存储时已脱敏（替换为 ***）</li>
+      </ul></div>
+    </div>
+  </div>
+
+  <div class="card">
+    <div class="card-title"><span class="num">3</span> $DB_* 数据库凭据替换</div>
+    <p class="card-desc">脚本中使用 <code>$DB_USER</code> / <code>$DB_PASS</code> / <code>$DB_HOST</code> / <code>$DB_PORT</code> / <code>$DB_NAME</code> 占位符，执行时自动替换为选定的数据库凭据，密码不出现在脚本文本或日志中。</p>
+    <div class="info-block note"><div class="info-title n">注意</div><p>替换在中心机完成后发往子机，子机接收到的已是明文命令；传输通过 HTTPS，子机侧无加密保护。</p></div>
+  </div>
+</div>
+
+<!-- 7. FILES -->
+<div class="section" id="files">
+  <div class="section-title"><span class="icon">📁</span> 7. 远程文件管理</div>
+
+  <div class="card">
+    <div class="card-title"><span class="num">1</span> 目录浏览</div>
+    <p class="card-desc">通过 SSH exec（<code>ls -la</code>）浏览指定服务器的远程目录，支持面包屑导航和目录点击进入。</p>
+    <div class="info-grid">
+      <div class="info-block usage"><div class="info-title u">使用说明</div><ul>
+        <li>「文件管理」→ 选服务器 → 输入路径 → 「浏览」（或按 Enter）</li>
+        <li>点击目录名进入子目录，点击「..」返回上级</li>
+        <li>文件按 目录优先 / 字母顺序 排列</li>
+      </ul></div>
+      <div class="info-block warn"><div class="info-title w">缺点 / 注意</div><ul>
+        <li>无左侧树状面板（每次需手动导航）</li>
+        <li>显示的文件大小为 <code>ls</code> 输出的字节数，大文件不友好</li>
+      </ul></div>
+    </div>
+  </div>
+
+  <div class="card">
+    <div class="card-title"><span class="num">2</span> 文件操作（删除/重命名/新建目录）</div>
+    <p class="card-desc">鼠标悬停文件/目录行显示操作按钮，通过 SSH exec 在远程执行操作。</p>
+    <table class="feat-table">
+      <tr><th>操作</th><th>命令</th><th>触发方式</th></tr>
+      <tr><td>删除文件</td><td><code>rm -f path</code></td><td>悬停 → 🗑 → confirm 弹窗</td></tr>
+      <tr><td>删除目录</td><td><code>rm -rf path</code></td><td>悬停 → 🗑 → 额外警告弹窗</td></tr>
+      <tr><td>重命名</td><td><code>mv src dst</code></td><td>悬停 → ✏ → prompt 输入新名</td></tr>
+      <tr><td>新建目录</td><td><code>mkdir -p path</code></td><td>右上角 📁+ → prompt 输入名</td></tr>
+    </table>
+    <div class="info-block warn" style="margin-top:10px"><div class="info-title w">缺点 / 注意</div><ul>
+      <li>删除目录（rm -rf）<strong>不可恢复</strong>，浏览器弹窗确认无法替代真正的安全保障</li>
+      <li>无文件编辑器（已明确否决，用 WebSSH vim/nano 代替）</li>
+      <li>无文件上传功能（可用 SFTP API 或 WebSSH scp）</li>
+      <li>无文件内容预览</li>
+    </ul></div>
+  </div>
+</div>
+
+<!-- 8. SCHEDULES -->
+<div class="section" id="schedules">
+  <div class="section-title"><span class="icon">⏰</span> 8. 定时调度</div>
+
+  <div class="card">
+    <div class="card-title"><span class="num">1</span> Cron 定时推送</div>
+    <p class="card-desc">配置 5 字段 Cron 表达式（分 时 日 月 周），定时将源目录推送到指定服务器组，后台每 60s 检查一次。</p>
+    <div class="info-grid">
+      <div class="info-block usage"><div class="info-title u">使用说明</div><ul>
+        <li>「定时」→「新建调度」→ 填名称、源路径、目标服务器、Cron 表达式</li>
+        <li>示例：<code>0 2 * * *</code> = 每天凌晨 2 点</li>
+        <li>可启用/禁用单个调度，不影响其他</li>
+      </ul></div>
+      <div class="info-block warn"><div class="info-title w">缺点 / 注意</div><ul>
+        <li>只支持文件推送，不支持脚本执行定时</li>
+        <li>只有 1 个 Primary Worker 运行调度（Redis 分布式锁），重启后需等下一周期</li>
+        <li>Cron 精度最小 1 分钟（60s 检查间隔）</li>
+      </ul></div>
+    </div>
+  </div>
+</div>
+
+<!-- 9. CREDENTIALS -->
+<div class="section" id="credentials">
+  <div class="section-title"><span class="icon">🔑</span> 9. 凭据管理</div>
+
+  <div class="card">
+    <div class="card-title"><span class="num">1</span> 数据库凭据</div>
+    <p class="card-desc">存储 MySQL/PostgreSQL 连接信息，密码 Fernet 加密，API 响应不含密码（仅元数据）。供脚本执行时通过 $DB_* 变量引用。</p>
+    <div class="info-block warn"><div class="info-title w">注意</div><p>凭据只加密存储，子机接收到的命令已含明文连接信息（仅在中心→子机的 HTTPS 传输中受保护）。</p></div>
+  </div>
+
+  <div class="card">
+    <div class="card-title"><span class="num">2</span> 密码预设</div>
+    <p class="card-desc">存储 SSH 密码模板（Fernet 加密），可在推送配置中引用，避免重复输入常用密码。</p>
+    <div class="info-block note"><div class="info-title n">注意</div><p>密码预设不能用于脚本 $DB_PASS 替换，只用于推送密码模板。</p></div>
+  </div>
+</div>
+
+<!-- 10. SETTINGS -->
+<div class="section" id="settings">
+  <div class="section-title"><span class="icon">⚙️</span> 10. 系统设置</div>
+
+  <div class="card">
+    <div class="card-title"><span class="num">1</span> 可配置项</div>
+    <table class="feat-table">
+      <tr><th>设置项</th><th>说明</th><th>是否可改</th></tr>
+      <tr><td>系统名称 / 标题</td><td>品牌展示名称</td><td>✅ 可改</td></tr>
+      <tr><td>告警阈值（CPU/内存/磁盘）</td><td>超过阈值触发 Telegram 告警，默认 80%</td><td>✅ 可改</td></tr>
+      <tr><td>Redis URL</td><td>Redis 连接地址</td><td>✅ 可改</td></tr>
+      <tr><td>数据库连接池大小</td><td>pool_size / max_overflow</td><td>✅ 可改</td></tr>
+      <tr><td>Telegram Bot Token / Chat ID</td><td>告警推送配置</td><td>✅ 可改</td></tr>
+      <tr><td>SECRET_KEY / API_KEY / ENCRYPTION_KEY</td><td>核心安全密钥</td><td>❌ 不可改（需改 .env 重启）</td></tr>
+      <tr><td>DATABASE_URL</td><td>数据库连接</td><td>❌ 不可改</td></tr>
+    </table>
+  </div>
+
+  <div class="card">
+    <div class="card-title"><span class="num">2</span> API Key 查看</div>
+    <p class="card-desc">全局 API Key 在设置页默认屏蔽，需输入管理员密码二次验证后才可查看完整值（操作记录到审计日志）。</p>
+  </div>
+</div>
+
+<!-- 11. AUDIT -->
+<div class="section" id="audit">
+  <div class="section-title"><span class="icon">📋</span> 11. 审计日志</div>
+
+  <div class="card">
+    <div class="card-title"><span class="num">1</span> 操作审计</div>
+    <p class="card-desc">所有 CUD 操作（创建/更新/删除服务器、推送、执行脚本、登录、改密码等）自动写入 <code>audit_logs</code>，记录操作人、IP、目标、详情。</p>
+    <div class="info-grid">
+      <div class="info-block usage"><div class="info-title u">使用说明</div><ul>
+        <li>「审计」页按操作类型过滤、分页查看</li>
+        <li>每页 50 条，支持按 action 类型过滤</li>
+      </ul></div>
+      <div class="info-block warn"><div class="info-title w">缺点 / 注意</div><ul>
+        <li>无日志导出功能（需直接查 MySQL）</li>
+        <li>无按时间范围过滤（只能按操作类型）</li>
+        <li>审计日志不会自动清理，长期运行需手动归档</li>
+      </ul></div>
+    </div>
+  </div>
+</div>
+
+<!-- 12. INSTALL -->
+<div class="section" id="install">
+  <div class="section-title"><span class="icon">🚀</span> 12. 安装向导</div>
+
+  <div class="card">
+    <div class="card-title"><span class="num">1</span> 5 步安装向导</div>
+    <p class="card-desc">无 <code>.env</code> 文件时系统进入安装模式，访问 <code>/app/install.html</code> 完成 5 步配置：欢迎 → 数据库 → Redis → 管理员账号 → 完成。自动生成 API Key / Secret Key / Encryption Key。</p>
+    <div class="info-grid">
+      <div class="info-block usage"><div class="info-title u">使用说明</div><ul>
+        <li>安装完成后 <code>.env</code> 自动生成，安装 API 除 GET /status 外全部锁定（返回 403）</li>
+        <li>重装需手动删除 <code>.env</code> 并重启</li>
+      </ul></div>
+      <div class="info-block warn"><div class="info-title w">注意</div><ul>
+        <li>安装过程未验证数据库/Redis 连接成功才允许进入下一步（应在步骤中手动验证）</li>
+        <li>安装模式下除 install API 和静态文件外，其余 API 返回 503</li>
+      </ul></div>
+    </div>
+  </div>
+</div>
+
+<!-- 13. GUARDIAN -->
+<div class="section" id="guardian">
+  <div class="section-title"><span class="icon">🛡</span> 13. 三层守护机制</div>
+
+  <div class="card">
+    <div class="card-title"><span class="num">1</span> 三层守护</div>
+    <table class="feat-table">
+      <tr><th>层级</th><th>机制</th><th>触发条件</th><th>动作</th></tr>
+      <tr><td>Layer 1</td><td>Supervisor</td><td>Python 进程崩溃</td><td>自动重启</td></tr>
+      <tr><td>Layer 2</td><td>Python self_monitor（30s）</td><td>Redis/MySQL 不可达</td><td>发 Telegram 告警/恢复</td></tr>
+      <tr><td>Layer 3</td><td>Shell cron（1 分钟）</td><td>连续 3 次 /health 失败</td><td>supervisorctl restart + Telegram</td></tr>
+    </table>
+    <div class="info-block warn" style="margin-top:10px"><div class="info-title w">注意</div><p>Shell cron 依赖宝塔/系统 crontab 配置，部署时需手动添加定时任务。</p></div>
+  </div>
+</div>
+
+<!-- 14. AGENT -->
+<div class="section" id="agent">
+  <div class="section-title"><span class="icon">🤖</span> 14. 子机 Agent</div>
+
+  <div class="card">
+    <div class="card-title"><span class="num">1</span> Agent 功能</div>
+    <p class="card-desc">部署在每台被管服务器上的轻量 FastAPI 服务（默认 <code>127.0.0.1:8601</code>），提供心跳、命令执行、进程管理。</p>
+    <table class="feat-table">
+      <tr><th>端点</th><th>功能</th></tr>
+      <tr><td>GET /health</td><td>返回 CPU/内存/磁盘等系统信息</td></tr>
+      <tr><td>POST /exec</td><td>执行 Shell 命令（wait=true 等待结果，wait=false 后台运行）</td></tr>
+      <tr><td>POST /exec/wait</td><td>等待指定 PID 的进程完成</td></tr>
+      <tr><td>POST /exec/kill</td><td>终止已注册的进程（防止杀非本 Agent 进程）</td></tr>
+      <tr><td>POST /config/reload</td><td>热更新 Agent 配置</td></tr>
+    </table>
+    <div class="info-grid" style="margin-top:12px">
+      <div class="info-block usage"><div class="info-title u">使用说明</div><ul>
+        <li>子机安装：<code>cd web/agent && pip install -r requirements.txt && uvicorn agent:app --host 127.0.0.1 --port 8601</code></li>
+        <li>配置文件 <code>config.json</code>：填写 <code>api_key</code>（从中心复制）、<code>server_id</code>、<code>central.url</code></li>
+        <li>心跳每 60s 自动上报，CPU/内存变化 &gt;10% 或超阈值时加急上报</li>
+      </ul></div>
+      <div class="info-block warn"><div class="info-title w">缺点 / 注意</div><ul>
+        <li>Agent 默认监听 <code>127.0.0.1</code>（只接受本机）；中心通过 SSH 端口转发或内网 IP 访问</li>
+        <li><code>/exec</code> 端点执行任意 Shell 命令，API Key 泄露等价于 RCE，Key 务必保密</li>
+        <li>Agent 无自动更新机制，升级需手动部署</li>
+        <li>长任务回调需子机能访问 <code>NEXUS_API_BASE_URL</code>（HTTPS）</li>
+      </ul></div>
+    </div>
+  </div>
+</div>
+
+<!-- 15. NOT IMPL -->
+<div class="section" id="notimpl">
+  <div class="section-title"><span class="icon">🚫</span> 15. 未实现 / 已否决功能</div>
+
+  <div class="card">
+    <table class="feat-table">
+      <tr><th>功能</th><th>状态</th><th>原因 / 替代方案</th></tr>
+      <tr><td>文件编辑器（Monaco/ACE）</td><td><span class="badge badge-red">已否决</span></td><td>运维场景用 WebSSH + vim/nano；嵌入编辑器增加复杂度无实质收益</td></tr>
+      <tr><td>会话录像（asciicast）</td><td><span class="badge badge-red">已否决</span></td><td>命令日志已满足审计需求</td></tr>
+      <tr><td>RBAC 权限体系</td><td><span class="badge badge-red">已否决</span></td><td>鉴权即信任，单管理员模型；增加 RBAC 代价远超收益</td></tr>
+      <tr><td>移动端适配</td><td><span class="badge badge-red">已否决</span></td><td>2000 台服务器运维不会用手机操作</td></tr>
+      <tr><td>批量服务器导入（CSV）</td><td><span class="badge badge-amber">未实现</span></td><td>可通过 API 批量 POST /api/servers/ 实现</td></tr>
+      <tr><td>文件上传到远程服务器</td><td><span class="badge badge-amber">未实现</span></td><td>可用 WebSSH scp / 推送功能代替</td></tr>
+      <tr><td>文件内容预览</td><td><span class="badge badge-amber">未实现</span></td><td>可通过 WebSSH cat 查看</td></tr>
+      <tr><td>审计日志时间范围过滤</td><td><span class="badge badge-amber">未实现</span></td><td>直接查 MySQL 可实现任意过滤</td></tr>
+      <tr><td>脚本执行定时触发</td><td><span class="badge badge-amber">未实现</span></td><td>定时调度目前只支持文件推送</td></tr>
+      <tr><td>T1～T5 + T-SE 联调验证</td><td><span class="badge badge-amber">待验证</span></td><td>代码已实现，需真机 E2E 测试</td></tr>
+    </table>
+  </div>
+</div>
+
+<!-- FOOTER -->
+<footer>
+  <p>Nexus 6.0 功能说明书 · 生成时间 2026-05-23</p>
+  <p style="margin-top:4px">Python 3.12 / FastAPI 0.115 / MySQL 8.4 / Redis 7 / asyncssh 2.17 / Tailwind v4</p>
+</footer>
+
+</div>
+</body>
+</html>