私有化部署指南
Veyra Router 可完整部署在贵方自己的 Kubernetes 集群上：模型凭据、调用记录与账单数据全部落在贵方环境内，不经任何外部服务中转。本页面向负责部署与日常运维的工程师；应用接入方式与公有云版完全一致，见快速开始。
部署形态概览
| 组件 | 说明 |
|---|---|
| 数据面网关 | 对外模型 API（三种协议），路由与转发 |
| 公开产品门户 | 产品介绍与快速接入，未登录可浏览 |
| 控制台 | 运营/调用方 Web 控制台，密钥、用量与账单需要登录 |
| 公开文档 | 产品使用、协议与部署文档，未登录可浏览 |
| 数据库 | PostgreSQL——模型、组织、计费明细的唯一持久层 |
| 缓存 | Redis（开启持久化） |
以上为 slim 模式全集。full 模式追加：
| 组件 | 说明 |
|---|---|
| 事件回流 | 消息队列 + 分析库，驱动实时看板 |
| 决策服务 | 路由决策模型服务（单实例内存约 2Gi） |
前置要求
- Kubernetes 集群：1.24 及以上；有默认 StorageClass，或可在安装时指定存储类（数据库与缓存需要持久化卷）
- 资源：起步建议 slim 模式 ≥ 4 核 / 8G 内存；full 模式 ≥ 8 核 / 16G 内存（含数据库与缓存）
- 网络（二选一）：
- 三个域名：数据面 API（如
api.example.com）、控制台（如console.example.com）与公开产品门户（如router-portal.example.com），均配 TLS 证书；泛域名证书可覆盖同级域名 - 无域名内网环境：使用 NodePort 方式接入（见下）
- 三个域名：数据面 API（如
- 统一账号组件：VeyraOS 账号组件为必装前置——Router 的登录与组织管理依赖它；随整套交付介质一起提供，安装器会自动处理安装顺序
- 安装介质：
router-component-<版本>.tar.gz离线档案（含全部容器镜像与部署清单），全程无需访问外部网络
安装
1. 校验介质
sha256sum -c checksums.sha256校验不通过说明介质损坏或被篡改，请重新获取，不要继续安装。
2. 运行安装向导
在档案解压目录启动安装器，完成访问方式、入口地址、TLS 与存储等配置。选择域名访问时，基域用于派生数据面、控制台和公开门户三个入口；上传的 TLS 证书需要覆盖这些域名。
安装完成后安装器会回显一次控制台管理员初始口令，并提示导出密钥冷备文件——两者都请立即妥善保存（口令不再显示；冷备文件的意义见备份与恢复）。
3. 模式对照
| 能力 | slim（推荐起步） | full |
|---|---|---|
| 模型调用 / 路由 | 完整可用 | 完整可用 |
| 用量与成本明细 | 完整可用（数据库侧完整记录） | 完整可用 |
| 实时看板 | 不可用（页面提示维护中，属正常现象） | 可用 |
| 智能路由决策 | 基础规则 | 追加决策模型服务 |
| 资源占用 | 低 | 高（决策服务约 2Gi 内存） |
slim → full 后期切换：重跑安装向导选 full 即可——安装器增量安装缺的组件并滚动重启，已有数据与配置不动，不需要卸载重装。
4. 无域名环境（NodePort）
不配置域名时，通过节点 IP + 端口接入（无 TLS，适用于可信内网）：
| 入口 | 地址 |
|---|---|
| 公开产品门户 | http://<任意节点IP>:31117/ |
| 控制台 | http://<任意节点IP>:31116/ |
| 公开文档 | http://<任意节点IP>:31116/docs/ |
| 数据面 API | http://<任意节点IP>:31115 |
数据面支持 OpenAI Chat Completions（/v1/chat/completions）、Responses （/v1/responses）与 Anthropic Messages（/v1/messages）协议。 Claude Code 等以 /anthropic 为 Base URL 的客户端在 NodePort 直连时使用 http://<任意节点IP>:31115/anthropic，同样可用；不需要经过域名入口。
公开门户顶部导航提供「进入控制台」与「登录」两个入口（内网 HTTP 环境同样支持）： 「登录」走控制台 SSO，登录完成后回跳你点击时所在的那一页；未登录也可以直接阅读 门户与公开文档，只有控制台、密钥、用量与账单等账号相关内容需要登录。
5. 域名环境
配置域名时，公开产品门户使用独立的 router-portal.<基域>；控制台与文档保持原入口：
| 入口 | 地址 | 访问要求 |
|---|---|---|
| 公开产品门户 | https://router-portal.<基域>/ | 无需登录 |
| 控制台 | https://console.<基域>/ | 需要登录 |
| 公开文档 | https://console.<基域>/docs/ | 无需登录 |
| 数据面 API | https://api.<基域>/v1 | 应用使用 API Key 调用 |
门户只提供产品介绍和公开资料入口，不包含注册、供应商管理或运营信息。 仅安装 Router 时保持单产品页面；如果安装器同时配置了本环境的 VeyraOS 平台门户， 顶部「产品」菜单与页脚会显示平台入口。该链接使用你环境中的域名或 IP/端口，不会跳往公有云。
备份与恢复
每日逻辑备份（推荐）：
pg_dump导出三个库（router / account / 网关），恢复时psql导入目标库即可搬移：shkubectl -n veyraos exec postgres-0 -- sh -c \ 'pg_dump -U "$POSTGRES_USER" router' > router-$(date +%F).sql存储卷快照（粗粒度兜底）：对数据库与缓存的持久化卷做整卷快照
密钥冷备（不可跳过）：安装结束导出的冷备文件包含控制台会话密钥与供应商凭据加密盐。这两个密钥丢失后无法补办——后果与处置见故障排查。请将冷备文件保存在集群之外的离线介质上，至少两份
升级
- 先做当日备份（
pg_dump，见上） - 获取新版本档案并校验（
sha256sum -c checksums.sha256） - 运行安装器的升级命令：安装器检测已装版本，滚动替换组件，数据卷与配置不动
- 验证：打开控制台登录页看右下角版本角标，或访问数据面
GET /health看version字段，确认已是目标版本
报障时请一并提供该版本号（角标或 /health 均可），它能唯一定位对应的软件版本。
故障排查
| 现象 | 原因 | 处置 |
|---|---|---|
| 登录跳转到账号页后回跳失败或提示会话无效 | 配置的账号域名与浏览器实际访问的域名不一致——比对必须逐字节一致：https:// 前缀、大小写、有无结尾斜杠 | 修正域名配置后重跑安装向导 |
| 数据库反复重启或组件报连接失败 | 自行提供的数据库口令含 URL 特殊字符（@ : / # 等），拼接连接串时被截断 | 换用不含特殊字符的口令 |
| 恢复备份（或重装）后全部供应商凭据失效、所有人被登出 | 会话密钥 / 供应商凭据加密盐丢失——不可逆，无技术回滚手段 | 在控制台重新录入各供应商凭据；用户重新登录。唯一预防是冷备文件离线双保存 |
| 实时看板打不开或显示维护中 | slim 模式未安装事件回流组件，属预期行为 | 用量与成本明细不受影响（数据库侧完整）；需要看板时切换 full 模式 |
与公有云版的差异（调用方视角）
| 维度 | 公有云版 | 私有化版 |
|---|---|---|
| 接入协议与鉴权 | 三种协议 + API Key | 完全一致，代码无需改动 |
| API Keys 管理 | 控制台自助 | 完全一致 |
| 模型供应商 | 平台托管接入 | 贵方在控制台「模型与供应商」自行录入凭据与成本价 |
| 模型售价与计费 | 按售价计费（未配价模型不可调用） | 无售价概念：模型注册即可调用，「用量与成本」页按供应商成本价统计开销 |
| 余额与欠费拦截 | 有余额卡、欠费暂停调用 | 无（买断制交付，不涉及） |
| 版本节奏 | 平台统一升级 | 自主控制（见升级） |
| 数据存储 | 平台侧 | 贵方集群内数据库 |
| 实时看板 | 可用 | slim 模式不可用（用量与成本明细不受影响） |