私有化部署指南

VeyraOS 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），均配 TLS 证书
- 无域名内网环境：使用 NodePort 方式接入（见下）
统一账号组件：VeyraOS 账号与计费组件为必装前置——Router 的登录、组织与计费依赖它；随整套交付介质一起提供，安装器会自动处理安装顺序
安装介质：router-component-<版本>.tar.gz 离线档案（含全部容器镜像与部署清单），全程无需访问外部网络

安装

1. 校验介质

sha256sum -c checksums.sha256

校验不通过说明介质损坏或被篡改，请重新获取，不要继续安装。

2. 运行安装向导

在档案解压目录启动安装器，按提示回答四组问题：

域名与证书：数据面/控制台域名，及对应的 TLS 证书（以 kubernetes.io/tls 类型 Secret 预先建好）
存储类：持久化卷使用的 StorageClass
模式：slim（推荐起步）或 full
入口：域名接入（默认）或 NodePort（无域名内网）

安装完成后安装器会回显一次控制台管理员初始口令，并提示导出密钥冷备文件——两者都请立即妥善保存（口令不再显示；冷备文件的意义见备份与恢复）。

3. 模式对照

能力	slim（推荐起步）	full
模型调用 / 路由 / 计费	完整可用	完整可用
用量与账单明细	完整可用（数据库侧完整记录）	完整可用
实时看板	不可用（页面提示维护中，属正常现象）	可用
智能路由决策	基础规则	追加决策模型服务
资源占用	低	高（决策服务约 2Gi 内存）

slim → full 后期切换：重跑安装向导选 full 即可——安装器增量安装缺的组件并滚动重启，已有数据与配置不动，不需要卸载重装。

4. 无域名环境（NodePort）

不配置域名时，通过节点 IP + 端口接入（无 TLS，适用于可信内网）：

入口	地址
数据面 API	`http://<任意节点IP>:31115`
控制台	`http://<任意节点IP>:31116`

备份与恢复

每日逻辑备份（推荐）：pg_dump 导出三个库（router / account / 网关），恢复时 psql 导入目标库即可搬移：
sh
```
kubectl -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 模式不可用（计费明细不受影响）

私有化部署指南 ​

部署形态概览 ​

前置要求 ​

安装 ​

1. 校验介质 ​

2. 运行安装向导 ​

3. 模式对照 ​

4. 无域名环境（NodePort） ​

备份与恢复 ​

升级 ​

故障排查 ​

与公有云版的差异（调用方视角） ​