企业官网建设流程全解析

Kimi CLI Web 接口健康探测（/healthz）指南：从 OpenAPI 生成的 DefaultApi 到 FastAPI 实现

【免费下载链接】kimi-cliKimi Code CLI is your next CLI agent.项目地址: https://gitcode.com/GitHub_Trending/ki/kimi-cli

Kimi Code CLI 的 Web 界面后端是一个基于 FastAPI 构建的本地服务，DefaultApi是其 TypeScript 客户端中由 OpenAPI 规范自动生成的基础 API 类，目前承载着唯一一个端点——GET /healthz健康探测接口。本指南将带你完整掌握该端点的 HTTP 协议细节、TypeScript 调用方式，以及它在服务端 FastAPI 应用与认证中间件中的真实实现，帮助你在本地开发、容器编排或 CI 环境中正确使用健康检查能力。

一、DefaultApi 是什么：OpenAPI 自动生成的 TypeScript 客户端基类

在 web/src/lib/api/apis/DefaultApi.ts 中，DefaultApi继承自运行时基类runtime.BaseAPI，是 kimi-cli Web 前端所有 API 客户端类（ConfigApi、SessionsApi、OpenInApi、WorkDirsApi等）之外的“默认”API 集合：

export class DefaultApi extends runtime.BaseAPI { async healthProbeHealthzGetRaw(initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<runtime.ApiResponse<{ [key: string]: any; }>> { const queryParameters: any = {}; const headerParameters: runtime.HTTPHeaders = {}; let urlPath = `/healthz`; const response = await this.request({ path: urlPath, method: 'GET', headers: headerParameters, query: queryParameters, }, initOverrides); return new runtime.JSONApiResponse<any>(response); } async healthProbeHealthzGet(initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<{ [key: string]: any; }> { const response = await this.healthProbeHealthzGetRaw(initOverrides); return await response.value(); } }

该文件头部注释明确标注其由OpenAPI Generator（typescript-fetch模板）自动生成，版本对应 OpenAPI 文档 0.1.0，并提示“不要手动编辑此类”。生成流程记录在 web/scripts/generate-api.sh 中：先请求后端http://127.0.0.1:5494/openapi.json拉取 OpenAPI 规范，再用 Docker 运行openapitools/openapi-generator-cli:v7.17.0以typescript-fetch生成器输出到src/lib/api。

注意：DefaultApi类本身没有绑定basePath前缀——所有 URIs 均相对于http://localhost（见 DefaultApi.md）。实际的基础地址由Configuration在运行时注入。

二、/healthz 端点完整规格

2.1 方法签名与返回类型

> { [key: string]: any; } healthProbeHealthzGet()

• HTTP 方法：GET
• 路径：/healthz
• 参数：无（该端点不需要任何参数）
• 返回类型：{ [key: string]: any; }，即任意 JSON 对象
• 授权：不需要任何授权（No authorization required）
• 请求头 Content-Type：未定义
• 响应头 Accept：application/json

2.2 响应状态码

唯一的成功状态码是 200，成功时返回一个 JSON 对象。

2.3 标准调用示例（TypeScript）

DefaultApi.md 给出了完整的调用模板：

import { Configuration, DefaultApi, } from ''; import type { HealthProbeHealthzGetRequest } from ''; async function example() { console.log("🚀 Testing SDK..."); const api = new DefaultApi(); try { const data = await api.healthProbeHealthzGet(); console.log(data); } catch (error) { console.error(error); } } // Run the test example().catch(console.error);

在实际工程中，导入路径应替换为真实的客户端模块入口。参考web/src/lib/api目录结构，可以这样组织：

import { DefaultApi } from '../lib/api/apis'; import { Configuration } from '../lib/api/runtime'; const config = new Configuration({ basePath: 'http://localhost:5494', // 与后端 DEFAULT_PORT 一致 accessToken: sessionToken, // 若设置了 KIMI_WEB_SESSION_TOKEN 则需要携带 }); const api = new DefaultApi(config); const data = await api.healthProbeHealthzGet(); console.log(data); // { status: "ok" }

三、服务端实现：FastAPI 中的 health_probe

健康探测端点定义在 src/kimi_cli/web/app.py 中：

@application.get("/healthz") async def health_probe() -> dict[str, Any]: # pyright: ignore[reportUnusedFunction] """Health check endpoint.""" return {"status": "ok"}

实现要点：

1. 路由挂在应用根路径：/healthz不带有/api/前缀，与config_router（/api/config）、sessions_router（/api/sessions）、work_dirs_router（/api/work-dirs）、open_in_router（/api/open-in）等业务路由区分开，专门用于探活。
2. 返回固定 JSON：{"status": "ok"}，与 OpenAPI 文档声明的返回类型{ [key: string]: any; }一致。
3. 同一文件还注册了/docs与/scalar：通过get_scalar_api_reference提供 Scalar 风格的 API 参考页面（include_in_schema=False，不进入 OpenAPI 规范）。

Web 应用的整体装配在 src/kimi_cli/web/app.py 的create_app()中完成：注册 GZip 中间件（GZIP_MINIMUM_SIZE = 1024，压缩级别 6）、静态资源缓存头中间件、AuthMiddleware与 CORS 中间件，最后挂载各业务路由。

四、为什么 /healthz 不需要鉴权：认证中间件的白名单机制

OpenAPI 文档声明该端点“No authorization required”并非随意为之，服务端 src/kimi_cli/web/auth.py 的AuthMiddleware.dispatch()明确将健康检查路径列入白名单：

async def dispatch(self, request: Request, call_next): path = request.url.path # LAN-only check applies to all requests (including static files) if self._lan_only: client_ip = get_client_ip(request) if client_ip and not is_private_ip(client_ip): return JSONResponse( status_code=403, content={"detail": "Access denied: only local network access is allowed"}, ) if request.method.upper() == "OPTIONS": return await call_next(request) if path in {"/healthz", "/docs", "/scalar"}: return await call_next(request) if not path.startswith("/api/"): return await call_next(request) # ... 后续的 Origin 校验与 Bearer Token 校验

这意味着：

• /healthz、/docs、/scalar三个路径在中间件中直接放行，无需 Bearer Token；
• 但要注意，LAN-only 限制仍然生效：如果开启了KIMI_WEB_LAN_ONLY（默认行为，lan_only=True），来自非私有 IP 的请求（包括/healthz）会先被 403 拒绝。这是健康检查在跨网络场景下探活时容易被忽略的细节——编排系统（如 Docker、Kubernetes）若从外部网络探测，需要先确认网络策略允许访问本机。

五、相关安全与部署配置速查

围绕 Web 服务的健康检查与访问控制，create_app()与 CLI 入口 src/kimi_cli/cli/web.py 提供以下可控项：

以上环境变量在 src/kimi_cli/web/app.py 与 src/kimi_cli/web/app.py 中定义。注意restrict_sensitive_apis在公开模式（非 LAN-only 且非 localhost）下会默认开启（src/kimi_cli/web/app.py），此时 open_in_router 不会被挂载，配置文件写入等敏感操作也会被拒绝。

六、实战：如何验证健康检查可用

6.1 启动 Web 服务

# 启动 kimi-cli 的 Web 界面（默认端口 5494） uv run ikimi web --port 5494

6.2 直接探测（curl / 浏览器）

curl -i http://127.0.0.1:5494/healthz

预期响应：

HTTP/1.1 200 OK content-type: application/json {"status":"ok"}

6.3 通过 TypeScript 客户端探测

按上文第三节的示例实例化DefaultApi后调用healthProbeHealthzGet()，解析返回的{ status: "ok" }即可判断后端进程是否存活、路由是否注册成功。

6.4 在编排 / CI 中使用

由于/healthz无鉴权且响应稳定，可安全地用于：

• Docker healthcheck：对容器执行curl -f http://127.0.0.1:5494/healthz；
• CI 冒烟测试：在启动 Web 服务后先探测/healthz再运行后续 API 测试；
• 反向代理上游探活：将/healthz作为 Nginx 等代理的 upstream 健康检查路径。

注意 LAN-only 限制：若探活方与被探方不在同一私有网络，需通过--network配合--lan-only false（或设置KIMI_WEB_LAN_ONLY=0）调整访问策略，否则会收到 403。

七、相关文件索引

• API 文档：web/src/lib/api/docs/DefaultApi.md
• TypeScript 客户端实现：web/src/lib/api/apis/DefaultApi.ts
• TypeScript 运行时基类：web/src/lib/api/runtime.ts
• 服务端 FastAPI 应用与/healthz路由：src/kimi_cli/web/app.py
• 认证中间件白名单逻辑：src/kimi_cli/web/auth.py
• CLI 入口与参数：src/kimi_cli/cli/web.py
• API 客户端生成脚本：web/scripts/generate-api.sh
• 相关业务路由：配置 src/kimi_cli/web/api/config.py、会话 src/kimi_cli/web/api/sessions.py、打开本地应用 src/kimi_cli/web/api/open_in.py

【免费下载链接】kimi-cliKimi Code CLI is your next CLI agent.项目地址: https://gitcode.com/GitHub_Trending/ki/kimi-cli