16 KiB
16 KiB
附录：覆盖映射、抓取清单与官方文档问题清单
本附录是《Ceph 知识学习手册》的溯源与自检文件。所有数字均来自实际抓取与统计脚本输出，未做估算。 文档版本：Tentacle v20.2.4 ｜ 抓取日期：2026-09-17 ｜ 官网入口：https://docs.ceph.com/en/tentacle/
一、版本基线的确定过程
用户给出的入口是 https://docs.ceph.com/en/latest/。实测发现该路径不是稳定版：
| 探测项 | 实测结果 |
|---|---|
/en/latest/ 首页 |
页面含 "This document is for a development version of Ceph" |
Read the Docs sitemap.xml |
除 latest 外还列出版本名 umbrella（即 v21 开发线） |
/en/tentacle/releases/ |
Active Releases：Tentacle 20.2.4（首发 2025-11-18，最新点版本 2026-08-19，EOL 预计 2027-06-01）；Squid 19.2.6（EOL 2026-10-31） |
| Archived | Reef 18.2.8（EOL 2025-03-20）及更早 |
结论：本手册以 Tentacle v20.2.4 为基线（用户确认），源文取自 GitHub tag v20.2.4。
⚠️ 一个需要读者注意的官方数据不一致：
/en/tentacle/releases/的 gantt 图把 Tentacle 列为 Active、最新 20.2.4，但同一版本源码doc/releases/index.rst的 Active Releases 表格只列了 Squid 与 Reef，没有 Tentacle，且doc/releases/目录下不存在tentacle.rst与releases.yml。本手册以站点渲染结果（Tentacle 20.2.4 为当前稳定线）为准，并在此如实登记该矛盾。
二、抓取方式说明（为什么不爬 docs.ceph.com）
| 环节 | 采用方案 | 原因 |
|---|---|---|
| 页面枚举 | 解析 Sphinx toctree 递归展开 + GitHub 目录树 embeddedData（补齐 dev/* 的 glob 目录） |
sitemap.xml 只有版本首页，拿不到子页；api.github.com 匿名限流 60 次/小时，实测已 403 |
| 源文获取 | raw.githubusercontent.com/ceph/ceph/v20.2.4/doc/**.rst |
逐字保真的 rst 源文，且 GitHub raw CDN 对数百文件并发几乎不限流；直接爬 docs.ceph.com 极易触发全站 429 硬限流（历史教训：并发抓 Ceph 803 页后全站 429，数小时才恢复） |
| 抓取结果 | 512 页，全部成功，0 失败，共 4.5 MB rst 源文 | 见 tools/fetched.json |
| 配置项默认值 | 额外抓取 src/common/options/*.yaml.in（13 个文件，2052 个配置项） |
见下方第四节 |
目录说明：
ceph-handbook/
├── handbook/ # 成稿：21 册 Markdown（本文件所在目录）
├── handbook-src/
│ ├── raw/ # 原文池：512 个 rst 源文，保留不删，供溯源
│ └── options/ # 源码配置项定义 yaml.in（默认值权威来源）
└── tools/ # 抓取与统计脚本 + tree.json / inventory.json / mapping.json
三、覆盖映射表（官页面 → 手册分册）
统计口径：官方 toctree 可达页面 ∪ doc/dev 目录树 = 545 页；本次抓取 512 页（排除 33 页，见第五节）；成稿覆盖 512 页中的 512 页（含第 03 册补写的 rados/operations/change-mon-elections）。
| 分册 | 覆盖页数 | 体积 | 覆盖的官方章节 |
|---|---|---|---|
| 00-Ceph-总览与快速上手 | 24 | 104 KB | start/*、install/*、index、foundation、governance、releases/index、releases/general |
| 01-架构篇 | 2 | 174 KB | architecture（76KB）、glossary（26KB） |
| 02-RADOS-数据寻址与存储引擎 | 25 | 238 KB | rados/index、rados/operations/{data-placement, crush-map, crush-map-edits, placement-groups, pg-concepts, pg-states, pools, upmap, erasure-code*, pgcalc}、rados/configuration/{bluestore, filestore, journal, storage-devices, pool-pg, mon-osd-interaction} |
| 03-RADOS-集群运维与配置 | 24+1 | 164 KB | rados/operations/{add-or-rm-mons, add-or-rm-osds, balancer, read-balancer, cache-tiering, control, monitoring, monitoring-osd-pg, operating, stretch-mode, bluestore-migration, devices, health-checks, user-management, change-mon-elections}、rados/configuration/{ceph-conf, common, mon, osd, auth, network, msgr2, mon-lookup-dns, mclock, general} |
| 04-RADOS-排障篇 | 8 | 132 KB | rados/troubleshooting/*（8 页） |
| 05-cephadm-部署与运维篇 | 25 | 209 KB | cephadm/* 全部（install、host-management、operations、services/* 15 个、upgrade、certmgr、adoption、compatibility、troubleshooting 等） |
| 06-ceph-volume-磁盘管理篇 | 24 | 97 KB | ceph-volume/* 全部（lvm/* 13、simple/* 4、zfs/* 2、intro、inventory、drive-group、systemd） |
| 07-RBD-块存储篇 | 39 | 224 KB | rbd/* 全部（含 iSCSI 9 页、NVMe-oF 6 页、K8s/OpenStack/CloudStack/Nomad/Windows 集成） |
| 08-CephFS-文件存储篇 | 50 | 300 KB | cephfs/* 全部 50 页 |
| 09-RGW-核心与运维篇 | 13 | 181 KB | radosgw/{index, frontends, pools, placement, layout, config-ref, admin, adminops, account, multitenancy, nfs, metrics, troubleshooting} |
| 10-RGW-S3与Swift接口篇 | 25 | 162 KB | radosgw/s3/*（13）、radosgw/swift/*（10）、s3.rst、swift.rst |
| 11-RGW-多站点与数据服务篇 | 16 | 194 KB | radosgw/{multisite, multisite-sync-policy, cloud-*, sync-modules, elastic-sync-module, archive-sync-module, zone-features, notifications, bucket_logging, s3select, s3-notification-compatibility, d3n, compression, rgw-cache, orphans, dynamicresharding} |
| 12-RGW-安全与高级特性篇 | 20 | 165 KB | radosgw/{encryption, vault, kmip, barbican, iam, role, STS, STSLite, session-tags, bucketpolicy, keycloak, keystone, ldap-auth, oidc, opa, mfa, lua-scripting, qat-accel, uadk-accel, api} |
| 13-监控告警与Dashboard篇 | 28 | 271 KB | monitoring/index、mgr/*（25 页）、jaegertracing/index、hardware-monitoring/index |
| 14-安全篇 | 8 | 60 KB | security/* 全部 8 页（含 5 个 CVE 详情页） |
| 15-命令速查手册 | 36 | 195 KB | man/8/* 全部 36 个命令手册 |
| 16-内部实现-核心机制篇 | 41 | 340 KB | dev/ 顶层核心机制类 37 页 + dev/mon-* 4 页 |
| 17-内部实现-OSD与MDS篇 | 32 | 295 KB | dev/osd_internals/*（27，含 erasure_coding 子目录 5）、dev/mds_internals/*（5） |
| 18-内部实现-组件工具与Crimson篇 | 52 | 255 KB | dev/crimson/*、dev/cephadm/*、dev/radosgw/*、dev/dashboard/*、dev/ceph-volume/* + dev/ 顶层其余文件 |
| 19-开发者贡献指南篇 | 18 | 194 KB | dev/developer_guide/* 全部 18 页 |
| 合计 | 512 | 约 3.7 MB |
逐页映射的完整机器可读清单见
tools/mapping.json（字段：by_volume）。 成稿前逐页反查过一次：仅rados/operations/change-mon-elections未被分配，已补写进第 03 册第二十二章。rados/man/index是 man 页的索引页（0KB，仅 toctree），其内容由第 15 册承载。
四、配置项默认值的取值来源（重要）
Ceph 文档的 *-config-ref 页用 .. confval:: 指令引用配置项，默认值、类型在 rst 源文里并不存在，是在文档构建期由 Ceph 源码生成的。因此：
- 第 02、03 册初稿中大量默认值被标为「文档未明确」；
- 后续从源码
src/common/options/*.yaml.in（tagv20.2.4）取到权威默认值，共 2052 个配置项，已回填：
| 分册 | 补全默认值处数 | 仍查不到 |
|---|---|---|
| 02-RADOS-数据寻址与存储引擎 | 80 | 6（crush-num-failure-domains、crush-device-class、crush-locality 非配置项；bluestore_block_path/_db_path/_wal_path 在 yaml.in 中无 default: 字段） |
| 03-RADOS-集群运维与配置 | 198 | 5（osd_recovery_thread_timeout、sleep_interval、pool_ids、mgr/devicehealth/*_threshold 为模块/命令参数）+ 17 项 yaml.in 中无 default: 字段（fsid、mon_initial_members、public_network、cluster_addr、pid_file、chdir 等） |
凡回填处均已标注「（默认值取自 src/common/options/*.yaml.in @ v20.2.4）」，与文档原文来源区分开。
五、未纳入本次手册的官页面（33 页）及原因
| 类别 | 页数 | 具体页面 | 原因 |
|---|---|---|---|
| 编程 API 参考 | 12 | rados/api/{index, librados, librados-intro, libradospp, libcephsqlite, python, objclass-sdk}、rbd/api/{index, librbdpy}、cephfs/api/{index, libcephfs-java, libcephfs-py}、api/{index, mon_command_api} |
用户指定「API 不要」。另外第 07 册已覆盖 librbd Python 用法、rbd/api/librbdpy 的内容 |
| 旧版本 release notes | 21 | releases/{argonaut…squid}（历代 changelog，约 4 MB） |
属历史变更记录而非学习材料；仅保留 releases/index（版本策略）与 releases/general，由第 00 册承载 |
| 合计 | 33 |
六、各册「文档未明确项」统计
下表为「文档未明确」在各册全文（含末尾清单）中的出现次数，可作为该册官方信息缺口的一个粗略指标——数值越高，说明该主题官方文档写得越不完整：
| 分册 | 出现次数 | 分册 | 出现次数 |
|---|---|---|---|
| 03-RADOS-集群运维与配置 | 262 | 08-CephFS-文件存储篇 | 12 |
| 02-RADOS-数据寻址与存储引擎 | 105 | 14-安全篇 | 11 |
| 05-cephadm-部署与运维篇 | 91 | 01-架构篇 | 9 |
| 12-RGW-安全与高级特性篇 | 132 | 19-开发者贡献指南篇 | 8 |
| 13-监控告警与Dashboard篇 | 56 | 00-Ceph-总览与快速上手 | 7 |
| 04-RADOS-排障篇 | 36 | 18-内部实现-组件工具与Crimson篇 | 7 |
| 10-RGW-S3与Swift接口篇 | 33 | 15-命令速查手册 | 6 |
| 17-内部实现-OSD与MDS篇 | 31 | 11-RGW-多站点与数据服务篇 | 8 |
| 16-内部实现-核心机制篇 | 30 | 09-RGW-核心与运维篇 | 15 |
| 07-RBD-块存储篇 | 22 | 06-ceph-volume-磁盘管理篇 | 19 |
说明：计数包含该册末尾「## 文档未明确项」清单中的条目行，故略高于实际独立条目数。每册的完整清单请直接查看对应分册末尾章节——这些是官方文档本身没写清楚、配生产前需要自行验证的点。
七、官方文档自身的问题清单（撰稿过程中实测发现）
以下问题均为阅读 Tentacle v20.2.4 源文时发现，本手册已在对应位置标注或按更权威口径修正：
| # | 问题 | 出处 |
|---|---|---|
| 1 | doc/releases/index.rst 的 Active Releases 表缺 Tentacle，且 releases/ 目录无 tentacle.rst、releases.yml，与站点渲染结果矛盾 |
00 册 |
| 2 | install/index.rst 的 Windows 链接 ./windows-install 断链 |
00 册 |
| 3 | start/quick-rbd.rst 示意图仍使用已废弃的 ceph-deploy |
00 册 |
| 4 | beginners-guide 称 manager 负责数据均衡，与 OSD/CRUSH 的实际职责冲突 |
00 册 |
| 5 | cephadm 安装示例中的版本号仍写 18.2.0（未随版本更新） |
00 册 |
| 6 | 术语表 Ceph Monitor 条目列了 manager map 却未列 PG/MDS map，与架构页「五张 map」不一致 |
01 册 |
| 7 | troubleshooting-pg.rst 中 incomplete、snaptrim 两节在源文中为空白 |
04 册 |
| 8 | cephadm/install.rst 中 --registry-url 参数源文不存在（实为 --registry-json） |
05 册 |
| 9 | cephadm/upgrade.rst 未给出回滚步骤；mgr/cephadm 元数据备份还原无对应章节 |
05 册 |
| 10 | mon_warn_on_slow_ping_time 初稿误写「1 秒 / 1000ms」，权威库为 0（禁用），已更正 |
03 册 |
| 11 | radosgw/lua-scripting.rst 正文称内存上限 500K，与 rgw_lua_max_memory_per_state 默认 128000 不一致 |
12 册 |
| 12 | radosgw/vault.rst 的 secret-id 获取命令与 role-id 重复；STSLite.rst 的 Keystone 密码/用户说明错位 |
12 册 |
| 13 | IAM policy 与 bucket policy 的优先级，官方未给出裁决规则 | 12 册 |
| 14 | mgr/prometheus/*、mgr/dashboard/*、influx、localpool 等模块级配置项不在 *.yaml.in，默认值无法二次校验 |
13 册 |
| 15 | CVE-2021-3509、CVE-2021-3531 的影响版本与修复版本口径不自洽；CVE-2021-3524 无影响版本；CVE-2015-5245 严重性为空 | 14 册 |
| 16 | man/8/ceph.rst 全文本身就没有 orch / telemetry 章节（仅第 1843 行 -f/--format 处提到 "yaml is only valid for orch commands"）；本手册该两节内容取自同仓库的 mgr/orchestrator.rst、mgr/telemetry.rst、cephadm/*，synopsis 系归纳所得，已全部用 💡 补充 标注。另 rbdnamer 二进制名有歧义 |
15 册 |
| 21 | dev/ceph_krb_auth.rst 六节编号跳号（a/b/c 直接到 f，无 d/e）；v20.2.4 的 options 中 auth_*_required 合法值只写 cephx/none，未列 gss；限制与已知问题源文未写 |
16 册 |
| 22 | dev/osd_internals/erasure_coding/enhancements.rst 的 Story 24 把 MOSDEcSubOpSequence 写成 MODSEcSubOpSequence，疑为笔误（已照录并标注）；新增消息的类定义/字段/默认值源文未给出 |
17 册 |
| 23 | mgr/smb.rst 字段名为 provider（在 cephfs 对象内，旧稿曾误作 share_vfs，已按源文更正）；官方 usersgroups 的 ref 称指向 ceph.smb.join.auth，语义疑似应为 ceph.smb.usersgroups；storage 示例命令主机 IBM-Ceph-1 与输出 node-10 不一致 |
13 册 |
| 17 | dev/peering.rst 的状态图为 SVG，源文无法提取；health-reports.rst 示意图缺失；perf_histograms.rst 示例称 9 个 history entry 但 JSON 只有 8 组 |
16 册 |
| 18 | dev/osd_internals/mclock_wpq_cmp_study.rst 数据来自 Quincy 而非 Tentacle；EC 的三种 data flow 官方只列了两种 |
17 册 |
| 19 | dev/radosgw/s3_compliance.rst 为草案且 commit 链接失效；ceph-volume/zfs.rst 的 compression 示例疑误写 ceph.vdo=1；freebsd.rst 的 zpool add osd1 log 疑应为 cache |
18 册 |
| 20 | 官方无 src/ 目录布局表；Fixes: trailer 规范、GDB 子命令、Sentry 章节在源文中缺失 |
19 册 |
八、交付物自检
| 自检项 | 结果 |
|---|---|
| 抓取成功率 | 512/512，0 失败 |
| 分册数量 | 21 册（00–19 正文 + 20 附录），无空册 |
| 页面覆盖 | 512/512 官页面均有对应分册（逐页反查确认） |
| 版本标注 | 每册文件头均标注 Tentacle v20.2.4 + 抓取日期 |
| 来源标注 | 每册章节末尾标注 > 引自：[页面](https://docs.ceph.com/en/tentacle/...) |
| 补充标注 | 非官方内容均标 > 💡 补充： |
| 数值核查 | 配置项默认值已从源码 yaml.in 回填 278 处；各册撰稿人另做了关键数值 grep 复核 |
| 截断补全 | 首轮因源文读取被截断/拦截而留白的 4 处已全部补齐（见下表） |
| 原文留存 | handbook-src/raw/ 保留 512 个 rst 源文，可逐条回溯 |
首轮截断处的补全记录（2026-09-18）
| 分册 | 补全内容 | 净增 |
|---|---|---|
| 15-命令速查手册 | ceph orch 全量子命令表 + ceph telemetry 子命令与 7 个 mgr/telemetry/* 配置项（源文 man/8/ceph.rst 无此两章，内容取自同仓 mgr/orchestrator.rst、mgr/telemetry.rst、cephadm/*） |
约 1.5 万字符 |
| 16-内部实现-核心机制篇 | Kerberos 认证：keytab 校验、KDC 搭建、kdc.conf/krb5.conf 配置、验证步骤、配置项速查表 | 约 1.0 万字符 |
| 17-内部实现-OSD与MDS篇 | EC 增强提案 19.5 节复校（正文 19.5.1–19.5.16 原本完整），新增 19.5.17「新增消息/接口/标志速查」 | 约 0.33 万字符 |
| 13-监控告警与Dashboard篇 | SMB 模块 8.15.4–8.15.11（五类资源完整字段、声明式全流程、客户端访问）+ 硬件监控 10.3–10.6（oob 带外凭据、storage/firmware 完整输出、注意事项） | 约 1.15 万字符 |
复校结果也对首轮判断做了一处更正：第 15 册的
orch/telemetry缺失不是源文截断，而是man/8/ceph.rst本来就没有这两章（见问题清单第 16 条）。