docs: 补充API运行时健康说明

API.md

@@ -50,6 +50,31 @@ Admin、Component、Dict、MinIO、Blog 管理、WordPress 管理和 QQBot 管
 - 后端格式化时间字段统一使用 `KtDateTime extends Date`：Entity 通过 `@KtDateTimeColumn(format)`、`@KtCreateDateColumn(format)`、`@KtUpdateDateColumn(format)` 在 TypeORM hydrate 边界转换；DTO/外部数据源通过 `@KtDateTimeField(format)` + `transformKtDateTimeFields()` 转换。默认输出 `YYYY-MM-DD HH:mm:ss`，可在装饰器中传入格式字符串；响应包装不做递归遍历。
 - `POST */save` 默认会删除请求体里的 `id`，防止新增接口误用前端主键。
 
+## Runtime Health
+
+| 方法  | 路径              | 认证 | 说明                               |
+| ----- | ----------------- | ---- | ---------------------------------- |
+| `GET` | `/health/runtime` | 否   | API 运行时健康和脱敏配置快照       |
+
+该接口返回 plain JSON，不使用 Vben 响应包装，供本地 smoke、Jenkins/K8s 和 ktWorkflow 观测脚本直接读取。接口位于 Swagger 基础能力分组 `/api/basic`。
+
+顶层字段：
+
+| 字段        | 说明                                             |
+| ----------- | ------------------------------------------------ |
+| `service`   | 固定为 `kt-template-online-api`                  |
+| `checkedAt` | ISO 时间字符串                                   |
+| `status`    | `live`、`ready`、`degraded` 或 `blocked`         |
+| `checks`    | 进程和配置检查列表                               |
+| `config`    | 脱敏后的运行时配置快照，不包含原始 secret/token |
+
+状态含义：
+
+- `live`：NestJS 进程能响应健康请求。
+- `ready`：关键配置存在，当前检查未发现缺失项。
+- `degraded`：可选运行时配置缺失，核心 API 可继续工作。
+- `blocked`：关键运行时配置缺失，不能声明部署或运行态成功。
+
 ## 环境变量分组
 
 | 分组        | 关键变量                                                                                                                                                                                 |

README.md

@@ -121,6 +121,18 @@ pnpm exec jest --runInBand --runTestsByPath test/path/to/file.spec.ts
 }
 ```
 
+## 运行时健康检查
+
+API 暴露 `GET /health/runtime` 作为本地 smoke、Jenkins/K8s 和 ktWorkflow 观测入口。该接口返回 plain JSON，不使用 Vben 响应包装，便于脚本直接读取。
+
+返回内容包括：
+
+- `status`：`live`、`ready`、`degraded` 或 `blocked`。
+- `checks`：进程存活和运行时配置检查。
+- `config`：已脱敏的运行时配置快照，不包含原始密码、Token、Cookie、SSH key 或验证码票据。
+
+`blocked` 表示关键配置缺失；`degraded` 表示可选运行时配置缺失，核心 API 仍可继续工作。本地未配置 Loki、WordPress、NapCat 等可选依赖时，健康状态可能保持 `degraded`。
+
 ## 核心规则
 
 - 后台主键使用 Snowflake 数字 ID，数据库字段为 `BIGINT`，接口按字符串返回。