Files
webup-cloud/docs/LOCAL-DEVELOPMENT.md
T
WebUp Cloud db82325ed7
Verify control plane / verify (push) Canceled after 0s
Initial import of WebUp Cloud
2026-11-07 13:31:14 +08:00

5.0 KiB
Raw Blame History

本机隔离执行部署

2026-10-31 已实际部署并通过隔离验收。预览使用 Windows 上的 Vue / Spring Boot / 独立 H2 文件库,以及专用 WSL2 发行版 WebUp-Local 中的 Docker、K3s、gVisor 和私有工具网关。不需要远程服务器或 Docker Desktop,也不修改原有 Ubuntu 发行版。

当前入口与状态

  • 首页 http://127.0.0.1:5173/,用户 AI 开发 /develop,管理员 /admin。
  • 后端 http://127.0.0.1:8080,网关 http://127.0.0.1:8090(仅回环、需要令牌)。
  • 集群节点 webup-local;K3s / gVisor 版本与官方制品哈希固定在 infra/local/versions.json。
  • 平台默认同时开发 2 个项目,预览 Worker 本实例容量 4。管理员 /admin/tasks 可改总并发和队列顺序。
  • 预览 AI Worker 已启用,实际调用管理员配置的模型。预览余额是测试余额,外部模型供应商仍可能收取真实 API 费用。
  • 运行发布 / 域名 Worker 保持关闭;本阶段验证了开发工作区,没有声称公网托管、镜像构建发布或 HTTPS 域名已验收。

重启和复验

WSL 空闲时可能停止。保持一个终端运行以下前台命令,直到本地测试结束:

wsl -d WebUp-Local -u root --exec sleep infinity

K3s 和端口转发由该发行版的 systemd 管理。检查状态:

wsl -d WebUp-Local -u root --exec systemctl is-active k3s webup-gateway-forward
wsl -d WebUp-Local -u root --exec k3s kubectl get nodes

修改网关源码后,在项目根目录依次执行(第二步导入本地镜像并滚动重启网关):

wsl -d WebUp-Local -u root --exec bash '/mnt/k/web dev/webup.run/scripts/local/build-images.sh' '/mnt/k/web dev/webup.run'
wsl -d WebUp-Local -u root --exec bash '/mnt/k/web dev/webup.run/scripts/local/deploy-gateway.sh' '/mnt/k/web dev/webup.run'
wsl -d WebUp-Local -u root --exec python3 '/mnt/k/web dev/webup.run/scripts/local/smoke-cluster.py'
.\scripts\local\enable-preview.ps1

enable-preview.ps1 要求最近 24 小时真实隔离验收通过,并重新探测网关。它只更新被忽略的本地基础设施配置和预览 reload trigger,不创建后台 Windows 进程,不改用户 / 模型 / 钱包数据。已运行的预览后端重新加载后,可在管理员服务器页面查看 READY 状态。

实际验收

真实调用网关并检查 10 项:拒绝无令牌访问、实际查询 Kubernetes、创建 PVC / 写文件、读回、拒绝父路径越界、非 root / 无平台凭证 / 根只读 / 内网阻断 / 公网 HTTPS 可达、请求 gVisor、containerd 实际使用 runsc、每 Pod 512 进程限制、删除工作区 Pod 后文件仍可读。

报告保存于 Linux /etc/webup-local/smoke-report.json 和宿主机 .runtime/local-cluster/smoke-report.json。验收只操作随机 UUID 的测试项目,不删除用户工作区。开发文件保存在 K3s PVC,前端编辑器与 AI Worker 共用同一网关;没有把用户 shell 命令放在 Windows 宿主机执行。

PostgreSQL / Redis 真实自动化测试

独立验收已部署 platform-reviews 命名空间和受限 RBAC。可运行 wsl -d WebUp-Local -u root --exec python3 '/mnt/k/web dev/webup.run/scripts/local/smoke-code-review.py' 复验真实隔离复制和 npm 构建 / 测试;详情见 代码验收。

专用测试容器 webup-test-postgres / webup-test-redis 已在同一 WSL 发行版部署,分别只映射回环端口 15432 / 16379,Redis 启用密码。测试数据库为 webup_integration,与预览 H2 文件库分开。测试会清理该测试数据库中的业务表,不触碰预览中的用户、模型和钱包。

wsl -d WebUp-Local -u root --exec python3 '/mnt/k/web dev/webup.run/scripts/local/start-test-services.py'
.\scripts\local\run-real-tests.ps1
wsl -d WebUp-Local -u root --exec python3 '/mnt/k/web dev/webup.run/scripts/local/check-database-persistence.py'

该脚本只接受固定的本机测试库 / Redis 地址,从被忽略的 services.env 导入环境,并在运行结束后恢复原环境变量。首次部署需要拉取 ECR Public 官方镜像 public.ecr.aws/docker/library/postgres:17 与 public.ecr.aws/docker/library/redis:7.4。

最新真实 PostgreSQL / Redis 全量测试 100 项通过、无跳过。持久化检查实际重启专用测试 PostgreSQL,非空用户、钱包、账本、任务数据与迁移记录保持一致;预览控制面的 H2 数据库不参与该重启。

本地私有文件

.runtime/ 和 .tools/ 已被 Git 忽略。网关令牌在 Linux /etc/webup-local/gateway.env(0600)与宿主机 .runtime/local-cluster/gateway.env;宿主机目录仅当前账户和 SYSTEM 可访问。不要分享这些文件、预览账号文件、数据库文件或 kubeconfig。预览日志只记录任务 ID 和状态,不记录模型密钥。

本地 H2 / 内存短期存储仍属于预览配置。正式域名 DNS / 证书、对象存储与支付另行验收,不能用本次隔离工作区和数据库测试通过代替。