forked from xhgit/webup-cloud
79 lines
10 KiB
Markdown
79 lines
10 KiB
Markdown
# 模型、钱包与隔离开发
|
||
|
||
本模块新增可执行代码,不代表全部商业需求已完成。真实供应商调用与 Kubernetes 工作区需要运营者配置凭证和集群,当前只完成本地自动化测试,不能将协议 Mock 或资源配置测试当成真实联调。
|
||
|
||
## 执行就绪与调度
|
||
|
||
仅启动前端和 API 不会执行 AI 任务。独立 Worker 每五秒向数据库登记实际网关 / Kubernetes 健康检查结果;四十五秒没有有效心跳视为离线。页面展示当前状态,离线时不创建新预算预留、不恢复任务、不收取新的优先费,已有任务仍可取消并释放未使用预留。
|
||
|
||
全局并发、人工调序、管理员指定下一位和钱包购买优先权已接入真实队列,详见 [队列规则、退费与接入](QUEUE.md)。单个 Worker 可使用受容量限制的虚拟线程同时开发多个项目,全局领取由数据库单例行锁协调。预览默认不启用 Worker,必须接入真实隔离网关后才能实际执行。
|
||
|
||
## 模型协议
|
||
|
||
支持 OpenAI Chat Completions 兼容协议、Anthropic Messages、Gemini generateContent。DeepSeek、智谱、百炼与中转站可按其实际兼容接口配置 OpenAI 类型;不能假设所有兼容服务完整支持 tools 或 usage。
|
||
|
||
协议依据:[OpenAI Chat Completions](https://developers.openai.com/api/reference/resources/chat/subresources/completions/methods/create)、[Anthropic 工具调用](https://platform.claude.com/docs/en/agents-and-tools/tool-use/how-tool-use-works)、[Gemini generateContent](https://ai.google.dev/api/generate-content)。Gemini 的原始 parts(包括 thoughtSignature)、Anthropic 原始内容块会保存在任务消息中,以便继续工具调用。
|
||
|
||
后台先添加供应商,再添加模型和每百万 Token 的人民币价格。供应商 Base URL 应包含协议版本,例如 `https://api.openai.com/v1`、`https://api.anthropic.com/v1`、`https://generativelanguage.googleapis.com/v1beta`。官方预设包含 MiMo / DeepSeek / Kimi 等国内供应商;自定义 HTTPS 中转默认允许管理员配置,并在连接时拒绝私网 / 元数据 DNS 地址。可以将 `app.allow-custom-providers` 设为 false,只接受官方预设和 `ALLOWED_PROVIDER_HOSTS` 精确允许列表。
|
||
|
||
API Key 通过 AES-256-GCM 加密,随机 12 字节 nonce 和认证附加数据;完整密钥不回传客户端、不写入审计。`APP_ENCRYPTION_KEY` 是 Base64 编码的 32 字节随机值,必须独立保管和备份。当前密钥格式为 v1;更换主密钥前需实现 / 执行重加密迁移,直接替换会导致旧凭证无法解密。供应商 API Key 则可通过编辑界面直接轮换。
|
||
|
||
HTTP 客户端禁用重定向和自动重试;实际 DNS 解析连接时拒绝本地、私有、链路本地、组播、CGNAT 等地址,避免只做一次字符串检查。超时 / HTTP 错误只公开脱敏原因,不返回上游响应正文。
|
||
|
||
连接测试调用真实 `/models`,只验证该接口可连接,不证明某个模型的工具能力。当前工具支持由管理员依据实际模型能力声明;自动能力探测、视觉附件上传和流式 Token 输出尚未实现。遇到不支持工具的模型不能宣称已执行开发。
|
||
|
||
## 钱包与预算
|
||
|
||
钱包独立于 users 表,使用 NUMERIC(24,8)。账本记录每次实际余额变化,具有用户内唯一幂等键、业务关联和变动后余额。
|
||
|
||
管理员增加 / 扣除余额需要 `finance:write`、原因与幂等标识;操作与审计使用同一事务。同一标识重复请求返回原记录,金额或原因不同则拒绝。扣除不能动用已预留资金。余额调整不是在线支付充值;支付渠道尚未实现。
|
||
|
||
任务创建时在事务中预留预算;每轮使用任务绑定的不可变价格版本计算实际消费。普通输入、缓存读取、缓存写入和输出分别计费,避免缓存输入重复计算。任务正常完成或取消时释放未使用部分,暂停时继续预留。模型当前价格使用明确的版本指针,不依赖并发事务时间排序。
|
||
|
||
执行前按模型上下文上限和输出上限计算保守的单次费用边界。剩余预算不足时暂停,不先调用再透支。缺少 usage 时不使用隐藏估算策略,转为 REVIEW_REQUIRED。当前未提供预算追加接口;预算不足需取消后重新设置预算发起任务。
|
||
|
||
## 任务与恢复
|
||
|
||
数据库任务状态:QUEUED、RUNNING、PAUSED、COMPLETED、CANCELLED、FAILED、REVIEW_REQUIRED。每个项目只允许一个活动任务,避免并发编辑同一工作区。用户每次提交需幂等标识。
|
||
|
||
Worker 以条件更新原子领取任务,持有 300 秒租约;调用模型前与每个工具操作前续租。租约过期不自动重放不确定请求。网络超时、工具结果未知和缺少 usage 会保留剩余预算并转为人工核对。财务管理员核对上游账单和工作区后可补充结算并释放预留,操作单独记录,不伪装为精确 Token 结算。
|
||
|
||
任务按预算执行,没有固定轮次上限。每轮最多 8 个工具,终端命令最长 120 秒。历史接近模型窗口时,Worker 保存交接摘要,在同一任务内开启下一段模型对话。新对话带上项目要求、本轮用户需求和历史进度摘要,继续使用原工作区及预算。摘要从已有消息和工具结果提取,无需单独调用模型。原始消息和日志仍可查询,已执行的工具不会重放。旧版因轮次或上下文上限暂停的任务可以直接继续。
|
||
|
||
Agent 按检查相关文件、小步修改和验证的顺序推进。压缩交接保留工具路径和命令退出状态,省略已读取的完整文件内容,便于下一段从最近的进展继续。此流程参考了 [Anthropic 对长任务 Agent 的公开设计](https://www.anthropic.com/research/effective-harnesses-for-long-running-agents)。
|
||
|
||
供应商明确拒绝过长输入且未返回 usage 时,可在仍有旧历史的情况下压缩后重试。超时等无法确定计费状态的错误走核算流程。供应商的实际上下文和输出限制仍适用。后续任务复制最近完成任务的消息,项目文件持久保存在对应 PVC。
|
||
|
||
COMPLETED 表示模型结束本轮工具循环,不是生产发布 / 构建验收结论。用户需核对实际工具日志、退出码、文件与构建测试结果。自动浏览器测试、预览代理和正式部署尚未实现。
|
||
|
||
## 隔离网关部署
|
||
|
||
1. 准备测试 K3s / Kubernetes 集群、支持 NetworkPolicy 的 CNI、可用 PVC provisioner。
|
||
2. 安装并实际验证 gVisor RuntimeClass `gvisor`(也可配置经验证的 Kata 类运行时)。不得把该名称映射回普通 runc 以绕过隔离要求。
|
||
3. 节点 kubelet 设置进程数等主机级限制,例如 `podPidsLimit`;NetworkPolicy 必须通过测试确认阻断私网、其他项目、元数据和管理网。YAML 创建成功不等于策略已生效。
|
||
4. 构建 `infra/sandbox/Dockerfile` 与 `node-agent/Dockerfile`,推送到自己的镜像仓库;生产应使用经扫描且固定摘要的镜像。
|
||
5. 检查并应用 `infra/k8s/sandbox-rbac.yaml`,配置独立随机 `SANDBOX_TOKEN` 的 Kubernetes Secret `sandbox-gateway`。Secret 通过受保护文件或密钥管理系统导入,不把明文提交到仓库。
|
||
6. 替换 `sandbox-gateway.yaml` 内两个镜像地址,部署网关。它只提供 ClusterIP 服务;不要暴露到公网。
|
||
7. 控制面与 Worker 配置相同的 SANDBOX_URL、SANDBOX_TOKEN、APP_ENCRYPTION_KEY。跨主机使用受认证的私有 TLS 网络;本地测试可通过只监听回环的 kubectl port-forward。
|
||
8. 本地 Compose 使用 `docker compose --profile ai up -d --build` 启动独立 AI Worker。配置不足时 Worker 启动失败,不降级到宿主机执行。控制面默认不运行 Worker。
|
||
|
||
开发工作区默认没有命名空间总配额。旧集群更新部署清单后,运行以下命令移除旧版安装的总配额:
|
||
|
||
```sh
|
||
kubectl -n platform-sandboxes delete resourcequota workspace-quota --ignore-not-found
|
||
```
|
||
|
||
网关自身是可信基础设施组件,持有指定命名空间的 Pod / PVC / NetworkPolicy 创建权限及 Pod exec 权限。它不需要集群管理员权限,不挂载 Docker Socket。工作区禁用 ServiceAccount token、非 root、只读根文件系统、禁提权、drop ALL capabilities、RuntimeDefault seccomp、独立 PVC、CPU / 内存 / 临时盘限制。工作区容器内没有平台 API Key 或管理凭证。
|
||
|
||
当前资源额度是网关固定安全默认值,尚未与商业套餐调度连接。网关单副本,每个工作区串行执行工具;锁映射与资源生命周期清理、限流及多副本网关需要后续工程完善。PVC 不自动删除,避免误删项目数据。
|
||
|
||
## 文件、版本与源码
|
||
|
||
在云托管选择「从源码发布」,平台会检查当前工作区并为本次发布保存独立快照。支持根目录 `index.html`、含 `scripts.start` 的 Node.js 项目,以及含 `scripts.build` 且输出 `dist/index.html` 或 `build/index.html` 的前端项目。依赖项目需要提交 npm 锁文件。源码服务使用端口 3000,并提供 `HOST`、`PORT` 和 `DATA_DIR` 环境变量。Node.js 项目的 `DATA_DIR` 指向持久卷,应用应把需要保留的数据写到这里。开发工作区中的环境文件、本地数据库和依赖缓存不随源码发布。
|
||
|
||
运维在 `platform-sandboxes` 的 `webup-runtime` ConfigMap 设置 `SOURCE_IMAGE`,指向具备 Node.js、npm、Python 3 的受信运行镜像,并启用运行发布 Worker。K3s 集群需有持久卷供应器。每次发布保存源码快照,构建和启动在隔离 Pod 内执行,健康检查通过后切换流量。回滚会使用所选版本的源码和锁文件重新构建。发布仍需项目审核通过和有效托管套餐。
|
||
|
||
用户可通过真实隔离网关列目录、读写 UTF-8 文件、保存 Git 版本、列出最近 30 个版本和下载 ZIP。路径必须位于工作区,读取上限 64KB,单次写入上限 256KB。终端输出截断在 64KB,源码 ZIP 限制为 10MB / 5000 文件并排除 `.git`、node_modules、.venv 与 __pycache__。归档属于项目所有者;其中可能包含项目自身的配置文件,下载后应妥善保管。
|
||
|
||
所有这些功能均先检查项目所有权,不能用修改 URL 访问其他项目。Kubernetes exec 和 PVC 的真实运行、Git 版本操作以及完整 Agent 开发仍需集群联调验证;本地文件工具测试不能替代隔离验收。
|