hullwork/site Vibe 项目

项目简介

hullwork/site 是与 hullwork/sandbox 配套的第二个开源基础设施项目，聚焦于解决 AI Agent 部署场景中「控制器返回成功，但用户实际上访问不到网站」的可验证性问题。项目提出「deployed 是一个测量结果，而非一句声明」的设计理念：Agent 通过 HTTP API / CLI / MCP 提交部署请求，Operator 等工作负载 Ready 后，会主动向目标地址发送真实 HTTP 请求，将状态码和响应体 SHA-256 写入 status.verification 字段，使「部署成功」变成可检查、可复现的测量结果。项目采用 MIT 协议，状态为 alpha。

核心功能

真实 HTTP 验证机制

与传统的仅依赖 Kubernetes 调度状态判断部署成功不同，site 的 Operator 在工作负载 Ready 后会主动发起真实 HTTP 请求到生成的地址，记录响应状态码和响应体 SHA-256 摘要。只有 2xx 响应才算验证成功（重定向不会 follow），这意味着「部署成功」是一个经得起独立验证的测量结果，而非进程退出码。

三种部署方式覆盖主流场景

支持四种部署形态：版本化静态发布（通过 MCP deploy_static_versioned）、静态直传（sites deploy-static）、已有镜像部署（sites deploy）、源码构建部署（sites build submit）。源码构建使用隔离的 BuildKit Job 产生不可变镜像摘要，静态发布支持嵌套 UTF-8 树结构和私有 S3/OSS 存储。

MCP 工具 + 脚手架自动评估

Agent 应通过 MCP 或 GET /v1/scaffolds 调用脚手架来选择静态 HTML、Vite、FastAPI/PostgreSQL、Express/PostgreSQL 等精选配置。API 会对源目录、执行部署检查和共享 schema 策略进行校验，并返回 contractCheckSuccessRate 和 agentEndToEndSuccessRate 两个真实成功率数字——未被实际执行的检查会标记为 not-run，不会凭空捏造端到端数字。

缩容至零与按需唤醒

sites-activator 组件负责缩容至零时的请求保持与唤醒：收到请求时若 Pod 已缩容，先保持连接、触发扩容、等 Pod 就绪后再转发请求，调用方不会看到错误。

多租户隔离与安全设计

租户身份由（merchant, tenant）配对通过凭证决定，Caller 声明的 X-Merchant-ID 和 X-User-ID 会直接被拒绝（403），而非静默忽略，防止配置错误的客户端将数据写入他人命名空间。Namespace 和资源名称来源于身份两部分的 SHA-256 摘要，而非字符串拼接，避免了碰撞到同一 Namespace 的风险。

技术实现

项目使用 Python 构建，由 sites-api（认证/准入/API）、sites-operator（CR 调和循环）、sites-activator（缩容唤醒）三个常驻进程加一个构建平面（rootless BuildKit Job + 内网镜像仓库）组成。sites-api 使用进程内 admission lock 替代分布式锁简化部署；sites-operator 无 leader election，单副本运行。Schema 迁移被限制在 sqlglot AST allow-list（仅允许 CREATE TABLE/INDEX IF NOT EXISTS 和 ADD COLUMN IF NOT EXISTS），确保旧版本镜像在较新数据库上也能正常运行。Django 作为 Web 框架，提供 React 管理 Console。

快速上手

1. 确认环境：macOS 或 Linux、硬件虚拟化支持、出站 HTTPS、三台 Lima VM 所需资源（8 CPU、10 GiB RAM、70 GiB 磁盘），安装 Git/Lima/Docker/kubectl/Helm/uv/Python 3.12+；
2. 执行 git clone https://github.com/hullwork/site.git && cd site 进入项目目录；
3. 执行 make quickstart，自动创建包含 1 个 control-plane + 2 个 worker 的 kubeadm 集群，部署 site 自身和示例 HTML 应用，等待 HTTP 验证通过后输出真实公网地址和摘要；
4. 启动 make quickstart-access 保持控制台隧道，在另一终端执行 make quickstart-token 获取管理员令牌，打开浏览器访问 http://127.0.0.1:18091 的 Console 界面查看应用状态；
5. 通过 CLI 部署自有应用：export SITES_URL=http://127.0.0.1:18091 && sites deploy --name myapp --image 。

适用人群

为 AI Agent 构建完整 CI/CD 流水线的平台工程师、需要确保 AI Agent 交付物可验证的企业开发团队、研究 AI Agent 自主性的研究者，以及关注部署确定性而非仅依赖调度状态的开源社区开发者。

官方链接

• GitHub 仓库：https://github.com/hullwork/site
• 项目官网：https://hullwork.github.io/site/