VeyraOS 部署指南
环境要求
- macOS (本机开发)
- Docker + Colima (k3s)
- kubectl
基础设施部署
bash
# 创建命名空间
kubectl apply -f deploy/k8s/namespace.yaml
# 部署基础设施 (PostgreSQL(pgvector) + MinIO + Neo4j)
kubectl apply -n veyraos -f deploy/k8s/infra/
# 创建 Secret
kubectl apply -n veyraos -f deploy/k8s/infra/secret.yaml知识库（RAG）依赖
知识库能力依赖 PostgreSQL（pgvector 扩展）、Neo4j（知识图谱存储）与 MinIO（文档原文托管），均包含在 deploy/k8s/infra/ 中。启用知识库需为 manager 注入 UA_KNOWLEDGE_ENABLED=true 及 Neo4j 连接环境变量（见 deploy/ci/deployment.yaml 中 knowledge 配置段）。
智能体 AI 生成（人设 / 头像）
智能体创建/编辑页支持 AI 生成人设（SOUL.md）与头像图片，属开发态能力，默认关闭。相关配置（见 deploy/ci/deployment.yaml 与 .env.local.example）：
| 环境变量 | 说明 |
|---|---|
UA_AI_PERSONA_ENABLED | 人设生成开关（默认 false）。默认走已部署的 LiteLLM 网关；配置 UA_AI_PERSONA_BASE_URL 后改为直连 OpenAI 兼容 chat API |
UA_AI_PERSONA_MODEL | 人设生成使用的模型：配了 UA_AI_PERSONA_BASE_URL 时为供应商模型名（如 Qwen/Qwen3.5-9B），否则为 LiteLLM 模型组名 |
UA_AI_PERSONA_BASE_URL | 人设生成直连 API 地址（OpenAI 兼容 /chat/completions，如 https://api.siliconflow.cn/v1）；留空则走 LiteLLM 网关 |
UA_AI_PERSONA_API_KEY | 人设生成直连 API Key（仅经环境变量 / k8s Secret 注入，不入仓） |
UA_AI_PERSONA_ENABLE_THINKING | 人设生成直连请求是否开启思考模式（默认 false 关闭）。硅基流动的 DeepSeek/Qwen 系默认思考会让正文首 token 前先完整推理（首 token 可达 25-29s）；关闭后首 token 显著下降（Qwen3.5-9B 实测 ~2-4s）。仅直连路径生效 |
UA_AI_AVATAR_ENABLED | 头像生成开关（默认 false） |
UA_AI_AVATAR_BASE_URL | 图像生成 API 地址（OpenAI 兼容 /images/generations） |
UA_AI_AVATAR_API_KEY | 图像生成 API Key（仅经环境变量 / k8s Secret 注入，不入仓） |
UA_AI_AVATAR_MODEL | 图像生成模型名 |
UA_AI_AVATAR_SIZE | 生成图片尺寸（默认 512x512） |
开关关闭时对应 API 返回 503，前端不显示「AI 生成」入口。生成的头像图片存入 MinIO public bucket（avatars/ai/），经 nginx /avatars/ 反代访问。
演示账号（一键演示）
面向产品演示/试用场景：管理台与终端门户的登录页均出现「一键演示」按钮，点击即免密进入一个已预填数据（演示用户组 + 智能体实例 + 知识库）的共享演示工作区。两端为各自独立的演示账号：管理台演示账号具备平台管理员权限（可浏览/操作演示组内全部资源），终端门户演示账号为终端用户（仅可使用演示组内智能体对话），两端共用同一演示用户组、仅能访问演示组内的数据。默认关闭。
| 环境变量 | 说明 |
|---|---|
UA_DEMO_ENABLED | 演示登录开关（默认 false）。关闭时登录接口返回 404、登录页不显示按钮 |
UA_DEMO_USERNAME | 共享演示账号用户名（默认 demo，管理台与终端门户各建一个同名账号；若已有同名真实用户，登录会拒绝并保持该用户不变） |
UA_DEMO_GROUP_NAME | 演示用户组名（默认 演示用户组） |
开启步骤：
- 为 manager 注入
UA_DEMO_ENABLED=true并重启（智能体定义会自动种入演示组）。 - 运行
scripts/seed-demo-workspace.py预置工作区（演示组/用户/资源池/知识库+样例文档解析/实例创建与部署，幂等可重跑；知识库解析为 LLM 慢操作，全程约 30 分钟）。 - 演示产生的会话/操作脏数据积累后，运行
scripts/reset-demo-workspace.py重置运行态（清实例与聊天数据，保留定义/知识库等静态资产；--with-instances重置后立即重建）。
命令沙箱（OpenSandbox）
智能体实例启用「命令沙箱」时，终端命令在独立的 OpenSandbox 沙箱中执行（与引擎运行环境隔离，每位用户独立沙箱、空闲自动回收）。沙箱服务已包含在一键部署链路中（deploy/ci/deploy.sh 自动部署并注入 API key），手动部署方式：
bash
# 部署 OpenSandbox server + controller（含 CRD、数据面 ns opensandbox）
# 生产必须先把清单内 api-key 占位值替换为随机串（与 veyraos-secret 的 opensandbox-api-key 同值）
kubectl apply -f deploy/k8s/infra/opensandbox.yaml
# 验证
kubectl -n opensandbox-system get deploy,pod要点：
- API Key 两端同值：
opensandbox-system/opensandbox-api-key（server 校验）与veyraos/veyraos-secret的opensandbox-api-key（引擎 Pod 经 secretKeyRef 透传）必须一致。一键部署由deploy.sh用同一变量（.env.local的OPENSANDBOX_API_KEY，留空则复用集群已有值/首次自动生成）注入两端；换值后自动滚动重启引擎 Pod 与 opensandbox-server（两端都只在 Pod 启动时解析 secret，任一端不重启都会导致沙箱创建 401）。 - manager 通过
OPENSANDBOX_SERVER_URL（默认http://opensandbox-server.opensandbox-system.svc.cluster.local）注入引擎 Pod，无需额外配置。 - 沙箱镜像来自阿里云公开镜像仓（
sandbox-registry.cn-zhangjiakou.cr.aliyuncs.com/opensandbox/），无需拉取凭据。 - 不启用命令沙箱的实例不受此组件影响（不注入相关 env，terminal 命令仍走引擎本地执行）。
容量估算
沙箱是独立 K8s Pod，按「实例并发用户数 × 实例配置的沙箱内存」估算数据面节点容量；节点 CPU requests 紧张时沙箱会 Pending，表现为终端命令长时间无响应。
服务部署
bash
# 构建 Manager 镜像
docker build -t veyraos/manager:latest -f services/manager/Dockerfile .
# 载入 k3s
docker save veyraos/manager:latest | colima ssh -- sudo ctr -n k8s.io images import -
# 部署所有服务
kubectl apply -n veyraos -f deploy/k8s/services/
# 初始化数据库种子数据
kubectl exec -n veyraos deployment/manager -- python /app/scripts/seed.py引擎部署
bash
# 构建引擎镜像 (基于 gateway 基础镜像)
docker build --no-cache -t veyraos/engine-hermes:latest -f engines/hermes/Dockerfile .
docker save veyraos/engine-hermes:latest | colima ssh -- sudo ctr -n k8s.io images import -
# 创建 DeepSeek API Key Secret
kubectl create secret generic -n veyraos deepseek-key \
--from-literal=deepseek-api-key=sk-your-key-here
# 部署引擎 (示例: engine-hermes-test)
kubectl apply -n veyraos -f deploy/k8s/engines/hermes-template.yaml
# (需替换模板中的 AGENT_ID 占位符)端用户门户部署
bash
# 构建镜像（apps/enduser/Dockerfile）
docker build -t veyraos/enduser-portal:latest -f apps/enduser/Dockerfile apps/enduser/
kubectl rollout restart -n veyraos deploy/enduser-portal产品主页（Landing）部署
bash
# 构建镜像（apps/landing/Dockerfile）
docker build -t veyraos/console-landing:latest -f apps/landing/Dockerfile .
docker save veyraos/console-landing:latest | colima ssh -- sudo ctr -n k8s.io images import -
# 部署到 k3s（NodePort 30082）
kubectl apply -n veyraos -f deploy/k8s/apps/landing.yaml云上裸域名 ingress + TLS 部署：运维需先创建 landing-secret（与 admin-secret / chat-secret 同模式）：
kubectl create secret tls landing-secret --cert=/path/to/fullchain.pem --key=/path/to/privkey.pem -n veyraos之后执行 bash deploy/ci/deploy.sh <版本号> 会自动 apply landing-ingress.yaml + deployment.yaml 中的 console-landing block。
端口转发 (本地开发)
bash
kubectl port-forward -n veyraos svc/manager 8002:8002 # Manager API
kubectl port-forward -n veyraos svc/gateway 8010:8010 # Gateway
kubectl port-forward -n veyraos svc/enduser-portal 3000:80 # 终端门户验证端到端流程
bash
# 1. 登录获取 Token
curl -s http://localhost:8000/api/auth/login \
-H 'Content-Type: application/json' \
-d '{"username":"admin","password":"admin123"}'
# 2. 创建并发布 Agent
TOKEN=<access_token>
curl -s -X POST http://localhost:8000/api/agents \
-H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' \
-d '{"name":"助手","engine_type":"HERMES"}'
curl -s -X POST http://localhost:8000/api/agents/<id>/publish \
-H "Authorization: Bearer $TOKEN"
# 3. 测试 Gateway 透传 (非流式)
curl -s -X POST http://localhost:8010/v1/chat/completions \
-H "Authorization: Bearer <engine_api_key>" \
-H "Content-Type: application/json" \
-d '{"model":"agent-test","messages":[{"role":"user","content":"你好"}]}'
# 4. 打开浏览器访问端用户门户
open http://localhost:3000镜像构建顺序 (依赖链)
veyraos/gateway:latest
└── veyraos/engine-hermes:latest (FROM gateway)
veyraos/manager:latest清理
bash
# 删除命名空间下的所有资源
kubectl delete namespace veyraos