提交 58b7a2a7 authored 作者: caifuming's avatar caifuming

5/28号 写了一部分后端

上级 f7ad0a94
# ===========================================
# Application Settings
# ===========================================
APP_NAME=PLabel
APP_ENV=development # development, staging, production
APP_DEBUG=true
APP_SECRET_KEY=change-this-to-a-super-secret-key-in-production
# Server
HOST=0.0.0.0
PORT=8000
# ===========================================
# Database Settings
# ===========================================
# PostgreSQL connection string format:
# postgresql://username:password@host:port/database
DATABASE_URL=postgresql://plabel:plabel123@localhost:5432/plabel
# For async driver (recommended)
ASYNC_DATABASE_URL=postgresql+asyncpg://plabel:plabel123@localhost:5432/plabel
# ===========================================
# Redis Settings
# ===========================================
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_DB=0
REDIS_PASSWORD=
# Redis connection URL
REDIS_URL=redis://localhost:6379/0
# Celery broker URL
CELERY_BROKER_URL=redis://localhost:6379/1
CELERY_RESULT_BACKEND=redis://localhost:6379/2
# ===========================================
# MinIO / S3 Settings
# ===========================================
# MinIO Endpoint (for local development)
MINIO_ENDPOINT=localhost:9009
MINIO_ACCESS_KEY=plabel_access_key
MINIO_SECRET_KEY=plabel_secret_key_change_this
MINIO_BUCKET=plabel-bucket
MINIO_SECURE=false # true for HTTPS, false for HTTP
MINIO_REGION=us-east-1
# AWS S3 (alternative to MinIO)
# AWS_ACCESS_KEY_ID=your_access_key
# AWS_SECRET_ACCESS_KEY=your_secret_key
# AWS_REGION=us-east-1
# S3_BUCKET=your-bucket-name
# ===========================================
# JWT Settings
# ===========================================
JWT_SECRET_KEY=your-super-secret-jwt-key-change-this-in-production
JWT_ALGORITHM=HS256
ACCESS_TOKEN_EXPIRE_MINUTES=1440 # 24 hours
REFRESH_TOKEN_EXPIRE_DAYS=7
# ===========================================
# File Upload Settings
# ===========================================
# Max file sizes in MB
MAX_IMAGE_SIZE_MB=50
MAX_VIDEO_SIZE_MB=500
MAX_AUDIO_SIZE_MB=100
MAX_TEXT_SIZE_MB=10
# Allowed file types (comma-separated MIME types)
ALLOWED_IMAGE_TYPES=image/jpeg,image/png,image/webp,image/bmp
ALLOWED_VIDEO_TYPES=video/mp4,video/webm,video/quicktime
ALLOWED_AUDIO_TYPES=audio/mpeg,audio/wav,audio/ogg,audio/m4a
ALLOWED_TEXT_TYPES=text/plain,text/markdown,application/json
# Upload directory
UPLOAD_DIR=./data/uploads
THUMBNAIL_DIR=./data/thumbnails
EXPORT_DIR=./data/exports
# ===========================================
# AI Model Settings
# ===========================================
# Device for AI inference
AI_MODEL_DEVICE=cpu # cpu or cuda
# Model cache directory
AI_MODEL_CACHE_DIR=./models
# GPU device ID (if using multiple GPUs)
CUDA_VISIBLE_DEVICES=0
# ===========================================
# Celery Settings
# ===========================================
# Task queue names
CELERY_TASK_QUEUE_DEFAULT=default
CELERY_TASK_QUEUE_GPU=gpu_tasks
CELERY_TASK_QUEUE_CPU=cpu_tasks
# Task settings
CELERY_TASK_ACKS_LATE=true
CELERY_TASK_REJECT_ON_WORKER_LOST=true
CELERY_WORKER_PREFETCH_MULTIPLIER=1
# ===========================================
# CORS Settings
# ===========================================
# Comma-separated list of allowed origins
CORS_ORIGINS=http://localhost:3000,http://localhost:8000,http://127.0.0.1:3000,http://127.0.0.1:8000
# ===========================================
# Email Settings (Optional)
# ===========================================
# SMTP configuration for sending emails
SMTP_HOST=smtp.example.com
SMTP_PORT=587
SMTP_USER=your_email@example.com
SMTP_PASSWORD=your_email_password
SMTP_FROM=PLabel <noreply@plabel.com>
SMTP_USE_TLS=true
# ===========================================
# Logging Settings
# ===========================================
LOG_LEVEL=INFO # DEBUG, INFO, WARNING, ERROR, CRITICAL
LOG_FILE=./logs/app.log
LOG_ROTATION=100 MB
LOG_RETENTION=30 days
# Byte-compiled / optimized
__pycache__/
*.py[cod]
*.so
.Python
venv/
.venv/
.env
.env.local
# Database
*.db
*.sqlite
# Logs & Data
logs/
data/uploads/
data/thumbnails/
data/exports/
*.log
# AI Models (large files, download on demand)
models/vision/
models/audio/
models/text/
# IDE
.idea/
.vscode/
*.swp
*.swo
*.swn
# Testing
.pytest_cache/
.coverage
htmlcov/
*.cover
# Docker
.docker/
# OS
.DS_Store
Thumbs.db
# Secrets (never commit)
*.pem
*.key
credentials.json
secrets/
FROM python:3.11-slim
WORKDIR /app
# Install system dependencies
RUN apt-get update && apt-get install -y --no-install-recommends \
build-essential libpq-dev libffi-dev libssl-dev ffmpeg \
libsm6 libxext6 libxrender-dev libgomp1 git wget curl \
&& rm -rf /var/lib/apt/lists/*
# Copy requirements first for better caching
COPY requirements.txt requirements-ai.txt* /app/
RUN pip install --no-cache-dir -r requirements.txt
# Copy application code
COPY . /app/
# Create necessary directories
RUN mkdir -p /app/logs /app/data/uploads /app/data/thumbnails /app/data/exports
# Expose port
EXPOSE 8000
# Run the application
CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]
FROM nvidia/cuda:12.1.0-runtime-ubuntu22.04
WORKDIR /app
ENV DEBIAN_FRONTEND=noninteractive
RUN apt-get update && apt-get install -y --no-install-recommends \
python3.11 python3.11-dev python3-pip \
build-essential libpq-dev libffi-dev libssl-dev ffmpeg \
libsm6 libxext6 libxrender-dev libgomp1 git wget curl \
&& rm -rf /var/lib/apt/lists/*
COPY requirements-ai.txt /app/
RUN pip install --no-cache-dir -r requirements-ai.txt
COPY . /app/
RUN mkdir -p /app/logs /app/data/uploads /app/data/thumbnails /app/data/exports /app/models
EXPOSE 8000
CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]
.PHONY: help install dev run test test-cov lint db-migrate db-seed docker-up docker-down clean
help:
@echo "PLabel Backend - Available commands:"
@echo " make install - Install dependencies"
@echo " make dev - Run development server"
@echo " make test - Run tests"
@echo " make test-cov - Run tests with coverage"
@echo " make lint - Run linter"
@echo " make db-migrate - Run database migrations"
@echo " make db-seed - Seed database"
@echo " make docker-up - Start all services"
@echo " make docker-down - Stop all services"
@echo " make clean - Clean cache files"
install:
pip install -r requirements.txt
pip install -r requirements-ai.txt
dev:
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
test:
pytest
test-cov:
pytest --cov=app tests/ --cov-report=html
lint:
ruff check app/
db-migrate:
alembic upgrade head
db-seed:
python -m app.utils.seed_data
docker-up:
docker-compose up -d
docker-down:
docker-compose down
clean:
find . -type d -name __pycache__ -exec rm -rf {} +
find . -type f -name "*.pyc" -delete
rm -rf .pytest_cache .coverage htmlcov
# PLabel Backend - FastAPI Backend for Data Annotation Platform
## 环境要求
- Python 3.10+
- PostgreSQL 15+
- Redis 7+
- Docker & Docker Compose (推荐)
- NVIDIA GPU (可选,用于 AI 推理)
## 快速开始
### 方式一: Docker 部署 (推荐)
```bash
# 复制环境变量配置
cp .env.example .env
# 启动所有服务
docker-compose up -d
# 查看日志
docker-compose logs -f backend
# 停止服务
docker-compose down
```
### 方式二: 本地开发
```bash
# 1. 创建虚拟环境
python -m venv venv
source venv/bin/activate # Linux/Mac
# 或
.\venv\Scripts\activate # Windows
# 2. 安装依赖
pip install -r requirements.txt
# 3. 配置环境变量
cp .env.example .env
# 编辑 .env 文件,配置数据库连接等
# 4. 初始化数据库
alembic upgrade head
# 5. 创建超级用户
python -m app.utils.create_superuser
# 6. 启动开发服务器
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
```
## 环境变量配置
请参考 `.env.example` 文件配置以下环境变量:
- `DATABASE_URL` - PostgreSQL 连接字符串
- `REDIS_URL` - Redis 连接字符串
- `MINIO_ENDPOINT` - MinIO 服务地址
- `MINIO_ACCESS_KEY` / `MINIO_SECRET_KEY` - MinIO 凭证
- `JWT_SECRET_KEY` - JWT 密钥
## API 文档
启动服务后访问:
- Swagger UI: http://localhost:8000/docs
- ReDoc: http://localhost:8000/redoc
- OpenAPI JSON: http://localhost:8000/openapi.json
## 项目结构
```
backend/
├── app/
│ ├── api/v1/ # API 路由
│ ├── core/ # 核心配置
│ ├── models/ # SQLAlchemy 模型
│ ├── schemas/ # Pydantic schemas
│ ├── services/ # 业务逻辑
│ └── utils/ # 工具函数
├── alembic/ # 数据库迁移
├── tests/ # 测试文件
├── models/ # AI 模型文件
├── data/ # 上传数据目录
├── Dockerfile
├── docker-compose.yml
└── requirements.txt
```
## Celery 任务
```bash
# 启动 Celery Worker
celery -A app.celery worker -l info
# 启动 Flower (任务监控)
celery -A app.celery flower --port=5555
```
## 测试
```bash
# 运行所有测试
pytest
# 运行带覆盖率
pytest --cov=app tests/
```
## 默认账号
- 管理员: admin@plabel.com / admin123
- 普通用户: user@plabel.com / user123
- 标注员: annotator@plabel.com / annotator123
- 审核员: reviewer@plabel.com / reviewer123
## 技术栈
- **框架**: FastAPI 0.110+
- **数据库**: PostgreSQL 15+ / SQLAlchemy 2.0
- **缓存**: Redis 7+
- **任务队列**: Celery 5.x
- **文件存储**: MinIO (S3 兼容)
- **认证**: JWT (python-jose)
- **验证**: Pydantic v2
## License
MIT License
[alembic]
script_location = alembic
prepend_sys_path = .
version_path_separator = os
sqlalchemy.url = postgresql://plabel:plabel123@localhost:5432/plabel
[post_write_hooks]
[loggers]
keys = root,sqlalchemy,alembic
[handlers]
keys = console
[formatters]
keys = generic
[logger_root]
level = WARN
handlers = console
qualname =
[logger_sqlalchemy]
level = WARN
handlers =
qualname = sqlalchemy.engine
[logger_alembic]
level = INFO
handlers =
qualname = alembic
[handler_console]
class = StreamHandler
args = (sys.stderr,)
level = NOTSET
formatter = generic
[formatter_generic]
format = %(levelname)-5.5s [%(name)s] %(message)s
datefmt = %H:%M:%S
"""
Alembic migration environment configuration
"""
from logging.config import fileConfig
from alembic import context
from sqlalchemy import pool
from sqlalchemy import engine_from_config
import sys
from pathlib import Path
sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
from app.core.config import settings
from app.core.database import Base
from app.models import * # noqa: F401,F403
config = context.config
config.set_main_option("sqlalchemy.url", settings.database_url)
if config.config_file_name is not None:
fileConfig(config.config_file_name)
target_metadata = Base.metadata
def run_migrations_offline() -> None:
"""Run migrations in 'offline' mode"""
url = config.get_main_option("sqlalchemy.url")
context.configure(
url=url,
target_metadata=target_metadata,
literal_binds=True,
dialect_opts={"paramstyle": "named"},
)
with context.begin_transaction():
context.run_migrations()
def run_migrations_online() -> None:
"""Run migrations in 'online' mode"""
connectable = engine_from_config(
config.get_section(config.config_ini_section, {}),
prefix="sqlalchemy.",
poolclass=pool.NullPool,
)
with connectable.connect() as connection:
context.configure(connection=connection, target_metadata=target_metadata)
with context.begin_transaction():
context.run_migrations()
if context.is_offline_mode():
run_migrations_offline()
else:
run_migrations_online()
"""${message}
Revision ID: ${up_revision}
Revises: ${down_revision | comma,n}
Create Date: ${create_date}
"""
from typing import Sequence, Union
from alembic import op
import sqlalchemy as sa
${imports if imports else ""}
revision: str = ${repr(up_revision)}
down_revision: Union[str, None] = ${repr(down_revision)}
branch_labels: Union[str, Sequence[str], None] = ${repr(branch_labels)}
depends_on: Union[str, Sequence[str], None] = ${repr(depends_on)}
def upgrade() -> None:
${upgrades if upgrades else "pass"}
def downgrade() -> None:
${downgrades if downgrades else "pass"}
"""Initial migration - create all tables
Revision ID: 2026_05_28_0001
Revises:
Create Date: 2026-05-28 10:00:00.000000
"""
from typing import Sequence, Union
from alembic import op
import sqlalchemy as sa
from sqlalchemy.dialects import postgresql
revision: str = '2026_05_28_0001'
down_revision: Union[str, None] = None
branch_labels: Union[str, Sequence[str], None] = None
depends_on: Union[str, Sequence[str], None] = None
def upgrade() -> None:
# Enable UUID extension
op.execute('CREATE EXTENSION IF NOT EXISTS "uuid-ossp"')
# --- users ---
op.create_table(
'users',
sa.Column('id', postgresql.UUID(as_uuid=True), primary_key=True, server_default=sa.text('gen_random_uuid()')),
sa.Column('username', sa.String(50), nullable=False, unique=True),
sa.Column('email', sa.String(255), nullable=False, unique=True),
sa.Column('password_hash', sa.String(255), nullable=False),
sa.Column('avatar_url', sa.String(500), nullable=True),
sa.Column('role', sa.String(20), nullable=False, server_default='user'),
sa.Column('is_active', sa.Boolean(), nullable=False, server_default='true'),
sa.Column('created_at', sa.DateTime(timezone=True), nullable=False, server_default=sa.text('now()')),
sa.Column('updated_at', sa.DateTime(timezone=True), nullable=False, server_default=sa.text('now()')),
)
op.create_index('ix_users_email', 'users', ['email'])
op.create_index('ix_users_role', 'users', ['role'])
# --- projects ---
op.create_table(
'projects',
sa.Column('id', postgresql.UUID(as_uuid=True), primary_key=True, server_default=sa.text('gen_random_uuid()')),
sa.Column('name', sa.String(200), nullable=False),
sa.Column('description', sa.Text(), nullable=True),
sa.Column('status', sa.String(20), nullable=False, server_default='active'),
sa.Column('owner_id', postgresql.UUID(as_uuid=True), sa.ForeignKey('users.id', ondelete='CASCADE'), nullable=False),
sa.Column('label_set_id', postgresql.UUID(as_uuid=True), nullable=True),
sa.Column('created_at', sa.DateTime(timezone=True), nullable=False, server_default=sa.text('now()')),
sa.Column('updated_at', sa.DateTime(timezone=True), nullable=False, server_default=sa.text('now()')),
)
op.create_index('ix_projects_owner', 'projects', ['owner_id'])
op.create_index('ix_projects_status', 'projects', ['status'])
# --- label_sets ---
op.create_table(
'label_sets',
sa.Column('id', postgresql.UUID(as_uuid=True), primary_key=True, server_default=sa.text('gen_random_uuid()')),
sa.Column('project_id', postgresql.UUID(as_uuid=True), sa.ForeignKey('projects.id', ondelete='CASCADE'), nullable=True),
sa.Column('name', sa.String(200), nullable=False),
sa.Column('created_at', sa.DateTime(timezone=True), nullable=False, server_default=sa.text('now()')),
sa.Column('updated_at', sa.DateTime(timezone=True), nullable=False, server_default=sa.text('now()')),
)
op.create_index('ix_label_sets_project', 'label_sets', ['project_id'])
# --- labels ---
op.create_table(
'labels',
sa.Column('id', postgresql.UUID(as_uuid=True), primary_key=True, server_default=sa.text('gen_random_uuid()')),
sa.Column('label_set_id', postgresql.UUID(as_uuid=True), sa.ForeignKey('label_sets.id', ondelete='CASCADE'), nullable=False),
sa.Column('name', sa.String(100), nullable=False),
sa.Column('color', sa.String(7), nullable=False),
sa.Column('type', sa.String(30), nullable=False),
sa.Column('shortcut', sa.String(10), nullable=True),
sa.Column('parent_id', postgresql.UUID(as_uuid=True), sa.ForeignKey('labels.id'), nullable=True),
sa.Column('attributes', postgresql.JSONB(), server_default='[]'),
sa.Column('created_at', sa.DateTime(timezone=True), nullable=False, server_default=sa.text('now()')),
)
op.create_index('ix_labels_set', 'labels', ['label_set_id'])
op.create_index('ix_labels_type', 'labels', ['type'])
# --- project_members ---
op.create_table(
'project_members',
sa.Column('id', postgresql.UUID(as_uuid=True), primary_key=True, server_default=sa.text('gen_random_uuid()')),
sa.Column('project_id', postgresql.UUID(as_uuid=True), sa.ForeignKey('projects.id', ondelete='CASCADE'), nullable=False),
sa.Column('user_id', postgresql.UUID(as_uuid=True), sa.ForeignKey('users.id', ondelete='CASCADE'), nullable=False),
sa.Column('role', sa.String(20), nullable=False, server_default='member'),
sa.Column('created_at', sa.DateTime(timezone=True), nullable=False, server_default=sa.text('now()')),
sa.Column('updated_at', sa.DateTime(timezone=True), nullable=False, server_default=sa.text('now()')),
sa.UniqueConstraint('project_id', 'user_id'),
)
op.create_index('ix_project_members_project', 'project_members', ['project_id'])
op.create_index('ix_project_members_user', 'project_members', ['user_id'])
# --- ai_models ---
op.create_table(
'ai_models',
sa.Column('id', postgresql.UUID(as_uuid=True), primary_key=True, server_default=sa.text('gen_random_uuid()')),
sa.Column('name', sa.String(200), nullable=False),
sa.Column('type', sa.String(30), nullable=False),
sa.Column('description', sa.Text(), nullable=True),
sa.Column('framework', sa.String(50), nullable=True),
sa.Column('model_path', sa.String(500), nullable=True),
sa.Column('config', postgresql.JSONB(), server_default='{}'),
sa.Column('accuracy', sa.Float(), nullable=True),
sa.Column('speed', sa.Integer(), nullable=True),
sa.Column('enabled', sa.Boolean(), server_default='true'),
sa.Column('created_at', sa.DateTime(timezone=True), nullable=False, server_default=sa.text('now()')),
sa.Column('updated_at', sa.DateTime(timezone=True), nullable=False, server_default=sa.text('now()')),
)
# --- tasks ---
op.create_table(
'tasks',
sa.Column('id', postgresql.UUID(as_uuid=True), primary_key=True, server_default=sa.text('gen_random_uuid()')),
sa.Column('project_id', postgresql.UUID(as_uuid=True), sa.ForeignKey('projects.id', ondelete='CASCADE'), nullable=False),
sa.Column('name', sa.String(200), nullable=False),
sa.Column('description', sa.Text(), nullable=True),
sa.Column('data_type', sa.String(20), nullable=False),
sa.Column('annotation_types', postgresql.JSONB(), server_default='[]'),
sa.Column('status', sa.String(20), nullable=False, server_default='pending'),
sa.Column('assignee_id', postgresql.UUID(as_uuid=True), sa.ForeignKey('users.id'), nullable=True),
sa.Column('reviewer_id', postgresql.UUID(as_uuid=True), sa.ForeignKey('users.id'), nullable=True),
sa.Column('ai_model_id', postgresql.UUID(as_uuid=True), sa.ForeignKey('ai_models.id'), nullable=True),
sa.Column('progress', sa.Integer(), server_default='0'),
sa.Column('total_count', sa.Integer(), server_default='0'),
sa.Column('completed_count', sa.Integer(), server_default='0'),
sa.Column('reviewed_count', sa.Integer(), server_default='0'),
sa.Column('rejected_count', sa.Integer(), server_default='0'),
sa.Column('created_at', sa.DateTime(timezone=True), nullable=False, server_default=sa.text('now()')),
sa.Column('updated_at', sa.DateTime(timezone=True), nullable=False, server_default=sa.text('now()')),
)
op.create_index('ix_tasks_project', 'tasks', ['project_id'])
op.create_index('ix_tasks_status', 'tasks', ['status'])
op.create_index('ix_tasks_assignee', 'tasks', ['assignee_id'])
op.create_index('ix_tasks_data_type', 'tasks', ['data_type'])
# --- data_items ---
op.create_table(
'data_items',
sa.Column('id', postgresql.UUID(as_uuid=True), primary_key=True, server_default=sa.text('gen_random_uuid()')),
sa.Column('task_id', postgresql.UUID(as_uuid=True), sa.ForeignKey('tasks.id', ondelete='CASCADE'), nullable=False),
sa.Column('name', sa.String(500), nullable=False),
sa.Column('type', sa.String(20), nullable=False),
sa.Column('file_path', sa.String(1000), nullable=False),
sa.Column('thumbnail_path', sa.String(1000), nullable=True),
sa.Column('size', sa.BigInteger(), nullable=False),
sa.Column('mime_type', sa.String(100), nullable=True),
sa.Column('width', sa.Integer(), nullable=True),
sa.Column('height', sa.Integer(), nullable=True),
sa.Column('duration', sa.Float(), nullable=True),
sa.Column('pages', sa.Integer(), nullable=True),
sa.Column('metadata', postgresql.JSONB(), server_default='{}'),
sa.Column('annotation_status', sa.String(20), server_default='none'),
sa.Column('created_at', sa.DateTime(timezone=True), nullable=False, server_default=sa.text('now()')),
)
op.create_index('ix_data_items_task', 'data_items', ['task_id'])
op.create_index('ix_data_items_type', 'data_items', ['type'])
op.create_index('ix_data_items_status', 'data_items', ['annotation_status'])
# --- annotations ---
op.create_table(
'annotations',
sa.Column('id', postgresql.UUID(as_uuid=True), primary_key=True, server_default=sa.text('gen_random_uuid()')),
sa.Column('data_item_id', postgresql.UUID(as_uuid=True), sa.ForeignKey('data_items.id', ondelete='CASCADE'), nullable=False),
sa.Column('user_id', postgresql.UUID(as_uuid=True), sa.ForeignKey('users.id'), nullable=False),
sa.Column('label_id', postgresql.UUID(as_uuid=True), sa.ForeignKey('labels.id'), nullable=True),
sa.Column('annotation_type', sa.String(30), nullable=False),
sa.Column('label_name', sa.String(100), nullable=False),
sa.Column('data', postgresql.JSONB(), nullable=False),
sa.Column('visible', sa.Boolean(), server_default='true'),
sa.Column('occluded', sa.Boolean(), server_default='false'),
sa.Column('ignored', sa.Boolean(), server_default='false'),
sa.Column('frame_index', sa.Integer(), server_default='0'),
sa.Column('created_at', sa.DateTime(timezone=True), nullable=False, server_default=sa.text('now()')),
sa.Column('updated_at', sa.DateTime(timezone=True), nullable=False, server_default=sa.text('now()')),
)
op.create_index('ix_annotations_data_item', 'annotations', ['data_item_id'])
op.create_index('ix_annotations_user', 'annotations', ['user_id'])
op.create_index('ix_annotations_frame', 'annotations', ['frame_index'])
# --- audio_annotations ---
op.create_table(
'audio_annotations',
sa.Column('id', postgresql.UUID(as_uuid=True), primary_key=True, server_default=sa.text('gen_random_uuid()')),
sa.Column('data_item_id', postgresql.UUID(as_uuid=True), sa.ForeignKey('data_items.id', ondelete='CASCADE'), nullable=False),
sa.Column('user_id', postgresql.UUID(as_uuid=True), sa.ForeignKey('users.id'), nullable=False),
sa.Column('start_time', sa.Float(), nullable=False),
sa.Column('end_time', sa.Float(), nullable=False),
sa.Column('text', sa.Text(), nullable=True),
sa.Column('speaker', sa.String(100), nullable=True),
sa.Column('labels', postgresql.JSONB(), server_default='[]'),
sa.Column('confidence', sa.Float(), nullable=True),
sa.Column('created_at', sa.DateTime(timezone=True), nullable=False, server_default=sa.text('now()')),
sa.Column('updated_at', sa.DateTime(timezone=True), nullable=False, server_default=sa.text('now()')),
)
op.create_index('ix_audio_annotations_item', 'audio_annotations', ['data_item_id'])
# --- text_entities ---
op.create_table(
'text_entities',
sa.Column('id', postgresql.UUID(as_uuid=True), primary_key=True, server_default=sa.text('gen_random_uuid()')),
sa.Column('data_item_id', postgresql.UUID(as_uuid=True), sa.ForeignKey('data_items.id', ondelete='CASCADE'), nullable=False),
sa.Column('user_id', postgresql.UUID(as_uuid=True), sa.ForeignKey('users.id'), nullable=False),
sa.Column('label_id', postgresql.UUID(as_uuid=True), sa.ForeignKey('labels.id'), nullable=True),
sa.Column('label_name', sa.String(100), nullable=False),
sa.Column('start_offset', sa.Integer(), nullable=False),
sa.Column('end_offset', sa.Integer(), nullable=False),
sa.Column('text', sa.String(1000), nullable=False),
sa.Column('color', sa.String(7), nullable=True),
sa.Column('attributes', postgresql.JSONB(), server_default='{}'),
sa.Column('created_at', sa.DateTime(timezone=True), nullable=False, server_default=sa.text('now()')),
)
op.create_index('ix_text_entities_item', 'text_entities', ['data_item_id'])
# --- text_relations ---
op.create_table(
'text_relations',
sa.Column('id', postgresql.UUID(as_uuid=True), primary_key=True, server_default=sa.text('gen_random_uuid()')),
sa.Column('data_item_id', postgresql.UUID(as_uuid=True), sa.ForeignKey('data_items.id', ondelete='CASCADE'), nullable=False),
sa.Column('user_id', postgresql.UUID(as_uuid=True), sa.ForeignKey('users.id'), nullable=False),
sa.Column('from_entity_id', postgresql.UUID(as_uuid=True), sa.ForeignKey('text_entities.id'), nullable=False),
sa.Column('to_entity_id', postgresql.UUID(as_uuid=True), sa.ForeignKey('text_entities.id'), nullable=False),
sa.Column('label', sa.String(100), nullable=False),
sa.Column('relation_type', sa.String(20), server_default='undirected'),
sa.Column('created_at', sa.DateTime(timezone=True), nullable=False, server_default=sa.text('now()')),
sa.Column('updated_at', sa.DateTime(timezone=True), nullable=False, server_default=sa.text('now()')),
)
# --- review_sessions ---
op.create_table(
'review_sessions',
sa.Column('id', postgresql.UUID(as_uuid=True), primary_key=True, server_default=sa.text('gen_random_uuid()')),
sa.Column('task_id', postgresql.UUID(as_uuid=True), sa.ForeignKey('tasks.id', ondelete='CASCADE'), nullable=False),
sa.Column('data_item_id', postgresql.UUID(as_uuid=True), sa.ForeignKey('data_items.id', ondelete='CASCADE'), nullable=False),
sa.Column('reviewer_id', postgresql.UUID(as_uuid=True), sa.ForeignKey('users.id'), nullable=False),
sa.Column('annotator_id', postgresql.UUID(as_uuid=True), sa.ForeignKey('users.id'), nullable=True),
sa.Column('status', sa.String(20), nullable=False, server_default='pending'),
sa.Column('created_at', sa.DateTime(timezone=True), nullable=False, server_default=sa.text('now()')),
sa.Column('updated_at', sa.DateTime(timezone=True), nullable=False, server_default=sa.text('now()')),
)
op.create_index('ix_review_task', 'review_sessions', ['task_id'])
op.create_index('ix_review_status', 'review_sessions', ['status'])
# --- review_comments ---
op.create_table(
'review_comments',
sa.Column('id', postgresql.UUID(as_uuid=True), primary_key=True, server_default=sa.text('gen_random_uuid()')),
sa.Column('session_id', postgresql.UUID(as_uuid=True), sa.ForeignKey('review_sessions.id', ondelete='CASCADE'), nullable=False),
sa.Column('reviewer_id', postgresql.UUID(as_uuid=True), sa.ForeignKey('users.id'), nullable=False),
sa.Column('annotation_id', postgresql.UUID(as_uuid=True), nullable=True),
sa.Column('content', sa.Text(), nullable=False),
sa.Column('resolved', sa.Boolean(), server_default='false'),
sa.Column('created_at', sa.DateTime(timezone=True), nullable=False, server_default=sa.text('now()')),
)
# --- auto_label_tasks ---
op.create_table(
'auto_label_tasks',
sa.Column('id', postgresql.UUID(as_uuid=True), primary_key=True, server_default=sa.text('gen_random_uuid()')),
sa.Column('task_id', postgresql.UUID(as_uuid=True), sa.ForeignKey('tasks.id', ondelete='CASCADE'), nullable=False),
sa.Column('user_id', postgresql.UUID(as_uuid=True), sa.ForeignKey('users.id'), nullable=False),
sa.Column('model_id', postgresql.UUID(as_uuid=True), sa.ForeignKey('ai_models.id'), nullable=False),
sa.Column('status', sa.String(20), nullable=False, server_default='pending'),
sa.Column('progress', sa.Integer(), server_default='0'),
sa.Column('config', postgresql.JSONB(), server_default='{}'),
sa.Column('result', postgresql.JSONB(), nullable=True),
sa.Column('error', sa.Text(), nullable=True),
sa.Column('data_item_ids', postgresql.JSONB(), server_default='[]'),
sa.Column('started_at', postgresql.TIMESTAMP(timezone=True), nullable=True),
sa.Column('completed_at', postgresql.TIMESTAMP(timezone=True), nullable=True),
sa.Column('created_at', sa.DateTime(timezone=True), nullable=False, server_default=sa.text('now()')),
sa.Column('updated_at', sa.DateTime(timezone=True), nullable=False, server_default=sa.text('now()')),
)
op.create_index('ix_auto_label_task_status', 'auto_label_tasks', ['status'])
op.create_index('ix_auto_label_task_task', 'auto_label_tasks', ['task_id'])
def downgrade() -> None:
op.drop_table('auto_label_tasks')
op.drop_table('review_comments')
op.drop_table('review_sessions')
op.drop_table('text_relations')
op.drop_table('text_entities')
op.drop_table('audio_annotations')
op.drop_table('annotations')
op.drop_table('data_items')
op.drop_table('tasks')
op.drop_table('ai_models')
op.drop_table('project_members')
op.drop_table('labels')
op.drop_table('label_sets')
op.drop_table('projects')
op.drop_table('users')
"""
PLabel Backend Application
FastAPI application for data annotation platform
"""
__version__ = "1.0.0"
"""
API dependencies: authentication, authorization, pagination
"""
from functools import wraps
from typing import Annotated, Callable
from fastapi import Depends, HTTPException, Path, Query, Request, status
from fastapi.security import HTTPAuthorizationCredentials, HTTPBearer
from sqlalchemy import select
from sqlalchemy.ext.asyncio import AsyncSession
from app.core.config import settings
from app.core.database import get_async_session
from app.core.security import decode_token
from app.models.user import User
security = HTTPBearer()
async def get_current_user(
credentials: Annotated[HTTPAuthorizationCredentials, Depends(security)],
db: AsyncSession = Depends(get_async_session),
) -> User:
"""Get current authenticated user from JWT token"""
credentials_exception = HTTPException(
status_code=status.HTTP_401_UNAUTHORIZED,
detail="Could not validate credentials",
headers={"WWW-Authenticate": "Bearer"},
)
try:
token = credentials.credentials
payload = decode_token(token)
if payload is None:
raise credentials_exception
user_id_str = payload.get("sub")
if user_id_str is None:
raise credentials_exception
try:
user_id = int(user_id_str)
except ValueError:
raise credentials_exception
except Exception:
raise credentials_exception
result = await db.execute(select(User).where(User.id == user_id))
user = result.scalar_one_or_none()
if user is None:
raise credentials_exception
if not user.is_active:
raise HTTPException(
status_code=status.HTTP_403_FORBIDDEN,
detail="Inactive user"
)
return user
async def get_current_active_user(
current_user: Annotated[User, Depends(get_current_user)],
) -> User:
"""Verify current user is active"""
return current_user
def require_roles(*allowed_roles: str):
"""Dependency factory to require specific roles for an endpoint"""
async def role_checker(
current_user: User = Depends(get_current_user),
) -> User:
if current_user.role not in allowed_roles:
raise HTTPException(
status_code=status.HTTP_403_FORBIDDEN,
detail=f"Insufficient permissions. Required roles: {', '.join(allowed_roles)}"
)
return current_user
return role_checker
async def check_project_access(
user_id: int,
project_id: int,
db: AsyncSession,
required_roles: list[str],
) -> bool:
"""Check if user has required role in a project"""
return True
class PaginationParams:
"""Pagination parameters for list endpoints"""
def __init__(
self,
page: int = Query(1, ge=1, description="Page number"),
page_size: int = Query(20, ge=1, le=100, description="Items per page"),
):
self.page = page
self.page_size = page_size
self.offset = (page - 1) * page_size
def get_pagination_params(
page: int = Query(1, ge=1),
page_size: int = Query(20, ge=1, le=100),
) -> dict:
return {
"offset": (page - 1) * page_size,
"limit": page_size,
"page": page,
"page_size": page_size,
}
"""
API v1 router
"""
from fastapi import APIRouter
from app.api.v1 import auth, users
api_router = APIRouter()
api_router.include_router(auth.router)
api_router.include_router(users.router)
"""
Authentication API routes
"""
from datetime import timedelta
from fastapi import APIRouter, Depends, HTTPException, status
from sqlalchemy.ext.asyncio import AsyncSession
from app.api.deps import get_current_user
from app.core.config import settings
from app.core.database import get_async_session
from app.core.exceptions import AuthenticationError, ConflictError, ValidationError
from app.core.security import decode_token
from app.models.user import User
from app.schemas.auth import (
ChangePasswordRequest,
LoginRequest,
LoginResponse,
RegisterRequest,
TokenResponse,
UserResponse,
)
from app.services.auth_service import AuthService
router = APIRouter(prefix="/auth", tags=["Authentication"])
def user_to_response(user: User) -> UserResponse:
"""Convert User model to UserResponse schema"""
return UserResponse(
id=str(user.id),
username=user.username,
email=user.email,
role=user.role,
avatar_url=user.avatar_url,
is_active=user.is_active,
)
@router.post("/login", response_model=LoginResponse)
async def login(
login_data: LoginRequest,
db: AsyncSession = Depends(get_async_session),
) -> LoginResponse:
"""
User login endpoint
Returns access token and user information
"""
auth_service = AuthService(db)
try:
user, access_token = await auth_service.login(login_data)
return LoginResponse(
access_token=access_token,
token_type="bearer",
expires_in=settings.access_token_expire_minutes * 60,
user=user_to_response(user),
)
except AuthenticationError as e:
raise HTTPException(
status_code=status.HTTP_401_UNAUTHORIZED,
detail=str(e),
headers={"WWW-Authenticate": "Bearer"},
)
@router.post("/register", response_model=LoginResponse, status_code=status.HTTP_201_CREATED)
async def register(
register_data: RegisterRequest,
db: AsyncSession = Depends(get_async_session),
) -> LoginResponse:
"""
User registration endpoint
Creates a new user account and returns access token
"""
auth_service = AuthService(db)
try:
user = await auth_service.register(register_data)
access_token = create_access_token(
data={
"sub": str(user.id),
"email": user.email,
"role": user.role,
}
)
return LoginResponse(
access_token=access_token,
token_type="bearer",
expires_in=settings.access_token_expire_minutes * 60,
user=user_to_response(user),
)
except ConflictError as e:
raise HTTPException(
status_code=status.HTTP_409_CONFLICT,
detail=str(e),
)
except ValidationError as e:
raise HTTPException(
status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
detail=str(e),
)
@router.post("/logout")
async def logout(current_user: User = Depends(get_current_user)) -> dict:
"""
User logout endpoint
Note: For JWT-based auth, logout is typically handled client-side
by removing the token from storage.
"""
return {"message": "Successfully logged out"}
@router.get("/me", response_model=UserResponse)
async def get_current_user_info(
current_user: User = Depends(get_current_user),
) -> UserResponse:
"""
Get current authenticated user information
"""
return user_to_response(current_user)
@router.put("/me", response_model=UserResponse)
async def update_current_user(
user_data: dict,
current_user: User = Depends(get_current_user),
db: AsyncSession = Depends(get_async_session),
) -> UserResponse:
"""
Update current user's profile information
"""
from app.services.user_service import UserService
from app.schemas.user import UserUpdate
user_service = UserService(db)
updated_user = await user_service.update_user(
current_user.id,
UserUpdate(**{k: v for k, v in user_data.items() if k in ["username", "email", "avatar_url"]})
)
return user_to_response(updated_user)
@router.post("/change-password")
async def change_password(
password_data: ChangePasswordRequest,
current_user: User = Depends(get_current_user),
db: AsyncSession = Depends(get_async_session),
) -> dict:
"""
Change current user's password
"""
from app.services.user_service import UserService
user_service = UserService(db)
try:
await user_service.update_password(
current_user.id,
password_data.old_password,
password_data.new_password,
)
return {"message": "Password updated successfully"}
except PermissionDeniedError:
raise HTTPException(
status_code=status.HTTP_403_FORBIDDEN,
detail="Current password is incorrect",
)
except ValueError as e:
raise HTTPException(
status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
detail=str(e),
)
def create_access_token(data: dict) -> str:
"""Helper function to create access token"""
from app.core.security import create_access_token as _create_access_token
return _create_access_token(data)
"""
User management API routes
"""
from fastapi import APIRouter, Depends, HTTPException, Query, status
from sqlalchemy.ext.asyncio import AsyncSession
from app.api.deps import get_current_user, get_pagination_params
from app.core.database import get_async_session
from app.core.exceptions import NotFoundError, PermissionDeniedError
from app.models.user import User
from app.schemas.base import ResponseSchema
from app.schemas.user import UserCreate, UserResponse, UserStatsResponse, UserUpdate
from app.services.user_service import UserService
router = APIRouter(prefix="/users", tags=["Users"])
def user_to_response(user: User) -> UserResponse:
"""Convert User model to UserResponse schema"""
return UserResponse(
id=str(user.id),
username=user.username,
email=user.email,
role=user.role,
avatar_url=user.avatar_url,
is_active=user.is_active,
)
@router.get("", response_model=ResponseSchema)
async def list_users(
page: int = Query(1, ge=1, description="Page number"),
page_size: int = Query(20, ge=1, le=100, description="Items per page"),
role: str | None = Query(None, description="Filter by role"),
current_user: User = Depends(get_current_user),
db: AsyncSession = Depends(get_async_session),
) -> ResponseSchema:
"""
Get list of users (admin only)
"""
if current_user.role != "admin":
raise HTTPException(
status_code=status.HTTP_403_FORBIDDEN,
detail="Only administrators can access user list",
)
user_service = UserService(db)
skip = (page - 1) * page_size
users, total = await user_service.get_users(skip=skip, limit=page_size, role=role)
return ResponseSchema(
code=200,
message="success",
data={
"items": [user_to_response(u) for u in users],
"total": total,
"page": page,
"page_size": page_size,
"total_pages": (total + page_size - 1) // page_size if total > 0 else 0,
}
)
@router.get("/{user_id}", response_model=ResponseSchema)
async def get_user(
user_id: int,
current_user: User = Depends(get_current_user),
db: AsyncSession = Depends(get_async_session),
) -> ResponseSchema:
"""
Get user by ID
"""
user_service = UserService(db)
user = await user_service.get_by_id(user_id)
if not user:
raise HTTPException(
status_code=status.HTTP_404_NOT_FOUND,
detail="User not found",
)
return ResponseSchema(
code=200,
message="success",
data=user_to_response(user),
)
@router.post("", response_model=ResponseSchema, status_code=status.HTTP_201_CREATED)
async def create_user(
user_data: UserCreate,
current_user: User = Depends(get_current_user),
db: AsyncSession = Depends(get_async_session),
) -> ResponseSchema:
"""
Create a new user (admin only)
"""
if current_user.role != "admin":
raise HTTPException(
status_code=status.HTTP_403_FORBIDDEN,
detail="Only administrators can create users",
)
user_service = UserService(db)
try:
user = await user_service.create_user(user_data)
return ResponseSchema(
code=201,
message="User created successfully",
data=user_to_response(user),
)
except Exception as e:
raise HTTPException(
status_code=status.HTTP_409_CONFLICT,
detail=str(e),
)
@router.put("/{user_id}", response_model=ResponseSchema)
async def update_user(
user_id: int,
user_data: UserUpdate,
current_user: User = Depends(get_current_user),
db: AsyncSession = Depends(get_async_session),
) -> ResponseSchema:
"""
Update user information (admin only for other users, users can update themselves)
"""
user_service = UserService(db)
if current_user.role != "admin" and current_user.id != user_id:
raise HTTPException(
status_code=status.HTTP_403_FORBIDDEN,
detail="You can only update your own profile",
)
try:
updated_user = await user_service.update_user(user_id, user_data)
return ResponseSchema(
code=200,
message="User updated successfully",
data=user_to_response(updated_user),
)
except NotFoundError:
raise HTTPException(
status_code=status.HTTP_404_NOT_FOUND,
detail="User not found",
)
except Exception as e:
raise HTTPException(
status_code=status.HTTP_409_CONFLICT,
detail=str(e),
)
@router.delete("/{user_id}", status_code=status.HTTP_204_NO_CONTENT)
async def delete_user(
user_id: int,
current_user: User = Depends(get_current_user),
db: AsyncSession = Depends(get_async_session),
):
"""
Delete a user (admin only)
"""
if current_user.role != "admin":
raise HTTPException(
status_code=status.HTTP_403_FORBIDDEN,
detail="Only administrators can delete users",
)
if current_user.id == user_id:
raise HTTPException(
status_code=status.HTTP_400_BAD_REQUEST,
detail="You cannot delete your own account",
)
user_service = UserService(db)
try:
await user_service.delete_user(user_id)
except NotFoundError:
raise HTTPException(
status_code=status.HTTP_404_NOT_FOUND,
detail="User not found",
)
@router.get("/{user_id}/stats", response_model=ResponseSchema)
async def get_user_stats(
user_id: int,
current_user: User = Depends(get_current_user),
db: AsyncSession = Depends(get_async_session),
) -> ResponseSchema:
"""
Get user statistics
"""
if current_user.role != "admin" and current_user.id != user_id:
raise HTTPException(
status_code=status.HTTP_403_FORBIDDEN,
detail="You can only view your own statistics",
)
user_service = UserService(db)
stats = await user_service.get_user_stats(user_id)
return ResponseSchema(
code=200,
message="success",
data=stats,
)
"""
PLabel Core Package
Exposes configuration, infrastructure, and shared utilities
"""
from app.core.config import settings
from app.core.database import (
AsyncSessionLocal,
Base,
SyncSessionLocal,
async_engine,
close_db,
get_async_session,
get_db_context,
get_sync_session,
init_db,
sync_engine,
)
from app.core.exceptions import (
AIInferenceError,
AlreadyExistsError,
AuthenticationError,
DatabaseError,
FileTooLargeError,
InvalidFileTypeError,
InvalidTokenError,
NotFoundError,
PermissionDeniedError,
PLabelException,
RateLimitError,
StorageError,
TaskQueueError,
ValidationError,
register_exception_handlers,
)
from app.core.logging import get_logger, setup_logging
from app.core.middleware import RequestLogMiddleware
from app.core.redis import CacheService, close_async_redis, get_async_redis, get_cache, get_redis_client
from app.core.security import create_access_token, create_refresh_token, decode_token, hash_password, verify_password
from app.core.storage import StorageService, storage_service
__all__ = [
# Config
"settings",
# Database
"Base",
"async_engine",
"sync_engine",
"AsyncSessionLocal",
"SyncSessionLocal",
"get_async_session",
"get_sync_session",
"get_db_context",
"init_db",
"close_db",
# Redis
"get_redis_client",
"get_async_redis",
"get_cache",
"CacheService",
"close_async_redis",
# Security
"hash_password",
"verify_password",
"create_access_token",
"create_refresh_token",
"decode_token",
# Storage
"StorageService",
"storage_service",
# Logging
"setup_logging",
"get_logger",
# Middleware
"RequestLogMiddleware",
# Exceptions
"PLabelException",
"NotFoundError",
"AlreadyExistsError",
"PermissionDeniedError",
"AuthenticationError",
"InvalidTokenError",
"FileTooLargeError",
"InvalidFileTypeError",
"ValidationError",
"DatabaseError",
"StorageError",
"TaskQueueError",
"AIInferenceError",
"RateLimitError",
"register_exception_handlers",
]
"""
Application configuration settings
Loads settings from environment variables using pydantic-settings
"""
from functools import lru_cache
from typing import List
from pydantic import Field
from pydantic_settings import BaseSettings, SettingsConfigDict
class Settings(BaseSettings):
"""Application settings loaded from environment variables"""
model_config = SettingsConfigDict(
env_file=".env",
env_file_encoding="utf-8",
case_sensitive=False,
extra="ignore"
)
# ===========================================
# Application Settings
# ===========================================
app_name: str = "PLabel"
app_env: str = "development"
app_debug: bool = True
app_secret_key: str = "change-this-super-secret-key"
# Server
host: str = "0.0.0.0"
port: int = 8000
# ===========================================
# Database Settings
# ===========================================
database_url: str = "postgresql://plabel:plabel123@localhost:5432/plabel"
async_database_url: str = "postgresql+asyncpg://plabel:plabel123@localhost:5432/plabel"
# ===========================================
# Redis Settings
# ===========================================
redis_host: str = "localhost"
redis_port: int = 6379
redis_db: int = 0
redis_password: str = ""
redis_url: str = "redis://localhost:6379/0"
celery_broker_url: str = "redis://localhost:6379/1"
celery_result_backend: str = "redis://localhost:6379/2"
# ===========================================
# MinIO Settings
# ===========================================
minio_endpoint: str = "localhost:9000"
minio_access_key: str = "plabel_access_key"
minio_secret_key: str = "plabel_secret_key"
minio_bucket: str = "plabel-bucket"
minio_secure: bool = False
minio_region: str = "us-east-1"
# ===========================================
# JWT Settings
# ===========================================
jwt_secret_key: str = "your-super-secret-jwt-key"
jwt_algorithm: str = "HS256"
access_token_expire_minutes: int = 1440 # 24 hours
refresh_token_expire_days: int = 7
# ===========================================
# File Upload Settings
# ===========================================
max_image_size_mb: int = 50
max_video_size_mb: int = 500
max_audio_size_mb: int = 100
max_text_size_mb: int = 10
allowed_image_types: str = "image/jpeg,image/png,image/webp,image/bmp"
allowed_video_types: str = "video/mp4,video/webm,video/quicktime"
allowed_audio_types: str = "audio/mpeg,audio/wav,audio/ogg,audio/m4a"
allowed_text_types: str = "text/plain,text/markdown,application/json"
upload_dir: str = "./data/uploads"
thumbnail_dir: str = "./data/thumbnails"
export_dir: str = "./data/exports"
# ===========================================
# AI Model Settings
# ===========================================
ai_model_device: str = "cpu"
ai_model_cache_dir: str = "./models"
cuda_visible_devices: str = "0"
# ===========================================
# CORS Settings
# ===========================================
cors_origins: str = "http://localhost:3000,http://localhost:8000"
# ===========================================
# Logging Settings
# ===========================================
log_level: str = "INFO"
log_file: str = "./logs/app.log"
# ===========================================
# Computed Properties
# ===========================================
@property
def cors_origins_list(self) -> List[str]:
return [origin.strip() for origin in self.cors_origins.split(",")]
@property
def max_image_size(self) -> int:
return self.max_image_size_mb * 1024 * 1024
@property
def max_video_size(self) -> int:
return self.max_video_size_mb * 1024 * 1024
@property
def max_audio_size(self) -> int:
return self.max_audio_size_mb * 1024 * 1024
@property
def max_text_size(self) -> int:
return self.max_text_size_mb * 1024 * 1024
@property
def allowed_image_types_list(self) -> List[str]:
return self.allowed_image_types.split(",")
@property
def allowed_video_types_list(self) -> List[str]:
return self.allowed_video_types.split(",")
@property
def allowed_audio_types_list(self) -> List[str]:
return self.allowed_audio_types.split(",")
@property
def allowed_text_types_list(self) -> List[str]:
return self.allowed_text_types.split(",")
@property
def is_production(self) -> bool:
return self.app_env == "production"
@property
def is_development(self) -> bool:
return self.app_env == "development"
@lru_cache()
def get_settings() -> Settings:
"""Get cached settings instance"""
return Settings()
# Global settings instance
settings = get_settings()
"""
Database connection and session management
"""
from contextlib import asynccontextmanager
from typing import AsyncGenerator
from sqlalchemy import create_engine
from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker, create_async_engine
from sqlalchemy.orm import DeclarativeBase, Session, sessionmaker
from app.core.config import settings
# ===========================================
# Synchronous Engine (for migrations & CLI)
# ===========================================
sync_engine = create_engine(
settings.database_url,
pool_pre_ping=True,
pool_size=10,
max_overflow=20,
echo=settings.app_debug,
)
SyncSessionLocal = sessionmaker(
autocommit=False,
autoflush=False,
bind=sync_engine,
)
# ===========================================
# Async Engine (for API endpoints)
# ===========================================
async_engine = create_async_engine(
settings.async_database_url,
pool_pre_ping=True,
pool_size=10,
max_overflow=20,
echo=settings.app_debug,
)
AsyncSessionLocal = async_sessionmaker(
bind=async_engine,
class_=AsyncSession,
expire_on_commit=False,
autocommit=False,
autoflush=False,
)
# ===========================================
# Base Model Class
# ===========================================
class Base(DeclarativeBase):
"""Base class for all SQLAlchemy models"""
pass
# ===========================================
# Dependency Functions
# ===========================================
async def get_async_session() -> AsyncGenerator[AsyncSession, None]:
"""
Async dependency for FastAPI to get database session
Usage:
@app.get("/items")
async def get_items(db: AsyncSession = Depends(get_async_session)):
...
"""
async with AsyncSessionLocal() as session:
try:
yield session
await session.commit()
except Exception:
await session.rollback()
raise
finally:
await session.close()
def get_sync_session() -> Session:
"""
Sync dependency for getting database session
Usage in CLI scripts or background tasks:
with get_sync_session() as session:
...
"""
session = SyncSessionLocal()
try:
yield session
session.commit()
except Exception:
session.rollback()
raise
finally:
session.close()
@asynccontextmanager
async def get_db_context() -> AsyncGenerator[AsyncSession, None]:
"""
Async context manager for database session
Usage:
async with get_db_context() as db:
result = await db.execute(query)
"""
async with AsyncSessionLocal() as session:
try:
yield session
await session.commit()
except Exception:
await session.rollback()
raise
finally:
await session.close()
# ===========================================
# Database Initialization
# ===========================================
async def init_db():
"""Initialize database tables"""
async with async_engine.begin() as conn:
await conn.run_sync(Base.metadata.create_all)
async def close_db():
"""Close database connections"""
await async_engine.dispose()
"""
Custom exceptions and exception handlers for PLabel
"""
from typing import Any, Optional
from fastapi import FastAPI, Request
from fastapi.responses import JSONResponse
class PLabelException(Exception):
"""Base exception for all PLabel errors"""
def __init__(
self,
message: str,
code: int = 400,
errors: Optional[list] = None,
details: Optional[Any] = None,
):
self.message = message
self.code = code
self.errors = errors or []
self.details = details
super().__init__(self.message)
class NotFoundError(PLabelException):
"""Resource not found"""
def __init__(self, resource: str, identifier: str | int):
super().__init__(
message=f"{resource} with identifier '{identifier}' not found",
code=404,
)
self.resource = resource
self.identifier = identifier
class AlreadyExistsError(PLabelException):
"""Resource already exists"""
def __init__(self, resource: str, field: str, value: str):
super().__init__(
message=f"{resource} with {field} '{value}' already exists",
code=409,
)
self.resource = resource
self.field = field
self.value = value
class ConflictError(PLabelException):
"""Resource conflict error (e.g., duplicate entry)"""
def __init__(self, message: str = "Resource already exists"):
super().__init__(message=message, code=409)
class PermissionDeniedError(PLabelException):
"""Insufficient permissions"""
def __init__(self, message: str = "You do not have permission to perform this action"):
super().__init__(message=message, code=403)
class AuthenticationError(PLabelException):
"""Authentication failed"""
def __init__(self, message: str = "Authentication failed"):
super().__init__(message=message, code=401)
class InvalidTokenError(AuthenticationError):
"""Invalid or expired token"""
def __init__(self, message: str = "Invalid or expired token"):
super().__init__(message=message)
class FileTooLargeError(PLabelException):
"""Uploaded file exceeds size limit"""
def __init__(self, filename: str, max_size: str):
super().__init__(
message=f"File '{filename}' exceeds maximum size limit of {max_size}",
code=413,
)
self.filename = filename
self.max_size = max_size
class InvalidFileTypeError(PLabelException):
"""File type not allowed"""
def __init__(self, filename: str, allowed_types: list[str]):
super().__init__(
message=f"File type of '{filename}' is not allowed. Allowed types: {', '.join(allowed_types)}",
code=415,
)
self.filename = filename
self.allowed_types = allowed_types
class ValidationError(PLabelException):
"""Request validation failed"""
def __init__(self, errors: list[dict]):
super().__init__(
message="Validation failed",
code=422,
errors=errors,
)
class DatabaseError(PLabelException):
"""Database operation failed"""
def __init__(self, message: str = "Database operation failed"):
super().__init__(message=message, code=500)
class StorageError(PLabelException):
"""File storage operation failed"""
def __init__(self, message: str = "File storage operation failed"):
super().__init__(message=message, code=500)
class TaskQueueError(PLabelException):
"""Task queue operation failed"""
def __init__(self, message: str = "Task queue operation failed"):
super().__init__(message=message, code=500)
class AIInferenceError(PLabelException):
"""AI model inference failed"""
def __init__(self, model_name: str, message: str = "AI inference failed"):
super().__init__(
message=f"{message} (model: {model_name})",
code=500,
)
self.model_name = model_name
class RateLimitError(PLabelException):
"""Rate limit exceeded"""
def __init__(self, message: str = "Rate limit exceeded. Please try again later"):
super().__init__(message=message, code=429)
def register_exception_handlers(app: FastAPI) -> None:
"""Register all exception handlers with the FastAPI app"""
@app.exception_handler(PLabelException)
async def plabel_exception_handler(
request: Request, exc: PLabelException
) -> JSONResponse:
content = {
"code": exc.code,
"message": exc.message,
}
if exc.errors:
content["errors"] = exc.errors
if exc.details:
content["details"] = exc.details
return JSONResponse(status_code=exc.code, content=content)
@app.exception_handler(NotFoundError)
async def not_found_handler(
request: Request, exc: NotFoundError
) -> JSONResponse:
return JSONResponse(
status_code=404,
content={
"code": 404,
"message": exc.message,
"errors": [{"field": "id", "message": exc.message}],
},
)
@app.exception_handler(ValidationError)
async def validation_handler(
request: Request, exc: ValidationError
) -> JSONResponse:
return JSONResponse(
status_code=422,
content={
"code": 422,
"message": exc.message,
"errors": exc.errors,
},
)
@app.exception_handler(AuthenticationError)
async def auth_error_handler(
request: Request, exc: AuthenticationError
) -> JSONResponse:
return JSONResponse(
status_code=401,
content={
"code": 401,
"message": exc.message,
},
)
@app.exception_handler(PermissionDeniedError)
async def permission_handler(
request: Request, exc: PermissionDeniedError
) -> JSONResponse:
return JSONResponse(
status_code=403,
content={
"code": 403,
"message": exc.message,
},
)
@app.exception_handler(FileTooLargeError)
async def file_too_large_handler(
request: Request, exc: FileTooLargeError
) -> JSONResponse:
return JSONResponse(
status_code=413,
content={
"code": 413,
"message": exc.message,
},
)
@app.exception_handler(InvalidFileTypeError)
async def invalid_file_type_handler(
request: Request, exc: InvalidFileTypeError
) -> JSONResponse:
return JSONResponse(
status_code=415,
content={
"code": 415,
"message": exc.message,
},
)
@app.exception_handler(RateLimitError)
async def rate_limit_handler(
request: Request, exc: RateLimitError
) -> JSONResponse:
return JSONResponse(
status_code=429,
content={
"code": 429,
"message": exc.message,
},
)
"""
Logging configuration using Loguru
"""
import sys
from pathlib import Path
from loguru import logger
from app.core.config import settings
def setup_logging():
"""Configure application logging"""
# Remove default handler
logger.remove()
# Add console handler
logger.add(
sys.stdout,
format="<green>{time:YYYY-MM-DD HH:mm:ss}</green> | <level>{level: <8}</level> | <cyan>{name}</cyan>:<cyan>{function}</cyan>:<cyan>{line}</cyan> - <level>{message}</level>",
level=settings.log_level,
colorize=True,
)
# Add file handler if log_file is configured
if settings.log_file:
log_path = Path(settings.log_file)
log_path.parent.mkdir(parents=True, exist_ok=True)
logger.add(
settings.log_file,
format="{time:YYYY-MM-DD HH:mm:ss} | {level: <8} | {name}:{function}:{line} - {message}",
level=settings.log_level,
rotation="100 MB",
retention="30 days",
compression="zip",
)
# Set logger as global
logger.configure(
handlers=[
{
"sink": sys.stdout,
"level": settings.log_level,
"format": "<green>{time:YYYY-MM-DD HH:mm:ss}</green> | <level>{level: <8}</level> | <cyan>{name}</cyan>:<cyan>{function}</cyan>:<cyan>{line}</cyan> - <level>{message}</level>",
}
]
)
return logger
def get_logger():
"""Get the configured logger"""
return logger
"""
Custom middleware for PLabel
"""
import time
from typing import Callable
from fastapi import Request, Response
from starlette.middleware.base import BaseHTTPMiddleware
from app.core.logging import get_logger
logger = get_logger()
class RequestLogMiddleware(BaseHTTPMiddleware):
"""Middleware to log all incoming requests and responses"""
async def dispatch(self, request: Request, call_next: Callable) -> Response:
request_id = request.headers.get("X-Request-ID", "-")
start_time = time.time()
method = request.method
url = str(request.url)
logger.info(
f"[{request_id}] --> {method} {url} | "
f"client={request.client.host if request.client else 'unknown'}"
)
try:
response = await call_next(request)
except Exception as exc:
elapsed = time.time() - start_time
logger.error(
f"[{request_id}] <-- {method} {url} | "
f"status=500 | elapsed={elapsed:.3f}s | error={exc}"
)
raise
elapsed = time.time() - start_time
logger.info(
f"[{request_id}] <-- {method} {url} | "
f"status={response.status_code} | elapsed={elapsed:.3f}s"
)
response.headers["X-Request-ID"] = request_id
response.headers["X-Response-Time"] = f"{elapsed:.3f}s"
return response
"""
Redis connection and caching utilities
"""
from typing import Optional
import redis.asyncio as aioredis
from redis import Redis
from redis.asyncio import Redis as AsyncRedis
from app.core.config import settings
# ===========================================
# Synchronous Redis Client
# ===========================================
def get_redis_client() -> Redis:
"""Get synchronous Redis client"""
return Redis(
host=settings.redis_host,
port=settings.redis_port,
db=settings.redis_db,
password=settings.redis_password or None,
decode_responses=True,
)
# ===========================================
# Async Redis Client
# ===========================================
_async_redis_client: Optional[AsyncRedis] = None
async def get_async_redis() -> AsyncRedis:
"""Get async Redis client (singleton pattern)"""
global _async_redis_client
if _async_redis_client is None:
_async_redis_client = await aioredis.from_url(
settings.redis_url,
encoding="utf-8",
decode_responses=True,
)
return _async_redis_client
async def close_async_redis():
"""Close async Redis connection"""
global _async_redis_client
if _async_redis_client is not None:
await _async_redis_client.close()
_async_redis_client = None
# ===========================================
# Cache Utilities
# ===========================================
class CacheService:
"""Simple caching service using Redis"""
def __init__(self, redis_client: AsyncRedis):
self.redis = redis_client
async def get(self, key: str) -> Optional[str]:
"""Get value from cache"""
return await self.redis.get(key)
async def set(
self,
key: str,
value: str,
expire: Optional[int] = None
) -> None:
"""Set value in cache with optional expiration (seconds)"""
await self.redis.set(key, value, ex=expire)
async def delete(self, key: str) -> None:
"""Delete key from cache"""
await self.redis.delete(key)
async def exists(self, key: str) -> bool:
"""Check if key exists"""
return await self.redis.exists(key) > 0
async def incr(self, key: str, amount: int = 1) -> int:
"""Increment counter"""
return await self.redis.incrby(key, amount)
async def decr(self, key: str, amount: int = 1) -> int:
"""Decrement counter"""
return await self.redis.decrby(key, amount)
async def get_cache() -> CacheService:
"""Get cache service instance"""
redis = await get_async_redis()
return CacheService(redis)
"""
Security utilities for authentication and authorization
"""
from datetime import datetime, timedelta
from typing import Optional
from jose import JWTError, jwt
from passlib.context import CryptContext
from app.core.config import settings
# Password hashing context
pwd_context = CryptContext(schemes=["bcrypt"], deprecated="auto")
def verify_password(plain_password: str, hashed_password: str) -> bool:
"""Verify a plain password against a hashed password"""
return pwd_context.verify(plain_password, hashed_password)
def hash_password(password: str) -> str:
"""Hash a password using bcrypt"""
return pwd_context.hash(password)
def create_access_token(
data: dict,
expires_delta: Optional[timedelta] = None
) -> str:
"""
Create a JWT access token
Args:
data: Dictionary containing token payload (should include 'sub' for user_id)
expires_delta: Optional expiration time delta
Returns:
Encoded JWT token string
"""
to_encode = data.copy()
if expires_delta:
expire = datetime.utcnow() + expires_delta
else:
expire = datetime.utcnow() + timedelta(
minutes=settings.access_token_expire_minutes
)
to_encode.update({"exp": expire, "iat": datetime.utcnow()})
encoded_jwt = jwt.encode(
to_encode,
settings.jwt_secret_key,
algorithm=settings.jwt_algorithm
)
return encoded_jwt
def decode_token(token: str) -> Optional[dict]:
"""
Decode and verify a JWT token
Args:
token: JWT token string
Returns:
Decoded token payload or None if invalid
"""
try:
payload = jwt.decode(
token,
settings.jwt_secret_key,
algorithms=[settings.jwt_algorithm]
)
return payload
except JWTError:
return None
def create_refresh_token(
data: dict,
expires_delta: Optional[timedelta] = None
) -> str:
"""
Create a JWT refresh token with longer expiration
Args:
data: Dictionary containing token payload
expires_delta: Optional expiration time delta
Returns:
Encoded JWT refresh token string
"""
to_encode = data.copy()
if expires_delta:
expire = datetime.utcnow() + expires_delta
else:
expire = datetime.utcnow() + timedelta(
days=settings.refresh_token_expire_days
)
to_encode.update({
"exp": expire,
"iat": datetime.utcnow(),
"type": "refresh"
})
encoded_jwt = jwt.encode(
to_encode,
settings.jwt_secret_key,
algorithm=settings.jwt_algorithm
)
return encoded_jwt
"""
MinIO / S3-compatible object storage client wrapper
"""
import io
from pathlib import Path
from typing import Optional
from minio import Minio
from minio.datatypes import Object
from app.core.config import settings
from app.core.exceptions import StorageError
from app.core.logging import get_logger
logger = get_logger()
class StorageService:
"""MinIO storage service for file operations"""
def __init__(self):
self._client: Optional[Minio] = None
self._bucket = settings.minio_bucket
@property
def client(self) -> Minio:
"""Lazy-initialize MinIO client"""
if self._client is None:
self._client = Minio(
endpoint=settings.minio_endpoint,
access_key=settings.minio_access_key,
secret_key=settings.minio_secret_key,
secure=settings.minio_secure,
region=settings.minio_region,
)
return self._client
async def ensure_bucket_exists(self) -> None:
"""Ensure the default bucket exists, create if not"""
try:
if not self.client.bucket_exists(self._bucket):
logger.info(f"Creating bucket: {self._bucket}")
self.client.make_bucket(self._bucket)
logger.info(f"Bucket '{self._bucket}' created successfully")
except Exception as exc:
logger.error(f"Failed to create bucket '{self._bucket}': {exc}")
raise StorageError(f"Failed to create bucket: {exc}")
def upload_file(
self,
file_data: bytes,
object_name: str,
content_type: str = "application/octet-stream",
length: Optional[int] = None,
) -> str:
"""
Upload a file to MinIO
Args:
file_data: File content as bytes
object_name: Destination object name (path in bucket)
content_type: MIME type of the file
length: File size in bytes (defaults to len(file_data))
Returns:
The object name of the uploaded file
"""
try:
data = io.BytesIO(file_data)
file_length = length if length is not None else len(file_data)
self.client.put_object(
bucket_name=self._bucket,
object_name=object_name,
data=data,
length=file_length,
content_type=content_type,
)
logger.info(f"Uploaded file: {object_name} ({file_length} bytes)")
return object_name
except Exception as exc:
logger.error(f"Failed to upload file '{object_name}': {exc}")
raise StorageError(f"Failed to upload file: {exc}")
def upload_file_from_path(
self,
file_path: str,
object_name: str,
content_type: str = "application/octet-stream",
) -> str:
"""Upload a file from local filesystem to MinIO"""
try:
file_size = Path(file_path).stat().st_size
self.client.fput_object(
bucket_name=self._bucket,
object_name=object_name,
file_path=file_path,
content_type=content_type,
)
logger.info(
f"Uploaded file from path: {file_path} -> {object_name} ({file_size} bytes)"
)
return object_name
except Exception as exc:
logger.error(f"Failed to upload file from path '{file_path}': {exc}")
raise StorageError(f"Failed to upload file from path: {exc}")
def get_presigned_url(
self,
object_name: str,
expires: int = 3600,
) -> str:
"""
Generate a presigned URL for reading an object
Args:
object_name: Object name in bucket
expires: URL expiration time in seconds
Returns:
Presigned URL string
"""
try:
url = self.client.presigned_get_object(
bucket_name=self._bucket,
object_name=object_name,
expires=expires,
)
return url
except Exception as exc:
logger.error(f"Failed to generate presigned URL for '{object_name}': {exc}")
raise StorageError(f"Failed to generate presigned URL: {exc}")
def get_presigned_put_url(
self,
object_name: str,
expires: int = 3600,
content_type: str = "application/octet-stream",
) -> str:
"""
Generate a presigned URL for uploading an object directly
Args:
object_name: Destination object name
expires: URL expiration time in seconds
content_type: Expected content type
Returns:
Presigned PUT URL string
"""
try:
url = self.client.presigned_put_object(
bucket_name=self._bucket,
object_name=object_name,
expires=expires,
extra_query_params={"Content-Type": content_type},
)
return url
except Exception as exc:
logger.error(
f"Failed to generate presigned PUT URL for '{object_name}': {exc}"
)
raise StorageError(f"Failed to generate presigned PUT URL: {exc}")
def delete_file(self, object_name: str) -> None:
"""Delete an object from MinIO"""
try:
self.client.remove_object(
bucket_name=self._bucket,
object_name=object_name,
)
logger.info(f"Deleted file: {object_name}")
except Exception as exc:
logger.error(f"Failed to delete file '{object_name}': {exc}")
raise StorageError(f"Failed to delete file: {exc}")
def delete_files(self, object_names: list[str]) -> None:
"""Delete multiple objects from MinIO"""
try:
self.client.remove_objects(
bucket_name=self._bucket,
object_names=object_names,
)
logger.info(f"Deleted {len(object_names)} files")
except Exception as exc:
logger.error(f"Failed to delete multiple files: {exc}")
raise StorageError(f"Failed to delete multiple files: {exc}")
def list_files(
self,
prefix: str = "",
max_keys: int = 1000,
) -> list[Object]:
"""
List objects in the bucket with optional prefix filter
Args:
prefix: Filter objects by prefix
max_keys: Maximum number of objects to return
Returns:
List of Object items
"""
try:
objects = self.client.list_objects(
bucket_name=self._bucket,
prefix=prefix,
max_keys=max_keys,
)
return list(objects)
except Exception as exc:
logger.error(f"Failed to list files with prefix '{prefix}': {exc}")
raise StorageError(f"Failed to list files: {exc}")
def get_object(self, object_name: str) -> io.BytesIO:
"""Get an object's content as BytesIO"""
try:
response = self.client.get_object(
bucket_name=self._bucket,
object_name=object_name,
)
data = io.BytesIO(response.read())
response.close()
response.release_conn()
return data
except Exception as exc:
logger.error(f"Failed to get object '{object_name}': {exc}")
raise StorageError(f"Failed to get object: {exc}")
def stat_object(self, object_name: str) -> dict:
"""Get object metadata/statistics"""
try:
stat = self.client.stat_object(
bucket_name=self._bucket,
object_name=object_name,
)
return {
"size": stat.size,
"etag": stat.etag,
"content_type": stat.content_type,
"last_modified": stat.last_modified,
}
except Exception as exc:
logger.error(f"Failed to stat object '{object_name}': {exc}")
raise StorageError(f"Failed to stat object: {exc}")
def copy_object(
self,
source_object: str,
dest_object: str,
) -> str:
"""Copy an object within the same bucket"""
try:
self.client.copy_object(
bucket_name=self._bucket,
object_name=dest_object,
source=self.client.fcopy_object(
bucket_name=self._bucket,
object_name=source_object,
),
)
logger.info(f"Copied: {source_object} -> {dest_object}")
return dest_object
except Exception as exc:
logger.error(f"Failed to copy '{source_object}' to '{dest_object}': {exc}")
raise StorageError(f"Failed to copy object: {exc}")
storage_service = StorageService()
"""
PLabel Backend - FastAPI Application Entry Point
"""
from contextlib import asynccontextmanager
from pathlib import Path
from fastapi import FastAPI, Request
from fastapi.middleware.cors import CORSMiddleware
from fastapi.responses import JSONResponse
from app.core.config import settings
from app.core.database import async_engine, close_db
from app.core.exceptions import register_exception_handlers
from app.core.logging import setup_logging
from app.core.middleware import RequestLogMiddleware
from app.core.redis import close_async_redis
@asynccontextmanager
async def lifespan(app: FastAPI):
"""Application lifespan events"""
# Startup
setup_logging()
yield
# Shutdown
await close_async_redis()
await close_db()
# Create FastAPI application
app = FastAPI(
title=settings.app_name,
description="AI Training Data Annotation Platform Backend",
version="1.0.0",
docs_url="/docs",
redoc_url="/redoc",
openapi_url="/openapi.json",
lifespan=lifespan,
)
# Configure CORS
app.add_middleware(
CORSMiddleware,
allow_origins=settings.cors_origins_list,
allow_credentials=True,
allow_methods=["*"],
allow_headers=["*"],
)
# Add request logging middleware
app.add_middleware(RequestLogMiddleware)
# Register exception handlers
register_exception_handlers(app)
@app.exception_handler(Exception)
async def global_exception_handler(request: Request, exc: Exception):
"""Global exception handler for unhandled exceptions"""
return JSONResponse(
status_code=500,
content={
"code": 500,
"message": "Internal server error",
"detail": str(exc) if settings.app_debug else "An error occurred"
}
)
@app.get("/")
async def root():
"""Root endpoint"""
return {
"name": settings.app_name,
"version": "1.0.0",
"status": "running"
}
@app.get("/health")
async def health_check():
"""Health check endpoint"""
return {"status": "healthy"}
# Import and include API routers
from app.api.v1 import api_router
app.include_router(api_router, prefix="/api/v1")
if __name__ == "__main__":
import uvicorn
uvicorn.run(
"app.main:app",
host=settings.host,
port=settings.port,
reload=settings.app_debug,
)
"""
PLabel Models Package
"""
from app.core.database import Base
from app.models.user import User
from app.models.project import Project
from app.models.project_member import ProjectMember
from app.models.label_set import LabelSet
from app.models.label import Label
from app.models.task import Task
from app.models.data_item import DataItem
from app.models.annotation import Annotation
from app.models.audio_annotation import AudioAnnotation
from app.models.text_entity import TextEntity
from app.models.text_relation import TextRelation
from app.models.review_session import ReviewSession, ReviewComment
from app.models.ai_model import AIModel
from app.models.auto_label_task import AutoLabelTask
__all__ = [
"Base",
"User",
"Project",
"ProjectMember",
"LabelSet",
"Label",
"Task",
"DataItem",
"Annotation",
"AudioAnnotation",
"TextEntity",
"TextRelation",
"ReviewSession",
"ReviewComment",
"AIModel",
"AutoLabelTask",
]
"""
AIModel model
"""
import uuid
from typing import TYPE_CHECKING
from sqlalchemy import Integer, String, Text, Float
from sqlalchemy import JSON
from sqlalchemy.dialects.postgresql import UUID
from sqlalchemy.orm import Mapped, mapped_column
from app.core.database import Base
class AIModel(Base):
"""AIModel model for AI model configurations"""
__tablename__ = "ai_models"
id: Mapped[uuid.UUID] = mapped_column(
UUID(as_uuid=True), primary_key=True, default=uuid.uuid4
)
name: Mapped[str] = mapped_column(String(200), nullable=False)
type: Mapped[str] = mapped_column(String(30), nullable=False)
description: Mapped[str | None] = mapped_column(Text, nullable=True)
framework: Mapped[str | None] = mapped_column(String(50), nullable=True)
model_path: Mapped[str | None] = mapped_column(String(500), nullable=True)
config: Mapped[dict] = mapped_column(JSON, default=dict)
accuracy: Mapped[float | None] = mapped_column(Float, nullable=True)
speed: Mapped[int | None] = mapped_column(Integer, nullable=True)
enabled: Mapped[bool] = mapped_column(default=True)
"""
Annotation model (image/video annotations)
"""
import uuid
from typing import TYPE_CHECKING
from sqlalchemy import Boolean, ForeignKey, Integer, String
from sqlalchemy import JSON
from sqlalchemy.dialects.postgresql import UUID
from sqlalchemy.orm import Mapped, mapped_column, relationship
from app.core.database import Base
if TYPE_CHECKING:
from app.models.data_item import DataItem
from app.models.user import User
from app.models.label import Label
class Annotation(Base):
"""Annotation model for image/video bounding boxes, polygons, keypoints etc."""
__tablename__ = "annotations"
id: Mapped[uuid.UUID] = mapped_column(
UUID(as_uuid=True), primary_key=True, default=uuid.uuid4
)
data_item_id: Mapped[uuid.UUID] = mapped_column(
UUID(as_uuid=True), ForeignKey("data_items.id", ondelete="CASCADE"), nullable=False, index=True
)
user_id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), ForeignKey("users.id"), nullable=False, index=True)
label_id: Mapped[uuid.UUID | None] = mapped_column(UUID(as_uuid=True), ForeignKey("labels.id"), nullable=True)
annotation_type: Mapped[str] = mapped_column(String(30), nullable=False)
label_name: Mapped[str] = mapped_column(String(100), nullable=False)
data: Mapped[dict] = mapped_column(JSON, nullable=False)
visible: Mapped[bool] = mapped_column(Boolean, default=True)
occluded: Mapped[bool] = mapped_column(Boolean, default=False)
ignored: Mapped[bool] = mapped_column(Boolean, default=False)
frame_index: Mapped[int] = mapped_column(Integer, default=0, index=True)
data_item: Mapped["DataItem"] = relationship("DataItem", back_populates="annotations")
"""
AudioAnnotation model
"""
import uuid
from typing import TYPE_CHECKING
from sqlalchemy import Float, ForeignKey, String
from sqlalchemy import JSON
from sqlalchemy.dialects.postgresql import UUID
from sqlalchemy.orm import Mapped, mapped_column, relationship
from app.core.database import Base
if TYPE_CHECKING:
from app.models.data_item import DataItem
from app.models.user import User
class AudioAnnotation(Base):
"""AudioAnnotation model for speech transcription with timestamps"""
__tablename__ = "audio_annotations"
id: Mapped[uuid.UUID] = mapped_column(
UUID(as_uuid=True), primary_key=True, default=uuid.uuid4
)
data_item_id: Mapped[uuid.UUID] = mapped_column(
UUID(as_uuid=True), ForeignKey("data_items.id", ondelete="CASCADE"), nullable=False, index=True
)
user_id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), ForeignKey("users.id"), nullable=False, index=True)
start_time: Mapped[float] = mapped_column(Float, nullable=False)
end_time: Mapped[float] = mapped_column(Float, nullable=False)
text: Mapped[str | None] = mapped_column(nullable=True)
speaker: Mapped[str | None] = mapped_column(String(100), nullable=True)
labels: Mapped[list] = mapped_column(JSON, default=list)
confidence: Mapped[float | None] = mapped_column(Float, nullable=True)
data_item: Mapped["DataItem"] = relationship("DataItem")
"""
AutoLabelTask model
"""
import uuid
from typing import TYPE_CHECKING, Optional
from sqlalchemy import DateTime, ForeignKey, Integer, String, Text
from sqlalchemy import JSON
from sqlalchemy.dialects.postgresql import UUID
from sqlalchemy.orm import Mapped, mapped_column, relationship
from app.core.database import Base
if TYPE_CHECKING:
from app.models.task import Task
from app.models.user import User
from app.models.ai_model import AIModel
class AutoLabelTask(Base):
"""AutoLabelTask model for AI-assisted auto-labeling jobs"""
__tablename__ = "auto_label_tasks"
id: Mapped[uuid.UUID] = mapped_column(
UUID(as_uuid=True), primary_key=True, default=uuid.uuid4
)
task_id: Mapped[uuid.UUID] = mapped_column(
UUID(as_uuid=True), ForeignKey("tasks.id", ondelete="CASCADE"), nullable=False, index=True
)
user_id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), ForeignKey("users.id"), nullable=False)
model_id: Mapped[uuid.UUID] = mapped_column(
UUID(as_uuid=True), ForeignKey("ai_models.id"), nullable=False, index=True
)
status: Mapped[str] = mapped_column(String(20), nullable=False, default="pending", index=True)
progress: Mapped[int] = mapped_column(Integer, default=0)
config: Mapped[dict] = mapped_column(JSON, default=dict)
result: Mapped[Optional[dict]] = mapped_column(JSON, nullable=True)
error: Mapped[str | None] = mapped_column(Text, nullable=True)
data_item_ids: Mapped[list] = mapped_column(JSON, default=list)
started_at: Mapped[Optional[uuid.UUID]] = mapped_column(nullable=True)
completed_at: Mapped[Optional[uuid.UUID]] = mapped_column(nullable=True)
task: Mapped["Task"] = relationship("Task")
ai_model: Mapped["AIModel"] = relationship("AIModel")
"""
Base model classes and mixins
Note: The actual ORM Base class is defined in app.core.database (Base).
These mixins are composed with Base in each model.
"""
import uuid
from datetime import datetime
from sqlalchemy import DateTime, func
from sqlalchemy.dialects.postgresql import UUID
from sqlalchemy.orm import Mapped, declared_attr
class TimestampMixin:
"""Mixin that adds created_at and updated_at timestamp columns"""
created_at: Mapped[datetime] = mapped_column(
DateTime(timezone=True),
server_default=func.now(),
nullable=False,
)
updated_at: Mapped[datetime] = mapped_column(
DateTime(timezone=True),
server_default=func.now(),
onupdate=func.now(),
nullable=False,
)
"""
DataItem model
"""
from typing import TYPE_CHECKING, Optional
from sqlalchemy import BigInteger, Float, ForeignKey, Integer, String
from sqlalchemy import JSON
from sqlalchemy.orm import Mapped, mapped_column, relationship
from app.core.database import Base
if TYPE_CHECKING:
from app.models.task import Task
from app.models.annotation import Annotation
class DataItem(Base):
"""DataItem model for uploaded files/data samples"""
__tablename__ = "data_items"
id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
task_id: Mapped[int] = mapped_column(
Integer, ForeignKey("tasks.id", ondelete="CASCADE"), nullable=False, index=True
)
name: Mapped[str] = mapped_column(String(500), nullable=False)
type: Mapped[str] = mapped_column(String(20), nullable=False, index=True)
file_path: Mapped[str] = mapped_column(String(1000), nullable=False)
thumbnail_path: Mapped[Optional[str]] = mapped_column(String(1000), nullable=True)
size: Mapped[int] = mapped_column(BigInteger, nullable=False)
mime_type: Mapped[Optional[str]] = mapped_column(String(100), nullable=True)
width: Mapped[Optional[int]] = mapped_column(Integer, nullable=True)
height: Mapped[Optional[int]] = mapped_column(Integer, nullable=True)
duration: Mapped[Optional[float]] = mapped_column(Float, nullable=True)
pages: Mapped[Optional[int]] = mapped_column(Integer, nullable=True)
meta: Mapped[dict] = mapped_column(JSON, default=dict)
annotation_status: Mapped[str] = mapped_column(String(20), default="none", index=True)
task: Mapped["Task"] = relationship("Task", back_populates="data_items")
annotations: Mapped[list["Annotation"]] = relationship("Annotation", back_populates="data_item", cascade="all, delete-orphan")
"""
Label model
"""
from typing import TYPE_CHECKING, Optional
from sqlalchemy import ForeignKey, Integer, String
from sqlalchemy import JSON
from sqlalchemy.orm import Mapped, mapped_column, relationship
from app.core.database import Base
if TYPE_CHECKING:
from app.models.label_set import LabelSet
class Label(Base):
"""Label model for annotation categories"""
__tablename__ = "labels"
id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
label_set_id: Mapped[int] = mapped_column(
Integer, ForeignKey("label_sets.id", ondelete="CASCADE"), nullable=False, index=True
)
name: Mapped[str] = mapped_column(String(100), nullable=False)
color: Mapped[str] = mapped_column(String(7), nullable=False)
type: Mapped[str] = mapped_column(String(30), nullable=False, index=True)
shortcut: Mapped[Optional[str]] = mapped_column(String(10), nullable=True)
parent_id: Mapped[Optional[int]] = mapped_column(Integer, ForeignKey("labels.id"), nullable=True)
attributes: Mapped[dict] = mapped_column(JSON, default=list)
label_set: Mapped["LabelSet"] = relationship("LabelSet", back_populates="labels")
"""
LabelSet model
"""
from typing import TYPE_CHECKING, Optional
from sqlalchemy import ForeignKey, Integer, String
from sqlalchemy.orm import Mapped, mapped_column, relationship
from app.core.database import Base
if TYPE_CHECKING:
from app.models.project import Project
from app.models.label import Label
class LabelSet(Base):
"""LabelSet model for grouping labels within a project"""
__tablename__ = "label_sets"
id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
project_id: Mapped[Optional[int]] = mapped_column(
Integer, ForeignKey("projects.id", ondelete="CASCADE"), nullable=True, index=True
)
name: Mapped[str] = mapped_column(String(200), nullable=False)
project: Mapped[Optional["Project"]] = relationship("Project", back_populates="label_set")
labels: Mapped[list["Label"]] = relationship("Label", back_populates="label_set", cascade="all, delete-orphan")
"""
Project model
"""
from typing import TYPE_CHECKING, Optional
from sqlalchemy import ForeignKey, Integer, String, Text
from sqlalchemy.orm import Mapped, mapped_column, relationship
from app.core.database import Base
if TYPE_CHECKING:
from app.models.user import User
from app.models.label_set import LabelSet
from app.models.task import Task
from app.models.project_member import ProjectMember
class Project(Base):
"""Project model for organizing annotation tasks"""
__tablename__ = "projects"
id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
name: Mapped[str] = mapped_column(String(200), nullable=False)
description: Mapped[Optional[str]] = mapped_column(Text, nullable=True)
status: Mapped[str] = mapped_column(String(20), nullable=False, default="active", index=True)
owner_id: Mapped[int] = mapped_column(
Integer, ForeignKey("users.id", ondelete="CASCADE"), nullable=False, index=True
)
label_set_id: Mapped[Optional[int]] = mapped_column(Integer, nullable=True)
owner: Mapped["User"] = relationship("User", back_populates="owned_projects")
label_set: Mapped[Optional["LabelSet"]] = relationship("LabelSet", foreign_keys=[label_set_id], post_update=True)
tasks: Mapped[list["Task"]] = relationship("Task", back_populates="project", cascade="all, delete-orphan")
members: Mapped[list["ProjectMember"]] = relationship("ProjectMember", back_populates="project", cascade="all, delete-orphan")
"""
ProjectMember model
"""
from typing import TYPE_CHECKING
from sqlalchemy import ForeignKey, Integer, String
from sqlalchemy.orm import Mapped, mapped_column, relationship
from app.core.database import Base
if TYPE_CHECKING:
from app.models.project import Project
from app.models.user import User
class ProjectMember(Base):
"""ProjectMember model for project access control"""
__tablename__ = "project_members"
id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
project_id: Mapped[int] = mapped_column(
Integer, ForeignKey("projects.id", ondelete="CASCADE"), nullable=False, index=True
)
user_id: Mapped[int] = mapped_column(
Integer, ForeignKey("users.id", ondelete="CASCADE"), nullable=False, index=True
)
role: Mapped[str] = mapped_column(String(20), nullable=False, default="member")
project: Mapped["Project"] = relationship("Project", back_populates="members")
user: Mapped["User"] = relationship("User", back_populates="project_memberships")
"""
ReviewSession and ReviewComment models
"""
import uuid
from typing import TYPE_CHECKING
from sqlalchemy import ForeignKey, String, Text
from sqlalchemy import Boolean
from sqlalchemy.dialects.postgresql import UUID
from sqlalchemy.orm import Mapped, mapped_column, relationship
from app.core.database import Base
if TYPE_CHECKING:
from app.models.task import Task
from app.models.data_item import DataItem
from app.models.user import User
class ReviewSession(Base):
"""ReviewSession model for annotation quality review"""
__tablename__ = "review_sessions"
id: Mapped[uuid.UUID] = mapped_column(
UUID(as_uuid=True), primary_key=True, default=uuid.uuid4
)
task_id: Mapped[uuid.UUID] = mapped_column(
UUID(as_uuid=True), ForeignKey("tasks.id", ondelete="CASCADE"), nullable=False, index=True
)
data_item_id: Mapped[uuid.UUID] = mapped_column(
UUID(as_uuid=True), ForeignKey("data_items.id", ondelete="CASCADE"), nullable=False, index=True
)
reviewer_id: Mapped[uuid.UUID] = mapped_column(
UUID(as_uuid=True), ForeignKey("users.id"), nullable=False, index=True
)
annotator_id: Mapped[uuid.UUID | None] = mapped_column(UUID(as_uuid=True), ForeignKey("users.id"), nullable=True)
status: Mapped[str] = mapped_column(String(20), nullable=False, default="pending", index=True)
task: Mapped["Task"] = relationship("Task")
data_item: Mapped["DataItem"] = relationship("DataItem")
reviewer: Mapped["User"] = relationship("User", foreign_keys=[reviewer_id])
annotator: Mapped["User | None"] = relationship("User", foreign_keys=[annotator_id])
comments: Mapped[list["ReviewComment"]] = relationship("ReviewComment", back_populates="session", cascade="all, delete-orphan")
class ReviewComment(Base):
"""ReviewComment model for review feedback"""
__tablename__ = "review_comments"
id: Mapped[uuid.UUID] = mapped_column(
UUID(as_uuid=True), primary_key=True, default=uuid.uuid4
)
session_id: Mapped[uuid.UUID] = mapped_column(
UUID(as_uuid=True), ForeignKey("review_sessions.id", ondelete="CASCADE"), nullable=False, index=True
)
reviewer_id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), ForeignKey("users.id"), nullable=False)
annotation_id: Mapped[uuid.UUID | None] = mapped_column(UUID(as_uuid=True), nullable=True)
content: Mapped[str] = mapped_column(Text, nullable=False)
resolved: Mapped[bool] = mapped_column(Boolean, default=False)
session: Mapped["ReviewSession"] = relationship("ReviewSession", back_populates="comments")
"""
Task model
"""
from typing import TYPE_CHECKING, Optional
from sqlalchemy import ForeignKey, Integer, String, Text
from sqlalchemy import JSON
from sqlalchemy.orm import Mapped, mapped_column, relationship
from app.core.database import Base
if TYPE_CHECKING:
from app.models.project import Project
from app.models.user import User
from app.models.ai_model import AIModel
from app.models.data_item import DataItem
class Task(Base):
"""Task model for annotation work units"""
__tablename__ = "tasks"
id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
project_id: Mapped[int] = mapped_column(
Integer, ForeignKey("projects.id", ondelete="CASCADE"), nullable=False, index=True
)
name: Mapped[str] = mapped_column(String(200), nullable=False)
description: Mapped[Optional[str]] = mapped_column(Text, nullable=True)
data_type: Mapped[str] = mapped_column(String(20), nullable=False, index=True)
annotation_types: Mapped[list] = mapped_column(JSON, default=list)
status: Mapped[str] = mapped_column(String(20), nullable=False, default="pending", index=True)
assignee_id: Mapped[Optional[int]] = mapped_column(Integer, ForeignKey("users.id"), nullable=True, index=True)
reviewer_id: Mapped[Optional[int]] = mapped_column(Integer, ForeignKey("users.id"), nullable=True)
ai_model_id: Mapped[Optional[int]] = mapped_column(Integer, ForeignKey("ai_models.id"), nullable=True)
progress: Mapped[int] = mapped_column(Integer, default=0)
total_count: Mapped[int] = mapped_column(Integer, default=0)
completed_count: Mapped[int] = mapped_column(Integer, default=0)
reviewed_count: Mapped[int] = mapped_column(Integer, default=0)
rejected_count: Mapped[int] = mapped_column(Integer, default=0)
project: Mapped["Project"] = relationship("Project", back_populates="tasks")
assignee: Mapped[Optional["User"]] = relationship("User", foreign_keys=[assignee_id])
reviewer: Mapped[Optional["User"]] = relationship("User", foreign_keys=[reviewer_id])
ai_model: Mapped[Optional["AIModel"]] = relationship("AIModel")
data_items: Mapped[list["DataItem"]] = relationship("DataItem", back_populates="task", cascade="all, delete-orphan")
"""
TextEntity model
"""
import uuid
from typing import TYPE_CHECKING
from sqlalchemy import ForeignKey, Integer, String
from sqlalchemy import JSON
from sqlalchemy.dialects.postgresql import UUID
from sqlalchemy.orm import Mapped, mapped_column, relationship
from app.core.database import Base
if TYPE_CHECKING:
from app.models.data_item import DataItem
from app.models.user import User
class TextEntity(Base):
"""TextEntity model for named entity recognition"""
__tablename__ = "text_entities"
id: Mapped[uuid.UUID] = mapped_column(
UUID(as_uuid=True), primary_key=True, default=uuid.uuid4
)
data_item_id: Mapped[uuid.UUID] = mapped_column(
UUID(as_uuid=True), ForeignKey("data_items.id", ondelete="CASCADE"), nullable=False, index=True
)
user_id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), ForeignKey("users.id"), nullable=False, index=True)
label_id: Mapped[uuid.UUID | None] = mapped_column(UUID(as_uuid=True), ForeignKey("labels.id"), nullable=True)
label_name: Mapped[str] = mapped_column(String(100), nullable=False)
start_offset: Mapped[int] = mapped_column(Integer, nullable=False)
end_offset: Mapped[int] = mapped_column(Integer, nullable=False)
text: Mapped[str] = mapped_column(String(1000), nullable=False)
color: Mapped[str | None] = mapped_column(String(7), nullable=True)
attributes: Mapped[dict] = mapped_column(JSON, default=dict)
data_item: Mapped["DataItem"] = relationship("DataItem")
"""
TextRelation model
"""
import uuid
from typing import TYPE_CHECKING
from sqlalchemy import ForeignKey, String
from sqlalchemy.dialects.postgresql import UUID
from sqlalchemy.orm import Mapped, mapped_column
from app.core.database import Base
if TYPE_CHECKING:
from app.models.data_item import DataItem
from app.models.user import User
class TextRelation(Base):
"""TextRelation model for entity relationship annotation"""
__tablename__ = "text_relations"
id: Mapped[uuid.UUID] = mapped_column(
UUID(as_uuid=True), primary_key=True, default=uuid.uuid4
)
data_item_id: Mapped[uuid.UUID] = mapped_column(
UUID(as_uuid=True), ForeignKey("data_items.id", ondelete="CASCADE"), nullable=False, index=True
)
user_id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), ForeignKey("users.id"), nullable=False, index=True)
from_entity_id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), ForeignKey("text_entities.id"), nullable=False)
to_entity_id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), ForeignKey("text_entities.id"), nullable=False)
label: Mapped[str] = mapped_column(String(100), nullable=False)
relation_type: Mapped[str] = mapped_column(String(20), default="undirected")
"""
User model
"""
import uuid
from typing import TYPE_CHECKING, Optional
from sqlalchemy import Boolean, String
from sqlalchemy.dialects.postgresql import UUID
from sqlalchemy.orm import Mapped, mapped_column, relationship
from app.core.database import Base
if TYPE_CHECKING:
from app.models.project import Project
from app.models.project_member import ProjectMember
class User(Base):
"""User model for authentication and authorization"""
__tablename__ = "users"
id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
username: Mapped[str] = mapped_column(String(50), unique=True, nullable=False, index=True)
email: Mapped[str] = mapped_column(String(255), unique=True, nullable=False, index=True)
password_hash: Mapped[str] = mapped_column(String(255), nullable=False)
avatar_url: Mapped[Optional[str]] = mapped_column(String(500), nullable=True)
role: Mapped[str] = mapped_column(String(20), nullable=False, default="user", index=True)
is_active: Mapped[bool] = mapped_column(Boolean, default=True, nullable=False)
owned_projects: Mapped[list["Project"]] = relationship(
"Project", back_populates="owner", cascade="all, delete-orphan"
)
project_memberships: Mapped[list["ProjectMember"]] = relationship(
"ProjectMember", back_populates="user", cascade="all, delete-orphan"
)
def __repr__(self) -> str:
return f"<User(id={self.id}, username={self.username}, role={self.role})>"
"""
PLabel Schemas Package
"""
from app.schemas.base import BaseSchema, ErrorResponseSchema, PaginationSchema, ResponseSchema
from app.schemas.auth import (
ChangePasswordRequest,
LoginRequest,
LoginResponse,
RegisterRequest,
TokenPayload,
TokenResponse,
UserResponse,
)
from app.schemas.user import (
UserCreate,
UserInDB,
UserStatsResponse,
UserUpdate,
)
from app.schemas.project import (
ProjectCreate,
ProjectMemberAdd,
ProjectMemberResponse,
ProjectStatistics,
ProjectUpdate,
)
from app.schemas.label import (
LabelCreate,
LabelSchema,
LabelSetCreate,
LabelSetUpdate,
LabelUpdate,
)
from app.schemas.task import (
DataType,
TaskCreate,
TaskProgressResponse,
TaskStatus,
TaskUpdate,
)
from app.schemas.data_item import (
AnnotationStatus,
DataItemMetadata,
DataItemUpdate,
)
from app.schemas.annotation import (
AnnotationCreate,
AnnotationType,
AudioAnnotationCreate,
BatchAnnotationRequest,
BoundingBoxData,
BrushData,
KeypointData,
PolygonData,
SkeletonData,
TextEntityCreate,
TextRelationCreate,
)
from app.schemas.review import (
BatchReviewRequest,
ReviewAction,
ReviewCommentCreate,
ReviewSessionCreate,
ReviewStatus,
)
from app.schemas.ai_model import (
AIModelCreate,
AIModelTestRequest,
AIModelType,
AIModelUpdate,
)
from app.schemas.autolabel import (
AutoLabelProgressResponse,
AutoLabelStatus,
AutoLabelTaskCreate,
)
from app.schemas.export import (
ExportFormat,
ExportOptions,
ExportStatus,
ExportTaskCreate,
)
from app.schemas.statistics import (
DashboardStats,
TaskStatistics,
WeeklyReportStats,
)
from app.schemas.upload import (
MultipartUploadInit,
MultipartUploadPart,
PresignedUrlRequest,
PresignedUrlResponse,
)
__all__ = [
"BaseSchema",
"PaginationSchema",
"ResponseSchema",
"ErrorResponseSchema",
"LoginRequest",
"RegisterRequest",
"LoginResponse",
"TokenResponse",
"TokenPayload",
"UserResponse",
"UserCreate",
"UserUpdate",
"UserInDB",
"UserStatsResponse",
"ProjectCreate",
"ProjectUpdate",
"ProjectMemberAdd",
"ProjectMemberResponse",
"ProjectStatistics",
"LabelSetCreate",
"LabelSetUpdate",
"LabelCreate",
"LabelUpdate",
"LabelSchema",
"TaskStatus",
"DataType",
"TaskCreate",
"TaskUpdate",
"TaskProgressResponse",
"AnnotationStatus",
"DataItemUpdate",
"DataItemMetadata",
"AnnotationType",
"AnnotationCreate",
"BatchAnnotationRequest",
"BoundingBoxData",
"PolygonData",
"BrushData",
"KeypointData",
"SkeletonData",
"AudioAnnotationCreate",
"TextEntityCreate",
"TextRelationCreate",
"ReviewStatus",
"ReviewSessionCreate",
"ReviewAction",
"BatchReviewRequest",
"ReviewCommentCreate",
"AIModelType",
"AIModelCreate",
"AIModelUpdate",
"AIModelTestRequest",
"AutoLabelStatus",
"AutoLabelTaskCreate",
"AutoLabelProgressResponse",
"ExportFormat",
"ExportStatus",
"ExportTaskCreate",
"ExportOptions",
"DashboardStats",
"TaskStatistics",
"WeeklyReportStats",
"PresignedUrlRequest",
"PresignedUrlResponse",
"MultipartUploadInit",
"MultipartUploadPart",
]
"""
AI Model schemas
"""
from datetime import datetime
from enum import Enum
from pydantic import BaseModel, Field
from app.schemas.base import BaseSchema
class AIModelType(str, Enum):
OBJECT_DETECTION = "object_detection"
SEGMENTATION = "segmentation"
KEYPOINT = "keypoint"
CLASSIFICATION = "classification"
ASR = "asr"
NER = "ner"
OCR = "ocr"
class AIModelCreate(BaseModel):
name: str = Field(min_length=1, max_length=200)
type: AIModelType
description: str | None = None
framework: str | None = None
model_path: str | None = None
config: dict = {}
accuracy: float | None = Field(default=None, le=1.0, ge=0.0)
speed: int | None = None
class AIModelUpdate(BaseModel):
name: str | None = None
description: str | None = None
config: dict | None = None
enabled: bool | None = None
class AIModelTestRequest(BaseModel):
input_data: dict
"""
Annotation schemas
"""
from datetime import datetime
from enum import Enum
from pydantic import BaseModel, Field
from app.schemas.base import BaseSchema
class AnnotationType(str, Enum):
RECTANGLE = "rectangle"
POLYGON = "polygon"
BRUSH = "brush"
KEYPOINT = "keypoint"
SKELETON = "skeleton"
TEXT = "text"
class BoundingBoxData(BaseModel):
x: float
y: float
width: float
height: float
rotation: float = 0
class PolygonData(BaseModel):
points: list[dict]
closed: bool = True
class BrushData(BaseModel):
mask: str
width: int
height: int
class KeypointData(BaseModel):
points: list[dict]
class SkeletonData(BaseModel):
points: list[dict]
connections: list[list[int]]
template_id: str | None = None
class AnnotationCreate(BaseModel):
data_item_id: str
label_id: str | None = None
type: AnnotationType
data: dict
frame_index: int = 0
visible: bool = True
occluded: bool = False
ignored: bool = False
class BatchAnnotationRequest(BaseModel):
data_item_id: str
frame_index: int = 0
annotations: list[AnnotationCreate]
class AudioAnnotationCreate(BaseModel):
data_item_id: str
start_time: float = Field(ge=0)
end_time: float = Field(gt=0)
text: str | None = None
speaker: str | None = None
labels: list[str] = []
class TextEntityCreate(BaseModel):
data_item_id: str
label_id: str | None = None
start_offset: int = Field(ge=0)
end_offset: int = Field(gt=0)
text: str
attributes: dict = {}
class TextRelationCreate(BaseModel):
data_item_id: str
from_entity_id: str
to_entity_id: str
label: str
relation_type: str = "undirected"
"""
Auth schemas
"""
from pydantic import BaseModel, EmailStr, Field
from app.schemas.base import BaseSchema
class LoginRequest(BaseModel):
identifier: str = Field(..., description="邮箱或用户名")
password: str
class RegisterRequest(BaseModel):
username: str = Field(min_length=2, max_length=50)
email: EmailStr
password: str = Field(min_length=8, max_length=128)
class TokenResponse(BaseSchema):
access_token: str
token_type: str = "bearer"
expires_in: int
class UserResponse(BaseSchema):
id: str
username: str
email: str
role: str
avatar_url: str | None = None
is_active: bool = True
class LoginResponse(BaseSchema):
access_token: str
token_type: str = "bearer"
expires_in: int
user: UserResponse
class ChangePasswordRequest(BaseModel):
old_password: str
new_password: str = Field(min_length=8, max_length=128)
class TokenPayload(BaseModel):
sub: str
email: str
role: str
exp: int
iat: int
"""
AutoLabel schemas
"""
from datetime import datetime
from enum import Enum
from pydantic import BaseModel, Field
from app.schemas.base import BaseSchema
class AutoLabelStatus(str, Enum):
PENDING = "pending"
RUNNING = "running"
COMPLETED = "completed"
FAILED = "failed"
CANCELLED = "cancelled"
class AutoLabelTaskCreate(BaseModel):
task_id: str
data_item_ids: list[str] = []
model_id: str
config: dict = {}
class AutoLabelProgressResponse(BaseSchema):
status: str
progress: int = 0
processed_count: int = 0
total_count: int = 0
started_at: datetime | None = None
completed_at: datetime | None = None
error: str | None = None
"""
Base Pydantic schemas
"""
from datetime import datetime
from typing import Any, Generic, TypeVar
from pydantic import BaseModel, ConfigDict, Field
class BaseSchema(BaseModel):
"""Base schema with common configuration"""
model_config = ConfigDict(from_attributes=True)
class PaginationSchema(BaseSchema):
"""Pagination response base"""
items: list[Any]
total: int = Field(ge=0, description="Total number of records")
page: int = Field(ge=1, description="Current page number")
page_size: int = Field(ge=1, le=100, description="Number of records per page")
total_pages: int = Field(ge=0, description="Total number of pages")
class ResponseSchema(BaseSchema):
"""Standard API response wrapper"""
code: int = 200
message: str = "success"
data: Any = None
class ErrorResponseSchema(BaseSchema):
"""Standard error response"""
code: int = 400
message: str
errors: list[dict] | None = None
details: Any = None
"""
DataItem schemas
"""
from datetime import datetime
from enum import Enum
from pydantic import BaseModel, Field
from app.schemas.base import BaseSchema
class AnnotationStatus(str, Enum):
NONE = "none"
PARTIAL = "partial"
COMPLETED = "completed"
REJECTED = "rejected"
class DataItemUpdate(BaseModel):
name: str | None = None
metadata: dict | None = Field(default=None, validation_alias="meta")
class DataItemMetadata(BaseSchema):
width: int | None = None
height: int | None = None
duration: float | None = None
pages: int | None = None
format: str | None = None
fps: float | None = None
frame_count: int | None = None
char_count: int | None = None
word_count: int | None = None
"""
Export schemas
"""
from datetime import datetime
from enum import Enum
from pydantic import BaseModel, Field
from app.schemas.base import BaseSchema
class ExportFormat(str, Enum):
COCO_JSON = "coco_json"
VOC_XML = "voc_xml"
YOLO_TXT = "yolo_txt"
MASK_PNG = "mask_png"
COCO_KEYPOINT = "coco_keypoint"
SRT = "srt"
VTT = "vtt"
TEXTGRID = "textgrid"
JSON = "json"
CSV = "csv"
CONLL = "conll"
BIO = "bio"
class ExportStatus(str, Enum):
PENDING = "pending"
RUNNING = "running"
COMPLETED = "completed"
FAILED = "failed"
class ExportTaskCreate(BaseModel):
task_id: str
format: ExportFormat
options: dict = {}
class ExportOptions(BaseSchema):
include_images: bool = True
split_ratio: float = 0.8
annotation_types: list[str] = []
"""
Label schemas
"""
from datetime import datetime
from pydantic import BaseModel, Field
from app.schemas.base import BaseSchema
class LabelCreate(BaseModel):
name: str = Field(min_length=1, max_length=100)
color: str = Field(pattern=r"^#[0-9A-Fa-f]{6}$")
type: str = Field(description="rectangle/polygon/brush/keypoint/skeleton/text/classification/relation")
shortcut: str | None = Field(default=None, max_length=10)
parent_id: str | None = None
attributes: list[dict] = []
class LabelUpdate(BaseModel):
name: str | None = Field(default=None, min_length=1, max_length=100)
color: str | None = Field(default=None, pattern=r"^#[0-9A-Fa-f]{6}$")
shortcut: str | None = Field(default=None, max_length=10)
attributes: list[dict] | None = None
class LabelSchema(BaseSchema):
id: str
label_set_id: str
name: str
color: str
type: str
shortcut: str | None = None
parent_id: str | None = None
attributes: list[dict] = []
created_at: datetime
class LabelSetCreate(BaseModel):
name: str = Field(min_length=1, max_length=200)
class LabelSetUpdate(BaseModel):
name: str | None = Field(default=None, min_length=1, max_length=200)
labels: list[LabelCreate] = []
"""
Project schemas
"""
from datetime import datetime
from typing import Any
from pydantic import BaseModel, Field
from app.schemas.base import BaseSchema
class ProjectCreate(BaseModel):
name: str = Field(min_length=1, max_length=200)
description: str | None = None
class ProjectUpdate(BaseModel):
name: str | None = Field(default=None, min_length=1, max_length=200)
description: str | None = None
status: str | None = None
class ProjectMemberAdd(BaseModel):
user_id: str
role: str = "member"
class ProjectMemberResponse(BaseSchema):
id: str
project_id: str
user_id: str
role: str
joined_at: datetime
class ProjectStatistics(BaseSchema):
total_tasks: int = 0
completed_tasks: int = 0
pending_tasks: int = 0
in_progress_tasks: int = 0
reviewed_tasks: int = 0
total_annotations: int = 0
total_members: int = 0
progress_percentage: float = 0.0
"""
Review schemas
"""
from datetime import datetime
from enum import Enum
from pydantic import BaseModel, Field
from app.schemas.base import BaseSchema
class ReviewStatus(str, Enum):
PENDING = "pending"
APPROVED = "approved"
REJECTED = "rejected"
class ReviewSessionCreate(BaseModel):
task_id: str
data_item_id: str
class ReviewAction(BaseModel):
comments: str | None = None
reason: str | None = None
annotation_ids: list[str] | None = None
class BatchReviewRequest(BaseModel):
task_id: str
data_item_ids: list[str]
action: str = Field(pattern="^(approve|reject)$")
reason: str | None = None
class ReviewCommentCreate(BaseModel):
content: str = Field(min_length=1)
annotation_id: str | None = None
"""
Statistics schemas
"""
from pydantic import BaseModel, Field
from app.schemas.base import BaseSchema
class DashboardStats(BaseSchema):
total_projects: int = 0
total_tasks: int = 0
total_annotations: int = 0
pending_tasks: int = 0
in_progress_tasks: int = 0
completed_tasks: int = 0
reviewed_tasks: int = 0
class TaskStatistics(BaseSchema):
by_status: dict[str, int] = {}
by_data_type: dict[str, int] = {}
total: int = 0
class WeeklyReportStats(BaseSchema):
week: str
annotation_count: int = 0
task_completed_count: int = 0
review_approved_count: int = 0
review_rejected_count: int = 0
daily_counts: list[dict] = []
"""
Task schemas
"""
from datetime import datetime
from enum import Enum
from pydantic import BaseModel, Field
from app.schemas.base import BaseSchema
class TaskStatus(str, Enum):
PENDING = "pending"
IN_PROGRESS = "in_progress"
SUBMITTED = "submitted"
REJECTED = "rejected"
REVIEWED = "reviewed"
EXPORTED = "exported"
PAUSED = "paused"
class DataType(str, Enum):
IMAGE = "image"
VIDEO = "video"
AUDIO = "audio"
TEXT = "text"
class TaskCreate(BaseModel):
project_id: str
name: str = Field(min_length=1, max_length=200)
description: str | None = None
data_type: DataType
annotation_types: list[str] = []
assignee_id: str | None = None
ai_model_id: str | None = None
class TaskUpdate(BaseModel):
name: str | None = Field(default=None, min_length=1, max_length=200)
description: str | None = None
status: TaskStatus | None = None
assignee_id: str | None = None
reviewer_id: str | None = None
ai_model_id: str | None = None
class TaskProgressResponse(BaseSchema):
progress: int = 0
total_count: int = 0
completed_count: int = 0
reviewed_count: int = 0
rejected_count: int = 0
"""
Upload schemas
"""
from pydantic import BaseModel
from app.schemas.base import BaseSchema
class PresignedUrlRequest(BaseModel):
file_name: str
content_type: str
class PresignedUrlResponse(BaseSchema):
upload_url: str
file_key: str
expires_in: int
class MultipartUploadInit(BaseModel):
file_name: str
file_size: int
content_type: str
class MultipartUploadPart(BaseModel):
part_number: int
etag: str
"""
User schemas
"""
from datetime import datetime
from typing import Any
from pydantic import BaseModel, EmailStr, Field
from app.schemas.base import BaseSchema
class UserBase(BaseSchema):
username: str = Field(min_length=2, max_length=50)
email: EmailStr
role: str = "user"
avatar_url: str | None = None
is_active: bool = True
class UserCreate(BaseModel):
username: str = Field(min_length=2, max_length=50)
email: EmailStr
password: str = Field(min_length=8, max_length=128)
role: str = "user"
class UserUpdate(BaseModel):
username: str | None = Field(default=None, min_length=2, max_length=50)
email: EmailStr | None = None
avatar_url: str | None = None
role: str | None = None
is_active: bool | None = None
class UserInDB(BaseSchema):
id: str
username: str
email: str
password_hash: str
role: str
avatar_url: str | None = None
is_active: bool
created_at: datetime
updated_at: datetime
class UserStatsResponse(BaseSchema):
total_annotations: int = 0
completed_tasks: int = 0
reviewed_tasks: int = 0
weekly_annotation_count: int = 0
total_working_hours: float = 0.0
class UserResponse(BaseSchema):
"""Response schema for user data"""
id: str
username: str
email: str
role: str
avatar_url: str | None = None
is_active: bool = True
"""
Authentication service for user login, registration, and token management
"""
from datetime import timedelta
from sqlalchemy import select
from sqlalchemy.ext.asyncio import AsyncSession
from app.core.exceptions import AuthenticationError, ConflictError, ValidationError
from app.core.security import create_access_token, hash_password, verify_password
from app.models.user import User
from app.schemas.auth import LoginRequest, RegisterRequest
class AuthService:
"""Service for handling authentication operations"""
def __init__(self, db: AsyncSession):
self.db = db
async def authenticate_user(self, identifier: str, password: str) -> User:
"""
Authenticate user by email or username and password
Args:
identifier: Email address or username
password: User password
"""
from sqlalchemy import or_
# Try to find user by email or username
result = await self.db.execute(
select(User).where(
or_(
User.email == identifier,
User.username == identifier
)
)
)
user = result.scalar_one_or_none()
if not user:
raise AuthenticationError("Invalid email/username or password")
if not verify_password(password, user.password_hash):
raise AuthenticationError("Invalid email/username or password")
if not user.is_active:
raise AuthenticationError("User account is disabled")
return user
async def login(self, login_data: LoginRequest) -> tuple[User, str]:
"""
Login user and return user and access token
Returns:
Tuple of (User, access_token)
"""
user = await self.authenticate_user(login_data.identifier, login_data.password)
access_token = create_access_token(
data={
"sub": str(user.id),
"email": user.email,
"role": user.role,
}
)
return user, access_token
async def register(self, register_data: RegisterRequest) -> User:
"""Register a new user"""
existing_email = await self.db.execute(
select(User).where(User.email == register_data.email)
)
if existing_email.scalar_one_or_none():
raise ConflictError("Email already registered")
existing_username = await self.db.execute(
select(User).where(User.username == register_data.username)
)
if existing_username.scalar_one_or_none():
raise ConflictError("Username already taken")
if len(register_data.password) < 8:
raise ValidationError("Password must be at least 8 characters long")
password_hash = hash_password(register_data.password)
new_user = User(
username=register_data.username,
email=register_data.email,
password_hash=password_hash,
role="user",
is_active=True,
)
self.db.add(new_user)
await self.db.commit()
await self.db.refresh(new_user)
return new_user
async def get_user_by_id(self, user_id: int) -> User | None:
"""Get user by ID"""
result = await self.db.execute(
select(User).where(User.id == user_id)
)
return result.scalar_one_or_none()
async def get_user_by_email(self, email: str) -> User | None:
"""Get user by email"""
result = await self.db.execute(
select(User).where(User.email == email)
)
return result.scalar_one_or_none()
"""
User service for user management operations
"""
from typing import Sequence
from sqlalchemy import func, select, update
from sqlalchemy.ext.asyncio import AsyncSession
from app.core.exceptions import ConflictError, NotFoundError, PermissionDeniedError
from app.core.security import hash_password
from app.models.user import User
from app.schemas.user import UserCreate, UserUpdate, UserStatsResponse
class UserService:
"""Service for handling user management operations"""
def __init__(self, db: AsyncSession):
self.db = db
async def get_by_id(self, user_id: int) -> User | None:
"""Get user by ID"""
result = await self.db.execute(
select(User).where(User.id == user_id)
)
return result.scalar_one_or_none()
async def get_by_email(self, email: str) -> User | None:
"""Get user by email"""
result = await self.db.execute(
select(User).where(User.email == email)
)
return result.scalar_one_or_none()
async def get_by_username(self, username: str) -> User | None:
"""Get user by username"""
result = await self.db.execute(
select(User).where(User.username == username)
)
return result.scalar_one_or_none()
async def get_users(
self,
skip: int = 0,
limit: int = 20,
role: str | None = None,
) -> tuple[Sequence[User], int]:
"""Get paginated list of users"""
query = select(User)
count_query = select(func.count()).select_from(User)
if role:
query = query.where(User.role == role)
count_query = count_query.where(User.role == role)
total_result = await self.db.execute(count_query)
total = total_result.scalar() or 0
query = query.offset(skip).limit(limit).order_by(User.id)
result = await self.db.execute(query)
users = result.scalars().all()
return users, total
async def create_user(self, user_data: UserCreate) -> User:
"""Create a new user"""
existing_email = await self.get_by_email(user_data.email)
if existing_email:
raise ConflictError("Email already registered")
existing_username = await self.get_by_username(user_data.username)
if existing_username:
raise ConflictError("Username already taken")
password_hash = hash_password(user_data.password)
new_user = User(
username=user_data.username,
email=user_data.email,
password_hash=password_hash,
role=user_data.role,
is_active=True,
)
self.db.add(new_user)
await self.db.commit()
await self.db.refresh(new_user)
return new_user
async def update_user(self, user_id: int, user_data: UserUpdate) -> User:
"""Update user information"""
user = await self.get_by_id(user_id)
if not user:
raise NotFoundError("User not found")
if user_data.email and user_data.email != user.email:
existing = await self.get_by_email(user_data.email)
if existing and existing.id != user_id:
raise ConflictError("Email already registered")
user.email = user_data.email
if user_data.username and user_data.username != user.username:
existing = await self.get_by_username(user_data.username)
if existing and existing.id != user_id:
raise ConflictError("Username already taken")
user.username = user_data.username
if user_data.avatar_url is not None:
user.avatar_url = user_data.avatar_url
if user_data.role is not None:
user.role = user_data.role
if user_data.is_active is not None:
user.is_active = user_data.is_active
await self.db.commit()
await self.db.refresh(user)
return user
async def update_password(self, user_id: int, old_password: str, new_password: str) -> bool:
"""Update user password"""
from app.core.security import verify_password
user = await self.get_by_id(user_id)
if not user:
raise NotFoundError("User not found")
if not verify_password(old_password, user.password_hash):
raise PermissionDeniedError("Current password is incorrect")
if len(new_password) < 8:
raise ValueError("Password must be at least 8 characters long")
user.password_hash = hash_password(new_password)
await self.db.commit()
return True
async def delete_user(self, user_id: int) -> bool:
"""Delete a user"""
user = await self.get_by_id(user_id)
if not user:
raise NotFoundError("User not found")
await self.db.delete(user)
await self.db.commit()
return True
async def get_user_stats(self, user_id: int) -> UserStatsResponse:
"""Get user statistics"""
user = await self.get_by_id(user_id)
if not user:
raise NotFoundError("User not found")
return UserStatsResponse(
total_annotations=0,
completed_tasks=0,
reviewed_tasks=0,
weekly_annotation_count=0,
total_working_hours=0.0,
)
async def update_last_login(self, user_id: int) -> None:
"""Update user's last login timestamp"""
await self.db.execute(
update(User)
.where(User.id == user_id)
.values(last_login_at=func.now())
)
await self.db.commit()
"""
Celery tasks package
"""
from app.tasks.celery_app import celery_app
__all__ = ["celery_app"]
"""
AI inference tasks (run on GPU/CPU workers)
"""
import time
from app.tasks.celery_app import celery_app
@celery_app.task(bind=True, name="ai_tasks.run_auto_label")
def run_auto_label_task(self, auto_task_id: str):
from app.core.logging import get_logger
logger = get_logger()
logger.info(f"Starting auto-label task: {auto_task_id}")
try:
self.update_state(state="STARTED", meta={"progress": 0})
time.sleep(1)
self.update_state(state="PROGRESS", meta={"progress": 50})
time.sleep(1)
self.update_state(state="PROGRESS", meta={"progress": 100})
logger.info(f"Auto-label task completed: {auto_task_id}")
return {"status": "completed", "auto_task_id": auto_task_id}
except Exception as exc:
logger.error(f"Auto-label task failed: {auto_task_id} - {exc}")
return {"status": "failed", "auto_task_id": auto_task_id, "error": str(exc)}
@celery_app.task(name="ai_tasks.infer_yolo")
def infer_yolo(model_id: str, data_item_id: str):
"""YOLOv8 object detection inference"""
pass
@celery_app.task(name="ai_tasks.infer_sam")
def infer_sam(model_id: str, data_item_id: str):
"""SAM segmentation inference"""
pass
@celery_app.task(name="ai_tasks.infer_whisper")
def infer_whisper(model_id: str, data_item_id: str):
"""Whisper ASR inference"""
pass
@celery_app.task(name="ai_tasks.infer_ner")
def infer_ner(model_id: str, data_item_id: str):
"""NER inference"""
pass
"""
Celery application configuration
"""
from celery import Celery
from app.core.config import settings
celery_app = Celery(
"plabel",
broker=settings.celery_broker_url,
backend=settings.celery_result_backend,
include=[
"app.tasks.ai_tasks",
"app.tasks.export_tasks",
"app.tasks.file_tasks",
"app.tasks.cleanup_tasks",
],
)
celery_app.conf.update(
task_serializer="json",
accept_content=["json"],
result_serializer="json",
timezone="UTC",
enable_utc=True,
task_track_started=True,
task_acks_late=True,
task_reject_on_worker_lost=True,
worker_prefetch_multiplier=1,
task_routes={
"app.tasks.ai_tasks.*": {"queue": "gpu_tasks"},
"app.tasks.export_tasks.*": {"queue": "cpu_tasks"},
"app.tasks.file_tasks.*": {"queue": "cpu_tasks"},
"app.tasks.cleanup_tasks.*": {"queue": "cpu_tasks"},
},
)
__all__ = ["celery_app"]
"""
Scheduled cleanup tasks
"""
from app.tasks.celery_app import celery_app
@celery_app.task(name="cleanup_tasks.cleanup_expired_files")
def cleanup_expired_files():
from app.core.logging import get_logger
logger = get_logger()
logger.info("Running expired files cleanup")
return {"deleted": 0}
@celery_app.task(name="cleanup_tasks.cleanup_old_exports")
def cleanup_old_export_files():
from app.core.logging import get_logger
logger = get_logger()
logger.info("Running old exports cleanup")
return {"deleted": 0}
@celery_app.task(name="cleanup_tasks.cleanup_failed_tasks")
def cleanup_failed_tasks():
from app.core.logging import get_logger
logger = get_logger()
logger.info("Running failed tasks cleanup")
return {"deleted": 0}
"""
Data export tasks
"""
import time
from app.tasks.celery_app import celery_app
@celery_app.task(bind=True, name="export_tasks.run_export")
def run_export_task(self, export_id: str, task_id: str, format: str):
from app.core.logging import get_logger
logger = get_logger()
logger.info(f"Starting export task: {export_id} (format={format})")
try:
self.update_state(state="STARTED", meta={"progress": 0})
for i in range(1, 11):
time.sleep(0.3)
self.update_state(state="PROGRESS", meta={"progress": i * 10})
logger.info(f"Export task completed: {export_id}")
return {"status": "completed", "export_id": export_id}
except Exception as exc:
logger.error(f"Export task failed: {export_id} - {exc}")
return {"status": "failed", "export_id": export_id, "error": str(exc)}
"""
File processing tasks
"""
import time
from app.tasks.celery_app import celery_app
@celery_app.task(name="file_tasks.generate_thumbnail")
def generate_thumbnail(data_item_id: str):
from app.core.logging import get_logger
logger = get_logger()
logger.info(f"Generating thumbnail for: {data_item_id}")
time.sleep(0.5)
return {"data_item_id": data_item_id, "thumbnail_path": f"thumbnails/{data_item_id}.jpg"}
@celery_app.task(name="file_tasks.extract_metadata")
def extract_file_metadata(data_item_id: str):
from app.core.logging import get_logger
logger = get_logger()
logger.info(f"Extracting metadata for: {data_item_id}")
return {"data_item_id": data_item_id, "metadata": {}}
"""
Helper utilities
"""
import re
import uuid
from pathlib import Path
def generate_uuid() -> str:
return str(uuid.uuid4())
def get_file_extension(filename: str) -> str:
return Path(filename).suffix.lower()
def get_file_mime_type(filename: str) -> str:
ext = get_file_extension(filename)
mime_types = {
".jpg": "image/jpeg", ".jpeg": "image/jpeg",
".png": "image/png", ".webp": "image/webp",
".bmp": "image/bmp", ".gif": "image/gif",
".mp4": "video/mp4", ".webm": "video/webm",
".mov": "video/quicktime", ".avi": "video/x-msvideo",
".mp3": "audio/mpeg", ".wav": "audio/wav",
".ogg": "audio/ogg", ".m4a": "audio/mp4",
".txt": "text/plain", ".md": "text/markdown",
".json": "application/json",
}
return mime_types.get(ext, "application/octet-stream")
def sanitize_filename(filename: str) -> str:
safe = re.sub(r"[^\w\s.-]", "", filename)
safe = re.sub(r"\s+", "_", safe)
return safe[:255]
def format_file_size(size_bytes: int) -> str:
for unit in ["B", "KB", "MB", "GB", "TB"]:
if size_bytes < 1024:
return f"{size_bytes:.2f} {unit}"
size_bytes /= 1024
return f"{size_bytes:.2f} PB"
def paginate_query(page: int, page_size: int) -> tuple[int, int]:
offset = (page - 1) * page_size
return offset, page_size
"""
Standard API response utilities
"""
from typing import Any
def success_response(data: Any = None, message: str = "success", code: int = 200) -> dict:
return {"code": code, "message": message, "data": data}
def error_response(code: int, message: str, errors: list[dict] | None = None) -> dict:
resp = {"code": code, "message": message}
if errors:
resp["errors"] = errors
return resp
def paginated_response(
items: list,
total: int,
page: int,
page_size: int,
) -> dict:
total_pages = (total + page_size - 1) // page_size if page_size > 0 else 0
return {
"code": 200,
"message": "success",
"data": {
"items": items,
"total": total,
"page": page,
"page_size": page_size,
"total_pages": total_pages,
}
}
FROM python:3.11-slim
WORKDIR /app
RUN apt-get update && apt-get install -y --no-install-recommends \
build-essential libpq-dev libffi-dev libssl-dev ffmpeg \
libsm6 libxext6 libxrender-dev libgomp1 && \
rm -rf /var/lib/apt/lists/*
COPY requirements.txt /app/
RUN pip install --no-cache-dir -r requirements.txt
COPY . /app/
RUN mkdir -p /app/logs /app/data/uploads /app/data/thumbnails /app/data/exports
EXPOSE 8000
CMD ["gunicorn", "-w", "4", "-k", "uvicorn.workers.UvicornWorker", "app.main:app"]
-- Initial database setup
CREATE EXTENSION IF NOT EXISTS "uuid-ossp";
events {
worker_connections 1024;
}
http {
include /etc/nginx/mime.types;
default_type application/octet-stream;
upstream backend {
server backend:8000;
}
server {
listen 80;
server_name localhost;
location /api/ {
proxy_pass http://backend;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}
location /docs {
proxy_pass http://backend;
}
location /redoc {
proxy_pass http://backend;
}
}
}
version: '3.8'
services:
gpu-worker:
build:
context: .
dockerfile: Dockerfile.gpu
env_file:
- .env
volumes:
- ./app:/app/app
- ./models:/app/models
- ./data:/app/data
environment:
- CUDA_VISIBLE_DEVICES=0
- MODEL_DEVICE=cuda
deploy:
resources:
reservations:
devices:
- driver: nvidia
count: 1
capabilities: [gpu]
command: celery -A app.tasks.celery_app worker -Q gpu_tasks -l info --concurrency=1
restart: unless-stopped
cpu-worker:
build:
context: .
dockerfile: Dockerfile
env_file:
- .env
volumes:
- ./app:/app/app
- ./models:/app/models
- ./data:/app/data
command: celery -A app.tasks.celery_app worker -Q cpu_tasks -l info --concurrency=4
restart: unless-stopped
version: '3.8'
services:
nginx:
image: nginx:alpine
ports:
- "80:80"
- "443:443"
volumes:
- ./configs/nginx/nginx.conf:/etc/nginx/nginx.conf:ro
- ./configs/nginx/ssl:/etc/nginx/ssl:ro
depends_on:
- backend
restart: unless-stopped
backend:
build:
context: .
dockerfile: configs/docker/Dockerfile.prod
env_file:
- .env
environment:
- DEBUG=false
- WORKERS=4
volumes:
- ./app:/app/app
- model_data:/app/models
deploy:
replicas: 2
restart: unless-stopped
celery_worker:
build:
context: .
dockerfile: configs/docker/Dockerfile.prod
env_file:
- .env
command: celery -A app.tasks.celery_app worker -Q gpu_tasks,cpu_tasks -l info --concurrency=4
volumes:
- ./app:/app/app
- model_data:/app/models
restart: unless-stopped
deploy:
resources:
reservations:
devices:
- driver: nvidia
count: 1
capabilities: [gpu]
postgres:
image: postgres:15-alpine
env_file:
- .env
volumes:
- postgres_data:/var/lib/postgresql/data
- ./configs/docker/init.sql:/docker-entrypoint-initdb.d/init.sql
healthcheck:
test: ["CMD-SHELL", "pg_isready -U plabel"]
interval: 10s
timeout: 5s
retries: 5
restart: unless-stopped
redis:
image: redis:7-alpine
command: redis-server --appendonly yes
volumes:
- redis_data:/data
restart: unless-stopped
minio:
image: minio/minio:latest
env_file:
- .env
volumes:
- minio_data:/data
command: server /data --console-address ":9001"
restart: unless-stopped
backup:
image: postgres:15-alpine
env_file:
- .env
volumes:
- postgres_data:/data
- ./backups:/backups
command: >
sh -c 'while true; do
pg_dump -h postgres -U plabel plabel > /backups/backup_$(date +%Y%m%d_%H%M%S).sql;
sleep 86400;
done'
restart: unless-stopped
volumes:
postgres_data:
redis_data:
minio_data:
model_data:
version: '3.8'
services:
postgres:
image: docker.m.daocloud.io/library/postgres:15-alpine
environment:
POSTGRES_DB: plabel
POSTGRES_USER: plabel
POSTGRES_PASSWORD: plabel
volumes:
- postgres_data:/var/lib/postgresql/data
ports:
- "0.0.0.0:5433:5432"
healthcheck:
test: ["CMD-SHELL", "pg_isready -U plabel"]
interval: 10s
timeout: 5s
retries: 5
redis:
image: docker.m.daocloud.io/library/redis:7-alpine
command: redis-server --appendonly yes
volumes:
- redis_data:/data
ports:
- "6379:6379"
healthcheck:
test: ["CMD", "redis-cli", "ping"]
interval: 10s
timeout: 3s
retries: 5
minio:
image: docker.m.daocloud.io/minio/minio:latest
environment:
MINIO_ROOT_USER: minio
MINIO_ROOT_PASSWORD: minio123
command: server /data --console-address ":9010"
volumes:
- minio_data:/data
ports:
- "9009:9009"
- "9010:9010"
healthcheck:
test: ["CMD", "curl", "-f", "http://localhost:9009/minio/health/live"]
interval: 30s
timeout: 20s
retries: 3
backend:
build:
context: .
dockerfile: Dockerfile
env_file:
- .env
volumes:
- ./app:/app/app
- ./data:/app/data
- ./logs:/app/logs
ports:
- "8899:8899"
depends_on:
postgres:
condition: service_healthy
redis:
condition: service_healthy
minio:
condition: service_healthy
command: >
sh -c "alembic upgrade head && uvicorn app.main:app --host 0.0.0.0 --port 8899 --reload"
celery_worker:
build:
context: .
dockerfile: Dockerfile
env_file:
- .env
volumes:
- ./app:/app/app
- ./data:/app/data
- ./models:/app/models
depends_on:
- redis
- backend
command: celery -A app.tasks.celery_app worker -Q gpu_tasks,cpu_tasks -l info --concurrency=2
flower:
build:
context: .
dockerfile: Dockerfile
env_file:
- .env
ports:
- "5555:5555"
depends_on:
- redis
- celery_worker
command: celery -A app.tasks.celery_app flower --port=5555
volumes:
postgres_data:
redis_data:
minio_data:
[pytest]
testpaths = tests
python_files = test_*.py
python_classes = Test*
python_functions = test_*
asyncio_mode = auto
addopts = -v --tb=short
filterwarnings =
ignore::DeprecationWarning
ignore::PendingDeprecationWarning
# AI/ML Dependencies (GPU Required)
# Install with: pip install -r requirements-ai.txt
# PyTorch GPU
torch==2.2.1
torchvision==0.17.1
torchaudio==2.2.1
-f https://download.pytorch.org/whl/cu121
# Transformers & NLP
transformers==4.39.1
accelerate==0.28.0
tokenizers==0.15.2
huggingface-hub==0.21.4
# Computer Vision
ultralytics==8.1.24
opencv-python==4.9.0.80
segment-anything==0.0.3
# Speech Processing
openai-whisper==20231117
soundfile==0.12.1
librosa==0.10.1
pyannote-audio==3.0.1
# ONNX Runtime
onnxruntime-gpu==1.17.1
# Chinese Text Processing
jieba==0.42.1
# Core Dependencies
fastapi==0.110.0
uvicorn[standard]==0.27.1
python-multipart==0.0.9
# Database
sqlalchemy==2.0.27
alembic==1.13.1
asyncpg==0.29.0
psycopg2-binary==2.9.9
# Cache & Queue
redis==5.0.1
celery==5.3.6
# Authentication
python-jose[cryptography]==3.3.0
passlib[bcrypt]==1.7.4
# Validation & Settings
pydantic==2.6.1
pydantic-settings==2.1.0
email-validator==2.1.0.post1
# File Storage
minio==7.2.3
aiofiles==23.2.1
# Image Processing
Pillow==10.2.0
opencv-python-headless==4.9.0.80
python-magic==0.4.27
# Utilities
python-dotenv==1.0.1
orjson==3.9.15
httpx==0.27.0
tenacity==8.2.3
# Logging
loguru==0.7.2
# Development & Testing
pytest==8.0.2
pytest-asyncio==0.23.5
pytest-cov==4.1.0
httpx==0.27.0
# ============================================
# AI/ML Dependencies (Optional - GPU Required)
# ============================================
# Uncomment as needed
# PyTorch (CPU version - for development)
# torch==2.2.1
# torchaudio==2.2.1
# PyTorch GPU version (uncomment instead of CPU version if you have NVIDIA GPU)
# torch==2.2.1+cu118
# torchaudio==2.2.1+cu118
# -f https://download.pytorch.org/whl/torch_stable.html
# Transformers & NLP
# transformers==4.39.1
# accelerate==0.28.0
# tokenizers==0.15.2
# huggingface-hub==0.21.4
# Computer Vision
# ultralytics==8.1.24 # YOLOv8
# opencv-python==4.9.0.80 # Use this instead of opencv-python-headless for visualization
# segment-anything==0.0.3
# Speech Processing
# openai-whisper==20231117
# soundfile==0.12.1
# librosa==0.10.1
# pyannote-audio==3.0.1
# ONNX Runtime
# onnxruntime-gpu==1.17.1 # GPU version
# onnxruntime==1.17.1 # CPU version
# Chinese Text Processing
# jieba==0.42.1
#!/usr/bin/env python3
"""Create MinIO buckets"""
import sys
from pathlib import Path
sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
from app.core.storage import storage_service
def create_buckets():
buckets = ["plabel-bucket", "plabel-assets"]
for bucket in buckets:
if not storage_service.client.bucket_exists(bucket):
storage_service.client.make_bucket(bucket)
print(f"Created bucket: {bucket}")
else:
print(f"Bucket already exists: {bucket}")
print("MinIO setup complete!")
if __name__ == "__main__":
create_buckets()
#!/usr/bin/env python3
"""
Initialize database and create default admin user
Usage: python scripts/init_db.py [--create-admin]
"""
import argparse
import sys
from pathlib import Path
# Add parent directory to path
sys.path.insert(0, str(Path(__file__).parent.parent))
from sqlalchemy import text
from app.core.database import sync_engine, Base
from app.core.security import hash_password
from app.models.user import User
from app.models.project import Project
from app.models.task import Task
from app.models.data_item import DataItem
from app.models.annotation import Annotation
from app.models.review_session import ReviewSession, ReviewComment
from app.models.label_set import LabelSet
from app.models.label import Label
from app.models.ai_model import AIModel
from app.models.auto_label_task import AutoLabelTask
from app.models.project_member import ProjectMember
def init_database():
"""Initialize database tables"""
print("Initializing database...")
with sync_engine.connect() as conn:
# Create public schema if not exists
conn.execute(text("CREATE SCHEMA IF NOT EXISTS public"))
conn.commit()
# Create all tables
Base.metadata.create_all(bind=sync_engine)
print("Database tables created successfully!")
return True
def create_default_admin():
"""Create default admin user if not exists"""
print("Creating default admin user...")
with sync_engine.connect() as conn:
# Check if admin exists
result = conn.execute(
text("SELECT id FROM users WHERE email = 'admin@plabel.com'")
)
if result.fetchone():
print("Admin user already exists.")
return False
# Create admin user
admin = User(
username="admin",
email="admin@plabel.com",
password_hash=hash_password("admin123"),
role="admin",
is_active=True,
)
conn.add(admin)
conn.commit()
conn.refresh(admin)
print(f"Admin user created successfully!")
print(f" Email: admin@plabel.com")
print(f" Password: admin123")
print(f" Role: admin")
return True
def create_sample_users():
"""Create sample users for testing"""
print("Creating sample users...")
sample_users = [
{"username": "annotator1", "email": "annotator@plabel.com", "role": "annotator"},
{"username": "reviewer1", "email": "reviewer@plabel.com", "role": "reviewer"},
{"username": "user1", "email": "user@plabel.com", "role": "user"},
]
with sync_engine.connect() as conn:
for user_data in sample_users:
# Check if user exists
result = conn.execute(
text("SELECT id FROM users WHERE email = :email"),
{"email": user_data["email"]}
)
if result.fetchone():
print(f" {user_data['username']} already exists, skipping...")
continue
user = User(
username=user_data["username"],
email=user_data["email"],
password_hash=hash_password("password123"),
role=user_data["role"],
is_active=True,
)
conn.add(user)
conn.commit()
print(f" Created: {user_data['username']} ({user_data['role']})")
print("Sample users created!")
return True
def drop_all_tables():
"""Drop all tables (use with caution!)"""
print("WARNING: Dropping all database tables...")
confirm = input("Are you sure? Type 'yes' to confirm: ")
if confirm.lower() != "yes":
print("Aborted.")
return False
Base.metadata.drop_all(bind=sync_engine)
print("All tables dropped!")
return True
def main():
parser = argparse.ArgumentParser(description="Database initialization script")
parser.add_argument("--create-admin", action="store_true", help="Create default admin user")
parser.add_argument("--sample-users", action="store_true", help="Create sample users")
parser.add_argument("--drop", action="store_true", help="Drop all tables first")
parser.add_argument("--init-only", action="store_true", help="Only initialize tables, don't create users")
args = parser.parse_args()
try:
if args.drop:
if not drop_all_tables():
return
# Initialize tables
init_database()
if args.init_only:
print("Database initialized (tables only).")
return
# Create users
if args.create_admin:
create_default_admin()
if args.sample_users:
create_sample_users()
if not args.create_admin and not args.sample_users:
print("\nNo actions specified. Use --create-admin to create admin user.")
print("Or use --sample-users to create sample users.")
print("\nExample:")
print(" python scripts/init_db.py --create-admin --sample-users")
except Exception as e:
print(f"Error: {e}")
sys.exit(1)
if __name__ == "__main__":
main()
#!/usr/bin/env python3
"""Seed database with initial data"""
import sys
from pathlib import Path
sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
from app.core.database import SyncSessionLocal
from app.core.security import hash_password
from app.models import User
def seed_users():
users = [
{
"username": "admin",
"email": "admin@plabel.com",
"password_hash": hash_password("admin123"),
"role": "admin",
},
{
"username": "user",
"email": "user@plabel.com",
"password_hash": hash_password("user123"),
"role": "user",
},
{
"username": "annotator",
"email": "annotator@plabel.com",
"password_hash": hash_password("annotator123"),
"role": "annotator",
},
{
"username": "reviewer",
"email": "reviewer@plabel.com",
"password_hash": hash_password("reviewer123"),
"role": "reviewer",
},
]
with SyncSessionLocal() as db:
for data in users:
existing = db.query(User).filter(User.email == data["email"]).first()
if not existing:
user = User(**data)
db.add(user)
db.commit()
print("Seed data created successfully!")
if __name__ == "__main__":
seed_users()
"""Test authentication endpoints"""
import pytest
def test_login_format():
"""Test login request format"""
assert True
def test_register_format():
"""Test register request format"""
assert True
"""Pytest fixtures and configuration"""
import pytest
import asyncio
from httpx import AsyncClient
from sqlalchemy.ext.asyncio import AsyncSession
from app.main import app
from app.core.database import AsyncSessionLocal, Base
@pytest.fixture(scope="session")
def event_loop():
loop = asyncio.get_event_loop_policy().new_event_loop()
yield loop
loop.close()
@pytest.fixture(scope="function")
async def db_session():
async with AsyncSessionLocal() as session:
yield session
await session.rollback()
/**
* Authentication API - 与后端认证接口对接
*/
import type { User } from '@/types'
const API_BASE_URL = import.meta.env.VITE_API_BASE_URL || '/api/v1'
// API 响应类型
export interface ApiResponse<T> {
code: number
message: string
data?: T
}
// 登录请求
export interface LoginRequest {
email: string
password: string
}
// 注册请求
export interface RegisterRequest {
username: string
email: string
password: string
}
// 登录响应
export interface LoginResponse {
access_token: string
token_type: string
expires_in: number
user: UserResponse
}
// 用户响应
export interface UserResponse {
id: string
username: string
email: string
role: string
avatar_url: string | null
is_active: boolean
}
// HTTP 工具函数
async function request<T>(
url: string,
options: RequestInit = {}
): Promise<T> {
const token = localStorage.getItem('plabel_token')
const headers: HeadersInit = {
'Content-Type': 'application/json',
...(token && { Authorization: `Bearer ${token}` }),
...options.headers,
}
const response = await fetch(`${API_BASE_URL}${url}`, {
...options,
headers,
})
const data = await response.json()
if (!response.ok) {
throw new Error(data.detail || data.message || 'Request failed')
}
return data
}
// 认证 API
export const AuthAPI = {
/**
* 用户登录
*/
async login(email: string, password: string): Promise<LoginResponse> {
const response = await request<ApiResponse<LoginResponse>>('/auth/login', {
method: 'POST',
body: JSON.stringify({ email, password }),
})
if (response.code !== 200) {
throw new Error(response.message)
}
return response.data!
},
/**
* 用户注册
*/
async register(username: string, email: string, password: string): Promise<LoginResponse> {
const response = await request<ApiResponse<LoginResponse>>('/auth/register', {
method: 'POST',
body: JSON.stringify({ username, email, password }),
})
if (response.code !== 200 && response.code !== 201) {
throw new Error(response.message)
}
return response.data!
},
/**
* 获取当前用户信息
*/
async getCurrentUser(): Promise<UserResponse> {
const response = await request<ApiResponse<UserResponse>>('/auth/me')
if (response.code !== 200) {
throw new Error(response.message)
}
return response.data!
},
/**
* 更新当前用户信息
*/
async updateProfile(data: Partial<{ username: string; email: string; avatar_url: string }>): Promise<UserResponse> {
const response = await request<ApiResponse<UserResponse>>('/auth/me', {
method: 'PUT',
body: JSON.stringify(data),
})
if (response.code !== 200) {
throw new Error(response.message)
}
return response.data!
},
/**
* 修改密码
*/
async changePassword(oldPassword: string, newPassword: string): Promise<void> {
const response = await request<ApiResponse<void>>('/auth/change-password', {
method: 'POST',
body: JSON.stringify({ old_password: oldPassword, new_password: newPassword }),
})
if (response.code !== 200) {
throw new Error(response.message)
}
},
/**
* 用户登出
*/
async logout(): Promise<void> {
try {
await request<ApiResponse<void>>('/auth/logout', {
method: 'POST',
})
} finally {
localStorage.removeItem('plabel_token')
localStorage.removeItem('plabel_user')
}
},
}
// 用户 API
export const UserAPI = {
/**
* 获取用户列表 (admin)
*/
async listUsers(params?: { page?: number; page_size?: number; role?: string }): Promise<{
items: UserResponse[]
total: number
page: number
page_size: number
total_pages: number
}> {
const queryParams = new URLSearchParams()
if (params?.page) queryParams.set('page', String(params.page))
if (params?.page_size) queryParams.set('page_size', String(params.page_size))
if (params?.role) queryParams.set('role', params.role)
const url = `/users${queryParams.toString() ? `?${queryParams.toString()}` : ''}`
const response = await request<ApiResponse<any>>(url)
if (response.code !== 200) {
throw new Error(response.message)
}
return response.data!
},
/**
* 获取用户详情
*/
async getUser(userId: string): Promise<UserResponse> {
const response = await request<ApiResponse<UserResponse>>(`/users/${userId}`)
if (response.code !== 200) {
throw new Error(response.message)
}
return response.data!
},
/**
* 创建用户 (admin)
*/
async createUser(data: { username: string; email: string; password: string; role?: string }): Promise<UserResponse> {
const response = await request<ApiResponse<UserResponse>>('/users', {
method: 'POST',
body: JSON.stringify(data),
})
if (response.code !== 201) {
throw new Error(response.message)
}
return response.data!
},
/**
* 更新用户
*/
async updateUser(userId: string, data: Partial<{ username: string; email: string; role: string; is_active: boolean }>): Promise<UserResponse> {
const response = await request<ApiResponse<UserResponse>>(`/users/${userId}`, {
method: 'PUT',
body: JSON.stringify(data),
})
if (response.code !== 200) {
throw new Error(response.message)
}
return response.data!
},
/**
* 删除用户 (admin)
*/
async deleteUser(userId: string): Promise<void> {
const response = await request<ApiResponse<void>>(`/users/${userId}`, {
method: 'DELETE',
})
if (response.code !== 200 && response.code !== 204) {
throw new Error(response.message)
}
},
}
// 工具函数:将后端用户响应转换为前端 User 类型
export function convertToUser(response: UserResponse): User {
return {
id: response.id,
username: response.username,
email: response.email,
avatar: response.avatar_url || undefined,
role: response.role as User['role'],
createTime: new Date().toISOString().split('T')[0],
}
}
export default AuthAPI
......@@ -843,7 +843,7 @@ export const TextAPI = {
id: e.id,
type: 'text' as const,
label: e.label,
data: { text: e.text, startOffset: e.startOffset, endOffset: e.endOffset },
data: { text: e.text, startOffset: e.startOffset, endOffset: e.endOffset } as any,
visible: true,
occluded: false,
ignored: false
......
......@@ -268,7 +268,7 @@
import { ref, computed, watch } from 'vue'
import { ElMessage } from 'element-plus'
import { mockAIModels } from '@/mock'
import type { DataItem, AIModel } from '@/types'
import type { DataItem, AIModel, AutoLabelConfig as BaseAutoLabelConfig } from '@/types'
interface Props {
taskId: string
......@@ -280,28 +280,40 @@ const props = withDefaults(defineProps<Props>(), {
availableDataItems: () => []
})
const emit = defineEmits<{
close: []
start: [config: AutoLabelConfig]
complete: [results: { completed: number; total: number }]
}>()
interface AutoLabelConfig {
// Extended config type for the panel
export interface ExtendedAutoLabelConfig extends BaseAutoLabelConfig {
taskId: string
dataType: string
model: { id: string; name?: string; type?: string } | null
params: {
model?: { id: string; name?: string; type?: string } | null
params?: {
confidence: number
maxResults: number
}
options: Record<string, unknown>
global: {
options?: Record<string, unknown>
global?: {
overwriteExisting: boolean
autoApply: boolean
notifyOnComplete: boolean
}
}
const emit = defineEmits<{
close: []
start: [config: ExtendedAutoLabelConfig]
complete: [results: { completed: number; total: number }]
}>()
interface PanelConfig {
taskId: string
dataType: string
modelId: string
confidence: number
maxResults: number
overwriteExisting: boolean
autoApply: boolean
notifyOnComplete: boolean
}
const config = ref({
modelId: '',
confidence: 0.7,
......@@ -428,7 +440,7 @@ async function simulateAutoLabel(_item: DataItem, _index: number, _total: number
}
}
function buildConfig(): AutoLabelConfig {
function buildConfig(): ExtendedAutoLabelConfig {
const selectedModel = availableModels.value.find(m => m.id === config.value.modelId)
return {
taskId: props.taskId,
......@@ -447,7 +459,11 @@ function buildConfig(): AutoLabelConfig {
overwriteExisting: config.value.overwriteExisting,
autoApply: config.value.autoApply,
notifyOnComplete: config.value.notifyOnComplete
}
},
modelId: config.value.modelId,
confidenceThreshold: config.value.confidence,
overwriteExisting: config.value.overwriteExisting,
autoApply: config.value.autoApply
}
}
</script>
......
......@@ -359,7 +359,10 @@ const {
sortedEntities,
labels,
relationTypes,
statistics
statistics,
prevPage,
nextPage,
selectEntity
} = textAnnotator
// Local state
......
......@@ -329,7 +329,21 @@ const {
sortedAnnotations,
zoomLevels,
playbackRates,
labels
labels,
selectAnnotation,
setZoom,
formatTime,
jumpToAnnotation,
jumpToNextAnnotation,
jumpToPrevAnnotation,
togglePlay,
deleteAnnotation,
seek,
timeToPercent,
getRegionStyle,
getSelectionStyle,
isInRegion,
readonly
} = voiceAnnotator
// Canvas settings
......
......@@ -3,11 +3,14 @@
export { default as ReviewInterface } from './ReviewInterface.vue'
// Re-export types for convenience
import type { ReviewQueueItem, ReviewComment, ReviewInterfaceProps } from '@/types/extended'
// Re-export types from extended types
export type {
ReviewQueueItem,
ReviewComment,
ReviewInterfaceProps
} from '@/types/extended'
import type { ReviewComment } from '@/types'
export type {
ReviewComment
}
......@@ -5,3 +5,5 @@ declare module '*.vue' {
const component: DefineComponent<{}, {}, any>
export default component
}
declare module 'element-plus/dist/locale/zh-cn.mjs'
......@@ -447,8 +447,8 @@ export const mockDatasets: Dataset[] = [
format: 'COCO',
itemCount: 3250,
annotatedCount: 3250,
createTime: '2024-05-20 10:00:00',
updateTime: '2024-05-27 09:00:00'
createdAt: '2024-05-20 10:00:00',
updatedAt: '2024-05-27 09:00:00'
},
{
id: 'dataset-002',
......@@ -458,8 +458,8 @@ export const mockDatasets: Dataset[] = [
format: 'COCO Keypoint',
itemCount: 1200,
annotatedCount: 1200,
createTime: '2024-05-15 14:00:00',
updateTime: '2024-05-20 16:00:00'
createdAt: '2024-05-15 14:00:00',
updatedAt: '2024-05-20 16:00:00'
},
{
id: 'dataset-003',
......@@ -469,8 +469,8 @@ export const mockDatasets: Dataset[] = [
format: 'MASK',
itemCount: 720,
annotatedCount: 720,
createTime: '2024-05-22 08:00:00',
updateTime: '2024-05-26 18:00:00'
createdAt: '2024-05-22 08:00:00',
updatedAt: '2024-05-26 18:00:00'
},
{
id: 'dataset-004',
......@@ -480,8 +480,8 @@ export const mockDatasets: Dataset[] = [
format: 'JSON',
itemCount: 225,
annotatedCount: 225,
createTime: '2024-05-26 13:00:00',
updateTime: '2024-05-27 08:00:00'
createdAt: '2024-05-26 13:00:00',
updatedAt: '2024-05-27 08:00:00'
},
{
id: 'dataset-005',
......@@ -491,8 +491,8 @@ export const mockDatasets: Dataset[] = [
format: 'JSON',
itemCount: 1500,
annotatedCount: 450,
createTime: '2024-05-26 09:00:00',
updateTime: '2024-05-27 10:00:00'
createdAt: '2024-05-26 09:00:00',
updatedAt: '2024-05-27 10:00:00'
}
]
......
import { defineStore } from 'pinia'
import { ref, computed } from 'vue'
import type { User } from '@/types'
import { mockCurrentUser } from '@/mock'
import { AuthAPI, convertToUser } from '@/api/auth'
/**
* User Store - 用户状态管理
......@@ -14,7 +14,7 @@ import { mockCurrentUser } from '@/mock'
* 使用示例:
* ```typescript
* const userStore = useUserStore()
* await userStore.login('admin', 'password')
* await userStore.login('admin@example.com', 'password')
* userStore.logout()
* ```
*/
......@@ -22,66 +22,161 @@ export const useUserStore = defineStore('user', () => {
const currentUser = ref<User | null>(null)
const isLoggedIn = ref(false)
const token = ref<string | null>(null)
const loading = ref(false)
const error = ref<string | null>(null)
const userInfo = computed(() => currentUser.value)
const isAdmin = computed(() => currentUser.value?.role === 'admin')
const isAnnotator = computed(() => currentUser.value?.role === 'annotator')
const isReviewer = computed(() => currentUser.value?.role === 'reviewer')
function login(username: string, password: string): Promise<boolean> {
return new Promise((resolve) => {
setTimeout(() => {
if (username && password) {
currentUser.value = { ...mockCurrentUser, username }
isLoggedIn.value = true
token.value = `mock-token-${Date.now()}`
localStorage.setItem('plabel_user', JSON.stringify(currentUser.value))
localStorage.setItem('plabel_token', token.value!)
resolve(true)
} else {
resolve(false)
}
}, 500)
})
/**
* 用户登录
* @param email 邮箱
* @param password 密码
*/
async function login(email: string, password: string): Promise<boolean> {
loading.value = true
error.value = null
try {
const response = await AuthAPI.login(email, password)
token.value = response.access_token
currentUser.value = convertToUser(response.user)
isLoggedIn.value = true
// 存储到 localStorage
localStorage.setItem('plabel_token', response.access_token)
localStorage.setItem('plabel_user', JSON.stringify(currentUser.value))
return true
} catch (err: any) {
error.value = err.message || '登录失败'
return false
} finally {
loading.value = false
}
}
function register(username: string, password: string, email: string): Promise<boolean> {
return new Promise((resolve) => {
setTimeout(() => {
if (username && password && email) {
const newUser: User = {
id: `user-${Date.now()}`,
username,
email,
avatar: `https://api.dicebear.com/7.x/avataaars/svg?seed=${username}`,
role: 'user',
createTime: new Date().toISOString().split('T')[0]
}
currentUser.value = newUser
isLoggedIn.value = true
token.value = `mock-token-${Date.now()}`
localStorage.setItem('plabel_user', JSON.stringify(newUser))
localStorage.setItem('plabel_token', token.value!)
resolve(true)
} else {
resolve(false)
}
}, 500)
})
/**
* 用户注册
* @param username 用户名
* @param email 邮箱
* @param password 密码
*/
async function register(username: string, password: string, email: string): Promise<boolean> {
loading.value = true
error.value = null
try {
const response = await AuthAPI.register(username, email, password)
token.value = response.access_token
currentUser.value = convertToUser(response.user)
isLoggedIn.value = true
// 存储到 localStorage
localStorage.setItem('plabel_token', response.access_token)
localStorage.setItem('plabel_user', JSON.stringify(currentUser.value))
return true
} catch (err: any) {
error.value = err.message || '注册失败'
return false
} finally {
loading.value = false
}
}
function logout() {
currentUser.value = null
isLoggedIn.value = false
token.value = null
localStorage.removeItem('plabel_user')
localStorage.removeItem('plabel_token')
/**
* 用户登出
*/
async function logout(): Promise<void> {
try {
await AuthAPI.logout()
} catch {
// 即使 API 调用失败也清理本地状态
} finally {
currentUser.value = null
isLoggedIn.value = false
token.value = null
localStorage.removeItem('plabel_user')
localStorage.removeItem('plabel_token')
}
}
function checkAuth() {
const savedUser = localStorage.getItem('plabel_user')
/**
* 检查认证状态
* 从 localStorage 恢复登录状态,并验证 token 有效性
*/
async function checkAuth(): Promise<boolean> {
const savedToken = localStorage.getItem('plabel_token')
if (savedUser && savedToken) {
currentUser.value = JSON.parse(savedUser)
isLoggedIn.value = true
const savedUser = localStorage.getItem('plabel_user')
if (!savedToken || !savedUser) {
return false
}
try {
// 设置 token
token.value = savedToken
// 尝试验证并获取最新用户信息
const userResponse = await AuthAPI.getCurrentUser()
currentUser.value = convertToUser(userResponse)
isLoggedIn.value = true
// 更新本地存储的用户信息
localStorage.setItem('plabel_user', JSON.stringify(currentUser.value))
return true
} catch {
// Token 无效,清除登录状态
token.value = null
currentUser.value = null
isLoggedIn.value = false
localStorage.removeItem('plabel_token')
localStorage.removeItem('plabel_user')
return false
}
}
/**
* 更新用户信息
*/
async function updateProfile(data: { username?: string; email?: string; avatar_url?: string }): Promise<boolean> {
loading.value = true
error.value = null
try {
const response = await AuthAPI.updateProfile(data)
currentUser.value = convertToUser(response)
localStorage.setItem('plabel_user', JSON.stringify(currentUser.value))
return true
} catch (err: any) {
error.value = err.message || '更新失败'
return false
} finally {
loading.value = false
}
}
/**
* 修改密码
*/
async function changePassword(oldPassword: string, newPassword: string): Promise<boolean> {
loading.value = true
error.value = null
try {
await AuthAPI.changePassword(oldPassword, newPassword)
return true
} catch (err: any) {
error.value = err.message || '密码修改失败'
return false
} finally {
loading.value = false
}
}
......@@ -89,10 +184,17 @@ export const useUserStore = defineStore('user', () => {
currentUser,
isLoggedIn,
token,
loading,
error,
userInfo,
isAdmin,
isAnnotator,
isReviewer,
login,
register,
logout,
checkAuth
checkAuth,
updateProfile,
changePassword,
}
})
......@@ -2,6 +2,7 @@
// Supports JSON, CoNLL-U, BIO, and plain text formats
import type { TextEntity, TextRelation, TextDocument } from '@/types'
import type { CoNLLExportOptions } from '@/types/extended'
export interface TextNERExportData {
document: {
......
......@@ -132,12 +132,12 @@
<div class="mini-stat">
<span class="mini-label">准确率</span>
<el-progress
:percentage="model.accuracy"
:color="getAccuracyColor(model.accuracy)"
:percentage="model.accuracy ?? 0"
:color="getAccuracyColor(model.accuracy ?? 0)"
:show-text="false"
style="width: 80px"
/>
<span class="mini-value">{{ model.accuracy }}%</span>
<span class="mini-value">{{ model.accuracy ?? 0 }}%</span>
</div>
<div class="mini-stat">
<span class="mini-label">推理速度</span>
......@@ -239,11 +239,11 @@ const enabledModels = computed(() => allModels.value.filter(m => m.enabled))
const totalModels = computed(() => allModels.value.length)
const averageAccuracy = computed(() => {
if (allModels.value.length === 0) return 0
return Math.round(allModels.value.reduce((sum, m) => sum + m.accuracy, 0) / allModels.value.length)
return Math.round(allModels.value.reduce((sum, m) => sum + (m.accuracy || 0), 0) / allModels.value.length)
})
const averageSpeed = computed(() => {
if (allModels.value.length === 0) return 0
return Math.round(allModels.value.reduce((sum, m) => sum + m.speed, 0) / allModels.value.length)
return Math.round(allModels.value.reduce((sum, m) => sum + (m.speed || 0), 0) / allModels.value.length)
})
function getTypeColor(type: string) {
......
......@@ -19,12 +19,12 @@
class="login-form"
@submit.prevent="handleLogin"
>
<el-form-item prop="username">
<el-form-item prop="email">
<el-input
v-model="loginForm.username"
placeholder="请输入用户名"
v-model="loginForm.email"
placeholder="请输入邮箱"
size="large"
:prefix-icon="User"
:prefix-icon="Message"
/>
</el-form-item>
......@@ -62,7 +62,7 @@
<div class="demo-hint">
<el-icon><InfoFilled /></el-icon>
<span>演示账号:admin / 任意密码</span>
<span>演示账号:admin@plabel.com / 任意密码</span>
</div>
</div>
......@@ -77,7 +77,7 @@
import { ref, reactive } from 'vue'
import { useRouter } from 'vue-router'
import { ElMessage } from 'element-plus'
import { User, Lock, InfoFilled } from '@element-plus/icons-vue'
import { Lock, InfoFilled, Message } from '@element-plus/icons-vue'
import type { FormInstance, FormRules } from 'element-plus'
import { useUserStore } from '@/store/user'
......@@ -87,14 +87,15 @@ const loginFormRef = ref<FormInstance>()
const loading = ref(false)
const loginForm = reactive({
username: '',
email: '',
password: '',
remember: false
})
const rules: FormRules = {
username: [
{ required: true, message: '请输入用户名', trigger: 'blur' }
email: [
{ required: true, message: '请输入邮箱', trigger: 'blur' },
{ type: 'email', message: '请输入正确的邮箱格式', trigger: 'blur' }
],
password: [
{ required: true, message: '请输入密码', trigger: 'blur' },
......@@ -109,12 +110,12 @@ const handleLogin = async () => {
if (valid) {
loading.value = true
try {
const success = await userStore.login(loginForm.username, loginForm.password)
const success = await userStore.login(loginForm.email, loginForm.password)
if (success) {
ElMessage.success('登录成功,欢迎回来!')
router.push('/dashboard')
} else {
ElMessage.error('用户名或密码错误')
ElMessage.error(userStore.error || '登录失败,请检查邮箱和密码')
}
} catch {
ElMessage.error('登录失败,请重试')
......
......@@ -122,7 +122,7 @@ const validateConfirmPassword = (rule: any, value: any, callback: any) => {
const rules: FormRules = {
username: [
{ required: true, message: '请输入用户名', trigger: 'blur' },
{ min: 3, max: 20, message: '用户名长度在3-20个字符', trigger: 'blur' }
{ min: 2, max: 50, message: '用户名长度在2-50个字符', trigger: 'blur' }
],
email: [
{ required: true, message: '请输入邮箱', trigger: 'blur' },
......@@ -130,7 +130,7 @@ const rules: FormRules = {
],
password: [
{ required: true, message: '请输入密码', trigger: 'blur' },
{ min: 6, message: '密码长度至少6位', trigger: 'blur' }
{ min: 8, message: '密码长度至少8位', trigger: 'blur' }
],
confirmPassword: [
{ required: true, message: '请确认密码', trigger: 'blur' },
......@@ -154,7 +154,7 @@ const handleRegister = async () => {
ElMessage.success('注册成功!')
router.push('/dashboard')
} else {
ElMessage.error('注册失败,请重试')
ElMessage.error(userStore.error || '注册失败,请重试')
}
} catch {
ElMessage.error('注册失败,请重试')
......
......@@ -11,7 +11,14 @@ export default defineConfig({
},
server: {
port: 8008,
host: true
host: true,
proxy: {
'/api': {
target: 'http://localhost:8899',
changeOrigin: true,
secure: false,
},
},
},
css: {
preprocessorOptions: {
......
No preview for this file type
# PLabel 自动标注平台 - 后端需求清单 v2.0
> 文档版本:v2.0
> 创建日期:2026年5月28日
> 参考文档:[说明书1.0.md](./说明书1.0.md)、[端口清单.md](./端口清单.md)、[项目落地方案.md](./项目落地方案.md)
> 目标:为后端开发团队提供完整、详细、可执行的技术需求规格
---
## 目录
1. [项目概述](#1-项目概述)
2. [系统架构设计](#2-系统架构设计)
3. [技术栈与选型](#3-技术栈与选型)
4. [环境依赖](#4-环境依赖)
5. [后端项目结构](#5-后端项目结构)
6. [数据库设计](#6-数据库设计)
7. [API 接口规范](#7-api-接口规范)
8. [AI 模型服务](#8-ai-模型服务)
9. [文件存储方案](#9-文件存储方案)
10. [功能模块详细需求](#10-功能模块详细需求)
11. [安全与权限](#11-安全与权限)
12. [部署架构](#12-部署架构)
13. [开发里程碑](#13-开发里程碑)
14. [前后端联调方案](#14-前后端联调方案)
---
## 1. 项目概述
### 1.1 项目背景
PLabel 是一款专业的 AI 训练数据标注平台,为机器学习和深度学习项目提供高质量的标注数据支持。项目采用前后端分离架构:
| 组件 | 技术栈 | 端口 | 状态 |
|------|--------|------|------|
| 前端 | Vue 3 + TypeScript + Vite | 8008 | 已完成基础功能 |
| 后端 | FastAPI + Python 3.10+ | 8899 | 待开发 |
| 数据库 | PostgreSQL | 5433 | 待配置 |
| 缓存 | Redis | 6379 | 待配置 |
| 对象存储 | MinIO | 9009/9010 | 待部署 |
| 任务队列 | Celery | - | 待集成 |
### 1.2 整体目标
本项目旨在开发一套完整的 FastAPI 后端系统,实现以下核心功能:
1. **用户认证与权限管理** - JWT 鉴权、角色权限控制
2. **项目管理** - 项目的 CRUD、成员管理、标签集管理
3. **任务管理** - 任务的创建、分配、状态流转
4. **数据管理** - 文件上传、元数据提取、存储管理
5. **标注功能** - 图像/音频/文本多种类型的标注
6. **审核管理** - 标注结果的审核流程
7. **AI 自动标注** - 基于预训练模型的自动标注
8. **数据导出** - 多格式数据集导出
### 1.3 性能目标
| 指标 | 目标值 | 说明 |
|------|--------|------|
| API 响应时间 | < 200ms | 普通 CRUD 操作 |
| 文件上传 | 支持单文件 500MB | 需支持大文件分片上传 |
| 并发用户 | 100+ | 支持团队协作场景 |
| AI 推理队列 | 支持 100+ 并发任务 | 任务排队与状态跟踪 |
| 数据导出 | 支持 10万+ 标注导出 | 批量导出性能 |
---
## 2. 系统架构设计
### 2.1 整体架构图
```
┌─────────────────────────────────────────────────────────────────────────────────────────┐
│ 用户浏览器 (http://localhost:8008) │
└─────────────────────────────────────────────┬───────────────────────────────────────────┘
│
│ HTTP/HTTPS
▼
┌─────────────────────────────────────────────────────────────────────────────────────────┐
│ Nginx 反向代理 │
│ 端口: 80 / 443 │
│ - SSL 终止 (生产环境) │
│ - 静态资源缓存 │
│ - 请求分发 │
└───────┬─────────────────────────────────────────┬───────────────────────────────────────┘
│ │
│ 静态资源 │ API 请求
▼ ▼
┌───────────────────┐ ┌───────────────────────────────────────────────┐
│ 前端静态资源 │ │ FastAPI 后端服务 │
│ (dist/) │ │ :8899 │
│ │◀──────────────────│ │
└───────────────────┘ CORS / 代理 │ ┌─────────────────────────────────────────┐ │
│ │ API Router Layer │ │
│ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ │
│ │ │ Auth │ │ Project │ │ Task │ │ │
│ │ └─────────┘ └─────────┘ └─────────┘ │ │
│ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ │
│ │ │Annotation│ │ Review │ │ Export │ │ │
│ │ └─────────┘ └─────────┘ └─────────┘ │ │
│ └─────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────┐ │
│ │ Service Layer (业务逻辑层) │ │
│ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ │
│ │ │UserSvc │ │ProjectSvc│ │TaskSvc │ │ │
│ │ └─────────┘ └─────────┘ └─────────┘ │ │
│ └─────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────┐ │
│ │ Data Access Layer (数据访问层) │ │
│ │ SQLAlchemy ORM │ │
│ └─────────────────────────────────────────┘ │
└──────────────────────┬──────────────────────────┘
│
┌──────────────────────────────────────┼──────────────────────────────────────┐
│ │ │
▼ ▼ ▼
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ PostgreSQL │ │ Redis │ │ MinIO │
│ :5433 │ │ :6379 │ │ :9009 / :9010 │
│ 主数据库 │ │ 缓存/消息队列 │ │ 对象存储 │
└─────────────────┘ └─────────────────┘ └─────────────────┘
│
▼
┌─────────────────────┐
│ Celery Workers │
│ ┌─────┐ ┌─────┐ │
│ │ GPU │ │ CPU │ │
│ │Queue│ │Queue│ │
│ └─────┘ └─────┘ │
└─────────────────────┘
```
### 2.2 服务依赖关系
```
┌─────────────┐
│ 前端 Vue │
│ :8008 │
└──────┬──────┘
│
│ HTTP REST API
▼
┌─────────────┐
│ FastAPI │──────────────┬──────────────┬──────────────┐
│ :8899 │ │ │ │
└──────┬──────┘ │ │ │
│ │ │ │
┌─────────────────┼─────────────────┐ │ │ │
│ │ │ │ │ │
▼ ▼ ▼ ▼ ▼ ▼
┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ PostgreSQL │ │ Redis │ │ MinIO │ │ Celery │ │ Flower │
│ :5433 │ │ :6379 │ │ :9009/:9010 │ │ Workers │ │ :5555 │
└─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘
```
### 2.3 数据流向
```
用户上传文件 ──▶ FastAPI 接收 ──▶ MinIO 存储 ──▶ 记录到 PostgreSQL
│
▼
Celery 任务
│
┌───────────┼───────────┐
▼ ▼ ▼
┌────────┐ ┌────────┐ ┌────────┐
│ 缩略图 │ │ AI推理 │ │ 元数据 │
│ 生成 │ │ 任务 │ │ 提取 │
└────────┘ └────────┘ └────────┘
│ │ │
└───────────┴───────────┘
│
▼
PostgreSQL 更新
```
---
## 3. 技术栈与选型
### 3.1 核心技术栈
#### 3.1.1 后端框架
| 类别 | 技术 | 版本 | 说明 |
|------|------|------|------|
| Web 框架 | FastAPI | 0.110+ | 异步高性能框架,自动生成 OpenAPI 文档 |
| ASGI 服务器 | Uvicorn | 0.27+ | ASGI 异步服务器,支持热重载 |
| Python | Python | 3.10+ | 后端编程语言 |
| 类型提示 | Pydantic | 2.6+ | 数据验证和序列化 |
#### 3.1.2 数据库层
| 类别 | 技术 | 版本 | 说明 |
|------|------|------|------|
| ORM | SQLAlchemy | 2.0+ | 数据库 ORM,支持异步 |
| 迁移工具 | Alembic | 1.13+ | 数据库版本管理 |
| 同步驱动 | psycopg2-binary | 2.9+ | PostgreSQL 同步驱动 |
| 异步驱动 | asyncpg | 0.29+ | PostgreSQL 异步驱动 |
#### 3.1.3 缓存与队列
| 类别 | 技术 | 版本 | 说明 |
|------|------|------|------|
| 缓存 | Redis | 7+ | 缓存和消息队列 |
| Python 客户端 | redis-py | 5.0+ | Redis Python 客户端 |
| 任务队列 | Celery | 5.3+ | 异步任务队列 |
| 监控面板 | Flower | 2.0+ | Celery 任务监控 |
#### 3.1.4 文件存储
| 类别 | 技术 | 版本 | 说明 |
|------|------|------|------|
| 对象存储 | MinIO | 最新版 | S3 兼容的对象存储服务 |
| Python SDK | minio | 7.2+ | MinIO Python SDK |
| 图像处理 | Pillow | 10.2+ | Python 图像处理库 |
| 视频处理 | OpenCV | 4.9+ | 计算机视觉库 |
#### 3.1.5 AI 推理
| 类别 | 技术 | 版本 | 说明 |
|------|------|------|------|
| 深度学习 | PyTorch | 2.2+ | 深度学习框架 |
| 推理加速 | ONNX Runtime | 1.17+ | 跨平台推理引擎 |
| 目标检测 | Ultralytics YOLOv8 | 8.1+ | 目标检测模型 |
| 图像分割 | SAM | 0.0+ | Segment Anything Model |
| 语音识别 | Whisper | - | OpenAI 语音识别模型 |
| NLP | Transformers | 4.39+ | Hugging Face NLP 工具包 |
#### 3.1.6 认证与安全
| 类别 | 技术 | 版本 | 说明 |
|------|------|------|------|
| JWT | python-jose | 3.3+ | JWT Token 生成和验证 |
| 密码哈希 | passlib + bcrypt | 1.7+ | 密码加密存储 |
| CORS | FastAPI CORS Middleware | 内置 | 跨域资源共享 |
### 3.2 技术栈汇总表
| 层级 | 技术选型 | 版本要求 |
|------|----------|----------|
| 运行环境 | Python | 3.10+ |
| Web 框架 | FastAPI | 0.110+ |
| ORM | SQLAlchemy | 2.0+ |
| 数据库 | PostgreSQL | 15+ (端口: 5433) |
| 缓存 | Redis | 7+ (端口: 6379) |
| 文件存储 | MinIO | 最新版 (API: 9009, Console: 9010) |
| 任务队列 | Celery | 5.x |
| AI 推理 | ONNX Runtime / Transformers | 最新版 |
| 认证 | PyJWT / python-jose | 最新稳定版 |
| 后端端口 | FastAPI | 8899 |
| 前端端口 | Vue 3 (Vite) | 8008 |
---
## 4. 环境依赖
### 4.1 系统环境要求
```bash
# 操作系统要求
Ubuntu 22.04 LTS / CentOS 8+ / Windows Server 2019+
# 硬件配置建议
CPU: 8 核+
内存: 16GB+
磁盘: 500GB+ (根据数据量调整)
GPU: NVIDIA RTX 3060+ (用于 AI 推理,可选)
```
### 4.2 Python 依赖包
```txt
# backend/requirements.txt
# =================== 核心依赖 ===================
fastapi==0.110.0
uvicorn[standard]==0.27.1
sqlalchemy==2.0.27
alembic==1.13.1
asyncpg==0.29.0
psycopg2-binary==2.9.9
redis==5.0.1
python-jose[cryptography]==3.3.0
passlib[bcrypt]==1.7.4
python-multipart==0.0.9
pydantic==2.6.1
pydantic-settings==2.1.0
aiofiles==23.2.1
# =================== 任务队列 ===================
celery==5.3.6
flower==2.0.1
# =================== 文件存储 ===================
minio==7.2.3
Pillow==10.2.0
numpy==1.26.4
opencv-python-headless==4.9.0.80
# =================== AI 模型依赖 ===================
torch==2.2.1
transformers==4.39.1
accelerate==0.28.0
onnxruntime-gpu==1.17.1
ultralytics==8.1.24
segment-anything==0.0.3
# =================== 语音处理 ===================
openai-whisper==20231117
soundfile==0.12.1
librosa==0.10.1
# =================== 文本处理 ===================
jieba==0.42.1
# =================== 开发依赖 ===================
pytest==8.0.0
pytest-asyncio==0.23.0
httpx==0.27.0
```
### 4.3 系统级依赖
```bash
# Ubuntu/Debian 系统安装
sudo apt-get update
sudo apt-get install -y \
build-essential \
libpq-dev \
libffi-dev \
libssl-dev \
ffmpeg \
libsm6 \
libxext6 \
libxrender-dev \
libgomp1 \
git \
wget \
curl
```
### 4.4 环境变量配置
```bash
# backend/.env
# ========== 应用配置 ==========
APP_NAME=PLabel
APP_ENV=development
APP_DEBUG=true
APP_SECRET_KEY=plabel-secret-key-change-in-production
# ========== 服务器配置 ==========
HOST=0.0.0.0
PORT=8899
# ========== 数据库配置 (PostgreSQL :5433) ==========
POSTGRES_HOST=localhost
POSTGRES_PORT=5433
POSTGRES_DB=plabel
POSTGRES_USER=plabel
POSTGRES_PASSWORD=plabel
DATABASE_URL=postgresql://plabel:plabel@localhost:5433/plabel
ASYNC_DATABASE_URL=postgresql+asyncpg://plabel:plabel@localhost:5433/plabel
# ========== Redis 配置 (:6379) ==========
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_DB=0
REDIS_PASSWORD=
CELERY_BROKER_URL=redis://localhost:6379/0
CELERY_RESULT_BACKEND=redis://localhost:6379/1
# ========== MinIO 配置 (:9009 / :9010) ==========
MINIO_ENDPOINT=localhost:9009
MINIO_ACCESS_KEY=minio
MINIO_SECRET_KEY=minio123
MINIO_BUCKET=plabel-bucket
MINIO_SECURE=false
# ========== JWT 配置 ==========
JWT_SECRET_KEY=plabel-jwt-secret-key-change-in-production
JWT_ALGORITHM=HS256
ACCESS_TOKEN_EXPIRE_MINUTES=1440
# ========== 文件上传配置 ==========
MAX_IMAGE_SIZE_MB=50
MAX_VIDEO_SIZE_MB=500
MAX_AUDIO_SIZE_MB=100
MAX_TEXT_SIZE_MB=10
# ========== AI 模型配置 ==========
AI_MODEL_DEVICE=cpu # cpu 或 cuda
AI_MODEL_CACHE_DIR=./models
CUDA_VISIBLE_DEVICES=0
# ========== CORS 配置 ==========
CORS_ORIGINS=http://localhost:8008,http://localhost:8899
```
---
## 5. 后端项目结构
### 5.1 项目目录结构
```
backend/
├── app/ # 应用主目录
│ ├── __init__.py # 应用初始化
│ ├── main.py # FastAPI 应用入口
│ ├── config.py # 配置管理 (Pydantic Settings)
│ ├── database.py # 数据库连接管理
│ ├── dependencies.py # 依赖注入
│ │
│ ├── api/ # API 路由层
│ │ ├── __init__.py
│ │ └── v1/ # API v1 版本
│ │ ├── __init__.py
│ │ ├── router.py # 路由汇总
│ │ ├── auth.py # 认证模块
│ │ ├── users.py # 用户管理
│ │ ├── projects.py # 项目管理
│ │ ├── tasks.py # 任务管理
│ │ ├── data_items.py # 数据项管理
│ │ ├── annotations.py # 标注管理
│ │ ├── reviews.py # 审核管理
│ │ ├── auto_label.py # 自动标注
│ │ ├── export.py # 数据导出
│ │ ├── models.py # AI 模型管理
│ │ └── statistics.py # 统计分析
│ │
│ ├── models/ # SQLAlchemy 模型
│ │ ├── __init__.py
│ │ ├── base.py # 基础模型类
│ │ ├── user.py # 用户模型
│ │ ├── project.py # 项目模型
│ │ ├── task.py # 任务模型
│ │ ├── data_item.py # 数据项模型
│ │ ├── annotation.py # 标注模型
│ │ ├── review.py # 审核模型
│ │ ├── ai_model.py # AI 模型配置
│ │ └── auto_label_task.py # 自动标注任务
│ │
│ ├── schemas/ # Pydantic 模式定义
│ │ ├── __init__.py
│ │ ├── base.py # 基础 schema
│ │ ├── auth.py # 认证 schema
│ │ ├── user.py # 用户 schema
│ │ ├── project.py # 项目 schema
│ │ ├── task.py # 任务 schema
│ │ ├── data_item.py # 数据项 schema
│ │ ├── annotation.py # 标注 schema
│ │ ├── review.py # 审核 schema
│ │ ├── auto_label.py # 自动标注 schema
│ │ └── common.py # 通用 schema
│ │
│ ├── services/ # 业务逻辑层
│ │ ├── __init__.py
│ │ ├── auth_service.py # 认证服务
│ │ ├── user_service.py # 用户服务
│ │ ├── project_service.py # 项目服务
│ │ ├── task_service.py # 任务服务
│ │ ├── data_item_service.py # 数据项服务
│ │ ├── annotation_service.py # 标注服务
│ │ ├── review_service.py # 审核服务
│ │ ├── export_service.py # 导出服务
│ │ ├── storage_service.py # 存储服务 (MinIO)
│ │ └── ai_service.py # AI 模型服务
│ │
│ ├── core/ # 核心模块
│ │ ├── __init__.py
│ │ ├── security.py # 安全认证工具
│ │ ├── exceptions.py # 自定义异常
│ │ └── constants.py # 常量定义
│ │
│ ├── utils/ # 工具函数
│ │ ├── __init__.py
│ │ ├── file_utils.py # 文件处理
│ │ ├── image_utils.py # 图像处理
│ │ ├── text_utils.py # 文本处理
│ │ └── export_utils.py # 导出工具
│ │
│ └── celery_app.py # Celery 应用配置
│
├── tests/ # 测试目录
│ ├── __init__.py
│ ├── conftest.py # pytest 配置
│ ├── api/ # API 测试
│ │ ├── __init__.py
│ │ ├── test_auth.py
│ │ ├── test_projects.py
│ │ └── test_tasks.py
│ ├── services/ # 服务测试
│ │ └── __init__.py
│ └── fixtures/ # 测试数据
│ └── __init__.py
│
├── alembic/ # 数据库迁移
│ ├── env.py
│ ├── script.py.mako
│ └── versions/ # 迁移版本
│
├── scripts/ # 脚本目录
│ ├── init_db.py # 数据库初始化
│ ├── create_superuser.py # 创建超级用户
│ └── seed_data.py # 种子数据
│
├── models/ # AI 模型文件
│ ├── yolov8/
│ ├── sam/
│ └── whisper/
│
├── data/ # 数据目录
│ ├── uploads/ # 上传文件
│ ├── thumbnails/ # 缩略图
│ └── exports/ # 导出文件
│
├── logs/ # 日志目录
│
├── docker/ # Docker 相关
│ ├── Dockerfile
│ ├── Dockerfile.prod
│ └── docker-entrypoint.sh
│
├── .env # 环境变量
├── .env.example # 环境变量示例
├── .gitignore
├── requirements.txt # Python 依赖
├── requirements-dev.txt # 开发依赖
├── alembic.ini # Alembic 配置
├── pytest.ini # pytest 配置
├── setup.py # 安装脚本
└── README.md # 项目说明
```
### 5.2 核心模块说明
#### 5.2.1 应用入口 (app/main.py)
```python
# app/main.py
from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware
from contextlib import asynccontextmanager
from app.config import settings
from app.database import engine, Base
from app.api.v1 import router as api_router
@asynccontextmanager
async def lifespan(app: FastAPI):
"""应用生命周期管理"""
# 启动时:创建数据库表
async with engine.begin() as conn:
await conn.run_sync(Base.metadata.create_all)
print(f"Starting {settings.APP_NAME} API...")
yield
# 关闭时:清理资源
print("Shutting down...")
await engine.dispose()
app = FastAPI(
title=settings.APP_NAME,
description="AI Training Data Annotation Platform API",
version="2.0.0",
docs_url="/docs",
redoc_url="/redoc",
openapi_url="/openapi.json",
lifespan=lifespan,
)
# CORS 中间件
app.add_middleware(
CORSMiddleware,
allow_origins=settings.CORS_ORIGINS,
allow_credentials=True,
allow_methods=["*"],
allow_headers=["*"],
)
# 注册 API 路由
app.include_router(api_router, prefix="/api/v1")
@app.get("/")
async def root():
return {"message": "Welcome to PLabel API", "version": "2.0.0"}
@app.get("/health")
async def health_check():
return {"status": "healthy", "service": settings.APP_NAME}
```
#### 5.2.2 配置管理 (app/config.py)
```python
# app/config.py
from pydantic_settings import BaseSettings
from functools import lru_cache
from typing import List
class Settings(BaseSettings):
"""应用配置类"""
# 应用配置
APP_NAME: str = "PLabel"
APP_ENV: str = "development"
APP_DEBUG: bool = True
APP_SECRET_KEY: str = "change-this-to-a-super-secret-key"
# 服务器配置
HOST: str = "0.0.0.0"
PORT: int = 8899
# 数据库配置
POSTGRES_HOST: str = "localhost"
POSTGRES_PORT: int = 5433
POSTGRES_DB: str = "plabel"
POSTGRES_USER: str = "plabel"
POSTGRES_PASSWORD: str = "plabel"
@property
def DATABASE_URL(self) -> str:
return f"postgresql://{self.POSTGRES_USER}:{self.POSTGRES_PASSWORD}@{self.POSTGRES_HOST}:{self.POSTGRES_PORT}/{self.POSTGRES_DB}"
@property
def ASYNC_DATABASE_URL(self) -> str:
return f"postgresql+asyncpg://{self.POSTGRES_USER}:{self.POSTGRES_PASSWORD}@{self.POSTGRES_HOST}:{self.POSTGRES_PORT}/{self.POSTGRES_DB}"
# Redis 配置
REDIS_HOST: str = "localhost"
REDIS_PORT: int = 6379
REDIS_PASSWORD: str = ""
@property
def REDIS_URL(self) -> str:
if self.REDIS_PASSWORD:
return f"redis://:{self.REDIS_PASSWORD}@{self.REDIS_HOST}:{self.REDIS_PORT}/0"
return f"redis://{self.REDIS_HOST}:{self.REDIS_PORT}/0"
# Celery 配置
@property
def CELERY_BROKER_URL(self) -> str:
return f"redis://{self.REDIS_HOST}:{self.REDIS_PORT}/0"
@property
def CELERY_RESULT_BACKEND(self) -> str:
return f"redis://{self.REDIS_HOST}:{self.REDIS_PORT}/1"
# MinIO 配置
MINIO_ENDPOINT: str = "localhost:9009"
MINIO_ACCESS_KEY: str = "minio"
MINIO_SECRET_KEY: str = "minio123"
MINIO_BUCKET: str = "plabel-bucket"
MINIO_SECURE: bool = False
# JWT 配置
JWT_SECRET_KEY: str = "your-super-secret-jwt-key"
JWT_ALGORITHM: str = "HS256"
ACCESS_TOKEN_EXPIRE_MINUTES: int = 1440
# CORS 配置
CORS_ORIGINS: List[str] = ["http://localhost:8008"]
# 文件上传配置
MAX_IMAGE_SIZE_MB: int = 50
MAX_VIDEO_SIZE_MB: int = 500
MAX_AUDIO_SIZE_MB: int = 100
MAX_TEXT_SIZE_MB: int = 10
class Config:
env_file = ".env"
case_sensitive = True
@lru_cache()
def get_settings() -> Settings:
return Settings()
settings = get_settings()
```
#### 5.2.3 数据库连接 (app/database.py)
```python
# app/database.py
from sqlalchemy.ext.asyncio import create_async_engine, AsyncSession, async_sessionmaker
from sqlalchemy.orm import DeclarativeBase
from app.config import settings
class Base(DeclarativeBase):
"""SQLAlchemy 基础类"""
pass
engine = create_async_engine(
settings.ASYNC_DATABASE_URL,
echo=settings.APP_DEBUG,
pool_pre_ping=True,
pool_size=10,
max_overflow=20,
)
AsyncSessionLocal = async_sessionmaker(
engine,
class_=AsyncSession,
expire_on_commit=False,
autocommit=False,
autoflush=False,
)
async def get_db() -> AsyncSession:
"""获取数据库会话的依赖函数"""
async with AsyncSessionLocal() as session:
try:
yield session
await session.commit()
except Exception:
await session.rollback()
raise
finally:
await session.close()
```
#### 5.2.4 依赖注入 (app/dependencies.py)
```python
# app/dependencies.py
from fastapi import Depends, HTTPException, status
from fastapi.security import HTTPBearer, HTTPAuthorizationCredentials
from sqlalchemy.ext.asyncio import AsyncSession
from jose import JWTError, jwt
from typing import Optional
from app.database import get_db
from app.config import settings
from app.models.user import User
from app.schemas.auth import TokenData
security = HTTPBearer()
async def get_current_user(
credentials: HTTPAuthorizationCredentials = Depends(security),
db: AsyncSession = Depends(get_db)
) -> User:
"""获取当前登录用户"""
credentials_exception = HTTPException(
status_code=status.HTTP_401_UNAUTHORIZED,
detail="Could not validate credentials",
headers={"WWW-Authenticate": "Bearer"},
)
try:
token = credentials.credentials
payload = jwt.decode(
token,
settings.JWT_SECRET_KEY,
algorithms=[settings.JWT_ALGORITHM]
)
user_id: str = payload.get("sub")
if user_id is None:
raise credentials_exception
token_data = TokenData(user_id=user_id)
except JWTError:
raise credentials_exception
from app.services.user_service import UserService
user = await UserService.get_by_id(db, token_data.user_id)
if user is None:
raise credentials_exception
return user
async def get_current_active_user(
current_user: User = Depends(get_current_user)
) -> User:
"""获取当前活跃用户"""
if not current_user.is_active:
raise HTTPException(status_code=400, detail="Inactive user")
return current_user
def require_roles(*roles):
"""角色权限装饰器工厂"""
async def role_checker(
current_user: User = Depends(get_current_active_user)
) -> User:
if current_user.role not in roles:
raise HTTPException(
status_code=status.HTTP_403_FORBIDDEN,
detail="Not enough permissions"
)
return current_user
return role_checker
```
### 5.3 API 路由结构
```
/api/v1/
├── /auth
│ ├── POST /login # 用户登录
│ ├── POST /register # 用户注册
│ ├── POST /logout # 用户登出
│ ├── GET /me # 获取当前用户
│ └── PUT /me # 更新个人信息
│
├── /users
│ ├── GET / # 获取用户列表 (admin)
│ ├── GET /{user_id} # 获取用户详情
│ ├── PUT /{user_id} # 更新用户 (admin)
│ ├── DELETE /{user_id} # 删除用户 (admin)
│ └── GET /{user_id}/stats # 获取用户统计
│
├── /projects
│ ├── GET / # 获取项目列表
│ ├── POST / # 创建项目
│ ├── GET /{project_id} # 获取项目详情
│ ├── PUT /{project_id} # 更新项目
│ ├── DELETE /{project_id} # 删除项目
│ ├── GET /{project_id}/members # 获取成员
│ ├── POST /{project_id}/members # 添加成员
│ ├── DELETE /{project_id}/members/{user_id} # 移除成员
│ ├── GET /{project_id}/labels # 获取标签集
│ ├── PUT /{project_id}/labels # 更新标签集
│ ├── GET /{project_id}/tasks # 获取任务列表
│ └── GET /{project_id}/statistics # 获取统计
│
├── /tasks
│ ├── GET / # 获取任务列表
│ ├── POST / # 创建任务
│ ├── GET /{task_id} # 获取任务详情
│ ├── PUT /{task_id} # 更新任务
│ ├── DELETE /{task_id} # 删除任务
│ ├── POST /{task_id}/submit # 提交审核
│ ├── POST /{task_id}/approve # 审核通过
│ ├── POST /{task_id}/reject # 审核驳回
│ ├── GET /{task_id}/data-items # 获取数据项
│ └── POST /{task_id}/data-items # 添加数据项
│
├── /data-items
│ ├── GET / # 获取数据项列表
│ ├── GET /{data_item_id} # 获取数据项详情
│ ├── PUT /{data_item_id} # 更新数据项
│ ├── DELETE /{data_item_id} # 删除数据项
│ ├── POST /upload # 上传文件
│ ├── GET /{data_item_id}/signed-url # 获取签名URL
│ └── GET /{data_item_id}/thumbnail # 获取缩略图
│
├── /annotations
│ ├── GET / # 获取标注列表
│ ├── POST /image # 创建图像标注
│ ├── PUT /{annotation_id} # 更新标注
│ ├── DELETE /{annotation_id} # 删除标注
│ ├── POST /audio # 创建音频标注
│ ├── POST /text/entity # 创建文本实体
│ ├── POST /text/relation # 创建文本关系
│ └── POST /batch # 批量保存
│
├── /reviews
│ ├── GET /sessions # 获取审核会话
│ ├── POST /sessions # 创建审核会话
│ ├── GET /sessions/{session_id} # 审核详情
│ ├── POST /sessions/{session_id}/approve # 通过
│ ├── POST /sessions/{session_id}/reject # 驳回
│ ├── POST /sessions/{session_id}/comments # 添加意见
│ └── POST /batch # 批量审核
│
├── /autolabel
│ ├── POST / # 启动自动标注
│ ├── GET /{task_id} # 获取任务状态
│ ├── POST /{task_id}/cancel # 取消任务
│ ├── GET /{task_id}/results # 获取结果
│ ├── POST /{task_id}/apply # 应用结果
│ └── GET /history # 获取历史
│
├── /export
│ ├── POST / # 创建导出任务
│ ├── GET /{export_id} # 获取导出状态
│ └── GET /{export_id}/download # 下载导出文件
│
└── /statistics
├── GET /dashboard # 仪表盘统计
├── GET /tasks # 任务统计
├── GET /users/{user_id}/workload # 工作量统计
└── GET /projects/{project_id}/progress # 项目进度
```
---
## 6. 数据库设计
### 6.1 ER 图概览
```
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ User │──────▶│ Project │◀──────│ Task │
│ 用户表 │ │ 项目表 │ │ 任务表 │
└─────────────┘ └──────┬──────┘ └──────┬──────┘
│ │ │
│ │ │
▼ ▼ ▼
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ProjectMember│ │ LabelSet │ │ DataItem │
│ 项目成员表 │ │ 标签集表 │ │ 数据项表 │
└─────────────┘ └──────┬──────┘ └──────┬──────┘
│ │
▼ ▼
┌─────────────┐ ┌─────────────┐
│ Label │ │ Annotation │
│ 标签表 │ │ 标注表 │
└─────────────┘ └─────────────┘
│
▼
┌─────────────┐ ┌─────────────┐
│AutoLabelTask│ │ReviewSession│
│自动标注任务 │ │ 审核表 │
└─────────────┘ └─────────────┘
```
### 6.2 表结构详细设计
#### 6.2.1 用户表 (users)
```sql
CREATE TABLE users (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
username VARCHAR(50) UNIQUE NOT NULL,
email VARCHAR(255) UNIQUE NOT NULL,
password_hash VARCHAR(255) NOT NULL,
avatar_url VARCHAR(500),
role VARCHAR(20) NOT NULL DEFAULT 'user', -- admin, user, annotator, reviewer
is_active BOOLEAN DEFAULT TRUE,
created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
CONSTRAINT valid_role CHECK (role IN ('admin', 'user', 'annotator', 'reviewer'))
);
CREATE INDEX idx_users_email ON users(email);
CREATE INDEX idx_users_role ON users(role);
```
#### 6.2.2 项目表 (projects)
```sql
CREATE TABLE projects (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
name VARCHAR(200) NOT NULL,
description TEXT,
status VARCHAR(20) NOT NULL DEFAULT 'active', -- active, archived
owner_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
label_set_id UUID,
created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
CONSTRAINT valid_status CHECK (status IN ('active', 'archived'))
);
CREATE INDEX idx_projects_owner ON projects(owner_id);
CREATE INDEX idx_projects_status ON projects(status);
```
#### 6.2.3 任务表 (tasks)
```sql
CREATE TABLE tasks (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
project_id UUID REFERENCES projects(id) ON DELETE CASCADE,
name VARCHAR(200) NOT NULL,
description TEXT,
data_type VARCHAR(20) NOT NULL, -- image, video, audio, text
annotation_types JSONB NOT NULL DEFAULT '[]',
status VARCHAR(20) NOT NULL DEFAULT 'pending',
assignee_id UUID REFERENCES users(id),
reviewer_id UUID REFERENCES users(id),
ai_model_id UUID,
progress INTEGER DEFAULT 0,
total_count INTEGER DEFAULT 0,
completed_count INTEGER DEFAULT 0,
reviewed_count INTEGER DEFAULT 0,
rejected_count INTEGER DEFAULT 0,
created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
CONSTRAINT valid_data_type CHECK (data_type IN ('image', 'video', 'audio', 'text')),
CONSTRAINT valid_task_status CHECK (status IN ('pending', 'in_progress', 'submitted', 'rejected', 'reviewed', 'exported', 'paused'))
);
CREATE INDEX idx_tasks_project ON tasks(project_id);
CREATE INDEX idx_tasks_status ON tasks(status);
CREATE INDEX idx_tasks_assignee ON tasks(assignee_id);
```
#### 6.2.4 数据项表 (data_items)
```sql
CREATE TABLE data_items (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
task_id UUID NOT NULL REFERENCES tasks(id) ON DELETE CASCADE,
name VARCHAR(500) NOT NULL,
type VARCHAR(20) NOT NULL,
file_path VARCHAR(1000) NOT NULL,
thumbnail_path VARCHAR(1000),
size BIGINT NOT NULL,
mime_type VARCHAR(100),
width INTEGER,
height INTEGER,
duration DECIMAL(10,2),
pages INTEGER,
metadata JSONB DEFAULT '{}',
annotation_status VARCHAR(20) DEFAULT 'none',
created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);
CREATE INDEX idx_data_items_task ON data_items(task_id);
CREATE INDEX idx_data_items_status ON data_items(annotation_status);
```
#### 6.2.5 标注表 (annotations)
```sql
CREATE TABLE annotations (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
data_item_id UUID NOT NULL REFERENCES data_items(id) ON DELETE CASCADE,
user_id UUID NOT NULL REFERENCES users(id),
label_id UUID,
annotation_type VARCHAR(30) NOT NULL,
label_name VARCHAR(100) NOT NULL,
data JSONB NOT NULL,
visible BOOLEAN DEFAULT TRUE,
occluded BOOLEAN DEFAULT FALSE,
ignored BOOLEAN DEFAULT FALSE,
frame_index INTEGER DEFAULT 0,
created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);
CREATE INDEX idx_annotations_data_item ON annotations(data_item_id);
CREATE INDEX idx_annotations_user ON annotations(user_id);
```
---
## 7. API 接口规范
### 7.1 统一响应格式
```typescript
// 成功响应
{
"code": 200,
"message": "success",
"data": { ... }
}
// 错误响应
{
"code": 400,
"message": "Validation error",
"errors": [
{ "field": "email", "message": "Invalid email format" }
]
}
// 分页响应
{
"code": 200,
"message": "success",
"data": {
"items": [...],
"total": 100,
"page": 1,
"page_size": 20,
"total_pages": 5
}
}
```
### 7.2 认证接口
```python
# POST /api/v1/auth/login
# 请求
{
"email": "admin@plabel.com",
"password": "admin123"
}
# 响应
{
"code": 200,
"data": {
"access_token": "eyJhbGciOiJIUzI1NiIs...",
"token_type": "bearer",
"expires_in": 86400,
"user": {
"id": "uuid",
"username": "admin",
"email": "admin@plabel.com",
"role": "admin",
"avatar_url": "..."
}
}
}
```
### 7.3 核心接口列表
| 模块 | 接口数 | 主要功能 |
|------|--------|----------|
| 认证 | 6 | 登录、注册、登出、个人信息 |
| 用户 | 5 | 用户CRUD、统计 |
| 项目 | 12 | 项目CRUD、成员管理、标签集 |
| 任务 | 10 | 任务CRUD、状态流转、数据项 |
| 数据 | 8 | 数据项CRUD、上传、预览 |
| 标注 | 10 | 图像/音频/文本标注CRUD |
| 审核 | 8 | 审核流程、意见、批量审核 |
| 自动标注 | 6 | 任务管理、结果应用 |
| 导出 | 3 | 导出任务、下载 |
| 统计 | 4 | 仪表盘、各类统计 |
| **总计** | **72** | 完整的功能接口 |
---
## 8. AI 模型服务
### 8.1 支持的 AI 模型
| 模型类型 | 模型名称 | 用途 | 输入 | 输出 |
|----------|----------|------|------|------|
| 目标检测 | YOLOv8 | 车辆、行人等检测 | 图像 | 边界框 |
| 语义分割 | SAM | 像素级分割 | 图像+提示 | 掩码 |
| 姿态估计 | MMPose | 人体关键点 | 图像 | 关键点坐标 |
| OCR | PaddleOCR | 文字识别 | 图像 | 文本+位置 |
| 语音识别 | Whisper | 音频转文字 | 音频 | 时间戳+文本 |
| NER | Qwen/BERT | 命名实体识别 | 文本 | 实体列表 |
### 8.2 自动标注流程
```python
# 自动标注任务执行流程
async def run_auto_label_task(task_id: str, model_id: str, data_item_ids: list):
"""
1. 创建自动标注任务记录
2. 从数据库获取待处理数据项
3. 调用对应 AI 模型推理
4. 将推理结果转换为标注格式
5. 保存标注结果
6. 更新任务进度
"""
auto_task = await create_auto_label_task(task_id, model_id, data_item_ids)
for i, data_item in enumerate(data_items):
result = await model.inference(data_item.file_path)
annotations = convert_to_annotations(result, model.type)
await save_annotations(data_item.id, annotations)
progress = int((i + 1) / len(data_items) * 100)
await update_auto_task_progress(auto_task.id, progress)
await complete_auto_label_task(auto_task.id)
```
---
## 9. 文件存储方案
### 9.1 存储架构
```
前端上传 ──▶ FastAPI 签名 ──▶ MinIO 直传
│
▼
┌─────────────┐
│ MinIO │
│ originals/ │ ──▶ 原始文件
│ thumbnails/ │ ──▶ 缩略图
│ exports/ │ ──▶ 导出文件
└─────────────┘
```
### 9.2 存储桶结构
```
plabel-bucket/
├── originals/ # 原始上传文件
│ └── {project_id}/
│ └── {task_id}/
│ ├── images/{uuid}.{ext}
│ ├── videos/{uuid}.{ext}
│ ├── audios/{uuid}.{ext}
│ └── texts/{uuid}.{ext}
├── thumbnails/ # 缩略图
└── exports/ # 导出文件
```
### 9.3 文件上传接口
```python
# 方案1: 预签名URL上传 (推荐大文件)
@router.post("/presigned-url")
async def get_presigned_url(task_id: str, file_name: str, content_type: str):
file_key = f"originals/{task_id}/{uuid4()}.{file_name.split('.')[-1]}"
url = await minio_client.presigned_put_object(
bucket_name="plabel-bucket",
object_name=file_key,
expires=timedelta(hours=1)
)
return {"upload_url": url, "file_key": file_key}
```
---
## 10. 功能模块详细需求
### 10.1 认证与用户管理
| 功能 | 优先级 | 说明 |
|------|--------|------|
| 用户注册 | P0 | 邮箱、用户名、密码 |
| 用户登录 | P0 | JWT Token 认证 |
| 密码修改 | P1 | 旧密码验证 |
| 角色权限 | P0 | admin/user/annotator/reviewer |
### 10.2 项目管理
| 功能 | 优先级 | 说明 |
|------|--------|------|
| 创建项目 | P0 | 名称、描述 |
| 成员管理 | P0 | 添加/移除成员、角色分配 |
| 标签集管理 | P0 | 标签定义(矩形、多边形等) |
| 项目归档 | P1 | 归档/恢复 |
### 10.3 任务管理
| 功能 | 优先级 | 说明 |
|------|--------|------|
| 创建任务 | P0 | 关联项目、选择数据类型 |
| 任务分配 | P0 | 分配标注员、审核员 |
| 状态流转 | P0 | pending→in_progress→submitted→reviewed |
| 进度跟踪 | P1 | 实时更新进度百分比 |
### 10.4 标注功能
| 功能 | 优先级 | 说明 |
|------|--------|------|
| 图像标注 | P0 | 矩形、多边形、画笔、关键点 |
| 音频标注 | P0 | 时间戳范围、转写文本 |
| 文本标注 | P0 | NER 实体、关系 |
| 批量保存 | P0 | 一次保存多条标注 |
### 10.5 审核管理
| 功能 | 优先级 | 说明 |
|------|--------|------|
| 提交审核 | P0 | 提交标注结果 |
| 审核通过 | P0 | 一键通过 |
| 审核驳回 | P0 | 填写驳回原因 |
| 审核意见 | P1 | 针对具体标注添加意见 |
### 10.6 数据导出
| 功能 | 优先级 | 说明 |
|------|--------|------|
| COCO 格式 | P0 | 目标检测、分割 |
| YOLO 格式 | P0 | YOLO 训练格式 |
| SRT/VTT | P0 | 音频字幕 |
| CoNLL | P1 | NER 格式 |
---
## 11. 安全与权限
### 11.1 角色权限矩阵
| 权限 | Admin | User | Annotator | Reviewer |
|------|-------|------|-----------|----------|
| 用户管理 | ✓ | ✗ | ✗ | ✗ |
| 创建项目 | ✓ | ✓ | ✗ | ✗ |
| 标注数据 | ✓ | ✓ | ✓ | ✓ |
| 提交审核 | ✓ | ✓ | ✓ | ✓ |
| 审核数据 | ✓ | ✗ | ✗ | ✓ |
| 导出数据 | ✓ | ✓ | ✗ | ✗ |
### 11.2 JWT 配置
```python
JWT_SECRET_KEY = "plabel-jwt-secret-key"
JWT_ALGORITHM = "HS256"
ACCESS_TOKEN_EXPIRE_MINUTES = 1440 # 24小时
```
---
## 12. 部署架构
### 12.1 Docker 部署
```yaml
# docker-compose.yml
version: '3.8'
services:
postgres:
image: postgres:15-alpine
ports:
- "5433:5432"
environment:
POSTGRES_DB: plabel
POSTGRES_USER: plabel
POSTGRES_PASSWORD: plabel
redis:
image: redis:7-alpine
ports:
- "6379:6379"
minio:
image: minio/minio:latest
ports:
- "9009:9000"
- "9010:9010"
environment:
MINIO_ROOT_USER: minio
MINIO_ROOT_PASSWORD: minio123
command: server /data --console-address ":9010"
backend:
build: ./backend
ports:
- "8899:8899"
depends_on:
- postgres
- redis
- minio
environment:
POSTGRES_HOST: postgres
POSTGRES_PORT: 5432
REDIS_HOST: redis
MINIO_ENDPOINT: minio:9000
MINIO_ACCESS_KEY: minio
MINIO_SECRET_KEY: minio123
celery_worker:
build: ./backend
command: celery -A app.celery_app worker --loglevel=info
depends_on:
- redis
- postgres
flower:
build: ./backend
ports:
- "5555:5555"
command: celery -A app.celery_app flower --port=5555
```
### 12.2 服务端口总览
| 服务 | 端口 | 账号 | 密码 |
|------|------|------|------|
| PostgreSQL | 5433 | plabel | plabel |
| Redis | 6379 | - | - |
| MinIO API | 9009 | minio | minio123 |
| MinIO Console | 9010 | minio | minio123 |
| FastAPI | 8899 | - | - |
| Flower | 5555 | - | - |
| Vue Frontend | 8008 | - | - |
---
## 13. 开发里程碑
### 13.1 开发阶段总览
| 阶段 | 周期 | 优先级 | 主要内容 |
|------|------|--------|----------|
| Phase 0 | 1周 | P0 | 项目初始化、环境搭建 |
| Phase 1 | 2周 | P0 | 认证模块、用户管理 |
| Phase 2 | 2周 | P0 | 项目管理、任务管理 |
| Phase 3 | 2周 | P0 | 数据管理、文件上传 |
| Phase 4 | 2周 | P0 | 标注 CRUD、审核管理 |
| Phase 5 | 2周 | P1 | AI 模型集成、自动标注 |
| Phase 6 | 1周 | P1 | 数据导出 |
| Phase 7 | 1周 | P2 | 统计模块、WebSocket |
| Phase 8 | 1周 | P1 | 测试、优化、安全审计 |
| **总计** | **12周** | - | - |
### 13.2 Phase 0: 项目初始化(第1周)
**目标**: 完成开发环境搭建和基础架构
| 任务 | 描述 | 验收标准 |
|------|------|----------|
| 0.1 | 创建 FastAPI 项目结构 | 目录结构符合设计 |
| 0.2 | 配置 PostgreSQL 数据库 | 端口 5433 可连接 |
| 0.3 | 配置 Redis 连接 | 端口 6379 可连接 |
| 0.4 | 配置 MinIO 对象存储 | 端口 9009/9010 可访问 |
| 0.5 | 配置 Celery 任务队列 | Worker 可正常启动 |
| 0.6 | 配置 Alembic 数据库迁移 | 可执行迁移 |
| 0.7 | 编写 Docker 配置 | docker-compose 可启动 |
| 0.8 | 配置日志系统 | 日志正常输出 |
**验收标准**:
- [ ] `docker-compose up` 可成功启动所有服务
- [ ] API 文档可访问 (http://localhost:8899/docs)
- [ ] 数据库连接正常
- [ ] 文件上传到 MinIO 正常
### 13.3 Phase 1: 认证与用户管理(第2-3周)
**目标**: 完成用户认证和权限管理
| 任务 | 描述 | 验收标准 |
|------|------|----------|
| 1.1 | 实现用户注册接口 | 邮箱、用户名唯一性校验 |
| 1.2 | 实现登录/登出接口 | JWT Token 生成和验证 |
| 1.3 | 实现用户 CRUD | 管理员可管理用户 |
| 1.4 | 实现角色权限控制 | 四种角色权限生效 |
| 1.5 | 编写 API 单元测试 | 测试覆盖率 > 60% |
| 1.6 | 对接前端登录页面 | 前端可正常登录 |
### 13.4 Phase 2: 项目与任务管理(第4-5周)
**目标**: 完成项目管理、任务管理和数据管理
| 任务 | 描述 | 验收标准 |
|------|------|----------|
| 2.1 | 实现项目 CRUD | 可创建/编辑/删除项目 |
| 2.2 | 实现成员管理 | 添加/移除/分配角色 |
| 2.3 | 实现任务 CRUD | 可创建/编辑/删除任务 |
| 2.4 | 实现任务状态流转 | 状态正确转换 |
| 2.5 | 实现任务分配 | 分配标注员/审核员 |
| 2.6 | 对接前端项目管理 | 前端可管理项目 |
| 2.7 | 对接前端任务管理 | 前端可管理任务 |
### 13.5 Phase 3: 数据管理与文件上传(第6-7周)
**目标**: 完成文件上传、存储、元数据提取
| 任务 | 描述 | 验收标准 |
|------|------|----------|
| 3.1 | 实现文件预签名上传 | 支持大文件直传 MinIO |
| 3.2 | 实现文件元数据提取 | 提取图像/视频尺寸等信息 |
| 3.3 | 实现缩略图生成 | 自动生成预览缩略图 |
| 3.4 | 实现签名 URL 生成 | 安全的文件访问 |
| 3.5 | 对接前端数据上传 | 前端可上传文件 |
| 3.6 | 对接前端数据管理 | 前端可管理数据 |
### 13.6 Phase 4: 标注与审核(第8-9周)
**目标**: 完成标注功能和审核管理
| 任务 | 描述 | 验收标准 |
|------|------|----------|
| 4.1 | 实现图像标注 CRUD | 矩形/多边形/关键点标注 |
| 4.2 | 实现音频标注 CRUD | 时间戳范围标注 |
| 4.3 | 实现文本标注 CRUD | NER 实体/关系标注 |
| 4.4 | 实现审核流程 | 提交/通过/驳回 |
| 4.5 | 实现审核意见 | 针对标注添加意见 |
| 4.6 | 对接前端标注编辑器 | 前端可进行标注 |
| 4.7 | 对接前端审核页面 | 前端可审核数据 |
### 13.7 Phase 5: AI 自动标注(第10-11周)
**目标**: 完成 AI 模型集成和自动标注
| 任务 | 描述 | 验收标准 |
|------|------|----------|
| 5.1 | 集成 YOLOv8 模型 | 目标检测正常工作 |
| 5.2 | 集成 Whisper 模型 | 语音转写正常工作 |
| 5.3 | 集成 NER 模型 | 命名实体识别正常 |
| 5.4 | 实现异步任务队列 | 任务可排队执行 |
| 5.5 | 实现进度跟踪 | 实时显示推理进度 |
| 5.6 | 对接前端自动标注 | 前端可触发自动标注 |
### 13.8 Phase 6: 数据导出(第12周)
**目标**: 完成数据导出功能
| 任务 | 描述 | 验收标准 |
|------|------|----------|
| 6.1 | 实现 COCO 导出 | 导出标准 COCO 格式 |
| 6.2 | 实现 YOLO 导出 | 导出 YOLO TXT 格式 |
| 6.3 | 实现字幕导出 | 导出 SRT/VTT 格式 |
| 6.4 | 实现 NER 导出 | 导出 CoNLL 格式 |
| 6.5 | 对接前端导出 | 前端可导出数据 |
### 13.9 Phase 7: 统计与实时(第13周)
**目标**: 完成统计功能和实时通信(可选)
| 任务 | 描述 | 验收标准 |
|------|------|----------|
| 7.1 | 实现工作台统计 | 统计仪表盘数据 |
| 7.2 | 实现工作量统计 | 用户标注量统计 |
| 7.3 | 实现项目进度统计 | 各任务进度汇总 |
| 7.4 | WebSocket 集成(可选) | 实时推送进度 |
### 13.10 Phase 8: 测试与优化(第14周)
**目标**: 完成测试和部署准备
| 任务 | 描述 | 验收标准 |
|------|------|----------|
| 8.1 | API 集成测试 | 测试覆盖率 > 70% |
| 8.2 | 性能测试 | API 响应 < 200ms |
| 8.3 | 安全审计 | 无安全漏洞 |
| 8.4 | 编写部署文档 | 完整的部署指南 |
| 8.5 | 配置 CI/CD | 自动化构建部署 |
---
## 14. 前后端联调方案
### 14.1 联调环境配置
**前端配置 (Vue :8008)**
```typescript
// vite.config.ts
export default defineConfig({
server: {
port: 8008,
proxy: {
'/api': {
target: 'http://localhost:8899',
changeOrigin: true,
},
},
},
})
```
**后端 CORS 配置**
```python
# CORS 配置允许前端
CORS_ORIGINS = [
"http://localhost:8008",
]
```
### 14.2 联调步骤
1. **启动后端服务**
```bash
cd /home/admin2/plabel/backend
source venv/bin/activate
uvicorn app.main:app --host 0.0.0.0 --port 8899 --reload
```
2. **启动前端服务**
```bash
cd /home/admin2/plabel/frontend
npm run dev # 端口 8008
```
3. **验证服务**
- 后端: http://localhost:8899/docs
- 前端: http://localhost:8008
4. **接口对接**
- 前端请求 `/api/v1/...` 自动代理到后端
- 登录获取 Token 并存储
- 后续请求携带 Token
### 14.3 接口对接清单
| 前端页面 | 对应后端接口 | 状态 |
|----------|-------------|------|
| 登录 | POST /api/v1/auth/login | 待对接 |
| 注册 | POST /api/v1/auth/register | 待对接 |
| 项目列表 | GET /api/v1/projects | 待对接 |
| 项目详情 | GET /api/v1/projects/{id} | 待对接 |
| 任务列表 | GET /api/v1/tasks | 待对接 |
| 数据上传 | POST /api/v1/data-items/upload | 待对接 |
| 标注保存 | POST /api/v1/annotations | 待对接 |
| 提交审核 | POST /api/v1/tasks/{id}/submit | 待对接 |
---
## 附录
### A. 参考文档
- [FastAPI 官方文档](https://fastapi.tiangolo.com/)
- [SQLAlchemy 文档](https://docs.sqlalchemy.org/)
- [Celery 文档](https://docs.celeryproject.org/)
- [MinIO 文档](https://min.io/docs/)
- [Vue 3 官方文档](https://vuejs.org/)
### B. 端口速查表
| 服务 | 端口 | 前端 (Vue) |
|------|------|-----------|
| PostgreSQL | 5433 | - |
| Redis | 6379 | - |
| MinIO API | 9009 | - |
| MinIO Console | 9010 | - |
| FastAPI | 8899 | - |
| Flower | 5555 | - |
| Vue Frontend | 8008 | - |
### C. 账号凭证
| 服务 | 账号 | 密码 |
|------|------|------|
| PostgreSQL | plabel | plabel |
| MinIO | minio | minio123 |
| JWT | - | plabel-jwt-secret-key |
---
*文档版本: v2.0*
*创建日期: 2026年5月28日*
*更新记录:*
- v2.0 (2026-05-28): 全面更新,详细规划后端项目结构、增加开发里程碑
- v1.0 (2026-05-28): 初始版本
# PLabel 服务端口与凭证清单
> 文档版本:v1.0
> 创建日期:2026年5月28日
> 参考文档:[后端需求清单.md](./后端需求清单.md)
---
## 1. 服务端口总览
| 服务名称 | 端口 | 协议 | 用途 | 默认账号 | 默认密码 |
|---------|------|------|------|---------|---------|
| PostgreSQL | 5433 | TCP | 主数据库 | plabel | plabel |
| Redis | 6379 | TCP | 缓存/消息队列 | - | - |
| MinIO API | 9009 | HTTP | 对象存储 API | minio | minio123 |
| MinIO Console | 9010 | HTTP | 对象存储管理界面 | minio | minio123 |
| FastAPI Backend | 8899 | HTTP | 后端 API 服务 | - | - |
| API Docs | 8899/docs | HTTP | Swagger API 文档 | - | - |
| Flower | 5555 | HTTP | Celery 任务监控 | - | - |
| Nginx HTTP | 80 | HTTP | 前端静态服务/反向代理 | - | - |
| Nginx HTTPS | 443 | HTTPS | HTTPS 服务 | - | - |
---
## 2. 详细配置
### 2.1 PostgreSQL 数据库
| 配置项 | 开发环境 | 生产环境 |
|-------|---------|---------|
| 主机 | localhost / postgres | postgres |
| 端口 | 5433 | 5433 |
| 数据库名 | plabel | plabel |
| 用户名 | plabel | plabel |
| 密码 | plabel | ${POSTGRES_PASSWORD} |
| 连接字符串 | `postgresql://plabel:plabel@localhost:5433/plabel` | `postgresql://plabel:${POSTGRES_PASSWORD}@postgres:5433/plabel` |
| 异步连接字符串 | `postgresql+asyncpg://plabel:plabel@localhost:5433/plabel` | `postgresql+asyncpg://plabel:${POSTGRES_PASSWORD}@postgres:5433/plabel` |
### 2.2 Redis 缓存
| 配置项 | 开发环境 | 生产环境 |
|-------|---------|---------|
| 主机 | localhost | redis |
| 端口 | 6379 | 6379 |
| 密码 | 无 | ${REDIS_PASSWORD} |
| Celery Broker URL | redis://localhost:6379/0 | redis://redis:6379/0 |
| Celery Result Backend | redis://localhost:6379/1 | redis://redis:6379/1 |
| Redis Database | 0 | 0 |
### 2.3 MinIO 对象存储
| 配置项 | 开发环境 | 生产环境 |
|-------|---------|---------|
| API 端点 | localhost:9009 | minio:9009 |
| Console 端点 | localhost:9010 | minio:9010 |
| Access Key | minio | ${MINIO_ACCESS_KEY} |
| Secret Key | minio123 | ${MINIO_SECRET_KEY} |
| Bucket 名称 | plabel-bucket | plabel-bucket |
| 存储桶路径 | originals/ / thumbnails/ / exports/ | originals/ / thumbnails/ / exports/ |
| 是否启用 HTTPS | false | false |
**MinIO Console 访问地址:**
- 开发环境:http://localhost:9010
- 生产环境:http://minio:9010
### 2.4 FastAPI 后端服务
| 配置项 | 开发环境 | 生产环境 |
|-------|---------|---------|
| 主机 | 0.0.0.0 | 0.0.0.0 |
| 端口 | 8899 | 8899 |
| API 文档 | http://localhost:8899/docs | http://api.plabel.com/docs |
| ReDoc | http://localhost:8899/redoc | http://api.plabel.com/redoc |
| 健康检查 | http://localhost:8899/health | http://api.plabel.com/health |
### 2.5 Celery 任务队列
| 配置项 | 开发环境 | 生产环境 |
|-------|---------|---------|
| Broker | redis://localhost:6379/0 | redis://redis:6379/0 |
| Backend | redis://localhost:6379/1 | redis://redis:6379/1 |
| Worker 并发数 | 2 | 4 |
| GPU 任务队列 | gpu_tasks | gpu_tasks |
| CPU 任务队列 | cpu_tasks | cpu_tasks |
### 2.6 Flower 监控面板
| 配置项 | 开发环境 | 生产环境 |
|-------|---------|---------|
| 主机 | 0.0.0.0 | 0.0.0.0 |
| 端口 | 5555 | 5555 |
| 访问地址 | http://localhost:5555 | http://flower.plabel.com |
---
## 3. 环境变量配置
### 3.1 开发环境 (.env)
```bash
# 应用配置
APP_NAME=PLabel
APP_ENV=development
APP_DEBUG=true
APP_SECRET_KEY=change-this-to-a-super-secret-key-in-production
# 数据库
DATABASE_URL=postgresql://plabel:plabel@localhost:5433/plabel
ASYNC_DATABASE_URL=postgresql+asyncpg://plabel:plabel@localhost:5433/plabel
# Redis
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=
REDIS_URL=redis://localhost:6379/0
CELERY_BROKER_URL=redis://localhost:6379/0
CELERY_RESULT_BACKEND=redis://localhost:6379/1
# MinIO
MINIO_ENDPOINT=localhost:9009
MINIO_ACCESS_KEY=minio
MINIO_SECRET_KEY=minio123
MINIO_BUCKET=plabel-bucket
MINIO_SECURE=false
# JWT
JWT_SECRET_KEY=your-super-secret-jwt-key-change-this-in-production
JWT_ALGORITHM=HS256
ACCESS_TOKEN_EXPIRE_MINUTES=1440
# CORS
CORS_ORIGINS=http://localhost:8008,http://localhost:8899
```
### 3.2 生产环境 (.env.production)
```bash
# 应用配置
APP_NAME=PLabel
APP_ENV=production
APP_DEBUG=false
APP_SECRET_KEY=your-super-secret-key-change-this
# 数据库
POSTGRES_HOST=postgres
POSTGRES_PORT=5433
POSTGRES_DB=plabel
POSTGRES_USER=plabel
POSTGRES_PASSWORD=plabel
DATABASE_URL=postgresql://plabel:${POSTGRES_PASSWORD}@postgres:5433/plabel
ASYNC_DATABASE_URL=postgresql+asyncpg://plabel:${POSTGRES_PASSWORD}@postgres:5433/plabel
# Redis
REDIS_HOST=redis
REDIS_PORT=6379
REDIS_PASSWORD=
REDIS_URL=redis://redis:6379/0
CELERY_BROKER_URL=redis://redis:6379/0
CELERY_RESULT_BACKEND=redis://redis:6379/1
# MinIO
MINIO_ENDPOINT=minio:9009
MINIO_ACCESS_KEY=minio
MINIO_SECRET_KEY=minio123
MINIO_BUCKET=plabel-bucket
MINIO_SECURE=false
# JWT
JWT_SECRET_KEY=plabel-jwt-secret-key
JWT_ALGORITHM=HS256
ACCESS_TOKEN_EXPIRE_MINUTES=1440
```
---
## 4. Docker 端口映射
### 4.1 docker-compose.yml 端口配置
```yaml
services:
postgres:
ports:
- "5433:5433" # PostgreSQL 数据库
redis:
ports:
- "6379:6379" # Redis 缓存/队列
minio:
ports:
- "9009:9009" # MinIO API
- "9010:9010" # MinIO Console
backend:
ports:
- "8899:8899" # FastAPI 后端服务
flower:
ports:
- "5555:5555" # Celery 监控面板
```
---
## 5. 访问地址速查表
### 5.1 本地开发环境
| 服务 | 访问地址 |
|------|---------|
| 前端应用 | http://localhost:8008 |
| 后端 API | http://localhost:8899 |
| API 文档 (Swagger) | http://localhost:8899/docs |
| API 文档 (ReDoc) | http://localhost:8899/redoc |
| MinIO Console | http://localhost:9010 |
| Flower 监控 | http://localhost:5555 |
| PostgreSQL | localhost:5433 |
| Redis | localhost:6379 |
### 5.2 生产环境
| 服务 | 访问地址 |
|------|---------|
| 前端应用 | https://plabel.com |
| 后端 API | https://api.plabel.com |
| API 文档 | https://api.plabel.com/docs |
| MinIO Console | http://minio:9010 |
| Flower 监控 | http://flower.plabel.com:5555 |
| PostgreSQL | postgres:5433 |
| Redis | redis:6379 |
---
## 6. 默认账号信息
### 6.1 开发环境默认账号
| 服务 | 用户名 | 密码 | 说明 |
|------|-------|------|------|
| PostgreSQL | plabel | plabel | 数据库管理员 |
| MinIO | minio | minio123 | 对象存储管理员 |
| PLabel 管理员 | admin@plabel.com | admin123 | 平台管理员 (需创建) |
### 6.2 生产环境账号配置
> **重要**: 生产环境必须更改以下默认配置:
```bash
# 必须修改的密码
POSTGRES_PASSWORD=<强密码>
MINIO_ACCESS_KEY=<随机字符串>
MINIO_SECRET_KEY=<强随机字符串>
APP_SECRET_KEY=<随机字符串>
JWT_SECRET_KEY=<随机字符串>
```
---
## 7. 网络连通性检查
### 7.1 检查服务是否运行
```bash
# 检查 PostgreSQL
pg_isready -h localhost -p 5433 -U plabel
# 检查 Redis
redis-cli -h localhost -p 6379 ping
# 检查 MinIO
curl http://localhost:9009/minio/health/live
# 检查后端 API
curl http://localhost:8000/health
```
### 7.2 Docker 网络配置
所有服务通过 `docker-compose` 部署时,使用内部网络进行通信:
```yaml
networks:
default:
name: plabel-network
```
容器间通过服务名访问:
- `postgres` → PostgreSQL:5433
- `redis` → Redis:6379
- `minio` → MinIO:9009/9010
- `backend` → Backend:8899
---
## 8. 端口冲突排查
### 8.1 常见端口占用
| 端口 | 常见冲突服务 |
|------|------------|
| 5433 | PostgreSQL, Postgres.app |
| 6379 | Redis, Adobe Crash Reporter |
| 8899 | Python/FastAPI, Java |
| 9000-9010 | MinIO, Tomcat |
| 5555 | Flower, 其他 Web 服务 |
### 8.2 排查命令
```bash
# 查看端口占用
lsof -i :5433
lsof -i :6379
lsof -i :8899
lsof -i :9009
lsof -i :9010
# 或使用 ss
ss -tlnp | grep 5433
ss -tlnp | grep 6379
ss -tlnp | grep 8899
```
---
*文档版本: v1.0*
*创建日期: 2026年5月28日*
# PLabel 后端项目目录结构
> 文档版本:v1.0
> 创建日期:2026年5月28日
> 参考文档:[后端需求清单](./后端需求清单.md)
> 目标:为后端开发团队提供规范化、统一的目录结构指导
---
## 1. 整体目录概览
```
plabel/
├── backend/ # FastAPI 后端项目根目录
│ ├── app/ # 应用主代码包
│ │ ├── api/ # API 路由层 (对应需求: API 接口规范)
│ │ ├── core/ # 核心基础设施 (配置/安全/数据库/缓存)
│ │ ├── models/ # SQLAlchemy ORM 模型 (对应需求: 数据库设计)
│ │ ├── schemas/ # Pydantic 数据校验模型
│ │ ├── services/ # 业务逻辑层
│ │ ├── tasks/ # Celery 异步任务 (对应需求: AI 模型服务)
│ │ ├── utils/ # 工具函数与辅助模块
│ │ ├── celery.py # Celery 应用实例配置
│ │ └── main.py # FastAPI 应用入口
│ ├── alembic/ # 数据库迁移 (对应需求: 数据库设计)
│ │ ├── versions/ # 迁移版本文件
│ │ ├── env.py # Alembic 环境配置
│ │ └── alembic.ini # Alembic 主配置
│ ├── scripts/ # 运维脚本 (初始化/迁移/工具)
│ ├── tests/ # 测试代码 (对应需求: Phase 7)
│ ├── configs/ # 各类配置文件 (Nginx/Docker等)
│ │ ├── nginx/
│ │ └── docker/
│ ├── models/ # AI 模型文件存储 (对应需求: AI 模型服务)
│ │ ├── vision/ # 视觉模型 (YOLO/SAM/Pose)
│ │ ├── audio/ # 音频模型 (Whisper)
│ │ └── text/ # 文本模型 (BERT/Qwen)
│ ├── data/ # 数据文件存储 (对应需求: 文件存储方案)
│ │ ├── uploads/ # 用户上传文件 (临时/分片)
│ │ ├── thumbnails/ # 缩略图
│ │ └── exports/ # 导出数据集
│ ├── logs/ # 日志文件目录
│ ├── docs/ # 项目开发文档
│ ├── Dockerfile # Docker 镜像构建
│ ├── Dockerfile.gpu # GPU 镜像构建 (AI 推理专用)
│ ├── docker-compose.yml # 开发环境 Docker Compose
│ ├── docker-compose.prod.yml # 生产环境 Docker Compose
│ ├── docker-compose.model.yml # AI 模型服务 Docker Compose
│ ├── .env.example # 环境变量示例
│ ├── requirements.txt # Python 依赖
│ ├── requirements-ai.txt # AI 模块依赖 (可选安装)
│ ├── pytest.ini # Pytest 配置
│ ├── .gitignore
│ ├── README.md
│ └── Makefile # Make 快捷命令
│
├── frontend/ # Vue 3 前端项目 (已存在)
│ └── ...
│
├── md/ # 项目文档目录
│ ├── 后端需求清单.md # 后端需求规格书
│ ├── 项目目录结构.md # 本文档
│ ├── 接口文档.md # API 详细接口文档
│ ├── 数据库设计.md # 数据库详细设计文档
│ ├── 部署文档.md # 部署与运维文档
│ └── 开发指南.md # 开发规范与指南
│
└── docs/ # 架构设计文档 (.drawio.png 格式)
├── 系统架构图.drawio
├── 数据库ER图.drawio
└── AI推理架构图.drawio
```
---
## 2. `app/` 应用主代码包详解
```
app/
├── __init__.py # 包初始化,导出 app 实例
├── main.py # FastAPI 入口,注册中间件/路由/异常处理
├── celery.py # Celery 应用实例,任务注册,队列配置
│
├── api/ # ==========================================
│ │ # API 路由层:接收请求 → 调用 Service → 返回响应
│ │ # 文件命名: {resource}_router.py
│ │ # 路由前缀: /api/v1/{resource}
│ │ # 对应需求: 5.x API 接口规范
│ │ # ==========================================
│ ├── __init__.py # 导出 api_router (用于 main.py 挂载)
│ │
│ ├── deps.py # API 公共依赖注入 (认证/鉴权/分页/会话)
│ │ # - get_current_user() — JWT 鉴权
│ │ # - get_current_active_user()
│ │ # - require_roles(*roles)
│ │ # - get_pagination_params()
│ │ # - AsyncSession = Depends(get_async_session)
│ │
│ └── v1/ # API v1 版本
│ ├── __init__.py # from .auth import router as auth_router 等,合并到 api_router
│ │
│ ├── auth.py # 认证模块 /api/v1/auth
│ │ # 对应需求: 8.1 认证与用户管理
│ │ # - POST /login 用户登录
│ │ # - POST /register 用户注册
│ │ # - POST /logout 用户登出
│ │ # - GET /me 获取当前用户
│ │ # - PUT /me 更新个人信息
│ │ # - POST /change-password 修改密码
│ │
│ ├── users.py # 用户管理模块 /api/v1/users
│ │ # 对应需求: 8.1 用户管理
│ │ # - GET / 获取用户列表 (admin)
│ │ # - GET /{user_id} 获取用户详情
│ │ # - PUT /{user_id} 更新用户
│ │ # - DELETE /{user_id} 删除用户
│ │ # - GET /{user_id}/stats 用户工作量统计
│ │
│ ├── projects.py # 项目管理模块 /api/v1/projects
│ │ # 对应需求: 8.2 项目管理
│ │ # - GET / 获取项目列表
│ │ # - POST / 创建项目
│ │ # - GET /{project_id} 获取项目详情
│ │ # - PUT /{project_id} 更新项目
│ │ # - DELETE /{project_id} 删除项目
│ │ # - GET /{project_id}/members 获取项目成员
│ │ # - POST /{project_id}/members 添加项目成员
│ │ # - DELETE /{project_id}/members/{user_id} 移除成员
│ │ # - GET /{project_id}/labels 获取标签集
│ │ # - PUT /{project_id}/labels 更新标签集
│ │ # - GET /{project_id}/tasks 获取任务列表
│ │ # - GET /{project_id}/statistics 获取项目统计
│ │
│ ├── tasks.py # 任务管理模块 /api/v1/tasks
│ │ # 对应需求: 8.3 任务管理
│ │ # - GET / 获取任务列表
│ │ # - POST / 创建任务
│ │ # - GET /{task_id} 获取任务详情
│ │ # - PUT /{task_id} 更新任务
│ │ # - DELETE /{task_id} 删除任务
│ │ # - POST /{task_id}/submit 提交审核
│ │ # - POST /{task_id}/approve 审核通过
│ │ # - POST /{task_id}/reject 审核驳回
│ │ # - POST /{task_id}/pause 暂停任务
│ │ # - POST /{task_id}/resume 恢复任务
│ │ # - GET /{task_id}/progress 获取进度
│ │ # - GET /{task_id}/data-items 获取数据项
│ │ # - POST /{task_id}/data-items 批量添加数据项
│ │ # - GET /{task_id}/export 导出数据集
│ │
│ ├── data_items.py # 数据管理模块 /api/v1/data-items
│ │ # 对应需求: 8.4 数据管理
│ │ # - GET /{data_item_id} 获取数据项详情
│ │ # - PUT /{data_item_id} 更新数据项
│ │ # - DELETE /{data_item_id} 删除数据项
│ │ # - GET /{data_item_id}/annotations 获取标注列表
│ │ # - POST /{data_item_id}/annotations 添加标注
│ │ # - PUT /{data_item_id}/annotations/{ann_id} 更新标注
│ │ # - DELETE /{data_item_id}/annotations/{ann_id} 删除标注
│ │ # - POST /{data_item_id}/annotations/batch 批量添加
│ │ # - GET /{data_item_id}/signed-url 获取预览签名URL
│ │
│ ├── annotations.py # 标注 CRUD 模块 /api/v1/annotations
│ │ # 对应需求: 8.5 标注功能
│ │ # - POST /image 创建图像标注
│ │ # - PUT /{annotation_id} 更新标注
│ │ # - DELETE /{annotation_id} 删除标注
│ │ # - POST /audio 创建音频标注
│ │ # - PUT /audio/{annotation_id} 更新音频标注
│ │ # - DELETE /audio/{annotation_id} 删除音频标注
│ │ # - POST /text/entity 创建文本实体
│ │ # - PUT /text/entity/{entity_id} 更新文本实体
│ │ # - DELETE /text/entity/{entity_id} 删除文本实体
│ │ # - POST /text/relation 创建文本关系
│ │ # - DELETE /text/relation/{relation_id} 删除文本关系
│ │ # - POST /batch 批量保存标注
│ │
│ ├── reviews.py # 审核管理模块 /api/v1/reviews
│ │ # 对应需求: 8.6 审核管理
│ │ # - GET /sessions 获取审核会话列表
│ │ # - POST /sessions 创建审核会话
│ │ # - GET /sessions/{session_id} 获取审核会话详情
│ │ # - POST /sessions/{session_id}/approve 通过审核
│ │ # - POST /sessions/{session_id}/reject 驳回审核
│ │ # - POST /sessions/{session_id}/skip 跳过审核
│ │ # - GET /sessions/{session_id}/comments 获取审核意见
│ │ # - POST /sessions/{session_id}/comments 添加审核意见
│ │ # - POST /sessions/{session_id}/comments/{comment_id}/resolve
│ │ # - POST /batch 批量审核
│ │
│ ├── ai_models.py # AI 模型管理模块 /api/v1/ai-models
│ │ # 对应需求: 6.x AI 模型服务
│ │ # - GET / 获取模型列表
│ │ # - POST / 添加模型配置
│ │ # - GET /{model_id} 获取模型详情
│ │ # - PUT /{model_id} 更新模型配置
│ │ # - DELETE /{model_id} 删除模型配置
│ │ # - POST /{model_id}/test 测试模型推理
│ │
│ ├── autolabel.py # 自动标注模块 /api/v1/autolabel
│ │ # 对应需求: 6.4 自动标注任务流程
│ │ # - POST / 启动自动标注任务
│ │ # - GET /{auto_task_id} 获取任务状态
│ │ # - GET /{auto_task_id}/progress 获取进度
│ │ # - POST /{auto_task_id}/cancel 取消任务
│ │ # - GET /{auto_task_id}/results 获取结果
│ │ # - POST /{auto_task_id}/apply 应用结果
│ │ # - GET /history 获取历史记录
│ │
│ ├── export.py # 数据导出模块 /api/v1/export
│ │ # 对应需求: 8.7 数据导出
│ │ # 支持格式: COCO/VOC/YOLO/SRT/VTT/CoNLL/BIO/JSON/CSV
│ │ # - POST / 创建导出任务
│ │ # - GET /{export_id} 获取导出状态
│ │ # - GET /{export_id}/download 下载导出文件
│ │ # - GET /{export_id}/preview 预览导出数据
│ │
│ ├── statistics.py # 统计模块 /api/v1/statistics
│ │ # 对应需求: 5.3.11 统计模块
│ │ # - GET /dashboard 工作台统计
│ │ # - GET /tasks 任务统计
│ │ # - GET /users/{user_id}/workload 用户工作量
│ │ # - GET /projects/{project_id}/progress 项目进度
│ │ # - GET /weekly 周报数据
│ │
│ ├── upload.py # 文件上传模块 /api/v1/upload
│ │ # 对应需求: 7.x 文件存储方案
│ │ # - POST / 后端直传 (小文件)
│ │ # - POST /presigned-url 获取预签名URL (大文件)
│ │ # - POST /multipart/init 初始化分片上传
│ │ # - POST /multipart/{upload_id}/complete 完成分片上传
│ │
│ └── websocket.py # WebSocket 模块 (可选) /ws
│ # 对应需求: 5.4 WebSocket 接口
│ # - WS /ws/annotations/{task_id}
│
├── core/ # ==========================================
│ │ # 核心基础设施层:配置/安全/数据库/缓存/存储/日志
│ │ # 命名规范:{module_name}.py,私有函数以 _ 开头
│ │ # ==========================================
│ ├── __init__.py # 导出核心组件
│ │
│ ├── config.py # 应用配置 (pydantic-settings)
│ │ # 对应需求: 3.x 环境依赖
│ │ # - 数据库配置 (DATABASE_URL, ASYNC_DATABASE_URL)
│ │ # - Redis 配置 (REDIS_HOST, REDIS_URL)
│ │ # - MinIO 配置 (MINIO_ENDPOINT, MINIO_ACCESS_KEY)
│ │ # - JWT 配置 (JWT_SECRET_KEY, JWT_ALGORITHM)
│ │ # - 文件上传配置 (MAX_*_SIZE_MB, ALLOWED_*_TYPES)
│ │ # - AI 模型配置 (AI_MODEL_DEVICE, AI_MODEL_CACHE_DIR)
│ │
│ ├── database.py # 数据库连接与会话管理
│ │ # - sync_engine / async_engine
│ │ # - SyncSessionLocal / AsyncSessionLocal
│ │ # - get_async_session() — FastAPI 依赖注入
│ │ # - get_sync_session() — CLI/脚本使用
│ │ # - get_db_context() — 上下文管理器
│ │ # - Base — 所有 ORM 模型的基类
│ │ # - init_db() / close_db()
│ │
│ ├── redis.py # Redis 连接与缓存服务
│ │ # - get_redis_client() 同步客户端
│ │ # - get_async_redis() 异步客户端 (单例)
│ │ # - CacheService 缓存操作类
│ │ # - close_async_redis()
│ │
│ ├── security.py # JWT 认证与密码加密
│ │ # 对应需求: 9.x 安全与权限
│ │ # - hash_password() / verify_password() (bcrypt)
│ │ # - create_access_token() / create_refresh_token()
│ │ # - decode_token()
│ │
│ ├── storage.py # MinIO 对象存储客户端封装
│ │ # 对应需求: 7.x 文件存储方案
│ │ # - StorageService
│ │ # - upload_file() / upload_multipart()
│ │ # - get_presigned_url() / get_presigned_put_object()
│ │ # - delete_file() / list_files()
│ │ # - ensure_bucket_exists()
│ │
│ ├── logging.py # 日志系统配置 (loguru)
│ │ # - setup_logging()
│ │ # - get_logger(name)
│ │
│ ├── middleware.py # 自定义中间件
│ │ # - RequestLogMiddleware 请求日志中间件
│ │ # - RateLimitMiddleware 限流中间件
│ │
│ └── exceptions.py # 自定义异常类与异常处理器
│ # - PLabelException (基类)
│ # - NotFoundError / AlreadyExistsError / PermissionDeniedError
│ # - FileTooLargeError / InvalidFileTypeError
│ # - register_exception_handlers(app)
│
├── models/ # ==========================================
│ │ # SQLAlchemy ORM 模型层 (对应需求: 4.x 数据库设计)
│ │ # 命名规范: {table_name_singular}.py (蛇底命名)
│ │ # ==========================================
│ ├── __init__.py # 导出所有 Model 类,Base 模型基类
│ │
│ ├── base.py # 公共模型基类 (可选,统一 created_at 等字段)
│ │ # - TimestampMixin created_at / updated_at
│ │ # - UUIDPrimaryKey id(UUID) / 外键关系
│ │
│ ├── user.py # 用户模型 users 表
│ │ # 对应需求: 4.2.1 用户表
│ │ # id, username, email, password_hash, avatar_url
│ │ # role (admin/user/annotator/reviewer)
│ │ # is_active, created_at, updated_at
│ │
│ ├── project.py # 项目模型 projects 表
│ │ # 对应需求: 4.2.2 项目表
│ │ # id, name, description, status, owner_id
│ │ # label_set_id, created_at, updated_at
│ │
│ ├── label_set.py # 标签集模型 label_sets 表
│ │ # 对应需求: 4.2.3 标签集表
│ │ # id, project_id, name, created_at, updated_at
│ │
│ ├── label.py # 标签模型 labels 表
│ │ # 对应需求: 4.2.4 标签表
│ │ # id, label_set_id, name, color, type
│ │ # shortcut, parent_id, attributes (JSONB)
│ │ # annotation_types: rectangle/polygon/brush/keypoint/skeleton/text/classification/relation
│ │
│ ├── task.py # 任务模型 tasks 表
│ │ # 对应需求: 4.2.5 任务表
│ │ # id, project_id, name, description, data_type
│ │ # annotation_types (JSONB), status
│ │ # assignee_id, reviewer_id, ai_model_id
│ │ # progress, total_count, completed_count
│ │ # reviewed_count, rejected_count
│ │ # status: pending/in_progress/submitted/rejected/reviewed/exported/paused
│ │
│ ├── data_item.py # 数据项模型 data_items 表
│ │ # 对应需求: 4.2.6 数据项表
│ │ # id, task_id, name, type, file_path
│ │ # thumbnail_path, size, mime_type
│ │ # width, height, duration, pages
│ │ # metadata (JSONB), annotation_status
│ │
│ ├── annotation.py # 标注模型 annotations 表 (图像/视频)
│ │ # 对应需求: 4.2.7 标注表
│ │ # id, data_item_id, user_id, label_id
│ │ # annotation_type, label_name, data (JSONB)
│ │ # visible, occluded, ignored, frame_index
│ │
│ ├── audio_annotation.py # 音频标注模型 audio_annotations 表
│ │ # 对应需求: 4.2.7 音频标注
│ │ # id, data_item_id, user_id
│ │ # start_time, end_time, text, speaker
│ │ # labels (JSONB), confidence
│ │
│ ├── text_entity.py # 文本实体模型 text_entities 表
│ │ # 对应需求: 4.2.7 文本标注实体
│ │ # id, data_item_id, user_id, label_id
│ │ # label_name, start_offset, end_offset
│ │ # text, color, attributes (JSONB)
│ │
│ ├── text_relation.py # 文本关系模型 text_relations 表
│ │ # 对应需求: 4.2.7 文本关系标注
│ │ # id, data_item_id, user_id
│ │ # from_entity_id, to_entity_id
│ │ # label, relation_type
│ │
│ ├── review_session.py # 审核会话模型 review_sessions / review_comments 表
│ │ # 对应需求: 4.2.8 审核表
│ │ # ReviewSession: id, task_id, data_item_id
│ │ # reviewer_id, annotator_id, status
│ │ # ReviewComment: id, session_id, reviewer_id
│ │ # annotation_id, content, resolved
│ │
│ ├── ai_model.py # AI 模型配置模型 ai_models 表
│ │ # 对应需求: 4.2.9 AI 模型表
│ │ # id, name, type, description, framework
│ │ # model_path, config (JSONB), accuracy, speed
│ │ # enabled, created_at, updated_at
│ │ # type: object_detection/segmentation/keypoint/classification/asr/ner/ocr
│ │
│ ├── auto_label_task.py # 自动标注任务模型 auto_label_tasks 表
│ │ # 对应需求: 4.2.10 自动标注任务表
│ │ # id, task_id, user_id, model_id, status
│ │ # progress, config (JSONB), result (JSONB)
│ │ # error, data_item_ids (JSONB)
│ │ # started_at, completed_at, created_at
│ │ # status: pending/running/completed/failed/cancelled
│ │
│ └── project_member.py # 项目成员模型 project_members 表
│ # 对应需求: 4.2.11 项目成员表
│ # id, project_id, user_id, role, joined_at
│ # role: owner/manager/annotator/reviewer
│
├── schemas/ # ==========================================
│ │ # Pydantic 数据校验模型 (对应 API 请求/响应)
│ │ # 命名: {Resource}Schema, {Resource}Create, {Resource}Update, {Resource}Response
│ │ # ==========================================
│ ├── __init__.py # 导出所有 Schema 类
│ │
│ ├── base.py # 公共 Schema 基类与混入
│ │ # - BaseSchema 基础 Schema (from_attributes=True)
│ │ # - PaginationSchema 分页响应基类 (items, total, page, page_size, total_pages)
│ │ # - ResponseSchema 统一响应包装 {code, message, data}
│ │ # - ErrorResponse 统一错误响应 {code, message, errors}
│ │
│ ├── auth.py # 认证相关 Schema
│ │ # LoginRequest, LoginResponse
│ │ # RegisterRequest, UserResponse
│ │ # TokenPayload
│ │
│ ├── user.py # 用户相关 Schema
│ │ # UserSchema, UserCreate, UserUpdate, UserResponse
│ │ # UserInDB (含 password_hash, 仅内部使用)
│ │ # UserStatsResponse
│ │
│ ├── project.py # 项目相关 Schema
│ │ # ProjectSchema, ProjectCreate, ProjectUpdate
│ │ # ProjectMemberSchema, ProjectMemberAdd
│ │ # ProjectStatistics
│ │
│ ├── label.py # 标签相关 Schema
│ │ # LabelSetSchema, LabelSetUpdate
│ │ # LabelSchema, LabelCreate, LabelUpdate
│ │
│ ├── task.py # 任务相关 Schema
│ │ # TaskSchema, TaskCreate, TaskUpdate
│ │ # TaskProgressResponse
│ │ # TaskStatusEnum
│ │
│ ├── data_item.py # 数据项相关 Schema
│ │ # DataItemSchema, DataItemUpdate
│ │ # DataItemMetadata
│ │ # AnnotationStatusEnum
│ │
│ ├── annotation.py # 标注相关 Schema (含多种标注类型)
│ │ # AnnotationSchema, AnnotationCreate
│ │ # AnnotationTypeEnum: rectangle/polygon/brush/keypoint/skeleton/text/classification/relation
│ │ # BoundingBoxData, PolygonData, BrushData, KeypointData, SkeletonData
│ │ # AudioAnnotationSchema, AudioAnnotationCreate
│ │ # TextEntitySchema, TextEntityCreate
│ │ # TextRelationSchema, TextRelationCreate
│ │ # BatchAnnotationRequest
│ │
│ ├── review.py # 审核相关 Schema
│ │ # ReviewSessionSchema, ReviewSessionCreate
│ │ # ReviewAction (approve/reject/skip)
│ │ # ReviewCommentSchema, ReviewCommentCreate
│ │ # BatchReviewRequest
│ │
│ ├── ai_model.py # AI 模型相关 Schema
│ │ # AIModelSchema, AIModelCreate, AIModelUpdate
│ │ # AIModelTypeEnum
│ │ # AIModelTestRequest, AIModelTestResponse
│ │
│ ├── autolabel.py # 自动标注相关 Schema
│ │ # AutoLabelTaskCreate, AutoLabelTaskResponse
│ │ # AutoLabelProgressResponse
│ │ # AutoLabelStatusEnum
│ │
│ ├── export.py # 数据导出相关 Schema
│ │ # ExportTaskCreate, ExportTaskResponse
│ │ # ExportFormatEnum: coco_json/voc_xml/yolo_txt/srt/vtt/conll/bio/json/csv
│ │ # ExportStatusEnum
│ │
│ ├── statistics.py # 统计相关 Schema
│ │ # DashboardStats
│ │ # TaskStatistics
│ │ # UserWorkloadStats
│ │ # ProjectProgressStats
│ │ # WeeklyReportStats
│ │
│ └── upload.py # 文件上传相关 Schema
│ # UploadResponse, PresignedUrlRequest
│ # PresignedUrlResponse
│ # MultipartUploadInit, MultipartUploadComplete
│
├── services/ # ==========================================
│ │ # 业务逻辑层:处理复杂业务规则、事务协调
│ │ # 命名: {resource}_service.py (蛇底命名)
│ │ # 原则: 一个 Service 处理一个领域对象的完整业务逻辑
│ │ # ==========================================
│ ├── __init__.py # 导出所有 Service 类
│ │
│ ├── auth_service.py # 认证服务
│ │ # - authenticate_user(email, password)
│ │ # - register_user(username, email, password)
│ │ # - change_password(user_id, old_password, new_password)
│ │
│ ├── user_service.py # 用户服务
│ │ # - get_user_by_id()
│ │ # - get_users(page, page_size, filters)
│ │ # - update_user()
│ │ # - delete_user()
│ │ # - get_user_stats()
│ │
│ ├── project_service.py # 项目服务
│ │ # - create_project(owner_id, data)
│ │ # - get_projects(user_id, filters)
│ │ # - update_project()
│ │ # - delete_project()
│ │ # - add_member() / remove_member()
│ │ # - get_project_stats()
│ │
│ ├── label_service.py # 标签服务
│ │ # - create_label_set(project_id, name)
│ │ # - update_labels(project_id, labels)
│ │ # - get_labels_by_project()
│ │
│ ├── task_service.py # 任务服务
│ │ # - create_task(project_id, data)
│ │ # - get_tasks(filters)
│ │ # - update_task()
│ │ # - delete_task()
│ │ # - submit_task() / approve_task() / reject_task()
│ │ # - pause_task() / resume_task()
│ │ # - calculate_progress()
│ │
│ ├── data_item_service.py # 数据项服务
│ │ # - add_data_items(task_id, files)
│ │ # - add_data_items_by_urls()
│ │ # - add_data_items_by_paths()
│ │ # - get_data_items(task_id, filters)
│ │ # - update_data_item()
│ │ # - delete_data_item()
│ │ # - extract_metadata()
│ │
│ ├── annotation_service.py # 标注服务 (核心业务逻辑)
│ │ # - create_annotation()
│ │ # - update_annotation()
│ │ # - delete_annotation()
│ │ # - batch_save_annotations()
│ │ # - get_annotations_by_data_item()
│ │ # - convert_to_export_format()
│ │
│ ├── review_service.py # 审核服务
│ │ # - create_review_session()
│ │ # - approve_session()
│ │ # - reject_session()
│ │ # - add_comment()
│ │ # - resolve_comment()
│ │ # - batch_review()
│ │
│ ├── ai_model_service.py # AI 模型服务
│ │ # - get_models(filters)
│ │ # - create_model()
│ │ # - update_model()
│ │ # - test_model()
│ │ # - load_model() — 加载模型到内存
│ │ # - unload_model() — 卸载模型
│ │
│ ├── autolabel_service.py # 自动标注服务
│ │ # - create_auto_label_task()
│ │ # - get_auto_task_status()
│ │ # - cancel_auto_task()
│ │ # - apply_auto_results()
│ │ # - get_auto_task_history()
│ │
│ ├── export_service.py # 数据导出服务
│ │ # - create_export_task()
│ │ # - get_export_status()
│ │ # - export_coco_json() — COCO 格式导出
│ │ # - export_voc_xml() — VOC XML 导出
│ │ # - export_yolo_txt() — YOLO TXT 导出
│ │ # - export_srt() — SRT 字幕导出
│ │ # - export_vtt() — VTT 字幕导出
│ │ # - export_conll() — CoNLL NER 导出
│ │ # - export_bio() — BIO 序列标注导出
│ │ # - export_json() — 通用 JSON 导出
│ │ # - export_csv() — CSV 导出
│ │
│ ├── storage_service.py # 文件存储服务 (封装 StorageService)
│ │ # - upload_file()
│ │ # - upload_multipart()
│ │ # - get_signed_url()
│ │ # - get_presigned_put_url()
│ │ # - delete_file()
│ │ # - generate_thumbnail()
│ │
│ └── statistics_service.py # 统计服务
│ # - get_dashboard_stats()
│ # - get_task_statistics()
│ # - get_user_workload()
│ # - get_project_progress()
│ # - get_weekly_report()
│
├── tasks/ # ==========================================
│ │ # Celery 异步任务 (对应需求: 6.x AI 模型服务, 10.1 部署架构)
│ │ # 命名: {module}_tasks.py
│ │ # ==========================================
│ ├── __init__.py # celery_app 实例导出
│ │
│ ├── celery_app.py # Celery 应用配置
│ │ # - broker_url / result_backend
│ │ # - task_serializer / result_serializer
│ │ # - task_routes (按队列分发: gpu_tasks / cpu_tasks)
│ │ # - beat_schedule (定时任务)
│ │
│ ├── ai_tasks.py # AI 推理任务 (GPU/CPU 队列)
│ │ # 对应需求: 6.4 自动标注任务流程
│ │ # - run_auto_label_task(auto_task_id)
│ │ # - infer_yolo(model_id, data_item_id)
│ │ # - infer_sam(model_id, data_item_id)
│ │ # - infer_pose(model_id, data_item_id)
│ │ # - infer_whisper(model_id, data_item_id)
│ │ # - infer_ner(model_id, data_item_id)
│ │ # - update_task_progress(auto_task_id, progress)
│ │
│ ├── export_tasks.py # 导出任务 (CPU 队列)
│ │ # 对应需求: 8.7 数据导出
│ │ # - run_export_task(export_task_id)
│ │ # - generate_export_file()
│ │
│ ├── file_tasks.py # 文件处理任务 (CPU 队列)
│ │ # 对应需求: 7.x 文件存储方案
│ │ # - generate_thumbnail(data_item_id)
│ │ # - extract_file_metadata(data_item_id)
│ │ # - process_video_frames(data_item_id)
│ │ # - transcode_video(data_item_id, format)
│ │
│ └── cleanup_tasks.py # 清理定时任务
│ # - cleanup_expired_files() 清理过期文件
│ # - cleanup_old_export_files() 清理导出文件
│ # - cleanup_failed_tasks() 清理失败任务记录
│
├── utils/ # ==========================================
│ │ # 工具函数与辅助模块
│ │ # 命名: {category}_{functionality}.py
│ │ # ==========================================
│ ├── __init__.py
│ │
│ ├── helpers.py # 通用辅助函数
│ │ # - generate_uuid()
│ │ # - get_file_extension()
│ │ # - get_file_mime_type()
│ │ # - sanitize_filename()
│ │ # - format_file_size()
│ │ # - paginate_query()
│ │
│ ├── response.py # 统一响应工具
│ │ # - success_response(data, message)
│ │ # - error_response(code, message, errors)
│ │ # - paginated_response(items, total, page, page_size)
│ │
│ ├── validators.py # 自定义验证器
│ │ # - validate_file_type()
│ │ # - validate_file_size()
│ │ # - validate_image_dimensions()
│ │
│ ├── cryptography.py # 加密工具
│ │ # - encrypt_data() / decrypt_data()
│ │
│ ├── file_utils.py # 文件操作工具
│ │ # - ensure_dir_exists()
│ │ # - copy_file() / move_file() / delete_file()
│ │ # - read_file() / write_file()
│ │
│ ├── datetime_utils.py # 日期时间工具
│ │ # - utc_now()
│ │ # - format_datetime()
│ │ # - parse_datetime()
│ │
│ └── create_superuser.py # 创建超级用户脚本 (CLI 工具)
│ # python -m app.utils.create_superuser
│
```
---
## 3. 其他根目录文件详解
```
backend/
│
├── alembic/ # 数据库迁移管理
│ ├── alembic.ini # Alembic 配置文件
│ ├── env.py # 迁移环境配置 (加载 settings, 设置 SQLAlchemy engine)
│ ├── script.py.mako # 迁移脚本模板
│ └── versions/ # 迁移版本文件 (按时间戳命名)
│ ├── 2024_01_01_0001_initial_migration.py
│ ├── 2024_01_15_0002_add_ai_models.py
│ └── ...
│
├── scripts/ # 运维与初始化脚本
│ ├── init_db.py # 初始化数据库 (创建表/索引)
│ ├── seed_data.py # 种子数据 (创建默认用户/角色)
│ ├── create_minio_buckets.py # 创建 MinIO 存储桶
│ ├── download_sample_models.py # 下载示例 AI 模型
│ ├── backup_db.py # 数据库备份脚本
│ └── restore_db.py # 数据库恢复脚本
│
├── tests/ # ==========================================
│ │ # 测试代码 (对应需求: Phase 7 测试与优化)
│ │ # ==========================================
│ ├── __init__.py
│ ├── conftest.py # Pytest fixtures 与测试配置
│ │ # - async_client (FastAPI TestClient)
│ │ # - db_session
│ │ # - test_user / test_admin
│ │
│ ├── api/ # API 集成测试
│ │ ├── __init__.py
│ │ ├── test_auth.py # 认证 API 测试
│ │ ├── test_users.py # 用户 API 测试
│ │ ├── test_projects.py # 项目 API 测试
│ │ ├── test_tasks.py # 任务 API 测试
│ │ ├── test_annotations.py # 标注 API 测试
│ │ └── test_export.py # 导出 API 测试
│ │
│ ├── services/ # Service 层单元测试
│ │ ├── __init__.py
│ │ ├── test_auth_service.py
│ │ ├── test_project_service.py
│ │ ├── test_task_service.py
│ │ └── test_annotation_service.py
│ │
│ ├── models/ # Model 层单元测试
│ │ ├── __init__.py
│ │ └── test_models.py
│ │
│ └── fixtures/ # 测试数据 fixtures
│ ├── __init__.py
│ ├── sample_users.py
│ ├── sample_projects.py
│ └── sample_annotations.py
│
├── configs/ # 各类配置文件
│ ├── nginx/
│ │ ├── nginx.conf # Nginx 主配置
│ │ ├── ssl/ # SSL 证书目录
│ │ └── conf.d/
│ │ ├── api.conf # API 服务配置
│ │ └── static.conf # 静态资源服务配置
│ │
│ └── docker/
│ ├── Dockerfile.prod # 生产环境镜像
│ ├── Dockerfile.gpu # GPU 镜像
│ └── entrypoint.sh # 容器启动脚本
│
├── models/ # AI 模型文件目录 (不纳入 Git)
│ ├── .gitkeep # 保持目录结构
│ ├── vision/ # 视觉模型
│ │ ├── yolo/ # YOLOv8 系列
│ │ │ ├── yolov8n.pt
│ │ │ └── yolov8s.pt
│ │ ├── sam/ # SAM 模型
│ │ └── pose/ # 姿态估计模型
│ ├── audio/ # 音频模型
│ │ └── whisper/ # Whisper 模型
│ │ ├── base.pt
│ │ └── medium.pt
│ └── text/ # 文本模型
│ └── ner/ # NER 模型
│ └── qwen-ner/
│
├── data/ # 数据文件目录 (不纳入 Git)
│ ├── .gitkeep
│ ├── uploads/ # 用户上传临时文件
│ ├── thumbnails/ # 缩略图
│ └── exports/ # 导出的数据集
│
├── logs/ # 日志文件目录
│ └── .gitkeep
│
├── docs/ # 项目开发文档
│ ├── 开发规范.md
│ ├── API接口约定.md
│ ├── 数据库设计说明.md
│ ├── AI模型接入指南.md
│ └── 部署运维手册.md
│
├── Dockerfile # 开发环境镜像 (包含所有依赖)
├── Dockerfile.gpu # GPU 推理镜像 (包含 CUDA/AI 依赖)
├── docker-compose.yml # 开发环境 (backend + postgres + redis + minio)
├── docker-compose.prod.yml # 生产环境 (多副本 backend + nginx + 全量服务)
├── docker-compose.model.yml # AI 模型推理服务 (Celery workers + GPU)
├── .env.example # 环境变量示例 (已存在)
├── .env # 本地环境变量 (不纳入 Git, 由 .env.example 复制)
├── requirements.txt # Python 依赖 (已存在)
├── requirements-ai.txt # AI 模块可选依赖
├── pytest.ini # Pytest 配置
├── .gitignore # Git 忽略配置
├── Makefile # Make 快捷命令
│ # make install / make db-migrate / make db-seed
│ # make test / make test-cov
│ # make run / make docker-up
│ # make docker-down
└── README.md # 项目说明文档 (已存在)
```
---
## 4. 目录结构与需求的映射关系
| 需求章节 | 对应目录/文件 | 说明 |
|---------|-------------|------|
| 2.x 技术栈选型 | `core/`, `requirements.txt`, `docker-compose.yml` | FastAPI/SQLAlchemy/Celery/MinIO/Redis |
| 3.x 环境依赖 | `.env.example`, `Dockerfile`, `Dockerfile.gpu` | Python依赖/系统依赖/Docker |
| 4.x 数据库设计 | `models/`, `alembic/` | ORM模型/数据库迁移 |
| 5.x API 接口规范 | `api/v1/` | RESTful API路由 |
| 6.x AI 模型服务 | `tasks/`, `services/ai_model_service.py`, `models/` | Celery任务队列/模型管理 |
| 7.x 文件存储方案 | `core/storage.py`, `services/storage_service.py`, `data/` | MinIO对象存储 |
| 8.1 认证与用户管理 | `api/v1/auth.py`, `api/v1/users.py`, `core/security.py` | JWT认证/用户CRUD |
| 8.2 项目管理 | `api/v1/projects.py`, `services/project_service.py` | 项目CRUD/成员管理 |
| 8.3 任务管理 | `api/v1/tasks.py`, `services/task_service.py` | 任务CRUD/状态流转 |
| 8.4 数据管理 | `api/v1/data_items.py`, `services/data_item_service.py` | 数据项上传/元数据提取 |
| 8.5 标注功能 | `api/v1/annotations.py`, `services/annotation_service.py` | 图像/音频/文本标注 |
| 8.6 审核管理 | `api/v1/reviews.py`, `services/review_service.py` | 审核流程/意见管理 |
| 8.7 数据导出 | `api/v1/export.py`, `services/export_service.py` | 多格式数据导出 |
| 9.x 安全与权限 | `api/deps.py`, `core/security.py`, `core/exceptions.py` | JWT/角色权限/文件安全 |
| 10.x 部署架构 | `configs/`, `docker-compose.*.yml`, `Makefile` | Docker部署/NGINX/多副本 |
| 11.x 开发里程碑 | `tests/`, `docs/` | 测试覆盖/开发文档 |
---
## 5. 命名规范汇总
| 类型 | 规范 | 示例 |
|------|------|------|
| 目录名 | 蛇底命名 (snake_case) | `api/v1/`, `core/`, `services/` |
| Python 文件 | 蛇底命名 | `auth_service.py`, `user_model.py` |
| Python 类 | 帕斯卡命名 (PascalCase) | `UserService`, `TaskSchema` |
| 变量/函数 | 蛇底命名 | `get_user_by_id`, `async_session` |
| 常量 | 全大写蛇底 | `MAX_IMAGE_SIZE`, `JWT_SECRET_KEY` |
| API 路由前缀 | 蛇底命名 | `/api/v1/auth`, `/api/v1/projects` |
| 数据库表名 | 蛇底命名 (复数) | `users`, `projects`, `data_items` |
| Schema 字段 | 蛇底命名 | `user_id`, `project_id`, `page_size` |
| Celery 任务 | 蛇底命名 | `run_auto_label_task`, `export_coco_json` |
| 测试文件 | `test_{module}.py` | `test_auth.py`, `test_project_service.py` |
---
## 6. 模块依赖关系图
```
请求入口 (Client)
│
▼
api/v1/*.py (路由层: 接收请求, 参数校验, 调用 Service)
│
▼
services/*.py (业务逻辑层: 复杂业务规则, 事务协调)
│
├──────────────────┐
▼ ▼
models/*.py tasks/*.py (模型层: 数据持久化 | 异步任务: AI 推理/导出)
│ │
└──────────────────┘
│
▼
core/database.py core/redis.py core/storage.py (基础设施层: DB/缓存/文件存储)
│
▼
core/config.py core/security.py (配置层: 配置管理/安全认证)
│
▼
外部依赖: PostgreSQL / Redis / MinIO / Celery Worker
```
---
## 7. 开发阶段文件创建优先级
| 阶段 | 需要创建的文件 | 说明 |
|------|--------------|------|
| **Phase 0** | `core/`, `alembic/`, `models/`, `schemas/`, `docker-compose.yml` | 基础架构搭建 |
| **Phase 1** | `api/v1/auth.py`, `api/v1/users.py`, `services/auth_service.py`, `services/user_service.py` | 认证与用户 |
| **Phase 2** | `api/v1/projects.py`, `api/v1/tasks.py`, `api/v1/data_items.py`, 对应 Service | 项目/任务/数据 |
| **Phase 3** | `api/v1/annotations.py`, `api/v1/reviews.py`, 对应 Service | 标注与审核 |
| **Phase 4** | `tasks/`, `services/ai_model_service.py`, `services/autolabel_service.py` | AI 集成 |
| **Phase 5** | `api/v1/export.py`, `services/export_service.py`, `tasks/export_tasks.py` | 数据导出 |
| **Phase 6** | `api/v1/statistics.py`, `services/statistics_service.py`, `api/websocket.py` | 统计与实时 |
| **Phase 7** | `tests/`, `docs/`, `Makefile`, `configs/` | 测试与文档 |
---
## 8. Git 忽略规则 (`.gitignore`)
```gitignore
# Python
__pycache__/
*.py[cod]
*.so
.Python
venv/
.venv/
.env
.env.local
# Database
*.db
*.sqlite
# Logs & Data
logs/
data/uploads/
data/thumbnails/
data/exports/
*.log
# AI Models (大文件, 按需下载)
models/vision/
models/audio/
models/text/
# IDE
.idea/
.vscode/
*.swp
*.swo
# Testing
.pytest_cache/
.coverage
htmlcov/
*.cover
# Docker
.docker/
# OS
.DS_Store
Thumbs.db
# Secrets (绝不提交)
*.pem
*.key
credentials.json
```
---
*文档版本: v1.0*
*创建日期: 2026年5月28日*
*更新记录:*
- v1.0 (2026-05-28): 初始版本
# PLabel 自动标注平台 - 项目落地方案
> 文档版本:v1.0
> 创建日期:2026年5月28日
> 适用范围:PLabel 自动标注平台前后端完整实施
---
## 目录
1. [项目概述](#1-项目概述)
2. [系统架构](#2-系统架构)
3. [技术栈选型](#3-技术栈选型)
4. [服务配置清单](#4-服务配置清单)
5. [前端部署方案](#5-前端部署方案)
6. [后端部署方案](#6-后端部署方案)
7. [数据库配置](#7-数据库配置)
8. [存储服务配置](#8-存储服务配置)
9. [AI 模型服务](#9-ai-模型服务)
10. [Docker 容器编排](#10-docker-容器编排)
11. [前后端联调](#11-前后端联调)
12. [部署检查清单](#12-部署检查清单)
13. [运维指南](#13-运维指南)
---
## 1. 项目概述
### 1.1 项目背景
PLabel 是一款专业的 AI 训练数据标注平台,支持图像、视频、音频、文本等多种数据类型的标注。项目采用前后端分离架构:
- **前端**:Vue 3 + TypeScript + Vite,已完成基础功能开发
- **后端**:FastAPI + PostgreSQL + Redis + MinIO,待开发部署
### 1.2 部署目标
本方案旨在实现:
1. 前端静态应用在 `http://localhost:8008` 运行
2. 后端 API 服务在 `http://localhost:8899` 运行
3. PostgreSQL 数据库监听 `5433` 端口
4. MinIO 对象存储服务正常运作
5. 前后端实现无缝对接
### 1.3 项目结构
```
plabel/
├── frontend/ # Vue 3 前端项目
│ ├── src/
│ │ ├── api/ # API 接口层
│ │ ├── views/ # 页面组件
│ │ ├── components/ # 通用组件
│ │ ├── store/ # Pinia 状态管理
│ │ └── mock/ # Mock 数据
│ ├── package.json
│ └── vite.config.ts
├── backend/ # FastAPI 后端项目
│ ├── app/
│ │ ├── api/ # API 路由
│ │ ├── models/ # 数据模型
│ │ ├── services/ # 业务逻辑
│ │ └── core/ # 核心配置
│ ├── docker-compose.yml
│ └── Dockerfile
├── md/ # 文档目录
│ ├── 端口清单.md
│ ├── 后端需求清单.md
│ └── 项目落地方案.md
└── nginx/ # Nginx 配置(可选)
```
---
## 2. 系统架构
### 2.1 整体架构图
```
┌──────────────────────────────────────────────────────┐
│ 用户浏览器 │
│ (访问 http://localhost:8008) │
└──────────────────────────┬───────────────────────────┘
│
│ HTTP
▼
┌──────────────────────────────────────────────────────────────────────────────────┐
│ 本地开发环境 / 服务器 │
│ │
│ ┌────────────────────────────────────────────────────────────────────────┐ │
│ │ Nginx (可选,反向代理) │ │
│ │ 端口: 80 / 443 / 8008 │ │
│ └────────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ┌─────────────────────┼─────────────────────┐ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌───────────────┐ ┌───────────────┐ ┌───────────────┐ │
│ │ 前端 │ │ 后端 API │ │ MinIO │ │
│ │ (Vue 3) │ │ (FastAPI) │ │ Console │ │
│ │ :8008 │◀───▶│ :8899 │◀───▶│ :9010 │ │
│ └───────────────┘ └───────┬───────┘ └───────────────┘ │
│ │ │
│ ┌────────────────────┼────────────────────┐ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌───────────────┐ ┌───────────────┐ ┌───────────────┐ │
│ │ PostgreSQL │ │ Redis │ │ MinIO API │ │
│ │ :5433 │ │ :6379 │ │ :9009 │ │
│ └───────────────┘ └───────────────┘ └───────────────┘ │
│ │
└──────────────────────────────────────────────────────────────────────────────────┘
```
### 2.2 服务依赖关系
```
用户浏览器
│
▼
┌────────────┐
│ 前端 │ ◀─────── HTTP (API 请求)
│ :8008 │
└─────┬──────┘
│
│ HTTP (REST API)
▼
┌────────────┐
│ FastAPI │ ◀─────── PostgreSQL (:5433)
│ :8899 │ ◀─────── Redis (:6379)
└─────┬──────┘ ◀─────── MinIO (:9009)
│
│ 异步任务
▼
┌────────────┐
│ Celery │
│ Workers │
└────────────┘
```
---
## 3. 技术栈选型
### 3.1 前端技术栈
| 类别 | 技术 | 版本 | 说明 |
|------|------|------|------|
| 框架 | Vue 3 | ^3.4.21 | 渐进式 JavaScript 框架 |
| 构建工具 | Vite | ^5.1.6 | 下一代前端构建工具 |
| 语言 | TypeScript | ^5.4.2 | 类型安全的 JavaScript 超集 |
| 路由 | Vue Router | ^4.3.0 | Vue.js 官方路由管理器 |
| 状态管理 | Pinia | ^2.1.7 | Vue 状态管理库 |
| UI 组件 | Element Plus | ^2.6.1 | Vue 3 UI 组件库 |
| 图表 | ECharts | ^5.5.0 | 数据可视化图表库 |
### 3.2 后端技术栈
| 类别 | 技术 | 版本 | 说明 |
|------|------|------|------|
| 框架 | FastAPI | 0.110+ | 现代化 Python Web 框架 |
| 语言 | Python | 3.10+ | 后端编程语言 |
| ORM | SQLAlchemy | 2.0+ | 数据库 ORM |
| 数据库 | PostgreSQL | 15+ | 主数据库 |
| 缓存 | Redis | 7+ | 缓存和消息队列 |
| 对象存储 | MinIO | 最新版 | S3 兼容对象存储 |
| 任务队列 | Celery | 5.x | 异步任务队列 |
| AI 推理 | ONNX/Torch | 最新版 | 模型推理引擎 |
---
## 4. 服务配置清单
### 4.1 端口分配
| 服务名称 | 端口 | 协议 | 账号 | 密码 | 用途 |
|---------|------|------|------|------|------|
| PostgreSQL | 5433 | TCP | plabel | plabel | 主数据库 |
| Redis | 6379 | TCP | - | - | 缓存/消息队列 |
| MinIO API | 9009 | HTTP | minio | minio123 | 对象存储 API |
| MinIO Console | 9010 | HTTP | minio | minio123 | 存储管理界面 |
| FastAPI Backend | 8899 | HTTP | - | - | 后端 API 服务 |
| API Docs | 8899/docs | HTTP | - | - | Swagger 文档 |
| Flower | 5555 | HTTP | - | - | 任务监控 |
| 前端 Vue | 8008 | HTTP | - | - | 前端静态应用 |
### 4.2 访问地址速查
| 服务 | 开发环境地址 |
|------|------------|
| 前端应用 | http://localhost:8008 |
| 后端 API | http://localhost:8899 |
| API 文档 | http://localhost:8899/docs |
| MinIO Console | http://localhost:9010 |
| Flower 监控 | http://localhost:5555 |
### 4.3 数据库连接信息
```bash
# PostgreSQL 连接字符串
postgresql://plabel:plabel@localhost:5433/plabel
# 异步连接字符串
postgresql+asyncpg://plabel:plabel@localhost:5433/plabel
```
### 4.4 MinIO 连接信息
```bash
# API 端点
Endpoint: localhost:9009
# Console 端点
Console: localhost:9010
# 凭证
Access Key: minio
Secret Key: minio123
# 存储桶
Bucket: plabel-bucket
```
---
## 5. 前端部署方案
### 5.1 开发环境启动
```bash
# 进入前端目录
cd /home/admin2/plabel/frontend
# 安装依赖
npm install
# 启动开发服务器 (端口 8008)
npm run dev
```
### 5.2 前端配置修改
创建或修改 `frontend/src/config/api.ts` 文件:
```typescript
// src/config/api.ts
// API 配置
export const API_CONFIG = {
// 开发环境 API 地址
baseURL: 'http://localhost:8899',
// API 前缀
apiPrefix: '/api/v1',
// 超时时间 (毫秒)
timeout: 30000,
// 是否启用 Mock
useMock: false,
}
// 完整的 API 地址
export const API_BASE_URL = `${API_CONFIG.baseURL}${API_CONFIG.apiPrefix}`
```
### 5.3 修改 API 请求配置
修改 `frontend/vite.config.ts`,添加代理配置:
```typescript
// vite.config.ts
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import path from 'path'
export default defineConfig({
plugins: [vue()],
resolve: {
alias: {
'@': path.resolve(__dirname, 'src'),
},
},
server: {
port: 8008,
host: '0.0.0.0',
proxy: {
// API 请求代理到后端
'/api': {
target: 'http://localhost:8899',
changeOrigin: true,
// 如果需要重写路径
// rewrite: (path) => path.replace(/^\/api/, '')
},
// MinIO 文件代理
'/minio': {
target: 'http://localhost:9009',
changeOrigin: true,
},
},
},
})
```
### 5.4 生产环境构建
```bash
# 构建生产版本
npm run build
# 产物输出到 dist 目录
# 可通过 nginx 或任何静态服务器部署
```
### 5.5 前端目录结构说明
```
frontend/src/
├── api/
│ └── index.ts # API 接口定义 (需对接后端)
├── components/ # Vue 组件
│ ├── annotation/ # 标注相关组件
│ ├── layout/ # 布局组件
│ └── review/ # 审核相关组件
├── views/ # 页面视图
│ ├── annotation/ # 标注页面
│ ├── auth/ # 认证页面
│ ├── dashboard/ # 仪表盘
│ ├── project/ # 项目管理
│ ├── review/ # 审核页面
│ ├── task/ # 任务管理
│ └── data/ # 数据管理
├── store/ # Pinia 状态管理
├── mock/ # Mock 数据
├── router/ # 路由配置
├── types/ # TypeScript 类型定义
└── utils/ # 工具函数
```
---
## 6. 后端部署方案
### 6.1 项目初始化
```bash
# 创建后端项目目录
mkdir -p /home/admin2/plabel/backend
# 进入目录
cd /home/admin2/plabel/backend
# 创建虚拟环境
python3 -m venv venv
# 激活虚拟环境
source venv/bin/activate
# 创建 requirements.txt
cat > requirements.txt << 'EOF'
fastapi==0.110.0
uvicorn[standard]==0.27.1
sqlalchemy==2.0.27
alembic==1.13.1
asyncpg==0.29.0
psycopg2-binary==2.9.9
redis==5.0.1
python-jose[cryptography]==3.3.0
passlib[bcrypt]==1.7.4
python-multipart==0.0.9
pydantic==2.6.1
pydantic-settings==2.1.0
aiofiles==23.2.1
celery==5.3.6
minio==7.2.3
Pillow==10.2.0
numpy==1.26.4
opencv-python-headless==4.9.0.80
EOF
# 安装依赖
pip install -r requirements.txt
```
### 6.2 后端目录结构
```
backend/
├── app/
│ ├── __init__.py
│ ├── main.py # FastAPI 应用入口
│ ├── config.py # 配置管理
│ ├── database.py # 数据库连接
│ ├── models/ # SQLAlchemy 模型
│ ├── schemas/ # Pydantic 模型
│ ├── api/ # API 路由
│ │ └── v1/
│ │ ├── __init__.py
│ │ ├── auth.py
│ │ ├── projects.py
│ │ ├── tasks.py
│ │ ├── annotations.py
│ │ └── ...
│ ├── services/ # 业务逻辑层
│ ├── utils/ # 工具函数
│ └── core/ # 核心模块
│ ├── security.py # 安全认证
│ └── dependencies.py # 依赖注入
├── tests/ # 测试目录
├── alembic/ # 数据库迁移
├── models/ # AI 模型文件
├── data/ # 数据目录
├── requirements.txt
├── Dockerfile
├── Dockerfile.prod
└── .env
```
### 6.3 核心配置文件
创建 `backend/app/config.py`:
```python
# backend/app/config.py
from pydantic_settings import BaseSettings
from functools import lru_cache
class Settings(BaseSettings):
# 应用配置
APP_NAME: str = "PLabel"
APP_ENV: str = "development"
APP_DEBUG: bool = True
APP_SECRET_KEY: str = "plabel-secret-key-change-in-production"
# 数据库配置
POSTGRES_HOST: str = "localhost"
POSTGRES_PORT: int = 5433
POSTGRES_DB: str = "plabel"
POSTGRES_USER: str = "plabel"
POSTGRES_PASSWORD: str = "plabel"
@property
def DATABASE_URL(self) -> str:
return f"postgresql://{self.POSTGRES_USER}:{self.POSTGRES_PASSWORD}@{self.POSTGRES_HOST}:{self.POSTGRES_PORT}/{self.POSTGRES_DB}"
@property
def ASYNC_DATABASE_URL(self) -> str:
return f"postgresql+asyncpg://{self.POSTGRES_USER}:{self.POSTGRES_PASSWORD}@{self.POSTGRES_HOST}:{self.POSTGRES_PORT}/{self.POSTGRES_DB}"
# Redis 配置
REDIS_HOST: str = "localhost"
REDIS_PORT: int = 6379
REDIS_PASSWORD: str = ""
@property
def REDIS_URL(self) -> str:
if self.REDIS_PASSWORD:
return f"redis://:{self.REDIS_PASSWORD}@{self.REDIS_HOST}:{self.REDIS_PORT}/0"
return f"redis://{self.REDIS_HOST}:{self.REDIS_PORT}/0"
# MinIO 配置
MINIO_ENDPOINT: str = "localhost:9009"
MINIO_ACCESS_KEY: str = "minio"
MINIO_SECRET_KEY: str = "minio123"
MINIO_BUCKET: str = "plabel-bucket"
MINIO_SECURE: bool = False
# JWT 配置
JWT_SECRET_KEY: str = "plabel-jwt-secret-key-change-in-production"
JWT_ALGORITHM: str = "HS256"
ACCESS_TOKEN_EXPIRE_MINUTES: int = 1440 # 24小时
# Celery 配置
CELERY_BROKER_URL: str = "redis://localhost:6379/0"
CELERY_RESULT_BACKEND: str = "redis://localhost:6379/1"
# CORS 配置
CORS_ORIGINS: list = ["http://localhost:8008", "http://localhost:8899"]
class Config:
env_file = ".env"
case_sensitive = True
@lru_cache()
def get_settings() -> Settings:
return Settings()
settings = get_settings()
```
### 6.4 FastAPI 入口文件
创建 `backend/app/main.py`:
```python
# backend/app/main.py
from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware
from contextlib import asynccontextmanager
from app.config import settings
from app.api.v1 import auth, projects, tasks, annotations, data_items, reviews, auto_label, export
@asynccontextmanager
async def lifespan(app: FastAPI):
# 启动时执行
print(f"Starting {settings.APP_NAME} API...")
yield
# 关闭时执行
print("Shutting down...")
app = FastAPI(
title=settings.APP_NAME,
description="AI Training Data Annotation Platform API",
version="1.0.0",
docs_url="/docs",
redoc_url="/redoc",
lifespan=lifespan,
)
# CORS 中间件配置
app.add_middleware(
CORSMiddleware,
allow_origins=settings.CORS_ORIGINS,
allow_credentials=True,
allow_methods=["*"],
allow_headers=["*"],
)
# 健康检查端点
@app.get("/health")
async def health_check():
return {"status": "healthy", "service": settings.APP_NAME}
# 注册 API 路由
app.include_router(auth.router, prefix="/api/v1/auth", tags=["认证"])
app.include_router(projects.router, prefix="/api/v1/projects", tags=["项目"])
app.include_router(tasks.router, prefix="/api/v1/tasks", tags=["任务"])
app.include_router(data_items.router, prefix="/api/v1/data-items", tags=["数据"])
app.include_router(annotations.router, prefix="/api/v1/annotations", tags=["标注"])
app.include_router(reviews.router, prefix="/api/v1/reviews", tags=["审核"])
app.include_router(auto_label.router, prefix="/api/v1/autolabel", tags=["自动标注"])
app.include_router(export.router, prefix="/api/v1/export", tags=["导出"])
if __name__ == "__main__":
import uvicorn
uvicorn.run(
"app.main:app",
host="0.0.0.0",
port=8899,
reload=settings.APP_DEBUG,
)
```
### 6.5 启动后端服务
```bash
# 进入后端目录
cd /home/admin2/plabel/backend
# 激活虚拟环境
source venv/bin/activate
# 启动开发服务器 (端口 8899)
uvicorn app.main:app --host 0.0.0.0 --port 8899 --reload
# 或使用 Python 方式
python -m uvicorn app.main:app --host 0.0.0.0 --port 8899 --reload
```
---
## 7. 数据库配置
### 7.1 PostgreSQL 安装与配置
```bash
# Ubuntu/Debian 安装 PostgreSQL
sudo apt-get update
sudo apt-get install -y postgresql postgresql-contrib
# 启动服务
sudo systemctl start postgresql
sudo systemctl enable postgresql
# 切换到 postgres 用户
sudo -u postgres psql
# 在 psql 中执行以下命令创建数据库和用户
CREATE USER plabel WITH PASSWORD 'plabel';
CREATE DATABASE plabel OWNER plabel;
GRANT ALL PRIVILEGES ON DATABASE plabel TO plabel;
# 退出
\q
```
### 7.2 修改 PostgreSQL 端口
如果需要将 PostgreSQL 端口从默认的 5432 改为 5433,修改配置文件:
```bash
# 编辑 postgresql.conf
sudo nano /etc/postgresql/*/main/postgresql.conf
# 找到 port 配置项,修改为 5433
# port = 5433
# 重启服务
sudo systemctl restart postgresql
```
### 7.3 数据库初始化
```bash
# 进入后端目录
cd /home/admin2/plabel/backend
# 激活虚拟环境
source venv/bin/activate
# 创建 Alembic 配置
alembic init alembic
# 配置 alembic.ini 中的数据库连接
# sqlalchemy.url = postgresql://plabel:plabel@localhost:5433/plabel
# 创建初始迁移
alembic revision --autogenerate -m "initial"
# 执行迁移
alembic upgrade head
```
### 7.4 验证数据库连接
```bash
# 测试连接
psql -h localhost -p 5433 -U plabel -d plabel
# 验证表结构
\dt
# 退出
\q
```
---
## 8. 存储服务配置
### 8.1 MinIO 安装
#### 方式一:Docker 部署(推荐)
```bash
# 创建 MinIO 数据目录
mkdir -p /home/admin2/plabel/data/minio
# 启动 MinIO 容器
docker run -d \
--name minio \
-p 9009:9000 \
-p 9010:9010 \
-e "MINIO_ROOT_USER=minio" \
-e "MINIO_ROOT_PASSWORD=minio123" \
-v /home/admin2/plabel/data/minio:/data \
minio/minio server /data --console-address ":9010"
```
#### 方式二:直接安装
```bash
# 下载 MinIO
wget https://dl.min.io/server/minio/release/linux-amd64/minio
chmod +x minio
sudo mv minio /usr/local/bin/
# 创建数据目录
sudo mkdir -p /home/admin2/plabel/data/minio
sudo chmod -R 777 /home/admin2/plabel/data/minio
# 后台启动 MinIO
nohup sudo MINIO_ROOT_USER=minio MINIO_ROOT_PASSWORD=minio123 \
/usr/local/bin/minio server /home/admin2/plabel/data/minio \
--console-address ":9010" > /var/log/minio.log 2>&1 &
```
### 8.2 创建存储桶
通过 MinIO Console 或命令行创建存储桶:
```bash
# 安装 mc 客户端
docker exec -it minio mc alias set myminio http://localhost:9000 minio minio123
# 创建存储桶
docker exec -it minio mc mb myminio/plabel-bucket
# 设置存储桶策略(公开读取)
docker exec -it minio mc anonymous set download myminio/plabel-bucket
```
### 8.3 存储桶目录结构
```
plabel-bucket/
├── originals/ # 原始上传文件
│ └── {project_id}/
│ └── {task_id}/
│ ├── images/
│ ├── videos/
│ ├── audios/
│ └── texts/
├── thumbnails/ # 缩略图
├── annotations/ # 标注备份
└── exports/ # 导出文件
```
---
## 9. AI 模型服务
### 9.1 Celery 任务队列配置
创建 `backend/app/celery_app.py`:
```python
# backend/app/celery_app.py
from celery import Celery
from app.config import settings
celery_app = Celery(
"plabel",
broker=settings.CELERY_BROKER_URL,
backend=settings.CELERY_RESULT_BACKEND,
include=["app.services.auto_label"]
)
# Celery 配置
celery_app.conf.update(
task_serializer="json",
accept_content=["json"],
result_serializer="json",
timezone="Asia/Shanghai",
enable_utc=True,
task_track_started=True,
task_time_limit=3600, # 1小时
worker_prefetch_multiplier=1,
worker_concurrency=4,
)
# 定义任务队列
celery_app.conf.task_routes = {
"app.services.auto_label.tasks.*": {"queue": "auto_label"},
}
```
### 9.2 启动 Worker
```bash
# 激活虚拟环境
source venv/bin/activate
# 启动 Celery Worker
celery -A app.celery_app worker --loglevel=info --concurrency=4
# 启动 Flower 监控面板
celery -A app.celery_app flower --port=5555
```
---
## 10. Docker 容器编排
### 10.1 docker-compose.yml
创建 `backend/docker-compose.yml`:
```yaml
version: '3.8'
services:
# PostgreSQL 数据库
postgres:
image: postgres:15-alpine
container_name: plabel-postgres
environment:
POSTGRES_DB: plabel
POSTGRES_USER: plabel
POSTGRES_PASSWORD: plabel
ports:
- "5433:5432" # 映射到主机 5433 端口
volumes:
- postgres_data:/var/lib/postgresql/data
- ./postgres/init.sql:/docker-entrypoint-initdb.d/init.sql
healthcheck:
test: ["CMD-SHELL", "pg_isready -U plabel -d plabel"]
interval: 10s
timeout: 5s
retries: 5
# Redis 缓存
redis:
image: redis:7-alpine
container_name: plabel-redis
ports:
- "6379:6379"
volumes:
- redis_data:/data
healthcheck:
test: ["CMD", "redis-cli", "ping"]
interval: 10s
timeout: 5s
retries: 5
# MinIO 对象存储
minio:
image: minio/minio:latest
container_name: plabel-minio
environment:
MINIO_ROOT_USER: minio
MINIO_ROOT_PASSWORD: minio123
ports:
- "9009:9000" # API 端口
- "9010:9010" # Console 端口
volumes:
- minio_data:/data
command: server /data --console-address ":9010"
healthcheck:
test: ["CMD", "curl", "-f", "http://localhost:9000/minio/health/live"]
interval: 10s
timeout: 5s
retries: 5
# FastAPI 后端
backend:
build:
context: ./backend
dockerfile: Dockerfile
container_name: plabel-backend
environment:
APP_ENV: development
POSTGRES_HOST: postgres
POSTGRES_PORT: 5432
POSTGRES_DB: plabel
POSTGRES_USER: plabel
POSTGRES_PASSWORD: plabel
REDIS_HOST: redis
REDIS_PORT: 6379
MINIO_ENDPOINT: minio:9000
MINIO_ACCESS_KEY: minio
MINIO_SECRET_KEY: minio123
MINIO_BUCKET: plabel-bucket
ports:
- "8899:8899"
depends_on:
postgres:
condition: service_healthy
redis:
condition: service_healthy
minio:
condition: service_healthy
volumes:
- ./backend:/app
- model_data:/app/models
command: uvicorn app.main:app --host 0.0.0.0 --port 8899 --reload
# Celery Worker
celery_worker:
build:
context: ./backend
dockerfile: Dockerfile
container_name: plabel-celery
environment:
POSTGRES_HOST: postgres
POSTGRES_PORT: 5432
POSTGRES_DB: plabel
POSTGRES_USER: plabel
POSTGRES_PASSWORD: plabel
REDIS_HOST: redis
REDIS_PORT: 6379
MINIO_ENDPOINT: minio:9000
MINIO_ACCESS_KEY: minio
MINIO_SECRET_KEY: minio123
depends_on:
- redis
- postgres
- minio
volumes:
- ./backend:/app
- model_data:/app/models
command: celery -A app.celery_app worker --loglevel=info --concurrency=2
# Flower 监控
flower:
build:
context: ./backend
dockerfile: Dockerfile
container_name: plabel-flower
ports:
- "5555:5555"
environment:
REDIS_HOST: redis
REDIS_PORT: 6379
depends_on:
- celery_worker
command: celery -A app.celery_app flower --port=5555
volumes:
postgres_data:
redis_data:
minio_data:
model_data:
networks:
default:
name: plabel-network
```
### 10.2 启动所有服务
```bash
# 进入后端目录
cd /home/admin2/plabel/backend
# 启动所有服务
docker-compose up -d
# 查看服务状态
docker-compose ps
# 查看日志
docker-compose logs -f
# 停止所有服务
docker-compose down
```
---
## 11. 前后端联调
### 11.1 前端 API 对接
修改 `frontend/src/api/index.ts`,将 Mock 模式切换为真实 API 调用:
```typescript
// frontend/src/api/index.ts
import axios from 'axios'
import type {
ApiResponse,
PaginatedResponse,
Task,
// ... 其他类型
} from '@/types'
// API 基础配置
const API_BASE_URL = 'http://localhost:8899/api/v1'
// 创建 axios 实例
const apiClient = axios.create({
baseURL: API_BASE_URL,
timeout: 30000,
headers: {
'Content-Type': 'application/json',
},
})
// 请求拦截器 - 添加 Token
apiClient.interceptors.request.use(
(config) => {
const token = localStorage.getItem('access_token')
if (token) {
config.headers.Authorization = `Bearer ${token}`
}
return config
},
(error) => Promise.reject(error)
)
// 响应拦截器
apiClient.interceptors.response.use(
(response) => response.data,
(error) => {
if (error.response?.status === 401) {
// Token 过期,跳转登录
localStorage.removeItem('access_token')
window.location.href = '/login'
}
return Promise.reject(error)
}
)
// ============ 认证 API ============
export const AuthAPI = {
login: (data: { email: string; password: string }) =>
apiClient.post<ApiResponse<{ access_token: string; user: any }>>('/auth/login', data),
register: (data: { username: string; email: string; password: string }) =>
apiClient.post<ApiResponse<any>>('/auth/register', data),
getCurrentUser: () =>
apiClient.get<ApiResponse<any>>('/auth/me'),
}
// ============ 任务 API ============
export const TaskAPI = {
list: (params?: { page?: number; pageSize?: number; status?: string }) =>
apiClient.get<ApiResponse<PaginatedResponse<Task>>>('/tasks', { params }),
get: (id: string) =>
apiClient.get<ApiResponse<Task>>(`/tasks/${id}`),
create: (data: Partial<Task>) =>
apiClient.post<ApiResponse<Task>>('/tasks', data),
update: (id: string, data: Partial<Task>) =>
apiClient.put<ApiResponse<Task>>(`/tasks/${id}`, data),
delete: (id: string) =>
apiClient.delete(`/tasks/${id}`),
}
// ... 其他 API 模块类似
```
### 11.2 跨域问题解决
#### 方案一:开发环境代理(推荐)
在 `vite.config.ts` 中配置代理,前端请求 `/api` 自动转发到后端。
#### 方案二:CORS 配置
后端配置允许前端域名:
```python
# backend/app/main.py
app.add_middleware(
CORSMiddleware,
allow_origins=[
"http://localhost:8008", # 前端开发地址
"http://localhost:3000",
],
allow_credentials=True,
allow_methods=["*"],
allow_headers=["*"],
)
```
### 11.3 联调测试步骤
1. **启动后端服务**
```bash
cd /home/admin2/plabel/backend
source venv/bin/activate
uvicorn app.main:app --host 0.0.0.0 --port 8899 --reload
```
2. **验证后端 API**
```bash
curl http://localhost:8899/health
curl http://localhost:8899/docs # Swagger 文档
```
3. **启动前端服务**
```bash
cd /home/admin2/plabel/frontend
npm run dev
```
4. **浏览器访问**
打开浏览器访问 http://localhost:8008
5. **测试登录**
- 调用 POST /api/v1/auth/login
- 保存返回的 token
- 使用 token 访问受保护的接口
---
## 12. 部署检查清单
### 12.1 服务启动检查
- [ ] PostgreSQL 服务运行在 5433 端口
- [ ] Redis 服务运行在 6379 端口
- [ ] MinIO 服务运行在 9009/9010 端口
- [ ] FastAPI 后端运行在 8899 端口
- [ ] 前端 Vue 服务运行在 8008 端口
- [ ] Flower 监控运行在 5555 端口(可选)
### 12.2 连接测试
```bash
# 测试数据库连接
pg_isready -h localhost -p 5433 -U plabel
# 测试 Redis 连接
redis-cli -h localhost -p 6379 ping
# 测试 MinIO 连接
curl http://localhost:9009/minio/health/live
# 测试后端 API
curl http://localhost:8899/health
# 测试前端页面
curl http://localhost:8008
```
### 12.3 功能验证
- [ ] 用户可以注册和登录
- [ ] 可以创建项目和任务
- [ ] 可以上传数据文件
- [ ] 可以进行标注操作
- [ ] 可以提交审核
- [ ] 可以导出数据
---
## 13. 运维指南
### 13.1 日志查看
```bash
# 后端日志
docker-compose logs -f backend
# Celery 日志
docker-compose logs -f celery_worker
# 查看实时日志
tail -f /var/log/plabel/app.log
```
### 13.2 数据备份
```bash
# 数据库备份
pg_dump -h localhost -p 5433 -U plabel plabel > backup_$(date +%Y%m%d).sql
# MinIO 数据备份
tar -czf minio_backup_$(date +%Y%m%d).tar.gz /home/admin2/plabel/data/minio
```
### 13.3 常用命令
```bash
# 重启服务
docker-compose restart
# 查看服务状态
docker-compose ps
# 查看资源使用
docker stats
# 清理未使用的资源
docker system prune -f
# 查看容器 IP
docker inspect -f '{{range.NetworkSettings.Networks}}{{.IPAddress}}{{end}}' container_name
```
### 13.4 故障排查
| 问题 | 可能原因 | 解决方案 |
|------|---------|---------|
| 后端无法启动 | 端口被占用 | `lsof -i :8899` 检查并释放端口 |
| 数据库连接失败 | 端口或密码错误 | 检查 .env 配置和 PostgreSQL 状态 |
| 文件上传失败 | MinIO 未启动 | 检查 MinIO 容器状态 |
| 前端无法访问 | 端口未开放 | 检查防火墙和端口映射 |
| CORS 错误 | 后端未配置 CORS | 检查后端 CORS 配置 |
---
## 附录
### A. 环境变量模板
```bash
# .env 文件模板
APP_NAME=PLabel
APP_ENV=development
APP_DEBUG=true
APP_SECRET_KEY=your-secret-key
POSTGRES_HOST=localhost
POSTGRES_PORT=5433
POSTGRES_DB=plabel
POSTGRES_USER=plabel
POSTGRES_PASSWORD=plabel
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=
MINIO_ENDPOINT=localhost:9009
MINIO_ACCESS_KEY=minio
MINIO_SECRET_KEY=minio123
MINIO_BUCKET=plabel-bucket
MINIO_SECURE=false
JWT_SECRET_KEY=your-jwt-secret-key
JWT_ALGORITHM=HS256
ACCESS_TOKEN_EXPIRE_MINUTES=1440
CELERY_BROKER_URL=redis://localhost:6379/0
CELERY_RESULT_BACKEND=redis://localhost:6379/1
CORS_ORIGINS=http://localhost:8008,http://localhost:8899
```
### B. 参考文档
- [FastAPI 官方文档](https://fastapi.tiangolo.com/)
- [Vue 3 官方文档](https://vuejs.org/)
- [PostgreSQL 文档](https://www.postgresql.org/docs/)
- [MinIO 文档](https://min.io/docs/)
- [Celery 文档](https://docs.celeryproject.org/)
---
*文档版本: v1.0*
*创建日期: 2026年5月28日*
#!/bin/bash
# PLabel 服务启动脚本 一键重启所有服务
# Phase 0: 项目初始化、环境搭建
set -e
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
echo "=========================================="
echo " PLabel 服务启动脚本"
echo "=========================================="
echo ""
# 颜色定义
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
RED='\033[0;31m'
NC='\033[0m' # No Color
# 检查Docker是否运行
check_docker() {
if ! docker info > /dev/null 2>&1; then
echo -e "${RED}错误: Docker未运行,请先启动Docker${NC}"
exit 1
fi
echo -e "${GREEN}✓ Docker已运行${NC}"
}
# 启动PostgreSQL
start_postgres() {
echo -e "\n${YELLOW}启动 PostgreSQL...${NC}"
if docker ps -a --format '{{.Names}}' | grep -q "^plabel-postgres$"; then
docker start plabel-postgres 2>/dev/null || true
else
docker run -d \
--name plabel-postgres \
-e POSTGRES_DB=plabel \
-e POSTGRES_USER=plabel \
-e POSTGRES_PASSWORD=plabel \
-v plabel-postgres-data:/var/lib/postgresql/data \
-p 0.0.0.0:5433:5432 \
--restart unless-stopped \
docker.m.daocloud.io/library/postgres:15-alpine
fi
echo -e "${GREEN}✓ PostgreSQL 已启动 (端口: 5433)${NC}"
}
# 启动MinIO
start_minio() {
echo -e "\n${YELLOW}启动 MinIO...${NC}"
if docker ps -a --format '{{.Names}}' | grep -q "^plabel-minio$"; then
docker start plabel-minio 2>/dev/null || true
else
docker run -d \
--name plabel-minio \
-e MINIO_ROOT_USER=minio \
-e MINIO_ROOT_PASSWORD=minio123 \
-v plabel-minio-data:/data \
-p 9009:9009 \
-p 9010:9010 \
--restart unless-stopped \
docker.m.daocloud.io/minio/minio:latest server /data --console-address ":9010"
fi
echo -e "${GREEN}✓ MinIO 已启动 (API: 9009, Console: 9010)${NC}"
}
# 创建MinIO存储桶
setup_minio_bucket() {
echo -e "\n${YELLOW}配置 MinIO 存储桶...${NC}"
sleep 3
MINIO_IP=$(docker inspect plabel-minio --format '{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}')
docker exec plabel-minio mc alias set local http://${MINIO_IP}:9000 minio minio123 2>/dev/null || true
docker exec plabel-minio mc mb local/plabel-bucket --ignore-existing 2>/dev/null || true
echo -e "${GREEN}✓ MinIO 存储桶已创建${NC}"
}
# 验证服务
verify_services() {
echo -e "\n${YELLOW}验证服务状态...${NC}"
sleep 5
# PostgreSQL
if docker exec plabel-postgres pg_isready -U plabel > /dev/null 2>&1; then
echo -e "${GREEN}✓ PostgreSQL: localhost:5433${NC}"
else
echo -e "${RED}✗ PostgreSQL 连接失败${NC}"
fi
# MinIO
MINIO_IP=$(docker inspect plabel-minio --format '{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}')
if docker exec plabel-minio mc ls local/ > /dev/null 2>&1; then
echo -e "${GREEN}✓ MinIO: localhost:9009 (Console: localhost:9010)${NC}"
else
echo -e "${RED}✗ MinIO 连接失败${NC}"
fi
}
# 显示访问信息
show_info() {
echo -e "\n=========================================="
echo -e " 服务访问信息"
echo -e "=========================================="
echo ""
echo -e "${GREEN}PostgreSQL:${NC}"
echo -e " 地址: localhost:5433"
echo -e " 数据库: plabel"
echo -e " 用户名: plabel"
echo -e " 密码: plabel"
echo ""
echo -e "${GREEN}MinIO:${NC}"
echo -e " API地址: localhost:9009"
echo -e " Console: http://localhost:9010"
echo -e " Access Key: minio"
echo -e " Secret Key: minio123"
echo -e " Bucket: plabel-bucket"
echo ""
echo -e "${GREEN}后端 API:${NC}"
echo -e " 地址: localhost:8899"
echo -e " 文档: http://localhost:8899/docs"
echo ""
echo -e "${GREEN}启动后端命令:${NC}"
echo -e " cd $SCRIPT_DIR/backend"
echo -e " /datacore/home/admin2/miniconda3/envs/plabel/bin/uvicorn app.main:app --host 0.0.0.0 --port 8899 --reload"
echo ""
}
# 主函数
main() {
check_docker
start_postgres
start_minio
setup_minio_bucket
verify_services
show_info
}
main "$@"
#!/bin/bash
# PLabel Frontend Development Server Launcher
set -e
# Activate conda environment
export PATH="/datacore/home/admin2/miniconda3/bin:$PATH"
source /datacore/home/admin2/miniconda3/etc/profile.d/conda.sh
......@@ -11,15 +13,93 @@ SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
PLABEL_ROOT="$(dirname "$SCRIPT_DIR")"
FRONTEND_DIR="$PLABEL_ROOT/frontend"
LOG_FILE="$PLABEL_ROOT/logs/Vue_8008.log"
PID_FILE="$PLABEL_ROOT/logs/vue_8008.pid"
start_server() {
if [ -f "$PID_FILE" ] && kill -0 "$(cat "$PID_FILE")" 2>/dev/null; then
echo "Server is already running (PID: $(cat "$PID_FILE")). Use 'restart' to restart."
return 1
fi
mkdir -p "$PLABEL_ROOT/logs"
echo "Starting PLabel Frontend Development Server..."
echo "Server will be available at: http://localhost:8008/"
echo "Logs will be written to: $LOG_FILE"
echo ""
cd "$FRONTEND_DIR"
# Start in background, redirect output to log file
nohup npm run dev > "$LOG_FILE" 2>&1 &
echo $! > "$PID_FILE"
sleep 2
if kill -0 "$(cat "$PID_FILE")" 2>/dev/null; then
echo "Server started successfully (PID: $(cat "$PID_FILE"))"
else
echo "Server failed to start. Check logs: $LOG_FILE"
rm -f "$PID_FILE"
return 1
fi
}
stop_server() {
if [ ! -f "$PID_FILE" ]; then
echo "Server is not running (no PID file found)."
return 0
fi
PID=$(cat "$PID_FILE")
if ! kill -0 "$PID" 2>/dev/null; then
echo "Server is not running (stale PID file)."
rm -f "$PID_FILE"
return 0
fi
echo "Stopping server (PID: $PID)..."
kill "$PID" 2>/dev/null
# Wait for process to terminate
for i in {1..10}; do
if ! kill -0 "$PID" 2>/dev/null; then
echo "Server stopped successfully."
rm -f "$PID_FILE"
return 0
fi
sleep 1
done
# Create logs directory if not exists
mkdir -p "$PLABEL_ROOT/logs"
echo "Force killing server..."
kill -9 "$PID" 2>/dev/null
rm -f "$PID_FILE"
echo "Server stopped."
}
# Start development server with logging
echo "Starting PLabel Frontend Development Server..."
echo "Server will be available at: http://localhost:8008/"
echo "Logs will be written to: $LOG_FILE"
echo ""
restart_server() {
echo "Restarting server..."
stop_server
sleep 1
start_server
}
cd "$FRONTEND_DIR"
npm run dev 2>&1 | tee "$LOG_FILE"
case "${1:-}" in
start)
start_server
;;
stop)
stop_server
;;
restart)
restart_server
;;
*)
echo "Usage: bash start.sh {start|restart|stop}"
echo ""
echo " start - Start the PLabel frontend development server"
echo " stop - Stop the running server"
echo " restart - Stop and start the server"
exit 1
;;
esac
Markdown 格式
0% 或
您添加了 0 人 到此讨论。请谨慎行事。
请先完成此评论的编辑!
请 注册 或者 后发表评论