windy/vps
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs: archive historical planning documents and fix references

Browse Source 
Move self-described historical/upstream docs to docs/archive/:
- agent-runbook-guide.md
- lan-core-switch-upgrade-plan.md
- lan-rb5009-upgrade.md
- se5420-review-claim-verification-2026-08.md

Update archive/README.md manifest and fix relative links in active docs
and archived docs. Update AGENTS.md docs/ layout description.
This commit is contained in:
windyboy
2026-08-22 19:34:05 +08:00
parent aaa4ee312e
commit 27fe9c078e
10 changed files with 29 additions and 25 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/archive/README.md
+4
View File
@@ -8,6 +8,10 @@
| 文件 | 归档日期 | 原位置 | 说明 |
|------|---------|--------|------|
| `lan-dns-alternatives.md` | 2026-08-17 | `docs/` | DNS 技术选型调研，零引用，无在途决策 |
| `agent-runbook-guide.md` | 2026-08-22 | `docs/` | 上游参考存档；仓库落地规范为 `RUNBOOKS.md` |
| `lan-core-switch-upgrade-plan.md` | 2026-08-22 | `docs/` | SE5420 历史规划参考；执行以 `docs/lan-se5420-deployment-guide.md` 为准 |
| `lan-rb5009-upgrade.md` | 2026-08-22 | `docs/` | 未采购的 ER-X→RB5009 休眠备选方案；其中 PVE 透传与 VLAN10 调研仍可参考 |
| `se5420-review-claim-verification-2026-08.md` | 2026-08-22 | `docs/` | 一次性评审复核调研（现场只读复核结论） |
> 购物类文档（打印机购买指南、交换机选型调研）已按整改计划移入 Obsidian
> vault（`~/Documents/vault/my-vault/02_Areas/House/`），不在本目录。
docs/archive/agent-runbook-guide.md
+326
View File
@@ -0,0 +1,326 @@
# Agent Runbook 实用指南（v1）
> **定位**：本指南用于把团队的重复性运维、交付与故障处理经验写成可由 Agent 安全执行的流程。它适用于以 Git 仓库为中心的工程协作模式，优先采用 **Markdown + Git 版本控制 + 明确的 Agent 路由规则**，而不是一开始引入复杂的自动化平台。
> 本文件为上游参考存档。仓库内落地规范见 [`RUNBOOKS.md`](../../RUNBOOKS.md)，标准模板见 [`runbooks/_template.md`](../../runbooks/_template.md)，索引见 [`runbooks/README.md`](../../runbooks/README.md)。
## 1. 什么是 Agent Runbook
Runbook 是预先设计的、可重复执行的操作流程，用于处理部署、告警、故障、配置变更、CI 修复等标准化工作。传统 Runbook 的主要读者是人；**Agent Runbook 则必须把人的隐性判断显式化**，使 Agent 能知道做什么、看到什么才算正常、下一步去哪里、何时停止以及如何撤销。
Google SRE 强调在事故发生前设计响应流程、系统化排障，并逐步将重复性运维工作自动化。[1] [2] AWS Systems Manager Automation 则把可执行 Runbook 建模为顺序步骤：每个步骤调用一个动作，前一步输出可以传递给后续步骤。[3] 这两种思路共同构成了 Agent Runbook 的实用基础。
| 层次 | 核心问题 | 应承担的职责 |
|---|---|---|
| `AGENTS.md` | **何时使用哪份流程？** | 工作路由、通用操作约束、无匹配流程时的默认行为 |
| `runbooks/*.md` | **这件事按什么流程做？** | 前置条件、分步操作、决策分支、验证、停止条件与回滚 |
| Skill / MCP / Tool | **有哪些可调用能力？** | 具体能力、参数、权限边界和使用说明 |
| Shell / GitHub / Linear / SSH 等 | **实际如何执行？** | 对系统、代码库或外部服务执行操作 |
## 2. 设计目标与适用边界
Agent Runbook 的目标不是让 Agent 在所有异常下“想办法修好”，而是在一个**已知、受控、可验证、可回退**的边界中提高执行一致性。它应当优先覆盖高频、后果明确、流程稳定的操作，例如 CI 失败定位、Issue 到合并请求、发布前检查、标准部署、回滚及网络变更。
| 适合纳入 Runbook | 暂不适合直接自动执行 |
|---|---|
| 明确输入、固定步骤、可观察结果的操作 | 目标或验收标准尚不清楚的探索性任务 |
| 可在每次修改后验证状态的变更 | 缺失关键参数、权限或上下文的任务 |
| 具有安全回滚路径的发布与配置调整 | 高破坏性、不可逆或影响面未知的操作 |
| 可由权限与审批规则约束的运维流程 | 与既有流程事实冲突、无法判断根因的异常场景 |
> **基本原则**：当实际状态与 Runbook 的假设冲突，Agent 应停止并呈报，而不是补全未知信息、绕过检查或继续试错。
## 3. Agent Runbook 的最小字段
与普通人工 Runbook 相比，Agent Runbook 必须显式包含以下六类控制信息。缺少其中任一项，都会增加盲目执行或错误恢复的风险。
| 字段 | 作用 | 写作要求 |
|---|---|---|
| **Action** | 定义当前要执行的动作 | 使用可观察、可执行的动词；避免“检查一下”“适当调整”等模糊表述 |
| **Expected** | 描述正常状态或预期输出 | 给出具体信号、阈值、状态码、测试结果或页面表现 |
| **Decision** | 定义分支与下一跳 | 用“条件 → 下一步”的形式；无法判断时指向 `STOP` |
| **Verification** | 确认变更真正生效 | 在每个有副作用的步骤后执行，不能被跳过 |
| **Stop condition** | 规定何时不得继续 | 明确列出信息缺失、状态冲突、权限不足、验证失败等条件 |
| **Rollback** | 描述如何恢复到变更前状态 | 标明触发条件、前提、撤销步骤及回滚后的验证方式 |
## 4. 推荐目录与路由机制
建议把流程与代码一起保存在 Git 仓库中。这样 Runbook 可以评审、版本化、随系统演进更新，也能与相关 Issue、PR 和配置建立可追溯关系。
```text
repo/
├── AGENTS.md
├── RUNBOOKS.md
├── runbooks/
│ ├── README.md
│ ├── issue-to-merge.md
│ ├── fix-ci.md
│ ├── release.md
│ ├── rollback.md
│ ├── network-change.md
│ └── network-recovery.md
└── ...
```
### `AGENTS.md`：只做路由与通用约束
`AGENTS.md` 不应重复流程细节。它只需要规定 Agent 在进行操作类工作前，先查找最具体且适用的 Runbook，并严格遵守其中的步骤、验证、停止和审批要求。
```markdown
# Operational Rules
Before performing operational work:
1. Inspect `runbooks/`.
2. Select the most specific applicable runbook.
3. Follow its steps in order.
4. Do not skip verification steps.
5. Respect STOP and approval conditions.
6. If no runbook applies, diagnose only; do not mutate production state.
## Routing
- CI failure → `runbooks/fix-ci.md`
- GitHub issue implementation → `runbooks/issue-to-merge.md`
- Deployment → `runbooks/release.md`
- Rollback → `runbooks/rollback.md`
- Network configuration → `runbooks/network-change.md`
- Network outage → `runbooks/network-recovery.md`
```
### `RUNBOOKS.md`：仓库级规范
`RUNBOOKS.md` 用于统一所有 Runbook 的字段、命名、评审要求和变更规则。每份 Runbook 只描述一种可识别的操作意图；如果流程已有明显分叉，应拆分为独立文件，而不是堆叠成长篇“万能流程”。
## 5. 规范模板
以下模板可直接保存为 `runbooks/_template.md` 使用。
```markdown
# Runbook: <名称>
## Purpose
说明本 Runbook 要解决的问题及成功结果。
## Scope
- 适用环境：<如 development / staging / production>
- 适用对象：<服务、仓库、组件或告警类型>
- 不适用情形：<需要改用其他 Runbook 或转人工的场景>
## Ownership
- Owner：<团队或角色>
- Last reviewed：<YYYY-MM-DD>
- Related systems：<系统名称>
## Preconditions
- <执行前必须满足的权限、备份、窗口、健康状态或已知信息>
## Inputs
| 输入 | 来源 | 是否必需 | 校验方法 |
|---|---|---:|---|
| <参数> | <来源> | 是/否 | <如何确认有效> |
## Safety
### Non-negotiable rules
- 先只读诊断，后执行变更。
- 不得把删除现有配置作为首次恢复动作。
- 不得猜测或编造缺失参数。
- 不得绕过失败的测试、检查或审批。
- 每次变更后必须完成对应验证。
- 破坏性操作必须获得明确批准。
### Stop conditions
- 实际状态与本文档的前提或预期结果冲突。
- 缺少必要输入、权限、审批或回滚能力。
- 验证失败且本文档没有明确的下一步。
- 影响范围超出 Scope。
### Approval gates
| 动作 | 风险级别 | 是否需要明确批准 | 批准记录位置 |
|---|---|---:|---|
| <动作> | 低/中/高 | 是/否 | <Issue / PR / 变更单> |
## Procedure
### Step 1 — Diagnose
**Action**
<执行只读诊断动作。>
**Expected**
<列出预期输出、状态或证据。>
**Decision**
- 若 <条件 A>，进入 Step 2。
- 若 <条件 B>，进入 Troubleshooting A。
- 若无法判断或状态冲突，`STOP` 并记录证据。
### Step 2 — Change
**Action**
<描述单一、可审计的变更动作。>
**Expected**
<变更后应出现的状态。>
**Verification**
<给出可重复执行的验证命令、测试、监控指标或检查清单。>
**Rollback**
- 触发条件：<什么情况需要回滚>
- 回滚动作：<如何撤销>
- 回滚验证：<如何确认恢复成功>
## Troubleshooting
### Troubleshooting A — <异常名称>
- 证据收集：<日志、指标、命令输出、链接>
- 允许动作：<仅限已验证且低风险的动作>
- 下一步：<回到某步 / 转入另一 Runbook / STOP 并升级>
## Final Verification
只有同时满足以下标准，流程才算成功：
- <功能或服务状态>
- <自动化测试或健康检查>
- <监控指标或告警状态>
- <变更记录、PR 或 Issue 已更新>
## Failure Handling
若未能完成：
1. 停止进一步变更。
2. 收集 <命令输出、时间范围、请求 ID、日志链接、截图或复现步骤>。
3. 记录已完成步骤、实际结果、未满足的预期和是否执行过回滚。
4. 按 <升级渠道> 交接，不继续猜测。
## References
- <关联 Issue、PR、架构文档、仪表盘、配置仓库或外部文档>
```
## 6. 编写步骤的标准写法
每个步骤应只承担一个清晰目的，并使用“动作—预期—决策”的闭环表达。如下表所示，前者会导致 Agent 自主扩大操作范围，后者则为其提供安全边界。
| 不推荐写法 | 推荐写法 |
|---|---|
| “检查部署是否正常，不正常就修复。” | “读取部署状态与最近一次发布记录。若所有副本 `Ready` 且版本等于目标版本，进入 Final Verification；若副本未就绪，收集事件与日志并进入 Troubleshooting A；若版本不匹配且原因未知，`STOP`。” |
| “必要时修改配置。” | “仅当配置差异与变更单 `CHG-123` 完全一致且审批已记录时，应用指定键的值；应用后运行健康检查；失败则按 Rollback 回退。” |
| “测试失败时可先跳过。” | “任何必需测试失败均不得继续部署。记录失败测试、日志和提交版本；仅按 Troubleshooting B 处理。” |
## 7. 通用安全规则
以下规则适合在每份 Runbook 的 `Safety` 章节中复用。若某流程存在更严格要求，应以更严格要求为准。
```markdown
## Safety Rules
- Never delete an existing configuration as the first recovery action.
- Prefer read-only diagnosis before mutation.
- After every mutation, verify the expected state.
- If actual state conflicts with this runbook, STOP.
- Do not invent missing parameters.
- Do not bypass failed tests.
- Destructive actions require explicit approval.
```
这些约束体现了一个关键顺序：**先证据，后变更；先小范围，后扩大；先验证，后结束；不确定则停止。** 特别是停止条件必须可操作，例如“权限不足”“缺少变更单”“生产状态与前提不一致”“错误率超过 1%”等，而不应写成“情况复杂时停止”。
## 8. 运行与审计流程
Agent 执行 Runbook 时，应按照固定运行模型工作。每一步的输入、动作、输出和下一跳都应可追踪，这与 AWS 自动化 Runbook 的顺序步骤和输出传递思想一致。[3]
```text
输入与前置条件
↓
只读诊断
↓
确认预期状态或决策分支
↓
获取审批（如需要）
↓
执行最小变更
↓
立即验证
↓
成功收尾 / 回滚 / 停止并升级
```
| 阶段 | Agent 必须产出的证据 | 禁止行为 |
|---|---|---|
| 输入确认 | 参数来源、环境、目标资源、权限与审批状态 | 用猜测值补全必需参数 |
| 诊断 | 命令输出、日志、指标或页面状态 | 在未诊断前直接修改生产状态 |
| 变更 | 实际执行内容、变更范围、时间 | 将多个无关变更混在一起执行 |
| 验证 | 测试、健康检查、监控状态与预期对比 | 以“命令执行成功”代替业务验证 |
| 失败处理 | 已做步骤、异常证据、回滚状态和升级对象 | 无限制重试或绕过失败检查 |
## 9. 从人工操作到自动化的成熟路径
不建议在流程尚未稳定时先构建复杂 DSL 或全自动编排。应先积累真实案例，把可重复部分固化为 Markdown Runbook，再把已稳定、低歧义、可验证的操作迁移到脚本、CI、Skill 或自动化系统。Google SRE 将能够由机器替代的重复性人工工作视为应逐步消除的 toil。[4]
| 阶段 | 主要形式 | 人的角色 | 自动化边界 |
|---|---|---|---|
| 1. 人工处理 | 现场处置与复盘 | 执行、判断、记录 | 不自动化 |
| 2. Markdown Runbook | 固化步骤与证据要求 | 审核流程与异常判断 | Agent 可辅助诊断 |
| 3. Agent + Runbook | 严格按流程执行 | 审批高风险动作、处理例外 | 受停止条件约束的执行 |
| 4. Script / Skill / CI / Automation | 把稳定步骤程序化 | 处理异常和维护自动化 | 自动完成重复性操作 |
| 5. 人工审批 + 自动执行 | 常规流程端到端运行 | 决策、审计与治理 | 审批门控下的自动变更 |
## 10. 上线前检查清单
在将一份新 Runbook 交给 Agent 使用前，建议由流程所有者按以下清单审核。
| 检查项 | 合格标准 |
|---|---|
| 问题边界 | Purpose 与 Scope 清楚描述适用和不适用情形 |
| 输入 | 所有必需输入都有来源、格式和校验方法 |
| 步骤 | 每一步均有 Action、Expected 与明确的下一跳 |
| 变更控制 | 所有修改动作都有 Verification；关键动作有 Rollback |
| 安全控制 | Stop conditions、审批门槛和禁止行为已列明 |
| 异常处理 | 失败时知道收集什么证据、交给谁，而非继续猜测 |
| 可维护性 | 有 Owner、最近复审日期与关联文档；已在版本控制中评审 |
| 可演练性 | 已在安全环境或历史案例上走通至少一次 |
## 11. 建议的首批 Runbook
首次落地时，应优先选择频率较高、输入相对明确、变更可回退的场景。以下集合通常能覆盖大部分工程协作的基础需求。
| Runbook | 目的 | 关键安全控制 |
|---|---|---|
| `issue-to-merge.md` | 从已明确 Issue 到可评审变更 | Scope 锁定、测试门槛、PR 证据 |
| `fix-ci.md` | 诊断并修复 CI 失败 | 不跳过测试、不修改无关代码 |
| `release.md` | 执行标准发布 | 发布窗口、审批、健康检查、回滚点 |
| `rollback.md` | 恢复到已知稳定版本 | 明确触发条件、版本选择、回滚后验证 |
| `network-change.md` | 实施受控网络配置变更 | 影响评估、变更单、回退配置 |
| `network-recovery.md` | 处理网络异常与服务恢复 | 只读诊断优先、状态冲突即停止 |
## 12. 结论
Agent Runbook 的价值不在于把每一项运维工作立即自动化，而在于将团队的工程判断编码为**可路由、可验证、可停止、可回滚**的操作系统。对于多数团队，从仓库中的 `AGENTS.md`、`RUNBOOKS.md` 和一组 Markdown Runbook 起步，已经足够实用。
当某个流程经过多次执行、输入稳定、异常分支收敛且验证可靠后，再将其下沉为脚本、CI 或其他自动化能力。这样既能逐步降低重复性 toil，也能始终保留人类对高风险和例外情形的决策权。[4]
## References
[1]: https://sre.google/sre-book/managing-incidents/ "Google SRE Book — Managing Incidents"
[2]: https://sre.google/sre-book/effective-troubleshooting/ "Google SRE Book — Effective Troubleshooting"
[3]: https://docs.aws.amazon.com/systems-manager/latest/userguide/automation-documents.html "AWS Systems Manager — Creating your own runbooks"
[4]: https://sre.google/sre-book/eliminating-toil/ "Google SRE Book — Eliminating Toil"
[5]: https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-automation.html "AWS Systems Manager Automation"
[6]: https://docs.aws.amazon.com/systems-manager-automation-runbooks/latest/userguide/automation-runbook-reference.html "AWS Systems Manager Automation Runbook Reference"
[7]: https://learn.microsoft.com/en-us/azure/automation/manage-runbooks "Microsoft Learn — Manage runbooks in Azure Automation"
---
**来源**：Manus AI《Agent Runbook 实用指南（v1.0）》，本仓库存档为规范参考。
docs/archive/lan-core-switch-upgrade-plan.md
+156
View File
@@ -0,0 +1,156 @@
# LAN 核心交换机升级计划（保留 ER-X）
**状态：** SE5420 **已采购**（2026-08-09）。**实施与验证以 [lan-se5420-deployment-guide.md](../lan-se5420-deployment-guide.md) 为准**；
本文为历史规划参考，**不得作为现场执行步骤**；所有实际操作均以部署指南为准。
**锁定硬件：** TP-Link **`TL-SE5420`**（16 × 2.5GbE RJ45 + 4 × 10GbE SFP+）。
**目标：** SE5420 承接全部 LAN 物理接入与二层转发；ER-X 继续承担公网、NAT、防火墙、
LAN66/LAN55 网关与 DHCP。
**拓扑与流量的详细说明**（职责、逻辑网、流量路径、Wi-Fi 分工、验收边界）见：
[lan-erx-se5420-network.md](../lan-erx-se5420-network.md)。
SE5420 官方资料：静态功耗 8 W、最大功耗 32 W；VLAN、LACP、STP/RSTP/MSTP、ACL、
CLI/SNMP、配置导入导出与固件下载。无 PoE——AP 使用本地取电 + 普通网线。
## 已确认边界（摘要）
| 项 | 结论 |
|---|---|
| 硬目标 | 同 VLAN 2.5G；SFP+ 先空槽 |
| 核心角色 | 纯 L2；不开 L3 / DHCP Server/Relay / NAT |
| 网关 | 默认一律 ER-X `.254`；升级专用 SSID（后续）才走 `gfw` `.1` |
| 本次 Done | 阶段 0–3；VLAN10 / 客人 SSID / 升级 SSID 另立项目 |
| 切换 | 30–60 分钟维护窗；旧交换迁完后闲置 |
| 首批 2.5G | NAS + 主力 PC（或 PVE） |
| 管理 | 先本地 HTTPS/SSH；云以后再说 |
### 保留的 ER-X 职责
| 项目 | 迁移后职责 |
|---|---|
| PPPoE / WAN、NAT、端口转发、WAN 防火墙 | ER-X，不变 |
| LAN66 (`192.168.66.0/24`) 默认网关与 DHCP | ER-X `eth0`，不变 |
| LAN55 (`192.168.55.0/24`) 默认网关与 DHCP | ER-X `switch0`，不变 |
| LAN66 ↔ LAN55 三层转发 | ER-X，不变 |
| 升级专用 Wi-Fi 网关（后续） | `gfw` VM，不是 ER-X 或核心交换机 |
ER-X 与核心之间使用两条**独立无标签 access**（LAN66 + LAN55），不向 ER-X 送
VLAN tag。
### 核心交换机职责
- 所有有线设备、AP 与 PVE 的物理接入；
- VLAN66、VLAN55 的二层转发；
- 为日后 U6 Lite 与 PVE 预留 VLAN10 trunk（本次不启用业务）；
- 同 VLAN 的 1G/2.5G 转发；
- SFP+ 预留未来 10G（DAC/AOC/光；不用 10GBASE-T 作默认）。
## 目标拓扑（简图）
```text
Internet
|
ER-X / PPPoE
+-------+--------+
| |
eth0, LAN66 switch0 port, LAN55
access access
| |
+-------+--------+
|
TL-SE5420 核心（纯 L2）
| | |
PVE / gfw U6 Lite LAN66/LAN55 access
（日后 trunk） （日后 trunk） NAS, PC, dns, ubnt, AC-Lite …
```
完整端口表、流量路径与 Wi-Fi 分工见
[lan-erx-se5420-network.md](../lan-erx-se5420-network.md)。
## VLAN 与端口设计
| VLAN / 逻辑网络 | 核心配置 | 网关 / DHCP | 用途 |
|---|---|---|---|
| 66 | access；PVE/U6 日后 trunk 的 native | ER-X `eth0` / `.254` | 主 LAN、管理 |
| 55 | access | ER-X `switch0` / `.254` | LAN55、AC-Lite |
| 10（后续） | 仅 PVE 与 U6 trunk 上 tagged | `gfw` | 升级专用 SSID |
| 管理 | LAN66 管理地址；不新建 VLAN | reservation / 静态 | SE5420 管理面 |
管理地址分配前先查 ER-X DHCP/reservation；禁用不需要的 HTTP/Telnet；云管延后；
保留 HTTPS/SSH 与离线配置备份（备份不进本仓库）。
### 初始端口分配
| 预留 | 对端 | 模式 |
|---|---|---|
| 铜口 1 | ER-X `eth0` | access VLAN66 |
| 铜口 2 | ER-X `switch0` 成员口 | access VLAN55 |
| 铜口 3 | PVE（`gfw`） | 现 access 66；日后 trunk native66+tag10 |
| 铜口 4 | U6 Lite | 同上；本地取电 |
| 铜口 5 | UAP-AC-Lite | access VLAN55；本地取电 |
| 其余铜口 | NAS、PC、`dns`、`ubnt`… | 默认 access VLAN66 |
| SFP+ 1–4 | 未来 | 空槽 |
## 分阶段实施与验收
### 阶段 0：采购前核验
1. 确认 SE5420 revision、保修、手册、固件页。
2. 确认 VLAN trunk、RSTP/MSTP、LACP、镜像、配置导出、错误计数。
3. SFP+ 模块本次不买；有对端后再选 DAC/AOC/光。
4. 盘点线缆与对端（LAN66/55、PVE、两台 AP）；确认关键 2.5G 链路可协商。
### 阶段 1：离线初始化核心
1. 仅电源 + 隔离管理本：管理 IP、强密码、时区、NTP、HTTPS/SSH；**关闭 L3/DHCP**。
2. 导出初始配置（离线保存，不进仓库）。
3. 建立 VLAN66/55/10 与端口模板；VLAN10 不接生产。
4. 开启 RSTP/MSTP；不制造物理环路。
### 阶段 2：维护窗迁移 LAN66
1. 使用约定维护窗（约 30–60 分钟）；保留原接线作回滚。
2. 先接铜口 1 ↔ ER-X `eth0`；验证管理地址、`.254`、DNS `.36`、互联网。
3. 逐台迁到 VLAN66 access；每台确认地址/DNS/路由/业务。
4. 最后迁 `ubnt`、`dns`、NAS/PC；禁止无意双上行。
### 阶段 3：迁移 LAN55
1. 接铜口 2 ↔ ER-X `switch0` 成员口。
2. 测试设备获 `192.168.55.x`、网关 `.254`、可达 DNS。
3. AC-Lite → 铜口 5；确认 `.55.5` 与 Inform Connected。
4. 旧交换下电闲置。
### 阶段 4：VLAN10 升级专用 Wi-Fi（独立项目）
不与本次 Done 捆绑。仅 U6；网关 `gfw`；详见
[lan-erx-se5420-network.md](../lan-erx-se5420-network.md) 第 6.5 / 8 节与
[unifi-network.md](../unifi-network.md)。
## 性能预期与不变瓶颈
- 同 VLAN、两端在核心上的 2.5G：可测 2.5G 级二层。
- 上网与 LAN66↔LAN55：仍经 ER-X 1G 路径。
- 空 SFP+ 不使网络「变成 10G」。
## 验收清单
- 管理面、口令、离线备份；
- 端口速率与错误计数；
- LAN66/55 的 DHCP、网关、DNS、互联网与关键本地服务；
- 两台 AP Connected；Inform 仍为 `http://192.168.66.46:9080/inform`；
- 无无意环路；旧交换已闲置；
- （建议）两台 2.5G 终端同 VLAN `iperf3`。
## 回滚
验证失败则停迁、恢复原接线；不改 ER-X WAN/DHCP/SSH。VLAN10 失败只撤新 SSID。
## 参考
- [ER-X + SE5420 网络与拓扑说明](../lan-erx-se5420-network.md)
- [LAN 概览](../lan-overview.md)
- [ER-X 配置记录](../edgerouter-x-configuration.md)
- [UniFi 网络](../unifi-network.md)
- [`gfw`](../../hosts/gfw.windy.lan.md)
- [TL-SE5420 官方规格](https://www.tp-link.com.cn/product_2899.html?v=specification)
docs/archive/lan-rb5009-upgrade.md
+397
View File
@@ -0,0 +1,397 @@
# ER-X → RB5009 网关升级：网络形态与实施计划
**状态：** 规划文档（未采购、未接线、未改生产配置）。
**重要变更（2026-08-09）：** **SE5420 已采购**，网络升级改为「保留 ER-X + SE5420 核心」路径——
实施与验证以 [lan-se5420-deployment-guide.md](../lan-se5420-deployment-guide.md) 为准。
本文保留为「ER-X 网关未来替换为 RB5009」的备选方案；其中 PVE 透传调研与 VLAN10 实现方法仍适用。
---
## 1. 一句话架构
```text
公网 ← RB5009（主网关：PPPoE / NAT / 防火墙 / DHCP / IPv6 / VLAN 66+55 三层）
↑ 全部终端 / AP / PVE 直连其 8×1G 端口
（SFP+ 空槽，为未来 10G 核心预留）
```
- **RB5009** 兼任路由与 LAN 二层交换：所有接入设备直插 RB5009 端口。
- 客户端默认网关仍是 **`.254`**（RB5009 沿用 ER-X 地址，客户端零感知）。
- **`gfw`** 仍为旁路由（默认网关 `.254`）；OpenClash 行为不变。
- **ER-X 升级后下电闲置，作为已配置的备件保存**（回滚路径）。
- 2.5G/10G 同 VLAN 交换目标**放弃**（无 SE5420）；LAN 二层为 1G。
---
## 2. 已确认的设计决策
| 决策 | 结论 |
|---|---|
| 角色 | RB5009 单机：路由 + LAN 交换 + 双 VLAN 三层 |
| WAN | **PPPoE**，走 **`ether1`（2.5G 铜口接 ONT/光猫）**，MTU 1492 |
| LAN 模型 | **单 bridge + VLAN 过滤**：VLAN 66（多数端口）+ VLAN 55；VLAN 10 预留 |
| 网关地址 | **沿用 `192.168.66.254` / `192.168.55.254`**；重编址另立项目 |
| IPv6 | **保留对等**：PPPoE 上 DHCPv6-PD `/60` + 双 LAN SLAAC `/64` + IPv6 防火墙 |
| 端口转发 | 4 条 **原样迁入**（hass / transmission / ssh / openvpn）+ hairpin NAT |
| LAN55 成员 | **保持现状**（AC-Lite、Aqara 及原 LAN55 设备）不迁到 VLAN66 |
| 管理面 | SSH **仅密钥**（`zhiqiang`）；禁用默认 `admin`；**禁 Winbox/API/WebFig** 或仅限 LAN |
| 迁移方式 | 台面预配置（临时 `.253`）→ 维护窗（30–60 分钟）→ 验证 → ER-X 留作备件 |
| 固件/备份 | 当前稳定 RouterOS 7.x；上线前 `.backup` + 文本导出存离线 |
| 时区/NTP | `Asia/Shanghai` + 现有 NTP 服务器 |
| 安全 | PPPoE 口令、SSH 私钥、`zhiqiang` 口令**只存设备上**，不落本仓库 |
---
## 3. 升级后的网络形态（拓扑图）
### 3.1 目标物理拓扑（升级完成后）
```text
Internet
│ PPPoE (ether1 2.5G, MTU 1492, IPv6 PD /60)
▼
┌──────────────────────────────────────────────┐
│ RB5009 (gw) RouterOS 7.x │
│ ether1 = WAN (PPPoE) │
│ bridge + vlan-filtering=yes │
│ vlan66 = 192.168.66.254/24 (pvid 66) │
│ vlan55 = 192.168.55.254/24 (pvid 55) │
│ SFP+ = 空槽（未来 10G） │
│ SSH-only 管理（仅 LAN） │
└─────┬─────────┬──────────┬──────────┬────────┘
│ pvid66 │ pvid66 │ pvid66 │ pvid55
│ │ │ │
gfw (.1) dns (.36) ubnt (.46) UAP-AC-Lite (.55.5)
PVE (.26) NAS/PC… U6 Lite Aqara (.55.248)
(.66.6)
```
端口角色以面板为准；下表是建议预留：
| RB5009 端口 | 对端 | 模式 |
|---|---|---|
| `ether1` | ONT/光猫 | WAN，PPPoE |
| `ether2`–`ether8` | PVE/gfw、dns、ubnt、U6 Lite、NAS、PC、杂项 | access，pvid 66 |
| `ether9` | 原 LAN55 成员（AC-Lite、Aqara…） | access，pvid 55 |
| SFP+ `sfp-sfpplus1` | 未来 10G 核心 | 空槽 |
> **禁止双上行：** 任一设备不得同时接旧 ER-X 与 RB5009（环路 / 双默认网关）。
### 3.2 逻辑网络
| VLAN | 子网 | 网关 / DHCP | 形态 | 成员 |
|---|---|---|---|---|
| **66** | `192.168.66.0/24` | RB5009 `vlan66` `.254` | 多数端口 access | gfw、dns、ubnt、U6、PVE、NAS、PC… |
| **55** | `192.168.55.0/24` | RB5009 `vlan55` `.254` | `ether9` access | AC-Lite、Aqara…（原 LAN55 全量） |
| 10（预留） | `192.168.10.0/24` | 未来（`gfw`） | 暂不配业务 | 升级专用 SSID（后续项目） |
- 客户端 DNS：DHCP 仍下发 **`192.168.66.36`**（AdGuard Home）。
- UniFi Inform 仍为 `http://192.168.66.46:9080/inform`。
- LAN66 ↔ LAN55 互通由 RB5009 三层转发（沿用现网默认可达语义，防火墙不设隔离边界）。
### 3.3 流量怎么走
```text
同 VLAN（NAS ↔ PC）： 客户端 → RB5009 端口 → bridge（二层交换，1G）
跨 VLAN（66 ↔ 55）： 客户端 → RB5009 路由（vlan66 ↔ vlan55，1G）
上网： 客户端 → RB5009 → PPPoE → Internet（限速 = 线路；RB5009 fasttrack 去掉 ER-X ~900M 天花板）
旁路由： 默认网关仍 `.254`；显式代理走 gfw（不变）
未来 VLAN10： U6 trunk → RB5009 →（转发 VLAN10）→ gfw（后续项目）
```
### 3.4 性能预期（诚实边界）
| 场景 | 预期 |
|---|---|
| WAN / PPPoE | 线路速率以内；若线路 >1G，RB5009 fasttrack 可跑满（ER-X 受 900M 限制） |
| 同 VLAN 交换 | **1G**（无 SE5420；RB5009 8×1G） |
| 跨 VLAN | 1G 级三层 |
| SFP+ 空槽 | 不等于已是 10G |
---
## 4. 分阶段实施计划
### 阶段 0：采购前核验
1. 确认 RB5009 revision、保修、零售渠道、RouterOS 当前稳定版本号（建议 7.x 最新 stable）。
2. 确认硬件：1× 2.5G PoE-in（ether1）、8× 1G、1× SFP+、1GB RAM。SFP+ 模块本次不买。
3. 盘点线缆与对端：ONT ↔ ether1；原 LAN55 设备清单（AC-Lite、Aqara…）及原 ER-X `switch0` 接线。
### 阶段 1：离线初始化（台面）
1. 仅电源 + 隔离管理本。设置身份、时区 `Asia/Shanghai`、NTP。
2. 建 `zhiqiang` 管理用户（**密钥登录，禁密码**）；**删除/禁用默认 `admin`**。
3. 建 bridge + VLAN 66/55 + 端口模板（`ether2–8` pvid66，`ether9` pvid55）；**临时地址 `.253`**（不与 ER-X `.254` 冲突）。
4. 配 WAN PPPoE（ether1）、默认路由、NAT masquerade、4 条端口转发 + hairpin、防火墙（input/forward）、MSS clamp、IPv6 PD + SLAAC + IPv6 防火墙。
5. 配 DHCP 池 `.38–.243`、24h 租约、DNS `.36`、UniFi Inform 选项、**静态映射全量照搬**。
6. 管理面收口：**禁 Winbox（8291）/ API（8728）/ WebFig（80/443）**；SSH 仅限 LAN66/55。
7. `system backup save` + `/export`，导出到离线存储（**不落仓库**）。
**参考 RouterOS 配置骨架**（口令/密钥用占位符；落地前逐一核对）：
```text
# 身份 / 时区 / NTP
/system identity set name=gw
/system clock set time-zone-name=Asia/Shanghai
# WAN
/interface ethernet set ether1 name=wan
/interface pppoe-client add name=pppoe0 interface=wan user=<PPPoE_USER> \
password=<PPPoE_PASS> add-default-route=yes use-peer-dns=no \
mtu=1492 mru=1492
# bridge + VLAN
/interface bridge add name=bridge66 vlan-filtering=yes
/interface bridge port add bridge=bridge66 interface=ether2 pvid=66
... # ether3..ether8 同 pvid 66
/interface bridge port add bridge=bridge66 interface=ether9 pvid=55
/interface bridge vlan add bridge=bridge66 vlan-ids=66 tagged=bridge66
/interface bridge vlan add bridge=bridge66 vlan-ids=55 tagged=bridge66
/interface vlan add name=vlan66 interface=bridge66 vlan-id=66
/interface vlan add name=vlan55 interface=bridge66 vlan-id=55
# 地址（台面先用 .253，维护窗切 .254）
/ip address add address=192.168.66.254/24 interface=vlan66
/ip address add address=192.168.55.254/24 interface=vlan55
# NAT masquerade + 端口转发 + hairpin
/ip firewall nat add chain=srcnat out-interface=pppoe0 action=masquerade
/ip firewall nat add chain=dstnat in-interface=pppoe0 protocol=tcp dst-port=8123 \
action=dst-nat to-addresses=192.168.55.11 to-ports=8123
/ip firewall nat add chain=dstnat in-interface=pppoe0 protocol=tcp dst-port=51413 \
action=dst-nat to-addresses=192.168.66.51 to-ports=51413
/ip firewall nat add chain=dstnat in-interface=pppoe0 protocol=udp dst-port=51413 \
action=dst-nat to-addresses=192.168.66.51 to-ports=51413
/ip firewall nat add chain=dstnat in-interface=pppoe0 protocol=tcp dst-port=5822 \
action=dst-nat to-addresses=192.168.66.36 to-ports=22
/ip firewall nat add chain=dstnat in-interface=pppoe0 protocol=udp dst-port=5822 \
action=dst-nat to-addresses=192.168.66.36 to-ports=22
/ip firewall nat add chain=dstnat in-interface=pppoe0 protocol=tcp dst-port=1194 \
action=dst-nat to-addresses=192.168.66.32 to-ports=1194
/ip firewall nat add chain=dstnat in-interface=pppoe0 protocol=udp dst-port=1194 \
action=dst-nat to-addresses=192.168.66.32 to-ports=1194
/ip firewall nat add chain=srcnat connection-nat-state=dstnat action=masquerade # hairpin
# 防火墙（input / forward），顺序很重要：SSH 放行必须早于默认 drop
/ip firewall filter add chain=input connection-state=established,related action=accept
/ip firewall filter add chain=input connection-state=invalid action=drop
/ip firewall filter add chain=input protocol=icmp action=accept
/ip firewall filter add chain=input in-interface=pppoe0 action=drop comment="drop WAN in"
/ip firewall filter add chain=input protocol=tcp dst-port=22 \
src-address=192.168.66.0/24,192.168.55.0/24 action=accept comment="mgmt SSH"
/ip firewall filter add chain=input action=drop comment="drop other input"
/ip firewall filter add chain=forward connection-state=established,related action=fasttrack-connection \
hw-offload=yes
/ip firewall filter add chain=forward connection-state=established,related action=accept
/ip firewall filter add chain=forward connection-state=invalid action=drop
/ip firewall filter add chain=forward in-interface=pppoe0 action=drop comment="drop WAN fwd"
/ip firewall filter add chain=forward action=accept comment="accept LAN fwd"
# MSS clamp（PPPoE MTU 1492 → 1452；ER-X 旧值 1412 偏小，验证后按标准值收敛）
/ip firewall mangle add chain=forward protocol=tcp tcp-flags=syn \
tcp-mss=1400-65535 action=change-mss new-mss=1452 passthrough=yes
# IPv6（PD /60 + SLAAC /64）
/ipv6 dhcp-client add interface=pppoe0 request=prefix pool-name=pd6 \
pool-prefix-length=60 add-default-route=yes
/ipv6 address add from-pool=pd6 interface=vlan66 address=::1 adverts=yes
/ipv6 address add from-pool=pd6 interface=vlan55 address=::1 adverts=yes
# /ipv6 firewall filter 参照 IPv4：established/related accept、invalid drop、
# icmpv6 accept、pppoe0 in drop、默认 drop，forward 同构
# DHCP（池 / DNS / Inform / 静态映射全量照搬 ER-X）
/ip pool add name=pool66 ranges=192.168.66.38-192.168.66.243
/ip pool add name=pool55 ranges=192.168.55.38-192.168.55.243
/ip dhcp-server add name=dhcp66 interface=vlan66 address-pool=pool66 lease-time=1d
/ip dhcp-server add name=dhcp55 interface=vlan55 address-pool=pool55 lease-time=1d
/ip dhcp-server network add address=192.168.66.0/24 gateway=192.168.66.254 \
dns-server=192.168.66.36
/ip dhcp-server network add address=192.168.55.0/24 gateway=192.168.55.254 \
dns-server=192.168.66.36
# 静态映射：从 ER-X 导出后逐条 /ip dhcp-server lease add ...
# UniFi Inform：DHCP option 43（hex 编码为 http://192.168.66.46:9080/inform），
# 或依赖已 adopt AP 的 set-inform；与现网 ER-X 行为保持一致。
```
### 阶段 2：上台预验证（ER-X 仍在线）
1. 将 RB5009 `ether2` 接入现有 LAN66 网段（管理本同网段），SSH 登录 `.253`。
2. 全配置复查：VLAN 表、防火墙规则顺序（SSH 在 drop 前）、NAT、路由、IPv6。
3. **暂不启用 RA/DHCP**（避免与 ER-X 冲突）。预验证 `.253` 可达、SSH 密钥生效、`zhiqiang` 无密码。
4. 确认 ER-X 当前配置**已备份并保存**（作为回滚依据；`show configuration commands` 过滤敏感行）。
### 阶段 3：维护窗切换（约 30–60 分钟）
1. 变更 RB5009 `vlan66`/`vlan55` 地址 `.253 → .254`。
2. **下电 ER-X**（保留原接线与配置，不作任何改动）。
3. ONT 线从 ER-X `eth4` 移到 RB5009 `ether1`。
4. 观察 PPPoE 拨号：`/interface pppoe-client monitor pppoe0` 直至 `status=established`；确认 WAN IP 与默认路由。
5. 验证清单（见第 5 节），全绿才算完成。
### 阶段 4：上线收口
1. 再确认管理面：禁 Winbox/API/WebFig、SSH 仅密钥、默认 `admin` 已除。
2. 更新固件/补丁至已核定的稳定版；重新导出备份（`.backup` + 文本）存离线。
3. ER-X 下电收纳为**已配置备件**，把其接线与角色记录到 `hosts/gw.md` 备份节。
### 阶段 5（后续，另立项目）
**时序确认：** VLAN10 升级专用 Wi-Fi 是 RB5009 上线**稳定之后**的独立项目，不并入本次维护窗。
- 4 条端口转发是否仍需的审计。
- 网关重编址（`.254 → 其它`）决策。
- **VLAN10 升级专用 SSID → `gfw`（可行性审查，2026-08-09）**。
- 迁移后同步本仓库事实文档：`hosts/gw.md`、`docs/lan-overview.md`、`inventory/hosts.md`、`AGENTS.md` 快速地图。
### 阶段 5 附：VLAN10 可行性审查
**结论：** 换 RB5009 后**物理上可行**，但 RB5009 只解决「交换机侧」路径；PVE 宿主机到 `gfw` 虚拟机这一段（此前判定为不可行的关键缺口）仍必须单独打通。
**为什么当前不能在 AP 上启用 VLAN10：**
U6 接的是 ER-X `eth0` 的普通 untagged LAN66 路径，尚无已验证的 VLAN10 端到端二层通道。给 SSID 选择 VLAN10 后，客户端不会获得可由 gfw 服务的预期 VLAN10 网络；帧究竟被丢弃、被设备错误处理，还是 SSID 实际没有打 tag，必须以 AP/交换机/gfw 抓包和配置核验判断。**不得**将“tagged 帧必然自动去标签并泄漏到 LAN66”作为实施前提。
**RB5009 下实现需要 3 个前提：**
1. **RB5009 bridge 增加 VLAN10 转发：**
`/interface bridge vlan add bridge=bridge66 vlan-ids=10 tagged=<U6口>,<PVE口>`
只在这两个口 tagged。**不要**在 RB5009 上给 VLAN10 配 IP / DHCP（gfw 才是网关与唯一 DHCP）。
2. **PVE 宿主机路径（必须做，RB5009 解决不了这一段）：**
PVE 物理上联口透传 tagged VLAN10；`gfw` 虚拟机有一块 VLAN10 可达的网卡
（如 vmbr0 开 `vlan_filtering` + 给 gfw 加第二块 pvid 10 的 NIC，或 VM 内 `eth0.10`）。
这是此前「无法实现」的同一处缺口，需在 PVE/vSwitch 层单独验证。
3. **`gfw` 侧：** VLAN10 网卡 `192.168.10.1/24` + DHCP（`192.168.10.0/24`）+ 出 66 口
masquerade。RB5009 无需到 `192.168.10.0/24` 的路由（gfw SNAT 后源地址即 66 网段）。
**两个注意点：**
- **单 DHCP 原则：** VLAN10 上唯一 DHCP 是 gfw；RB5009 不得在 VLAN10 提供 DHCP。
- **设计确认：** 升级 SSID 客户端走 gfw 网关后，DNS 为 gfw 的 dnsmasq→clash（7874），
**不是** AdGuard `.36`——这是「被代理网络」的预期行为，需接受。
### 阶段 5 附：PVE 上 VLAN10 透传实现（调研 2026-08-09）
官方 wiki + 多个社区案例支持两种模型，核心原则是 **「一层只拥有一个 tag」**——要么 PVE 拥有
access VLAN，要么 OpenWrt 拥有 trunk，**不能在同一张 NIC 上两层都做**。
**方案 A（推荐）：PVE 拥有 access VLAN，gfw 加第二块 virtio 网卡**
1. `vmbr0` 开 vlan-aware（`/etc/network/interfaces`）：
```text
auto vmbr0
iface vmbr0 inet static
address 192.168.66.26/24
gateway 192.168.66.254
bridge-ports eno1
bridge-stp off
bridge-fd 0
bridge-vlan-aware yes
bridge-vids 10 # 至少含 10；常见默认 2-4094
```
2. gfw VM 添加 `net1: virtio,bridge=vmbr0,tag=10`。VM 内该网卡是**无标记**接口
（已落在 VLAN10 广播域），**不要再建同名 8021q 子接口**。
3. 现有 `eth0`（native/untagged = VLAN66）不动，gfw 原有角色不变。
4. PVE 物理上联口（PVE→RB5009）改为 **trunk：native 66 + tagged 10**。
5. OpenWrt 内：新网卡 `192.168.10.1/24` + DHCP（`192.168.10.0/24`）+ 独立 firewall zone→wan masq。
**方案 B：OpenWrt 拥有 trunk（单 NIC 多 VLAN）**
- `vmbr0` vlan-aware；VM NIC **不加 tag**；trunk 原样进 VM；OpenWrt 内建 `8021q` 设备
（`eth0.10`，x86/virtio 用 `option type '8021q'`，不要套用 DSA 教程）。物理上联 trunk。
- 更灵活（一块网卡多 VLAN），是 router VM 的常见做法，但需要 OpenWrt 8021q 配置，
且方案 A 对现有单网卡 gfw 改动更小。
**RB5009 侧配套（U6 口 + PVE 口都做成 trunk）：**
```text
/interface bridge port add bridge=bridge66 interface=<U6口> pvid=66
/interface bridge port add bridge=bridge66 interface=<PVE口> pvid=66
/interface bridge vlan add bridge=bridge66 vlan-ids=66 tagged=bridge66 untagged=<U6口>,<PVE口>,<其余66口>
/interface bridge vlan add bridge=bridge66 vlan-ids=55 tagged=bridge66 untagged=<ether9>
/interface bridge vlan add bridge=bridge66 vlan-ids=10 tagged=<U6口>,<PVE口>
```
VLAN10 在 RB5009 上**纯二层桥接**（U6 ↔ PVE），三层由 gfw 承担；RB5009 无 VLAN10 IP/DHCP。
**常见坑（社区高复发）：**
- **双标签：** PVE 设了 `tag=10` 又在 OpenWrt 里建 `eth1.10` → 一帧被两层改两次。
- **native VLAN 不一致：** trunk 上无标记帧被两端当成不同 VLAN → DHCP 消失 / 拿到错网段
（正是你之前在 AP 上打 VLAN10 坏 66 网的同类故障）。
- **bridge 未 vlan-aware：** tagged 帧进 host 后在 bridge 过滤层消失。
**诊断命令：**
```bash
# PVE host
bridge vlan show
ip -br link
tcpdump -eni <上联口> # 帧是否到物理口
tcpdump -eni vmtapXXXXXX # 帧是否到 VM tap
# OpenWrt guest
ip -d link show
logread -e netifd
```
**参考案例：**
- PVE 官方 wiki — Network Configuration / VLAN 802.1Q（三种模式 + vlan-aware bridge）：
<https://pve.proxmox.com/wiki/Network_Configuration>
- 「OpenWrt VM on Proxmox」设计（trunk vs access 谁拥有 tag、双标签坑）：
<https://phb-crystal-ball.org/run-openwrt-in-proxmox/>
- PVE 论坛「Tagged and Untagged VLAN」（`bridge-vlan-aware yes` + `bridge-vids` 解法）：
<https://forum.proxmox.com/threads/tagged-and-untagged-vlan-configuration.144421/>
- OpenWrt 论坛 guest WiFi tagged VLAN 案例（`vmbr0.3`→VM 第三网卡；guest 拿到错误网段的
同型故障，最终归因在 PVE/host 侧）：<https://forum.openwrt.org/t/continued-x86-openwrt-proxmox-vlan-issues/182623>
> **PVE host 改动风险：** 给 `vmbr0` 开 vlan-aware 是对宿主机网络栈的修改，有管理面断连风险；
> 需在维护窗内用控制台/独立带外通道进行，先 `ifreload -a`（PVE7+ 的 ifupdown2 支持热应用），
> 保留原配置作回滚。
---
## 5. 验收清单（「网络算正常」的样子）
1. 管理面：`zhiqiang` 密钥 SSH 可从 LAN66/55 登录；默认 `admin` 禁用；Winbox/API 不可达；`.254` 管理可达。
2. VLAN：客户端取得正确网段（`.66.x` / `.55.x`），默认网关 `.254`，DNS `.36` 可用。
3. 互联网：PPPoE 已建立；IPv4 外网通；端口转发逐条从公网验证（hass 8123、transmission 51413、ssh 5822→.36:22、openvpn 1194）。
4. IPv6：两 VLAN 拿到 SLAAC `/64`，默认路由存在，外部 IPv6 可达；IPv6 防火墙未阻断必要 ICMPv6/DHCPv6。
5. 本地服务：跨 VLAN（`.55.x` ↔ `.66.x`）互通；AdGuard Home、UniFi 控制器、`gfw` 旁路由行为与升级前一致。
6. UniFi：U6 Lite（`.66.6`）与 UAP-AC-Lite（`.55.5`）在控制器显示 **Connected**；Inform 未变 `:9080`。
7. 无环路、无双默认网关；端口协商与错误计数正常。
8. 备份（`.backup` + 文本导出）已离线保存；ER-X 已下电收纳。
---
## 6. 回滚语义
任一阶段失败：**停手**。
- **维护窗内失败（PPPoE 未起 / 客户端不通 / 防火墙锁死）：**
1. 下电 RB5009。
2. ONT 线插回 ER-X `eth4`。
3. 给 ER-X 上电 → 服务在数分钟内恢复。
4. 不要在故障中改 ER-X 的 WAN、DHCP、网关地址或 SSH 策略。
- **维护窗成功后** ER-X 只是备件；后续 VLAN10 失败只撤 SSID/VLAN 绑定，主 SSID 与 `.254` 路径不动。
---
## 7. 安全与记录
- **本仓库永不记录**：PPPoE 口令、`zhiqiang` 口令、SSH 私钥、RouterOS 备份（含口令/密钥）。
- 每次实质性变更（切换、回滚、加固）完成后，在 Linear **`vps` 项目**记录 scope / action / verification / 遗留 follow-up（本次先不建 issue，待执行时补）。
- SSH 与访问策略变更遵循仓库「SSH access safety」流程：ER-X 会话保持为回滚路径，新密钥登录验证成功前不关闭旧通道。
---
## 8. 参考
- 现网地图：[lan-overview.md](../lan-overview.md)
- ER-X 现状：[edgerouter-x-configuration.md](../edgerouter-x-configuration.md)、[hosts/gw.md](../../hosts/gw.md)
- UniFi：[unifi-network.md](../unifi-network.md)、[hosts/ubnt.md](../../hosts/ubnt.md)
- `gfw`：[hosts/gfw.windy.lan.md](../../hosts/gfw.windy.lan.md)
- 作废方案（**不再实施**）：[lan-erx-se5420-network.md](../lan-erx-se5420-network.md)、[lan-core-switch-upgrade-plan.md](lan-core-switch-upgrade-plan.md)
- MikroTik RB5009 官方：<https://mikrotik.com/product/rb5009ug_s_in>、RouterOS v7 手册
docs/archive/se5420-review-claim-verification-2026-08.md
+74
View File
@@ -0,0 +1,74 @@
# SE5420 实施评审主张核实（2026-08-10）
> **核对基准（历史快照）：** 本文于 2026-08-10 针对 [lan-se5420-deployment-guide.md](../lan-se5420-deployment-guide.md) 的**评审前版本**（`35577d0`）撰写。该指南自 `ffb37a9`（"finalize SE5420 deployment guide per review"）起已按本评审修订，当前 `origin/main` 章节已重组：旧 §3.3 → §4.3、旧 §6（gfw）→ §11、旧 §7（SSID）→ §12、旧 §9（验收/IPv6）→ §13 + §11.4。文末「当前指南处理情况」列出各主张的现行状态；实施以部署指南现行为准。
**范围。** 本文核对对 `lan-se5420-deployment-guide.md` 的评审意见。结论分为
“已证实”（规范/一手资料直接支持）、“基本证实”（架构推论成立但仍须读取现场配置）和
“需现场核实”（不能仅由文档或产品手册断言）。这不是实施变更，也不替代维护窗前的
`uci show firewall`、交换机当前 VLAN 表和 PVE bridge 配置检查。
## 核实结论
| 评审主张 | 结论 | 依据与限定 |
| --- | --- | --- |
| `firewall.ubunt_upg.masq=1` 是错误方向，应在实际出站的 `wan` zone 做 IPv4 NAT | **已证实** | OpenWrt 明确规定 masquerade 是**按出站 zone/interface**控制；`masq` 通常在 `wan`。因此，对 `ubunt_upg → wan` 流量把 `masq` 放在源 zone 不是该需求的正确 zone 语义。若 `wan` 已 masq，不应重复开启；也可用 `masq_src` 只限 `192.168.10.0/24`。见 [OpenWrt firewall configuration](https://openwrt.org/docs/guide-user/firewall/firewall_configuration) 和 [fw4 masq 测试](https://lxr.openwrt.org/source/firewall4/tests/02_zones/02_masq)。 |
| `ubunt_upg → wan` 允许所有经 gfw `wan` 可路由的目的地，不等于只上互联网 | **已证实** | `forwarding` 的 `src`/`dest` 是 zone-to-zone 单向许可，未按“Internet”语义区分目标 IP；规则可用 `dest_ip` 限制。故若 gfw 的 `wan` 接在 LAN66 且 ER-X 可路由 LAN55，评审所列 LAN66/LAN55 风险成立。最终可达网段仍须以 gfw 路由表、ER-X 路由/防火墙现场检查为准。见 [OpenWrt forwarding/rule 参考](https://openwrt.org/docs/guide-user/firewall/firewall_configuration)。 |
| 不应把 `ubunt_upg.forward` 改为 `ACCEPT`；`forward_policy` 不是必要的标准 zone 选项；匿名 `uci add` 不可重复执行 | **基本证实** | OpenWrt zone 的标准项是 `forward`，forwarding 是独立 section，参考页未定义 `forward_policy`。单独的具名 forwarding 足以允许跨 zone 路径，因此保持 zone 内 `forward=REJECT` 是较小权限配置。匿名 section 每执行一次都会新增一节，这是 UCI 的操作语义；实施应先读现场配置并使用具名 section。 |
| VLAN10 必须有显式 IPv6 策略，否则可能绕过仅 IPv4 的 NAT/隔离 | **已证实** | fw4 将 `masq`（IPv4）和 `masq6`（IPv6）分开；forwarding 默认 family 是 `any`。仅写 IPv4 DHCP/NAT/地址规则不能表达 VLAN10 的 IPv6 RA、DHCPv6、路由和过滤策略。是否已经存在可用 IPv6 前缀、以及 OpenClash 是否接管 IPv6，必须现场验证。见 [OpenWrt firewall configuration](https://openwrt.org/docs/guide-user/firewall/firewall_configuration)。 |
| 管理 SVI + 默认路由与“不开 SVI/静态路由/一切 L3”矛盾 | **已证实** | 指南（历史版）§3.3 同时要求 VLAN66 `192.168.66.253/24` 与默认路由，又要求不开 SVI/静态路由。TL-SE5420 官方称其为三层交换机，支持静态路由、RIP、DHCP server/relay。准确目标应是：仅保留 VLAN66 管理 L3 interface/默认网关，不给 VLAN55/10 建 L3 interface，且禁用不需要的 L3 服务和跨 VLAN routing。见 [TL-SE5420 官方页](https://www.tp-link.com.cn/product_2899.html?v=specification) 与 [官方安装手册](https://service.tp-link.com.cn/download/202310/TL-SE5420%20V1.0%E5%AE%89%E8%A3%85%E6%89%8B%E5%86%8C%201.0.2.pdf)。 |
| 必须明确移除 VLAN1 成员，PVID 变更本身不等于 access-port VLAN membership | **已证实** | PVID/native VLAN 只处理进入端口的未标记帧；access/trunk 的允许 VLAN 列表是独立概念。指南（历史版）§3.3 只列 VLAN66/55 member 和 PVID，未写移除 VLAN1 或 ingress filtering。验收应检查 VLAN1 member、VLAN1 管理 IP、端口允许 VLAN 和 tagged-frame ingress policy。见 [Ubiquiti 对 native/tagged/access/trunk 的定义](https://help.ui.com/hc/en-us/articles/26136855808919-Switch-Port-VLAN-Assignment-Trunk-Access-Ports)（术语与 802.1Q 语义）以及 [Linux bridge VLAN 配置示例](https://www.kernel.org/doc/html/v5.19/networking/dsa/b53.html)（显式 `bridge vlan del ... vid 1`）。TL-SE5420 具体 GUI/CLI 行为仍以其固件手册核验。 |
| NAS 不应在未先完成双端 LACP 时同时接两口；LACP 不使单 TCP 流自动达到 5G | **基本证实** | 这是标准二层环路/聚合变更控制结论：没有已协商的 LAG 时，两条同 VLAN 并行链路会构成潜在环路；STP 只能作为保护而非实施方法。官方产品页列出 LACP 相关资料，但本次未取得 TL-SE5420/TrueNAS 对端的精确配置与当前 NAS 连接状态，故“必然环路/双 IP”不能在桌面审阅中断言。单连接吞吐受链路散列限制是 802.3ad 的常见实现特性，应以 NAS 与交换机的 hash policy 和 `iperf3` 实测验收。 |
| 非 VLAN-aware 的 PVE `vmbr0` 不提供 VLAN10 的端口级隔离 | **已证实** | PVE 将 bridge 描述为虚拟交换机；VLAN-aware mode 才能给 guest NIC 赋 VLAN tag，或显式 trunk。Linux 内核说明：`vlan_filtering=0` 时 bridge 不考虑 VLAN tag，且默认关闭；开启后才按 MAC **和 VLAN tag**转发及进行严格 VID 检查。因此“共享非 VLAN-aware bridge 可让可控 guest 主动消费 VLAN10，不能作为严格隔离边界”成立。不能仅凭该结论断言每个 guest 必定收到每个单播帧：未知单播/广播会泛洪，已学习的单播会按 FDB 转发。见 [PVE 网络配置](https://pve.proxmox.com/wiki/Network_Configuration) 和 [Linux bridge 文档](https://docs.kernel.org/networking/switchdev.html)。 |
| AP VLAN10 tagged frame 在一个普通 untagged LAN66 access path 上会“自动去 tag 并泄漏到 LAN66” | **不成立／需改写** | 802.1Q 的 native VLAN 是对**未标记**流量的 VLAN；tagged VLAN 需被显式允许于 trunk。因此通常的正确表述是：若上游不允许 VLAN10 tag，AP 到 VLAN10 网关/DHCP 的路径不存在，SSID 会成为不可用入口。实际设备的端口模式（包括是否错误地配置为 all/trunk、是否接受 tagged ingress）须现场查看，不能泛称必然去标签。见 [Ubiquiti VLAN 端口定义](https://help.ui.com/hc/en-us/articles/26136855808919-Switch-Port-VLAN-Assignment-Trunk-Access-Ports) 和 [Ubiquiti VLAN troubleshooting](https://help.ui.com/hc/en-us/articles/9592924981911-Virtual-Network-VLAN-Troubleshooting)。 |
| 仅保留 SSH 会话不是移动 PVE/ER-X 物理上联时的真正带外回滚路径；应全程保持 SE5420 Console | **已证实** | 这是直接的操作依赖判断：TCP SSH 的承载链路被拔除时会断，不能证明回滚可达。TL-SE5420 官方安装手册确认该机有 Type-C Console，且本仓库指南本身也把恢复出厂流程建立在 Console 上。故应在迁移前接通 Console、标注旧/新端口、逐根迁移并用 MAC 表与链路/错误计数验证。见 [官方安装手册](https://service.tp-link.com.cn/download/202310/TL-SE5420%20V1.0%E5%AE%89%E8%A3%85%E6%89%8B%E5%86%8C%201.0.2.pdf)。 |
| “所有设备均不得直连 ER-X”不是避免环路的必要条件 | **已证实** | 环路取决于同一 L2 广播域存在多条并行二层路径，不取决于是否还有一个独立终端直接接 ER-X。应禁止的是一个下级交换机/桥接主机同时形成平行路径。此项仍需以 ER-X switch0 VLAN/bridge 现场配置和实际接线图确认。 |
| 性能不应承诺全面 2.5G；同 VLAN 才可能在 SE5420 本地交换超 1G，跨 55/66 与 Internet 受 ER-X/宽带限制 | **已证实** | TL-SE5420 的 2.5G 端口仅提高经其本地二层转发的链路上限；跨子网必须由网关路由，Internet 另受 WAN/PPPoE 约束。产品页确认 16×2.5G + 4×10G SFP+，但 ER-X、NAS、PC、AP 的实际协商速率和 NIC/布线能力必须由 `ethtool`/端口状态及 `iperf3` 验证。见 [TL-SE5420 官方规格](https://www.tp-link.com.cn/product_2899.html?v=specification)。 |
## 已核对的文档内事实
现行指南的**历史版本**（`35577d0`）确实包含评审指出的关键文字：旧 §3.3 的管理 IP/默认路由与“不开 SVI/静态路由”；旧 §6 的 `ubunt_upg.masq`、`forward=ACCEPT`、`forward_policy`、匿名 forwarding；旧 §7 只验“不可达 LAN66”；旧 §9 对新增 VLAN10 写“IPv6 行为与升级前一致”。因此上述评审不是对未出现内容的假设。
但这些内容在 `ffb37a9` 起的修订中已被修正或重组：`ubunt_upg.masq` 与 `forward_policy` 已删除，gfw 防火墙改为 §11（§11.3 第 2 步明确“不要给 `ubunt_upg` zone 加 masq”）；VLAN10 IPv6 在 §11.4 显式写为“本阶段不提供”；SVI/L3 边界在 §4.3 第 16 步单列“L3 明确边界检查”。本文按历史快照保留评审结论，读者应以现行部署指南为准。
本仓库的 `hosts/gfw.windy.lan.md` 还记录 gfw 的 `eth0` 在 LAN66、`eth1` 在 LAN55，故 `ubunt_upg → wan` 的隔离结论应在执行前以当前 `ip route`、`uci show firewall`、`nft list ruleset` 复核，而不能从方案文字直接把规则写死。
## gfw 现场只读复核（2026-08-10）
已通过 `ssh -4 root@192.168.66.1` 仅读取配置和运行规则，未修改设备。该结果会改变
评审中两项“当前状态”的表述：
| 现场事实 | 对评审的影响 |
| --- | --- |
| `wan` zone 已有 `masq='1'`；现有配置另有具名 `ubunt_upg_nat`，运行时渲染为 `oifname "eth0"` 且只匹配 `ip saddr 192.168.10.0/24 masquerade`。 | “必须在 wan 开 masq”的**方向原则**正确，但“当前无 masq”不正确。现有显式 SNAT 已在实际出 `eth0` 时执行；计划中再将 `masq` 加到 `ubunt_upg` 仍是多余且方向错误。 |
| 当前放行是具名 `ubunt_upg_to_lan`，不是 `ubunt_upg→wan`；其运行链先拒绝 `192.168.66.0/24`，再允许到 `lan`。gfw 的 IPv4 default route 是 `192.168.66.254`。 | 计划新增 `ubunt_upg→wan` 会是与当前设计不同、过宽的改动。现有 LAN66 阻断规则在该链中先匹配；但对经 ER-X 可达的 LAN55/其他内网仍没有显式拒绝，故隔离评审的**剩余风险成立**。应以明确内网前缀 deny + 所需外网 allow 重写，而不是加 WAN forwarding。 |
| `ubunt_upg` DHCPv6 和 RA 都是 `disabled`；运行路由表仅有各接口的 IPv6 link-local route，没有 IPv6 default route；全局 IPv6 forwarding 是 `1`。 | 评审“VLAN10 未明确 IPv6 策略”的表述对计划文本仍成立，但“IPv6 可能立即绕过”的事实判断在当前状态**未获证实**：现有 RA/DHCPv6 已关闭且无 IPv6 默认路由。实施文档仍应把这项显式写为“IPv6 不提供”，并在启用前复查。 |
| 系统是 ImmortalWrt **25.12.0**，`/usr/bin/apk` 存在（apk-tools 3.0.5）。 | 评审中“ImmortalWrt 21.02.5 应使用 opkg”的版本判断错误/过时；在本机上 `apk add tcpdump` 是可用包管理器。仍应先检查软件包可用性，避免在维护文档中把两种命令并列为未经验证的替代方案。 |
这些命令输出未含凭据、令牌或私钥，故仅记录了安全相关的摘要；不将完整防火墙快照提交至仓库。
## 当前指南处理情况（2026-08-13 核对）
对 `origin/main`（`2fd354c`）逐项核对评审主张：
| 评审主张 | 现行状态 | 现行位置 |
| --- | --- | --- |
| `ubunt_upg.masq=1` 方向错误 | ✅ 已修复 | §11.3 第 2 步「不要给 `ubunt_upg` zone 加 masq」 |
| `ubunt_upg→wan` 不等于只上互联网 | ⚠️ 原则成立，指南已禁止新增宽泛 forwarding；LAN55/RFC1918 显式 deny 仍为待办 | §11.1b「待补缺口」、§11.3 |
| 勿改 `forward=ACCEPT`；无 `forward_policy`；匿名 uci 不可重复 | ✅ 已修复 | §11.3 第 1 步保持 REJECT；指南已无 `forward_policy` |
| VLAN10 须显式 IPv6 策略 | ✅ 已修复 | §11.4「本阶段不提供 VLAN10 IPv6」 |
| 管理 SVI + 默认路由 vs「不开一切 L3」矛盾 | ✅ 已消解 | §4.3 第 16 步「L3 明确边界检查」 |
| 须移除 VLAN1 成员；PVID≠membership | ✅ 指南已加强；现网仍偏离（W1N-54） | §4.3 第 9–12 步；VLAN1 不可删说明 |
| NAS 双口未 LACP 前勿并行 | ✅ 已体现 | §7 第 7 步「仅口 8，口 12 断开」 |
| 非 VLAN-aware PVE bridge 不能作隔离边界 | ✅ 已体现 | §9.2 要求 VLAN-aware + `bridge-vids` |
| AP tagged 帧在 access 口自动去 tag | ✅ 本文已纠正（不成立） | — |
| SSH 非真正带外；须 Console | ✅ 已体现 | 开头第 2 条、§4.1、§16 |
| 「所有设备不得直连 ER-X」非必要 | ✅ 已体现 | 全程三条第 1 条、§7 |
| 不应承诺全面 2.5G | ✅ 已体现 | §8 第 7 条、§14 |
## 实施前的最低限度现场证据
1. gfw：保存并审阅 `uci show firewall`、`ip route`、`ip -6 route`、`nft list ruleset`；确认 wan 的 masq 与所有 WAN→内网、VLAN10→内网匹配次序。
2. SE5420 Console：导出/截图 VLAN1、55、66 member 和 PVID/ingress-filter 状态；确认唯一管理 L3 interface 和路由/relay/DHCP 状态。
3. PVE：记录 `/etc/network/interfaces`、VM NIC VLAN tags 和 `bridge vlan show`，再决定是否把 VLAN-aware 改造另开窗口。
4. AP：从实际设备 `info` 或控制器记录确认 Inform URL（本仓库目前记录 `http://192.168.66.46:9080/inform`），并验证 VLAN10 tag 只经 U6/PVE trunk。
5. NAS：单网口稳定后，另窗配置并验证两端 LACP，第二根线最后插入；用多流及单流 `iperf3` 分开验收。