justfixnyc/nycdb-k8s-loader

nycdb-k8s-loader 镜像文档

镜像概述和主要用途

本镜像用于探索通过Kubernetes任务或Amazon Fargate填充https://github.com/aepyornis/nyc-db%E5%AE%9E%E4%BE%8B%E7%9A%84%E5%8F%AF%E8%83%BD%E6%80%A7%E3%80%82%E5%AE%83%E6%8F%90%E4%BE%9B%E4%BA%86%E5%AE%B9%E5%99%A8%E5%8C%96%E7%9A%84NYC-DB%E6%95%B0%E6%8D%AE%E9%9B%86%E5%8A%A0%E8%BD%BD%E6%96%B9%E6%A1%88%EF%BC%8C%E9%80%82%E7%94%A8%E4%BA%8E%E9%9C%80%E8%A6%81%E9%83%A8%E7%BD%B2%E5%92%8C%E7%BB%B4%E6%8A%A4NYC-DB%E5%AE%9E%E4%BE%8B%E7%9A%84%E5%9C%BA%E6%99%AF%E3%80%82

核心功能和特性

• 容器化便利性：对熟悉容器化技术的开发者更友好，无需学习VPS或Ansible等部署工具
• 环境一致性：确保开发环境与生产环境一致
• 并行处理能力：可在多台机器上并行处理工作负载，提升数据库填充速度
• 定时更新支持：通过Kubernetes定时任务或Amazon Fargate计划任务实现NYC-DB实例持续更新
• 管理便捷性：Kubernetes仪表板提供直观UI，便于任务状态监控和管理

使用场景和适用范围

• 熟悉容器化技术的开发者部署NYC-DB实例
• 需要定时更新NYC-DB数据集的场景
• 追求开发/生产环境一致性的团队
• 需要通过并行处理提升数据集加载速度的场景
• 希望利用Kubernetes或AWS Fargate管理NYC-DB维护任务的用户

使用方法和配置说明

环境准备

需安装Docker。

首先，复制示例环境变量文件创建.env：

bash
cp .env.example .env     # Windows系统使用: copy .env.example .env

编辑.env文件，根据需求修改环境变量配置。

开发环境设置

通过Docker Compose可便捷搭建开发环境，自动配置Postgres服务器：

bash
docker-compose run app bash

进入容器后，可开发和运行load_dataset.py脚本。/app目录挂载本地仓库根目录，文件修改会实时同步到容器环境。

部署方式

Kubernetes部署

1. 准备Kubernetes集群
   本地可通过Docker Desktop启用Kubernetes，建议部署Kubernetes仪表板UI便于任务监控。

2. 构建容器镜像

   bash
   docker-compose build
   

3. 生成Kubernetes任务文件

   bash
   docker-compose run app python k8s_build_jobs.py
   

   生成的任务文件会使用.env中定义的环境变量。

4. 启动Kubernetes任务

   bash
   kubectl create -f ./k8s-jobs
   

   通过Kubernetes仪表板的"任务"部分查看任务状态。

5. 停止或清理任务

   bash
   kubectl delete -f ./k8s-jobs
   

Amazon Fargate部署

可将容器部署为Amazon Fargate任务，支持计划任务。部署指南：

• 任务定义：容器镜像使用https://hub.docker.com/r/justfixnyc/nycdb-k8s-loader%EF%BC%8C%E6%8C%89%60.env.example%60%E9%85%8D%E7%BD%AE%E7%8E%AF%E5%A2%83%E5%8F%98%E9%87%8F%E3%80%82

• 网络配置：运行任务时需将"Auto-assign public IP"设为ENABLED（容器需访问外部网络，详见https://github.com/aws/amazon-ecs-agent/issues/1128#issuecomment-351545461%EF%BC%89%E3%80%82

• VPC和安全组：确保数据库实例在VPC中可访问，RDS实例安全组入站规则需允许容器IP范围访问（默认安全组可能名为rds-launch-wizard）。

• 计划任务配置：使用aws_schedule_tasks.py脚本配置定期加载数据集的计划任务。

注意：目前Fargate不支持查看任务级CPU/内存使用率（https://github.com/aws/amazon-ecs-agent/issues/565%EF%BC%89%EF%BC%8C%E4%B8%94%E6%97%A0%E6%B3%95%E4%BD%BF%E7%94%A8SSM%E5%8F%82%E6%95%B0%E5%AD%98%E5%82%A8%E4%BD%9C%E4%B8%BA%E5%AF%86%E9%92%A5%E5%AD%98%E5%82%A8%EF%BC%88https://github.com/aws/amazon-ecs-agent/issues/1209%EF%BC%89%EF%BC%8C%E9%9C%80%E6%98%8E%E6%96%87%E6%8C%87%E5%AE%9A%E6%95%B0%E6%8D%AE%E5%BA%93URL%E3%80%82

其他系统部署

容器通过环境变量配置，详细参数见.env.example。

工作原理

数据集URL通常包含ETag和Last-Modified元数据，加载器利用这些信息判断数据集是否更新：若未变更，则不重复下载和加载。可通过dbtool.py lastmod:reset命令重置数据集的最后修改元数据。

加载流程：下载更新的数据集→创建临时Postgres schema→加载数据到临时schema→删除公共schema中旧表→将临时schema表移至公共schema。临时schema确保加载过程不影响用户查询。

其他工具

dbtool.py工具提供数据库状态查询和修改功能。

测试

运行测试套件：

bash
docker-compose run app pytest

更新NYC-DB版本

Dockerfile中通过NYCDB_REV参数指定NYC-DB Python库的GitHub提交哈希。更新步骤：修改Dockerfile中NYCDB_REV默认值→提交PR→CI验证通过后合并至master分支→Docker Hub自动发布新镜像。

更新Who Owns What数据

镜像包含wowutil.py工具，用于创建和更新https://github.com/justfixnyc/who-owns-what%EF%BC%88WoW%EF%BC%89%E6%89%80%E9%9C%80%E7%9A%84NYCDB%E6%B4%BE%E7%94%9F%E8%A1%A8%E5%92%8C%E5%87%BD%E6%95%B0%EF%BC%9A

• WoW表和函数创建在wow Postgres schema中，需将Postgres schema搜索路径设为wow, public以确保WoW函数正常工作。

• 需手动确保运行wowutil.py时，数据库中已存在WoW数据依赖的NYCDB数据集。

• Dockerfile中WOW_REV参数指定wowutil.py使用的WoW版本。

• 替代方式：通过load_dataset.py工具加载wow数据集（相当于wowutil.py build的快捷方式）。