bubbaj/class-api-it4200-2024-fall

IT-4200 2024秋季学期课程API Docker镜像文档

1. 镜像概述和主要用途

本Docker镜像专为IT-4200 2024秋季学期课程设计，用于封装和运行课程配套的API服务。其核心用途是提供标准化的API运行环境，确保课程相关的开发、测试、作业提交及教学演示过程中环境一致性，简化学生和教师的本地部署流程。

2. 核心功能和特性

• 课程API集成：内置课程所需的全部API接口，涵盖教学案例、作业提交、数据验证等核心功能。
• 环境一致性：通过容器化消除"本地环境差异"问题，确保所有用户使用相同的运行时配置。
• 轻量级部署：基于精简基础镜像构建，资源占用低，支持快速启动和停止。
• 可配置性：支持通过环境变量自定义端口、日志级别、数据存储路径等关键参数。
• 数据持久化：默认支持挂载外部目录保存API运行数据，避免容器重启后数据丢失。

3. 使用场景和适用范围

适用场景

• 学生本地开发与测试：快速搭建课程API环境，验证作业代码与API的交互逻辑。
• 作业提交环境：作为标准化的运行环境，确保提交的作业在统一配置下执行。
• 教学演示：教师在课堂中快速启动API服务，展示接口调用流程和功能特性。

适用对象

• IT-4200 2024秋季学期注册学生
• 课程授课教师及助教

4. 使用方法和配置说明

4.1 前置条件

• 已安装Docker Engine（20.10+版本）
• 已安装Docker Compose（可选，用于多容器部署）

4.2 获取镜像

方式1：从Docker Registry拉取（若提供）

bash
docker pull [registry-url]/it4200-class-api:2024-fall

方式2：本地构建（若提供Dockerfile）

bash
# 克隆课程代码仓库（假设包含Dockerfile）
git clone [课程代码仓库地址]
cd [仓库目录]

# 构建镜像
docker build -t it4200-class-api:2024-fall .

4.3 运行容器（基础模式）

使用docker run命令启动API服务：

bash
docker run -d \
  --name it4200-api \
  -p 8080:8080 \  # 端口映射（主机端口:容器端口）
  -v ./api-data:/app/data \  # 数据持久化（主机目录:容器目录）
  -e LOG_LEVEL=info \  # 日志级别（debug/info/warn/error）
  -e API_TIMEOUT=30 \  # 请求超时时间（秒）
  it4200-class-api:2024-fall

参数说明：

• -d：后台运行容器
• --name：指定容器名称（便于管理）
• -p：端口映射，默认容器内API服务监听8080端口
• -v：挂载外部目录到容器内/app/data，用于持久化API数据（如配置文件、日志、作业数据等）
• -e：设置环境变量（详见4.5节环境变量说明）

4.4 Docker Compose配置（推荐，适用于复杂场景）

创建docker-compose.yml文件：

yaml
version: '3.8'

services:
  api:
    image: it4200-class-api:2024-fall
    container_name: it4200-api
    restart: unless-stopped  # 容器退出时自动重启（除非手动停止）
    ports:
      - "8080:8080"
    volumes:
      - ./api-data:/app/data  # 数据持久化目录
      - ./logs:/app/logs      # 日志输出目录（可选）
    environment:
      - LOG_LEVEL=info
      - API_TIMEOUT=30
      - DB_CONN_STR=sqlite:///app/data/db.sqlite  # 数据库连接字符串（若API依赖数据库）
    networks:
      - class-network  # 自定义网络（可选，用于与其他服务联动）

networks:
  class-network:
    driver: bridge

启动服务：

bash
docker-compose up -d

停止服务：

bash
docker-compose down

4.5 环境变量配置

容器支持通过环境变量自定义服务行为，常用变量如下：

4.6 验证服务状态

服务启动后，通过以下方式验证是否正常运行：

1. 检查容器状态：

   bash
   docker ps | grep it4200-api  # 若状态为Up则表示运行中
   

2. 访问API健康检查接口（假设提供）：

   bash
   curl http://localhost:8080/health  # 预期返回{"status":"ok"}
   

3. 查看服务日志：

   bash
   docker logs -f it4200-api  # -f参数实时跟踪日志输出
   

5. 数据管理

5.1 数据持久化

通过-v ./api-data:/app/data挂载的目录包含以下关键数据：

• API配置文件（config.yaml）
• 用户作业数据（submissions/目录）
• 运行日志（若未单独挂载LOG_PATH）
• 数据库文件（若使用文件型数据库如SQLite）

注意：删除容器时，若需保留数据，请勿使用docker rm -v（-v会删除挂载卷）。

5.2 数据备份

定期备份挂载的./api-data目录：

bash
tar -czf api-data-backup-$(date +%Y%m%d).tar.gz ./api-data

6. 常见问题解决

6.1 端口冲突

若启动时提示"Bind for 0.0.0.0:8080 failed"，表示主机8080端口已被占用，解决方案：

• 更换主机端口，如映射到8081端口：-p 8081:8080
• 停止占用8080端口的进程：lsof -i:8080找到进程ID后kill -9 [PID]

6.2 服务启动失败

1. 检查日志定位错误原因：

   bash
   docker logs it4200-api
   

2. 常见失败原因：
   • 端口被占用（见6.1节）
   • 挂载目录权限不足：确保主机./api-data目录有读写权限，可执行chmod 755 ./api-data
   • 环境变量配置错误：如DB_CONN_STR格式不正确

6.3 镜像更新

当课程API有版本更新时，重新拉取/构建镜像并重启容器：

bash
# 停止并删除旧容器
docker stop it4200-api && docker rm it4200-api

# 拉取新镜像（若从Registry获取）
docker pull [registry-url]/it4200-class-api:2024-fall

# 重新启动容器（使用原参数）
docker run -d [原有参数] it4200-class-api:2024-fall

6. 注意事项

• 课程结束后，若需清理环境，执行docker rm -f it4200-api && docker rmi it4200-class-api:2024-fall
• 敏感配置（如数据库密码）建议通过环境变量注入，避免硬编码在镜像中
• 若API依赖外部服务（如数据库、消息队列），需在docker-compose.yml中添加对应服务配置并通过DB_CONN_STR等变量关联

7. 联系方式

若使用中遇到问题，可联系课程助教或通过课程LMS平台提交工单。