Files
webup-cloud/docs/LOCAL-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

67 lines
5.1 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.
# 本机隔离执行部署
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 默认关闭。部署新版网关并通过隔离验收后,可用 `enable-preview.ps1 -EnableHosting` 启用本地托管和源码发布。公网域名仍需要实际 DNS、Ingress 与证书配置。
## 重启和复验
WSL 空闲时可能停止。保持一个终端运行以下前台命令,直到本地测试结束:
```powershell
wsl -d WebUp-Local -u root --exec sleep infinity
```
K3s 和端口转发由该发行版的 systemd 管理。检查状态:
```powershell
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
```
修改网关源码后,在项目根目录依次执行(第二步导入本地镜像并滚动重启网关):
```powershell
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 构建 / 测试;详情见 [代码验收](CODE-REVIEWS.md)。
专用测试容器 `webup-test-postgres` / `webup-test-redis` 已在同一 WSL 发行版部署,分别只映射回环端口 15432 / 16379,Redis 启用密码。测试数据库为 `webup_integration`,与预览 H2 文件库分开。测试会清理该测试数据库中的业务表,不触碰预览中的用户、模型和钱包。
```powershell
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 / 证书、对象存储与支付另行验收,不能用本次隔离工作区和数据库测试通过代替。