settings.json 中 extraHeaders 不再生效，导致 CF-Access 场景客户端离线

[ryzonic]

问题描述

在使用 Cloudflare Access 保护 HAPI Hub 时，客户端需要携带 CF-Access 相关 headers。

之前版本需要在 settings.json 中配置 extraHeaders 才可以正常连接，但当前版本中 settings.json 里的 extraHeaders 似乎不再生效，导致客户端无法连接 Hub，机器显示离线。

已确认

源码中看起来：

• configuration.ts 中 extraHeaders / CF-Access headers 只从环境变量 HAPI_EXTRA_HEADERS_JSON 读取
• tokenInit.ts 初始化时只从 settings.json 读取了 cliApiToken
• _setExtraHeaders 没有业务代码调用
• settings.json 中的 extraHeaders 字段没有被读取

实际结果

即使在 settings.json 中配置了 extraHeaders，客户端请求仍未携带 CF-Access headers，导致机器离线。

期望结果

如果旧版本支持/依赖在 settings.json 中配置 extraHeaders，当前版本也应该继续兼容读取该配置。

或者文档中明确说明该配置已迁移为只支持环境变量 HAPI_EXTRA_HEADERS_JSON，并提供迁移说明。

备注

这看起来像是一个 regression：旧版本可用的 settings.json.extraHeaders 配置在当前版本中不再生效。

[github-actions]

确认：当前代码里没有找到从 ~/.hapi/settings.json 读取 extraHeaders 的路径；现在 CLI 侧额外 header 只从环境变量 HAPI_EXTRA_HEADERS_JSON 初始化。

已验证的当前行为：

• HAPI_EXTRA_HEADERS_JSON 会被解析成 configuration.extraHeaders。
• configuration.extraHeaders 会合并到 CLI -> Hub 的 REST 请求 header。
• 如果存在额外 header，也会作为 Socket.IO extraHeaders 传给机器/会话 WebSocket 连接。
• initializeToken() 只从 settings 读取 cliApiToken，没有读取 extraHeaders。
• Settings 类型目前也没有 extraHeaders 字段，公开的 settings schema 也没有该字段。

所以你描述的现象和当前代码一致：在 settings.json 里配置 extraHeaders 不会生效。当前可用迁移方式是设置环境变量，例如：

export HAPI_EXTRA_HEADERS_JSON='{"Cookie":"CF_Authorization=..."}'

如果期望继续支持旧的 settings.json.extraHeaders，这里需要补一条 CLI 配置加载路径；当前仓库里未找到这条兼容逻辑。

Relevant code:

• cli/src/configuration.ts:14 - parseExtraHeaders() 解析 HAPI_EXTRA_HEADERS_JSON
• cli/src/configuration.ts:61 - CLI 初始化 apiUrl / cliApiToken / extraHeaders，其中 extraHeaders 来自环境变量
• cli/src/ui/tokenInit.ts:31 - settings 初始化路径只读取 cliApiToken
• cli/src/persistence.ts:13 - CLI Settings 类型包含 cliApiToken / apiUrl 等，但没有 extraHeaders
• cli/src/api/hubExtraHeaders.ts:3 - REST 请求合并 configuration.extraHeaders
• cli/src/api/hubExtraHeaders.ts:10 - Socket.IO 连接使用 extraHeaders
• cli/src/api/api.ts:168 - /cli/machines REST 请求使用合并后的 headers
• cli/src/api/apiMachine.ts:377 - machine-scoped Socket.IO 连接使用额外 headers
• cli/src/api/apiSession.ts:194 - session-scoped Socket.IO 连接使用额外 headers
• docs/guide/installation.md:176 - 文档表格里 HAPI_EXTRA_HEADERS_JSON 的 settings.json 映射为 -
• docs/public/schemas/settings.schema.json:7 - settings schema properties 中没有 extraHeaders

---

HAPI Bot