Chengfang Lu
7f3b84faf0
说明勿拷贝开发者 .env/feishu.env、常见排障与部署前自检，明确不绑定单机环境。 Co-authored-by: Cursor <cursoragent@cursor.com>
338 lines
11 KiB
Markdown
338 lines
11 KiB
Markdown
# HSAP — Huaxu Sentinel Active Safety Platform
|
||
|
||
**华胥 Sentinel 主动安全算法迭代平台**（HSAP）：卡车主动安全（DMS / Lane / ADAS）算法迭代平台，含 **Web UI + API + 审核 + Job 队列 + CVAT 标注 + 算法适配器 + 车队地图**。
|
||
|
||
克隆本仓库即可运行；**算法源码与数据集脚手架已内嵌**。大文件（图像、训练权重）通过外部 `workspace` 或 **送标数据湖** 挂载，不进入 Git。
|
||
|
||
**新机器 3 步部署 → 见下方 [快速部署到其他机器](#快速部署到其他机器)** · 详细文档 [docs/DEPLOY.md](docs/DEPLOY.md)
|
||
|
||
---
|
||
|
||
## 快速部署到其他机器
|
||
|
||
在目标 Linux 机器上执行（需 Docker + Node 18+）：
|
||
|
||
```bash
|
||
# 1. 克隆（HTTPS 需 Gitea 用户名 + Access Token 作密码；或配置 SSH 公钥）
|
||
git clone https://git.sanyele.com/ChengFang.LU/HSAP.git
|
||
cd HSAP
|
||
|
||
# 2. 初始化：.env、feishu.env、前端构建、lake_example 样例植入
|
||
bash scripts/init_after_clone.sh
|
||
|
||
# 3. 启动平台 + CVAT
|
||
bash scripts/dev_up.sh
|
||
```
|
||
|
||
浏览器打开 http://127.0.0.1:8787 → 开发登录 → **批次台账 → 扫描数据湖 → 登记 → 送标工作台开标**（样例已自动就位）。
|
||
|
||
| 检查项 | 命令 / 地址 |
|
||
|--------|-------------|
|
||
| 平台健康 | `make health` |
|
||
| 容器状态 | `docker compose ps` |
|
||
| 样例批次 | `lake/lake_example/datasets/manifest.yaml` |
|
||
| 局域网访问 | 改 `.env` 中 `AS_FRONTEND_URL`、`CVAT_PUBLIC_URL` 为 `http://<IP>:8787` / `:8080` |
|
||
|
||
**目录布局（推荐与仓库平级）：**
|
||
|
||
```text
|
||
/opt/DATA/
|
||
├── HSAP/ ← git clone
|
||
└── data/ ← AS_DATA_LAKE_HOST，init 自动创建 送标/adas/inbox
|
||
```
|
||
|
||
`AS_WORKSPACE_ROOT`（DMS 训练大图）**验收送标流程不必配置**；有外部 workspace 时再在 `.env` 填写。
|
||
|
||
**环境差异说明：** 路径、端口、Docker 权限、前端构建等项因机器而异，但**均可在本机按 [docs/DEPLOY.md §9](docs/DEPLOY.md#9-开发机-vs-接手人环境均可本机自行解决) 自行解决**，不依赖开发者个人目录。
|
||
|
||
**推送代码到远端：**
|
||
|
||
```bash
|
||
git push origin main
|
||
# 用户名 Chengfang.LU，密码填 Gitea Access Token（设置 → 应用 → 生成令牌）
|
||
```
|
||
|
||
---
|
||
|
||
## 仓库结构
|
||
|
||
```text
|
||
HSAP/
|
||
├── as.py / workflow.registry.yaml
|
||
├── platform/
|
||
│ ├── as_platform/ # FastAPI 后端
|
||
│ │ └── labeling/ # CVAT 客户端、格式转换、任务分配
|
||
│ └── web/ # React (Vite) 前端 → build 到 ui-hsap/dist
|
||
├── algorithms/
|
||
│ ├── dms_yolo/code/ # DMS YOLO
|
||
│ └── lane_ufld/code/ # Lane UFLD
|
||
├── datasets/
|
||
│ ├── dms/ # DMS 配置/脚本
|
||
│ ├── lane/
|
||
│ ├── adas -> ../../data/送标/adas # ADAS 送标数据湖（符号链接，clone 后可手动创建）
|
||
│ └── labeling.registry.yaml
|
||
├── lake/lake_example/ # 数据湖 inbox 目录示例与 manifest
|
||
├── vendor/cvat/patches/ # CVAT no_auth + iframe 补丁
|
||
├── scripts/ # dev_up、build_web、init_after_clone 等
|
||
├── docs/DEPLOY.md # 新机器部署（推荐阅读）
|
||
├── docs/HANDOVER.md # 详细交接文档
|
||
├── docker-compose.yml # 平台 + CVAT（单文件，已合并）
|
||
└── manifests/
|
||
├── feishu.env.example
|
||
└── feishu.env # 本地生成，不入 Git
|
||
```
|
||
|
||
| 内容 | 是否在 Git 中 | 说明 |
|
||
|------|---------------|------|
|
||
| 平台 + 前端源码 + 适配器 | ✅ | 直接提交 |
|
||
| CVAT 补丁 / compose | ✅ | `vendor/cvat/patches/` |
|
||
| 前端构建产物 `ui-hsap/dist` | ❌ | `bash scripts/build_web.sh` 生成 |
|
||
| 算法 Python 源码 | ✅ | `scripts/vendor_workspace.sh` 可同步 |
|
||
| 送标图像 / 标定 / 标注 | ❌ | 数据湖挂载 |
|
||
| 图像 / 视频 / 权重 | ❌ | `.gitignore` |
|
||
|
||
---
|
||
|
||
## 快速开始（Docker，推荐）
|
||
|
||
**依赖：** Docker 20+、Docker Compose v2、Node 18+（仅构建前端）
|
||
|
||
```bash
|
||
git clone https://git.sanyele.com/ChengFang.LU/HSAP.git
|
||
cd HSAP
|
||
|
||
bash scripts/init_after_clone.sh # .env / feishu.env、构建前端、植入 lake_example 样例
|
||
bash scripts/dev_up.sh # 或: make up
|
||
```
|
||
|
||
按上面两步即可 **启动平台**；`init_after_clone.sh` 会自动把 [`lake/lake_example`](lake/lake_example/) 里的示例送标批次复制到数据湖 inbox，接手人无需再手动拷文件。
|
||
|
||
| 服务 | 地址 | 说明 |
|
||
|------|------|------|
|
||
| HSAP 平台 UI + API | http://127.0.0.1:8787 | 登录、送标、标注、审核、车队地图 |
|
||
| CVAT 标注画布 | http://127.0.0.1:8080 | HSAP iframe 嵌入；内部 no_auth |
|
||
| PostgreSQL | localhost:5433 | 见 `.env` `AS_DB_PORT` |
|
||
| Redis | localhost:6380 | Job 队列 |
|
||
|
||
```bash
|
||
make logs # platform / worker / cvat 日志
|
||
make down # 停止全部服务
|
||
make health # API 健康检查
|
||
```
|
||
|
||
**开发登录：** `manifests/feishu.env` 中 `AS_DEV_AUTH=true` 时无需飞书即可登录。
|
||
|
||
**改前端后：** 须 `bash scripts/build_web.sh` 并 `docker compose restart platform`。
|
||
|
||
**局域网部署：** 修改 `.env` 中 `AS_FRONTEND_URL`、`CVAT_PUBLIC_URL`，详见 [docs/DEPLOY.md](docs/DEPLOY.md)。
|
||
|
||
---
|
||
|
||
## 接手走通送标流程（lake_example）
|
||
|
||
仓库内 [`lake/lake_example/`](lake/lake_example/) 含 **DMS / ADAS 2D / ADAS 3D / Lane** 各一条样例批次（含少量图片），用于验收全流程。
|
||
|
||
### 一键植入（部署时自动执行）
|
||
|
||
```bash
|
||
bash scripts/init_after_clone.sh # 已包含 seed
|
||
# 或单独执行：
|
||
bash scripts/seed_lake_example.sh
|
||
```
|
||
|
||
样例落盘位置：
|
||
|
||
| 业务 | 路径 | 样例批次 |
|
||
|------|------|----------|
|
||
| ADAS 2D | `data/送标/adas/inbox/det_7cls/` | `20260616_adas2d_pilot` |
|
||
| ADAS 3D | `data/送标/adas/inbox/cuboid_7cls/` | `20260616_3d_pilot` |
|
||
| DMS | `datasets/dms/inbox/addw/` 等 | `20260616_addw_pilot` 等 |
|
||
| Lane | `datasets/lane/inbox/` | `20260616_lane_pilot` |
|
||
|
||
默认 `AS_DATA_LAKE_HOST=../data`（与 HSAP 仓库平级）。完整清单见 [`lake/lake_example/datasets/manifest.yaml`](lake/lake_example/datasets/manifest.yaml)。
|
||
|
||
### UI 操作顺序
|
||
|
||
1. 打开 http://127.0.0.1:8787 → 开发登录
|
||
2. **批次台账** → **扫描数据湖** → 勾选样例批次 → **登记到台账**
|
||
3. **送标工作台** → 选批次（建议先试 `adas / det_7cls / 20260616_adas2d_pilot`）→ **开标**
|
||
4. **标注进度** → **分配任务** → 标注员进入 **我的标注** → CVAT 画框保存
|
||
5. 协调员 **提交批次** → 审核员 **审核队列** 通过 → 导出入库
|
||
|
||
清空标注记录重来：`bash scripts/reset_labeling.sh`（不删 inbox 文件，可再次扫描登记）。
|
||
|
||
---
|
||
|
||
## 标注与送标
|
||
|
||
HSAP 统一使用 **CVAT** 作为标注画布；账号、任务分配、权限在 HSAP 管理，CVAT 仅作内部引擎。
|
||
|
||
### 流程概览
|
||
|
||
```text
|
||
数据湖登记批次 → 协调员「开标」→ CVAT 自动建 Task / 上传图片
|
||
→ 协调员分配任务（飞书通讯录 + 可选 DM）
|
||
→ 标注员「我的标注」→ CVAT 画框 / Cuboid → 保存 → 同步回数据湖
|
||
→ 协调员提交批次 → 质检 → 导出入库
|
||
```
|
||
|
||
### 角色与页面
|
||
|
||
| 角色 | 典型页面 |
|
||
|------|----------|
|
||
| 协调员 (engineer) | 送标工作台、标注进度、任务分配 |
|
||
| 标注员 (labeler) | **我的标注**、标注页 |
|
||
| 审核员 (reviewer) | 审核队列 |
|
||
|
||
### 支持的标注类型
|
||
|
||
| Profile | 范围 | CVAT 工具 |
|
||
|---------|------|-----------|
|
||
| `ddaw` / `addw` 等 | DMS 2D 检测 | Rectangle |
|
||
| `lane__lane_v1` | 车道线 | Polyline |
|
||
| `det_7cls` | ADAS 2D 七类检测 | Rectangle |
|
||
| `cuboid_7cls` | ADAS 单目 3D Cuboid | Cuboid |
|
||
|
||
ADAS 7 类：`car`, `pedestrian`, `truck`, `bus`, `motorcycle`, `tricycle`, `traffic cone`
|
||
|
||
### 送标数据湖路径
|
||
|
||
宿主机（默认 `AS_DATA_LAKE_HOST` = 仓库上级 `../data`）：
|
||
|
||
| 类型 | inbox 路径 | project | task |
|
||
|------|----------|---------|------|
|
||
| ADAS 2D | `送标/adas/inbox/det_7cls/<batch>/` | `adas` | `det_7cls` |
|
||
| ADAS 3D | `送标/adas/inbox/cuboid_7cls/<batch>/` | `adas` | `cuboid_7cls` |
|
||
| DMS | `送标/dms/inbox/<profile>/<batch>/` | `dms` | 见 profile |
|
||
|
||
批次目录示例见 `lake/lake_example/`。登记：**批次台账 → 扫描数据湖 → 登记**。
|
||
|
||
部署时执行 `bash scripts/seed_lake_example.sh`（已包含在 `init_after_clone.sh`）可自动植入样例批次。
|
||
|
||
清空送标/标注 DB（保留账号）：`bash scripts/reset_labeling.sh`
|
||
|
||
---
|
||
|
||
## 环境变量（`.env`）
|
||
|
||
| 变量 | 默认 | 说明 |
|
||
|------|------|------|
|
||
| `AS_PLATFORM_PORT` | 8787 | HSAP 端口 |
|
||
| `CVAT_PORT` | 8080 | CVAT Traefik 端口 |
|
||
| `AS_DB_PORT` | 5433 | PostgreSQL 宿主机端口 |
|
||
| `AS_REDIS_PORT` | 6380 | Redis 宿主机端口 |
|
||
| `AS_WORKSPACE_ROOT` | 占位目录 | DMS/Lane 大文件 |
|
||
| `AS_DATA_LAKE_HOST` | `../data` | 送标数据湖根 |
|
||
| `AS_FRONTEND_URL` | `http://127.0.0.1:8787` | 浏览器访问 HSAP |
|
||
| `CVAT_PUBLIC_URL` | `http://127.0.0.1:8080` | 浏览器访问 CVAT |
|
||
|
||
完整列表见 [.env.example](.env.example)。
|
||
|
||
---
|
||
|
||
## 数据挂载
|
||
|
||
```bash
|
||
# .env
|
||
AS_WORKSPACE_ROOT=/path/to/DATA/workspace
|
||
AS_DATA_LAKE_HOST=/path/to/DATA/data
|
||
|
||
bash scripts/setup_links.sh # 可选：切换为 workspace 软链模式
|
||
docker compose up -d --build
|
||
```
|
||
|
||
确保 `datasets/adas` 指向数据湖（若缺失）：
|
||
|
||
```bash
|
||
ln -sfn ../../data/送标/adas datasets/adas
|
||
```
|
||
|
||
---
|
||
|
||
## 本机直跑（不用 Docker 跑 Platform）
|
||
|
||
```bash
|
||
pip install -r requirements.txt
|
||
bash scripts/init_after_clone.sh
|
||
bash scripts/run_local.sh
|
||
```
|
||
|
||
- Job 默认 `AS_JOB_EXECUTOR=thread`
|
||
- 无 PostgreSQL 时回退 SQLite
|
||
- 标注需 CVAT 可达
|
||
|
||
仅基础设施用 Docker：`docker compose up -d postgres redis cvat_traefik cvat_server ...`
|
||
|
||
---
|
||
|
||
## 认证（飞书 + PostgreSQL）
|
||
|
||
```bash
|
||
cp manifests/feishu.env.example manifests/feishu.env
|
||
```
|
||
|
||
| 角色 | 权限 |
|
||
|------|------|
|
||
| admin | 全部 + 用户管理 |
|
||
| reviewer | 审核 |
|
||
| engineer | 送标开标、任务分配、build/train |
|
||
| labeler | 我的标注、CVAT 保存 |
|
||
| viewer | 只读 |
|
||
|
||
---
|
||
|
||
## CLI 示例
|
||
|
||
```bash
|
||
python as.py pending
|
||
python as.py add dms dam --src /path/to/batch ...
|
||
python as.py train dms dam --track local
|
||
```
|
||
|
||
---
|
||
|
||
## 维护者
|
||
|
||
### 从 workspace 刷新内嵌代码
|
||
|
||
```bash
|
||
bash scripts/vendor_workspace.sh
|
||
git add algorithms/ datasets/ manifests/repo_layout.json
|
||
git commit -m "chore: refresh vendored algorithm scaffolds"
|
||
```
|
||
|
||
### 同步到训练服务器
|
||
|
||
```bash
|
||
bash scripts/sync_to_server.sh user@host:/opt/HSAP
|
||
```
|
||
|
||
### 推送到 Git 远端
|
||
|
||
```bash
|
||
git status # 确认无 .env、feishu.env、*.pt、送标图像
|
||
git push origin main
|
||
```
|
||
|
||
远端：`https://git.sanyele.com/ChengFang.LU/HSAP.git`
|
||
|
||
---
|
||
|
||
## 更多文档
|
||
|
||
| 文档 | 说明 |
|
||
|------|------|
|
||
| [docs/DEPLOY.md](docs/DEPLOY.md) | **新机器部署**（含 §9 环境差异清单） |
|
||
| [docs/HANDOVER.md](docs/HANDOVER.md) | 架构、API、运维、排障 |
|
||
| [docs/DEVELOPMENT_GUIDE.md](docs/DEVELOPMENT_GUIDE.md) | 开发指南 |
|
||
| [lake/lake_example/README.md](lake/lake_example/README.md) | 数据湖 inbox 示例 |
|
||
|
||
---
|
||
|
||
## Job 执行模式
|
||
|
||
| `AS_JOB_EXECUTOR` | 行为 |
|
||
|-------------------|------|
|
||
| `worker` | Docker 默认：Redis 队列 + worker |
|
||
| `thread` | 本机调试：API 进程内线程 |
|