Appearance
服务配置 · 使用说明（小白向）
本文说明：服务器管理 → 服务配置 页面怎么用——统一管理动态 API、自定义 API 运行面的鉴权、流量与网络策略。
适合：项目管理员、运维、对接动态/自定义 API 的后端开发。
关联：动态API-用户项目接入与鉴权说明 · 自定义API-使用说明
阅读建议
| 你是谁 | 建议先看 |
|---|---|
| 要开鉴权 | 第 4 章 + 动态API-用户项目接入与鉴权说明 第 4 章 |
| 自定义 API 对外 | 第 5 章 + 自定义API-使用说明 |
| 401 大面积失败 | 第 8 章「紧急收紧」+ FAQ |
1. 一句话
服务配置 = 项目级「运行面安检台」：
控制 /yc/dynamic-api/ 和 /yc/custom-api/ 要不要凭证、用什么方式验、IP 是否受限、Token 有效期多长。
不是在这里配表结构或接口业务逻辑——那些分别在 数据模型、自定义 API 里做。
2. 名词解释
| 名词 | 说明 |
|---|---|
| 运行面 | 给业务系统调的 HTTP API，前缀 /yc/dynamic-api/、/yc/custom-api/ |
| 管理面 / 控制台 | 你登录 sky-curtain 配项目的界面 |
| 启用运行时鉴权 | 总开关；打开后运行面默认要凭证 |
| 校验方式 | 平台凭证换 Token / RSA / 项目 JWT / API Key 四选一 |
| 项目 ID | 页面顶部展示，可复制；拼在运行面 URL 里 |
| 紧急收紧 | 一键关闭运行时鉴权，用于密钥泄露或误配导致大面积 401 |
| 单接口鉴权 | 动态 API 每条接口的 security 在 数据模型 → 发布配置 里设 |
3. 入口与页面结构
路径：项目 → 服务器管理 → 服务配置
页面区块：
| 区块 | 管什么 |
|---|---|
| 工具栏 | 项目 ID、复制、刷新、紧急收紧 |
| 鉴权与凭证 | 启用鉴权、校验方式、JWT 密钥、接入密钥、RSA 等 |
| 自定义 API 对外接入 | 是否对外、接入密钥、Token TTL、QPS |
| 网络与 IP | 是否强制 IP 白名单、信任代理头、允许 IP 列表 |
底部 保存配置 统一提交（分块保存到后端）。
4. 动态 API 鉴权（最常用）
4.1 操作步骤
- 打开 服务配置。
- 启用运行时鉴权 → 开。
- 校验方式 选一种（见下表）。
- 按所选方式生成或填写密钥。
- 点击 保存配置。
- 改完建议 重启 yc_user_service 后再试调。
4.2 四种校验方式怎么选
| 方式 | 适合 | 平台要配 | 业务后端要配 |
|---|---|---|---|
| 平台凭证换 Token | 正式项目、有 BFF | 生成 ycdk_... 接入密钥 | YC_PLATFORM_ACCESS_KEY |
| RSA 私钥签 JWT | 高安全 | 生成密钥对，平台存公钥 | 私钥 PEM |
| 项目 JWT | 演示、PoC | JWT 签名密钥 = 业务 JWT_SECRET | 用户登录 JWT 转发给天幕 |
| API Key | 内网简单联调 | 服务 API Key | 请求头 X-Api-Key |
详细说明、请求示例、FAQ 见：动态API-用户项目接入与鉴权说明。
4.3 生成接入密钥（平台凭证模式）
- 校验方式选 平台凭证换 Token。
- 点击 生成接入密钥。
- 弹窗中
ycdk_...只显示一次，立即复制到业务服务器.env。 - 保存配置。
4.4 JWT 签名密钥（项目 JWT 模式）
- 校验方式选 项目 JWT。
- 在 JWT 签名密钥 填写与业务后端
JWT_SECRET完全相同的字符串。 - 已配置过可显示「已配置密钥」；点 修改密钥 才显示输入框。
- 留空不填 = 不修改已保存密钥，不是「这次不用鉴权」。
4.5 默认端点策略
| 选项 | 含义 |
|---|---|
| 跟随项目是否启用鉴权 | 项目开鉴权则 inherit 接口也要凭证 |
| 不需要鉴权（匿名） | 默认端点策略层面的匿名（单接口仍可在发布配置覆盖） |
单条动态 API 是否在发布弹窗里设为「须鉴权 / 匿名」，见 数据模型-使用说明。
5. 自定义 API 对外接入
与动态 API 共用「启用运行时鉴权」总开关；此处额外控制自定义 API 的流量参数。
| 配置项 | 说明 |
|---|---|
| 对外接入 | 开启后，调用 /yc/custom-api/v1/... 须 Token |
| 生成接入密钥 | 得到 ycak_...（与动态 API 的 ycdk_ 不同体系，按页面提示） |
| Token 默认 / 最大有效期 | 默认 600 秒，最长 3600 秒 |
| 项目调用 QPS / 换 Token QPS | 限流保护 |
| IP 白名单 | 每行一个 IP 或 CIDR；留空不限制 |
控制台配置步骤与 env 模板见：自定义API-使用说明。
6. 网络与 IP 策略
| 配置项 | 说明 |
|---|---|
| 运行面强制 IP 校验 | 开启后，不在白名单的请求拒绝 |
| 信任代理头 | 网关后部署时，从 X-Forwarded-For 等取真实客户端 IP |
| 允许 IP 列表 | 业务后端出口公网 IP，每行一条 |
提示：开发环境本机调试用 127.0.0.1；生产填 BFF 服务器出口 IP。
7. 项目 ID 怎么用？
页面顶部 项目 ID 用于：
- 拼运行面 URL：
/yc/dynamic-api/v1/{projectId}/... - 业务
.env的YC_PROJECT_ID - 换 Token：
POST .../dynamic-api/v1/{projectId}/_auth/token
点击 复制 ID 发给后端同事。
8. 紧急收紧（什么时候用？）
场景：接入密钥疑似泄露、JWT 密钥配错导致全部 401、需要 temporarily 恢复业务。
效果：关闭 启用运行时鉴权，动态 API 与自定义 API 暂时不再校验凭证。
注意：
- 会降低安全性，仅应急。
- 处理完密钥/配置后，务必重新 开启鉴权 并保存。
- 不能替代「轮换密钥」——泄露后仍应生成新密钥。
9. 服务配置 vs 其它菜单
| 想做的事 | 去哪里 |
|---|---|
| 连哪个数据库 | 连接配置-使用说明 |
| 表结构、发布动态 API、单接口鉴权 | 数据模型-使用说明 |
| 项目级鉴权、IP、Token | 服务配置（本文） |
| 组合多接口 | API编排-使用说明 |
| 表格化查询、1:N 嵌套输出 | 自定义API-使用说明 |
10. 常见问题（FAQ）
10.1 开了鉴权，控制台试调 401？
动态 API 试调可勾选 跳过鉴权试调；或按校验方式填 Bearer / API Key。见动态 API 接入文档第 8 章。
10.2 动态 API 和自定义 API 用同一套密钥吗？
校验方式在项目级共用（服务配置）；
换 Token 路径：/dynamic-api/.../_auth/token 与 /custom-api/.../_auth/token 在统一鉴权下等效。
自定义 API 列表另有 接入与安全 弹窗，见自定义 API 使用说明。
10.3 只改了 JWT 密钥，要不要重启？
建议 重启 yc_user_service，并让用户重新登录拿新 JWT。
10.4 生产环境能否关鉴权？
不能长期关闭。仅本地调试或紧急收紧临时使用。
10.5 单接口想匿名，项目却开了鉴权？
在 数据模型 → 发布 → 接口配置 里将该接口 security 设为匿名（若产品已提供该选项）；否则 inherit 接口仍须凭证。
10.6 升级运行面引擎后，动态 API 行为没变？
修改了 yc_user_service（如 JSON 写入、create 时 null 视为未传）后须：
- 重新编译并重启 运行面（本地常见端口 8081）。
- 到 数据模型 对业务表 重新发布。
- 在控制台 试调 验证后再测业务 BFF。
未重启时，控制台与 BFF 仍会表现为旧引擎逻辑。
详见 数据模型 FAQ 10.11 · 动态 API FAQ 11.21。
10.7 JSON 列、create 传 null 等与鉴权有关吗？
无关。 属于数据模型字段类型与 create 写入语义，在 服务配置 只需保证 YC_PROJECT_ID、鉴权方式、接入密钥正确即可。
排错见 数据模型 FAQ 10.7～10.8 · 动态 API FAQ 11.18～11.19。
11. 推荐阅读顺序
- 本文
- 动态API-用户项目接入与鉴权说明
- sdk/使用文档（后端 SDK 环境变量）
修订记录
| 版本 | 日期 | 说明 |
|---|---|---|
| v1.0 | 2026-05-22 | 初版：服务配置控制台使用说明 |
| v1.1 | 2026-05-26 | FAQ 10.6～10.7：运行面升级重启、JSON/null 与鉴权区分 |