Fleetd for Chrome:在 ChromeOS 设备上运行 Fleet 代理的构建、调试与发布指南

原创2026-09-19 20:20:501,721 阅读

Fleetd for Chrome:在 ChromeOS 设备上运行 Fleet 代理的构建、调试与发布指南

导读:本文以开源仓库 ee/fleetd-chrome 目录下的官方文档 ee/fleetd-chrome/README.md 为核心,系统讲解 Fleet 如何在 ChromeOS 设备上以浏览器扩展(Chrome Extension)形态运行 osquery 代理。你将掌握扩展的本地打包方式、手动注册(Enroll)到 Fleet 服务器的完整流程、Service Worker 的调试方法、自动化测试与版本发布机制,并结合源码理解其基于 wa-sqlite 虚拟表的本地 SQL 引擎与每分钟心跳的轮询架构。

一、Fleetd for Chrome 是什么

Fleet 是开源的设备管理平台(Open device management),其传统形态的 agent(fleetd/orbit)运行在 macOS、Windows、Linux 与 Android 上。而对于 ChromeOS / Chromebook 设备,仓库采用的是另一种轻量承载方式:一个以 Manifest V3 编写的 Chrome 扩展,名为 Fleetd for Chrome,位于 ee/fleetd-chrome 目录。

从 manifest.json 可以看到它的关键声明:

  • manifest_version: 3,使用 Service Worker 作为后台;
  • update_url: "https://chrome.fleetdm.com/updates.xml",用于官方版本的自动更新;
  • 声明了大量系统级权限,如 enterprise.deviceAttributes、enterprise.hardwarePlatform、system.cpu、system.memory、system.storage、management、platformKeys、storage 等,这些是采集 Chromebook 硬件信息、执行注册与远程管理所必需的;
  • 通过 storage.managed_schema: "schema.json" 接入企业策略配置。

企业管理员正是通过 Google Admin Console 将此类扩展以“强制安装”策略下发到指定 OU 的 ChromeOS 设备上,从而让 Fleet 服务器能看到并管理这些 Chromebook。

二、在本地打包扩展

2.1 生成 PEM 密钥文件

发布 Chrome 扩展必须使用固定的密钥签名,否则每次打包都会生成不同的扩展 ID,导致自动更新与策略安装失效。在父目录下执行:

/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --pack-extension=./fleetd-chrome --pack-extension-key=path/to/chrome.pem

该命令使用本机 Chrome 将 fleetd-chrome 目录打包为 .crx 文件,并使用指定的 .pem 私钥签名。其中 path/to/chrome.pem 需要替换为真实密钥路径。

2.2 本地开发服务器(可选)

仓库在 server.go 中附带了一个极简的 Go 静态文件服务器,用于在本地开发时以 http://localhost:1337 提供扩展文件(特别是 .crx 文件的 Content-Type 会被设置为 application/x-chrome-extension):

if tFile.MatchString(ruri) {
    w.Header().Set("Content-Type", "application/x-chrome-extension")
}

不过 README 也明确指出,日常开发通常直接使用 Chrome 的“加载已解压的扩展程序”(Load unpacked)功能,而无需启动该服务器。

三、将 ChromeOS 设备接入 Fleet(手动 Enroll)

3.1 配置环境变量

在 ee/fleetd-chrome 目录下创建 .env 文件:

echo 'FLEET_URL="https://your-fleet-server.example.com"' >> .env
echo 'FLEET_ENROLL_SECRET="<your enroll secret>"' >> .env

重要前提:FLEET_URL 指向的地址必须拥有有效的 TLS 证书。扩展在注册与通信时使用 HTTPS 请求,自签名证书会导致握手失败。

本地测试时若 Fleet 服务器跑在 localhost:8080,可用内网穿透工具将其暴露为带合法证书的 HTTPS 地址:

Tunnelmole:

tmole 8080

ngrok:

ngrok http https://localhost:8080

注意示例中 ngrok 的目标写法是 https://localhost:8080(如果你的本地 Fleet 已启用 HTTPS 则照此使用;若为纯 HTTP 服务,请相应调整)。

3.2 构建未打包扩展

npm install && npm run build

build 脚本(见 package.json)实际执行的是 webpack --config webpack.prod.js,产物输出到 ./dist 目录。webpack 会在打包过程中把 .env 中的 FLEET_URL、FLEET_ENROLL_SECRET 注入到 background.ts 中声明的两个全局变量里:

declare var FLEET_URL: string;
declare var FLEET_ENROLL_SECRET: string;

这也是 .env 必须放在 ee/fleetd-chrome 目录下执行构建的原因。

3.3 在 Chromebook 上加载扩展

前三步可以在开发机完成,最后一步必须在目标 Chromebook 上执行:

  1. 把 ./dist 目录拷贝到目标 Chromebook;
  2. 在 Chromebook 上打开 chrome://extensions;
  3. 开启右上角 Developer mode(开发者模式);
  4. 点击 Load unpacked(加载已解压的扩展程序),选择 dist 文件夹。

加载后扩展会立即尝试注册:如果目标 Chromebook 上已有企业策略配置了 fleet_url / enroll_secret,则以策略值为准;否则回退到构建时注入的 .env 值。这一逻辑对应 background.ts 中的:

const { fleet_url } = await chrome.storage.managed.get({ fleet_url: FLEET_URL });
const { enroll_secret } = await chrome.storage.managed.get({ enroll_secret: FLEET_ENROLL_SECRET });

3.4 注册原理:enroll 与 node_key

background.ts 中的 enroll() 完整展示了注册过程:

const os_version = (await DATABASE.query("SELECT * FROM os_version")).data;
const system_info = (await DATABASE.query("SELECT * FROM system_info")).data;
const host_details = { os_version: os_version[0], system_info: system_info[0] };
  • 主机标识符(host_identifier)优先取 system_info.hardware_serial(即 Chromebook 硬件序列号),取不到时回退为 uuid(由 chrome.instanceID.getID() 生成);
  • 向 Fleet 服务器 POST /api/v1/osquery/enroll,携带 enroll_secret、host_details、host_identifier;
  • 服务器返回 node_key,扩展将其保存到 chrome.storage.local。之后的所有请求(如分布式查询读写)都会携带该 node_key 作为身份凭证。

若服务器在响应中返回 node_invalid(节点失效,例如设备被删除或密钥轮换),扩展会清除本地 node_key 并触发一次自动重新注册(reenroll),重试时禁用递归以避免死循环。这正是 README 排障章节中“enroll failed: no matching secret found”错误背后对应的服务端逻辑。

四、架构剖析:扩展如何“模拟” osquery

Fleet 的查询体系建立在 osquery 之上,而 Chrome 扩展无法直接运行 osquery 二进制。fleetd-chrome 的解法是:在扩展内用 WASM 版 SQLite(wa-sqlite)搭建一个虚拟数据库,把各系统信息表注册为 SQLite 虚拟表,从而让 osquery SQL 可以原样执行。

4.1 虚拟数据库初始化

db.ts 在内存中打开 SQLite,并注册了以下虚拟表:

表名 实现文件 说明
chrome_extensions tables/chrome_extensions.ts 已安装的 Chrome 扩展清单
disk_info tables/disk_info.ts 磁盘容量信息
geolocation tables/geolocation.ts 地理位置
network_interfaces tables/network_interfaces.ts 网络接口
privacy_preferences tables/privacy_preferences.ts 隐私偏好设置
screenlock tables/screenlock.ts 锁屏策略状态
system_info tables/system_info.ts 系统与硬件信息
system_state tables/system_state.ts 系统运行状态
os_version tables/os_version.ts 操作系统版本
osquery_info tables/osquery_info.ts 模拟 osquery 自身元信息
users tables/users.ts 用户账户列表

4.2 虚拟表基类

tables/Table.ts 是所有表的抽象基类,它把 wa-sqlite 的虚拟表方法(xConnect、xFilter、xNext、xEof、xColumn、xRowid 等)封装为统一模式:子类只需声明 name、columns 并实现 generate() 方法,返回 { data, warnings }。查询触发时,wa-sqlite 调用 xFilter → generate() 异步拉取 Chrome API 数据 → 游标逐行交给 SQLite 返回。

基类中还处理了一个重要的工程细节:不能在 SQLite 内部抛 JS 异常,否则会导致 WASM 栈内存耗尽(注释引用了 wa-sqlite 的已知 issue),因此在 xFilter 中用 try/catch 捕获后返回 SQLITE_ERROR。

4.3 数据采集示例:system_info

以 tables/system_info.ts 为例,它通过多个 Chrome 企业 API 采集数据:

  • chrome.instanceID.getID() → uuid
  • chrome.enterprise.deviceAttributes.getDeviceHostname() / getDeviceSerialNumber() → 主机名与序列号
  • chrome.enterprise.hardwarePlatform.getHardwarePlatformInfo() → 厂商与型号
  • chrome.system.cpu.getInfo() → CPU 品牌与架构
  • chrome.system.memory.getInfo() → 物理内存

值得注意的两点:

  1. 开发模式降级:当 chrome.enterprise 不可用(即非企业托管环境)时,会回退到开发模式,序列号留空、用 UUID 标识主机,厂商/型号写入 dev-hardware_vendor / dev-hardware_model 占位。这就是 README 中"在开发机上也能跑"背后的实现依据。
  2. 错误抑制策略:getHardwarePlatformInfo() 返回 "Not allowed" 时不会计入 warnings,因为当设备所在 OU 未开启 EnterpriseHardwarePlatformAPIEnabled 时这是预期错误,而 warnings 会导致整条查询被标记为失败(status=1)。

os_version 表则通过 navigator.userAgentData.getHighEntropyValues() 解析 Chrome 版本号,并按 Chromium 的 MAJOR.MINOR.BUILD.PATCH 规则拆分为 major/minor/build/patch 字段,同时将 platform 硬编码为 "chrome",确保 Fleet 始终把该扩展识别为 Chrome 设备(即使本地开发跑在非 ChromeOS 机器上)。

4.4 后台主循环与心跳

background.ts 定义了扩展的驱动逻辑:

  • 入口 main() 首先校验平台:非 Chrome OS 且非开发模式安装时拒绝运行("Refusing to run on non Chrome OS with managed install!");
  • 初始化数据库(无 node_key 时先 enroll()),然后执行一次 live_query();
  • live_query() 通过 POST /api/v1/osquery/distributed/read 拉取服务器下发的查询,逐条执行 discovery 查询与正式查询,再通过 POST /api/v1/osquery/distributed/write 回传结果与状态码(status 0 成功、1 失败/有警告);
  • mainLoop() 每 10 秒用 setTimeout 调度一次主循环,并用 async-mutex 保证同一时刻只有一个实例在运行(60 秒超时,重复触发时打印 'main' mutex already locked, skipping run);
  • 另注册一个 periodInMinutes: 1 的 chrome.alarms 定时器,确保 Service Worker 至少每分钟被唤醒一次,防止被 Chrome 在后台杀掉;
  • 若 wa-sqlite 抛出了 "memory access out of bounds" 运行时错误,会重建整个数据库实例以防扩展失去响应。

这套机制解释了 README 中"自动更新大约每天一次、可手动点 Update 按钮"以及"Service Worker 日志可查"等行为的底层原因。

五、调试技巧

5.1 查看 Service Worker 日志

  • 生产环境:打开 chrome://serviceworker-internals/?devtools 查看 Service Worker 日志;
  • 开发环境:在 chrome://extensions 页面中,找到 Fleetd for Chrome,点击 "Inspect views service worker"(检查视图 Service Worker)链接,即可打开 DevTools 查看 Console。

background.ts 中有大量 console.debug / console.warn / console.error 输出(如请求 URL、响应 JSON、node_key empty 警告等),是定位问题的一手线索。

5.2 验证数据库表结构(测试辅助)

开发时也可借助仓库自带的测试基建验证表实现。源码为每个关键表都配备了单元测试,例如 tables/disk_info.test.ts、tables/os_version.test.ts、tables/screenlock.test.ts、tables/system_info.test.ts、tables/system_state.test.ts、tables/geolocation.test.ts,以及 db.test.ts。测试使用 Jest + MSW(mocks/handlers.ts、mocks/server.ts)模拟 Chrome API 与网络请求。

运行全部测试:

npm run test

底层执行的是 NODE_OPTIONS=--experimental-vm-modules jest(package.json),开发时可使用 npm run test-watch 进入监听模式。

六、发布流程与自动更新

发布遵循“beta 先行、生产跟上”的节奏,具体步骤如下:

  1. 修改合并到 main 分支后,新建发布分支;
  2. 在仓库根目录执行 version="X.X.X" make changelog-chrome 更新 CHANGELOG.md;
  3. 人工审阅 CHANGELOG;
  4. 在 ee/fleetd-chrome 下执行 npm version X.X.X,同步更新 package.json 与 package-lock.json 中的版本号;
  5. 提交改动并用 tag fleetd-chrome-vX.X.X-beta 打标签,触发 beta 发布工作流;
  6. 在 Google Admin Console 中灰度测试 beta 版本(详见下文);
  7. beta 验证通过后,发起 PR 合入版本与 changelog 改动,并打 fleetd-chrome-vX.X.X 正式标签,触发 正式发布工作流;
  8. 在 Google Admin Console 中将 beta 扩展策略改回 Block,生产扩展恢复 Force install;
  9. 在 Slack 的 #help-releases 与 #help-engineering 频道发布公告。

6.1 在 Google Admin Console 中灰度测试 beta

  1. 打开 Google 管理控制台(https://admin.google.com);
  2. 进入 设备 > Chrome > 应用和扩展程序 > 用户和浏览器;
  3. 在“组织部门”下选择目标 OU——若希望所有 ChromeOS 设备参与测试,选择顶层 Fleet Device Management OU(设备可能不在特定 OU 中);
  4. 将生产扩展 fleeedmmihkfkeemmipgmhhjemlljidg 的安装策略改为 Block 并保存,将生产扩展从设备上移除;

    注意:此步骤后部分员工浏览器可能出现 “This extension is not allowed” 提示,属正常现象。

  5. 将 beta 扩展 bfleegjcoffelppfmadimianphbcdjkb 的策略改为 Force install 并保存,将 beta 推送至所选设备;
  6. 通过 Chrome 扩展管理器确认 beta 已安装,然后开始测试。

6.2 更新机制

  • 两个扩展 ID 分别对应正式版与 beta 版构建产物,更新清单 updates.xml(正式版)与 updates-beta.xml 中记录了 codebase 与版本号,构建时版本号会被替换(FLEETD_CHROME_VERSION 占位符);
  • 借助 GitHub Actions,构建产物会自动上传到 R2 对象存储,配置正确的客户端会在任务完成后自动更新;
  • 注意:Chrome 的自动更新大约每天才检查一次,需要立即更新时可在 chrome://extensions 页面点击 Update(更新) 按钮手动触发。

七、常见问题排查

排查已发布扩展(beta 或生产)的第一步:打开 chrome://extensions,开启右上角 Developer mode,点击扩展条目下的 “Inspect views service worker”,在 Console 中查看错误日志。

7.1 Chromebook 未出现在 Dogfood 中

若日志中出现 enroll failed: no matching secret found,请检查 Google Admin Console 中该扩展的“扩展程序策略”设置(应用和扩展程序 > 用户和浏览器 > 选择 fleet 扩展 > 滚动到右侧面板底部):

  • 确保 enroll_secret 的取值是 Fleet Dogfood 实例上真实有效的注册密钥;
  • 同时确认 schema.json 中定义的 fleet_url 与 enroll_secret 两个托管策略键(managed policy keys)与 Admin Console 中下发的一致——扩展启动时优先读取企业托管策略,构建时注入的 .env 仅在无策略时作为回退。

7.2 设备未收到新版本扩展

  1. 先点击 chrome://extensions 页面上的 Update 按钮手动触发更新;
  2. 若仍无效,把扩展策略临时改为 Block,等待其从设备移除,再改回 Force install 强制重装。

八、小结

Fleetd for Chrome 用约 20 个源文件将 osquery 的核心能力移植到了 ChromeOS 生态:以 Manifest V3 Service Worker 承载每 10 秒一次的轮询主循环,用 wa-sqlite 虚拟表忠实复刻 osquery 表模型,通过 enroll / distributed/read / distributed/write 三个端点与 Fleet 服务器完成注册和分布式查询,并依托 Google Admin Console 的企业策略完成规模化下发与灰度发布。对于需要管理 Chromebook 的团队,本文覆盖的打包、调试、测试与发布流程足以支撑从本地验证到生产上线的完整闭环。

延伸阅读:可结合 docs 目录 中的 Chromebook 注册文档(如 enroll-hosts.md)与 ee/fleetd-chrome/CHANGELOG.md 了解各版本能力演进;测试实现可参阅 db.test.ts 与各 *.test.ts 文件。

登录后查看全文