VeyraOS — 功能概述
企业级多智能体平台。版本基线：1.0.0。
已实现功能
1. 多租户与作用域 RBAC 权限系统
- 账号中心的组织 1:1 投影为平台租户；租户内分「组织空间 / 部门空间 / 个人空间」，管理台顶栏提供工作空间切换器
- 用户-角色-权限 三层模型（多对多关系）
- 预置角色：平台员工（账号中心 scope 投影）、租户管理员、部门管理员、开发者、只读成员；支持租户自定义角色
- 作用域绑定：租户 / 部门两级，生效权限按「平台 scope → 租户管理员 → 部门管理员 → 角色绑定 → 默认角色」并集解析
- JWT 双 Token 认证（access 30min + refresh 90d）
- 首个管理员账号由安装引导创建；存量环境经种子脚本创建，口令通过
SEED_ADMIN_PASSWORD环境变量设定（未设置时随机生成并在日志中打印一次），首登后请立即修改
2. SSO 统一认证
- 管理台无独立登录页：未登录自动跳账号中心授权页（OIDC 授权码 + PKCE），回跳
/sso/callback后建本地会话 - 首次登录自动建档（JIT）并完成租户/角色投影
- 统一登出：后通道（backchannel）一次退出所有接入服务，本地令牌随会话撤销水位失效
3. 智能体管理 (Manager API)
- 定义/版本/实例三层模型：定义 CRUD、发布生成不可变版本快照（可回滚）、实例化运行
- 三种创建方式：AI 助建（对话式生成人设与配置）、从模板创建、自定义创建
- 智能体工作台 7 个页签：概览 / 构建 / 调试 / 版本 / 渠道 / 部署 / 分析
- 定时任务：按 cron 周期驱动智能体自动执行
- 引擎类型：Hermes / DeepSeek / Dify（外接，平台不部署其组件）
- 实例状态流转：DRAFT → PUBLISHED → OFFLINE；运行时生命周期 deploy / suspend / resume / restart / destroy
- 访问范围控制：ALL / USER / USER_GROUP
- 终端用户可用智能体列表 (
GET /api/manager/agent-instances/accessible)
4. 终端用户门户 (Enduser Portal)
- 技术栈：Vue 3 + TypeScript + Vite + Tailwind CSS + Pinia
- 页面：登录（
/login）、智能体落地解析（/agents）、对话页（/agents/:id） - 聊天组件：直接渲染 Vue 3 组件（无 iframe）；对话体验（流式渲染、执行轨迹、思考卡片）由共享实现承载，与管理台调试面板等行为一致
- 对话流程：
- 用户选择智能体 → 检测引擎部署状态
- 未部署 → 创建 K8s Pod + SSE 进度推送 → 就绪
- 已休眠 → 恢复 (scale=1)
- 就绪 → 进入 Chat 页面
- 发送消息 → Gateway → engine Pod → SSE 流式回复
- 会话管理：会话由引擎自身管理（不入平台数据库），门户经 Gateway 的
/v1/sessions系列接口访问 - 消息反馈：支持对回复点踩并填写反馈原因
- 白牌：登录页品牌区、页脚版权与备案号、浏览器标题与图标按管理台「产品设置」在线定制
- Gateway 通信：
/api/gateway/同域代理，X-Agent-ID头路由
5. 智能体生命周期 (Manager worker，原 Controller 职责)
- K8s 引擎管理：通过 kubernetes Python client 创建/管理 Pod
- 命名规范：
engine-hermes-{agent_id[:8]}（Gateway DNS 路由依据）
- 命名规范：
- 部署状态：PENDING → DEPLOYING → RUNNING → SUSPENDED → ARCHIVED
- SSE 部署进度：实时推送创建 Pod → 等待就绪 → 完成
- 数据存档：SUSPEND 时 exec tar 引擎数据 → MinIO 备份
- 空闲回收：30min 空闲 → 存档+休眠 (scale=0)；24h 空闲 → 清理 K8s 资源
- 部署失败归因：失败原因按受众分级（管理侧详细原因 + 解决方案，终端侧通俗文案）
6. 引擎容器化（Hermes / DeepSeek）
- 引擎以容器化方式运行于 k3s Pod，通过原生 HTTP API 调用，不侵入式修改源码
- 引擎镜像独立语义化版本（
<上游版本>-veyra.<修订号>），唯一真相在各engines/<name>/VERSION文件 - 支持流式 (SSE) 和非流式响应
- Gateway 模式：去掉透传的 Origin/Referer 头
- Dify 仅外接模式：登记用户自管平台地址与应用密钥，无 Pod、不占资源池
7. Gateway 动态路由
- DNS 命名规范路由：
engine-hermes-{agent_id[:8]}.veyraos.svc.cluster.local:8642 - 从
X-Agent-ID请求头提取 agent_id，无需调用外部服务 - SSE 流式透传（统一 VES 事件流 / OpenAI chunk 流两个出口）
- 503 引擎不可用处理
- 无反向依赖（Gateway 不查询其他服务获取 upstream）
8. k3s 基础设施
- PostgreSQL 16 (StatefulSet + PVC)
- MinIO 对象存储 (StatefulSet + PVC)
- Neo4j（知识库图谱存储，可选启用）
- 平台服务 RBAC：ServiceAccount + Role + RoleBinding
- 所有服务 ClusterIP 内网通信
imagePullPolicy: IfNotPresent（本地镜像优先）
端口规划
| 分组 | 服务 | K8s 端口 | 本地开发 |
|---|---|---|---|
| 基础设施 | PostgreSQL | 5432 | 5432 |
| MinIO API | 9000 | 9000 | |
| 引擎 | Hermes Engine | 8642 | — |
| DeepSeek Engine | 8649 | — | |
| 后端 | Manager（含原 controller worker） | 8002 | 8002 |
| Gateway | 8010 | 8010 | |
| Hub（资产中心） | 8003 | 8003 | |
| Skill Engine（技能开发） | 8004 | 8004 | |
| 前端 | Admin (Vite) | — | 8848 |
| Enduser Portal (Vite) | — | 3000 |
数据库模型
| 模型 | 表名 | 说明 |
|---|---|---|
| User | users | 管理员账号（登录管理台，参与 RBAC） |
| EndUser | end_users | 终端用户账号（登录终端门户，不走 RBAC） |
| Role | roles | 角色 |
| Permission | permissions | 权限 |
| Tenant | tenants | 租户（账号中心组织投影） |
| UserGroup | user_groups | 租户内资源空间（根组 / 部门组） |
| AgentDefinition | agent_definitions | 智能体定义 |
| AgentVersion | agent_versions | 不可变版本快照 |
| AgentInstance | agent_instances | 智能体实例 |
| AgentDeployment | agent_deployments | 部署状态 |
架构约束
Gateway 反向依赖
- Gateway 不允许查询其他服务获取 upstream
- 路由信息通过请求头
X-Agent-ID+ DNS 命名规范传递 - 引擎 Pod 命名规范是编排层和 Gateway 之间的约定契约
开源软件修改策略
- 不对开源软件做侵入式修改
- hermes-webui 仅作为参考实现，终端用户前端为自研 Vue 3 应用
数据存档策略
- 存档时机提前到 SUSPEND（30min），不在 DESTROY 时
- 不加定期轮询备份（避免大规模下的资源消耗）
- PVC 实时写（引擎自身行为，零开销）
- SUSPEND 存档 → DESTROY 仅清理 K8s 资源