Cockpit 开发实战指南从环境搭建、构建测试到调试的完整工作流HACKING.md 深度解读【免费下载链接】cockpitCockpit is a web-based graphical interface for servers.项目地址: https://gitcode.com/gh_mirrors/co/cockpitCockpit 是一个基于 Web 的服务器图形管理界面本文围绕仓库根目录的 HACKING.md 展开系统讲解面向 Cockpit 开发者的完整工作流从获取源码、搭建官方开发容器到构建会话页面、运行单元测试与集成测试、调试 Bridge 与 Web 服务再到提交贡献与发布 release note。读完本文你将掌握一套可在本地可复现的开发环境toolbox/distrobox cockpit/tasks容器与多种迭代/调试手段能够独立修改 Cockpit 的 Web 页面、Python Bridge 乃至 C 语言 Web 服务并把变更安全地提交为 Pull Request。获取源码与远程仓库的正确姿势一切开发从克隆仓库开始。HACKING.md 给出的标准操作是git clone https://github.com/cockpit-project/cockpit cd cockpit/后续所有命令都默认在仓库顶层目录执行。文档特别强调了一个易踩的坑不要克隆你自己的 fork 作为主 checkout。原因有三fork 缺少标签missing tags、无法正确确定版本号、无法与 CI bot 命令集成。正确做法是保持origin指向只读的上游仓库把你的 fork 添加为一个独立的、可写的远程仓库git remote add my gitgithub.com:yourgithubid/cockpit.git这样你可以在my上推送分支、发起 Pull Request同时origin始终与上游同步便于持续拉取最新代码。仓库根目录的 AUTHORS 记录了项目的贡献者名单tools/git-hook-pre-push、tools/git-hook-post-commit、tools/git-hook-pre-rebase 则是后续章节会提到的官方 git 钩子脚本。使用官方开发容器toolbox/distrobox cockpit/tasksCockpit 团队维护了ghcr.io/cockpit-project/tasks容器镜像同时用于本地开发与 CI。HACKING.md 强烈建议你在本机安装 toolbx 或 distrobox 后使用该容器理由包括它是 CI 的官方环境已知可用且结果可复现避免在主系统上安装一堆开发包无需把构建/测试依赖映射到各个发行版的包名。安装与创建按发行版安装 toolbox# Fedora/CentOS/RHEL 系 sudo dnf install toolbox # Debian/Ubuntu 系 sudo apt install podman-toolbox创建并进入名为cockpit的开发容器toolbox create --image ghcr.io/cockpit-project/tasks -c cockpit toolbox enter cockpit容器与宿主机共享 home 目录、用户 D-Bus 等因此你依然可以像平常一样用宿主机上的编辑器改代码构建和测试则在容器内进行需要额外软件时用sudo dnf install安装即可。刷新开发容器Cockpit 团队会不定期刷新tasks镜像。要从最新镜像重建开发容器podman pull ghcr.io/cockpit-project/tasks toolbox rm cockpit然后重复上面的toolbox create与toolbox enter两步即可。开发会话页面符号链接 dist watch 模式大多数贡献者关心的是 Cockpit 的 Web 部分HTML、JavaScript、CSS。其核心技巧是让本机 Cockpit 直接读取你本地构建产物而不是系统安装的文件。第一步先安装 Cockpit先在本地机器上安装 Cockpit参考官方 running 文档作为运行载体。第二步把构建产物目录链接到用户目录在仓库顶层执行并且务必以你稍后登录 Cockpit 所用的同一用户身份运行mkdir -p ~/.local/share/ ln -s $(pwd)/dist ~/.local/share/cockpit执行后Cockpit 会直接从本地dist/目录读取 JavaScript、HTML、CSS而不是系统安装的版本。第三步用 watch 模式持续构建推荐的构建方式是针对正在开发的那个页面启用 watch 模式-w/--watch。例如想改 pkg/systemd 下的内容./build.js -w systemd如果改动影响多个页面比如改动了 pkg/lib 下的共享文件可以构建全部页面./build.js -w从 build.js 的源码可以看到该脚本基于 esbuild 打包它先调用tools/node-modules make_package_lock_json确保node_modules就绪通过-r/--rsync指定构建后同步到的 SSH 目标-w/--watch开启监听模式onlydir参数则限定只构建pkg/DIRECTORY。开发模式下会输出 linked sourcemap并把产物输出到./dist目录QUnit 测试产物则输出到./qunit。注意 watch 模式在非 x64 架构使用 esbuild-wasm时不受支持脚本会直接报错。构建完成后用与桌面登录相同的用户名密码访问http://localhost:9090即可看到效果。watch 模式会在源文件变更时自动重建刷新浏览器就能看到改动按Ctrl-C停止监听。测试到 VMRSYNC 环境变量很多场景需要把改动拿到测试 VM 里验证。设置$RSYNC环境变量即可把构建好的页面复制到指定 SSH 目标的/usr/local/share/cockpit/目录。如果你按 test/README.md 配置了 SSHc别名指向测试 VM可以直接用RSYNCc ./build.js -w kdump RSYNCc ./build.js -w配合 build.js 中-r/--rsync参数的实现构建完成后会自动把 bundle 同步到目标主机。回到系统安装包想撤销本地覆盖、恢复使用系统安装的 Cockpit 文件删除符号链接并重新登录即可rm ~/.local/share/cockpit构建与单元测试autotools 工作流Cockpit 使用 autotools因此有熟悉的./configure脚本和 Makefile 目标。初始化构建树克隆源码后第一次构建需要运行autogen.sh./autogen.sh --prefix/usr --enable-debug从 autogen.sh 源码可见它会先用git describe --tags --abbrev0生成版本号写入version.m4然后执行autoreconf -i --warnings obsolete最后用给定参数调用configure同时它还会下载各种 nodejs 依赖node_modules。文档建议在 git 克隆环境下始终使用./autogen.sh而不是直接./configure。构建与测试make # 构建全部内容 make check # 运行单元测试Cockpit 采用单一非递归 Makefile只能在顶层执行make而且总是重建整个项目。make check应该很快完成建议高频执行。针对个别测试的调试方法编译出的二进制位于构建目录中对于 QUnitJavaScript测试运行./test-server它会输出一个可浏览器访问的 URL例如http://localhost:8765/qunit/base1/test-dbus.html调整路径可访问不同测试并查看结果QUnit 测试是作为一个名为test_browser的 pytest 测试运行的可用pytest -k筛选例如pytest -k test-fsinfo.html。JavaScript 代码覆盖率pytest -k test_browser --js-cov # 汇总表 pytest -k test-fsinfo.html --js-cov-files*/fsinfo.ts # 指定文件未覆盖明细覆盖率信息无论是否加覆盖率参数都会收集到 pytest 的 tmpdir事后可不下重跑测试直接用 test/common/js_coverage.py 分析test/common/js_coverage.py -m */fsinfo.ts /tmp/pytest-of-*/pytest-current/js-coverage/*此外还有静态代码与语法检查建议经常运行test/common/static-codegit 钩子把检查前置到提交/推送强烈建议设置 pre-push 钩子避免推送出会被平凡错误卡住的 PRln -s ../../tools/git-hook-pre-push .git/hooks/pre-push该钩子会对每个待推送的 commit 调用test/common/static-code。同样可以设置 post-commit 钩子每次提交后执行相同检查ln -s ../../tools/git-hook-post-commit .git/hooks/post-commit还有一个缓解 git submodule 痛点防止误提交子模块的陈旧指针的钩子ln -s ../../tools/git-hook-pre-rebase .git/hooks/pre-rebase理解并调试 BridgeCockpit 会话的核心进程Bridge 的定位Bridge 是 Cockpit Linux 会话中启动的第一个程序它的 stdin/stdout 连接到 web socket进而连接到页面中的 JavaScript在上面说一种 JSON 协议——该协议把“channels”复用在一起channel 是操作系统 API 的抽象页面借助它们实现功能。这个协议最终被翻译为实际的操作系统调用如打开/写文件、D-Bus 调用、HTTP 查询。文档中有一个形象的类比Bridge 之于 Cockpit 页面就像 bash 之于人的 SSH 会话。从源码看Bridge 的实现位于 src/cockpit/bridge.pyBridge类继承自Router并实现PackagesListener组装了ChannelRoutingRule、PeersRoutingRule、HostRoutingRule、SuperuserRoutingRule等路由规则把协议消息分发到具体的 channel 实现src/cockpit/channels 目录下即各类 channel。该目录被选作src/cockpit是因为它符合 Python 包的标准 src layout 约定——每个包cockpit都是src的子目录。从源码树直接运行 BridgePYTHONPATHsrc python3 -m cockpit.bridge为了免去手写协议消息的麻烦可以用cockpit.misc.print工具来模拟协议帧。它在 src/cockpit/misc/print.py 中实现Printer.json()负责把 JSON 消息打包成长度前缀 channel 名 载荷的帧格式Printer.control()发送控制消息还有open、data等便捷方法。例如打开一个fsinfochannel 读取/etc目录PYTHONPATHsrc python3 -m cockpit.misc.print open fsinfo path/etc attrs[type, entries] | PYTHONPATHsrc python3 -m cockpit.bridge两个便于实验协议的 shell 别名alias cpyPYTHONPATHsrc python3 -m cockpit.bridge alias cpfPYTHONPATHsrc python3 -m cockpit.misc.print例如跑一个内部 metrics channel每隔 1000ms 上报一次 CPU 使用率cpf open metrics1 sourceinternal interval1000 metrics[{name: cpu.basic.user, derive: rate}] : wait | cpy在测试镜像上启用 journal 调试日志可以在image-prepare时传--debug它会把COCKPIT_DEBUGall写入/etc/environment如果只想看 channel 级调试消息把all改成cockpit.channel。借助 ws 容器迭代 Bridgefedora-coreos 与 -bootc 镜像用cockpit/ws容器替代cockpit-bridge.rpm。要做 改 Bridge → 跑集成测试 的快速循环可以修改 test/common/testlib.py 的MachineCase.login_and_go()把本地开发树的 bridge 代码上传进 VM再拷入运行中的容器并 bind-mount 到正确路径--- test/common/testlib.py test/common/testlib.py -1933,6 1933,14 class MachineCase(unittest.TestCase): if enable_root_login: self.enable_root_login() self.machine.start_cockpit(tlstls) m self.machine m.execute(umount /usr/lib/python3.14/site-packages/cockpit || true) m.upload([../src/cockpit], /tmp/) m.execute(podman cp /tmp/cockpit ws:/tmp/) m.execute(podman exec ws mount -o bind /tmp/cockpit /usr/lib/python3.14/site-packages/cockpit) # first load after starting cockpit tends to take longer, due to on-demand service start with self.browser.wait_timeout(30): self.browser.login_and_go(path, useruser, passwordpassword, hosthost, superusersuperuser,其中3.14需要替换为当时的 Python 版本。测试 Bridge针对 bridge 代码的 pytest 测试在持续增加用以下命令运行make pytest # 或 make pytest-cov这两个 make 规则的作用是确保在源码目录运行 pytest 前先检出systemd_ctypes子模块。测试至少需要 pytest 7.0.0 以上版本。代码风格检查ESLint 与 StylelintESLintCockpit 用 ESLint 自动检查.js与.jsx文件的代码风格它是test/common/static-code的一部分。也可以显式运行npm run eslint # 检查 npm run eslint:fix # 自动修复大部分违规从 package.json 可以看到eslint脚本实际执行的是对pkg/与test/common/下.js/.jsx/.ts/.tsx文件的检查。规则配置位于.eslintrc.json。在快速迭代时可以用./build.js的-e/--no-eslint选项跳过 ESLint加快构建并避免因格式不当的注释、未使用的标识符等导致构建失败。Stylelint类似地Cockpit 用 Stylelint 检查.css与.scss文件风格npm run stylelint # 检查 npm run stylelint:fix # 自动修复部分违规注意npm run stylelint只覆盖pkg/下的文件而test/common/static-code覆盖 git 跟踪的全部(S)CSS 文件。规则配置位于.stylelintrc.json。快速迭代时可使用./build.js的-s/--no-stylelint选项跳过检查。在本机安全地测试改动systemd-sysext如果你想直接在本地机器上安全地测试改动Cockpit 支持以 systemd-sysext 方式安装。它覆盖 Cockpit 的所有部分ws、tls、session、bridge、登录页、systemd unit、PAM 配置、会话页面唯独不含 SELinux 策略。由于安装到/run/extensions/内存文件系统不会写盘也适用于只读安装CoreOS、OSTree、bootc。一行命令搞定tools/make-sysext从 tools/make-sysext 源码可见脚本按发行版选择 PAM 配置Fedora/CentOS/RHEL 用 tools/cockpit.pamDebian/Ubuntu 用 tools/cockpit.debian.pamArch 用 tools/arch/cockpit.pam必要时先运行./autogen.sh然后make install DESTDIRtmp/sysext装到临时目录再拷贝到/run/extensions/cockpit-git并执行systemd-sysext refresh最后启动cockpit.socket。完成后访问http://localhost:9090即可。卸载只需重启或运行tools/make-sysext stop注意该方式目前与 enforcing 模式下的 SELinux 不兼容如有需要请先禁用sudo setenforce 0本机 Web 服务器联调bind mount 方案如果 sysext 方案不可行还可以用 bind mount 测试改动。测试登录页改动——把构建树dist/覆盖到系统目录sudo mount -o bind dist /usr/share/cockpit测试品牌branding改动sudo mount -o bind src/branding/ /usr/share/cockpit/branding/如果两条命令同时执行需要先mkdir dist/branding。之后执行systemctl stop cockpit.service确保下次浏览器请求时 Web 服务器重启加载新文件。恢复系统安装版本sudo umount /usr/share/cockpit /usr/share/cockpit/branding/ systemctl stop cockpit.service改动cockpit-ws本身时可以让 systemdunit、cockpit-tls 等使用你的构建产物sudo mount -o bind cockpit-ws /usr/libexec/cockpit-wsDebian 系含 Ubuntu的路径是/usr/lib/cockpit/cockpit-ws。在 Fedora、CentOS、RHEL 及相关发行版上由于本地构建树没有预期的 SELinux 类型还需要先sudo setenforce 0。另外部分 cockpit 二进制依赖/usr/share或 libexecdir 下的特定路径默认值被设为/usr/local。RPM 系系统可通过 autogen.sh 参数设置之后需要重新构建./autogen.sh rpm从 autogen.sh 源码可见rpm参数会走rpmbuild --build-in-place -bc tools/cockpit.spec分支用与构建 RPM 相同的 flag 进行配置。从上游源码安装与构建发行包直接安装make sudo make install这会安装 Cockpit 及所有支持文件。Fedora/RHEL/CentOS 系还需安装 PAM 配置sudo cp tools/cockpit.pam /etc/pam.d/cockpitDebian/Ubuntu 系安装对应配置sudo cp tools/cockpit.debian.pam /etc/pam.d/cockpit其他发行版需要自行创建 PAM 配置。如果想安装到其他--prefix且希望make install不写入 prefix 之外可给autogen.sh指定--enable-prefix-only选项得到的是不经调整无法运行的安装仅供高级用户使用。相比直接make install构建发行包通常更健壮——升级/卸载干净且不会与/usr中的发行版包冲突# Fedora/RHEL 构建环境二进制 RPM tools/make-rpms --quick # Debian/Ubuntu 构建环境deb 包 tools/make-debs --quick管理 node_modulesgit 检出后的常规构建会自动从一个独立的 git 仓库缓存的node_modules解包。可以强制解包tools/node-modules checkout通常无需手动执行。如果需要修改package.json例如安装新模块则要运行tools/node-modules install从新package.json执行npm install的结果创建新缓存。你本地对node_modules的重建不会被其他人使用——打开 PR 后由 GitHub workflow 生成新版本。tools/node-modules脚本会检查GITHUB_BASE环境变量以确定拉取/推送的目标仓库它去掉仓库名保留项目/用户名使用该命名空间下的node-cache.git若GITHUB_BASE未设置则默认cockpit-project/node-cache.git。本地缓存维护在~/.cache/cockpit-dev。贡献一个变更PR 工作流与发布说明Pull Request 流程在 github.com 上为你的改动发起 Pull Request所有变更都会经过评审、测试与迭代。整体工作流在项目 wiki 中描述。你需要熟悉 git在分支上工作每个 commit 只包含一个单一、逻辑简单、可评审的变更且不得包含与 commit message 无关的修改。评审中来回修改是常态。评审意见下来后直接force-push 到你的分支即可自动更新 PR——不要关闭旧 PR 再开新的那会丢失对话与评审记录。Cockpit 是一个有设计流程的项目凡是用户可见的东西都要先完成设计在 wiki 和邮件列表上进行。较大的改动建议先在#cockpit:fedoraproject.orgMatrix 频道或cockpit-devellists.fedoraproject.org邮件列表讨论避免投入过多精力后才返工。功能变更应附上视频和/或截图视频可直接上传到 GitHub 的 PR/issue或上传到允许嵌入的服务。录制包含浏览器边框的视频示例仅 X11需要recordmydesktoprecordmydesktop -x 1 -y 200 --width 1024 --height 576 \ --fps 24 --freq 44100 --v_bitrate 2000000也可以先调整浏览器窗口位置再录屏——Firefox 中打开 ScratchpadShiftF4输入window.resizeTo(1024, 576); window.moveTo(1, 200);在浏览器显示空标签页如about:newtab时用CtrlR运行坐标可按环境调整。在 PR 中附带 release noteCockpit 有一套自动化的 release note 流程任何带release-note标签且描述中包含 release note 片段的 PR其内容会被用于生成 cockpit-project.org 的发布博客。格式要求是在 PR 描述末尾加一个 h2 标题标题之下的所有内容含上传的图片、视频都会被自动化抓取例如[...truncated PR description...] ## Release note title Release note text that will be picked up by automation img for release note调试日志体系系统侧journal 与 G_MESSAGES_DEBUGCockpit 各进程的消息都写入 journal可实时查看sudo journalctl -fCockpit Web 服务器有冗长的内部调试日志排查问题时可按如下步骤开启sudo mkdir -p /etc/systemd/system/cockpit-wsinstance-http.service.d sudo sh -c printf [Service]\nEnvironmentG_MESSAGES_DEBUGall\n /etc/systemd/system/cockpit-wsinstance-http.service.d/debug.conf sudo systemctl daemon-reload sudo systemctl stop cockpit除all外也可以指定具体日志域log domaincockpit-protocol极详细的底层流量日志cockpit-wsCockpit Web 服务的详细调试消息WebSocket底层 WebSocket 详细日志撤销以上改动sudo rm /etc/systemd/system/cockpit-wsinstance-http.service.d/debug.conf sudo systemctl daemon-reload sudo systemctl stop cockpit调试 HTTPS 连接时把上面命令中的http换成https。注意bridge 运行在用户会话而非 systemd 服务中其调试日志开启方式见前文 Running the bridge 一节COCKPIT_DEBUG环境变量。前端window.debugging 与浏览器存储Cockpit 的多个 JavaScript 方法支持调试消息通过设置全局window.debugging或浏览器存储中的debugging属性开启。在 JS 控制台执行 sessionStorage.debugging all这会输出大量消息更精细的取值如下all // 所有可用调试消息 channel // 发往服务器的所有 channel 消息 dbus // DBus 相关调试消息 http // HTTP经由服务器相关调试消息 spawn // 与执行进程相关的调试消息还有与具体代码相关的取值例如 metrics 页面用metrics显示调试信息。在仓库中执行git grep window.debugging pkg即可找到全部可用取值——实测 pkg/apps/utils.tsx、pkg/lib/cockpit/_internal/common.ts 等文件中都有使用。如果希望调试设置在浏览器刷新或 Cockpit 登出后依然生效用 localStorage localStorage.debugging spawn使用 React Developer ToolsCockpit 前端使用 React。由于页面加载在独立的 iframe 中React Developer Tools 开箱即用无法检查组件。解决办法是直接内嵌加载页面例如系统概览页http://localhost:9090/cockpit/localhost/system/index.html这会以独立页面加载系统概览从而允许 React Developer Tools 检查其 state。在调试器下运行 Cockpit 进程可以以普通用户身份在 gdb 或 valgrind 下运行 cockpit-ws但这样无法调试全部认证逻辑。前提是 Cockpit 已正确安装——虽然我们从构建树运行cockpit-ws但仍依赖正确的系统软件PAM 栈、UI 文件、cockpit-bridge 等。gdb 下运行export G_DEBUGfatal-criticals export G_MESSAGES_DEBUGcockpit-ws,cockpit-wrapper,cockpit-bridge gdb --args ./cockpit-ws --port 10000 --no-tlsvalgrind 下运行 cockpit-ws 与 cockpit-bridgeexport G_DEBUGfatal-criticals export G_MESSAGES_DEBUGcockpit-ws,cockpit-wrapper,cockpit-bridge valgrind --trace-childrenyes --trace-children-skip*unix_chkpwd* \ ./cockpit-ws --port 10000 --no-tls注意 cockpit-session 与 cockpit-bridge 会从已安装的 prefix 运行而不是你的构建树。调试难以捕获的 UI 元素大多数场景可以直接用浏览器调试器给感兴趣的元素打断点但对弹出菜单等响应mouseenter/mouseleave的元素行不通。技巧是在开发者控制台运行setTimeout(() { debugger }, 5000)然后执行鼠标操作如悬停等待超时触发断点即可。用 curl 手动建立登录会话与 WebSocket迭代登录 / websocket ←→ bridge 集成时下面这条命令会登录标准的测试 VMhttps://127.0.0.2:9091并建立 websocket 连接与用户会话curl -ksS -D- -u admin:foobar --cookie-jar /tmp/cookie https://127.0.0.2:9091/cockpit/login --no-buffer -HConnection: Upgrade -HUpgrade: websocket -HHost: 127.0.0.2:9091 -HOrigin: https://127.0.0.2:9091 -HSec-Websocket-Key: 3sc2c9IzwRUc3BlSIYwtSA -HSec-WebSocket-Version: 13 https://127.0.0.2:9091/cockpit/socket返回类似{csrf-token:e3074fc5e06cb3804ad8c3463fc6727c67ac245dd3c39590e486644759a42818}HTTP/1.1 101 Switching Protocols其中的 csrf-token 就是会话令牌。可用--cookie-jar继续发起需要认证的 HTTP 请求。注意由于没有浏览器保持连接会话在约 10 秒不活跃后超时。手动安装开发依赖备用方案如果可能请优先使用上文 toolbox/distrobox cockpit/tasks容器方案。在主机手动安装全部开发依赖侵入性强、易出错、难调试。以下仅作备用。至少需要 node.js 与 npm# Fedora/CentOS ( 9) sudo dnf install npm # Debian/Ubuntu sudo apt install npm运行测试所需依赖sudo dnf install curl expect xz rpm-build chromium-headless dbus-daemon \ libvirt-daemon-driver-storage-core libvirt-daemon-driver-qemu libvirt-client python3-libvirt \ python3-pyyaml编译 C 部分需要包的构建依赖sudo dnf install dnf-utils python-srpm-macros sudo dnf builddep --spec tools/cockpit.spec延伸阅读集成测试的完整说明见 test/README.md包括test/image-prepare准备镜像、test/verify/check-metrics TestCurrentMetrics.testCPU运行单个用例、TEST_OS/TEST_BROWSER/TEST_SHOW_BROWSER等环境变量、nondestructive测试约定、bots/vm-run手动测试以及像素测试pixel tests的更新流程架构细节在 test/ARCHITECTURE.md。Bridge 所讲 JSON 协议 的完整规范可对照 src/cockpit/protocol.py 中的CockpitProblem等协议实现一起阅读。构建脚本 build.js 与 autogen.sh 是理解构建流程的第一手材料package.json 定义了全部 lint 与测试脚本。【免费下载链接】cockpitCockpit is a web-based graphical interface for servers.项目地址: https://gitcode.com/gh_mirrors/co/cockpit创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考