Chengfang Lu
2d450715ff
新增 seed_lake_example.sh 并在 init_after_clone 中调用；更新 README/CLAUDE/DEPLOY 使接手人 clone 后即可走通送标样例流程。 Co-authored-by: Cursor <cursoragent@cursor.com>
195 lines
4.8 KiB
Markdown
195 lines
4.8 KiB
Markdown
# 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)。
|