--- title: "读取机密信息或目录" description: "读取当前机密值、列出目录子项，或者通过资源路径后缀 /versions 与 /versions/{version} 列出和读取历史版本。" --- > 文档索引 > 完整文档索引：http://127.0.0.1:4321/docs/llms.txt # 读取机密信息或目录 读取当前机密值、列出目录子项，或者通过资源路径后缀 /versions 与 /versions/{version} 列出和读取历史版本。 **GET /api/v1/secret/{resource_path...}** - 模块：机密信息存储（Secret KV） - 认证：使用 App Header 签名或 App Secret - 系统状态：需要 unsealed ## 请求示例 ```bash curl --request GET \ 'http://127.0.0.1:7770/api/v1/secret/production/orders/database' \ --header 'X-QK-AppID: $APP_ID' \ --header 'X-QK-Timestamp: $TIMESTAMP' \ --header 'X-QK-Nonce: $NONCE' \ --header 'X-QK-Signature: $SIGNATURE' ``` ## Path 参数 | 名称 | 类型 | 必填 | 敏感 | 默认值 | 说明 | | --- | --- | --- | --- | --- | --- | | `resource_path` | `string` | 是 | 否 | — | 机密信息或目录路径；可追加 /versions 或 /versions/{version} 访问历史版本 | ## Query 参数 | 名称 | 类型 | 必填 | 敏感 | 默认值 | 说明 | | --- | --- | --- | --- | --- | --- | | `cursor` | `string` | 否 | 否 | — | 上一页响应返回的不透明分页游标 | | `limit` | `int` | 否 | 否 | `50` | 单页返回数量 | | `order` | `string` | 否 | 否 | — | 排序方向：asc 或 desc | | `q` | `string` | 否 | 否 | — | 按名称或路径搜索 | | `sort` | `string` | 否 | 否 | — | 排序字段 | ## Body 参数 无。 ## 成功响应 ### HTTP 200 · 读取当前机密值 根据资源路径返回机密值、目录子项或版本信息 ```json { "data": { "item": { "data": { "endpoint": "db.internal:5432", "password": "<数据库密码>", "username": "orders_app" }, "digest": "sm3:", "metadata": { "contact_email": "owner@example.com", "contact_name": "张三", "contact_phone": "13800000000", "created_at": "2026-08-01T08:00:00Z", "created_by": "app_orders", "current_version": 3, "department": "平台工程部", "description": "生产订单服务连接数据库使用", "labels": { "environment": "production" }, "metadata": { "ticket": "SEC-1001" }, "name": "订单数据库凭据", "organization": "示例科技", "path": "production/orders/database", "status": "active", "updated_at": "2026-08-02T08:00:00Z", "updated_by": "app_orders", "version": 2 }, "path": "production/orders/database", "version": 3 } }, "error": null, "request_id": "019fb18d-6b45-7e2d-a3b4-c5d6e7f80910" } ``` ### HTTP 200 · 列出目录子项 根据资源路径返回机密值、目录子项或版本信息 ```json { "data": { "items": [ { "current_version": 3, "name": "database", "path": "production/orders/database", "status": "active", "type": "secret" } ], "page": { "has_more": false, "limit": 50, "next_cursor": "" } }, "error": null, "request_id": "019fb18d-6b45-7e2d-a3b4-c5d6e7f80910" } ``` ### HTTP 200 · 列出历史版本 根据资源路径返回机密值、目录子项或版本信息 ```json { "data": { "items": [ { "created_at": "2026-08-02T08:00:00Z", "created_by": "app_orders", "deleted_at": null, "destroyed_at": null, "digest": "sm3:", "version": 3 } ], "page": { "has_more": false, "limit": 50, "next_cursor": "" } }, "error": null, "request_id": "019fb18d-6b45-7e2d-a3b4-c5d6e7f80910" } ``` ### HTTP 200 · 读取指定历史版本 根据资源路径返回机密值、目录子项或版本信息 ```json { "data": { "item": { "data": { "endpoint": "db.internal:5432", "password": "<历史数据库密码>", "username": "orders_app" }, "digest": "sm3:", "metadata": { "contact_email": "owner@example.com", "contact_name": "张三", "contact_phone": "13800000000", "created_at": "2026-08-01T08:00:00Z", "created_by": "app_orders", "current_version": 3, "department": "平台工程部", "description": "生产订单服务连接数据库使用", "labels": { "environment": "production" }, "metadata": { "ticket": "SEC-1001" }, "name": "订单数据库凭据", "organization": "示例科技", "path": "production/orders/database", "status": "active", "updated_at": "2026-08-02T08:00:00Z", "updated_by": "app_orders", "version": 2 }, "path": "production/orders/database", "version": 2 } }, "error": null, "request_id": "019fb18d-6b45-7e2d-a3b4-c5d6e7f80910" } ``` ## 失败响应 按 HTTP status 与 `error.code` 区分失败原因；响应始终使用统一 envelope。 ### HTTP 400 · `invalid_request` 请求参数或 JSON 请求体无效 ```json { "data": null, "error": { "code": "invalid_request", "details": {}, "message": "请求参数或 JSON 请求体无效" }, "request_id": "019fb18d-6b45-7e2d-a3b4-c5d6e7f80910" } ``` ### HTTP 400 · `not_initialized` 系统尚未初始化 ```json { "data": null, "error": { "code": "not_initialized", "details": {}, "message": "系统尚未初始化" }, "request_id": "019fb18d-6b45-7e2d-a3b4-c5d6e7f80910" } ``` ### HTTP 401 · `replayed_request` 签名请求的 nonce 已被使用 ```json { "data": null, "error": { "code": "replayed_request", "details": {}, "message": "签名请求的 nonce 已被使用" }, "request_id": "019fb18d-6b45-7e2d-a3b4-c5d6e7f80910" } ``` ### HTTP 401 · `unauthorized` App ID、App Secret 或签名无效，或者凭据已过期 ```json { "data": null, "error": { "code": "unauthorized", "details": {}, "message": "App ID、App Secret 或签名无效，或者凭据已过期" }, "request_id": "019fb18d-6b45-7e2d-a3b4-c5d6e7f80910" } ``` ### HTTP 403 · `forbidden` App 没有访问目标资源所需的权限 ```json { "data": null, "error": { "code": "forbidden", "details": {}, "message": "App 没有访问目标资源所需的权限" }, "request_id": "019fb18d-6b45-7e2d-a3b4-c5d6e7f80910" } ``` ### HTTP 404 · `not_found` 机密信息、目录或指定版本不存在 ```json { "data": null, "error": { "code": "not_found", "details": {}, "message": "机密信息、目录或指定版本不存在" }, "request_id": "019fb18d-6b45-7e2d-a3b4-c5d6e7f80910" } ``` ### HTTP 409 · `conflict` 机密信息路径或当前状态发生冲突 ```json { "data": null, "error": { "code": "conflict", "details": {}, "message": "机密信息路径或当前状态发生冲突" }, "request_id": "019fb18d-6b45-7e2d-a3b4-c5d6e7f80910" } ``` ### HTTP 413 · `request_body_too_large` 请求体超过服务端限制 ```json { "data": null, "error": { "code": "request_body_too_large", "details": {}, "message": "请求体超过服务端限制" }, "request_id": "019fb18d-6b45-7e2d-a3b4-c5d6e7f80910" } ``` ### HTTP 423 · `sealed` 系统处于封印状态 ```json { "data": null, "error": { "code": "sealed", "details": {}, "message": "系统处于封印状态" }, "request_id": "019fb18d-6b45-7e2d-a3b4-c5d6e7f80910" } ``` ### HTTP 500 · `internal_error` 服务端无法完成请求 ```json { "data": null, "error": { "code": "internal_error", "details": {}, "message": "服务端无法完成请求" }, "request_id": "019fb18d-6b45-7e2d-a3b4-c5d6e7f80910" } ``` ### HTTP 503 · `leader_unavailable` 高可用集群的 Leader 暂不可用 ```json { "data": null, "error": { "code": "leader_unavailable", "details": {}, "message": "高可用集群的 Leader 暂不可用" }, "request_id": "019fb18d-6b45-7e2d-a3b4-c5d6e7f80910" } ``` ### HTTP 503 · `maintenance_mode` 系统处于维护模式 ```json { "data": null, "error": { "code": "maintenance_mode", "details": {}, "message": "系统处于维护模式" }, "request_id": "019fb18d-6b45-7e2d-a3b4-c5d6e7f80910" } ``` Source: http://127.0.0.1:4321/docs/api/secret/get-under-resource-path/