HSAP/docs/DEPLOY.md

# HSAP 部署指南（新机器 / 他人电脑）

本文档面向 **从 Git 克隆后在全新 Linux 机器上启动 HSAP**（平台 + CVAT + PostgreSQL + Redis）。

---

## 1. 环境要求

| 组件 | 版本 |
|------|------|
| Docker | 20.10+ |
| Docker Compose | v2（`docker compose` 子命令） |
| Node.js + npm | 18+（仅构建前端；运行期不需要） |
| 磁盘 | 建议 ≥ 20GB（含 CVAT 镜像与数据卷） |
| 内存 | 建议 ≥ 8GB |

Ubuntu 示例：

```bash
sudo apt update
sudo apt install -y docker.io docker-compose-v2 git nodejs npm
sudo usermod -aG docker $USER   # 重新登录后生效
```

---

## 2. 克隆与初始化

```bash
git clone https://git.sanyele.com/ChengFang.LU/HSAP.git
cd HSAP
bash scripts/init_after_clone.sh
```

脚本会：

- 从 `.env.example` 生成 `.env`
- 从 `manifests/feishu.env.example` 生成 `manifests/feishu.env`
- 若上级目录存在 `workspace/`、`data/`，自动写入挂载路径
- 首次构建前端 → `platform/ui-hsap/dist/`
- **植入 `lake/lake_example` 样例送标批次** → 数据湖 inbox（接手人可直接走流程）

---

## 3.5 样例送标数据（lake_example）

`init_after_clone.sh` 已自动执行 `scripts/seed_lake_example.sh`。也可单独重跑：

```bash
bash scripts/seed_lake_example.sh
```

推荐验收批次：

| 类型 | 批次名 |
|------|--------|
| ADAS 2D | `20260616_adas2d_pilot` |
| ADAS 3D | `20260616_3d_pilot` |
| DMS | `20260616_addw_pilot` |

平台启动后：**批次台账 → 扫描数据湖 → 登记 → 送标工作台开标**。详见 [README 接手流程](../README.md#接手走通送标流程lake_example)。

---

## 3. 必改配置

### 3.1 `.env`（Docker Compose）

```bash
cp .env.example .env
nano .env
```

| 变量 | 说明 |
|------|------|
| `AS_WORKSPACE_ROOT` | DMS/Lane 大文件目录（宿主机绝对路径） |
| `AS_DATA_LAKE_HOST` | 送标数据湖根目录，下有 `送标/adas`、`送标/dms` 等 |
| `AS_FRONTEND_URL` | 浏览器访问 HSAP 的完整 URL（局域网用 `http://<IP>:8787`） |
| `CVAT_PUBLIC_URL` | 浏览器访问 CVAT 的 URL（通常 `http://<IP>:8080`） |
| `FEISHU_REDIRECT_URI` | 飞书回调，与 `AS_FRONTEND_URL` 同源 |
| `AS_DB_PORT` / `AS_REDIS_PORT` | 宿主机端口冲突时修改（默认 5433 / 6380） |

### 3.2 `manifests/feishu.env`（认证）

**开发 / 内网演示**（无需飞书）：

```env
AS_DEV_AUTH=true
AS_JWT_SECRET=请更换为随机长字符串
```

**生产飞书登录**：填入 `FEISHU_APP_ID`、`FEISHU_APP_SECRET`，并将 `AS_DEV_AUTH=false`。

---

## 4. 数据目录布局

推荐与仓库平级：

```text
DATA/
├── HSAP/                 # 本仓库
├── workspace/            # AS_WORKSPACE_ROOT
│   ├── DMS/
│   └── LaneDection/
└── data/                 # AS_DATA_LAKE_HOST
    └── 送标/
        ├── adas/
        │   └── inbox/
        │       ├── det_7cls/      # ADAS 2D 七类
        │       └── cuboid_7cls/   # ADAS 3D Cuboid
        └── dms/
            └── inbox/
```

inbox 目录结构示例见仓库内 `lake/lake_example/`。

`.env` 示例：

```env
AS_WORKSPACE_ROOT=/opt/DATA/workspace
AS_DATA_LAKE_HOST=/opt/DATA/data
AS_FRONTEND_URL=http://192.168.1.50:8787
CVAT_PUBLIC_URL=http://192.168.1.50:8080
FEISHU_REDIRECT_URI=http://192.168.1.50:8787/api/v1/auth/feishu/callback
```

---

## 5. 启动

```bash
bash scripts/dev_up.sh
# 或
make up
```

单文件编排：`docker-compose.yml` 已包含 **平台 + CVAT 全套服务**，无需 `-f` 多文件。

| 服务 | 默认地址 |
|------|----------|
| HSAP 平台 | http://127.0.0.1:8787 |
| CVAT 画布 | http://127.0.0.1:8080 |
| PostgreSQL | localhost:5433 |
| Redis | localhost:6380 |

健康检查：

```bash
make health
docker compose ps
```

---

## 6. 前端更新

修改 `platform/web/` 后须重新构建并重启：

```bash
bash scripts/build_web.sh
docker compose restart platform
```

---

## 7. 常用运维

```bash
docker compose logs -f platform worker cvat_server
docker compose down
docker compose up -d --build          # 拉代码后重建
bash scripts/reset_labeling.sh        # 清空标注 DB（保留账号）
```

可选 MinIO 暂存：

```bash
docker compose --profile minio up -d
```

---

## 8. 排障

| 现象 | 处理 |
|------|------|
| 8787 白屏 / 旧 UI | `bash scripts/build_web.sh && docker compose restart platform` |
| 标注页 CVAT 无法嵌入 | 检查 `CVAT_PUBLIC_URL` 与 `AS_FRONTEND_URL` 是否为浏览器实际访问地址 |
| `CVAT 标注引擎不可用` | `docker compose ps`，确认 `hsap-cvat-server`、`hsap-cvat-traefik` 为 Up |
| 送标扫描不到批次 | 确认 `AS_DATA_LAKE_HOST` 挂载正确，`送标/adas/inbox/...` 路径存在 |
| 端口冲突 | 修改 `.env` 中 `AS_PLATFORM_PORT`、`CVAT_PORT`、`AS_DB_PORT`、`AS_REDIS_PORT` |

更多架构与 API 说明见 [HANDOVER.md](HANDOVER.md)。

---

## 9. 开发机 vs 接手人环境（均可本机自行解决）

以下条目是 **环境差异**，不是仓库缺陷。每一项都可以在接手人自己的主机上通过配置或一次性命令解决；按 `init_after_clone.sh` → `dev_up.sh` 走，**送标样例流程不依赖开发者的个人目录或数据**。

### 9.1 不要从开发者机器拷贝的文件

| 文件 | 原因 | 接手人做法 |
|------|------|------------|
| `.env` | 含开发者绝对路径（如 `/home/xxx/DATA/...`） | 用 `init` 从 `.env.example` 生成，再按本机改路径 |
| `manifests/feishu.env` | 含飞书 Secret、个人 admin open_id | 用 `feishu.env.example` 复制；验收阶段保持 `AS_DEV_AUTH=true` 即可 |

### 9.2 首次部署常见差异

| 现象 | 原因 | 本机解决 |
|------|------|----------|
| 8787 白屏 | `platform/ui-hsap/dist` 不在 Git | 安装 Node 18+ 后 `bash scripts/build_web.sh`（`init` 会尝试） |
| `docker: permission denied` | 用户不在 `docker` 组 | `sudo usermod -aG docker $USER` 后重新登录 |
| 样例 DMS 拷不进 inbox | 曾用 root 跑过 Docker，`inbox` 属主为 root | `sudo chown -R $USER datasets/dms/inbox` 后重跑 `seed_lake_example.sh` |
| 扫描不到 ADAS 批次 | `datasets/adas` 软链或 `data/送标/adas` 未建 | 重跑 `bash scripts/seed_lake_example.sh`；确认 `AS_DATA_LAKE_HOST` |
| 首次 `up` 很慢 | 需拉 CVAT / ClickHouse 等大镜像 | 保证能访问 Docker Hub，等待拉取完成 |
| 端口被占用 | 8787 / 8080 / 5433 / 6380 冲突 | 改 `.env` 对应端口后 `docker compose up -d` |
| CVAT iframe 空白（局域网） | 浏览器用 IP 访问，`.env` 仍是 `127.0.0.1` | 改 `AS_FRONTEND_URL`、`CVAT_PUBLIC_URL` 为实际 `http://<IP>:端口` |
| 车队地图无瓦片 | 未配高德 Key | 可选：`.env` 填 `AS_AMAP_KEY`；不影响送标主流程 |
| `git clone` 失败 | 无 git.sanyele.com 权限 | HTTPS + Gitea Token，或登记 SSH 公钥 |

### 9.3 本就不随 Git 带走的内容（新机器为空是正常的）

| 内容 | 说明 |
|------|------|
| Docker 卷 `hsap_*` | 用户、标注任务、CVAT 数据；新环境需重新「扫描 → 登记 → 开标」 |
| `workspace/` 训练大图 | 仅训练需要；`lake_example` 已覆盖送标验收 |
| 开发者 `data/送标/` 真实批次 | 生产数据各自挂载；样例在 `lake/lake_example/` |

### 9.4 部署前自检（复制执行）

```bash
docker --version && docker compose version
node -v && npm -v                    # 建议 Node 18+
groups | grep -q docker && echo OK   # 或在 docker 组

cd HSAP
bash scripts/init_after_clone.sh
bash scripts/dev_up.sh
make health

# 浏览器：8787 → 开发登录 → 批次台账应能扫到 20260616_adas2d_pilot
```

### 9.5 可选能力（验收样例不强制）

| 能力 | 何时需要 |
|------|----------|
| `AS_WORKSPACE_ROOT` | DMS/Lane 训练、大图 promote |
| 飞书 OAuth | 关闭 `AS_DEV_AUTH`、走正式登录与任务通知 |
| `AS_AMAP_KEY` | 车队地图国内底图完整显示 |
| MinIO profile | S3 暂存联调 |

**结论：** 仓库不绑定某一台开发机；路径、端口、认证、Docker 权限均在接手人本机配置即可跑通。