部署与许可
双部署模式部署指南（私有化 / SaaS·VM 级逻辑隔离）、部署与健康状态确认、许可有效期与失效开关、升级与回滚约定
灵渠平台以单一系统、双控制台形态交付：同一套数据底座与运行内核，向客户 Portal 与运营控制台两类读者各自呈现。无论以何种模式部署，平台对外暴露的接口、控制台形态与计量口径完全一致——部署模式只决定平台运行在哪里、以何种方式与其他租户隔离。
本节面向负责平台落地与日常运维的内部管理员，说明两种部署模式的差异与选型、如何确认部署与许可状态、许可的有效期与失效行为，以及版本升级与回滚的约定。
1. 双部署模式
平台支持两种部署模式，二者功能完全一致，仅运行位置与隔离方式不同。选型应依据客户对数据驻留、运维归属与隔离强度的要求。
| 对比项 | 私有化部署 | SaaS 部署 |
|---|---|---|
| 运行位置 | 客户自有控制环境（客户自管数据中心 / 客户云账号 / 客户专有网络内） | 供应方托管环境 |
| 隔离方式 | 实例独占（物理 / 网络层面与外部完全隔离） | VM 级逻辑隔离（每客户独立虚拟机实例，租户间不共享运行进程与存储卷） |
| 数据驻留 | 全部数据驻留客户控制环境，不出客户边界 | 数据驻留供应方托管环境，按数据安全策略约束（见 数据安全） |
| 运维归属 | 客户侧运维为主，供应方提供支持 | 供应方托管运维 |
| 网络入口 | 由客户在其网络内规划统一入口地址 | 由供应方分配实例统一入口地址 |
| 升级节奏 | 客户确认窗口后由客户侧执行 | 供应方按维护窗口统一推进 |
SaaS 模式下的「VM 级逻辑隔离」指为每个客户分配独立的虚拟机实例承载其平台，租户之间不共享运行进程、缓存与存储卷；这与多租户共进程的「软隔离」不同，是平台 SaaS 形态的隔离基线。两种模式下，路由小模型、中间件编排脚本、策略配置等客户权属物的归属与隔离口径一致（见 路由小模型微调 与 数据安全）。
部署模式在平台初始化时确定，运行期不在控制台内切换。如需从一种模式迁移到另一种，按迁移流程重新部署并迁移配置与客户权属物，而非在线变更。
2. 部署与健康状态确认
平台部署完成后，运营控制台「部署与许可」页给出平台整体的部署状态与许可状态。可调用部署与许可状态接口一次取回：
curl https://your-platform/api/v1/deployment \
-H "Cookie: <控制台会话凭证>"响应给出部署模式、部署可用性二值与许可状态：
{
"deploy_mode": "private",
"deploy_status": "ready",
"license": {
"valid_from": "<许可生效日>",
"valid_until": "<许可失效日>",
"kill_switch": false
}
}字段含义：
| 字段 | 含义 |
|---|---|
deploy_mode | 部署模式：private（私有化于客户控制环境）/ saas（供应方托管·VM 级逻辑隔离） |
deploy_status | 部署可用性，二值：ready（已部署·正常可用）/ unavailable（不可用） |
license.valid_from / valid_until | 许可有效期起止日 |
license.kill_switch | 许可失效开关；置位后平台停止受理新的查询请求 |
本端点只反映平台整体是否已部署且正常可用的二值状态与许可状态，不承载逐项运行指标。月度可用率、故障响应时延等运行速率指标归 上游 SLA 监控（成本侧 SLA 报表），不在本端点返回。
deploy_status与kill_switch共同决定数据平面/v1/*是否对外受理请求：仅当deploy_status为ready且kill_switch为false时，平台才正常受理新查询。
部署后建议按以下顺序做一次落地自检：
- 调用
GET /api/v1/deployment，确认deploy_status为ready、kill_switch为false、许可在有效期内； - 登录运营控制台，确认两套导航树（客户 Portal / 运营控制台）均可进入；
- 接入首个上游并做连通性探测，确认有可路由的目标（见 多上游模型接入）；
- 按 快速开始 跑通一次端到端查询请求，确认请求在控制台落账。
3. 许可模型
平台运行受许可约束。许可决定平台在何时间段内可受理查询，以及失效后的对外行为。
3.1 许可有效期
每份许可带有效期起止日（valid_from / valid_until）。在有效期内，平台正常受理数据平面查询与控制平面管理操作；超过 valid_until 后，平台进入到期行为（见 3.3）。许可有效期与服务协议约定的服务期对应，具体起止日以服务协议与控制台「部署与许可」页显示为准，不在本文档写定。
3.2 失效开关（kill switch）
许可内含失效开关 kill_switch。这是一个独立于有效期的对外受理总闸：
kill_switch为false：平台正常受理查询（仍需在有效期内）；kill_switch为true：平台立即停止受理新的查询请求，数据平面/v1/*对新请求返回许可不可用的结构化错误，控制平面只读管理接口仍可用于查看历史用量与对账数据。
失效开关一旦置位，已在途的请求按既有逻辑收尾，新请求一律不再受理。置位与复位由部署方按服务协议执行，不在客户控制台内自助切换。遇到
kill_switch为true时，请先联系部署方核对许可与服务期状态，再恢复受理。
3.3 到期行为
许可到期（超过 valid_until）或失效开关置位时，平台的对外行为如下：
| 状态 | 数据平面 /v1/* | 控制平面 /api/v1/*（只读） | 控制平面（写操作） |
|---|---|---|---|
| 有效期内、开关未置位 | 正常受理 | 可用 | 可用 |
| 已到期 | 停止受理新请求 | 可用（查看历史用量、账单、对账） | 受限 |
| 失效开关置位 | 停止受理新请求 | 可用（查看历史用量、账单、对账） | 受限 |
平台在许可到期或失效后仍保留历史数据的只读访问，便于在恢复前完成用量核对与账单结算。历史用量明细、结算单、对账数据不因许可到期而清除——其留存与退出导出口径见 数据安全。许可可用性同时关联服务计费安排：达成服务协议约定的年度用量承诺后，当年度平台服务费按协议减免，具体承诺口径、减免规则与费率以服务协议与运营控制台「供应商对账」页为准，本文档不写定数额。
4. 升级与回滚
平台按版本发布。升级在不改变接口契约的前提下迭代平台内核与控制台，回滚用于在升级出现异常时退回上一个稳定版本。
4.1 升级约定
| 约定项 | 说明 |
|---|---|
| 接口兼容 | 控制平面在同一大版本（/api/v1）内保持向后兼容；不兼容变更升 /api/v2，旧前缀按公告期并行保留。数据平面保持 OpenAI 兼容形态不变 |
| 升级窗口 | 私有化模式由客户在确认窗口后执行；SaaS 模式由供应方按维护窗口统一推进。升级窗口内数据平面可能短暂只读或暂停受理 |
| 配置与权属物 | 升级不影响中间件编排、上游接入配置、API 密钥、路由小模型等客户配置与权属物，升级前后保持一致 |
| 升级前核对 | 升级前建议导出一次当前编排与策略配置（见 数据安全 的退出导出清单），作为回滚基线 |
升级完成后，按第 2 节的落地自检顺序复核一次部署与健康状态，确认 deploy_status 为 ready 且查询可正常受理。
4.2 回滚约定
升级后若出现部署不可用或查询受理异常，可回滚至上一个稳定版本：
- 回滚以部署可用、查询正常受理为目标，回滚后
deploy_status应恢复为ready； - 回滚保留升级前的中间件编排、上游接入与 API 密钥配置——配置与版本相互独立，回滚版本不丢配置；
- 历史用量明细与结算数据不受回滚影响，回滚前后逐条记录连续、可对账（计量口径版本号随记录留存，见 API 参考）；
- 回滚完成后同样按第 2 节自检顺序复核部署与健康状态。
升级与回滚均不改变已发生查询的计量结果与计费口径。每条历史调用记录携带其发生时的计量口径版本号，升级或回滚不会重写历史记录，确保跨版本的用量与账单仍然对得上。