Skip to content

Commit 88e7f06

Browse files
mudsskymudssky
committed
2 parents bfa9620 + c1e72a6 commit 88e7f06

50 files changed

Lines changed: 7225 additions & 62 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.husky/pre-commit‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
pnpm lint-staged
1+
# pnpm lint-staged

‎docs/brainstorms/2026-04-05-fnos-disk-alias-and-backfill-requirements.md‎

Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
---
2+
date: 2026-04-05
3+
topic: fnos-disk-alias-and-backfill
4+
---
5+
6+
# FNOS 磁盘业务名别名与失败盘补挂方案
7+
8+
## Problem Frame
9+
10+
当前 `linux/fnos/fnos-mount-manager` 已经能生成 `fstab`、`tmpfiles`、并提供 `check`、`repair`、`remount` 等命令，但实机重启后的结果说明：仅靠 systemd `fstab` 挂载，并不能稳定赢过 FNOS 原生自动挂载。
11+
12+
本机当前状态已经清楚分成两类：
13+
14+
- `animeDisk`、`debutDisk`、`galDisk` 已经被 FNOS 原生服务挂上，但路径是 `/vol00/ST4000VX007-2DT166`、`/vol00/ST8000NM017B-2TJ103`、`/vol00/WDC WD40EZRZ-00GXCB0` 这类型号路径，而不是业务名路径。
15+
- `bookDisk` 没有被成功挂上，属于真正的失败盘。
16+
17+
因此下一步不应该继续把所有盘都视为“必须由我们抢到底层首次挂载”，而是要把方案改成两段式：
18+
19+
1. 对已经被 FNOS 原生挂上的盘，建立稳定业务名别名层。
20+
2. 对 FNOS 没挂上的盘，单独补挂。
21+
22+
这个方案的目标不是改掉 FNOS 原始挂载路径，而是在保留原始路径的前提下，额外提供稳定、可预期、适合 Samba/脚本/人工使用的业务名路径。
23+
24+
## Requirements
25+
26+
**Alias Layer**
27+
- R1. 方案必须保留 FNOS 原始挂载路径，不主动重命名或删除 `/vol00/ST...`、`/vol00/WDC...` 这类原生路径。
28+
- R2. 对已经被 FNOS 成功挂上的磁盘，管理器必须能够建立稳定的业务名别名路径，例如把原始路径映射到 `/vol00/debutDisk`。
29+
- R3. 业务名别名层默认必须使用 bind mount，而不是 symlink，除非目标环境明确不支持 bind mount。
30+
- R4. 别名同步时必须以“原始路径是否已存在且已挂载”为前提；如果原始路径不存在，不应创建空壳别名误导使用者。
31+
32+
**Backfill for Failed Disks**
33+
- R5. 对 FNOS 原生自动挂载失败的磁盘，管理器必须能够单独执行补挂，而不是要求所有磁盘都统一重挂。
34+
- R6. “失败盘补挂”与“已挂盘别名同步”必须是可组合但逻辑独立的两个分支；不能因为某块盘失败就中断其余已挂盘的别名同步。
35+
- R7. 对补挂仍失败的磁盘，管理器必须给出明确失败原因，并保留其他磁盘的成功结果。
36+
37+
**Naming and Access**
38+
- R8. 业务名路径必须继续以结构化配置中的固定业务名为准，例如 `/vol00/bookDisk`、`/vol00/debutDisk`，不能退回卷标或磁盘型号派生。
39+
- R9. Samba 等上层共享配置必须可以稳定切换到业务名路径，而不要求依赖 FNOS 原始型号路径。
40+
- R10. 对终端用户和脚本调用方而言，业务名路径应成为推荐访问入口；原始路径保留但降级为底层实现细节。
41+
42+
**Workflow**
43+
- R11. 管理器必须新增明确的“别名同步”能力，并支持只同步别名、不执行补挂。
44+
- R12. 管理器必须支持只对失败盘执行补挂，而不扰动已经被 FNOS 挂上的磁盘。
45+
- R13. 管理器必须支持一个组合入口，在一次运行中完成“先同步已挂盘别名，再补挂失败盘”。
46+
- R14. 组合入口默认不应对已经健康挂上的磁盘执行 `umount` + `mount`，除非用户显式选择强制重挂。
47+
48+
## Success Criteria
49+
- `animeDisk`、`debutDisk`、`galDisk` 这类已被 FNOS 挂到型号路径的盘，在不破坏原始路径的前提下，能稳定通过业务名路径访问。
50+
- `bookDisk` 这类 FNOS 未挂上的盘，可以被单独补挂到业务名路径。
51+
- 业务名路径能够作为 Samba 或其他上层入口的稳定配置目标。
52+
- 管理器在一次执行中可以同时报告：哪些盘做了别名同步、哪些盘做了补挂、哪些盘仍失败。
53+
- 失败盘不会拖垮已挂盘的别名同步结果。
54+
55+
## Scope Boundaries
56+
- 本次不尝试让 FNOS 原生自动挂载直接改名为业务名路径。
57+
- 本次不禁用或替换 `trim_main.service` 这类 FNOS 核心服务。
58+
- 本次不要求删除型号路径或让它们从系统中消失。
59+
- 本次不把 Samba 共享层的最终改动策略在此文档中细化到具体配置文件级别；这里只要求业务名路径可作为稳定目标。
60+
61+
## Key Decisions
62+
- 采用“保留 FNOS 原始路径 + 叠加 bind mount 业务名别名”的方式，而不是强行改写 FNOS 原始挂载结果。
63+
- 采用“只对失败盘补挂”的方式，而不是每次对所有盘统一重挂。
64+
- 采用“别名同步”和“失败盘补挂”分支解耦的方式，而不是把两者硬塞进一个只会全成全败的流程。
65+
- 采用“业务名路径为推荐入口”的方式，而不是继续让型号路径暴露给上层使用者。
66+
67+
## Dependencies / Assumptions
68+
- FNOS 原生自动挂载在多数情况下仍会先把部分盘挂到型号路径，这些路径在方案运行时可被发现。
69+
- 目标环境支持 bind mount，并允许在 `/vol00` 下建立附加挂载点。
70+
- 当前仓库内的结构化磁盘配置已经足以表达“业务名 -> 设备标识”的关系。
71+
72+
## Outstanding Questions
73+
74+
### Resolve Before Planning
75+
- 暂无。
76+
77+
### Deferred to Planning
78+
- [Affects R2,R3,R11,R13][Technical] 别名同步是通过 bind mount 单次命令完成，还是需要额外生成/安装持久化规则或 service 来保障重启后自动恢复。
79+
- [Affects R5,R6,R12,R13][Technical] 失败盘补挂的判定规则如何定义，才能稳定区分“未挂上”与“已挂到错误路径”。
80+
- [Affects R9,R10][Technical] 是否要在同一轮里同步更新 Samba 配置指向业务名路径，还是先只保证本地业务名路径稳定可用。
81+
- [Affects R13][Technical] 组合入口的命令面应如何设计，例如 `sync`、`alias`、`backfill`、`reconcile` 哪个最清晰。
82+
83+
## Next Steps
84+
85+
→ /prompts:ce-plan for structured implementation planning

‎docs/brainstorms/2026-04-05-fnos-portable-disk-mounting-requirements.md‎

Lines changed: 93 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
1+
---
2+
date: 2026-04-05
3+
topic: fnos-portable-disk-mounting
4+
---
5+
6+
# FNOS 跨发行版可复用的数据盘挂载方案
7+
8+
## Problem Frame
9+
10+
当前机器上的外接数据盘挂载同时混用了 `fstab`、开机重挂载 service、以及登录 shell 里的 `mount -a`，导致启动阶段容易互相打断，也让方案难以复制到别的机器。
11+
12+
这次要定义的是一套更稳、更简单、可迁移的挂载管理方案，用于 FNOS 及其他常见 systemd Linux 发行版上的外接数据盘。目标不是做自动识别一切硬盘的“智能系统”，而是沉淀一套低维护成本的约定：仓库里保留可提交模板，本机保留私有配置，通过单一管理脚本统一生成与应用挂载配置，运行时仍然只依赖 `fstab` 作为系统挂载真相来源，并兼顾 Samba 与本地文件管理访问。
13+
14+
## Requirements
15+
16+
**Configuration Source**
17+
- R1. 数据盘挂载配置必须以 `linux/fnos/` 下的结构化 shell 配置清单作为单一真相来源，并采用“仓库模板 + 本机私有配置”的双文件模式。
18+
- R2. 仓库内必须保留可提交的示例配置文件，供新机器复制后生成本机私有配置；机器私有配置不能要求直接纳入 Git 管理。
19+
- R3. 结构化清单必须支持在同一份配置中混合使用 `LABEL=` 与 `UUID=` 标识磁盘：能统一卷标的磁盘优先使用 `LABEL=`，少数不能稳定统一的磁盘允许继续使用 `UUID=`。
20+
- R4. 挂载路径必须使用显式配置的固定业务路径，例如 `/vol00/bookDisk`，并且路径命名必须独立于磁盘卷标，允许后续调整而不要求改卷标。
21+
- R5. 挂载根目录必须支持配置，默认值为 `/vol00`，以便同一套方案迁移到其他 Linux 机器时无需改脚本代码。
22+
23+
**Management Workflow**
24+
- R6. `linux/fnos/` 下必须拆分为多文件模块化源码，并通过一个 `build.sh` 产出单文件管理脚本，方便在目标机器上分发与执行。
25+
- R7. 管理脚本必须作为唯一推荐操作入口，常规的生成、校验、应用、修复都通过该脚本执行，而不是要求用户直接手改系统文件。
26+
- R8. 管理脚本必须采用显式两步流程：先 `build/generate` 生成结果与预览，再由用户执行 `apply` 写入系统文件；不能默认一步到位直接改 `/etc/fstab`。
27+
- R9. 运行时必须只有一套自动挂载真相来源；管理脚本负责生成和应用配置，但常规挂载行为仍由 `fstab` 定义，不能依赖第二套开机自动重挂载机制来维持正常工作。
28+
29+
**Mount Behavior**
30+
- R10. 方案必须支持两种挂载模式：默认按需自动挂载，以及按盘可选的开机立即挂载。
31+
- R11. 默认推荐模式必须是按需自动挂载，以降低启动阶段的挂载竞争和慢盘拖慢开机的问题。
32+
- R12. 少数对“开机后立即可见”有明确要求的磁盘，必须允许通过配置切换为开机立即挂载，而不影响其他磁盘继续使用按需自动挂载。
33+
34+
| 模式 | 默认性 | 触发方式 | 适用场景 | 主要代价 |
35+
|---|---|---|---|---|
36+
| 按需自动挂载 | 默认 | 首次访问挂载点时触发 | 大多数外接数据盘、冷数据盘、慢盘 | 首次访问会有一次挂载延迟 |
37+
| 开机立即挂载 | 可选 | 开机阶段主动挂载 | 需要开机后立刻在线的少数磁盘 | 更容易暴露慢盘、脏盘、竞争挂载问题 |
38+
39+
**Access and Recovery**
40+
- R13. Samba 共享与本地文件管理访问必须基于固定挂载点路径，而不是依赖桌面环境或其他组件临时生成的自动挂载路径。
41+
- R14. 管理脚本必须包含统一的修复能力，用于处理磁盘未挂载、被其他进程占用、或 NTFS 状态不干净等异常；现有 `linux/fnos/remount.sh` 只作为历史功能来源，不再单独保留为最终入口文件。
42+
- R15. 管理脚本必须包含校验能力，能够检查挂载点、磁盘标识匹配情况、重复自动挂载来源，以及当前系统状态与配置清单是否一致。
43+
- R16. 文档与工具必须明确要求移除或禁用与 `fstab` 冲突的重复自动挂载来源，例如开机重挂载 service、登录 shell 中的 `mount -a`，以及在需要时关闭抢占相同磁盘的其他自动挂载行为。
44+
45+
**Portability**
46+
- R17. 方案必须优先依赖常见 systemd Linux 发行版都具备的标准能力，避免把发行版私有 UI、桌面自动挂载策略或 NAS 厂商界面行为作为必需前提。
47+
- R18. 方案必须保持“复制成本低于自动化复杂度”的原则：允许每台机器做少量本地编辑，但不为了完全零配置复制而引入新的长期守护进程或多套运行时配置体系。
48+
- R19. 管理脚本与主配置清单必须基于纯 shell 能力可运行，不要求 `jq`、`yq` 或其他额外解析依赖作为前置条件。
49+
- R20. 管理脚本的构建产物必须是单文件脚本，便于复制到其他机器执行，而不要求在目标机器上保留完整源码目录。
50+
51+
## Success Criteria
52+
- 新机器可以通过复制仓库中的示例配置、做少量本地调整、运行单文件管理脚本，快速得到可工作的挂载配置。
53+
- 正常启动时不再依赖额外的重挂载 service 或 shell 登录脚本来补救挂载。
54+
- 大多数外接数据盘在首次通过 Samba、文件管理器或命令行访问固定挂载点时可以自动挂载。
55+
- 需要“开机后立即在线”的个别磁盘可以单独配置为 eager 模式，而不会迫使所有磁盘都采用同一策略。
56+
- 故障排查路径清晰：运维者知道唯一该修改的主配置在哪里，也知道生成、应用、校验、修复分别通过哪个管理命令完成。
57+
58+
## Scope Boundaries
59+
- 本次不追求“插到任意机器自动识别所有外接盘并零配置完成挂载”。
60+
- 本次不尝试覆盖所有文件系统类型，优先服务当前以 NTFS 外接数据盘为主的场景。
61+
- 本次不把 NAS 文件管理器的 UI 展示逻辑作为保证对象；保证的是对固定挂载点的访问行为与共享路径稳定。
62+
- 本次不把机器私有配置直接纳入 Git 管理。
63+
- 本次不让管理脚本接管系统开机后的常驻挂载调度；脚本是管理入口，不是常驻守护进程。
64+
65+
## Key Decisions
66+
- 采用“结构化 shell 清单为单一真相来源 + 仓库模板 + 本机私有配置”的方式，而不是直接把 `fstab` 模板当主配置。
67+
- 采用“固定业务挂载点 + 可配置磁盘标识 + 可配置挂载根目录”的方式，而不是让挂载路径跟着卷标变化或把根目录写死。
68+
- 采用“多文件源码 + `build.sh` 生成单文件管理脚本”的方式，而不是让目标机器直接依赖完整源码目录运行。
69+
- 采用“管理脚本作为唯一推荐入口 + 显式 generate/apply 两步流”的方式，而不是继续手工拼改多个文件。
70+
- 采用“默认 automount、按盘可切 eager”的混合模式，而不是强制所有磁盘统一开机挂载或统一按需挂载。
71+
- 采用“`fstab` 作为唯一运行时自动挂载来源 + 管理脚本内置校验与修复能力”的方案，而不是继续保留独立的开机重挂载脚本参与正常启动流程。
72+
73+
## Dependencies / Assumptions
74+
- 目标机器为采用 systemd 的 Linux 发行版；按需自动挂载能力依赖 `x-systemd.automount` 这一类 systemd `fstab` 行为。
75+
- Samba 等上层访问会直接命中固定挂载点路径，从而在按需模式下触发自动挂载。
76+
- 个别桌面环境或 NAS 组件如果会抢占同一块磁盘的自动挂载，需要在落地时按机器情况关闭或绕开。
77+
- 目标机器可以执行标准 POSIX/Bash shell 脚本，并允许管理脚本在显式 `apply` 阶段写入系统级 `fstab`。
78+
79+
## Outstanding Questions
80+
81+
### Resolve Before Planning
82+
- 暂无。
83+
84+
### Deferred to Planning
85+
- [Affects R1,R2,R6,R20][Technical] `linux/fnos/` 下的源码目录、模块边界和 `build.sh` 产物命名如何设计，才能既利于维护又便于分发。
86+
- [Affects R1,R3,R5,R19][Technical] 结构化 shell 配置清单的字段格式、注释约定和加载方式如何设计，才能既便于复制又不容易填错。
87+
- [Affects R8,R9,R10,R11,R12][Technical] 默认 automount 与 eager 两种模式在生成 `fstab` 时分别采用哪些推荐挂载选项，才能兼顾稳定性、权限和可读性。
88+
- [Affects R14,R15,R16][Technical] 管理脚本的子命令边界如何划分，例如 `generate`、`apply`、`check`、`repair`、`status` 是否都需要首版提供。
89+
- [Affects R14,R15,R16,R17][Needs research] 对 FNOS 当前文件管理器、Samba 与其他潜在自动挂载组件，需要给出多强的兼容指导，才能避免与目标方案相冲突。
90+
91+
## Next Steps
92+
93+
→ /prompts:ce-plan for structured implementation planning

0 commit comments

Comments
 (0)