Files

Chengfang Lu 2d450715ff docs: 部署交接文档、lake_example 自动植入与 CLAUDE 快速部署指南

新增 seed_lake_example.sh 并在 init_after_clone 中调用；更新 README/CLAUDE/DEPLOY
使接手人 clone 后即可走通送标样例流程。

Co-authored-by: Cursor <cursoragent@cursor.com>

2026-06-16 17:36:37 +08:00

4.8 KiB

Raw Blame History

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

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

1. 环境要求

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

Ubuntu 示例：

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

2. 克隆与初始化

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 scripts/seed_lake_example.sh

推荐验收批次：

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

平台启动后：批次台账 → 扫描数据湖 → 登记 → 送标工作台开标。详见 README 接手流程。

3. 必改配置

3.1 `.env`（Docker Compose）

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`（认证）

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

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

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

4. 数据目录布局

推荐与仓库平级：

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 示例：

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 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

健康检查：

make health
docker compose ps

6. 前端更新

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

bash scripts/build_web.sh
docker compose restart platform

7. 常用运维

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

可选 MinIO 暂存：

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。

4.8 KiB Raw Blame History Unescape Escape