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

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。

---

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 部署前自检（复制执行）

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 权限均在接手人本机配置即可跑通。