podcast-server-backend Docker镜像文档

一、镜像概述和主要用途

本镜像是podcast-server应用的后端服务组件，负责处理核心业务逻辑、数据持久化、API服务提供及与前端/客户端的交互。作为播客服务器的核心，其主要用途包括：

• 提供播客内容管理的后端接口
• 处理用户数据、播客订阅及媒体文件元数据
• 实现业务逻辑层与数据存储层的交互

二、核心功能和特性

2.1 核心功能

• RESTful API服务：提供标准化的HTTP接口，支持播客查询、订阅、管理、用户操作等功能
• 数据持久化：支持与关系型数据库（如PostgreSQL、MySQL）集成，实现用户数据、播客元数据持久化
• 用户认证与授权：支持基于JWT的用户认证、角色权限管理（如管理员/普通用户）
• 播客订阅管理：处理播客源（RSS/Atom）的订阅、更新检测及内容同步
• 媒体文件元数据处理：解析音频文件元数据（时长、比特率、封面等）并存储

2.2 特性

• 轻量级部署：基于Alpine Linux构建，镜像体积小，资源占用低
• 可配置性强：通过环境变量灵活调整服务参数
• 扩展性支持：支持水平扩展，可与负载均衡器配合使用
• 日志标准化：支持JSON格式日志输出，便于集成监控工具（如Prometheus、ELK）

三、使用场景和适用范围

3.1 适用场景

• 个人播客服务器搭建：通过Docker快速部署个人播客管理后端，配合前端实现本地播客存储与播放
• 小型团队播客平台：支持多用户权限管理，适用于团队内部播客内容协作与分发
• 播客相关二次开发：作为后端服务基础，供开发者扩展自定义功能（如播客推荐、统计分析）

3.2 环境要求

• 运行环境：Docker Engine 20.10+
• 依赖服务：需配合关系型数据库（如PostgreSQL 13+、MySQL 8.0+）
• 网络：需暴露API端口（默认8080），支持HTTP/HTTPS

四、使用方法和配置说明

4.1 快速启动（docker run）

通过以下命令快速启动容器，需提前配置数据库环境：

bash
docker run -d \
  --name podcast-server-backend \
  -p 8080:8080 \
  -e SPRING_DATASOURCE_URL=jdbc:postgresql://db-host:5432/podcast_db \
  -e SPRING_DATASOURCE_USERNAME=podcast_user \
  -e SPRING_DATASOURCE_PASSWORD=secure_password \
  -e LOG_LEVEL=INFO \
  -v /host/data:/app/data \
  -v /host/logs:/app/logs \
  podcast-server-backend:latest

参数说明：

• -p 8080:8080：映射容器内API服务端口到宿主机
• -e：设置环境变量（详见4.3节配置参数）
• -v：挂载宿主机目录到容器，用于数据持久化（/app/data存储业务数据，/app/logs存储日志）

4.2 容器编排（docker-compose）

通过docker-compose.yml配置后端服务与依赖数据库的联动部署：

yaml
version: '3.8'

services:
  backend:
    image: podcast-server-backend:latest
    container_name: podcast-backend
    restart: always
    ports:
      - "8080:8080"
    environment:
      - SPRING_DATASOURCE_URL=jdbc:postgresql://db:5432/podcast_db
      - SPRING_DATASOURCE_USERNAME=podcast_user
      - SPRING_DATASOURCE_PASSWORD=secure_password
      - SERVER_PORT=8080
      - LOG_LEVEL=INFO
      - CORS_ALLOWED_ORIGINS=[***]
    volumes:
      - ./data:/app/data
      - ./logs:/app/logs
    depends_on:
      - db

  db:
    image: postgres:14-alpine
    container_name: podcast-db
    restart: always
    environment:
      - POSTGRES_DB=podcast_db
      - POSTGRES_USER=podcast_user
      - POSTGRES_PASSWORD=secure_password
    volumes:
      - postgres-data:/var/lib/postgresql/data

volumes:
  postgres-data:

启动命令：

bash
docker-compose up -d

4.3 配置参数（环境变量）

容器通过环境变量配置核心参数，常用参数如下表：

4.4 数据持久化

容器内以下目录需通过宿主机挂载实现数据持久化：

• /app/data：存储播客元数据、用户配置等业务数据
• /app/logs：存储应用运行日志（按日滚动）

挂载示例：

bash
-v /host/podcast/data:/app/data \
-v /host/podcast/logs:/app/logs

五、注意事项

1. 数据库依赖：必须配置外部数据库（不支持内置数据库），建议使用PostgreSQL以获得最佳兼容性
2. 权限配置：宿主机挂载目录需确保Docker用户有读写权限（可通过chmod 775 /host/data调整）
3. 安全建议：生产环境需修改默认JWT_SECRET，并通过HTTPS暴露服务（可配合Nginx反向代理实现）
4. 升级说明：升级镜像前建议备份/app/data目录数据，避免数据丢失

六、健康检查与日志

6.1 健康检查

容器内置健康检查接口，通过GET /actuator/health访问，返回状态UP表示服务正常。

6.2 日志查看

通过以下命令查看容器日志：

bash
docker logs -f podcast-server-backend

日志格式示例（INFO级别）：

2024-05-20 10:30:00.123  INFO 1 --- [main] c.p.backend.Application: Started Application in 5.234 seconds (JVM running for 5.890)
2024-05-20 10:30:05.678  INFO 1 --- [nio-8080-exec-1] c.p.backend.controller.PodcastController: User 'admin' fetched 10 podcasts