Assemblyline 本地开发镜像 技术文档

1. 镜像概述和主要用途

1.1 概述

本镜像是为 Assemblyline 项目设计的本地开发专用环境镜像，旨在简化开发者的环境配置流程，提供统一、可复现的开发环境，减少因本地环境差异导致的开发障碍。

1.2 主要用途

• 快速部署 Assemblyline 本地开发环境，无需手动配置复杂依赖
• 支持代码实时修改与调试，提升开发效率
• 提供与 Assemblyline 核心组件兼容的运行时环境，便于功能验证与集成测试
• 统一团队开发环境，确保代码在一致环境中构建与运行

2. 核心功能和特性

• 一键部署开发环境：集成 Assemblyline 开发所需的全部依赖（如数据库、缓存服务、开发工具等），支持一键启动完整开发栈
• 依赖自动配置：自动安装并配置 Assemblyline 开发所需的系统库、Python 包及第三方服务（如 PostgreSQL、Redis）
• 与核心组件兼容：与 Assemblyline 核心模块（如前端、后端 API、任务队列等）无缝集成，确保开发功能可直接对接现有架构
• 本地代码挂载支持：支持将本地代码目录挂载至容器内，实现代码实时修改与热重载，无需重启容器
• 调试工具集成：内置常用调试工具（如 pdb、logging 增强组件），便于追踪代码执行流程与定位问题

3. 使用场景和适用范围

3.1 使用场景

• Assemblyline 功能开发：开发者基于本地代码进行新功能开发与逻辑验证
• Bug 修复：针对特定问题在本地复现并调试修复，验证修复效果
• 单元测试与集成测试：在隔离环境中运行测试用例，确保代码质量
• 扩展开发：开发 Assemblyline 插件、自定义分析器等扩展组件

3.2 适用范围

• 目标用户：Assemblyline 项目贡献者、二次开发人员、企业内部定制化开发团队
• 前置知识：需具备 Docker 基础操作能力及 Assemblyline 项目基本架构认知

4. 详细使用方法和配置说明

4.1 前提条件

• 已安装 Docker Engine（20.10+）及 Docker Compose（v2+）
• 本地已克隆 Assemblyline 项目代码仓库（[***]

4.2 获取镜像

4.2.1 从 Docker Hub 拉取（推荐）

bash
docker pull cccs/assemblyline-dev:latest

4.2.2 本地构建（如需修改镜像源码）

bash
# 克隆 Assemblyline 源码仓库（含镜像构建文件）
git clone [***]
cd assemblyline/dev-environment

# 构建镜像
docker build -t cccs/assemblyline-dev:local .

4.3 基本使用（docker run 命令）

通过以下命令启动开发容器，挂载本地代码目录并映射必要端口：

bash
docker run -d \
  --name assemblyline-dev \
  -p 8080:8080  # 前端服务端口（示例） \
  -p 5000:5000  # 后端 API 端口（示例） \
  -v /path/to/local/assemblyline/code:/app  # 挂载本地代码目录至容器内 /app \
  -e ASSEMBLYLINE_DEV_MODE=1  # 启用开发模式 \
  cccs/assemblyline-dev:latest

4.4 Docker Compose 配置示例

创建 docker-compose.yml 文件，定义完整开发环境（含依赖服务）：

yaml
version: '3.8'

services:
  assemblyline-dev:
    image: cccs/assemblyline-dev:latest
    container_name: assemblyline-dev
    ports:
      - "8080:8080"  # 前端访问端口
      - "5000:5000"  # 后端 API 端口
      - "5678:5678"  # 调试端口（如需远程调试）
    volumes:
      - ./assemblyline:/app  # 本地代码目录挂载（替换为实际路径）
      - ./dev-data:/data  # 持久化开发数据（如数据库文件）
    environment:
      - ASSEMBLYLINE_DEV_MODE=1
      - DB_HOST=postgres  # 连接容器内 PostgreSQL 服务
      - REDIS_HOST=redis  # 连接容器内 Redis 服务
      - LOG_LEVEL=DEBUG  # 调试级别日志输出
    depends_on:
      - postgres
      - redis

  postgres:
    image: postgres:14-alpine
    environment:
      - POSTGRES_USER=assemblyline
      - POSTGRES_PASSWORD=devpass
      - POSTGRES_DB=assemblyline_dev
    volumes:
      - postgres-data:/var/lib/postgresql/data

  redis:
    image: redis:7-alpine
    volumes:
      - redis-data:/data

volumes:
  postgres-data:
  redis-data:

启动命令：

bash
docker-compose up -d

4.5 常用操作

• 启动容器：docker start assemblyline-dev 或 docker-compose up -d
• 停止容器：docker stop assemblyline-dev 或 docker-compose down
• 进入容器：docker exec -it assemblyline-dev /bin/bash
• 查看日志：docker logs -f assemblyline-dev（-f 实时跟踪）
• 重启服务：docker restart assemblyline-dev

5. 配置参数与环境变量

6. 常见问题与故障排除

• 问题：本地代码修改后容器内未生效？
  解决：确认本地代码目录已正确挂载（-v /local/path:/app），且 ASSEMBLYLINE_DEV_MODE=1 已启用热重载。

• 问题：数据库连接失败？
  解决：检查 DB_HOST 与 DB_PORT 是否正确（使用 Docker Compose 时需指定服务名而非 localhost），或通过 docker logs postgres 查看数据库服务日志。

• 问题：容器启动后端口冲突？
  解决：修改 docker run 或 docker-compose.yml 中的端口映射（如 -p 8081:8080 将容器 8080 端口映射至主机 8081 端口）。