Document deployment and expose weight manifest

README.md

@@ -31,20 +31,124 @@ cp .env.example .env
 # Create or repair the two runtime environments, then verify imports.
 scripts/bootstrap_conda_envs.sh
 
-# Backend. The deployment env is seg_smp so the API and most task wrappers
-# share the same segmentation dependency stack. MMSeg jobs default to the
-# separate SEG_MMSEG_CONDA_ENV because full mmcv wheels must match torch/CUDA.
-conda run -n seg_smp uvicorn app.main:app --app-dir backend --host 0.0.0.0 --port 8010
+# Backend. The script loads .env and uses SEG_BACKEND_CONDA_ENV/PORT/HOST.
+scripts/run_backend.sh
 
-# Frontend.
-cd frontend
-npm install
-npm run dev -- --host 0.0.0.0
+# Frontend. The script loads .env, installs npm packages, and starts Vite.
+scripts/run_frontend.sh
 ```
 
 Open the Vite URL shown in the terminal. The frontend expects the backend at
 `http://localhost:8010` by default.
 
+## Deployment and Environment
+
+The expected deployment layout keeps the original algorithm workspace next to
+this web project:
+
+```text
+/home/wkmgc/Desktop/Data_Disk_1/Seg/
+  Seg/                  existing algorithms, datasets, logs, and raw outputs
+  Seg_Data_Server_Net/  this FastAPI + React control plane
+```
+
+Clone or update the web project from Gitea:
+
+```bash
+git clone https://gitea.huijutec.cn/admin/Seg_Data_Server_Net.git
+cd Seg_Data_Server_Net
+cp .env.example .env
+```
+
+Edit `.env` for the server before first boot. Relative paths are resolved from
+the `Seg_Data_Server_Net/` project root; absolute paths are safest when moving
+to another machine.
+
+```bash
+SEG_SOURCE_ROOT=../Seg
+SEG_DATA_SERVER_ROOT=.
+SEG_BACKEND_DB=var/seg_data_server.sqlite3
+SEG_BACKEND_LOG_DIR=var/job_logs
+SEG_TASK_CONDA_ENV=seg_smp
+SEG_MMSEG_CONDA_ENV=seg_mmcv
+SEG_BACKEND_CONDA_ENV=seg_smp
+SEG_WEIGHT_MODE=copy
+SEG_ENABLE_SHELL_TASKS=1
+SEG_VALIDATE_DEEP=1
+VITE_API_BASE=http://localhost:8010
+```
+
+Install system prerequisites first: Git, Conda or Miniconda, Node.js/npm, a
+working NVIDIA driver and `nvidia-smi` for GPU discovery, and enough free disk
+space for the copied weights. Full weight sync currently needs about 35 GB
+plus normal training output space.
+
+Create the Python runtimes with the bundled bootstrap script:
+
+```bash
+scripts/bootstrap_conda_envs.sh all
+```
+
+This creates `seg_smp` for the backend, SegModel, YOLO, dataset tools, and
+general analysis jobs, plus `seg_mmcv` for full MMSeg/mmcv execution. To repair
+only one environment:
+
+```bash
+scripts/bootstrap_conda_envs.sh task
+scripts/bootstrap_conda_envs.sh mmseg
+```
+
+Install and build the frontend once during deployment:
+
+```bash
+cd frontend
+npm install
+npm run build
+cd ..
+```
+
+Synchronize weights locally after the original `Seg/` directory is present.
+The command copies `.pt`, `.pth`, `.onnx`, and `.engine` files into
+`weights/files/` and writes `weights/manifest.json`.
+
+```bash
+python scripts/sync_weights.py --mode copy --hash
+```
+
+If the deployment filesystem supports copy-on-write reflinks and disk space is
+tight, set `SEG_WEIGHT_MODE=reflink` or pass `--mode reflink`; otherwise keep
+the default `copy` mode. Weight binaries must stay out of normal Git commits.
+
+Start the services:
+
+```bash
+# Terminal 1
+scripts/run_backend.sh
+
+# Terminal 2
+scripts/run_frontend.sh
+```
+
+Defaults are `0.0.0.0:8010` for the backend and Vite's dev port for the
+frontend. Override backend binding with `SEG_BACKEND_HOST` and
+`SEG_BACKEND_PORT`. For a production process manager such as systemd,
+supervisor, or Docker Compose, call the same two scripts so `.env` and the
+configured conda environments are used consistently.
+
+Validate a deployment before handing it to operators:
+
+```bash
+curl http://127.0.0.1:8010/api/health
+curl http://127.0.0.1:8010/api/system/readiness
+PYTHONPATH=backend conda run -n seg_smp python scripts/verify_runtime_envs.py --refresh
+PYTHONPATH=backend conda run -n seg_smp python scripts/run_agents.py --build
+scripts/check_no_weight_git.sh
+```
+
+For a fast non-training validation pass, run agents with
+`SEG_VALIDATE_DEEP=0`. The browser dashboard exposes the same readiness,
+coverage, GPU, weight, result, and agent checks through the UI.
+
 The web UI includes a dataset bench for creating upload workspaces, uploading
 images/labels/masks, and jumping into the existing rename, PNG conversion,
 resize, pair-check, label rebuild, transparent overlay, stitch, and video-frame
@@ -132,6 +236,9 @@ scripts/bootstrap_conda_envs.sh mmseg
 The current workspace contains tens of GB of pretrained and trained weights.
 They are copied into `weights/files/<original-relative-path>` and indexed in
 `weights/manifest.json`.
+The web weight panel reads `GET /api/weights`, shows family/role counts and
+sample source paths, and can run `POST /api/weights/verify` to check the local
+manifest entries without putting the large files in Git.
 
 ```bash
 cd Seg_Data_Server_Net