Fleetd for Chrome:在 ChromeOS 设备上运行 Fleet 代理的构建、调试与发布指南
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 上执行:
- 把
./dist目录拷贝到目标 Chromebook; - 在 Chromebook 上打开
chrome://extensions; - 开启右上角 Developer mode(开发者模式);
- 点击 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()→uuidchrome.enterprise.deviceAttributes.getDeviceHostname()/getDeviceSerialNumber()→ 主机名与序列号chrome.enterprise.hardwarePlatform.getHardwarePlatformInfo()→ 厂商与型号chrome.system.cpu.getInfo()→ CPU 品牌与架构chrome.system.memory.getInfo()→ 物理内存
值得注意的两点:
- 开发模式降级:当
chrome.enterprise不可用(即非企业托管环境)时,会回退到开发模式,序列号留空、用 UUID 标识主机,厂商/型号写入dev-hardware_vendor/dev-hardware_model占位。这就是 README 中"在开发机上也能跑"背后的实现依据。 - 错误抑制策略:
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 先行、生产跟上”的节奏,具体步骤如下:
- 修改合并到 main 分支后,新建发布分支;
- 在仓库根目录执行
version="X.X.X" make changelog-chrome更新 CHANGELOG.md; - 人工审阅 CHANGELOG;
- 在
ee/fleetd-chrome下执行npm version X.X.X,同步更新package.json与package-lock.json中的版本号; - 提交改动并用 tag
fleetd-chrome-vX.X.X-beta打标签,触发 beta 发布工作流; - 在 Google Admin Console 中灰度测试 beta 版本(详见下文);
- beta 验证通过后,发起 PR 合入版本与 changelog 改动,并打
fleetd-chrome-vX.X.X正式标签,触发 正式发布工作流; - 在 Google Admin Console 中将 beta 扩展策略改回 Block,生产扩展恢复 Force install;
- 在 Slack 的
#help-releases与#help-engineering频道发布公告。
6.1 在 Google Admin Console 中灰度测试 beta
- 打开 Google 管理控制台(
https://admin.google.com); - 进入 设备 > Chrome > 应用和扩展程序 > 用户和浏览器;
- 在“组织部门”下选择目标 OU——若希望所有 ChromeOS 设备参与测试,选择顶层 Fleet Device Management OU(设备可能不在特定 OU 中);
- 将生产扩展 fleeedmmihkfkeemmipgmhhjemlljidg 的安装策略改为 Block 并保存,将生产扩展从设备上移除;
注意:此步骤后部分员工浏览器可能出现 “This extension is not allowed” 提示,属正常现象。
- 将 beta 扩展 bfleegjcoffelppfmadimianphbcdjkb 的策略改为 Force install 并保存,将 beta 推送至所选设备;
- 通过 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 设备未收到新版本扩展
- 先点击
chrome://extensions页面上的 Update 按钮手动触发更新; - 若仍无效,把扩展策略临时改为 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 文件。