placement/python3.7-nodejs12-base

HypeTrain 全栈应用 Docker 镜像文档

镜像概述

HypeTrain 是一个功能丰富的全栈 Web 应用容器化解决方案。该镜像及配套的 Docker Compose 配置封装了基于 Django 的后端服务、基于 Node.js/Yarn 的前端构建环境，并无缝集成了 PostgreSQL (含 PostGIS 扩展)、Redis、Elasticsearch 以及 Celery 分布式任务队列。它旨在为开发者提供开箱即用的生产级部署架构与标准化的本地开发环境。

核心功能与特性

• 全栈架构支持：后端采用 Python/Django，前端支持 Node.js 生态及 MJML 邮件模板渲染。
• 空间与全文检索：深度集成 PostGIS 进行地理空间数据计算，结合 Elasticsearch 实现高性能全文检索与数据同步。
• 异步任务调度：内置 Celery Worker 与 Celery Beat，支持复杂的后台异步任务与周期性定时任务。
• NLP 能力：预装 spaCy 及 en_core_web_sm 语言模型，支持自然语言处理任务。
• 数据工程脚本：内置 COLI（生活成本指数）季度数据处理与映射构建脚本。
• 代码质量保障：开发环境支持 pre-commit hooks，集成 ESLint、Prettier、Black、isort 和 Flake8 等代码格式化工具。

使用场景和适用范围

• 与数据分析平台：适用于需要集成 Plaid 等 API 并进行生活成本指数 (COLI) 数据分析的业务场景。
• 地理信息系统 (GIS) 应用：依赖 PostGIS 进行位置服务、区域划分和空间查询的 Web 应用。
• 复杂企业级后端：需要处理高并发异步任务、定时调度以及海量数据全文检索的中大型项目。

环境变量配置

在部署前，请在项目根目录创建 .env 文件，并配置以下核心环境变量：

env
# Django 核心配置
DJANGO_READ_DOT_ENV_FILE=1
DJANGO_SECRET_KEY=your_secure_secret_key
DJANGO_ALLOWED_HOSTS=localhost,127.0.0.1,yourdomain.com

# 数据库配置 (对应 docker-compose 中的 postgres 服务)
DATABASE_URL=postgis://hyped_user:hyped_password@db:5432/hyped

# Redis 配置
REDIS_URL=redis://redis:6379/0

# Elasticsearch 配置
ELASTICSEARCH_URL=http://elasticsearch:9200

# 第三方 API 密钥
PLAID_SECRET=your_plaid_secret_key

# Celery 配置 (生产环境必须设为 False 以启用异步)
CELERY_TASK_ALWAYS_EAGER=False

Docker Compose 部署示例

以下是完整的 docker-compose.yml 配置文件，用于一键启动所有依赖服务与应用容器：

yaml
version: '3.8'

services:
  db:
    image: docker.xuanyuan.run/postgis/postgis:14-3.2
    environment:
      POSTGRES_USER: hyped_user
      POSTGRES_PASSWORD: hyped_password
      POSTGRES_DB: hyped
    volumes:
      - postgres_data:/var/lib/postgresql/data
    ports:
      - "5432:5432"

  redis:
    image: docker.xuanyuan.run/redis:7-alpine
    ports:
      - "6379:6379"

  elasticsearch:
    image: ***-elastic.xuanyuan.run/elasticsearch/elasticsearch:7.17.9
    environment:
      - discovery.type=single-node
      - "ES_JAVA_OPTS=-Xms512m -Xmx512m"
    volumes:
      - es_data:/usr/share/elasticsearch/data
    ports:
      - "9200:9200"

  app:
    build: .
    command: python manage.py runserver 0.0.0.0:8000
    volumes:
      - .:/app
    ports:
      - "8000:8000"
    env_file:
      - .env
    depends_on:
      - db
      - redis
      - elasticsearch

  worker:
    build: .
    command: celery -A hypetrain worker --loglevel=info -n worker1
    volumes:
      - .:/app
    env_file:
      - .env
    depends_on:
      - db
      - redis

  beat:
    build: .
    command: celery -A hypetrain beat --loglevel=info
    volumes:
      - .:/app
    env_file:
      - .env
    depends_on:
      - db
      - redis

volumes:
  postgres_data:
  es_data:

常用运维与管理命令

以下命令均假设您已使用 docker-compose up -d 启动了服务。

1. 数据库与基础初始化

bash
# 执行数据库迁移
docker-compose exec app python manage.py migrate

# 运行项目测试
docker-compose exec app python manage.py test

2. Elasticsearch 索引管理

bash
# 创建索引
docker-compose exec app python manage.py search_index --create

# 并行填充数据库数据到 ES
docker-compose exec app python manage.py search_index --populate --parallel

# 删除并重建索引（慎用）
docker-compose exec app python manage.py search_index --rebuild --parallel

# 增量同步新记录到 ES
docker-compose exec app python manage.py search_index --sync --parallel

3. COLI (生活成本指数) 数据管理

1. 将季度 CSV 数据文件放入挂载目录：hypetrain/main/data/coli/quartery_data/year-quarter.csv
2. 构建映射数据：

   bash
   docker-compose exec app python manage.py runscript build_county_to_coli_map
   

3. 检查 hypetrain/main/data/coli/logs 中的日志，并提交生成的 county-to-coli.json。
4. 在生产环境中更新数据库中的 COLI 数据：

   bash
   docker-compose exec app python manage.py runscript update_coli
   

4. 前端构建 (Node/Yarn)

若需在容器内执行前端构建或安装依赖：

bash
# 安装前端依赖
docker-compose exec app yarn install

# 构建前端资源 (具体命令参考 frontend/README.md)
docker-compose exec app yarn build