133 lines
19 KiB
Markdown
133 lines
19 KiB
Markdown
# NexusGate UI 全量套皮报告（NexusGate → amo）
|
||
|
||
- 日期：2026-10-21
|
||
- 基线：`7c21742`（含按月重置，仅 panel-go 实现）
|
||
- 范围：前端按 3x-ui 定版样张全量重写；后端 Node 参考实现与 panel-go 双实现对称新增节点排序、在线状态（presence）、近似速度、系统状态采样、客户凭据接口、订阅聚合管线、服务器启停门禁；agent / agent-go **零改动**；版本保持 `0.6.8`。
|
||
- 结论：Node 测试 61/61、panel-go 测试全过、difftest 差分 E2E（selftest + Node vs Go 正式）各 65/65 全过；四页 + 客户表单三页签真机（Go 主控 + 种子库）截图自检通过；同种子同口径 RSS 新版未增（见 §7）。
|
||
|
||
## 1. 改动清单
|
||
|
||
### 1.1 前端（`public/`，双实现共用；panel-go 经 build.sh 同步进 embed）
|
||
|
||
- `index.html`：样张骨架（224px 侧边栏 + 顶栏 + 内容区）；品牌纯文字 **amo**（无 logo/图标）；`<title>amo</title>`；head 内联脚本按 localStorage `nexusgate-theme` 预置主题防闪烁；六个导航页：系统状态（原总览）、服务器、客户与订阅、转发与节点、安装与命令、设置与运维。
|
||
- `styles.css`：四样张 CSS 合并；浅色默认 + 深色变量双套；字体为 3x-ui 同款系统字体栈（`-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, "Noto Sans", "PingFang SC", "Hiragino Sans GB", "Microsoft YaHei", sans-serif`），**零 webfont/外链**；紧凑密度；弹窗/表单/页签/入站选择器/浮层/toast/登录/展开行样式齐备。
|
||
- `app.js`：全量重写（保留 api/CSRF/toast/弹窗/45s 自动刷新/哈希路由骨架）。全站无说明性文字（page-intro 类已绝迹，grep 验证）；原生 confirm/prompt 全部换成样式化弹窗；列表默认 50 条/页（客户/服务器/节点）。
|
||
- 四页按定版列落地：
|
||
- **系统状态**：四小卡（主控 CPU/内存/存储 + 今日全网流量，带迷你走势线；存储卡显示剩余）、整体速度双线图 + 三格统计（已发送/已接收/窗口均值）、连接数卡、底部信息条（运行时间：面板/系统｜面板：内存/在线节点/客户｜IP 地址 IPv4/IPv6）。
|
||
- **服务器**：统计条（设备总数/在线/离线/平均延迟）+ 15 列（展开 +｜复选｜操作｜已启用开关｜名称｜地址打码 + 表头 👁 显隐｜状态｜CPU｜内存｜Agent 版本 + 「有可用更新」徽标｜核心版本｜运行时长｜客户端总数/在线数｜延迟｜上次心跳）；展开行承载旧详情与全部旧动作。
|
||
- **客户与订阅**：定版列（操作图标栏：二维码/详情/重置流量/编辑/红删除｜已启用开关｜在线药丸 + 已暂停红字｜客户端名 + 备注两行｜关联入站协议分色 chip + 「+N」弹层｜流量药丸 + 迷你条｜速度｜剩余药丸｜时长药丸）。
|
||
- **转发与节点**：定版列（拖动手柄｜复选｜ID=排序序号｜铅笔 + ⋮ 菜单｜启用开关｜备注｜服务器 chip 三态色｜端口｜协议徽标组单行｜客户端总数 + 绿色在线数 + 悬停名单浮层（挂 body）｜流量药丸｜速度药丸｜到期时间药丸）。
|
||
|
||
### 1.2 后端 Node（`lib/`、`server.js`）
|
||
|
||
- 新增 `lib/presence.js`（在线/速度推导）、`lib/sysstat.js`（主控采样 + 环形历史 + 全局 IP 挑选）、`lib/extsub.js`（外部订阅拉取/解析/SSRF/退避/去重命名）、`lib/reset.js`（**按月重置从 panel-go 1:1 移植补齐 parity**，见 §5）。
|
||
- `lib/orchestrator.js`：绑定数据层抽出 `assignCustomerData/unassignCustomerData` + 新增 `alignCustomerNodes`（表单全量对齐）；部署校验加设备停用门禁；用量上报写 presence/速度（含节点 `lastSampleAt` 落盘，与 Go 对齐）。
|
||
- `lib/subscriptions.js`：entries 按节点 sortIndex 排序；新增聚合管线 `aggregateEntries`（自有 → 手动 → 外部合并/命名/去重）。
|
||
- `server.js`：`GET /api/system`、客户凭据 GET/regenerate、外部源手动刷新、节点 reorder 路由；客户 POST/PATCH 支持 `nodeIds` 全量对齐与聚合字段；housekeeping 接月重置 + 采样 + 到期源刷新；启动时 sortIndex 迁移。
|
||
- `lib/store.js`：默认 `brandName` 改为 `amo`。
|
||
|
||
### 1.3 后端 Go（`panel-go/`，与 Node 逐项对称）
|
||
|
||
- 新增 `presence.go`、`sysstat.go`、`extsub.go`；`types.go` 增字段（`Server.Enabled`、`Node.SortIndex` + 速度/活跃指针字段、`UsageSlot` 速度字段、`Customer.ExternalSources/ManualLinks`、顶层 `SubSourceCache`、设置项）；`orchestrator.go`（绑定对齐、停用门禁、用量写 presence/速度）；`subscriptions.go`（sortIndex 排序 + 聚合）；`handlers.go`（/api/system、凭据、刷新、reorder 路由与列表附加字段）；`main.go`（sortIndex 迁移、housekeeping 采样/刷新）；默认品牌名 `amo`。
|
||
|
||
### 1.4 测试
|
||
|
||
- 新增 `test/uireskin.test.js`（Node，9 个）与 `panel-go/uireskin_test.go`（Go：聚合解析、SSRF 拦截、排序/去重、presence 窗口等）。
|
||
- difftest 扩展 phase-3（见 §6），`ID_PREFIXES` 补 `src`/`lnk`。
|
||
|
||
## 2. 旧功能对照表（逐项核对旧前端动作入口）
|
||
|
||
旧前端共 22 个 `data-action`，新前端 38 个。逐项结论：
|
||
|
||
| 旧功能 | 新入口 | 结论 |
|
||
|---|---|---|
|
||
| 新建/编辑/删除服务器、复制注册命令 | 服务器页操作列同名动作 | ✅ 保留 |
|
||
| 服务器详情（资源余量、TLS 证书、引擎状态、流量统计状态、旧版 agent 警告、重试清理、遗忘离线、SSH 卸载 Agent） | 服务器展开行 | ✅ 保留（样张 15 列放不下的收进展开行） |
|
||
| 新建/编辑/删除客户、启停、重置流量、重置令牌 | 客户页操作列 + 表单左下「重置流量」+ 订阅弹窗重置令牌 | ✅ 保留 |
|
||
| 客户详情（IP 观测、使用限制、订阅访问日志、清空日志） | 操作列详情 ⓘ 弹窗 | ✅ 保留（列表不显示 IP/设备上限，详情与表单仍在） |
|
||
| 订阅链接（9 种格式 + 信息页 + 各节点入站链接 + 二维码） | 订阅弹窗，顶部 auto 格式二维码 + 逐行复制/二维码 | ✅ 保留 |
|
||
| 新建/编辑节点、部署、修复、删除 | 节点页菜单（铅笔/⋮） | ✅ 保留 |
|
||
| 节点行「停用/启用」按钮 | **去除**（用户定版：与行首开关重复，只留开关） | ⛔ 按定版删除 |
|
||
| 节点页「分配客户」表单 + 客户端弹窗内解绑 | **去除**；绑定写入口收敛到客户表单「关联入站」（用户定版，防两处不一致）；`/assign`、`/unassign` API 保留不动；节点客户端弹窗改只读名单 + 可复制链接 | ⛔ 按定版收敛 |
|
||
| `copy-uri` 复制动作 | 改名统一为 `copy-text`（订阅行、命令、入站链接同一处理器） | ✅ 改名保留 |
|
||
| 安装与命令页全部命令复制 | 命令页换皮、删除每条命令的说明小字 | ✅ 保留 |
|
||
| 设置与运维（改密、备份下载/恢复等） | 运维页换皮、删除说明段（备份卡保留一句凭据保管警告） | ✅ 保留 |
|
||
| 旧前端死代码 `renderNodeLinks` | 未迁移（无入口调用） | ⛔ 死代码不迁移 |
|
||
|
||
## 3. 客户表单三页签（基本 / 凭据 / 链接）
|
||
|
||
- **基本**：名称、分组、流量上限 GB、快速到期 + 到期日期/时间、IP 限制、设备（HWID）限制、**流量重置成对控件**（「流量重置」下拉：不重置/每月 + 「每月重置日」数字输入并排；直接绑定既有 `trafficResetDay`，非「每月」时重置日输入禁用，截图与 DOM 实测验证）、标签、备注、启用开关（编辑态绑定状态）、左下「重置流量」（仅编辑态）。
|
||
- **关联入站**（基本页签内）：点击输入框弹下拉面板列全部节点（按 sortIndex 序、可滚动、已选高亮 + ✓、点击切换），右侧 🔍 按节点名搜索过滤；已选项以 chips 呈现可 × 单删；「全选 / 全部清除」按钮。保存 = 按勾选全量对齐 `nodeClients`（走现有部署/回收链路与凭据生成，不另起数据）。
|
||
- 3x-ui 独有而模型没有的字段（自动续期/Telegram ID/反向标签等）**未加**。
|
||
- **凭据**：订阅令牌行（复制 + ↻ 重置，沿用既有 rotate-subscription）；每条节点绑定一行：节点名/协议/状态、UUID（`credentials.clientId`)、密码（`credentials.relayPassword`，SS/HY2/AnyTLS/SOCKS 共用）、Reality Short ID（`credentials.shortId`)、SOCKS 时用户名（`ng:<customerId>`）；逐项只读 + 复制 + ↻ 重新生成（**二次确认**）。
|
||
- **凭据对应关系（按代码模型点名）**：凭据挂在「客户 × 节点」绑定（nodeClients）上、每条绑定一套，不是客户级一套——同一客户在不同节点上的 UUID/密码/Short ID 各自独立；订阅令牌（subId）才是客户级的。新接口：`GET /api/customers/:id/credentials`、`POST /api/customers/:id/credentials/:ncid/regenerate`（重生成后对已部署节点自动 rebuildNode 下发；打审计 `regenerate_credentials`）；生成规则沿用既有 `newNodeClientCredentials(protocol)`，未新造格式。
|
||
- **链接**：顶部一句短文案（「添加第三方分享链接和远程订阅地址，将其包含在该客户的订阅中」）；「＋ 添加外部链接」+ 手动链接列表（空态「暂无外部链接」；每条：链接本体 + 备注 + 启用开关 + 删除）；「＋ 添加外部订阅」+ 订阅源列表（空态「暂无外部订阅」；每条：地址 + 备注 + 可选 UA + 启用开关 + 删除 + 状态行（条数/上次成功/失败原因/已忽略 N 条）+「立即刷新」）。
|
||
|
||
## 4. 订阅聚合（按 SUB-AGGREGATION-DESIGN.md 全文）
|
||
|
||
- 客户新增 `externalSources`（≤5）与 `manualLinks`（≤50）；拉取缓存独立顶层 `subSourceCache`（与客户配置分离，删源/删客户顺手清键）。
|
||
- 拉取：超时 10s、体上限 1MiB、每源 ≤200 条、重定向 ≤3 跳逐跳复检；SSRF：解析全部地址、任一非全局即拒绝（`settings.allowPrivateSubSources` 默认关时才放行内网）、连接钉死校验过的 IP 并保留 Host/SNI；UA 默认 `v2rayN/6.55` 可按源覆盖；解析只吃链接列表（整体 base64 或明文逐行），协议白名单 `vless/ss/hysteria2/anytls/socks5`，其余丢弃并计数 `droppedCount`。
|
||
- 刷新：全局间隔 `settings.externalSubRefreshMinutes` 默认 60（钳 15–720）；失败指数退避 + 确定性 jitter（双实现一致）；housekeeping 每轮串行最多 3 个到期源；保存新增/改 URL 后台立即拉一次；手动刷新端点同步返回结果；**失败永远用上次成功缓存兜底**。
|
||
- 合并：顺序自有（sortIndex）→ 手动（列表序）→ 外部（源序/缓存序）；外部项命名加 `[源备注]` 前缀，手动项取备注 → URI 自带名 → 「手动节点 N」；跨段重名追加 ` (2)`；去重键 = 协议 + 主机（小写）+ 端口 + 凭据指纹（解码后 userinfo 的 sha256 前 16 hex），自有优先；外部项不计量；客户停用仍整单 403；**自有-only 客户输出与改造前逐字节一致**（difftest 金标准守）。
|
||
- 注：面板没有 `/api/settings` 路由（双实现都没有，旧前端也无此调用），`externalSubRefreshMinutes`/`allowPrivateSubSources` 只能改数据文件——属既有形态，本轮未新造设置 UI。
|
||
|
||
## 5. 口径取舍专节（被迫近似与信号缺口，逐项点名）
|
||
|
||
1. **presence 粒度近似（B2）**：agent 用量样本只有 `{kind:'user', id:customerId}`（按服务器聚合，无节点线索）与 `{kind:'inbound', id:nodeId}`；observations 只有 `{customerId, ip}`。故客户×节点在线的推导为：客户在其绑定节点的服务器上有新鲜活跃槽（180s 窗口）⇒ 该客户在该服务器的**全部**绑定节点上同时点亮。同机多节点无法区分——这是上报粒度的上限，agent 协议未动。`customer.lastOnlineAt` 此前双实现从未写入，本轮在用量 delta>0 与 observations 接受时补写。
|
||
2. **速度为近似值（B3）**：相邻两次已处理样本 delta/时间差（dt≥5s 才更新，epoch 变更跳过），有效期 150s；无历史显「—」。difftest 里速度值依赖墙钟，只比形状（正/零）不比数值。
|
||
3. **连接数替代呈现（B4）**：agent 上报**没有连接数字段**，未编造通道——系统状态「连接数」卡与 /api/system 的 `connections` 用**在线客户数**替代呈现，前端卡内如实标注「在线客户」及在线节点/客户明细。「今日流量」基线为纯内存（面板启动时刻的节点累计量），面板重启后从启动时重新累计；历史环形缓冲 240 条纯内存（主控指标 + 全网速度/连接数），量级百 KB 内。
|
||
4. **服务器延迟无数据源**：agent 心跳不上报延迟——服务器页统计条与延迟列恒显「—」，未编造。
|
||
5. **核心版本（sing-box 版本）无数据源**：engine 上报只有 `singBoxInstalled` 布尔——核心版本列恒显「—」。CPU% 由 load1/cpuCount 换算，内存% 由 memoryTotal/memoryAvailable 算。
|
||
6. **节点到期时间恒 ∞**：节点模型无到期字段，到期时间药丸恒显 ∞，未造字段。
|
||
7. **IP 地址口径（B5）**：从主机网卡挑全局地址（排除 RFC1918/CGNAT/链路本地/ULA/回环/组播），取不到显「—」；不调用任何外部 IP 查询服务。沙箱实测显示 198.19.0.2（VM 出口的基准测试段地址，属网卡地址列表口径内；真实硬件上为实际网卡全局地址）。
|
||
8. **系统状态页活动区**：样张底部无活动区；为保「旧功能零丢失」，在信息条下方补回异常节点提示条（有才显）+ 最近活动面板——相对样张的唯一版式增补，特此点名。
|
||
9. **存储卡走势线**：无历史数据源时以当前占用率画平线（真实采样累积后即为真实曲线）。
|
||
10. **服务器 enabled（新实现）**：server 加 `enabled`（默认 true）：停用后禁止其上节点部署（409「设备 X 已停用」）、reconcile 跳过该设备；与状态（在线/离线）正交。
|
||
11. **按月重置 Node parity 补齐**：该功能原只有 panel-go 实现（7c21742）；本轮按 reset.go 语义 1:1 移植到 Node 并接进 create/PATCH/housekeeping——这是 parity 补齐，不是行为变更，Go 侧行为不变。
|
||
12. **种⼦环境假象（验收时确认非缺陷）**：种子库节点在面板重启后被既有 reconcile 置为 deploying（无真实 agent 轮询完成），故截图里「在线节点」按 active 计数为 0、节点开关呈启用态——与生产（agent 数秒内轮询完成）表现不同，非套皮问题。
|
||
|
||
## 6. 改名清单（NexusGate → amo，仅展示层）
|
||
|
||
改了的可见点：
|
||
- 侧边栏品牌、登录页品牌：纯文字「amo」加粗，无 logo。
|
||
- 页面 `<title>amo</title>`、顶栏面包屑前缀、订阅输出可见名相关默认值。
|
||
- Node 与 Go 的默认设置 `brandName`：`NexusGate` → `amo`（新库默认；`brandName` 当前无渲染消费点，老库里的存量值不会出现在任何用户可见输出中）。
|
||
- 面板对外文案中的产品名（前端静态文案）。
|
||
|
||
刻意保留的内部标识（未改）：
|
||
- 仓库目录、二进制名（`nexusgate-panel` 等）、数据路径（`/etc/nexusgate`、`nexusgate.json`)、环境变量（`NG_*`)、agent 协议与字段名。
|
||
- 安装/卸载命令里的仓库 URL（`git.881218.xyz/rogue/NexusGate`)。
|
||
- 启动日志行与数据文件损坏错误文案中的 "NexusGate"（运维耦合的日志/错误前缀，按定版保留）。
|
||
|
||
## 7. 测试与验收证据
|
||
|
||
| 项目 | 结果 |
|
||
|---|---|
|
||
| Node 测试 `npm test` | **61/61 全过**（含新增 uireskin 9 个） |
|
||
| Go 测试 `go test ./...` | **全过**（含新增 uireskin_test.go) |
|
||
| difftest selftest（Node vs Node) | **65/65** |
|
||
| difftest 正式（Node vs Go 二进制） | **65/65** |
|
||
| 真跑截图自检 | Go 主控 + 混合种子库（3 服务器/6 客户/3 节点/6 绑定，含在线/离线/额度暂停/手动停用/过期/聚合客户），四页 + 表单三页签 + 深色抽查，见下 |
|
||
| RSS 对比 | 同一种子、同样预热请求、无 GOMEMLIMIT 的同口径：**基线（7c21742）VmRSS 45,528–45,596 kB；新版 43,164–43,224 kB**——新版未增（差值在 Go 运行时波动量级内）；新增历史环形缓冲纯内存 240 条封顶 |
|
||
|
||
difftest phase-3 新增覆盖（双实现逐项比对）：节点 reorder 后列表序与订阅输出序、客户 PATCH `nodeIds` 全量对齐（加/清绑定）、凭据 GET 形状与 regenerate 后凭据变化、两段用量上报后的 presence 投影（在线布尔/速度正性）与速度字段形状归一、`/api/system` 键结构形状、聚合全链路（本地 fixture 源：手动刷新返回 count=2/dropped=1、externalStatus 状态、Dave 全格式订阅逐项比对）。时间依赖值（速度数值、/api/system 数值）按设计只比形状——Normalizer 对 `speedUpBps/speedDownBps` 做正/零归一并注明原因。既有约束保持：Alice 订阅与 seed 金标准逐字节比对、DB 互换（swap）后互通、phase-2 全部步骤不变。
|
||
|
||
截图（浅色默认，深色抽查客户页）：
|
||
- `~/workspace/nexusgate-ui-reskin-shots/01-overview-light.png` 系统状态
|
||
- `~/workspace/nexusgate-ui-reskin-shots/02-servers-light.png` 服务器
|
||
- `~/workspace/nexusgate-ui-reskin-shots/03-customers-light.png` 客户与订阅（在线/离线/额度暂停/手动停用/已过期五态齐全；无备注客户第二行留空、无分组回退）
|
||
- `~/workspace/nexusgate-ui-reskin-shots/04-nodes-light.png` 转发与节点
|
||
- `~/workspace/nexusgate-ui-reskin-shots/05-customer-form-basic.png` 客户表单·基本（流量重置成对控件、关联入站 chips、左下重置流量）
|
||
- `~/workspace/nexusgate-ui-reskin-shots/06-customer-form-credentials.png` 客户表单·凭据（Dave：令牌 + N1 绑定 UUID/密码/Short ID)
|
||
- `~/workspace/nexusgate-ui-reskin-shots/07-customer-form-links.png` 客户表单·链接（手动链接 + 外部源 + 状态行 + 立即刷新）
|
||
- `~/workspace/nexusgate-ui-reskin-shots/08-customers-dark.png` 客户页深色
|
||
|
||
自检中发现并处置：① difftest interop 暴露 Node 侧节点 `lastSampleAt` 未落盘（速度计算借道 lastUsageAt）——已按设计对齐落盘并复跑全绿；② 截图种子一度用了模型不存在的 `disabled` 状态——模型手动停用为 `suspended+manual`，前端推导与后端一致，种子已修正（非产品缺陷）。
|
||
|
||
## 8. 提交
|
||
|
||
本地提交（不 push）:
|
||
1. `feat(panel): reskin backend — node sortIndex, presence/speed, /api/system, credentials, subscription aggregation (Node+Go parity)`（含 SUB-AGGREGATION-DESIGN.md、difftest phase-3)
|
||
2. `feat(web): 3x-ui style reskin — amo branding, light/dark themes, four pages + tabbed customer form`
|
||
3. `docs: UI reskin report`
|