# amo 下一版（v2）九项改造报告

本地提交于 `156a31c` 之上，共 7 个提交（基线冻结 + 6 个功能提交）。**未 push、未部署、未碰路由器**；发布包已备好（见 §5），换装等发话。

| 提交 | 内容 |
|---|---|
| `d576219` | Go 金标准基线冻结（见 §3） |
| `80f1370` | 第 7 项 端口随机只掷一次 |
| `161a5d7` | UI 批次：第 3/5/6/9 项 |
| `6e82d0d` | 第 1 项 客户页统计条 |
| `bb8a0cb` | 第 4 项 核心版本探测 |
| `ad18e16` | 第 2 项 客户级凭据 |
| `18048f3` | 第 8 项 手动落地端点 |

## 1. 逐项状态与验证证据

**第 1 项 客户页统计条 — 完成。**
服务端 `CustomerSummary` 随 GET /api/customers 返回（total/online/depleted/depletingSoon/disabled/enabled），前端渲染六格统计条。口径逐条对齐 3x-ui 源码（`client_paging.go`）：耗尽 =(限额>0∧已用≥限额)∨已到期，不论启停；即将耗尽 = 启用中∧未耗尽∧[(距到期<expireDiff 天)∨(剩余<trafficDiff GB)]。**偏离说明**：这两个阈值是 3x-ui 的面板设置，出厂默认均为 **0（恒不触发）**，本版原样落为 amo Settings 的 `expireDiff`/`trafficDiff` 字段（默认 0），没有自创"90%"口径——未改设置前"即将耗尽"恒为 0，这是与 3x-ui 一致的行为。证据：`summary_test.go` 覆盖每桶及阈值开关两态（设 3 天/1GB 后 soon=2）；真机脚本核对种子库 summary={total 2, enabled 2, 其余 0} 与库一致。

**第 2 项 客户凭据收归客户级 — 完成。**
一套凭据（UUID + 32 字节根密钥 + ShortID）挂在客户记录上，全节点共用；绑定不再存凭据。SS2022 的 user key 按方法密钥长度对根密钥做**确定性前缀截断派生**（16/24/32 字节），legacy SS 与其他协议用原值——一份密码即可服务全部协议，与 3x-ui 的单客户单凭据模型一致。Reality 公钥仍是节点属性，凭据页签按绑定逐行显示。重生成改为整套轮换并重建该客户全部已部署节点。**API 形状变更**：GET 凭据返回 `{credentials, bindings}`；重生成路由改为 `POST /api/customers/:id/credentials/regenerate`，旧的 `.../credentials/:ncid/regenerate` 已移除（前端同步改完，无其他调用方）。**存量迁移**（store 加载时执行、幂等）：取第一个带凭据的绑定收敛；收敛后密码不是 32 字节根密钥时**仅重新生成密码**（UUID/ShortID 保留，老链接除 SS 密码外不变）；绑定凭据全部清空、随下次保存落盘消失。证据：`credentials_test.go`（收敛优先序/仅换密码/幂等/派生用例）；真机核对——种子客户 Alice 的 N1 链接与改前期望逐字节相同，N2 的 user key 恰为新根密钥前 16 字节派生值；重生成真机验证（部署载荷与订阅同步换成新 UUID、旧 UUID 消失）；订阅 golden 夹具在单套凭据下重建并逐条人工审计（RF/SS 两条逐字节不变，余五条按预期变化）。

**第 3 项 内容区间距 — 完成。** `.content` 改为全宽 + `padding:24px`，≤760px 为 8px，与 3x-ui page-shell 一致，一处改动全站生效。

**第 4 项 核心版本探测 — 完成。** agent-go 在引擎二进制 mtime+size 变化时（启动首轮/换装）才跑一次 `sing-box version` 并缓存，心跳 engine 报告新增 `singBoxVersion`（短字符串）；面板落库、服务器页核心版本列显示，老 agent 无字段显示"—"，可与新面板混跑（金标准剧本用老式心跳 + 新式心跳各验一轮）。**agent 版本号保持 0.6.8 未动**（源码常量已核）。证据：`singboxversion_test.go`（解析/缓存命中/换文件重探/二进制缺失）。

**第 5 项 删除延迟 — 完成。** 服务器页延迟列与统计条"平均延迟"格删除（统计网格 4→3 列）；系统状态页经查无延迟占位；后端本无 latency 字段。真机断言：服务中的 app.js 全文无"平均延迟"。

**第 6 项 图标悬停提示 — 完成。** 自研气泡（黑底白字圆角 + 尖角，挂 body 避免表格滚动裁剪），全部 icon-btn 的 title 换为 data-tip 并统一命名（二维码/详情/重置流量/编辑/删除/复制/重新生成凭据等）；非图标元素的原生 title（速度数值、完整地址）保留。

**第 7 项 端口只掷一次 — 完成。** 根因：NormalizeNode 以"键存在"判定重选，而前端编辑恒提交 port:null。新语义：已分配端口仅在显式改地址时才动（切 random 模式重掷 / fixed 给不同值且校验占用 / 迁服务器且目标端口被占）。证据：`portlock_test.go` 6 用例；金标准冻结了 UI 式全量 PATCH 场景；真机连存两次：端口 34035→34035→34035、出口端口同步不变。

**第 8 项 手动落地端点 — 完成。** 节点出口二选一：受管设备（现状）/ 手动端点（地址 + 端口 + VLESS/SS2022/SOCKS5 + 对应凭据，第三方节点同样可用）；面板只在入口侧生成 outbound + route、不下发出口资源、节点恒 exitReady。节点表单有粘贴 vless:// / ss:// / socks5:// 链接自动填表（SS 密码取 method 之后整段，即 serverKey:userKey 组合，与出站发送形态一致）。**两处规格外但必要的决定**：① 手动端口恒为显式值（远端服务的端口不可掷、也不查面板端口表），表单同此语义；② SS2022 密码在保存时前置校验 base64 密钥形态与长度（单段 PSK 或双段组合）——这是真 sing-box 对生成配置跑 `check` 时抓到的（非法形态会让整份配置被 sing-box 拒绝），与其部署时整节点失败，不如保存时给明确报错。**验收中另修一处真 bug**：DeployNode 的部署校验对无出口服务器的手动节点解引用了 nil（handler panic、连接断开），已修并加回归测试。证据：`manualexit_test.go`（校验/出站生成/不排出口 job/防 panic）；金标准新增 5 个 section（恰好 1 个入口 job、出站指向 203.0.113.9、用户为客户级凭据、节点转 active；既有 27 个 section 零变化）；生成配置经真 sing-box 1.13.21 `check` 通过。

**第 9 项 删除顶栏头像 — 完成。** span#avatar、app.js 赋值、.avatar CSS 三处全清；同排"刷新"按钮未动（真机断言仍在）。

## 2. 总验收

- 全量测试：panel-go `go test ./...` 全过、agent-go 全过、`go vet` 干净。
- 金标准：32 个 section 的全链路剧本（登录/心跳/订阅全格式/部署载荷/用量与 presence/凭据/手动端点/备份/错误用例）对最终二进制连续 verify 通过。
- 真机（最终 Go 面板 + 种子库）逐项核对：统计条对账、端口连存两次、凭据轮换全链路、核心版本全链路与老心跳兼容、手动端点 sing-box 配置 check、服务资源静态断言 13 条全过。
- **内存**：同种子、同预热流量、无 GOMEMLIMIT 的 A/B 实测——基线（156a31c）VmRSS 39.1 MB，最终版 39.1 MB，**零增长**。（UI 改版报告的 43.2MB 是另一台机器/另一负载下的数字，本次以受控 A/B 差值为口径。）
- **截图未产出**：本沙箱无浏览器二进制，Puppeteer 的 Chromium 下载源不可达（90 秒超时、无落地文件），`~/workspace/nexusgate-v2-shots/` 仍为空。前端验收改以"服务中真实 HTML/JS/CSS 断言 + API 全链路"完成；如需截图，需在有浏览器的环境补跑一轮。

## 3. Node 退役与基线冻结（用户 2026-10-21 04:36 决定）

Node 实现自本版起冻结退役，**Go 为单一真源**：八项（+第 9 项）只改了 panel-go、agent-go 与共用的 public/ 前端；server.js / lib/*.js / agent.js 未再同步，Node 测试不再作为门槛，difftest 差分退役。防行为漂移改用 Go 侧金标准：动手改模型前，先以 difftest 的确定性种子与剧本把 Go 现状行为冻结为 `panel-go/golden/`（golden.mjs + golden.json，27 个 section），此后每项改动只允许在对应提交中、经人工逐条审计后重新抓取基线（端口、summary 键、engine 字段、凭据形状、手动端点各一轮，提交说明均已列明受影响 section）。归一化器为此补了两条规则：base64 根密钥的前缀截断编码（第 2 项派生密钥）与 Surge 的 `=`→`_` 变体视为同一密钥。

## 4. 其他说明

- `LINK-MIGRATION.md`（非本任务产物）在第 2 项提交 `ad18e16` 中被 `git add -A` 一并扫入，内容未作任何改动；如需移出版本库请示下。
- NEXT-ROUND-NOTES.md 已随基线提交入库（`d576219`）。

## 5. 发布准备包（未部署）

`~/workspace/NexusGate-release/amo-panel-v2/`：

| 文件 | 大小 | sha256 |
|---|---|---|
| nexusgate-panel-linux-arm64 | 10,211,310 B | f135742c424192f53c2db2c270d383b67f2229f2593ea2c5b37502ae34d8460d |
| nexusgate-agent-linux-amd64 | 6,332,600 B | 4b641d2e46eedd6177166cf6a69b15d083959ca15f22d6b023c0387973265818 |
| nexusgate-agent-linux-arm64 | 5,963,960 B | 0e1ba1b0711b394944501b107381775d296642cf7b2f013825230a1288cb52d3 |
| SHA256SUMS | — | 包内文件，换装前先验哈希 |