> 基于 Ceph 官方文档整理 | 文档版本：**Tentacle v20.2.4** | 抓取日期：2026-09-17 | 源文：ceph/ceph@v20.2.4 `doc/dev/developer_guide/` > 官网入口：https://docs.ceph.com/en/tentacle/dev/developer_guide/ # 第 19 册 · 开发者贡献指南篇 --- ## 本册导读 本册面向**想给 Ceph 提 PR、参与社区开发的人**。内容覆盖从「第一次 fork 仓库」到「PR 被 merge、backport、跑 teuthology 集成测试、用 gdb 调试」的完整贡献链路，并包含两块体量很大的专题：Ceph Dashboard 前后端开发（本册最大块，约占源文一半）与集成测试框架 teuthology。 **运维向读者可跳过本册。** 本册讲的是「如何改 Ceph 的代码」，不是「如何部署/调优 Ceph 集群」。如果你只是要装集群、扩 OSD、排障，请看第 3 册（集群运维与配置）、第 4 册（RADOS 排障）、第 5 册（cephadm 部署运维）。唯一可能对你有用的章节是第七章（用 gdb attach 到 `ceph-osd` 进程）与第八章（Windows CI 的产物怎么看），但那也是排障时才用得上。 ### 本册覆盖的源文件（`doc/dev/developer_guide/`，共 18 个 .rst，约 214KB） | 分组 | 文件 | 大小 | 对应章节 | |---|---|---|---| | 入口 | `index.rst` | 949B | 一 | | 入门 | `intro.rst`、`essentials.rst` | 1.2KB / 11KB | 一 | | 工作流 | `basic-workflow.rst` | 23KB | 二 | | 任务管理 | `issue-tracker.rst` | 1.4KB | 三 | | 合并策略 | `merging.rst` | 3.9KB | 四 | | 测试 | `tests-unit-tests.rst`、`running-tests-locally.rst`、`tests-windows.rst` | 6.2KB / 7.5KB / 6KB | 五、八 | | 集成测试 | `testing_integration_tests/`（index + intro + workflow + debugging-tips + kernel + sentry，共 6 个） | 约 49KB | 六 | | 调试 | `debugging-gdb.rst` | 1.4KB | 七 | | Dashboard | `dash-devel.rst` | 103KB | 十 | | 追踪 | `jaegertracing.rst` | 2.4KB | 十一 | ### 阅读须知 1. **命令、工具名、目录名、git 规范术语、环境变量一律保留英文原文**，中文只做叙述。 2. **文档的年代痕迹要如实标注**。本册部分页面明显多年未更新：`merging.rst` 仍在用 hammer/infernalis/jewel/mimic 举例，`teuthology-intro.rst` 的平台列表写的是「as of September 2020」，Windows 章节的示例日志里有 `ceph_test_dokan.DokanTests`。这些内容不等于 Tentacle 的现状，遇到时本册会指出。 3. 凡官方文档没写的，一律写「**文档未明确**」；本册作者补充的内容一律以 `> 💡 补充：` 标注。 4. 每个章节末尾标注来源：`> 引自：[<页面标题>](URL)`。 --- # 一、入门：开发环境、社区与构建要点 ## 1.1 索引页：本册的目录结构 `doc/dev/developer_guide/index.rst` 是整个开发者贡献指南的入口，作者署名 Loic Dachary 与 Nathan Cutler，许可为 CC-BY-SA-3.0。它的 toctree 如下（翻译保留原顺序）： | 英文条目 | 页面 | |---|---| | Introduction | `intro` | | Essentials | `essentials` | | What is Merged and When | `merging` | | Issue tracker | `issue-tracker` | | Basic workflow | `basic-workflow` | | Tests: Unit Tests | `tests-unit-tests` | | Tests: Integration Tests (Teuthology) | `testing_integration_tests/index` | | Tests: Running Tests (Locally) | `running-tests-locally` | | Tests: Windows | `tests-windows` | | Ceph Dashboard Developer Documentation (formerly HACKING.rst) | `dash-devel` | | Tracing Developer Documentation | `jaegertracing` | | Cephadm Developer Documentation | `../cephadm/index`（不在本册范围） | | Debugging with GDB | `debugging-gdb` | 页面顶部还有一条 note：你可能也对 `/dev/internals` 文档感兴趣。 > 引自：[Contributing to Ceph: A Guide for Developers](https://docs.ceph.com/en/tentacle/dev/developer_guide/) ## 1.2 Introduction：这份指南的两个目标 官方开篇写明本指南有两个目标： 1. **降低软件开发者参与 Ceph 项目的门槛**（lower the barrier to entry）。 2. **作为 Ceph 开发者的参考手册**（serve as a reference）。 它假设读者已经熟悉 Ceph 本身（分布式对象存储与文件系统，设计目标是提供出色的 performance、reliability 与 scalability）。如果不熟悉，官方给的三个入口是： - 项目官网：https://ceph.com - 论文列表：https://ceph.com/publications/ - YouTube 频道：https://www.youtube.com/c/CephStorage （有 Tech Talks、Code walk-throughs、Ceph Developer Monthly 录像） 由于读者被假定为有网络连接的开发者，本指南对「在别处已讲过的主题」采取**只给链接**的处理方式。如果发现链接失效或有更好的链接，官方请你到 http://tracker.ceph.com/projects/ceph/issues/new 报 bug。 > 引自：[Introduction](https://docs.ceph.com/en/tentacle/dev/developer_guide/intro/) ## 1.3 Essentials：每个 Ceph 开发者都必须知道的事 ### 1.3.1 Leads（各组件负责人） Ceph 由 Sage Weil 创建，现在由 **Ceph Leadership Team（CLT）** 领导。每个主要组件有自己的 lead。完整的 lead 列表及其 GitHub nick 见社区网站：https://ceph.io/en/community/team 列表里出现的 Ceph 专有缩写，官方说在 `/architecture` 文档里解释（不在本册范围）。 ### 1.3.2 History 官方只给了一个外链：维基百科 Ceph 条目的 History 章节 https://en.wikipedia.org/wiki/Ceph_%28software%29#History ### 1.3.3 Licensing（许可证） Ceph 是自由软件。除非另有说明，Ceph 源码按 **LGPL2.1 或 LGPL3.0** 分发。完整细节见源码树顶层目录的 `COPYING` 文件： https://github.com/ceph/ceph/blob/master/COPYING ### 1.3.4 Source code repositories（代码仓库） 代码托管在 GitHub 的 Ceph organization（https://github.com/ceph）下的多个仓库里，但**本册只覆盖 `https://github.com/ceph/ceph`**。 官方强调：想做出有意义的贡献，**熟练掌握 git 是必需的**（A working knowledge of git is essential）。git 文档入口：https://git-scm.com/doc ### 1.3.5 Redmine issue tracker 代码在 GitHub，但 **issues（Bug、Feature、Backport、Documentation 等）在 Redmine**：http://tracker.ceph.com - tracker 里有一个 Ceph 项目，下面有若干子项目，大致对应各个架构组件。 - **只要注册就能开新 issue 和评论**（权限自动授予）。注册地址：http://tracker.ceph.com/account/register - 报 bug 或提 feature：跳到 http://tracker.ceph.com/projects/ceph 然后点 `New issue`。 ### 1.3.6 Slack、邮件列表与 IRC | 渠道 | 说明 | |---|---| | Slack | https://join.slack.com/t/ceph-storage/shared_invite/zt-32hkefbs5-f6qZDZLd5U8CYj7drBTHFw | | `dev@ceph.io` | Ceph 本身的开发讨论、与其他技术的互操作性、项目运作。对所有人开放，订阅地址 https://lists.ceph.io/postorius/lists/dev.ceph.io | | `ceph-devel@vger.kernel.org` | **Linux 内核 Ceph 客户端**组件的讨论与 patch review。注意：2018 年中之前，这个列表曾经是通用的 devel-ceph 归档列表，搜索历史归档时留意这一点。订阅走 https://subspace.kernel.org/vger.kernel.org.html | | IRC | Ceph 社区在 **OFTC** 网络的 `#ceph` 频道实时交流。服务器 `irc.oftc.net`。建议注册账号，注册说明见 https://www.oftc.net/Services/#register-your-account | IRC 频道清单（官方给出）：`#ceph`、`#ceph-devel`、`#cephfs`、`#ceph-dashboard`、`#ceph-orchestrators`、`#sepia`。`#ceph` 的讨论有日志和在线归档。 IRC 的礼仪提醒（官方原话大意）：频道里可能有很多人，但不一定都在键盘前；没人回应就多等一会儿。 ### 1.3.7 Submitting patches 官方明确说：**提交 patch 的权威说明在源码树顶层目录的 `CONTRIBUTING.rst` 文件里**，并建议所有新人仔细阅读： https://github.com/ceph/ceph/blob/main/CONTRIBUTING.rst 本册（developer_guide）与该文件之间可能有重叠。 ### 1.3.8 Building from source（从源码构建） 官方只给了一个指向：`/install/build-ceph`（安装手册的构建章节，不在本册范围）。 ### 1.3.9 用 ccache 加速本地构建 `ccache`（https://ccache.samba.org/）可以加快 Ceph 源码树的**重**构建。 **前提**：使用 ccache 之前，先确认源码树是干净的、不会产生构建失败。切分支时可能不知不觉引入旧的构建产物，导致构建失败。 **清理源码树**（两步）： ```bash ninja clean ``` ```bash git clean -fdx; git submodule foreach git clean -fdx ``` > **官方警告**：上面第二条命令会删除源码树中所有**不被 git 跟踪**的文件。跑之前务必备份你的日志文件和配置选项。 **开启 ccache 构建**： ```bash cmake -DWITH_CCACHE=ON .. ``` `ccache` 在大多数发行版里都有包。更多关于 run modes 见 https://ccache.samba.org/manual.html#_run_modes ；默认设置用 `ccache -s` 查看。 **官方推荐**：覆盖 `max_size`（默认 10G），用更大的值，比如 **25G**。配置说明见 https://ccache.samba.org/manual.html#_configuration **进一步提高缓存命中率**：在开发环境里把版本信息和构建时间戳固定下来，这样包含这些信息的二进制就不必每次重建。做法是在 `ccache.conf` 里加： ```text sloppiness = time_macros run_second_cpp = true ``` 然后把环境变量 `SOURCE_DATE_EPOCH` 设成一个固定的 UNIX 时间戳，并在跑 `cmake` 时把 `ENABLE_GIT_VERSION` 设为 `OFF`： ```bash export SOURCE_DATE_EPOCH=946684800 cmake -DWITH_CCACHE=ON -DENABLE_GIT_VERSION=OFF .. ``` > **官方警告**：用这些选项编出来的二进制**不适合生产或调试用途**，因为它们不包含正确的构建时间和 git 版本信息。 ### 1.3.10 开发模式集群与 Kubernetes/Rook - 开发模式集群：见 `/dev/quick_guide`（不在本册范围）。 - Kubernetes/Rook 开发集群：见 `kubernetes-dev` 引用（不在本册范围）。 ### 1.3.11 Backporting（回移） **所有 bugfix 都应先合到 `main` 分支，然后再 backport。** 给 bugfix 打 backport 标记的方法： 1. 确保它关联了一个 tracker issue； 2. 把该 issue 的 **`Backport` 字段**设为你认为需要回移的先前版本的**逗号分隔列表**（例如 `hammer,jewel`）； 3. **你自己负责你提出的 PR 的 backport 工作**（You are responsible for the backporting of pull requests that you raise）。 ### 1.3.12 Dependabot Dependabot 是 GitHub 的机器人，扫描仓库依赖里的安全漏洞（CVE）。如果发现可用修复，它会自动开 PR 升级依赖，并给出**兼容度评分**（基于该修复在其他 GitHub 仓库引发的 CI 失败数量）。经过配置后它也可以做非安全更新（升到最新的 minor 或 patch 版本）。 支持的语言和包管理器见 GitHub 官方文档。**截至 2022 年 7 月**，Ceph 项目只接收来自 **pip**（基于 `requirements.txt`）和 **npm**（`package*.json`）的告警；可以扩展到 git submodules、Golang、Java；**C++ 包管理器（vcpkg、conan、C++20 modules）当时没有支持**。 官方提醒：Dependabot 发现的很多依赖，其实在 Ceph GitHub 仓库之外更新更合适（比如发行版软件包）。但Dependabot 生成的新增/现存漏洞清单依然有用。 示例 PR：https://github.com/ceph/ceph/pull/46998 ### 1.3.13 cluster log 使用指引 如果你的 patch 会向 Ceph cluster log 输出消息，官方要求你先读 `/dev/logging`（不在本册范围）。 > 引自：[Essentials (tl;dr)](https://docs.ceph.com/en/tentacle/dev/developer_guide/essentials/) ## 1.4 代码库结构：`src/` 目录布局 > ⚠️ **文档未明确**：`doc/dev/developer_guide/` 下的 18 个页面**没有提供 `src/` 目录布局表**。本节下方表格中的路径，全部是本册 18 个源文里**实际出现过、可被确证**的路径；不属于「官方给出的目录布局说明」。完整的 `src/` 布局在官方文档中未明确（`/dev/internals` 可能有零散说明，但不在本册源文范围内）。 下表汇总本册源文里明确提到的路径及其内容： | 路径 | 内容 | 出现于 | |---|---|---| | `src/vstart.sh` | vstart 脚本本体，在本机启动单节点 Ceph 集群。是 Ceph Dashboard 三种最常用开发环境的基础 | `dash-devel.rst` | | `build/` | 构建目录。`vstart.sh` 通常从这里调用；`out/osd.0.pid` 在这里 | `debugging-gdb.rst`、`dash-devel.rst` | | `build/bin/` | 编译产物二进制目录。`vstart_runner.py` 会在这里检查第一个参数对应的二进制是否存在 | `running-tests-locally.rst` | | `build/out/` | 日志输出目录（`vstart` 提示 `see out/*`）；单测客户端日志 `build/out/client.admin..log` | `running-tests-locally.rst`、`tests-unit-tests.rst` | | `build/vstart_enviroment.sh` | 用于 `source` 设置环境变量，以便直接跑 workunit（注意官方文件名拼写是 `enviroment`，少一个 n） | `running-tests-locally.rst` | | `build/src/pybind/mgr/dashboard/node-env/` | Ceph 构建时创建的 nodeenv 虚拟环境，内含 `node`/`npm`，激活脚本在 `bin/activate` | `dash-devel.rst` | | `build/src/pybind/mgr/dashboard/cypress/` | Cypress 二进制缓存目录（Ceph 改写了默认位置，避免污染 `~/.cache`） | `dash-devel.rst` | | `src/CMakeLists.txt` | 单元测试在这里声明，使用 `add_ceph_test` / `add_ceph_unittest` | `tests-unit-tests.rst` | | `cmake/modules/AddCephTest.cmake` | `add_ceph_test` / `add_ceph_unittest` 这两个 CMake 函数的定义处 | `tests-unit-tests.rst` | | `src/test/cli/` | CLI 工具的测试文件，扩展名 `.t`，通过 `cram` 运行 | `tests-unit-tests.rst` | | `src/test/run-cli-tests` | 运行 CLI 测试的 shell 脚本 | `tests-unit-tests.rst` | | `src/test/dokan/dokan.cc` | Windows 端 ceph-dokan 测试源码（Windows CI 示例日志引用） | `tests-windows.rst` | | `src/pybind/` | 大多数使用 tox 的 Python 模块所在地 | `tests-unit-tests.rst` | | `src/pybind/mgr/` | Ceph Manager Python API，`tox.ini` 在 `./src/pybind/mgr/tox.ini` | `tests-unit-tests.rst` | | `src/pybind/mgr/dashboard/` | Ceph Dashboard 模块根目录（前端在 `frontend/` 子目录），有 `tox.ini` | `dash-devel.rst` | | `src/pybind/mgr/dashboard/frontend/` | Dashboard 前端（Angular）。`package.json`、`angular.json`、`proxy.conf.json.sample`、`cypress/` 都在这 | `dash-devel.rst` | | `src/pybind/mgr/dashboard/frontend/src/app/shared/components` | 可在多个页面复用的前端组件声明处 | `dash-devel.rst` | | `src/pybind/mgr/dashboard/frontend/src/app/core/error/` | 通用前端错误处理组件（`error.ts`、`DashboardError` 类） | `dash-devel.rst` | | `src/pybind/mgr/dashboard/frontend/src/testing/` | 前端单测工具集，核心是 `unit-test-helper.ts` | `dash-devel.rst` | | `src/pybind/mgr/dashboard/frontend/src/locale/messages.xlf` | `npm run i18n:extract` 生成的翻译模板（**不被 git 跟踪**） | `dash-devel.rst` | | `src/pybind/mgr/dashboard/frontend/src/styles/defaults/_bootstrap-defaults.scss` | Dashboard 所有 UI 颜色的变量定义处 | `dash-devel.rst` | | `src/pybind/mgr/dashboard/frontend/src/styles/vendor/_variables.scss` | 厂商定制：覆盖 SCSS 变量默认值 | `dash-devel.rst` | | `src/pybind/mgr/dashboard/frontend/src/styles/vendor/_style-overrides.scss` | 厂商定制：覆盖或扩展默认 CSS | `dash-devel.rst` | | `src/pybind/mgr/dashboard/frontend/src/app/shared/enum/icons.enum.ts` | 已使用图标清单（Fork Awesome 类名） | `dash-devel.rst` | | `src/pybind/mgr/dashboard/frontend/cypress/integration/visualTests/` | 视觉回归测试，命名约定 `.vrt-spec.ts` | `dash-devel.rst` | | `src/pybind/mgr/dashboard/frontend/cypress/integration/a11y/` | 无障碍（accessibility）测试 | `dash-devel.rst` | | `src/pybind/mgr/dashboard/frontend/cypress/screenshots/` | E2E 失败用例截图输出目录 | `dash-devel.rst` | | `src/pybind/mgr/dashboard/frontend/.tx/config` | transifex 配置，每个 Ceph release 一个 resource | `dash-devel.rst` | | `src/pybind/mgr/dashboard/controllers/` | Dashboard 后端控制器目录，OpenAPI 规范由这里动态生成 | `dash-devel.rst` | | `src/pybind/mgr/dashboard/plugins/` | Dashboard 插件目录 | `dash-devel.rst` | | `src/pybind/mgr/dashboard/tests/` | Dashboard 后端单测目录（如 `test_controllers.py`、`test_rgw_client.py`） | `dash-devel.rst`、`tests-unit-tests.rst` | | `src/pybind/mgr/dashboard/openapi.yaml` | 版本化的 Ceph RESTful API OpenAPI 规范 | `dash-devel.rst` | | `src/pybind/mgr/dashboard/settings.py` | `Options` 类所在文件，新增配置项在这里加 | `dash-devel.rst` | | `src/pybind/mgr/dashboard/module.py` | Dashboard 模块入口，插件需要从这里 import（目前没有动态加载） | `dash-devel.rst` | | `src/pybind/mgr/dashboard/run-backend-api-tests.sh` | 启动 vstart 集群并跑 teuthology API 测试 | `dash-devel.rst` | | `src/pybind/mgr/dashboard/run-frontend-e2e-tests.sh` | 启动 vstart 集群并跑全量前端 E2E | `dash-devel.rst` | | `src/pybind/mgr/dashboard/ci/cephadm/run-cephadm-e2e-tests.sh` | 基于 KCLI 的 cephadm E2E 测试 | `dash-devel.rst` | | `src/pybind/mgr/dashboard/ci/cephadm/start-cluster.sh` | cephadm 开发模式集群启动脚本，支持 `--dev-mode`、`--expanded` | `dash-devel.rst` | | `src/pybind/mgr/dashboard/requirements.txt` | Dashboard 后端 Python 依赖清单 | `dash-devel.rst` | | `src/pybind/mgr/dashboard/grafana_dashboards.jsonnet` | Grafana 面板的 jsonnet 源（官方写的路径是 `monitoring/grafana/dashboards/jsonnet` 目录下的 `grafana_dashboards.jsonnet`） | `dash-devel.rst` | | `src/python-common/` | Python common 模块，有 `tox.ini` | `tests-unit-tests.rst` | | `src/cephadm/` | cephadm，有 `tox.ini` | `tests-unit-tests.rst` | | `src/ceph-volume/` | ceph-volume，有多个 `tox.ini`（根目录、plugin/zfs、3 个 functional 测试目录） | `tests-unit-tests.rst` | | `src/tools/cephfs/` | CephFS 工具，有 `tox.ini` | `tests-unit-tests.rst` | | `src/script/` | 各类脚本：`run_tox.sh`、`ptl-tool.py`、`ceph-debug-docker.sh` | 多个文件 | | `src/script/ptl-tool.py` | Patrick Donnelly 的 `ptl-tool`，用于生成 merge commit | `basic-workflow.rst` | | `src/script/ceph-debug-docker.sh` | 用于分析 Teuthology 失败的调试脚本 | `debugging-gdb.rst` | | `qa/` | 集成测试与 workunit 所在目录（`qa/suites`、`qa/tasks`、`qa/workunits`） | 多个文件 | | `qa/suites/` | 集成测试的 yaml 定义（suite） | `teuthology-intro.rst` | | `qa/tasks/` | 集成测试的 Python 实现（task） | `teuthology-intro.rst` | | `qa/workunits/` | 可直接在 vstart 集群上跑的 shell 测试（如 `mon/osd.sh`） | `running-tests-locally.rst` | | `qa/tasks/vstart_runner.py` | 在本机 vstart 集群上跑 `qa/tasks/` 下 Python 测试的驱动器 | `running-tests-locally.rst` | | `qa/tasks/mgr/dashboard/` | Dashboard API 测试模块目录 | `dash-devel.rst` | | `qa/suites/rados/mgr/tasks/dashboard.yaml` | 新增 Dashboard API 测试模块后，必须把模块路径加到这个文件的 `modules` 段 | `dash-devel.rst` | | `qa/distros/supported/` | teuthology 支持的发行版列表（截至 2020 年 9 月：RHEL/CentOS 8、Ubuntu 18.04） | `teuthology-intro.rst` | | `.githubmap`（仓库根） | GitHub 用户名 → 邮箱映射，用于查 reviewer 邮箱 | `basic-workflow.rst` | | `win32_build.sh` / `win32_deps_build.sh` | Windows 构建脚本与依赖构建脚本 | `tests-windows.rst` | > 💡 补充：如果你需要一份完整的 `src/` 子目录（如 `src/osd/`、`src/mon/`、`src/mds/`、`src/common/`、`src/msg/`、`src/crimson/`）逐条说明的布局表，官方 `developer_guide` 里没有；这类内容属于 `doc/dev/internals.rst` 与 `doc/dev/osd_internals/` 的范畴，可参考本手册第 16、17、18 册。 > 引自：[Essentials (tl;dr)](https://docs.ceph.com/en/tentacle/dev/developer_guide/essentials/) ## 1.5 构建要点小结（本册范围内的） | 要点 | 做法 | |---|---| | 从源码构建 | 参见 `/install/build-ceph`，本册未展开 | | 加速重建 | `cmake -DWITH_CCACHE=ON ..`，建议 `max_size` 调到 25G | | 最大化缓存命中 | `ccache.conf` 加 `sloppiness = time_macros` + `run_second_cpp = true`；`export SOURCE_DATE_EPOCH=946684800`；`cmake -DENABLE_GIT_VERSION=OFF` | | 构建失败先清树 | `ninja clean`，再 `git clean -fdx; git submodule foreach git clean -fdx`（**会删掉未跟踪文件，先备份**） | | 带 Jaeger 构建 | `WITH_JAEGER=true ./install-deps.sh` 然后 `cmake -DWITH_JAEGER=ON ..`（见第十一章） | | 跑单测 | 顶层目录 `./run-make-check.sh`（见第五章） | --- # 二、基本工作流（fork → 分支 → 提交 → PR → 评审 → merge） 这一章来自 `basic-workflow.rst`（23KB，本册第二大的页面）。 ## 2.1 官方给出的工作流图 官方用 ditaa 画了一张图，文字化如下： ```text Upstream Code Your Local Environment /----------\ git clone /-------------\ | Ceph | -------------------------> | ceph/main | \----------/ \-------------/ ^ | | | git branch fix_1 | git merge | | v /----------------\ git commit --amend /-------------\ | ninja check |---------------------> | ceph/fix_1 | | ceph--qa--suite| \-------------/ \----------------/ | ^ | fix changes | | test changes | review | git commit | | | v /--------------\ /-------------\ | github |<---------------------- | ceph/fix_1 | | pull request | git push \-------------/ \--------------/ ``` 官方还推荐了一个视频：*Getting Started with Ceph Development*（https://www.youtube.com/watch?v=t5UIehZ1oLs，1 小时 15 分），说它是本工作流的实操总结。 ## 2.2 第 0 步：更新 tracker **先找到你打算修的 bug 的 Redmine issue 号；如果没有，就创建一个。** **唯一不需要建 tracker issue 的情况：minor documentation changes（文档的小改动）。** | 文档改动类型 | 是否需要 tracker issue | |---|---| | 简单的文档清理（simple documentation cleanup） | **不需要** | | 新增文档章节或文件 | 需要（属 major） | | 对文档结构或内容做实质性改动 | 需要（属 major） | 写 ticket 标题时的自检问题（官方原话）：**「如果两年后我要搜这个 ticket，我最可能搜哪些关键词？」**——然后把这些关键词放进标题。描述里要有详细的信息。 如果权限够，把 `Assignee` 设成自己；权限不够就在评论里写一句「I am working on this issue」。 ## 2.3 Ceph 工作流总览：三个仓库 | # | 仓库 | 说明 | |---|---|---| | 1 | `ceph/ceph` | upstream repository（上游仓库） | | 2 | `your_github_id/ceph` | 你的 fork | | 3 | 本地工作副本 | 你工作站上的 clone | 完整步骤： 1. **配置本地环境** 1. 创建 fork 2. clone fork 到本地 2. **修 bug** 1. 同步本地 main 与 upstream main 2. 在本地工作副本创建 bugfix 分支 3. 改代码 4. push 到你的 fork 3. **开 PR**：请求把改动合入 upstream Ceph ## 2.4 准备本地工作副本（仅首次需要） ### 2.4.1 创建 fork GitHub 文档：https://help.github.com/articles/fork-a-repo/#platform-linux 简言之：如果你的 GitHub 用户名是 `mygithubaccount`，你的 fork 就在 `https://github.com/mygithubaccount/ceph`。 ### 2.4.2 Clone 你的 fork ```bash git clone https://github.com/mygithubaccount/ceph ``` > **必须先 fork 再 clone。** 不 fork 就没法开 GitHub pull request。 ### 2.4.3 配置本地环境（生成 Signed-off-by 的必要步骤） 这一节的命令是为了让本地 git 生成 `Signed-off-by:` 标签，并让本地环境能与 upstream 同步。**只在初次搭建时跑一次**，但不跑就没法正常工作。 **1. 配置用户名和邮箱**（必须在 clone 出来的 `ceph/` 目录里跑）： ```bash git config user.name "FIRST_NAME LAST_NAME" git config user.email "MY_NAME@example.com" ``` **2. 把 upstream 仓库加为 remote 并 fetch：** ```bash git remote add ceph https://github.com/ceph/ceph.git git fetch ceph ``` 这两条会把 `ceph/ceph.git` 的所有分支和提交拉到本地 git 仓库，存为 `remotes/ceph/$BRANCH_NAME`，在本地命令里可以引用为 `ceph/$BRANCH_NAME`。 ## 2.5 修 bug ### 2.5.1 同步本地 main 与 upstream main 本地工作副本里 `remotes/origin/main` 是 main 分支的一个副本，叫「local main」。**它在你 clone 的那一刻就「冻结」了**，而 upstream 还在被别人持续更新，fork 会越漂越远。所以要经常同步： ```bash git fetch ceph git checkout main git reset --hard ceph/main git push -u origin main ``` 如果 `git status` 出现「Untracked files」这一行，官方让你去看 `the procedure on updating submodules`（更新子模块的步骤，本册源文未展开，**文档未明确**）。 ### 2.5.2 创建 bugfix 分支 ```bash git checkout main git checkout -b fix_1 git push -u origin fix_1 ``` 三条命令的含义： | 命令 | 作用 | |---|---| | `git checkout main` | 确保 bugfix 分支 `fix_1` 是从 upstream main 的最新状态创建的 | | `git checkout -b fix_1` | 在本地工作副本创建名为 `fix_1` 的 bugfix 分支，修 bug 的改动都提交到这个分支 | | `git push -u origin fix_1` | 把本地的 bugfix 分支推到你的 fork | ### 2.5.3 在本地改代码 1. **更新 tracker**：把 issue 状态改成 `In progress`，告诉别人你在做了，避免重复劳动。没权限就评论一句。 2. **修 bug 本身**：官方坦白说「本指南没法告诉你怎么修你选中的 bug」。多数情况下要经历多轮测试，过程是迭代的，需要 trial、error、skill 和 patience。可用的验证工具见第五章、第六章。 ### 2.5.4 提交并推送到你的 fork **提交（注意 `-as`，其中 `s` 就是 `--signoff`）：** ```bash git commit -as ``` **推送：** ```bash git push origin fix_1 ``` 关于 `origin` 的说明： ```bash $ git remote -v ceph https://github.com/ceph/ceph.git (fetch) ceph https://github.com/ceph/ceph.git (push) origin git@github.com:username/ceph.git (fetch) origin git@github.com:username/ceph.git (push) ``` 上面输出里 `origin` 那两行说明 `origin` 是你的 fork。**`origin` 不一定是你的 fork 的名字**——用 `git remote -v` 确认。 ## 2.6 开 GitHub Pull Request push 之后开 PR，让你的改动被 Ceph 贡献者社区看到、评审、可能追加测试、可能要求你改。 官方建议读： | 资源 | 链接 | |---|---| | GitHub PR 教程 | https://help.github.com/articles/using-pull-requests/ | | Git Commit Good Practice（OpenStack Wiki） | https://wiki.openstack.org/wiki/GitCommitMessages | | Ceph 自己的 Submitting Patches | https://github.com/ceph/ceph/blob/main/SubmittingPatches.rst | **开完 PR 后，去 tracker issue 里加一条评论指向你的 PR**，可以简单到只有一行： ```text *PR*: https://github.com/ceph/ceph/pull/$NUMBER_OF_YOUR_PULL_REQUEST ``` ## 2.7 Commit message 规范（本册源文能确证的部分） > ⚠️ 关于 `Fixes:` 等更细的 trailer 规范：**文档未明确**。本册源文（basic-workflow + essentials）只明确要求了下面表格里的这些；更完整的规范官方指向仓库里的 `CONTRIBUTING.rst` 与 `SubmittingPatches.rst`，本册未展开。 | 规范项 | 官方要求 | 出处 | |---|---|---| | `Signed-off-by:` | **必须有**。通过 `git commit -as`（`-s` = `--signoff`）自动追加。这也是 CI 的一个检查项（a test to check that the commits are properly signed） | `basic-workflow.rst` | | 提交前配置 | `git config user.name` / `git config user.email`，否则生成不出 `Signed-off-by` | `basic-workflow.rst` | | 前置 tracker issue | 除 minor 文档改动外，先有 Redmine issue；PR 开出来后在 issue 里留 `*PR*: ` 评论 | `basic-workflow.rst` | | Backport 标记 | 在 tracker issue 的 `Backport` 字段填逗号分隔的先前版本列表（如 `hammer,jewel`），**提交者自己负责 backport** | `essentials.rst` | | Backport 前提 | 所有 bugfix 先合到 `main`，再 backport | `essentials.rst` | | Merge commit 标题 | `doc/component: title of the commit` | `basic-workflow.rst` | | Merge commit 身体 | `Reviewed-by: Reviewer Name `（邮箱用尖括号包起来） | `basic-workflow.rst` | | PR 只含一个 commit | **最佳实践**：一个 PR 只包含一个 commit，便于保持干净的 history、简化评审、便于 merge 与 revert | `basic-workflow.rst` | | Git commit 好实践 | 见 OpenStack Wiki 的 GitCommitMessages | `basic-workflow.rst` | **最基本的 merge commit 形式（官方原文）：** ```text doc/component: title of the commit Reviewed-by: Reviewer Name ``` 两部分：被 merge 的 commit 的标题 + 评审者的姓名和邮箱。 > 💡 补充：Ceph 社区实际使用的 `Fixes: https://tracker.ceph.com/issues/NNNNN` trailer 在 `SubmittingPatches.rst` 里有规定，但该文件不在本册源文范围内，因此本册不声称它是本册所讲内容。 ## 2.8 Merge commit 的三条生成路径 ### 2.8.1 用浏览器扩展自动填充 官方推荐 **Ceph GitHub Helper Extension**（https://github.com/tspmelo/ceph-github-helper）： - Chrome：https://chrome.google.com/webstore/detail/ceph-github-helper/ikpfebikkeabmdnccbimlomheocpgkmn - Firefox：https://addons.mozilla.org/en-US/firefox/addon/ceph-github-helper/ 启用后，打开 GitHub PR 页面，右上角会出现一条竖直的 helper；点用户剪影按钮，merge message 输入框会被自动填充。 ### 2.8.2 查 reviewer 邮箱的两种方法 | 方法 | 做法 | |---|---| | `.githubmap` 文件 | 仓库里 `/ceph/.githubmap`，查 GitHub 用户名对应的邮箱 | | `git log` | 在待评审分支上跑 `git log`，评审者之前大概率提交过东西，日志里会有其邮箱 | ### 2.8.3 用 ptl-tool 生成 Patrick Donnelly 的 `ptl-tool` 位于 `/ceph/src/script/ptl-tool.py`。它生成的 merge commit 形如： ```text Merge PR #36257 into main * refs/pull/36257/head: client: move client_lock to _unmount() client: add timer_lock support Reviewed-by: Patrick Donnelly ``` ## 2.9 理解自动化的 PR 校验（CI） 创建或更新 PR 时，Ceph 的 CI 基础设施会自动测试。**官方列出的自动化检查：** 1. 检查 commit 是否正确签名（signed） 2. 检查文档能否构建（that the documentation builds） 3. 检查 submodules 未被修改（that the submodules are unmodified） 4. 检查 API 是否正常（that the API is in order） 5. **`make check` 测试** 此外，根据 PR 修改了哪些文件，**可能还会跑更多测试**。 `make check` 会构建 PR 并跑一整套测试，跑在 Ceph CI 团队运维的服务器上，结果直接显示在 GitHub 的 PR 页面里。 **官方明确要求：开 PR 之前先自己测。** ### make check 的注意事项 - GitHub 的 `make check` 由 **Jenkins 实例**驱动。 - **Jenkins 会先把你的 PR 分支 merge 进 base 分支的最新版本再开始测试**——所以你不需要为了拿到最新修复而 rebase。 - 你可以随时通过在 PR 里**发评论**触发测试，评论里要包含字符串 `test this please`。由于订阅了 PR 的人可能误以为你在请求他/她去测，官方要求**直接称呼 Jenkins**，例如写 `jenkins retest this please`。 - 只跑某一个测试可以用类似 `jenkins test signed` 的命令。这些命令列表会自动附加在每个新 PR 描述的末尾，去那里查你需要的那一条。 - 出构建失败又不确定原因，就去看 `make check` 日志：点 PR 里 `make check` 旁边的 **details** 进 Jenkins web GUI，然后点左侧的 **Console Output**。 - Jenkins 配了「已知与历史 make check 失败相关的字符串」的搜索，但**不保证这些字符串与你的失败有关**，还是得自己读日志。 ## 2.10 集成测试（ceph-qa-suite） 有时候需要在物理或虚拟硬件上的真实 Ceph 集群上测试你的修复。这类测试在 `ceph/qa` 子目录（https://github.com/ceph/ceph/tree/main/qa/）里，通过 **teuthology 框架**（https://github.com/ceph/teuthology）运行。 Ceph 社区有 **Sepia lab**（https://wiki.sepia.ceph.com/doku.php）可以在物理硬件上跑集成测试。申请访问权限从 https://wiki.sepia.ceph.com/doku.php?id=vpnaccess 开始。 **关于 `needs-qa` 与 `needs-upgrade-testing` 标签：** | 标签 | 含义 | |---|---| | `needs-qa` | 其他贡献者可能给你的 PR 加这个标签。这样可以把多个 PR 合到一条分支上一起测。teuthology suite 可能要跑几小时甚至几天，批量跑能减少资源争用、节省时间 | | `needs-upgrade-testing` | **如果你的改动会影响升级，自己加上这个标签**，表示应该安排一个升级测试 suite | ## 2.11 Code review bugfix 经过充分测试后（有时测试期间就会开始），会接受其他开发者的代码评审。形式通常是 PR 里的评论，也可能辅以 IRC、Slack 或邮件列表上的讨论。 ## 2.12 修改（amend）你的 PR 测试与评审期间，你随时可以修改本地分支里的文件。改动在本地（`fix_1` 分支）提交后，**必须 push 到 GitHub 才会出现在 PR 里**。 修改 PR 的做法：往 `fix_1` 分支加 commit，通常再 rebase 来整理 git history（rebase 入门见 https://www.atlassian.com/git/tutorials/rewriting-history）。改完之后需要 **force push**： ```bash git push --force origin fix_1 ``` **为什么要这么麻烦，而不是直接往 PR 里加 commit？** 官方给了三条理由： 1. **一个 PR 只含一个 commit 是最佳实践**，能保持干净的 history； 2. 简化 peer review； 3. 让 merge 更容易；万一（in the unlikely event）PR 需要被 revert，只有一个 commit 的 PR 回退起来也更容易。 ## 2.13 Merging 流程在项目 lead 合并你的 PR 时结束。 此时你（或合并 PR 的 lead）应该把 tracker 状态改成 **Resolved**。如果 issue 被标记了 backport，状态应改成 **Pending Backport**。 ## 2.14 杂项 git 技巧 ### `--set-upstream` 忘记加 `--set-upstream origin x` 会看到： ```text fatal: The current branch {x} has no upstream branch. To push the current branch and set the remote as upstream, use git push --set-upstream origin {x} ``` 想让 git 自动创建对应的 upstream 分支（不用每次都加参数），在 `ceph/` 目录里跑一次： ```bash git config --global push.autoSetupRemote true ``` ### 删除本地分支 ```bash git branch -d localBranchName ``` ### 删除远程分支 ```bash git push origin --delete remoteBranchName ``` （这里的「远程」指你的 fork。） ### 纵向搜索某个文件里的某个字符串是被哪次 commit 引入的 ```bash git log -S 'foo' file.rst ``` `-S ` 会找出引入/移除该字符串的 commit。 > 引自：[Basic Workflow](https://docs.ceph.com/en/tentacle/dev/developer_guide/basic-workflow/) --- # 三、Issue Tracker 与任务管理 Ceph 开发者用 issue tracker 做两件事： 1. **跟踪 issue**——bug、fix request、feature request、backport request 等； 2. **与其他开发者沟通**，让大家知道 issue 的进展。 ## 3.1 开始工作时的约定 当你开始处理某个已有 issue 时，**最好让别人知道**，避免重复劳动。典型做法： 1. 把 `Assignee` 字段改成你自己； 2. 把 `Status` 改成 **In progress**。 > **注意**：Ceph 社区的新人通常**没有足够权限**修改这些字段。这时只需在 issue 里加一条简短说明即可。 ## 3.2 常用状态的含义 | Status | Meaning | |---|---| | **New** | 初始状态 | | **In Progress** | 有人在做了 | | **Need Review** | 修复的 pull request 已开 | | **Pending Backport** | 修复已 merge，backport 待办 | | **Resolved** | 修复以及（如果有）backport 都已 merge | > 引自：[Issue Tracker](https://docs.ceph.com/en/tentacle/dev/developer_guide/issue-tracker/) --- # 四、代码合并流程（`merging.rst`） 本章回答三个问题：**什么**（What）、**合到哪**（Where）、**什么时候**（When），以及**分支之间的 merge 关系**。 > ⚠️ 本章的举例版本（hammer / infernalis / jewel / luminous / mimic / nautilus / pacific / octopus）是文档原有内容，用于说明规则，不代表 Tentacle 当前正在用的分支名。 ## 4.1 开发发布阶段（Development releases，即 x.0.z） **What（合什么）**：Features（新特性）+ Bug fixes（缺陷修复）。 **Where（合到哪）**： - Features 合到 **main** 分支。 - Bug fixes 应合到对应的 named branch，例如 14.0.z 对应 *nautilus*，16.0.z 对应 *pacific*。 - **但这不是强制的**——bug fix 和文档改进也可以合到 main，因为在开发发布阶段 main 本身也会偶尔被 merge 到 named branch。 - 无论哪种情况，如果某个 bug fix 很重要，它也可以被标记 backport 到一个或多个先前的 stable release。 **When（什么时候）**：每次 stable release 之后，先前 release 的候选分支进入 phase 2。举例：*jewel* named branch 是在 *infernalis* release candidates 进入 phase 2 时创建的。从那时起，main 就不再与 infernalis 关联。下一个 stable release 的 named branch 创建后，main 会偶尔被 merge 进去。 **Branch merges（分支合并规则）**： - 最新的 stable release 分支被**周期性**地 merge 进 main。 - main 分支被**周期性**地 merge 进 stable release 的分支。 - 每次开发版（x.0.z）发布后，main 会**立即** merge 进 stable release 分支。 ## 4.2 Stable release candidates（x.1.z）阶段 1 **What**：**只有 bug fixes**。 **Where**：stable release 分支（如 10.0.z 对应 *jewel*，12.0.z 对应 *luminous*）**或 main**。 在此阶段，**所有合到 main 的 commit 都会被 merge 到 named branch，反之亦然**。换句话说，合到 named branch 还是 main **没有区别**——反正都会进下一个 release candidate。 **When**：第一个 stable release candidate 发布之后，即在 release 分支上打了 x.1.0 tag 之后。 **Branch merges**： - stable release 分支被周期性地 merge 进 main； - main 被周期性地 merge 进 stable release 分支； - 每次 x.1.z release candidate 之后，main 立即 merge 进 stable release 分支。 ## 4.3 Stable release candidates（x.1.z）阶段 2 **What**：**只有 bug fixes**。 **Where**：stable release 分支（如 13.0.z 对应 *mimic*，15.0.z 对应 *octopus*）。 在此阶段，**所有合到 named branch 的 commit 都会被 merge 进 main**。而**往 named branch 的 cherry-pick 是手工做的**，因为正式的 backport 流程要等 release 被宣布为 "stable" 之后才开始。 **When**：CLT 宣布进入 phase 2 之后。 **Branch merges**：stable release 分支**偶尔** merge 进 main。 ## 4.4 Stable releases（x.2.z） **What**： - Bug fixes； - Features **有时**会被接受； - **尽可能从 main cherry-pick** commit； - 不是从 main cherry-pick 的 commit，**必须**是针对该 stable release 独有 bug 的修复； - 另见 backport HOWTO：http://tracker.ceph.com/projects/ceph-releases/wiki/HOWTO#HOWTO **Where**：stable release 分支（0.94.x 对应 *hammer*，9.2.x 对应 *infernalis* 等）。 **When**：stable release 发布之后，即在 release 分支上打了 "vx.2.0" tag 之后。 **Branch merges**：**Never（从不）**。 ## 4.5 四个阶段对照表 | 阶段 | 版本形态 | 合什么 | 合到哪 | 何时开始 | 分支 merge 关系 | |---|---|---|---|---|---| | Development releases | x.0.z | Features + Bug fixes | Features → main；Bug fixes → named branch（也可 main） | 每次 stable release 之后，上一批候选分支进入 phase 2 | stable ↔ main 周期性互 merge；x.0.z 发布后 main 立即合入 stable | | Stable RC phase 1 | x.1.z | **仅** Bug fixes | stable release 分支 **或** main（**等价**） | 打了 x.1.0 tag 之后 | stable ↔ main 周期性互 merge；每个 RC 后 main 立即合入 stable | | Stable RC phase 2 | x.1.z | **仅** Bug fixes | stable release 分支 | CLT 宣布进入 phase 2 | stable **偶尔** merge 进 main；反向靠手工 cherry-pick | | Stable releases | x.2.z | Bug fixes；Features 有时接受；**尽量 cherry-pick 自 main** | stable release 分支 | 打了 vx.2.0 tag 之后 | **Never** | > 💡 补充：把四个阶段串起来的直觉是——越接近发布，收得越紧：从「什么都能合」到「只收 bugfix」到「只收 bugfix 且主方向只剩单向」，最后 stable 分支完全不再与其他分支互相 merge，只靠 backport（cherry-pick）单点进补丁。 > 引自：[Commit merging: scope and cadence](https://docs.ceph.com/en/tentacle/dev/developer_guide/merging/) --- # 五、本地运行测试（单元测试与 workunit） ## 5.1 Ceph 的两类测试 Ceph GitHub 仓库有两类测试： | 类型 | 也称 | 特征 | |---|---|---| | **Unit tests** | `make check` tests | 从源码编译完 Ceph 后，能在**单台构建机器**上轻松跑起来的测试 | | **Integration tests** | teuthology tests | 需要**安装软件包**、需要**多机集群**才能跑的测试 | 官方特意说明：**严格来说 `make check` 测试并不是「单元测试」**，只是因为它们能在单机构建环境下跑，才被归为一类。 ## 5.2 「make check」是什么意思 编译完 Ceph 后，代码可以跑一整套测试。由于历史原因，这套测试常被称为 `make check`，**尽管实际用来跑测试的命令现在是 `ctest`**。 **一个测试要被纳入这一类，必须满足：** - 绑定的端口不与其他测试冲突； - 不需要 root 权限； - 不需要多于一机器就能跑； - 在几分钟内完成。 为简化表述，这类测试被称为 "make check tests" 或 "unit tests"，用来和更复杂的、通过 teuthology 框架运行的 "integration tests" 区分开。 虽然可以直接跑 `ctest`，但**正确设置环境比较麻烦**。官方提供了一个脚本，从 Ceph 源码树顶层目录调用即可： ```bash ./run-make-check.sh ``` **资源要求（官方给出）**：x86_64 架构上至少需要 **8GB RAM 和 32GB 可用磁盘空间**；其他架构要求可能不同。根据硬件不同，**耗时从 20 分钟到 3 小时不等**。 ## 5.3 单元测试是怎么声明的 单元测试在 **`./src` 目录的 `CMakeLists.txt`** 里声明，使用两个 CMake 函数： | 函数 | 用途 | |---|---| | `add_ceph_test` | 声明**脚本形式**的单元测试 | | `add_ceph_unittest` | 声明**二进制形式**的单元测试（编译期生成的可执行文件） | 这两个函数本身定义在 **`./cmake/modules/AddCephTest.cmake`**。 ## 5.4 CLI 工具的单元测试 部分 CLI 工具用扩展名为 **`.t`** 的特殊文件测试，存放在 **`./src/test/cli`** 下。这些测试通过 **`cram`**（https://bitheap.org/cram/）运行，驱动脚本是 **`./src/test/run-cli-tests`**。 不适合放进 `make check` 的 cram 测试，也可以由 teuthology 通过 **cram task**（https://github.com/ceph/ceph/blob/master/qa/tasks/cram.py）来跑。 ## 5.5 基于 Tox 的 Python 模块测试 Ceph 的部分 Python 模块使用 **tox**（https://tox.readthedocs.io/en/latest/）跑单元测试，这些模块大多在 **`./src/pybind/`** 下。 **官方列出的（截至 2020 年 12 月）使用 tox 的模块清单：** | 模块 | tox.ini 位置 | |---|---| | Cephadm | `./src/cephadm/tox.ini` | | Ceph Manager Python API | `./src/pybind/mgr/tox.ini` | | Dashboard | `./src/pybind/mgr/dashboard/tox.ini` | | （mgr 下另有） | `./src/pybind/tox.ini` | | Python common | `./src/python-common/tox.ini` | | CephFS | `./src/tools/cephfs/tox.ini` | | ceph-volume | `./src/ceph-volume/tox.ini` | | ceph-volume zfs plugin | `./src/ceph-volume/plugin/zfs/tox.ini` | | ceph-volume batch functional | `./src/ceph-volume/ceph_volume/tests/functional/batch/tox.ini` | | ceph-volume simple functional | `./src/ceph-volume/ceph_volume/tests/functional/simple/tox.ini` | | ceph-volume lvm functional | `./src/ceph-volume/ceph_volume/tests/functional/lvm/tox.ini` | ### 5.5.1 查看 tox 的环境与任务列表 大多数 tox 配置支持多个 environment 和 task，清单在 `tox.ini` 的 **`envlist`** 里。例如 `./src/cephadm/tox.ini` 的前三行： ```ini [tox] envlist = py3, mypy skipsdist=true ``` 这个例子指定了 `Python 3` 和 `mypy` 两个环境。 列出环境： ```bash tox --list ``` 或 ```bash tox -l ``` ### 5.5.2 运行 tox 在包含 `tox.ini` 的目录里直接执行 `tox` 即可。如果不指定环境（例如 `-e $env1,$env2`），**tox 会跑所有环境**。Jenkins 通过执行 **`./src/script/run_tox.sh`** 来跑 tox。 Ceph Dashboard 的示例： ```bash ## Run Python 2+3 tests+lint commands: tox -e py27,py3,lint,check ## Run Python 3 tests+lint commands: tox -e py3,lint,check ## To run it as Jenkins would: ../../../script/run_tox.sh --tox-env py3,lint,check ``` ### 5.5.3 Manager core 单元测试 目前**只跑 `mgr_util.py` 里的 doctests**（https://docs.python.org/3/library/doctest.html）。 要往 manager core 里加更多被测文件，打开 `tox.ini`，把文件加到**包含 `mgr_util.py` 的那一行末尾**。 ## 5.6 单元测试的两个注意事项（caveats） 1. **内存分配器**：与各个 Ceph 守护进程和 `ceph-fuse` 不同，单元测试**默认链接到系统默认的内存分配器（glibc）**，除非显式链接到别的。这样做的目的是**让 valgrind 这类工具能在测试中使用**。 2. **Google Test 会隐藏客户端输出**。要调试客户端，先设好 debug level（例如 `ceph config set client debug_rbd 20`），然后去 **`build/out/client.admin..log`** 找日志文件。这在查看 teuthology 里失败的单元测试 job 时也很有用——可以在相关的 yaml 文件里设置 job 的 debug level。 > 引自：[Testing - unit tests](https://docs.ceph.com/en/tentacle/dev/developer_guide/tests-unit-tests/) ## 5.7 在本地跑 s3-tests（RGW） RGW 代码可以这样测：本地从源码构建 Ceph → 起一个 vstart 集群 → 跑 "s3-tests" suite。以下步骤在 jewel 及以上应该可用。 **Step 1 - 构建 Ceph**：参见 `/install/build-ceph`。（Step 2 可以在构建期间并行做。） **Step 2 - vstart**。构建完成后，仍在 git clone 的顶层目录里： ```bash cd build/ RGW=1 ../src/vstart.sh -n ``` 会输出很多内容，最后应看到类似： ```text started. stop.sh to stop. see out/* (e.g. 'tail -f out/????') for debug output. ``` 表示集群已跑起来。 **Step 3 - 跑 s3-tests**： ```bash ../qa/workunits/rgw/run-s3tests.sh ``` ## 5.8 用 `vstart_runner.py` 跑测试（CephFS / Mgr） CephFS 和 Ceph Manager 的代码用 **`vstart_runner.py`** 测试。 ### 5.8.1 安装 teuthology（前置） Ceph 仓库里的 Python 测试要在本机执行，需要装 `teuthology`： ```bash git clone https://github.com/ceph/teuthology cd teuthology ./bootstrap install ``` 这会在 teuthology 仓库根目录创建一个名为 `virtualenv` 的虚拟环境并安装 teuthology。 也可以用 `pip` 装到自定义虚拟环境（同时用 git clone 一份 teuthology 仓库）： ```bash virtualenv --python=python3 venv source venv/bin/activate pip install 'setuptools >= 12' pip install teuthology[test]@git+https://github.com/ceph/teuthology deactivate ``` 如果上面两种方式都不行（比如 bootstrap 脚本有 bug 或暂时下载不到），可以从本机已有的 teuthology 仓库副本手动安装： ```bash cd teuthology virtualenv -p python3 venv source venv/bin/activate pip install -r requirements.txt pip install . deactivate ``` ### 5.8.2 跑你的第一个测试 先成功构建 Ceph，然后： ```bash cd build ../src/vstart.sh -n -d -l source ~/path/to/teuthology/venv/bin/activate ``` 跑一个具体的测试（例如 `qa/tasks/cephfs/test_client_recovery` 里 `TestClientRecovery` 类的 `test_reconnect_timeout`）： ```bash python ../qa/tasks/vstart_runner.py tasks.cephfs.test_client_recovery.TestClientRecovery.test_reconnect_timeout ``` 也可以按组跑： ```bash $ # run all tests in class TestClientRecovery $ python ../qa/tasks/vstart_runner.py tasks.cephfs.test_client_recovery.TestClientRecovery $ # run all tests in test_client_recovery.py $ python ../qa/tasks/vstart_runner.py tasks.cephfs.test_client_recovery ``` `vstart_runner.py` 根据传入的参数收集测试并像跑单个测试一样执行它们。 ### 5.8.3 `vstart_runner.py` 的命令行选项 | 选项 | 说明 | |---|---| | `--clear-old-log` | 跑测试前删除旧日志文件 | | `--create` | 跑测试前创建 Ceph 集群 | | `--create-cluster-only` | 只创建集群然后退出，测试可以稍后再发 | | `--interactive` | 测试失败时进入 Python shell | | `--log-ps-output` | 记录 ps 输出，调试时有用 | | `--teardown` | 测试跑完后拆掉 Ceph 集群 | | `--kclient` | 用内核 cephfs 客户端而不是 FUSE | | `--brxnet=` | 为 mount 客户端的网络命名空间容器指定新的 net/mask（默认 `192.168.0.0/16`） | 三条官方 note： - 用 FUSE 客户端时，确保系统装了并启用了 fuse 包，且 `/etc/fuse.conf` 里加了 `user_allow_other`。 - 用内核客户端时，用户必须能**免密 sudo**。 - 内核客户端上的失败**可能导致宿主机崩溃**，建议在虚拟机里用这个功能。 ### 5.8.4 `vstart_runner.py` 的内部工作机制 它主要做三件事： 1. **收集并运行测试**：setup/teardown 集群，收集并运行测试。由 `scan_tests()`、`load_tests()`、`exec_test()` 三个方法实现。所有命令行选项以及「记录日志」「把 traceback 复制到日志底部」等特性都在这里实现。 2. **提供下发与测试 shell 命令的接口**：测试是假设集群在远程机器上写的。`vstart_runner.py` 提供接口，让同样的测试能跑在本机的集群上。这靠 class `LocalRemote` 实现；`LocalRemoteProcess` 管理执行 `LocalRemote` 命令的进程，`LocalDaemon` 提供操作 Ceph 守护进程的接口，`LocalFuseMount` 创建并管理 FUSE mount。 3. **提供操作 Ceph 集群的接口**：`LocalCephManager` 提供带/不带 admin socket 执行 Ceph 集群命令的方法；`LocalCephCluster` 提供设置或清除 `ceph.conf` 的方法。 三条实现细节 note： - `vstart_runner.py` **无条件**从命令参数里删除 `adjust-ulimits` 和 `ceph-coverage`，因为它们在开发者本机上不适用。 - 对于 `passwd` 和 `chown` 命令，`omit_sudo` 会被**无条件重置为 False**。 - 会检查 `/build/bin/` 下是否存在与第一个参数同名的二进制文件；如果存在，第一个参数会被替换为该二进制文件的路径。 ## 5.9 用 `vstart_enviroment.sh` 跑 workunit 和 s3-tests 类似，其他 workunit 也可以配置好环境后直接对着 vstart 集群跑。 **设置环境：** ```bash . ./build/vstart_enviroment.sh ``` > ⚠️ 注意官方文件名是 `vstart_enviroment.sh`（**enviroment**，不是 environment），这是官方文档里就有的拼写。 **跑一个 workunit（例如 `mon/osd.sh`）：** ```bash ./qa/workunits/mon/osd.sh ``` > 引自：[Running Unit Tests](https://docs.ceph.com/en/tentacle/dev/developer_guide/running-tests-locally/) ## 5.10 三类本地测试对比 | 测试方式 | 适用代码 | 前置条件 | 命令 | |---|---|---|---| | `make check` / `ctest` | 通用 C++ 单元测试 | 编译完 Ceph；8GB RAM / 32GB 磁盘 | `./run-make-check.sh`（或手工 `ctest`） | | `cram`（`.t` 文件） | CLI 工具 | `./src/test/cli` 下的 `.t` 文件 | `./src/test/run-cli-tests` | | `tox` | Python 模块（cephadm / mgr / dashboard / python-common / cephfs / ceph-volume） | 装 `tox`、`coverage` | `tox -e py3,lint,check` 或 `../../../script/run_tox.sh --tox-env py3,lint,check` | | s3-tests | RGW | 编译 + `RGW=1 ../src/vstart.sh -n` | `../qa/workunits/rgw/run-s3tests.sh` | | `vstart_runner.py` | CephFS、Mgr Python 测试 | 装 teuthology + `../src/vstart.sh -n -d -l` | `python ../qa/tasks/vstart_runner.py tasks.cephfs...` | | workunit | 通用 shell 测试 | `. ./build/vstart_enviroment.sh` | `./qa/workunits/.sh` | --- # 六、集成测试与 teuthology `testing_integration_tests/` 目录下共 6 个文件：`index.rst`、`tests-integration-testing-teuthology-intro.rst`（约 27KB，本册第三大）、`-workflow.rst`（18KB）、`-debugging-tips.rst`、`-kernel.rst`、`tests-sentry-developers-guide.rst`。 ## 6.1 什么是集成测试 Ceph 有两类测试：`make check` 测试和集成测试。**当一个测试需要多台机器、需要 root 权限、或者持续时间很长（例如要模拟真实的 Ceph 工作负载），它就被认定为集成测试。** 集成测试被组织成 **suites**，定义在 `ceph/qa` 子目录（https://github.com/ceph/ceph/tree/master/qa），用 **`teuthology-suite`** 命令运行。该命令是 teuthology 框架（https://github.com/ceph/teuthology）的一部分。 ### 6.1.1 关键认知：Teuthology 消费的是**软件包** 官方特别强调这一点「需要点时间才能理解其意义，但它极其重要」：**这意味着自动化测试可以在多个平台上使用与任意运行这些平台的机器所能安装的相同软件包（RPM、DEB）来进行。** teuthology 有一份支持的平台清单（https://github.com/ceph/ceph/tree/master/qa/distros/supported），**截至 2020 年 9 月，清单是「RHEL/CentOS 8」和「Ubuntu 18.04」**。它期望拿到这些平台的**预构建 Ceph 软件包**，然后按测试要求把这些平台部署到机器上（裸金属或云供给的），装包，部署 Ceph 集群。 ### 6.1.2 The Nightlies 大量集成测试会**定期**在 Sepia lab（https://wiki.sepia.ceph.com/doku.php）里针对 Ceph 官方仓库（`master` 开发分支和 stable 分支）跑。传统上叫 "the nightlies"（夜间测试），因为 Ceph 核心开发者过去住在同一时区，从他们的视角看测试是在 overnight 跑的。 结果发布在 http://pulpito.ceph.com/ 的 `teuthology` 用户下。开发者 nick 出现在测试结果 URL 里以及 Pulpito dashboard 的第一列。结果也会报到 ceph-qa 邮件列表（https://ceph.com/irc/）。 ## 6.2 测试优先级（Testing Priority）：务必设置 `-p ` 且 N < 500 `teuthology-suite` 有 `-p ` 选项，指定提交到队列的 job 优先级。**`N` 越小，优先级越高。** **`N` 的默认值是 1000。** 由 `teuthology@teuthology.front.sepia.ceph.com` 自动调度的大多数 nightly 测试都以 `N >= 500` 跑。一些关键的 nightly 测试会给更高优先级，比如 smoke 测试或即将发布的重大版本的 QA 跑。 > 官方 note：nightly 期间要跑的测试量经常大到**在 allotted 时间内跑不完全部 nightly 测试**。 **如果不把 `N` 设到 500 以下，你的测试优先级不会高于 nightly 测试——这意味着它们可能永远跑不起来。** **优先级取值指南（官方表格）：** | 优先级 | 适用场景 | |---|---| | **N < 10** | 天塌下来了，某组测试必须立刻跑 | | **10 <= N < 50** | 你的测试很紧急，正阻塞其他重要开发 | | **50 <= N < 75** | 你在测某个 feature/fix，且跑的 job 少于约 25 个；也用于紧急的 release 测试 | | **75 <= N < 100** | Tech Leads 常规用来针对 master 验证 PR 的优先级 | | **100 <= N < 150** | 点发布（point release）的 QE 验证 | | **150 <= N < 200** | 测某个 feature/fix，100 个 job 或更少；约 24 小时出结果 | | **200 <= N < 500** | 大规模测试跑；约一周出结果 | **两个配套选项：** | 选项 | 用途 | |---|---| | `--dry-run` | 先看这条命令会触发多少 job。数量满意后，去掉 `--dry-run` 并加上 `-p <合适的数字>` 再跑一次 | | `--force-priority` | 跳过优先级检查。官方要求：**体谅其他开发者也要跑测试，只在紧急情况下用** | ## 6.3 Suites Inventory（suite 清单） `ceph/qa` 子目录的 `suites` 目录包含所有 Ceph 组件的集成测试。 | Suite | 功能 | |---|---| | `ceph-deploy` | 用 `ceph-deploy` 安装 Ceph 集群 | | `dummy` | 拿一台机器，什么都不做，返回成功。常用来验证集成测试基础设施本身是否正常 | | `fs` | 测试用 kernel 和 FUSE 客户端挂载的 CephFS，也测多 MDS | | `krbd` | 测试 RBD 内核模块 | | `powercycle` | 验证机器断电再上电时 Ceph 集群的行为 | | `rados` | 在各种压力条件下运行含 OSD 和 MON 的 Ceph 集群 | | `rbd` | 用真实 Ceph 集群跑 RBD 测试，带 qemu 和不带 qemu 都有 | | `rgw` | 用真实 Ceph 集群跑 RGW 测试 | | `smoke` | 用真实 Ceph 集群跑调用 Ceph API 的测试 | | `teuthology` | 验证 teuthology 能跑集成测试，带 OpenStack 和不带都有 | | `upgrade` | 对各个版本的 Ceph，验证升级能在不中断进行中工作负载的前提下完成 | ## 6.4 teuthology-describe `teuthology-describe` 被加入 teuthology 框架，是为了**便于文档化集成测试并增进理解**。 做法是：在定义测试的 yaml 文件里嵌入 **`meta:` 注解**。查看效果：https://gist.github.com/jdurgin/09711d5923b583f60afc 由于这是个新特性，**很多 yaml 文件还没被注解过**。官方鼓励开发者去提高文档的覆盖率和质量。 ## 6.5 怎么跑集成测试 - 通常用 **Sepia lab** 跑。但作为 Ceph 新开发者，你**多半没有 Sepia lab 访问权限**；不过你可能能在 Sepia lab 之外的环境里跑一部分集成测试。**去问相关团队的成员**怎么弄。 - 一种方式是在**裸金属上搭 teuthology 集群**，这是件复杂的活儿。入门笔记：https://docs.ceph.com/projects/teuthology/en/latest/LAB_SETUP.html - 每个 teuthology 集群（无论裸金属还是云供给）都有一台所谓的 **teuthology machine**，从那台机器上用 `teuthology-suite` 命令触发测试 suite。 - 在该机器上跑下面的命令可拿到每个 `teuthology-suite` 选项的最新详尽说明： ```bash teuthology-suite --help ``` `teuthology-suite` 在线文档：https://docs.ceph.com/projects/teuthology/en/latest/commands/teuthology-suite.html **为什么要跑并把结果发出去**：在你贡献的代码上跑集成测试并发布结果，能让评审者验证改动没有引入回归，也能在测试失败时让评审者分析失败原因。 ## 6.6 集成测试是怎么定义的 集成测试由 `ceph/qa` 子目录下 **`suites` 子目录里的 yaml 文件**定义，由 **`tasks` 子目录里的 python 代码**实现。 - 有些测试（"standalone tests"）定义在**单个 yaml 文件**里； - 其他测试由**一棵含若干 yaml 文件的目录树**定义，运行时这些 yaml 会被组合成一个更大的 yaml 文件。 ## 6.7 读一个 standalone test（单例） 以 `rados/singleton/all/admin-socket.yaml` 为例： ```yaml roles: - - mon.a - osd.0 - osd.1 tasks: - install: - ceph: - admin_socket: osd.0: version: git_version: help: config show: config set filestore_dump_file /tmp/foo: perf dump: perf schema: ``` **`roles` 数组**：决定这个测试运行在什么样的集群构成上（几个 MON、几个 OSD 等），以及这些 role 如何分布到测试集群的机器上。 - 顶层数组只有一个元素 → 只给这个测试分配**一台机器**； - 嵌套数组声明这台机器要跑一个 id 为 `a` 的 MON（`mon.a`）和两个 OSD（`osd.0`、`osd.1`）。 **`tasks` 数组**是测试主体：每个元素**按顺序求值**，导致 `tasks` 子目录（teuthology 仓库的，或 `ceph/qa` 子目录的）里对应的 python 文件被运行。"运行" 在这里指的是**调用该文件里定义的 `task()` 函数**。 | 本例的 task | 作用 | |---|---| | `install` | 在每台机器上安装 Ceph 软件包（按 `roles` 数组定义）。完整描述见 https://github.com/ceph/teuthology/blob/master/teuthology/task/install/__init__.py（搜 "def task"） | | `ceph` | 按 `roles` 数组要求启动 OSD 和 MON（可能还有 MDS），源码见 https://github.com/ceph/ceph/blob/master/qa/tasks/ceph.py（搜 "def task"）。本例会启动一个 MON（`mon.a`）和两个 OSD（`osd.0`、`osd.1`），都在同一台机器上。**当 Ceph 集群达到 `HEALTH_OK` 状态时，控制流才转到下一个 task** | | `admin_socket` | 源码 https://github.com/ceph/ceph/blob/master/qa/tasks/admin_socket.py。它的参数（任何 task 的参数都一样）是一个结构，解释方式由该 task 文档化。本例的参数是发给 `osd.0` 的 admin socket 的一组命令；task 会验证**每条命令都返回成功（exit code 为零）** | **运行这个测试：** ```bash teuthology-suite --machine-type smithi --suite rados/singleton/all/admin-socket.yaml fs/ext4.yaml ``` ## 6.8 Test descriptions（测试描述） 每个测试有一个 "test description"，**类似目录路径，但不完全是**。 - **standalone test** 的描述：等同于定义它的 yaml 文件**从 `suites/` 目录开始的相对路径**。 - **更常见的情况**：测试不是由单个 yaml 文件定义，而是由**一棵 yaml 文件目录树**定义。运行时遍历这棵树，所有 yaml 文件（**facets**）被组合成更大的 yaml "programs" 来定义测试。**每个测试日志开头都会包含定义该测试的完整 yaml 清单。** 这类测试的描述 = `suites/` 下包含 yaml facets 的子目录 + 一个**花括号 `{}` 表达式**，里面是按拼接顺序排列的 yaml facet 列表。例如： ```text ceph-deploy/basic/{distros/centos_7.0.yaml tasks/ceph-deploy.yaml} ``` 表示两个文件按顺序拼接： 1. `ceph-deploy/basic/distros/centos_7.0.yaml` 2. `ceph-deploy/basic/tasks/ceph-deploy.yaml` ## 6.9 测试是怎么从目录构建出来的：三个特殊文件操作符 一组给定 `suites/` 子目录所定义的所有测试，称为一个 "integration test suite"，或 "teuthology suite"。 **yaml facets 的组合由放在目录树里的特殊文件控制，可以看作操作符：** | 特殊文件 | 名字 | 含义 | |---|---|---| | `%` | **convolution（卷积）** 操作符 | 从该目录下各子目录里的 yaml facets 构造测试矩阵 | | `+` | **concatenation（拼接）** | 把一个目录内的文件拼接在一起 | | `$` | **random selection（随机选择）** | 提示 teuthology 随机包含一个 YAML fragment | ### 6.9.1 卷积操作符 `%` `%` 是一个（通常为空的）文件，告诉 teuthology 从**包含该操作符的目录下面的各子目录**里的 YAML facets 构造测试矩阵。 以 `ceph-deploy` suite 为例，目录结构： ```text qa/suites/ceph-deploy ├── % ├── distros │ ├── centos_latest.yaml │ └── ubuntu_latest.yaml └── tasks ├── ceph-admin-commands.yaml └── rbd_import_export.yaml ``` 被解释为一个 2x1 矩阵，产生两个测试： 1. `ceph-deploy/basic/{distros/centos_7.0.yaml tasks/ceph-deploy.yaml}` 2. `ceph-deploy/basic/{distros/ubuntu_16.04.yaml tasks/ceph-deploy.yaml}` 人话：**`ceph-deploy.yaml` 里的 task 打算在 CentOS 7.0 和 Ubuntu 16.04 上都跑一遍。** **如果没有 `%` 文件**，`ceph-deploy` 树会被解释成三个 standalone 测试： - `ceph-deploy/basic/distros/centos_7.0.yaml` - `ceph-deploy/basic/distros/ubuntu_16.04.yaml` - `ceph-deploy/basic/tasks/ceph-deploy.yaml` （这当然是错的。） > **symlink 技巧**：`suites/ceph-deploy/basic/distros/` 里的 `centos_7.0.yaml` 和 `ubuntu_16.04.yaml` 是**符号链接**。用 symlink 而不是复制，可以让一个文件出现在多个 suite 里，降低整个测试框架的维护成本。 跑整个 ceph-deploy suite： ```bash teuthology-suite --machine-type smithi --suite ceph-deploy ``` 跑其中一个测试（加 `--filter`）： ```bash teuthology-suite \ --machine-type smithi \ --suite ceph-deploy/basic \ --filter 'ceph-deploy/basic/{distros/ubuntu_16.04.yaml tasks/ceph-deploy.yaml}' ``` > 官方 note：跑 standalone test **只用 `--suite` 就够了**。但如果想跑一个「由目录树定义的 suite」里的单个测试，**`--suite` 必须配合 `--filter`**，因为 `--suite` 选项只认 POSIX 相对路径。 ### 6.9.2 Nested Subsets（嵌套子集） suite 会因为 yaml 配置的组合爆炸而变得非常大：**写作时 `rados` suite 有超过 100,000 个 job**。因此调度时常用 `--subset` 只跑一部分 job。但这**只在被跑 suite 的顶层生效**（例如 `fs`），这可能**顺带放大了**某些较大子 suite（如 `fs:workload`）相对某些较小但关键的子 suite（如 `fs:volumes`）的 job 占比。 因此，对那些**永远不会被完整跑**的子 suite 自动做子集化是很有吸引力的。做法：**给 `%` 卷积操作符文件里写一个整数除数**，而不是留空。该除数会自动对生成的矩阵做子集化。例如 `%` 文件里内容是 `2`，矩阵就会用与 `--subset` 相同的逻辑被一分为二。 注意：**分子不像 `--subset` 选项那样指定**，因为在可能有多层嵌套的情况下没法有意义地表达。取而代之的是**随机选一个子集**（上例就是 2 选 1）。选择基于调度时用的随机种子（**`--seed`**）。**记住种子会被保存在结果里**，这样对失败测试做 `--rerun` 时仍能保持正确的分子（subset of subsets）。 可以用 **`--no-nested-subset`** 参数禁用嵌套子集。 ### 6.9.3 拼接操作符 `+` 为了在 suite 之间共享 yaml 文件时获得更大的灵活性，可以在一个目录里放特殊文件 `+`，把该目录内的文件拼接起来。 以 `suites/rbd/thrash` 为例： ```text qa/suites/rbd/thrash ├── % ├── clusters │ ├── + │ ├── fixed-2.yaml │ └── openstack.yaml └── workloads ├── rbd_api_tests_copy_on_read.yaml ├── rbd_api_tests.yaml └── rbd_fsx_rate_limit.yaml ``` 这产生两个测试： - `rbd/thrash/{clusters/fixed-2.yaml clusters/openstack.yaml workloads/rbd_api_tests_copy_on_read.yaml}` - `rbd/thrash/{clusters/fixed-2.yaml clusters/openstack.yaml workloads/rbd_api_tests.yaml}` 因为 `clusters/` 子目录里有特殊文件 `+`，该目录里其他所有文件（`fixed-2.yaml` 和 `openstack.yaml`）被**拼接成一个文件**对待。 **如果没有 `+`**，它们会和 workloads 目录里的文件做卷积，产生 2x2 矩阵四个测试： - `rbd/thrash/{clusters/openstack.yaml workloads/rbd_api_tests_copy_on_read.yaml}` - `rbd/thrash/{clusters/openstack.yaml workloads/rbd_api_tests.yaml}` - `rbd/thrash/{clusters/fixed-2.yaml workloads/rbd_api_tests_copy_on_read.yaml}` - `rbd/thrash/{clusters/fixed-2.yaml workloads/rbd_api_tests.yaml}` `clusters/fixed-2.yaml` 被很多 suite 共享，用来定义如下 `roles`： ```yaml roles: - [mon.a, mon.c, osd.0, osd.1, osd.2, client.0] - [mon.b, osd.3, osd.4, osd.5, client.1] ``` 跑整个 `rbd/thrash` suite： ```bash teuthology-suite --machine-type smithi --suite rbd/thrash ``` 跑其中一个测试： ```bash teuthology-suite \ --machine-type smithi \ --suite rbd/thrash \ --filter 'rbd/thrash/{clusters/fixed-2.yaml clusters/openstack.yaml workloads/rbd_api_tests_copy_on_read.yaml}' ``` ### 6.9.4 Upgrade Testing（升级测试） 用 upgrade suite 可以验证：**从较早版本升级能够成功完成，且不中断任何进行中的工作负载**。 **每个 release 分支的升级目录包含 2-x 升级测试**，也就是说能测**从当前版本往前 2 个版本**升级到当前版本。升级过程与其他给定工作负载**并行**进行（用 https://github.com/ceph/teuthology/blob/main/teuthology/task/parallel.py）。 以 Quincy release 分支的升级测试目录为例： ```text . ├── octopus-x └── pacific-x ``` 可以测从 Octopus（2-x）或从 Pacific（1-x）升到 Quincy（x）。 一个简单的升级测试由以下部分组成： ```text ├── 0-start.yaml ├── 1-tasks.yaml ├── upgrade-sequence.yaml └── workload ``` 先用旧版本启动集群，然后开始**并行**跑给定的 `workload` 和 `upgrade-sequence`： ```yaml - print: "**** done start parallel" - parallel: - workload - upgrade-sequence - print: "**** done end parallel" ``` `workload` 目录就是普通的 yaml 文件（和其他 suite 一样），而 `upgrade-sequence` 负责执行升级并等待其完成： ```yaml - print: "**** done start upgrade, wait" ... mon.a: - ceph orch upgrade start --image quay.ceph.io/ceph-ci/ceph:$sha1 - while ceph orch upgrade status | jq '.in_progress' | grep true ; do ceph orch ps ; ceph versions ; sleep 30 ; done ... - print: "**** done end upgrade, wait..." ``` **也可以分阶段升级，中间穿插跑工作负载：** ```text ├── % ├── 0-cluster ├── 1-ceph-install ├── 2-partial-upgrade ├── 3-thrash ├── 4-workload ├── 5-finish-upgrade.yaml ├── 6-quincy.yaml └── 8-final-workload ``` 流程：启动集群 → 只升级集群的 2/3（`2-partial-upgrade`）→ 跑 thrash 测试和给定工作负载测试 → 继续升级剩下的部分（`5-finish-upgrade.yaml`）→ 最后要求升级后的 release（`ceph require-osd-release quincy`、`ceph osd set-require-min-compat-client quincy`）并跑 `final-workload`。 ### 6.9.5 随机选择操作符 `$` 存在名为 **`$`** 的文件，会提示 teuthology **随机包含其中一个 YAML fragment**。这种场景典型地出现在：需要在若干 flavor 的 feature/option 里**随机挑一个**来测的时候。 ## 6.10 Position Independent Linking（位置无关链接） `qa/suites` 目录下**每个目录里都有 `.qa` 符号链接**，每个链接都**递归地指向 `../.qa/`**，最终终止链接在 `qa/` 目录本身：`qa/.qa -> .`。 这种符号链接布局让一个 suite **可以轻松被复制或移动而不破坏大量符号链接**。例如： ```text qa/suites/fs/upgrade/nofs/centos_latest.yaml -> .qa/distros/supported/centos_latest.yaml ``` 如果你把 `nofs` suite 复制到别处、在其上加一层父目录、或者把 `centos_latest.yaml` fragment 挪进一个子目录，**这个链接都不会断**。 对比传统写法： ```text qa/suites/fs/upgrade/nofs/centos_latest.yaml -> ../../../../distros/supported/centos_latest.yaml ``` 一旦移动，很可能会断，因为到达 `distros` 目录所需的父目录层数可能变化。 **官方建议：新增目录或 suite 时，记得一并加上 `.qa` 符号链接。** 一条 find 命令就能搞定： ```bash find qa/suites/ -type d -execdir ln -sfT ../.qa/ {}/.qa \; ``` ## 6.11 按描述过滤测试 当少数 job 失败需要重跑时，可以用 `--filter` 选出描述匹配的测试。例如 `rados` suite 里的 `all/peer.yaml` 失败了，下面这条只跑包含这个文件的测试： ```bash teuthology-suite --machine-type smithi --suite rados --filter all/peer.yaml ``` | 选项 | 作用 | |---|---| | `--filter` | 只跑描述**包含**给定字符串的测试 | | `--filter-out` | 反过来，匹配**不包含**给定字符串的测试；可以与 `--filter` 组合使用 | 两者都接受**逗号分隔的字符串列表**（这意味着 `ceph/qa` 子目录里的文件名**隐式禁止出现逗号字符**）。例如： ```bash teuthology-suite --machine-type smithi --suite rados --filter all/peer.yaml,all/rest-api.yaml ``` 会跑包含 `all/peer.yaml` **或** `all/rest-api.yaml` 的测试。 > **重要**：每个字符串是在 test description 的**任意位置**查找，且**必须是精确匹配——它们不是正则表达式**。 ## 6.12 减少测试数量 `rados` suite 从几百个文件里生成数万甚至数十万个测试，这是因为 teuthology 在**每遇到一个名为 `%` 的文件**时就从子目录构造测试矩阵。例如 `rados/basic` suite 里所有测试都会用不同的 messenger 类型（`simple`、`async`、`random`）跑，因为它们通过特殊文件 `%` 与 `msgr` 目录组合。 **所有集成测试在 Ceph 发布之前都必须跑一遍。** 但如果只是要验证一个贡献能否合入而不冒引入低级回归的风险，**跑一个子集就够了**。 | 选项 | 作用 | 备注 | |---|---|---| | `--subset` | 减少被触发的测试数量。例如 `--subset 0/4000` 会跑尽可能少的测试 | 权衡是**并非所有测试变体的组合都会被一起跑到**；但**无论比例给多小，teuthology 仍会保证 suite 里的每个文件至少出现在一个测试中**。理解背后真正的逻辑需要读 teuthology 源码 | | `--no-nested-subset` | 禁用嵌套子集（某些 suite 现在用了这个自动对一组精心挑选的 YAML 配置做子集化的特性） | 想做自定义过滤时可用 | | `--limit` | 只跑 suite 里**前 N 个**测试 | **很少有用**，因为没法控制哪个测试排在第一个 | > 引自：[Testing - Integration Tests - Introduction](https://docs.ceph.com/en/tentacle/dev/developer_guide/testing_integration_tests/tests-integration-testing-teuthology-intro/) ## 6.13 Teuthology 工作流：基础设施组件 一次 teuthology **run** 包含多个 **job**，每个 job 在相互隔离的环境里、在不同的 test node 集合上运行。 | # | 组件 | 说明 | |---|---|---| | 1 | `ceph-ci` | Ceph 主仓库的 clone，用于触发 Jenkins 开发构建 | | 2 | Ceph Jenkins | 负责触发构建、把包上传到 Chacra、把构建更新推送到 Shaman | | 3 | `Shaman` | UI 界面，用来查看构建状态。后端是一个查询和存储构建信息的 REST API | | 4 | `Chacra` | 包上传目的地服务。上传到这里二进制任何人都能下载使用 | | 5 | Teuthology CLI | 开发者用各种 Teuthology 命令调度和管理测试运行 | | 6 | Teuthology | 负责把测试 job 推到 Beanstalk 队列和 Paddles；也负责从队列取 job 并跑测试 | | 7 | Beanstalk queue | 包含所有排队 job 的优先队列。开发者通常不需要直接交互 | | 8 | Paddles | 存储所有测试运行信息的后端服务。开发者通常不需要直接交互 | | 9 | `Pulpito` | UI 界面（数据来自 Paddles），让开发者查看已调度测试的详细信息，包括状态和结果 | | 10 | Testnodes | 用于跑测试的各种机器组成的集群。开发者通常把测试调度到 **`smithi`** 机器上——这是 Teuthology 集成测试的专用测试节点 | **工作流总览（文字版）**： 1. 把带改动的分支推到 `ceph-ci` 仓库 → 自动触发 Jenkins 构建 Ceph 二进制，构建状态在 `Shaman` 上观察； 2. 构建好的包上传到 `Chacra`； 3. 要针对这个新构建调度 teuthology 集成测试，需要 **Sepia lab 访问权限**； 4. 登录后做一次性的初始 teuthology 设置，之后用 `teuthology-suite` 调度，用 `-c ` 指定你的构建； 5. 结果在 `Pulpito` 上看； 6. 登录 **developer playground machine** 查看 teuthology run 的归档日志。 ## 6.14 拿到二进制：构建 Ceph 1. **把分支推到 `ceph-ci` 仓库**，触发 Jenkins CI 上的二进制构建流程。 2. **确认构建流程已启动**：分支名出现在 `Shaman` 的 "Latest Builds Available" 列表里。不久之后，测试基础设施会往列表里加其他名字相近的构建——它们的名字里会包含各种 Linux 发行版的名字，用于在这些发行版上测你的构建。 3. **等待包构建完成并上传到 `Chacra`、等待提供这些包的 repository 创建完成**。`Shaman` 上 "Latest Builds Available" 列表里对应分支名的条目会**变绿**，表示包已上传到 Chacra 且 repository 已创建。**等到每个条目都变绿**。通常**需要 2 到 3 小时**，取决于机器可用性。 Chacra URL 可以从 https://shaman.ceph.com/api/search/?status=ready&project=ceph 查询。 两条 note： - 推到 ceph-ci 的分支**可以是任意分支**，不必是 PR 分支。 - 如果你打算推 master 或其他标准分支，**先查一下 Shaman**，因为可能已经有构建好的了。 ### 6.14.1 推到 ceph-ci 仓库 **1. 把 ceph-ci 仓库加为本地 Ceph clone 的 remote：** ```bash git remote add ceph-ci git@github.com:ceph/ceph-ci.git $ git remote -v origin git@github.com:ceph/ceph.git (fetch) origin git@github.com:ceph/ceph.git (push) ceph-ci git@github.com:ceph/ceph-ci.git (fetch) ceph-ci git@github.com:ceph/ceph-ci.git (push) ``` **2. 推你的分支：** ```bash $ git push ceph-ci wip-yourname-feature-x ``` ### 6.14.2 ceph-ci 分支命名规则 **推到 ceph-ci 前，给分支名加上你自己的名字前缀。** 例如分支 `feature-x` 应该命名为 `wip-$yourname-feature-x`。这样你的分支在 Shaman 和 Pulpito 上容易被找到。 **如果你用的是某个 stable 分支（quincy、pacific 等），把该 stable 分支名也放进 ceph-ci 分支名里。** 例如 `feature-x` PR 分支应命名为 `wip-feature-x-nautilus`。 > 官方强调：**这不只是约定。这确保你的分支在正确的环境里被构建。** 不用了就把分支从 ceph-ci 删掉。登录 GitHub 后，你在 ceph-ci 上的所有分支可以在这里看到：https://github.com/ceph/ceph-ci/branches > note：你可以只触发 CentOS 9.Stream 构建（排除 ubuntu 等其他发行版），方法是在 ceph-ci 分支名末尾加 `"centos9-only"`，例如 `wip-$yourname-feature-centos9-only`。这能在你不需要其他发行版二进制时**更快拿到构建并节省资源**。 ## 6.15 调度测试运行 ### 6.15.1 触发 teuthology 测试 **1. 登录 teuthology 机器：** ```bash ssh @teuthology.front.sepia.ceph.com ``` （需要 Sepia lab 访问权限。申请：https://ceph.github.io/sepia/adding_users/） **2. 初次设置**：按 teuthology 安装指南（https://docs.ceph.com/projects/teuthology/en/latest/INSTALL.html#installation-and-setup）在你的用户下配置 teuthology，之后你才能跑 teuthology 命令。 **3. 跑 `teuthology-suite` 命令：** ```bash teuthology-suite -v \ -m smithi \ -c wip-devname-feature-x \ -s fs \ -p 110 \ --filter "cephfs-shell" \ -e foo@gmail.com ``` | 选项 | 含义 | |---|---| | `-v` | verbose | | `-m` | machine name（机器名） | | `-c` | 推到 ceph-ci 上的分支名 | | `-s` | test-suite 名字 | | `-p` | **数字越大，job 优先级越低** | | `--filter` | 过滤给定 suite 里的测试，参数指定你想跑哪些测试 | | `-e ` | 测试完成或超时时发邮件到指定地址。也可以在 `~/.teuthology.yaml` 里用 `results_email` 指定 | 两条 note： - 上面命令里的优先级数字**只是占位符，不要在你自己的测试里用**。见「Testing Priority」的推荐取值。 - **不要不带优先级数字就发命令**。默认值是 1000，大到你的 job 很可能永远不跑。 跑 `teuthology-suite --help` 读这些和其他可用选项的说明。 **4. 等测试跑。** `teuthology-suite` 会打印一个 `Pulpito` 链接，可以看结果。 ### 6.15.2 其他常用选项 | 选项 | 用途 | |---|---| | `--dry-run` | 试跑，不真的调度。用来检查一条命令会调度多少 job、哪些 job | | `-d` / `--distro` | 发行版 | | `--distro-version` | 发行版版本 | | `--filter-out` | 反向过滤 | | `--timeout` | 超时 | | `flavor` | flavor | | `--rerun` | 重跑 | | `--limit` | 限制 job 数量 | | `-N` | job 跑多少次 | | `--subset` | 减少被触发的测试数量 | ### 6.15.3 只改了 `qa/` 目录：不用重新构建二进制 **如果你只在 `qa/` 目录里做改动，重跑测试前不必重新构建二进制**，可以用为 ceph-ci 分支构建的二进制直接重跑，只需告诉 `teuthology-suite` 用一个单独的分支来跑测试。 具体做法：给 `teuthology-suite` 传两个额外参数—— 1. `--suite-repo`：指定你的 ceph 仓库； 2. `--suite-branch`：指定你的分支名。 例如，你要在测完 `branch-x`（对应 ceph-ci 分支 `wip-username-branch-x`）之后改 `qa/`： ```bash teuthology-suite -v \ -m smithi \ -c wip-username-branch-x \ -s fs \ -p 50 \ --filter cephfs-shell ``` 然后本地做修改、更新 PR 分支，再从你的 PR 分支触发测试： ```bash teuthology-suite -v \ -m smithi \ -c wip-username-branch-x \ -s fs -p 50 \ --filter cephfs-shell \ --suite-repo https://github.com/$username/ceph \ --suite-branch branch-x ``` **如何确认测试确实用了这个分支跑**：看 teuthology job 开头打印的 job config 里的 `suite_branch`、`suite_repo` 和 `suite_sha1` 三个键的值。 > note：如果改动**不在 `qa/` 目录里**，就必须走标准流程：触发构建 → 等构建完成 → 触发测试 → 等结果。 ### 6.15.4 过滤测试：关键词从哪找 Suite 里包含大量 yaml 文件的组合，可能调度出海量的 job，因此需要过滤。 **过滤关键词的位置**：`qa/suites///tasks`。该目录里**每个 YAML 文件都能触发测试**；把**文件名去掉扩展名**作为 `--filter` 的参数，就能触发那些测试。 例如上面用的 `cephfs-shell`，是因为 `qa/suites/fs/basic_functional/tasks/` 下有一个 `cephfs-shell.yaml`。 **如果文件名看不出它触发什么测试**，就去搜文件内容里的 **`modules` 属性**。`cephfs-shell.yaml` 的 `modules` 属性是 `tasks.cephfs.test_cephfs_shell`，意味着它触发 `qa/tasks/cephfs/test_cephfs_shell.py` 里的所有测试。 ## 6.16 查看测试结果 ### 6.16.1 Pulpito Dashboard https://pulpito.ceph.com/ ### 6.16.2 Teuthology Archives（查日志） 测试跑完后，在 Pulpito 的 run 页面点 **job ID** 可以拿到日志。**官方建议下载日志再看，而不是在浏览器里看**，因为这些日志**很容易达到 1GB**。 也可以 ssh 到 developer playground machine（https://wiki.sepia.ceph.com/doku.php?id=devplayground）访问这个路径： ```text /teuthology///teuthology.log ``` 例如： ```text /teuthology/teuthology-2019-12-10_05:00:03-smoke-master-testing-basic-smithi/4588482/teuthology.log ``` 这比通过浏览器看快。 **看 ceph 日志**（cephadm、ceph monitors、ceph-mgr 等）或**系统日志**：在浏览器里把 job 的 teuthology log url 末尾的 `teuthology.log` 去掉，然后进入 `remote//log/`；系统日志在 `remote//syslog/`。在 developer playground 机器上对应路径是 `/teuthology///remote//`。 **其他为调试提供的文件：** | 文件 | 内容 | |---|---| | `unit_test_summary.yaml` | 所有单元测试失败的摘要。**可选生成**——只有当 job 的 YAML 文件里用了 `unit_test_scan` 配置项时才会生成 | | `valgrind.yaml` | 汇总可能发生的 Valgrind 错误 | > 便捷访问：`/a/` 已经符号链接到 `/teuthology/`。例如上面的例子可以写成： > `/a/teuthology-2019-12-10_05:00:03-smoke-master-testing-basic-smithi/4588482/teuthology.log` ## 6.17 杀掉测试 `teuthology-kill` 用来杀掉那些**意外跑了几个小时**的 job，或者开发者想提前终止测试时。 ```bash teuthology-kill -p -r teuthology-2019-12-10_05:00:03-smoke-master-testing-basic-smithi -m smithi -o scheduled_teuthology@teuthology ``` 传给 `-r` 的是 **run name**，可以在你触发的测试的 Pulpito 页面链接里轻松找到。例如： http://pulpito.front.sepia.ceph.com/teuthology-2019-12-10_05:00:03-smoke-master-testing-basic-smithi/ ## 6.18 重跑测试 `teuthology-suite` 的 `-r`（`--rerun`）选项允许重跑测试，在测试失败或变成 dead 时很方便。**`--rerun` 接受一个 teuthology run 的名字作为参数。** 可以配合 `-R`（`--rerun-statuses`）**选择从这次 run 里挑出哪些状态的测试**重跑。例如只重跑上次变成 dead 的测试： ```bash teuthology-suite -v \ -m smithi \ -c wip-rishabh-fs-test_cephfs_shell-fix \ -p 50 \ --r teuthology-2019-12-10_05:00:03-smoke-master-testing-basic-smithi \ -R fail,dead,queued \ -e $CEPH_QA_MAIL ``` | 选项 | 含义 | |---|---| | `-r`, `--rerun` | 尝试重新调度一次 run，只挑选状态被 `--rerun-status` 提及的那些 job | | `-R`, `--rerun-statuses` | 与 `--rerun` 配合使用的逗号分隔状态列表。支持的状态：`dead`、`fail`、`pass`、`queued`、`running`、`waiting`。**默认值：`fail,dead`** | > 引自：[Integration Tests using Teuthology Workflow](https://docs.ceph.com/en/tentacle/dev/developer_guide/testing_integration_tests/tests-integration-testing-teuthology-workflow/) ## 6.19 分析与调试一个 Teuthology Job ### 6.19.1 查看结果 run 成功完成后，用 pulpito dashboard 看结果（https://pulpito.ceph.com）： ```text http://pulpito.front.sepia.ceph.com/// ``` 或 ssh 进 teuthology server： ```bash ssh @teuthology.front.sepia.ceph.com ``` 然后访问 teuthology archives，例如： ```bash nano /a/teuthology-2021-01-06_07:01:02-rados-master-distro-basic-smithi/ ``` （需要 Sepia lab 访问权限，申请见 https://ceph.github.io/sepia/adding_users/） ### 6.19.2 识别失败的 job **在 pulpito 上，红色表示一个 failed job 或一个 dead job。** 一个 job 是 `qa/suites` 里 yaml fragments 定义的一组守护进程与配置的组合。Teuthology 使用这些配置并运行 `qa/tasks` 里列出的 tasks——这些 task 是搭建测试环境并测试 Ceph 各组件的命令。这些 task 覆盖了很大一部分用例，有助于暴露 `make check` 测试暴露不出的 bug。 **一个 job 失败可能由以下一个或多个原因导致：** - **环境搭建**（在多样的系统上测试，见 https://github.com/ceph/ceph/tree/master/qa/distros/supported）：测试与受支持版本的 stable release 的兼容性。 - **配置值的排列组合**：例如 `qa/suites/rados/thrash` 确保我们在压力工作负载下对 Ceph 跑 thrashing 测试，从而抓到 corner-case bug。 **最终用于测试的 setup config yaml 文件**可以在这里拿到： ```text /a///orig.config.yaml ``` 更多关于 config.yaml 的细节见 https://docs.ceph.com/projects/teuthology/en/latest/detailed_test_config.html ### 6.19.3 定位失败原因（Triaging） job 失败时，需要读它的 teuthology log 来定位原因。用 pulpito 上的 job name 和 id 找到失败 job 的日志： ```text http://qa-proxy.ceph.com///teuthology.log ``` 打开文件： ```text /a///teuthology.log ``` 例如： ```bash nano /a/teuthology-2021-01-06_07:01:02-rados-master-distro-basic-smithi/5759282/teuthology.log ``` **每一次 job 失败都会以 Traceback 的形式记录在 teuthology log 里，并被加进 job summary。** **做法：找 `Traceback` 关键字，搜索调用栈和日志里导致失败的问题。通常 traceback 里会包含失败的那条命令。** > note：teuthology 日志会被定期删除。如果上面示例的链接访问不了，就从 http://pulpito.front.sepia.ceph.com/ 随便找另一个 case 用。 ### 6.19.4 上报 issue **原则：先确认你的 job 失败是不是已知 issue 导致的；如果不是，就提 tracker ticket。** 流程： 1. 定位完失败原因，确认**不是你的代码改动导致的**——这可能说明你遇到了上游分支的已知失败（本节例子里上游分支是 "octopus"）。 2. 去 https://tracker.ceph.com 用你在失败中看到的关键词搜索相关 issue。 3. **找到相似 issue**：在上面留言，按你的理解解释这次失败，**务必附上你最近一次 test run 的链接**。 4. **没找到**：为这个 issue 新建一个 tracker ticket，尽可能详尽地解释 job 失败的原因。 5. **不确定失败原因**：找团队成员求助。 ### 6.19.5 用 `interactive-on-error` 调试 遇到 job 失败时应该尝试复现它。这就是 `--interactive-on-error` 的用武之地。 确认 job 失败后，用 teuthology 再跑一次同一个 job，但加上 `interactive-on-error` flag： ```bash ideepika@teuthology:~/teuthology$ ./virtualenv/bin/teuthology -v --lock --block $ --interactive-on-error ``` 可以用自定义 `config.yaml`，也可以用失败 job 的 yaml 文件。如果用失败 job 的，先把 `orig.config.yaml` 拷到本地目录： ```bash ideepika@teuthology:~/teuthology$ cp /a/teuthology-2021-01-06_07:01:02-rados-master-distro-basic-smithi/5759282/orig.config.yaml test.yaml ideepika@teuthology:~/teuthology$ ./virtualenv/bin/teuthology -v --lock --block test.yaml --interactive-on-error ``` **它做了什么**：如果用了 `interactive-on-error` 后 job 失败，teuthology 会**锁住 `config.yaml` 需要的机器**，**停住**这些测试机并把它们**保持在失败发生那一刻的状态**，然后把你放进一个**交互式 Python session**。从那里你可以 ssh 进系统排查失败原因。 排查完后**直接终止 session** 即可，teuthology 会清理 session 并解锁机器。 ### 6.19.6 官方推荐的学习资源 | 资源 | 链接 | |---|---| | Testing Ceph: Pains & Pleasures | https://www.youtube.com/watch?v=gj1OXrKdSrs | | Teuthology Training（播放列表） | https://www.youtube.com/playlist?list=PLrBUGiINAakNsOwHaIM27OBGKezQbUdM- | | Intro to Teuthology | https://www.youtube.com/watch?v=WiEUzoS6Nc4 | > 引自：[Analyzing and Debugging A Teuthology Job](https://docs.ceph.com/en/tentacle/dev/developer_guide/testing_integration_tests/tests-integration-testing-teuthology-debugging-tips/) ## 6.20 Kernel 开发的集成测试 ### 6.20.1 CephFS `fs` suite 会跑各种 kernel，由 **kernel YAML fragments** 描述。这些 fragments 被 `fs` suite 下的其他子 suite **符号链接**引用。 这个 fragment 矩阵允许测试以下配置： - **RHEL 8 上的 "stock" kernel**（即随发行版自带的那个内核）； - 内核开发团队的 **`testing` 分支**，代表正在积极测试中的补丁。这些补丁**可能进入也可能不进入**下一个上游内核发布，包含 CephFS 或 kRBD 改动的混合。对 testing kernel，我们用**子 suite 指定的发行版**来测。例如 `fs:functional` 子 suite 使用 **supported random distros 的随机选择**。 ### 6.20.2 测试自定义内核 如果你在 `ceph-client.git` 上有一个 kernel 分支，并且已经用 shaman 构建过，那么可以通过给 `teuthology-suite` 传一个 YAML fragment 来**覆盖 kernel**，轻松测它： ```yaml $ cat custom-kernel.yaml overrides: kernel: branch: for-linus ``` 这为 suite 矩阵里指定的 kernel 分支提供了 override。你也可以把 override 指定为 **`kernel` task 的一个 tag 或 SHA1**。 > **重要提醒**：覆盖 kernel 时，你**应该减少 job 的选择范围**，因为矩阵会包含很多你不关心的 kernel 配置（见上文 CephFS 一节）；override YAML 会**应用到 kernel 的所有配置**，从而产生**重复的测试**。 运行命令形如： ```bash teuthology-suite ... --suite fs --filter k-testing custom-kernel.yaml ``` 其中 `...` 是平时跑 `teuthology-suite` 时的其他常规选项。**关键的过滤器 `--filter k-testing`** 会把 job 选择范围**限制在使用 kernel 的 `testing` 分支的那些**（见 `k-testing.yaml` 文件），所以你只会选到用 `testing` 分支 kernel client 的 job。然后你的自定义 YAML 文件 `custom-kernel.yaml` 会进一步把 `testing` 分支覆盖成你指定的任何东西。 > 引自：[Integration Tests for Kernel Development](https://docs.ceph.com/en/tentacle/dev/developer_guide/testing_integration_tests/tests-integration-testing-teuthology-kernel/) ## 6.21 Sentry `tests-sentry-developers-guide.rst` 的完整内容只有两行： ```text Sentry Notes ============ To be updated. Feel free to contribute. ``` 即：**待补充，欢迎贡献。** 官方文档本身没有写任何 Sentry 相关内容。 > 引自：[Sentry Notes](https://docs.ceph.com/en/tentacle/dev/developer_guide/testing_integration_tests/tests-sentry-developers-guide/) ## 6.22 子目录索引 `testing_integration_tests/index.rst` 的 toctree（用 `:glob:` + `:titlesonly:`）： | 条目 | 页面 | |---|---| | Introduction | `tests-integration-testing-teuthology-intro` | | Workflow | `tests-integration-testing-teuthology-workflow` | | Debugging Tips | `tests-integration-testing-teuthology-debugging-tips` | | Kernel Development | `tests-integration-testing-teuthology-kernel` | | Sentry Notes | `tests-sentry-developers-guide` | > 引自：[Teuthology User Guide](https://docs.ceph.com/en/tentacle/dev/developer_guide/testing_integration_tests/) --- # 七、用 GDB 调试 Ceph **GNU Project Debugger (GDB)**（https://www.sourceware.org/gdb）是一个强大的工具，可以分析进程的执行流。GDB 能帮你找 bug、发现 crash 错误、或者在开发集群运行时跟踪源码。**它也可以用来调试 Teuthology 测试运行。** ## 7.1 起步 基础用法与示例：https://geeksforgeeks.org/gdb-command-in-linux-with-examples **GDB 可以 attach 到运行中的进程。** 例如部署一个开发集群后，`ceph-osd` 守护进程的 PID 可以在这里找到： ```bash $ cd build $ cat out/osd.0.pid ``` **attach gdb 到该进程：** ```bash $ gdb ./bin/ceph-osd -p ``` ## 7.2 两条重要建议 **1）编译时不要优化。** 官方建议**编译时不带任何优化（`-O0` gcc flag）**，以避免中间值被消除。 **2）调大的超时时间。** 调试时因断点停下来可能导致超时，官方建议设置以下配置项： ```ini [osd] osd_op_thread_timeout = 1500 osd_op_thread_suicide_timeout = 1500 ``` ## 7.3 调试 Teuthology 测试 **`src/script/ceph-debug-docker.sh`** 可以用来分析 Teuthology 失败： ```bash $ ./ceph-debug-docker.sh ``` 更多信息参见该脚本的头部注释。 ## 7.4 常用 GDB 命令速查 > ⚠️ **文档未明确**：官方 `debugging-gdb.rst` **没有列出任何具体的 GDB 子命令**（如 `bt`、`info threads`、`thread apply all bt` 等），只给了一个外部链接。上面的 `gdb ./bin/ceph-osd -p ` 是官方给出的唯一一条完整命令。 > 💡 补充：本册源文能确证的 gdb 相关命令只有： ```bash # 1) 找到 ceph-osd 的 PID cd build cat out/osd.0.pid # 2) attach gdb ./bin/ceph-osd -p # 3) 分析 teuthology 失败 ./ceph-debug-docker.sh ``` > 💡 补充：调试时若需要看 Ceph 自己的日志，注意 Google Test 与守护进程的客户端日志位置不同（见 5.6 节）：单测客户端日志在 `build/out/client.admin..log`；vstart 集群日志在 `build/out/` 下，可用 `tail -f out/????` 观察。 > 引自：[GDB - The GNU Project Debugger](https://docs.ceph.com/en/tentacle/dev/developer_guide/debugging-gdb/) --- # 八、Windows 测试 ## 8.1 背景 **从 Pacific 起，Ceph 客户端工具和库可以在 Windows 上原生使用**，这样 Windows 节点消费 Ceph 时不需要额外加 iSCSI gateway 或 SMB share 之类的层。 为了保证这些组件在 Windows 上持续正常工作，**大量单元测试和集成测试被移植**过来。 ## 8.2 Windows CI Job 做了什么 `Windows CI job`（https://github.com/ceph/ceph-build/blob/main/ceph-windows-pull-requests/config/definitions/ceph-windows-pull-requests.yml）对**每个 GitHub pull request** 执行以下步骤： 1. 起一台 Linux VM，在里面构建服务端（Linux）Ceph 二进制，并交叉编译 Windows（客户端）二进制； 2. 重建 Linux VM 并启动一个 Ceph **vstart** 集群； 3. 启动一台 Windows VM，在上面跑 Ceph 测试。 一个**小型 PowerShell 框架**（https://github.com/ceph/ceph-win32-tests/）负责并行化测试、聚合结果，并隔离或跳过已知的 flaky 测试。 **控制台输出**里可能包含编译错误和失败测试的名字。要拿到失败测试的控制台输出以及 Ceph 和操作系统日志，**去看 Jenkins "Status" 页面的 build artifacts**。 Windows CI artifacts 可以下载为 zip 归档，也可以在浏览器里直接看。点 "artifacts" 按钮查看内容。 ## 8.3 Artifact 目录结构 | 路径 | 内容 | |---|---| | `client/` | Ceph 客户端侧日志（Windows） | | `client/eventlog/` | Windows 系统日志 | | `client/logs/` | Ceph 日志 | | `client/*-windows.conf` | Ceph 配置文件 | | `cluster/` | Ceph 服务端日志（Linux） | | `cluster/ceph_logs/` | Ceph 日志 | | `cluster/journal` | journal | | `test_results/` | 测试结果 | | `test_results/out/` | 按测试可执行文件分组的 raw 与 xml 测试输出 | | `test_results/test_results.html` | 聚合测试报告（html） | | `test_results/test_results.txt` | 聚合测试报告（纯文本） | 测试结果用 **`subunit`** 格式（https://github.com/testing-cabal/subunit）及相关工具聚合，**在并行跑大量测试时特别好用**。 ## 8.4 怎么读聚合测试报告 聚合测试报告能很好地概览失败的测试。**跳到文件末尾**可以看到实际错误： ```text {0} unittest_mempool.mempool.bufferlist_reassign [0.000000s] ... ok {0} unittest_mempool.mempool.bufferlist_c_str [0.006000s] ... ok {0} unittest_mempool.mempool.btree_map_test [0.000000s] ... ok {0} ceph_test_dokan.DokanTests.test_mount [9.203000s] ... FAILED Captured details: ~~~~~~~~~~~~~~~~~ b'/home/ubuntu/ceph/src/test/dokan/dokan.cc:136' b'Expected equality of these values:' b' wait_for_mount(mountpoint)' b' Which is: -138' b' 0' b'' b'/home/ubuntu/ceph/src/test/dokan/dokan.cc:208' b'Expected equality of these values:' b' ret' b' Which is: "ceph-dokan: exit status: -22"' b' ""' b'Failed unmapping: Y:\\' {0} ceph_test_dokan.DokanTests.test_mount_read_only [9.140000s] ... FAILED ``` HTML 报告按测试 suite（测试二进制）分组，**出于安全原因默认不渲染**，但可以下载到本地看。 **排查技巧：** - **超时和缺失的测试结果往往是进程崩溃的信号**。 - 注意 **ceph status 会在跑测试前后打印到控制台**，这有助于识别崩溃的服务。 - 也可以查服务日志（客户端和服务端都要看）。 - 另外注意：**Windows "application" 事件日志**里会有 Windows 进程崩溃的条目。 ## 8.5 FAQ ### Q1：为什么我的 PR 只有 Windows CI job 失败？ Ceph 集成测试通常是通过 **Teuthology** 在 Ceph Lab 基础设施上做的。这些测试由 Ceph QA 团队**按需触发**，**不会为每个提交的 PR 自动跑**。 而 Windows CI job **只聚焦客户端侧的 Ceph 组件**，因此**能对每个 GitHub PR 及时跑各种集成测试**。**换句话说，它跑的是各种 librados、librbd 和 libcephfs 测试——这些是 `make check` 等其他检查所不跑的。** 因此 Windows CI 经常能抓到其他检查漏掉的回归，而这些回归**往往不是平台特有的，也影响 Linux**。 **Windows CI 失败时，强烈建议按上面的方法查测试结果。** 另外要注意：`Windows build script`（https://github.com/ceph/ceph/blob/main/win32_build.sh）可能使用**不同的编译 flag 和传给 CMake 的 `-D` 选项**。例如它**默认是 `Release` 模式而不是 `Debug` 模式**；同时它用的是不同的 toolchain（**`mingw-llvm`**）和一套独立的 **dependencies**（https://github.com/ceph/ceph/blob/main/win32_deps_build.sh），**需要时要记得升级版本**。 ### Q2：为什么 Windows CI job 是强制的（mandatory）？ 这个测试 job **最初是可选的**，结果**回归被引入得非常频繁**。 后来 Windows 支持成熟到足以让这个 CI job 变成**强制的**。这**显著减少了处理回归所需的工作量**，也向 Ceph 用户保证了 Windows 支持的持续性。 另一个巨大好处（如上所述）：**它跑的集成测试能快速抓到往往同样影响 Linux 构建的回归**，让开发者不必等完整的 Teuthology 结果。 > 引自：[Testing - Windows](https://docs.ceph.com/en/tentacle/dev/developer_guide/tests-windows/) --- # 九、文档贡献 > ⚠️ **范围说明**：`documenting.rst` **不在 `doc/dev/developer_guide/` 目录下**，它的实际位置是 `doc/dev/documenting.rst`，属于本手册**第 18 册**（内部实现篇·组件工具与 Crimson）的覆盖范围。按本册的取材范围，这里只讲**与贡献流程直接相关**的部分，完整内容见第 18 册。 ## 9.1 从贡献流程角度看文档改动 | 场景 | 是否需要 Redmine tracker issue | |---|---| | Simple documentation cleanup（简单文档清理） | **不需要** | | 新增文档章节或文件 | 需要 | | 对文档结构或内容做实质性改动 | 需要 | > 引自：[Basic Workflow](https://docs.ceph.com/en/tentacle/dev/developer_guide/basic-workflow/) ## 9.2 所有 PR 都会跑的一个 CI 检查：文档能否构建 官方列出的第 2 项自动化检查就是 **a test to check that the documentation builds**。也就是说，**你的 rst 写坏了，PR 会红**。 > 引自：[Basic Workflow](https://docs.ceph.com/en/tentacle/dev/developer_guide/basic-workflow/) ## 9.3 `doc/dev/documenting.rst` 要点（摘要，详见第 18 册） - docs.ceph.com 上的文档由 Ceph git 仓库 **`/doc/` 目录里的 reStructuredText 源文件**生成。 - 除非你是在 **`/doc/dev/`**（开发者专区）里做增补，否则**改动必须面向软件的最终用户来写**。 - **所有修改面向用户功能的 PR 都必须包含对应的文档更新**，详见 `SubmittingPatches`。 - 检查 rst 语法：在 GitHub 上看 diff 时用 **"View" 按钮**；或者用 **`admin/build-doc`** 脚本本地构建。 - C/C++ 代码文档用 **Doxygen**（配合 **Breathe** 支持的 Doxygen 标记子集），注释写在**声明函数的头文件**里，函数应按逻辑分组。生成 HTML： ```bash cmake --build . --target doxygen ``` 输出在 `build-doc/doxygen/html`。 - 画图工具：**Graphviz**（推荐把 DOT 源放单独文件，用 `.. graphviz:: myfile.dot`）、**Ditaa**、**Blockdiag**（如需要可集成）、**Inkscape**（应同时提交 SVG 和导出的 PNG，rst 里引用 PNG）。 > 💡 补充：本节 9.3 的内容来自 `doc/dev/documenting.rst`，**不属于本册的源文范围**（本册源文是 `doc/dev/developer_guide/`），此处仅作为与「贡献流程」相关的必要引述列出，完整讲解见第 18 册。 --- # 十、Ceph Dashboard 开发（`dash-devel.rst`，本册最大块） 这是本册最大的一章，源文 103KB、2747 行，官方标题是 *Ceph Dashboard Developer Documentation (formerly HACKING.rst)*——即它前身是 Dashboard 的 `HACKING.rst`。 ## 10.1 Feature Design（特性设计） 为了促进在 Ceph Dashboard 新特性上的协作，**第一步是定义一份设计文档**。这些文档随后构成实现范围的基础，并让更多人能参与到 Ceph Dashboard UI 的演进中。 设计文档的 toctree 里目前挂着一个条目： - UI Design Goals → `../dashboard/ui_goals` ## 10.2 Preliminary Steps：搭建开发环境 后续各章都假设你有一个**运行中的 Ceph 集群**，且至少跑着 `dashboard` manager module（少数例外）。本章讲如何为开发搭建这样一个系统，**无需搭建完整的生产环境**。 > **重要前提**：**每个 `vstart` 环境都需要 Ceph 从 GitHub 仓库编译**（https://docs.ceph.com/docs/master/install/build-ceph/），不过 Docker 环境通过提供一个包含这些指令的 shell 脚本简化了这一步。 > > **一个例外**：`ceph-dev` 的 **`build-free`** 能力（见下文）——它通过**用 RPM 系统包安装 Ceph** 来做到免编译，同时你仍然能像往常一样使用本地 GitHub 仓库。 ### 10.2.1 vstart 是什么 "vstart" 其实是 Ceph 仓库 `src/` 目录里的一个 shell 脚本（**`src/vstart.sh`**），用来**在执行它的机器上启动一个单节点 Ceph 集群**。用它启动集群时，若干必需的以及一些可选的 Ceph 内部服务会自动启动。 **vstart 是 Ceph Dashboard 三种最常用开发环境的基础。** 更多见 `Deploying a development cluster`，开发者额外信息见 Developer Guide（https://docs.ceph.com/docs/master/dev/quick_guide/）。 ### 10.2.2 基于宿主机 vs 基于 Docker 的开发环境 本册介绍三种都基于 vstart 的开发环境： 1. **vstart 跑在你的宿主机系统上** 2. **vstart 跑在 Docker 环境里** - `ceph-dev-docker`（https://github.com/ricardoasmarques/ceph-dev-docker） - `ceph-dev`（https://github.com/rhcs-dashboard/ceph-dev） 两个 Docker 项目除了各自独立的开发分支和略有差异的做法，底层操作系统也不同： | Release | ceph-dev-docker | ceph-dev | |---|---|---| | Mimic | openSUSE Leap 15 | CentOS 7 | | Nautilus | openSUSE Leap 15 | CentOS 7 | | Octopus | openSUSE Leap 15.2 | CentOS 8 | | Master | openSUSE Tumbleweed | CentOS 8 | > **重要 note**：**无论你选哪个环境，都需要在该环境里编译 Ceph。** 如果你在宿主机上编译过 Ceph，切到 Docker 方案就得在 Docker 里重新编译；反之亦然（也可以另开一个独立仓库编译）。 > > `ceph-dev` 是**唯一的例外**：它提供 `build-free` 选项，通过 RPM 系统包安装 Ceph 实现免编译，同时你仍然可以用本地 GitHub 仓库工作。 **基于宿主机的开发环境：** - 不需要学 Docker、不需要 Docker 经验，可以直接上手； - 用于自动化（如 Ceph 编译）的脚本数量有限； - 没有预配置好、开箱即用的服务（Prometheus、Grafana 等）； - 支持的宿主操作系统有限，取决于要用哪个 Ceph 版本； - 依赖需要装在你的宿主机上； - 你可能被迫升级宿主操作系统（例如因为编译 Ceph 用的 GCC 版本变了）。 **基于 Docker 的开发环境：** - 如果你还不熟悉 Docker，有一点学习开销； - 两个 Docker 项目都提供了帮你上手和自动化重复任务的脚本； - **都自带部分预配置的外部服务**，可以用来对接或补充 Ceph Dashboard 特性，包括： - Prometheus - Grafana - Node-Exporter - Shibboleth - HAProxy - **与你宿主机用的操作系统无关**。 ### 10.2.3 在宿主机上跑 vstart vstart 脚本通常从你的 `build/` 目录这样调用： ```bash ../src/vstart.sh -n -d ``` - **`-n`**：确保创建一个新的 vstart 集群，不会复用之前可能已创建的集群； - **`-d`**：在日志文件里开启 debug 消息。 还有更多选项，用 `--help` 参数可以列出。 **vstart 输出末尾应该有 dashboard 及其 URL 的信息：** ```text vstart cluster complete. Use stop.sh to stop. See out/* (e.g. 'tail -f out/????') for debug output. dashboard urls: https://192.168.178.84:41259, https://192.168.178.84:43259, https://192.168.178.84:45259 w/ user/pass: admin / admin ``` **开发过程中（尤其是后端开发），你也会想偶尔检查 dashboard manager module 是否还在跑。** 可以手工调用 `./bin/ceph mgr services`，它会列出所有成功启用的服务的 URL。**只有可通过 HTTP(S) 访问的服务才会列在那里**，Ceph Dashboard 就是其中之一。应该类似这样： ```bash $ ./bin/ceph mgr services { "dashboard": "https://home:41931/" } ``` > **默认这个环境给 Ceph Dashboard 用随机端口**，你需要用上面这条命令查出来是哪个。 ### 10.2.4 Docker Docker 开发环境通常自带很多有用的脚本。例如 `ceph-dev-docker` 里有一个 `start-ceph.sh`，它会：清理日志文件、总是启动一个 Rados Gateway 服务、设置一些 Ceph Dashboard 配置选项、并自动运行一个 frontend proxy——全都在启动 vstart 集群之前或之后完成。 使用说明在各自仓库的 README 里（见 10.2.2 的两个链接）。 ## 10.3 Frontend Development（前端开发） 在开发环境里启动 dashboard 之前，你需要先生成前端代码，然后**要么**使用一个已编译且运行的 Ceph 集群（例如由 `vstart.sh` 启动的），**要么**使用 standalone development web server。 构建过程基于 **Node.js**（https://nodejs.org/），需要安装 **npm**（https://www.npmjs.com/）。 ### 10.3.1 前置条件与工具链 | 项 | 要求 / 说明 | |---|---| | Node | **20.13.1 或更高** | | NPM | **10.5.2 或更高** | | nodeenv | Ceph 构建时会创建一个装了 `node` 和 `npm` 的 virtualenv，可替代系统安装的 node/npm。用它之前先激活：`. build/src/pybind/mgr/dashboard/node-env/bin/activate`；用完 `deactivate` 退出 | | Angular CLI | 如果你**没有全局安装** Angular CLI（https://github.com/angular/angular-cli），那么执行 `ng` 命令时需要前面加一个 `npm run` | **技术栈小结**（官方明确提到的）：**Angular + Angular CLI + Node.js/npm + TypeScript + SCSS + HTML + Bootstrap（CSS 框架）+ Jest（单元测试）+ Cypress（E2E）+ Applitools Eyes（视觉回归）+ ngx-toastr（通知）+ Fork Awesome（图标）+ compodoc（代码文档）**。 ### 10.3.2 安装依赖 在 `src/pybind/mgr/dashboard/frontend` 目录里跑： ```bash npm ci ``` ### 10.3.3 增加或更新依赖包 ```bash npm install npm ci ``` ### 10.3.4 起开发服务器 1. 基于 `proxy.conf.json.sample` 创建 **`proxy.conf.json`** 文件； 2. 跑 `npm start` 起 dev server； 3. 浏览器打开 **http://localhost:4200/**。**改动任何源文件后应用会自动 reload。** ### 10.3.5 代码脚手架 ```bash ng generate component component-name ``` 也可以生成其他类型： ```bash ng generate directive|pipe|service|class|guard|interface|enum|module ``` 没装全局 Angular CLI 时，前面加 `npm run`。 ### 10.3.6 构建项目 ```bash npm run build ``` 构建产物存放在 **`dist/`** 目录。用 `--prod` flag 做生产构建： ```bash npm run build -- --prod ``` 然后访问 `https://localhost:8443`。 ### 10.3.7 构建代码文档 ```bash npm run doc-build ``` 会在 **`documentation/`** 目录生成代码文档。要在本地用浏览器访问： ```bash npm run doc-serve ``` 然后打开 **http://localhost:8444**。用 `npm run compodoc -- ` 可以**完全配置**它（https://compodoc.app/guides/usage.html）。 ### 10.3.8 代码 lint 与格式化 官方用于所有 TS、SCSS 和 HTML 文件的工具： | 工具 | 链接 | |---|---| | codelyzer | http://codelyzer.com/ | | html-linter | https://github.com/chinchiheather/html-linter | | htmllint-cli | https://github.com/htmllint/htmllint-cli | | Prettier | https://prettier.io/ | | ESLint | https://eslint.org/ | | stylelint | https://stylelint.io/ | 官方加了两个 npm script： ```bash npm run lint # 用所有 linter 检查前端文件 npm run fix # 尝试修复所有检测到的 linting 错误 ``` ### 10.3.9 Ceph Dashboard 与 Bootstrap 目前 Ceph Dashboard 用 **Bootstrap** 作为 CSS 框架，这意味着大部分 SCSS 和 HTML 代码可以利用 Bootstrap 提供的所有 utility 和其他优势。 **历史问题**：过去经常使用自定义样式，导致越来越多的「只用过一次的变量」和「重复定义的变量」——有些忘了删，有些导致样式不一致（有人忘了改颜色或调整某个自定义 SCSS class）。 **查当前 Bootstrap 版本**：看 `package.json`，搜： - `bootstrap`：Bootstrap 版本； - `@ng-bootstrap`：使用的 Angular bindings 版本。 **官方明确要求（今后访问组件时请照做）：** 1. **这段 HTML/SCSS 代码用了自定义代码吗？** 如果是：**有必要吗？** → **先清理干净**再改你想修/想改的东西。 2. **如果你在创建新组件**：**尽可能合理地使用 Bootstrap！别重复造轮子。** 3. **如果可能**：查一下 Bootstrap 有没有「如何正确扩展它」的指南来实现你想要的效果。 官方给的理由：代码越像 Bootstrap，就越容易 theme、越容易维护、bug 越少；Bootstrap 本身考虑了可用性和用户体验，能同时提升这两点；**最大好处是我们要维护的代码更少**——对新手更好读，对已熟悉代码的人更容易。 ## 10.4 编写前端单元测试 为高效编写单元测试，官方提供了一小套在 test suite 里使用的工具，位于： ```text src/pybind/mgr/dashboard/frontend/src/testing/ ``` **特别要看 `unit-test-helper.ts`。** 你能找到： | 工具 | 说明 | |---|---| | `configureTestBed` | 取代初始的 `TestBed` 方法。**接受与 `TestBed.configureTestingModule` 相同的参数。** 用它**在开发时跑测试会快很多**，因为它不会每次测试都从零重建一切。**要用默认行为，传 `true` 作为第二个参数** | | `PermissionHelper` | 帮助判断**基于当前权限和列表中的选择，是否显示了正确的操作** | | `FormHelper` | 用几个简单方法让**测试表单**容易得多。可以设置单个或多个 control、断言某个 control 是否有效或有错误，或者用一个方法同时做这两件事。此外还能断言某个 template element 或多个 elements 在渲染后的模板里可见 | ## 10.5 运行前端单元测试 ```bash npm run test ``` 通过 **Jest**（https://facebook.github.io/jest/）执行单元测试。 **如果所有测试都报错**，可能是因为 Jest 或其他东西被更新了。可以尝试这样解决： ```bash rm -rf dist node_modules npm install ``` 或清 Jest 缓存： ```bash npx jest --clearCache ``` ## 10.6 运行端到端（E2E）测试 Ceph Dashboard 用 **Cypress**（https://www.cypress.io/）跑前端 E2E 测试。 ### 10.6.1 E2E 前置条件 - **需要先构建前端**。 - 在某些环境下，取决于你的用户权限和 `CYPRESS_CACHE_FOLDER`，可能需要用 `--unsafe-perm` flag 跑 `npm ci`。 - 可能需要安装额外的包才能跑 Cypress。跑 **`npx cypress verify`** 来验证。 ### 10.6.2 `run-frontend-e2e-tests.sh`（全量 E2E 首选） 官方的 `run-frontend-e2e-tests.sh` 脚本是**做全规模 e2e 跑时的首选方案**。它会：验证所需组件是否都装了 → 起一个新的 vstart 集群 → 跑完整测试套件。 ```bash $ cd src/pybind/mgr/dashboard $ ./run-frontend-e2e-tests.sh ``` | 方面 | 说明 | |---|---| | **报告** | 可以在终端跟踪 e2e 报告；失败用例的截图在 `src/pybind/mgr/dashboard/frontend/cypress/screenshots/` | | **Device** | 用 `-d` flag 强制指定设备：``，例如 `./run-frontend-e2e-tests.sh -d ` | | **Remote** | 默认脚本会停掉并重启一个新的 vstart 集群。想在 ceph 环境外跑测试，需要用 `-r` 手动指定 dashboard url，可选地用 `-u`、`-p` 指定凭据：`./run-frontend-e2e-tests.sh -r -u -p ` | | **Note** | 用 docker 作为 device 时，可能需要 sudo 权限跑脚本 | ### 10.6.3 `run-cephadm-e2e-tests.sh`（cephadm 场景） `run-cephadm-e2e-tests.sh` 跑 **E2E 测试的一个子集**，用来验证 Dashboard 与作为 Orchestrator 后端的 **cephadm** 行为是否正确。 **前置条件**：本机需要安装 **KCLI**（https://kcli.readthedocs.io/en/latest/）和 Node.js。 **配置 KCLI plan：** ```bash $ sudo chown -R $(id -un) /var/lib/libvirt/images $ mkdir -p /var/lib/libvirt/images/ceph-dashboard $ kcli create pool -p /var/lib/libvirt/images/ceph-dashboard ceph-dashboard $ kcli create network -c 192.168.100.0/24 ceph-dashboard ``` > Note：这个脚本**目标是作为 jenkins job 跑的，所以只在 jenkins 环境里触发清理。在本地，用户需要自己决定何时关掉集群（例如调试完之后）。** **启动 E2E 测试：** ```bash $ cd $ sudo chown -R $(id -un) src/pybind/mgr/dashboard/frontend/{dist,node_modules,src/environments} $ ./src/pybind/mgr/dashboard/ci/cephadm/run-cephadm-e2e-tests.sh ``` > Note（Fedora 35）：挂载 shared_folders 时可能出现权限错误，可以修： > ```bash > $ sudo setfacl -R -m u:qemu:rwx > ``` > 或者给你的 `$HOME` 目录设置合适的权限。 **开发模式启动集群**（前端构建进入 watch mode，你只需刷新页面就能看到改动）： ```bash $ ./src/pybind/mgr/dashboard/ci/cephadm/start-cluster.sh --dev-mode ``` > Note：如果需要一个**可直接部署服务**的集群（monitor 守护进程分布在多台主机上且有足够 OSD），加 **`--expanded`**。 **用改动测一遍：** ```bash $ ./src/pybind/mgr/dashboard/ci/cephadm/run-cephadm-e2e-tests.sh ``` **关闭集群：** ```bash $ kcli delete plan -y ceph $ # 在 development mode 下，还要杀掉 npm build watch 进程（例如 pkill -f "ng build"） ``` ### 10.6.4 其他运行方式（活跃开发期推荐） **在活跃开发期间，官方不建议跑上面那个脚本**，因为它没有为「文件持续变动」做准备。改用下面这些命令： | 命令 | 说明 | |---|---| | `npm run e2e` | 跑 `ng serve` 并打开 Cypress Test Runner | | `npm run e2e:ci` | 跑 `ng serve` 并把 Cypress Test Runner 跑一次 | | `npx cypress run` | 直接调 cypress 跑 Cypress Test Runner。**需要有一个正在运行的前端服务器** | | `npx cypress open` | 直接调 cypress 打开 Cypress Test Runner。**需要有一个正在运行的前端服务器** | **直接调 Cypress 的好处**：可以使用任何可用的 flags（https://docs.cypress.io/guides/guides/command-line.html#cypress-run）来定制测试运行，而且**不必每次都启动前端服务器**。 用 `open` 类命令会打开一个 cypress 应用，里面能看到所有测试文件并逐个运行。**这会以 watch mode 运行**，所以改动测试文件会重新触发测试跑。**这在 docker 里没法用，因为它需要 X11 环境才能打开。** **默认 Cypress 会在 `https://localhost:4200/` 找页面。** 如果你用别的 URL 提供服务，需要通过导出环境变量 **`CYPRESS_BASE_URL`** 来配置，例如： ```bash CYPRESS_BASE_URL=https://localhost:41076/ npx cypress open ``` ### 10.6.5 `CYPRESS_CACHE_FOLDER` 通过 npm 安装 cypress 时，cypress app 的二进制也会被下载并存在一个缓存目录里，这样**每次跑 `npm ci` 甚至在其他项目用 cypress 时都不必重新下载**。 - Cypress **默认用 `~/.cache`** 存二进制。 - 为避免改动用户 home 目录，Ceph 把这个目录改成了 **`/ceph/build/src/pybind/mgr/dashboard/cypress`**——所以当你构建 ceph 或跑 `run-frontend-e2e-tests.sh` 时，Cypress 会用这个目录。 - **当你用任何其他命令安装或运行 cypress 时，它会回到默认目录。** - **官方建议**：导出 `CYPRESS_CACHE_FOLDER` 环境变量指向一个固定目录，这样无论用哪个命令都用同一个目录。 ## 10.7 编写 E2E 测试 ### 10.7.1 `PageHelper` 类 `PageHelper` 类**用于各种页面或 suite 都能用的通用代码**。 示例方法： - `navigateTo()` —— 导航到特定页面并等待加载完成； - `getFirstTableCell()` —— 返回第一个表格单元格。也可以传一个期望内容的字符串，它会返回**第一个包含该内容的单元格**； - `getTabsCount()` —— 返回 tab 的数量。 **凡是可能在多个页面上有用的方法都放这里。** 另外，**增强 `PageHelper` 派生类的方法**也属于这里。一个好例子是 **`restrictTo()` 装饰器**：它确保 `PageHelper` 子类里实现的某个方法是在正确的页面上被调用的；如果不是，它会显示一条**对开发者友好的警告**。 ### 10.7.2 `PageHelper` 的子类 **Helper Methods**：为了让针对某个特定 suite 的代码可复用，确保把它放在 `PageHelper` 的**派生类**里。例如对 pool suite，这样的方法就是 `create()`、`exist()` 和 `delete()`——它们对 pool 是特有的，但对其他 suite 也有用。 返回**只能在特定页面上找到的 HTML 元素**的方法，应该实现在 `PageHelper` 子类的 helper methods 里，或者作为 `PageHelper` 子类自己的方法。 **Using PageHelpers**：在任何 suite 里，应该**实例化并直接调用**具体 `Helper` 类的实例： ```typescript const pools = new PoolPageHelper(); it('should create a pool', () => { pools.exist(poolName, false); pools.navigateTo('create'); pools.create(poolName, 8); pools.exist(poolName, true); }); ``` ### 10.7.3 代码风格：`describe()` vs `it()` 官方请读者参考 Cypress Core Concepts（https://docs.cypress.io/guides/core-concepts/introduction-to-cypress.html#Cypress-Can-Be-Simple-Sometimes）来更好地理解如何编写和组织测试。 **`describe()` vs `it()`：** 两者都是函数块，意味着测试需要的任何可执行代码都可以放在任一块里。但 **Typescript 的作用域规则仍然适用**，因此在 `describe` 里声明的任何变量对其中 `it()` 块都是可用的。 **`describe()`** 通常是测试的**容器**，让你把测试拆成多个部分。同样，测试运行前必须做的任何 setup 都可以在 `describe()` 块里初始化。示例： ```typescript describe('create, edit & delete image test', () => { const poolName = 'e2e_images_pool'; before(() => { cy.login(); pools.navigateTo('create'); pools.create(poolName, 8, 'rbd'); pools.exist(poolName, true); }); beforeEach(() => { cy.login(); images.navigateTo(); }); //... }); ``` 如上所示，我们可以在 `describe` 里初始化变量 `poolName`，也可以在测试套件开始前跑命令（创建 pool）。**`describe()` 块的消息应该说明这个测试套件是什么。** **`it()`** 块通常是** overarching test 的一部分**，包含测试套件的功能，各自扮演独立角色。示例： ```typescript describe('create, edit & delete image test', () => { //... it('should create image', () => { images.createImage(imageName, poolName, '1'); images.getFirstTableCell(imageName).should('exist'); }); it('should edit image', () => { images.editImage(imageName, poolName, newImageName, '2'); images.getFirstTableCell(newImageName).should('exist'); }); //... }); ``` **`it()` 的命名规范（明确要求）**：**每个 `it()` 块的消息都应该小写，并且写成能让 "it" 作为前缀的形式。** - 好：`it('edits the test image' () => ...)` —— 用 `it()` 作前缀语法通顺； - 不好：`it('image edit test' () => ...)` —— 不通顺。 **`it()` 应该描述这个单独的测试在做什么、期望发生什么。** ## 10.8 视觉回归测试（Visual Regression Testing） Ceph Dashboard 用 **Applitools Eyes**（https://applitools.com/products-eyes/）——一个 AI 驱动的自动化视觉回归测试工具。Applitools 与现有的 Cypress E2E 测试集成。 测试位置：`ceph/src/pybind/mgr/dashboard/frontend/cypress/integration/visualTests`，命名约定：**`.vrt-spec.ts`**。 ### 10.8.1 本地运行 需要 **Applitools API key**（没有可以注册免费账号）。拿到后导出为环境变量 **`APPLITOOLS_API_KEY`**。 然后就可以像普通 cypress E2E 测试一样跑：用 `npx cypress open`，或 headless 模式 `npx cypress run`。 ### 10.8.2 截图（Capturing Screenshots） **Baseline screenshots（基线截图）** 是 checkpoint screenshots（或者说你 feature 分支上的截图）用来比对的对象。 做法：**先对 master 分支跑测试**捕获 baseline，然后**切到你的 feature 分支再跑一次**捕获 checkpoint。 然后登录 applitools.com，落地页会看到 applitools eyes test runner，里面能看到你所有的截图。**如果 baseline 和 checkpoint 之间有任何视觉回归或差异（diff），会用一层遮罩高亮出来。** ### 10.8.3 写更多视觉回归测试 参考 Applitools 官方 cypress sdk 文档：https://www.npmjs.com/package/@applitools/eyes-cypress#usage ### 10.8.4 Jenkins 中的视觉回归测试 目前所有视觉回归测试在 **ceph dashboard tests**（https://jenkins.ceph.com/job/ceph-dashboard-pull-requests）这个 GitHub check 下的 Jenkins job 里跑。 ### 10.8.5 接受或拒绝差异 目前**只有 ceph dashboard 团队**有 applitools test runner 的读写权限。如果测试报告了差异： - 想**接受**它们并更新 baseline 截图，或 - 差异是**真实的回归**，想**判为失败**， 按这个指南操作：https://applitools.com/docs/topics/test-manager/pages/page-test-results/tm-accepting-and-rejecting-steps.html ### 10.8.6 调试回归 本地跑测试时如果报告了回归，可以利用 **Applitools 的 Root Cause Analysis 特性**（https://applitools.com/docs/topics/test-manager/viewers/root-cause-analysis.html）找回归原因。 ## 10.9 前端单元测试 vs E2E 测试（FAQ） ### 10.9.1 它们各自是为什么设计的？ **E2E 测试**：需要一个**功能完整的系统**，测试应用所有组件的交互（Ceph、back-end、front-end）。E2E 测试被设计成**模仿用户与应用交互时的行为**——例如创建/编辑/删除一个条目这样的工作流。测试还应验证**某些条目按用户点击 UI 时会看到的那样被显示**（例如一个菜单项，或者一个在测试中被创建的 pool 及其属性应显示在表格里）。 **Angular 单元测试**：顾名思义，是**更小代码单元**的测试。这些测试用于测试各种 Angular 组件（如 services、pipes 等）。**它们不需要连接后端，因此独立于后端。** 后端预期的数据在前端被 mock，用这些数据就能测试前端功能而不需要来自后端的真实数据。简单情况下是「静态输入 + 函数调用 + 期望的静态输出」；更复杂的例子包括组件的 state（component class 的属性）如何根据给定输入改变输出。 ### 10.9.2 什么样的测试算「有效」？ 这不好回答，但**用与已有 dashboard 测试相同方式写的新测试，一般应视为有效**。 - 单元测试应**聚焦在被测试的组件**上（Angular component、directive、service、pipe 等）。 - E2E 测试应聚焦测试**整个应用的功能**。**整体 E2E 测试中大约三分之一应该验证用户可见元素的正确性。** ### 10.9.3 一个测试应该长什么样？ - **单元测试**应聚焦所述目的，**不应试图在同一个 `it` 块里测其他东西**。 - **E2E 测试**应包含一段描述，要么验证**用户可见元素的正确性**，要么验证一个**完整流程**（例如 pool 的创建/验证/删除）。 ### 10.9.4 应该覆盖什么？ - **E2E 测试**应**主要（但不排他）覆盖与后端的交互**。这样与后端的交互就被用来写成集成测试。 - **单元测试**应主要覆盖组件的**关键或复杂功能**（Angular Components、Services、Pipes、Directives 等）。 ### 10.9.5 不应该覆盖什么？ - **避免重复测试**：不要为已经被前端单元测试覆盖的东西写 E2E 测试，反之亦然。（可能无法完全避免重叠。） - **单元测试不应**被用来大量点击组件；**E2E 测试不应**被用来大量测试单个 Angular 组件。 ### 10.9.6 最佳实践 / 指导方针 作为通用指导，官方遵循 **70/20/10 方法**： | 类型 | 占比 | |---|---| | Unit tests | **70%** | | Integration tests | **20%** | | End-to-end tests | **10%** | 进一步阅读：https://testing.googleblog.com/2015/04/just-say-no-to-more-end-to-end-tests.html 及其中提到的 "Testing Pyramid"。 ## 10.10 更多帮助与 Generator 示例 用 `ng help` 获取更多 Angular CLI 帮助，或看 Angular CLI README（https://github.com/angular/angular-cli/blob/master/README.md）。 **Generator 示例（官方原文）：** ```bash # Create module 'Core' src/app> ng generate module core -m=app --routing # Create module 'Auth' under module 'Core' src/app/core> ng generate module auth -m=core --routing or, alternatively: src/app> ng generate module core/auth -m=core --routing # Create component 'Login' under module 'Auth' src/app/core/auth> ng generate component login -m=core/auth or, alternatively: src/app> ng generate component core/auth/login -m=core/auth ``` ## 10.11 前端 TypeScript 代码风格指南（推荐） **按来源对 import 分组，组之间用空行分隔。** 来源分组可以是 **Angular**、**external** 或 **internal**。 ```typescript import { Component } from '@angular/core'; import { Router } from '@angular/router'; import { ToastrManager } from 'ngx-toastr'; import { Credentials } from '../../../shared/models/credentials.model'; import { HostService } from './services/host.service'; ``` ## 10.12 可复用前端组件 有多个组件可以在不同页面上复用，这些组件声明在 components module 里： ```text src/pybind/mgr/dashboard/frontend/src/app/shared/components ``` ### `cd-helper` 组件 **这个组件应该用来给用户提供补充信息。** ```html Some helper html text ``` ## 10.13 术语与措辞（Terminology and wording） **不要使用 Ceph 组件名，官方建议用逻辑/通用名称**：用 **Block** 而不是 RBD，用 **Filesystem** 而不是 CephFS，用 **Object** 而不是 RGW。不过由于 Ceph-Dashboard 无法完全隐藏 Ceph 内部，一些 Ceph 专有名称可能仍然可见。 **动作标签和其他文本元素（表单标题、按钮等）的措辞**，官方选择遵循这些指南：https://www.patternfly.org/styles/terminology-and-wording/#terminology-and-wording-for-action-labels **经验法则**：**大多数表单用 'Create' 和 'Delete'**，而不是 'Add' 和 'Remove'——**除非**某个已创建的条目被**加入**或**移出**一组条目（例如：给用户 'Add permission' vs 'Create (new) permission'）。 **为了强制使用这套措辞，创建了一个 `ActionLabelsI18n` service**，为 UI 元素提供翻译好的标签。 ## 10.14 前端品牌定制（Frontend branding） 每个厂商都可以按自己的需要定制 'Ceph dashboard'。无论是 logo、HTML 模板还是 TypeScript，**frontend 文件夹里的每个文件都可以被替换。** **替换方法**：打开 `./frontend/angular.json`，滚到 production 配置里的 **`fileReplacements`** 段。在这里添加你想定制的文件。 **官方命名建议**：把定制版文件放在与原文件**同一个目录**，并在**文件名里、紧挨着扩展名之前**加一个 **`.brand`**。一个 `fileReplacement` 例如： ```json { "replace": "src/app/core/auth/login/login.component.html", "with": "src/app/core/auth/login/login.component.brand.html" } ``` **serve 或 build 定制后的 UI：** ```bash $ npm run start -- --prod ``` 或 ```bash $ npm run build -- --prod ``` **两个已知限制：** 1. **serve 或 build UI 时目前无法同时使用多个 configuration**。也就是说，只为 branding 的 `fileReplacements` 单开一个 configuration 不可行，因为你反正要用 production configuration（https://github.com/angular/angular-cli/issues/10612）。 2. **`fileReplacements` 目前不支持 glob 表达式**。在该特性实现之前，你必须手工把 file replacements 加到 `angular.json`（https://github.com/angular/angular-cli/issues/12354）。 > 但**你仍应坚持建议的命名方案**，因为一旦未来支持 glob，你就容易迁移。 **改变量默认值或加自己的变量**：覆盖 `./frontend/src/styles/vendor/_variables.scss`，直接重新赋值你想改的变量，例如： ```scss $color-primary: teal; ``` **覆盖或扩展默认 CSS**：把你的样式加到 `./frontend/src/styles/vendor/_style-overrides.scss`。 ## 10.15 UI Style Guide 样式指南的创建是为了记录 Ceph Dashboard 的标准，并在整个项目中保持一致性，让贡献者更容易设计 mockup 和 Dashboard 设计。 **Ceph Dashboard 的开发环境启用了 live reloading**，UI 里的改动会反映在打开的浏览器窗口中。Ceph Dashboard 使用 **Bootstrap** 作为主要的第三方 CSS 库。 **避免重复代码。** 尽量复用已有的 SCSS 声明，与现有 UI 保持一致。 **总是先检查是否已有类似你想写的代码。** 应尽量保持与现有代码相同的 look-and-feel。 ### 10.15.1 Colors Ceph Dashboard UI 中用到的所有颜色都列在 **`frontend/src/styles/defaults/_bootstrap-defaults.scss`**。 - **使用新颜色时，总是在 `_bootstrap-defaults.scss` 里定义颜色变量，并使用变量而不是硬编码颜色值**，这样颜色的改动会反映到相似的 UI 元素上。 - Ceph Dashboard 的**主色是 `$primary`**，用于导航组件，以及作为表单 input 组件的 `$border-color`。 - **次要色是 `$secondary`**，是 Ceph Dashboard 的背景色。 ### 10.15.2 Buttons 按钮用于执行动作，如 "Submit"、"Edit"、"Create"、"Update"。 | 场景 | 主按钮 | 次按钮 | |---|---|---| | **Forms** | 用 **`cd-submit-button`** 组件；文字**应与表单标题相同**且**遵循 title case** | 用 **`cd-back-button`** 组件；文字应为 **`Cancel`** | | **Modals** | 用 **`cd-submit-button`** 组件；文字遵循 title case 且**对应要执行的动作** | 用 **`cd-back-button`** 组件；文字应为 **`Close`** | 其他约定： - **位置**：`Perform action` 按钮**始终在右**，`Cancel` 按钮**始终在左**。 - **Disclosure Button**：用于让用户显示/隐藏界面中的附加内容。 - **Action Button**：用于执行编辑或更新组件等动作。**所有 action button 都应有与其动作对应的图标**，按钮文字遵循 title case。按钮颜色应与表单主按钮颜色一致。 - **Drop Down Buttons**：用于显示预定义的动作列表。**所有 dropdown 按钮都有与其动作对应的图标。** ### 10.15.3 Links 用文本超链接作为导航，引导用户到应用中的新页面，或锚定到页面内的某个 section。**超链接的颜色应为 `$primary`。** ### 10.15.4 Forms - **用红色描边标记无效表单字段**并显示**有意义的错误消息**。消息用红色字体，**尽可能具体**。 - **必填字段的错误消息必须 exactly 是**：`This field is required.` - **用绿色描边和表单末尾的绿色对勾标记有效表单**。 - **Section 的标题不应比父级更大。** ### 10.15.5 Modals - **模糊化背景中的界面元素**，让 modal 内容成为焦点。 - **Modal 的标题应反映它能执行的动作**，并在 modal 顶部清楚写明。 - **在 footer 用 `cd-back-button` 组件关闭 modal。** ### 10.15.6 Icons - 使用 **Fork Awesome**（https://forkaweso.me/Fork-Awesome/）的 class 作为图标。 - 已使用图标清单在 **`src/app/shared/enum/icons.enum.ts`**，**HTML 里应引用这些**，便于日后修改。 - **图标与文字相邻时，水平居中对齐。图标堆叠时，也应垂直居中对齐。** - **按钮配小图标。通知配大图标。** ### 10.15.7 Navigation - **局部导航用 tabs。** - **整体导航用可展开的垂直导航**，按需折叠和展开条目。 ### 10.15.8 Alerts and notifications | 类型 | 颜色 class | |---|---| | 默认通知 | `text-info` | | 成功通知 | `text-success` | | 失败通知 | `text-danger` | ## 10.16 前端错误处理 处理前端错误有一个**通用 Error Component**，位于： ```text ./src/pybind/mgr/dashboard/frontend/src/app/core/error ``` **上报一个新错误**：只需**扩展 `error.ts` 文件里的 `DashboardError` 类**，并为新错误添加特定的 header 和 message。 **已经有一些通用错误类就位**，可以在不同场景调用和复用，例如 **`DashboardNotFoundError`** 和 **`DashboardForbiddenError`**。 用法示例： ```typescript throw new DashboardNotFoundError(); ``` ## 10.17 国际化（Internationalization, i18n） ### 10.17.1 从源码提取消息 在 `src/pybind/mgr/dashboard/frontend` 里跑： ```bash $ npm run i18n:extract ``` 这会**先从 HTML 模板里提取所有被标记的消息**，然后**把 TypeScript 文件里所有被标记的字符串加到翻译模板中**。 由于 **Angular 本身仍不支持从 TypeScript 文件提取**，官方使用 **`ngx-translator`**（https://github.com/ngx-translate/i18n-polyfill）的 extractor 来解析 TypeScript 文件。 命令成功跑完后，应该已经创建或更新了文件 **`src/locale/messages.xlf`**。 > **该文件不被 git 跟踪**，你可以用它来离线开始翻译，或用于添加/更新 transifex 上的资源文件。 ### 10.17.2 支持的语言 **所有支持的语言都应注册在 `supported-languages.enum.ts` 的两个 export 里**，并在 **`language-selector.component.spec.ts`** 里有对应的测试。 **`SupportedLanguages` enum 提供默认语言选择的列表。** ### 10.17.3 翻译流程 为了便利 Dashboard 的翻译流程，官方使用一个叫 **transifex**（https://www.transifex.com/）的 web 工具。 想帮忙翻译任何语言，只需去 transifex 项目页（https://www.transifex.com/ceph/ceph-dashboard/），加入项目，就可以立即开始翻译。 **所有翻译会被 review，之后推送到 upstream。** ### 10.17.4 更新已翻译的消息 1. 下载 **transifex CLI tool**（https://github.com/transifex/cli） 2. 创建 API token（https://www.transifex.com/user/settings/api/） 3. **推送翻译**： ```bash $ tx push -s ``` 这会把源文件推到 transifex。 4. **拉取翻译**： ```bash $ tx pull -r ceph-dashboard. -f ``` 例如 `tx pull -r ceph-dashboard.main`。这会拉取该 resource 的所有翻译。 ### 10.17.5 给 transifex 加一个新的 release resource 为了组织翻译，官方**为每一个 Ceph release 创建一个 transifex resource**。这意味着**一旦发布了新版本，release 分支上的 `src/pybind/mgr/dashboard/frontend/.tx/config` 就需要更新**。 把： ```text resource_name = Main ``` 替换成： ```text resource_name = ``` 例如 Tentacle release 的 resource 定义： ```text resource_name = Tentacle ``` 并把： ```text [o:ceph:p:ceph-dashboard:r:main] ``` 替换成： ```text [o:ceph:p:ceph-dashboard:r:] ``` 例如 Tentacle release： ```text [o:ceph:p:ceph-dashboard:r:tentacle] ``` 完成后推送翻译： ```bash $ tx push -s ``` > **Note**：只有 `` 首字母大写。 ### 10.17.6 i18n 书写建议（官方给了 4 组 avoid/recommended） **1）字符串应与元素在同一行开始和结束：** ```html Foo Foo Foo bar baz. Foo bar baz. Foo bar baz. Foo bar baz. ``` **2）孤立的插值不应被翻译：** ```html {{ foo }} {{ foo }} ``` **3）用在句子里的插值应保留在翻译中：** ```html There are {{ x }} OSDs. ``` **4）移除翻译上下文之外的元素：** ```html ``` **5）保留影响句子的元素：** ```html Profile foo will be removed. ``` ## 10.18 无障碍（Accessibility） Ceph Dashboard 的很多部分以 **WCAG 2.1**（Web Content Accessibility Guidelines 2.1，https://www.w3.org/TR/WCAG21/）**level A** 无障碍一致性指南为模型。通过实施无障碍最佳实践，你在改善 Ceph Dashboard 对盲人和视障用户的可用性。 ### 10.18.1 提交改动前的 5 项自检 1. 给**可操作的 HTML 元素**加 **ARIA labels 和 descriptions**（https://www.w3.org/TR/wai-aria/）。 2. **别忘了**给 ARIA labels/descriptions 或任何用户可读文本**打上翻译标记**（`i18n-title`、`i18n-aria-label`...）。 3. 给**行为与其本意不同**（例如 `` 标签当 `