766 lines
26 KiB
Markdown
766 lines
26 KiB
Markdown
# HSAP 项目交接文档
|
||
|
||
> **HSAP** — Huaxu Sentinel Active Safety Platform / 华胥 Sentinel 主动安全平台
|
||
>
|
||
> 最后更新：2026-06-12 | 交接人：chengfanglu
|
||
|
||
---
|
||
|
||
## 目录
|
||
|
||
1. [项目概述](#1-项目概述)
|
||
2. [技术栈](#2-技术栈)
|
||
3. [项目架构](#3-项目架构)
|
||
4. [环境与部署](#4-环境与部署)
|
||
5. [核心功能模块](#5-核心功能模块)
|
||
6. [API 概览](#6-api-概览)
|
||
7. [数据库设计](#7-数据库设计)
|
||
8. [配置与环境变量](#8-配置与环境变量)
|
||
9. [日常运维](#9-日常运维)
|
||
10. [当前完成状态与待办](#10-当前完成状态与待办)
|
||
11. [关键文件索引](#11-关键文件索引)
|
||
12. [常见问题排查](#12-常见问题排查)
|
||
|
||
---
|
||
|
||
## 1. 项目概述
|
||
|
||
### 1.1 定位
|
||
|
||
HSAP 是一个**卡车主动安全算法的迭代平台**，覆盖三大感知任务：
|
||
|
||
| 任务 | 算法 | 说明 |
|
||
|------|------|------|
|
||
| DMS (Driver Monitoring) | YOLOv6 | 驾驶员状态监测（疲劳、分心、打电话等） |
|
||
| Lane Detection | UFLD | 车道线检测 |
|
||
| ADAS Perception | — | 辅助驾驶感知（规划中） |
|
||
|
||
**HSAP 不是训练框架**，它是一个**协作编排平台**，覆盖从数据到模型的全生命周期：
|
||
|
||
```
|
||
数据采集 → 数据上载 → 扫描入库 → 送标(CVAT) → 标注审核 → 构建数据集 → 模型训练 → 评估 → 晋级上线
|
||
```
|
||
|
||
### 1.2 核心能力
|
||
|
||
- 🌐 **Web UI + API**：React 前端 + FastAPI 后端，四个功能模块
|
||
- 🏷️ **标注管理**：集成 CVAT 标注引擎，支持供应商回传
|
||
- 🔍 **审核治理**：所有写操作经过审核队列，RBAC 权限控制
|
||
- 🚛 **车队地图**：GPS/T-Box 轨迹追踪，模拟数据生成
|
||
- 🤖 **算法适配**：DMS YOLO 和 Lane UFLD 适配器，支持本地/平台双轨训练
|
||
- 📋 **飞书集成**：SSO 登录、Bitable 数据同步、消息通知
|
||
|
||
### 1.3 代码仓库
|
||
|
||
```
|
||
路径：/home/chengfanglu/DATA/HSAP
|
||
远端：git@github.com:Reuonny/HSAP.git （待确认）
|
||
分支：main
|
||
关键提交：
|
||
- e72bc06 feat: HSAP platform v2 — modular navigation, quality review, audit log, world model simulation
|
||
- 7c43b44 feat: initial HSAP platform
|
||
```
|
||
|
||
---
|
||
|
||
## 2. 技术栈
|
||
|
||
### 2.1 后端
|
||
|
||
| 技术 | 版本 | 用途 |
|
||
|------|------|------|
|
||
| Python | 3.11+ | 主要开发语言 |
|
||
| FastAPI | latest | Web 框架 |
|
||
| Uvicorn | latest | ASGI 服务器 |
|
||
| SQLAlchemy | 2.0 | ORM |
|
||
| PostgreSQL | 16 | 生产数据库 |
|
||
| SQLite | — | 本地开发备选（自动回退） |
|
||
| Redis | 7 | 任务队列 + 发布订阅 |
|
||
| python-jose | latest | JWT 令牌 |
|
||
| httpx | latest | HTTP 客户端 |
|
||
|
||
### 2.2 前端
|
||
|
||
| 技术 | 版本 | 用途 |
|
||
|------|------|------|
|
||
| React | 18 | UI 框架 |
|
||
| TypeScript | latest | 类型安全 |
|
||
| Vite | 5 | 构建工具 |
|
||
| Tailwind CSS | 3 | 样式框架 |
|
||
| React Router | v5 | 路由管理 |
|
||
|
||
### 2.3 基础设施
|
||
|
||
| 技术 | 版本 | 用途 |
|
||
|------|------|------|
|
||
| Docker Compose | v2 | 服务编排 |
|
||
| CVAT | latest | 标注引擎 |
|
||
| MinIO | latest | S3 兼容存储（可选） |
|
||
|
||
---
|
||
|
||
## 3. 项目架构
|
||
|
||
### 3.1 三层解耦设计
|
||
|
||
```
|
||
HSAP/
|
||
├── platform/ ← 编排层：API、鉴权、审核、任务队列、Web 前端
|
||
│ ├── as_platform/ # FastAPI 后端 Python 包
|
||
│ └── web/ # React + Vite + TypeScript 前端
|
||
├── algorithms/ ← 算法层：DMS YOLO / Lane UFLD 适配器
|
||
├── datasets/ ← 数据层：数据集包、标注配置、数据注册表
|
||
├── scripts/ ← 运维脚本（初始化、冒烟测试、同步、worker）
|
||
├── docs/ ← 文档（20+ 篇）
|
||
├── lake/ ← 数据湖暂存区
|
||
├── reports/ ← 报告、CSV、图表
|
||
├── manifests/ ← 运行时配置（feishu.env、DB、日志）
|
||
├── as.py ← CLI 入口
|
||
├── workflow.registry.yaml ← 中央注册表
|
||
├── docker-compose.yml ← Docker 服务编排
|
||
├── docker-compose.yml ← 平台 + CVAT 标注引擎（单文件）
|
||
├── Dockerfile ← Python 3.11-slim 镜像
|
||
└── Makefile ← 快捷命令
|
||
```
|
||
|
||
### 3.2 服务拓扑（Docker Compose）
|
||
|
||
```
|
||
┌──────────────────┐
|
||
│ hsap-platform │ ← FastAPI :8787 + 静态前端
|
||
│ (uvicorn) │
|
||
└───────┬──────────┘
|
||
│
|
||
┌─────────────┼─────────────┐
|
||
│ │ │
|
||
┌────────▼──────┐ ┌───▼────┐ ┌──────▼──────────┐
|
||
│ hsap-postgres │ │ hsap- │ │ hsap-worker │
|
||
│ PostgreSQL 16 │ │ redis │ │ (异步任务消费者) │
|
||
│ :5433(host) │ │ :6380 │ │ │
|
||
└───────────────┘ └────────┘ └─────────────────┘
|
||
|
||
可选服务 (profile: minio):
|
||
┌──────────┐ ┌──────────────┐
|
||
│ minio │ │ minio-init │
|
||
│ :9000 │ │ (初始化桶) │
|
||
└──────────┘ └──────────────┘
|
||
|
||
CVAT 服务（已合并入 docker-compose.yml）:
|
||
┌──────────────────────────────────────────┐
|
||
│ CVAT 标注引擎 (完整服务栈) │
|
||
│ cvat_server + cvat_ui + workers + ... │
|
||
│ 代理端口 :8080 │
|
||
└──────────────────────────────────────────┘
|
||
```
|
||
|
||
### 3.3 后端包结构 (`platform/as_platform/`)
|
||
|
||
```
|
||
as_platform/
|
||
├── api/ # FastAPI 路由 (auth, labeling, fleet, models, system, delivery, feishu)
|
||
├── auth/ # 飞书 OAuth、JWT 令牌、用户管理、RBAC 依赖
|
||
├── db/ # SQLAlchemy 引擎、数据模型（13+ 表）、初始化/迁移
|
||
├── data/ # 数据湖核心：采集管线、批次暂存、目录缓存
|
||
│ └── ingest/ # 采集适配器 (dms_coco, dms_yolo, dms_inbox_raw, lane_lines, lane_mask)
|
||
├── labeling/ # 标注服务：CVAT 客户端、批次暂存、供应商导入、进度追踪
|
||
├── audit/ # 审核队列和预览逻辑
|
||
├── jobs/ # 任务队列（Redis List / 内存）、执行器、飞书 Bitable 同步
|
||
├── deliveries/ # 交付/模型交接服务
|
||
├── fleet/ # 车队地图：GPS 追踪、T-Box 采集、模拟数据
|
||
├── training/ # 训练编排服务
|
||
├── agents/ # Agent 工作流图 (ingest_flow, labeling_flow, train_promote_flow)
|
||
├── integrations/ # 第三方集成：飞书 Bitable、飞书通知
|
||
├── redis/ # Redis 发布订阅总线
|
||
├── config.py # 中央配置（AS_* 环境变量）
|
||
└── sdk.py # Python SDK
|
||
```
|
||
|
||
### 3.4 前端模块结构 (`platform/web/src/`)
|
||
|
||
前端采用 **4 模块 + 侧边栏导航** 架构：
|
||
|
||
| 模块 | 路由前缀 | API 前缀 | 子页面 |
|
||
|------|---------|---------|--------|
|
||
| 🏷️ **数据送标** | `/labeling/*` | `/api/v1/labeling/*` | 数据上载、送标工作台、标注进度、导出与入库、批次台账、数据目录 |
|
||
| 🤖 **模型管理** | `/models/*` | `/api/v1/models/*` | 模型概览、训练提交、训练记录、评估管理、模型晋级 |
|
||
| 🚛 **车队管理** | `/fleet/*` | `/api/v1/fleet/*` | 车队总览、车辆管理、实时地图、行程记录、T-Box配置 |
|
||
| ⚙️ **系统管理** | `/system/*` | `/api/v1/system/*` | 审核队列、任务监控、执行日志、用户管理 |
|
||
|
||
**旧路由兼容重定向**（`/deliveries` → `/labeling/deliveries` 等）
|
||
|
||
---
|
||
|
||
## 4. 环境与部署
|
||
|
||
### 4.1 快速启动（Docker，推荐）
|
||
|
||
```bash
|
||
# 1. 首次克隆后初始化
|
||
bash scripts/init_after_clone.sh # 生成 .env 和 manifests/feishu.env
|
||
|
||
# 2. 启动全部服务
|
||
bash scripts/dev_up.sh # 或 make up
|
||
|
||
# 3. 启动平台 + CVAT 标注引擎
|
||
docker compose up -d
|
||
|
||
# 4. 验证
|
||
curl http://127.0.0.1:8787/api/v1/health
|
||
# 或 make health
|
||
```
|
||
|
||
### 4.2 本地开发（仅平台，基础设施用 Docker）
|
||
|
||
```bash
|
||
# 1. 启动基础设施
|
||
docker compose up -d postgres redis
|
||
|
||
# 2. 本地启动平台
|
||
pip install -r requirements.txt
|
||
bash scripts/run_local.sh
|
||
|
||
# 3. 或前端热重载开发
|
||
make dev # Vite :5173
|
||
```
|
||
|
||
### 4.3 Docker 服务端口映射
|
||
|
||
| 服务 | 容器内端口 | 宿主机端口 | 说明 |
|
||
|------|----------|-----------|------|
|
||
| platform | 8787 | 8787 | FastAPI + Web UI |
|
||
| postgres | 5432 | 5433 | PostgreSQL 16 |
|
||
| redis | 6379 | 6380 | Redis 7 |
|
||
| minio (可选) | 9000/9001 | 9000/9001 | S3 存储 |
|
||
| cvat (可选) | — | 8080 | CVAT 标注引擎 |
|
||
|
||
### 4.4 停止服务
|
||
|
||
```bash
|
||
make down # 停止全部（含 CVAT 和 dev profile）
|
||
```
|
||
|
||
---
|
||
|
||
## 5. 核心功能模块
|
||
|
||
### 5.1 数据送标（Labeling）
|
||
|
||
完整的数据送标工作流：
|
||
|
||
```
|
||
数据上载 → 送标工作台（扫描入库） → 创建标注任务(CVAT) → 标注进度追踪 → 导出与入库 → 批次台账
|
||
```
|
||
|
||
**关键文件：**
|
||
- `platform/as_platform/labeling/` — 标注服务后端
|
||
- `platform/as_platform/data/ingest/` — 数据采集适配器
|
||
- `platform/web/src/modules/labeling/` — 前端页面
|
||
- `docs/LABELING_SOP.md` — 标准操作流程
|
||
- `docs/LANE_LABELING_PLAN.md` — 车道线标注方案
|
||
- `docs/LABEL_STUDIO_UI_MIGRATION.md` — UI 迁移记录
|
||
|
||
### 5.2 模型管理（Models）
|
||
|
||
模型全生命周期管理：
|
||
|
||
```
|
||
数据集版本快照 → 训练提交 → 训练记录追踪 → 评估管理(mAP对比) → 模型晋级
|
||
```
|
||
|
||
**关键文件：**
|
||
- `platform/as_platform/api/models_routes.py` — 模型 API
|
||
- `platform/as_platform/training/` — 训练编排
|
||
- `platform/web/src/modules/models/` — 前端页面
|
||
|
||
### 5.3 车队管理（Fleet）
|
||
|
||
车队 GPS 追踪与数据采集管理：
|
||
|
||
- 车辆注册与管理
|
||
- 实时地图展示（高德/OSM）
|
||
- T-Box 设备数据采集
|
||
- 行程记录与里程碑
|
||
- 模拟 GPS 数据生成（开发用）
|
||
|
||
**关键文件：**
|
||
- `platform/as_platform/fleet/` — 车队服务后端
|
||
- `platform/web/src/modules/fleet/` — 前端页面
|
||
- `docs/FLEET_MAP.md` — 车队地图文档
|
||
|
||
### 5.4 系统管理（System）
|
||
|
||
平台治理：
|
||
|
||
- **审核队列**：所有写操作（构建/训练/晋级/注册）需要审核，支持批量操作
|
||
- **任务监控**：异步任务状态追踪，自动刷新
|
||
- **执行日志**：Agent 工作流 Trace 查看
|
||
- **用户管理**：飞书用户信息、角色分配、分页
|
||
|
||
### 5.5 飞书集成
|
||
|
||
| 功能 | 状态 | 说明 |
|
||
|------|------|------|
|
||
| SSO 登录 | ✅ 已实现 | OAuth2 认证，JWT 令牌 |
|
||
| Bitable 同步 | ✅ 已实现 | HSAP 数据 ↔ 飞书多维表格 |
|
||
| 审核通知 | ❌ 待实现 | 审核提交/结果通知到飞书群 |
|
||
| 角色同步 | ✅ 已实现 | 按飞书部门自动分配角色 |
|
||
|
||
**关键文件：**
|
||
- `platform/as_platform/auth/` — 飞书 OAuth + JWT
|
||
- `platform/as_platform/integrations/feishu_bitable.py` — Bitable 集成
|
||
- `platform/as_platform/integrations/feishu_notify.py` — 通知（待接入）
|
||
- `docs/FEISHU_BITABLE_OPS.md` — Bitable 运维文档
|
||
- `docs/FEISHU_DEV_HANDOFF.md` — 飞书开发交接
|
||
|
||
### 5.6 CLI 工具 (`as.py`)
|
||
|
||
```bash
|
||
python as.py status # 查看工作区和活动数据包
|
||
python as.py pending # 查看待审核项
|
||
python as.py add dms dam --src ... # 注册 DMS 批次
|
||
python as.py build dms dam # 从活动数据包构建数据集
|
||
python as.py train dms dam --track local # 本地训练
|
||
python as.py train dms dam --track platform # 平台训练（需审核）
|
||
```
|
||
|
||
### 5.7 世界模型仿真（新功能）
|
||
|
||
用于生成合成训练数据的仿真 API，已实现基础框架：
|
||
|
||
**API 端点：**
|
||
- `POST /api/v1/simulate/generate` — 提交生成任务
|
||
- `GET /api/v1/simulate/jobs` — 查看生成历史
|
||
- `GET /api/v1/simulate/jobs/{id}/images` — 预览生成结果
|
||
- `POST /api/v1/simulate/jobs/{id}/ingest` — 入库
|
||
|
||
**视频预处理管线**：设计了但尚未完全实现。包括去噪（非局部均值/双边滤波）、去重（SSIM/感知哈希）、异常过滤（全黑/模糊/过曝检测）、关键帧提取。
|
||
|
||
---
|
||
|
||
## 6. API 概览
|
||
|
||
### 6.1 主要路由
|
||
|
||
| 路由前缀 | 文件 | 关键端点 |
|
||
|---------|------|---------|
|
||
| `/api/v1/auth` | `auth_routes.py` | 飞书登录/回调、用户管理、角色分配 |
|
||
| `/api/v1/labeling` | `labeling_routes.py` | 标注活动管理、扫描入库、进度、供应商导入 |
|
||
| `/api/v1/models` | `models_routes.py` | 模型生命周期、训练、评估、晋级 |
|
||
| `/api/v1/fleet` | `fleet_routes.py` | 车辆、轨迹、行程、T-Box |
|
||
| `/api/v1/system` | `system_routes.py` | 审核队列、任务监控、执行日志 |
|
||
| `/api/v1/delivery` | `delivery_routes.py` | 批次交付、Bitable 集成 |
|
||
| `/api/v1/feishu` | `feishu_routes.py` | Bitable Webhook 回调 |
|
||
| `/api/v1/` (根) | `server.py` | health, dashboard, catalog, approvals, simulate, agents |
|
||
|
||
### 6.2 核心端点速查
|
||
|
||
```bash
|
||
# 健康检查
|
||
GET /api/v1/health
|
||
|
||
# 首页仪表盘数据
|
||
GET /api/v1/dashboard
|
||
|
||
# 数据目录
|
||
GET /api/v1/catalog
|
||
POST /api/v1/catalog
|
||
|
||
# 审核流程
|
||
GET /api/v1/approvals
|
||
POST /api/v1/approvals/{id}/approve
|
||
POST /api/v1/approvals/{id}/reject
|
||
GET /api/v1/approvals/{id}/preview
|
||
|
||
# 任务队列
|
||
GET /api/v1/jobs
|
||
POST /api/v1/jobs
|
||
|
||
# 文件上传
|
||
POST /api/v1/data/upload/file
|
||
|
||
# Agent 工作流
|
||
POST /api/v1/agents/invoke
|
||
|
||
# Swagger 文档
|
||
GET /docs # FastAPI 自动生成的交互式 API 文档
|
||
```
|
||
|
||
---
|
||
|
||
## 7. 数据库设计
|
||
|
||
### 7.1 核心表（13+ 张）
|
||
|
||
| 表名 | 说明 | 关键字段 |
|
||
|------|------|---------|
|
||
| `users` | 用户账户 | feishu_open_id, name, email, department |
|
||
| `roles` | RBAC 角色 | admin, reviewer, engineer, labeler, viewer |
|
||
| `permissions` | 细粒度权限 | read:catalog, write:approval_review 等 13 个 |
|
||
| `user_roles` | 用户-角色 M2M | — |
|
||
| `role_permissions` | 角色-权限 M2M | — |
|
||
| `approvals` | 审核队列 | action, params, status, reviewed_by |
|
||
| `jobs` | 任务队列 | action, status, approval_id, params, result |
|
||
| `dataset_candidates` | 数据集候选 | project, task, mode, status, format |
|
||
| `batch_deliveries` | 批次交付 | project, task, batch_name, status |
|
||
| `feishu_bitable_links` | 飞书 Bitable 映射 | hsap_record_id, bitable_record_id |
|
||
| `fleet_vehicles` | 车队车辆 | plate_no, tbox_device_id, GPS 坐标 |
|
||
| `fleet_collection_runs` | 采集行程 | vehicle_id, run_no, mileage |
|
||
| `fleet_track_points` | GPS 轨迹点 | lat, lng, speed, heading |
|
||
| `fleet_run_milestones` | 行程里程碑 | 途经点/事件标记 |
|
||
| `labeling_campaigns` | 标注活动 | project, task, batch, status, CVAT 引用 |
|
||
| `labeling_task_assignments` | 标注任务分配 | 每张图片的标注员分配 |
|
||
| `labeling_export_jobs` | 导出/预测任务 | 导出参数、结果路径 |
|
||
|
||
### 7.2 数据库模式
|
||
|
||
- **生产**：PostgreSQL 16，通过 Docker Compose 启动
|
||
- **本地开发**：自动回退到 SQLite (`manifests/platform.db`)
|
||
- **迁移**：`scripts/db_migrate_from_sqlite.py` 支持 SQLite → PostgreSQL 迁移
|
||
|
||
### 7.3 权限体系
|
||
|
||
**5 个默认角色** + **13 个细粒度权限**：
|
||
|
||
```
|
||
admin → 全部权限
|
||
reviewer → read:catalog + write:approval_review
|
||
engineer → read:catalog + write:dataset + write:training + write:model
|
||
labeler → read:catalog + write:labeling
|
||
viewer → read:catalog
|
||
```
|
||
|
||
飞书部门 ID 自动映射到角色（在 `db/init_db.py` 中配置）。
|
||
|
||
---
|
||
|
||
## 8. 配置与环境变量
|
||
|
||
### 8.1 核心环境变量（`AS_*` 前缀）
|
||
|
||
#### 数据库
|
||
| 变量 | 默认值 | 说明 |
|
||
|------|--------|------|
|
||
| `AS_DB_HOST` | `127.0.0.1` | PostgreSQL 主机 |
|
||
| `AS_DB_PORT` | `5432` | PostgreSQL 端口 |
|
||
| `AS_DB_USER` | `as_platform` | 数据库用户 |
|
||
| `AS_DB_PASSWORD` | `as_platform` | 数据库密码 |
|
||
| `AS_DB_NAME` | `as_platform` | 数据库名 |
|
||
| `AS_DATABASE_URL` | (自动构建) | 完整连接 URL |
|
||
|
||
#### Redis / 任务队列
|
||
| 变量 | 默认值 | 说明 |
|
||
|------|--------|------|
|
||
| `AS_REDIS_URL` | `redis://127.0.0.1:6379/0` | Redis 连接 |
|
||
| `AS_JOB_EXECUTOR` | `thread` | 任务执行模式：`thread` 或 `worker` |
|
||
| `AS_JOB_QUEUE_KEY` | `as:job_queue` | Redis 队列键名 |
|
||
|
||
#### 认证
|
||
| 变量 | 默认值 | 说明 |
|
||
|------|--------|------|
|
||
| `AS_JWT_SECRET` | (必须修改) | JWT 签名密钥 |
|
||
| `AS_JWT_EXPIRE_HOURS` | `168` | 令牌有效期 |
|
||
| `AS_DEV_AUTH` | `false` | 绕过飞书登录 |
|
||
| `AS_FORCE_DEV_AUTH` | `false` | 强制开发认证 |
|
||
| `FEISHU_APP_ID` | (空) | 飞书应用 ID |
|
||
| `FEISHU_APP_SECRET` | (空) | 飞书应用密钥 |
|
||
|
||
#### 飞书 Bitable
|
||
| 变量 | 默认值 | 说明 |
|
||
|------|--------|------|
|
||
| `FEISHU_BITABLE_APP_TOKEN` | (空) | Bitable App Token |
|
||
| `FEISHU_BITABLE_TABLE_ID` | (空) | Bitable 表 ID |
|
||
| `FEISHU_BITABLE_SYNC_ENABLED` | `false` | 启用定期同步 |
|
||
| `FEISHU_BITABLE_SYNC_INTERVAL_SEC` | `120` | 同步间隔 |
|
||
|
||
#### 工作区 / 数据路径
|
||
| 变量 | 默认值 | 说明 |
|
||
|------|--------|------|
|
||
| `AS_WORKSPACE_ROOT` | (自动检测) | 外部数据工作区路径 |
|
||
| `AS_DATA_LAKE_ROOT` | (自动检测) | 数据湖根路径 |
|
||
|
||
#### 车队
|
||
| 变量 | 默认值 | 说明 |
|
||
|------|--------|------|
|
||
| `AS_FLEET_MAP_ENABLED` | `1` | 启用车队地图 API |
|
||
| `AS_FLEET_MOCK_SEED` | `1` | 种子演示车辆 |
|
||
| `AS_FLEET_MOCK_SIMULATE` | `1` | 自动模拟 GPS |
|
||
| `AS_FLEET_SIM_INTERVAL_SEC` | `8` | 模拟间隔 |
|
||
|
||
### 8.2 敏感配置文件（Git 忽略）
|
||
|
||
- **`.env`** — Docker Compose 环境变量
|
||
- **`manifests/feishu.env`** — 飞书凭证（`FEISHU_APP_ID`, `FEISHU_APP_SECRET` 等）
|
||
|
||
---
|
||
|
||
## 9. 日常运维
|
||
|
||
### 9.1 常用命令速查
|
||
|
||
```bash
|
||
# === 服务管理 ===
|
||
make up # 启动全部服务
|
||
make down # 停止全部服务
|
||
make ps # 查看容器状态
|
||
make logs # 查看 platform + worker 日志
|
||
make health # 检查 API 健康状态
|
||
make build # 重新构建镜像
|
||
|
||
# === 开发调试 ===
|
||
make dev # 启动前端热重载开发 (:5173)
|
||
|
||
# === 查看日志 ===
|
||
docker compose logs -f platform # 后端日志
|
||
docker compose logs -f worker # Worker 日志
|
||
docker compose logs -f postgres # 数据库日志
|
||
|
||
# === 数据库操作 ===
|
||
docker compose exec postgres psql -U as_platform -d as_platform # 进入 PostgreSQL
|
||
|
||
# === API 测试 ===
|
||
curl http://127.0.0.1:8787/api/v1/health
|
||
curl http://127.0.0.1:8787/docs # Swagger 交互文档
|
||
|
||
# === CLI ===
|
||
python as.py status # 查看工作区状态
|
||
python as.py pending # 查看待审核项
|
||
```
|
||
|
||
### 9.2 数据备份
|
||
|
||
```bash
|
||
# PostgreSQL 备份
|
||
docker compose exec postgres pg_dump -U as_platform as_platform > backup_$(date +%Y%m%d).sql
|
||
|
||
# PostgreSQL 恢复
|
||
docker compose exec -T postgres psql -U as_platform as_platform < backup_20260612.sql
|
||
```
|
||
|
||
### 9.3 冒烟测试
|
||
|
||
```bash
|
||
bash scripts/smoke_api.sh # API 基础功能测试
|
||
bash scripts/smoke_labeling.sh # 标注流程测试
|
||
bash scripts/smoke_manifest_alignment.sh # 配置一致性检查
|
||
```
|
||
|
||
### 9.4 环境重置
|
||
|
||
```bash
|
||
# 完全重置（清除所有数据）
|
||
docker compose down -v # -v 删除 volumes（数据库+Redis 数据）
|
||
|
||
# 仅重置标注状态
|
||
bash scripts/reset_labeling.sh
|
||
```
|
||
|
||
---
|
||
|
||
## 10. 当前完成状态与待办
|
||
|
||
### 10.1 已完成功能 ✅
|
||
|
||
| 模块 | 页面 | 状态 |
|
||
|------|------|:--:|
|
||
| 数据送标 | 送标工作台（扫描入库） | ✅ |
|
||
| 数据送标 | 标注进度（Campaigns） | ✅ |
|
||
| 数据送标 | 导出与入库（供应商回传） | ✅ |
|
||
| 数据送标 | 批次台账（Deliveries） | ✅ |
|
||
| 数据送标 | 数据目录（可视化） | ✅ |
|
||
| 模型管理 | 模型概览（KPI 卡片） | ✅ |
|
||
| 模型管理 | 数据集版本（自动快照+diff） | ✅ |
|
||
| 模型管理 | 训练提交（表单校验） | ✅ |
|
||
| 模型管理 | 训练记录（分页+展开详情） | ✅ |
|
||
| 模型管理 | 评估管理（mAP 对比图） | ✅ |
|
||
| 模型管理 | 模型晋级（版本选择+历史） | ✅ |
|
||
| 车队管理 | 总览 / 车辆 / 地图 / 行程 / T-Box | ✅ |
|
||
| 系统管理 | 审核队列（批量操作+驳回分类） | ✅ |
|
||
| 系统管理 | 任务监控（自动刷新） | ✅ |
|
||
| 系统管理 | 执行日志（Trace 查看） | ✅ |
|
||
| 系统管理 | 用户管理（飞书信息+分页） | ✅ |
|
||
| 世界模型 | 仿真工坊（生成合成数据） | ✅ |
|
||
|
||
### 10.2 待开发功能 ❌
|
||
|
||
| 优先级 | 功能 | 预估工时 | 说明 |
|
||
|:--:|------|:--:|------|
|
||
| **P0** | 首页仪表盘 | 1天 | KPI 卡片、审核待办、车队实时卡片、最近活动时间线 |
|
||
| **P0** | 飞书审核通知 | 0.5天 | 审核提交/通过/驳回时飞书群通知，复用已有 `integrations/feishu_notify.py` |
|
||
| **P1** | 入库基础质检 | 1天 | 图片可读性、分辨率分布、标注格式校验、越界检测 |
|
||
| **P1** | 操作审计日志 | 0.5天 | 新增 `OperationLog` 表，埋点关键操作，前端时间线页面 |
|
||
| **P2** | 标注质量抽检 | 1.5天 | 随机抽取标注结果审核，统计标注员准确率 |
|
||
| **P2** | 模型预标 | 2天 | 已有模型推理 → 预标注 → 标注员修正 |
|
||
| **P3** | 模型部署追踪 | — | 实验→候选→生产→退役 状态追踪 |
|
||
| **P3** | 采集任务管理 | — | 创建采集任务、指派车辆、回传追踪 |
|
||
| **—** | 视频预处理管线 | — | 去噪/去重/异常过滤/关键帧提取，代码框架已设计 |
|
||
|
||
> 详细开发计划见 `docs/DEVELOPMENT_ROADMAP.md` 和 `CLAUDE.md` 末尾。
|
||
|
||
---
|
||
|
||
## 11. 关键文件索引
|
||
|
||
### 11.1 核心代码
|
||
|
||
| 文件/目录 | 说明 |
|
||
|----------|------|
|
||
| `platform/as_platform/api/server.py` | FastAPI 主入口，挂载所有路由 |
|
||
| `platform/as_platform/config.py` | 中央配置（读环境变量） |
|
||
| `platform/as_platform/sdk.py` | Python SDK |
|
||
| `platform/as_platform/db/models.py` | 全部数据模型定义 |
|
||
| `platform/as_platform/db/init_db.py` | 数据库初始化 + 种子数据 |
|
||
| `as.py` | CLI 入口 |
|
||
| `workflow.registry.yaml` | 中央注册表（项目/数据包/规则） |
|
||
| `algorithms/registry.yaml` | 算法注册表 |
|
||
| `scripts/worker.py` | 异步任务 Worker |
|
||
|
||
### 11.2 配置文件
|
||
|
||
| 文件 | 说明 |
|
||
|------|------|
|
||
| `docker-compose.yml` | Docker 服务编排 |
|
||
| `docker-compose.yml` | 平台 + CVAT 全套编排 |
|
||
| `Dockerfile` | 镜像构建 |
|
||
| `Makefile` | 运维快捷命令 |
|
||
| `.env` | Docker Compose 环境变量（Git 忽略） |
|
||
| `manifests/feishu.env` | 飞书凭证（Git 忽略） |
|
||
| `requirements.txt` | Python 依赖 |
|
||
|
||
### 11.3 文档
|
||
|
||
| 文档 | 说明 |
|
||
|------|------|
|
||
| `CLAUDE.md` | AI 助手指南（项目最详细的文档） |
|
||
| `docs/DEVELOPMENT_GUIDE.md` | 架构、约定、设计决策 |
|
||
| `docs/DEVELOPMENT_ROADMAP.md` | Q2 2026 开发路线图 |
|
||
| `docs/DATA_LAKE_CHECKLIST.md` | 数据湖操作清单 |
|
||
| `docs/LABELING_SOP.md` | 标注标准操作流程 |
|
||
| `docs/FLEET_MAP.md` | 车队地图文档 |
|
||
| `docs/FEISHU_BITABLE_OPS.md` | 飞书 Bitable 运维 |
|
||
| `docs/BATCH_DELIVERY_OPS.md` | 批次交付操作 |
|
||
| `docs/MINIO_STAGING.md` | MinIO S3 暂存配置 |
|
||
| `docs/PILOT_BATCH.md` | 试点批次流程 |
|
||
| `docs/LANE_LABELING_PLAN.md` | 车道线标注方案 |
|
||
| `docs/GIT_PUSH.md` | Git 推送清单 |
|
||
| `docs/HANDOVER.md` | 👈 **本文档** |
|
||
|
||
---
|
||
|
||
## 12. 常见问题排查
|
||
|
||
### 12.1 服务启动失败
|
||
|
||
```bash
|
||
# 检查容器状态
|
||
docker compose ps
|
||
|
||
# 查看具体服务日志
|
||
docker compose logs platform
|
||
docker compose logs postgres
|
||
docker compose logs redis
|
||
|
||
# 常见原因：
|
||
# 1. 端口冲突 → 修改 .env 中的端口映射
|
||
# 2. PostgreSQL 未就绪 → 等待 healthcheck 通过
|
||
# 3. 飞书凭证缺失 → 检查 manifests/feishu.env
|
||
```
|
||
|
||
### 12.2 数据库连接问题
|
||
|
||
```bash
|
||
# 测试 PostgreSQL 连接
|
||
docker compose exec postgres pg_isready -U as_platform -d as_platform
|
||
|
||
# 进入数据库查看
|
||
docker compose exec postgres psql -U as_platform -d as_platform
|
||
|
||
# 本地开发时 SQLite 自动回退，检查：
|
||
ls -la manifests/platform.db
|
||
```
|
||
|
||
### 12.3 飞书登录问题
|
||
|
||
```bash
|
||
# 确认飞书凭证已配置
|
||
cat manifests/feishu.env
|
||
|
||
# 开发模式绕过飞书登录
|
||
export AS_DEV_AUTH=true
|
||
export AS_FORCE_DEV_AUTH=true
|
||
|
||
# 检查回调 URI 配置
|
||
# 飞书应用控制台 → 安全设置 → 重定向 URL
|
||
```
|
||
|
||
### 12.4 标注/CVAT 问题
|
||
|
||
```bash
|
||
# 确认 CVAT 服务状态
|
||
docker compose ps
|
||
|
||
# CVAT 公开地址
|
||
echo $CVAT_PUBLIC_URL # 默认 http://127.0.0.1:8080
|
||
|
||
# 检查 CVAT 日志
|
||
docker compose logs cvat_server
|
||
```
|
||
|
||
### 12.5 任务队列积压
|
||
|
||
```bash
|
||
# 检查 Worker 是否在运行
|
||
docker compose ps worker
|
||
|
||
# 查看 Worker 日志
|
||
docker compose logs worker
|
||
|
||
# 检查 Redis 队列长度
|
||
docker compose exec redis redis-cli LLEN as:job_queue
|
||
|
||
# 模式确认：线程模式不需要 worker，Redis 模式需要 worker
|
||
# AS_JOB_EXECUTOR=worker → 必须有 worker 容器
|
||
# AS_JOB_EXECUTOR=thread → 不需要 worker（开发环境）
|
||
```
|
||
|
||
### 12.6 前端构建/热重载
|
||
|
||
```bash
|
||
# 前端代码在 platform/web/
|
||
cd platform/web/
|
||
|
||
# 安装依赖
|
||
npm install
|
||
|
||
# 开发模式（热重载）
|
||
npm run dev # Vite :5173
|
||
|
||
# 生产构建
|
||
bash scripts/build_web.sh
|
||
```
|
||
|
||
---
|
||
|
||
## 附录
|
||
|
||
### A. Git 忽略规则（不要提交这些）
|
||
|
||
- `.env`、`manifests/feishu.env`（凭证）
|
||
- `*.pt`、`*.pth`、`*.onnx`、`*.rknn`（模型权重）
|
||
- 图片/视频数据集文件
|
||
- `node_modules/`
|
||
- `__pycache__/`、`*.pyc`
|
||
- `manifests/platform.db`（SQLite 数据库）
|
||
- `reports/`（报告输出）
|
||
|
||
### B. Python 路径约定
|
||
|
||
- 所有代码从仓库根目录运行，`PYTHONPATH=platform`
|
||
- Python 包名为 `as_platform`（历史命名保留）
|
||
|
||
### C. 外部依赖
|
||
|
||
- 飞书应用（SSO + Bitable）
|
||
- CVAT 标注引擎（可选，通过 Docker Compose 集成）
|
||
- 训练服务器（通过 `scripts/sync_to_server.sh` 同步）
|
||
- 外部工作区（大文件存储，Docker 中挂载到 `/data/workspace`）
|