label_backend/specs/001-label-backend-spec/quickstart.md

快速启动指南：label_backend

日期: 2026-04-09
分支: 001-label-backend-spec

---

前置条件

• Docker Desktop ≥ 4.x（含 Docker Compose v2）
• JDK 17（本地开发时）
• Maven ≥ 3.8（本地开发时）

---

一、使用 Docker Compose 启动完整环境

# 克隆仓库
git clone <repo-url>
cd label_backend

# 启动所有服务（PostgreSQL + Redis + RustFS + AI Service + Backend + Frontend）
docker compose up -d

# 查看后端启动日志
docker compose logs -f backend

# 检查健康状态
docker compose ps

服务端口:

服务	端口
前端（Nginx）	http://localhost:80
后端 REST API	http://localhost:8080
AI 服务（FastAPI）	http://localhost:8000
PostgreSQL	localhost:5432
Redis	localhost:6379
RustFS S3 API	http://localhost:9000
RustFS Web 控制台	http://localhost:9001

---

二、初始化数据库

数据库 DDL 通过 ./sql/init.sql 在 PostgreSQL 容器启动时自动执行（docker-entrypoint-initdb.d）。

若需手动执行：

docker compose exec postgres psql -U label -d label_db -f /docker-entrypoint-initdb.d/init.sql

初始账号（由 init.sql 中的 INSERT 语句创建）：

用户名	密码	角色	公司
admin	admin123	ADMIN	演示公司
reviewer01	review123	REVIEWER	演示公司
annotator01	annot123	ANNOTATOR	演示公司
uploader01	upload123	UPLOADER	演示公司

---

三、本地开发模式（不使用 Docker）

# 启动依赖服务（仅 PostgreSQL + Redis + RustFS，不启动后端）
docker compose up -d postgres redis rustfs

# 设置环境变量
export SPRING_DATASOURCE_URL=jdbc:postgresql://localhost:5432/label_db
export SPRING_DATASOURCE_USERNAME=label
export SPRING_DATASOURCE_PASSWORD=label_password
export SPRING_REDIS_HOST=localhost
export SPRING_REDIS_PORT=6379
export SPRING_REDIS_PASSWORD=redis_password
export RUSTFS_ENDPOINT=http://localhost:9000
export RUSTFS_ACCESS_KEY=minioadmin
export RUSTFS_SECRET_KEY=minioadmin
export AI_SERVICE_BASE_URL=http://localhost:8000

# 编译并启动
mvn clean spring-boot:run

---

四、验证安装

# 1. 登录（获取 Token）
curl -X POST http://localhost:8080/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"companyCode":"DEMO","username":"admin","password":"admin123"}'

# 期望响应：{"code":"SUCCESS","data":{"token":"...","role":"ADMIN",...}}

# 2. 使用 Token 访问受保护接口（将 {TOKEN} 替换为上一步返回的 token）
curl http://localhost:8080/api/auth/me \
  -H "Authorization: Bearer {TOKEN}"

# 期望响应：{"code":"SUCCESS","data":{"username":"admin","role":"ADMIN",...}}

---

五、运行测试

# 运行所有测试（Testcontainers 会自动启动真实 PG + Redis 容器）
mvn test

# 运行特定测试（并发任务领取）
mvn test -Dtest=TaskClaimConcurrencyTest

# 运行集成测试套件
mvn test -Dtest=*IntegrationTest

注意: Testcontainers 需要本地 Docker 可用。首次运行会拉取 PostgreSQL 和 Redis 镜像（约 200MB）。

---

六、关键配置项说明

配置文件位于 src/main/resources/application.yml。以下配置项可在运行时通过 PUT /api/config/{key} 接口（ADMIN 权限）动态调整，无需重启服务：

配置键	说明	默认值
token_ttl_seconds	会话凭证有效期（秒）	7200（2小时）
model_default	AI 辅助默认模型	glm-4
video_frame_interval	视频帧提取间隔（帧数）	30
prompt_extract_text	文本三元组提取 Prompt	见 init.sql
prompt_extract_image	图片四元组提取 Prompt	见 init.sql
prompt_qa_gen_text	文本问答生成 Prompt	见 init.sql
prompt_qa_gen_image	图片问答生成 Prompt	见 init.sql

---

七、标注流水线快速验证

TOKEN="your-admin-token"

# 步骤 1：上传文本资料
curl -X POST http://localhost:8080/api/source/upload \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@sample.txt" -F "dataType=TEXT"

# 步骤 2：为资料创建提取任务（sourceId 从上一步响应中获取）
curl -X POST http://localhost:8080/api/tasks \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"sourceId": 1, "taskType": "AI_ASSISTED", "aiModel": "glm-4"}'

# 步骤 3：标注员领取任务（使用 annotator01 的 Token）
ANNOTATOR_TOKEN="annotator-token"
curl -X POST http://localhost:8080/api/tasks/1/claim \
  -H "Authorization: Bearer $ANNOTATOR_TOKEN"

# 步骤 4：获取 AI 预标注结果
curl http://localhost:8080/api/extraction/1 \
  -H "Authorization: Bearer $ANNOTATOR_TOKEN"

# 步骤 5：提交标注结果
curl -X PUT http://localhost:8080/api/extraction/1 \
  -H "Authorization: Bearer $ANNOTATOR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"items":[{"subject":"北京","predicate":"是首都","object":"中国","sourceText":"北京是中国的首都","startOffset":0,"endOffset":8}]}'

curl -X POST http://localhost:8080/api/extraction/1/submit \
  -H "Authorization: Bearer $ANNOTATOR_TOKEN"

# 步骤 6：审批员审批通过（使用 reviewer01 的 Token）
REVIEWER_TOKEN="reviewer-token"
curl -X POST http://localhost:8080/api/extraction/1/approve \
  -H "Authorization: Bearer $REVIEWER_TOKEN"