Kimi CLI Web 接口健康探测/healthz指南从 OpenAPI 生成的 DefaultApi 到 FastAPI 实现【免费下载链接】kimi-cliKimi Code CLI is your next CLI agent.项目地址: https://gitcode.com/GitHub_Trending/ki/kimi-cliKimi 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): Promiseruntime.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.JSONApiResponseany(response); } async healthProbeHealthzGet(initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise{ [key: string]: any; } { const response await this.healthProbeHealthzGetRaw(initOverrides); return await response.value(); } }该文件头部注释明确标注其由OpenAPI Generatortypescript-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未定义响应头 Acceptapplication/json2.2 响应状态码状态码描述响应头200Successful Response无唯一的成功状态码是 200成功时返回一个 JSON 对象。2.3 标准调用示例TypeScriptDefaultApi.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}实现要点路由挂在应用根路径/healthz不带有/api/前缀与config_router/api/config、sessions_router/api/sessions、work_dirs_router/api/work-dirs、open_in_router/api/open-in等业务路由区分开专门用于探活。返回固定 JSON{status: ok}与 OpenAPI 文档声明的返回类型{ [key: string]: any; }一致。同一文件还注册了/docs与/scalar通过get_scalar_api_reference提供 Scalar 风格的 API 参考页面include_in_schemaFalse不进入 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_code403, 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_onlyTrue来自非私有 IP 的请求包括/healthz会先被 403 拒绝。这是健康检查在跨网络场景下探活时容易被忽略的细节——编排系统如 Docker、Kubernetes若从外部网络探测需要先确认网络策略允许访问本机。五、相关安全与部署配置速查围绕 Web 服务的健康检查与访问控制create_app()与 CLI 入口 src/kimi_cli/cli/web.py 提供以下可控项配置环境变量 / CLI 参数默认值作用监听地址--host/--network127.0.0.1--network绑定 0.0.0.0控制 Web 服务可达范围端口--port5494DEFAULT_PORTHTTP 服务端口会话令牌KIMI_WEB_SESSION_TOKEN/--auth-token无未设置则不要求除/healthz、/docs、/scalar外的 API 鉴权允许的 OriginKIMI_WEB_ALLOWED_ORIGINS/--allowed-origins本地开发正则CORS 来源校验强制 Origin 校验KIMI_WEB_ENFORCE_ORIGIN/--enforce-origin依部署模式拒绝未授权 Origin禁用敏感 APIKIMI_WEB_RESTRICT_SENSITIVE_APIS/--restrict-sensitive-apis公开模式下自动开启关闭配置写入、open-in 等敏感能力LAN-onlyKIMI_WEB_LAN_ONLYtrue仅允许私有网络访问对/healthz同样生效以上环境变量在 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 54946.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/healthzCI 冒烟测试在启动 Web 服务后先探测/healthz再运行后续 API 测试反向代理上游探活将/healthz作为 Nginx 等代理的 upstream 健康检查路径。注意 LAN-only 限制若探活方与被探方不在同一私有网络需通过--network配合--lan-only false或设置KIMI_WEB_LAN_ONLY0调整访问策略否则会收到 403。七、相关文件索引API 文档web/src/lib/api/docs/DefaultApi.mdTypeScript 客户端实现web/src/lib/api/apis/DefaultApi.tsTypeScript 运行时基类web/src/lib/api/runtime.ts服务端 FastAPI 应用与/healthz路由src/kimi_cli/web/app.py认证中间件白名单逻辑src/kimi_cli/web/auth.pyCLI 入口与参数src/kimi_cli/cli/web.pyAPI 客户端生成脚本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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考