chore(dev): add pnpm dev hot-reload workflow for local development

Replace full docker compose rebuild during development with:
- pnpm dev / dev:backend (air hot-reload control-plane) / dev:frontend (vite HMR) / dev:deps
- compose.dev.yaml: postgres+docker-gateway only, host port mapping (5432/8081), container control-plane disabled via profile
- scripts/dev-backend.mjs: read .env, fill dev defaults (login admin/admin123, listen :8082, 32-byte dev master key with explicit warning on invalid .env value), ensure dep containers, run air
- vite: fixed port 5173, /api proxy to local control-plane (8082)
- README: document hot-reload dev workflow

Verified: pnpm dev end-to-end (login/API/frontend/proxy 200), Go+JSX edit hot-reload, compose config --quiet, go build ./..., web tests 65 passed, npm --prefix web run build.
This commit is contained in:
2026-09-02 14:38:44 +08:00
parent 2676df12c2
commit 208f6766af
8 changed files with 192 additions and 9 deletions
+26
View File
@@ -25,6 +25,32 @@ DOCKER_GID=$(stat -c %g /var/run/docker.sock) docker compose up --build
打开 <http://127.0.0.1:8080>,使用 `CONTROL_PLANE_USERNAME` / `CONTROL_PLANE_PASSWORD` 登录;局域网内用宿主机 IP 访问同一端口。首次使用:在「网关管理」用 Compose 里的 `GATEWAY_TOKEN` 注册 `http://docker-gateway:8081`,在「镜像版本」添加可用的指纹浏览器镜像引用,即可创建环境;网关会在镜像缺失时自动拉取。架构、API 契约、失败语义和 `docker.sock` 风险边界见
[《浏览器容器控制面》](docs/architecture/container-control.md)。
## 本地开发(热加载)
日常开发不再整仓重建镜像,改用源码热加载:
```bash
npm --prefix web ci
pnpm dev
```
- `pnpm dev`:同时起后端(air 热重载)与前端(vite HMR);
- `pnpm dev:backend` / `pnpm dev:frontend`:单独启动其中一端;
- `pnpm dev:deps`:仅启动 postgres 与 docker-gateway 两个容器(`compose.dev.yaml` 会把 5432/8081 映射到宿主机)。
服务地址:
| 端 | 地址 | 说明 |
| --- | --- |
| 前端 | <http://127.0.0.1:5173> | `/api` 由 vite 代理到本地 control-plane |
| 后端 control-plane | <http://127.0.0.1:8082> | Go 源码改动即自动重启 |
| docker-gateway | <http://127.0.0.1:8081> | 容器内常驻,重启不频繁 |
| postgres | `127.0.0.1:5432` | 容器内常驻,数据库重建直接销毁 volume |
开发默认值(`.env` 缺失或留空时):登录 `admin` / `admin123`;控制面监听 `:8082`;凭据主密钥使用本地开发专用密钥;本地网关注册地址用 `http://127.0.0.1:8081`(容器名 `docker-gateway` 仅存在于 Compose 网络内)。
注意:本地开发后端占用 `:8082`,与整仓 `docker compose up` 的容器端口互斥,两者二选一运行。
最小验证:
```bash