Files
webup-cloud/docs/AI-DEVELOPMENT.md
WebUp Cloud d1d14f0f77
Verify control plane / verify (push) Canceled after 0s
Verify control plane / verify (pull_request) Canceled after 0s
Publish AI workspace source through the isolated runtime
2026-11-08 17:29:54 +08:00

79 lines
10 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 模型、钱包与隔离开发
本模块新增可执行代码,不代表全部商业需求已完成。真实供应商调用与 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 开发仍需集群联调验证;本地文件工具测试不能替代隔离验收。