pcic/climate-explorer-backend

PCIC Climate Explorer Backend

镜像概述和主要用途

PCIC Climate Explorer Backend是太平洋气候影响联盟（PCIC）气候探索器的后端服务组件，基于Flask框架开发。主要用于处理气候数据相关的API请求，支持与PostgreSQL等数据库交互，提供数据查询、处理和集成功能，适用于气候数据研究、后端服务开发及多环境部署场景。

核心功能和特性

• 基于Flask框架，支持RESTful API接口开发
• 集成数据库访问功能，支持PostgreSQL和SQLite（通过MDDB_DSN配置）
• 提供开发服务器及热重载功能（FLASK_DEBUG=1）
• 支持环境变量配置，灵活调整数据库连接、端口等参数
• 容器化部署支持，确保开发、测试和生产环境一致性
• 包含完整测试体系，支持虚拟环境内测试及Docker容器测试

使用场景和适用范围

• 气候数据相关应用的后端服务开发与调试
• 多环境（开发、测试、生产）的快速部署
• 需要共享数据卷的多实例后端服务部署
• 气候数据API接口的功能测试与性能验证

详细的使用方法和配置说明

依赖项

系统依赖安装

bash
$ sudo apt-get install libpq-dev python-dev libhdf5-dev libnetcdf-dev libgdal-dev

GDAL环境变量配置

GDAL在安装Python包时无法正确获取库路径，需手动定义以下环境变量：

bash
$ export CPLUS_INCLUDE_PATH=/usr/include/gdal
$ export C_INCLUDE_PATH=/usr/include/gdal

开发环境设置

虚拟环境安装

使用Python 3的venv模块（不建议使用virtualenv，因其默认安装Python 2）。单元测试依赖datetime.timezone，该特性仅Python 3支持。

bash
$ python3 -m venv venv
$ source venv/bin/activate
(venv)$ pip install -U pip
(venv)$ pip install -i https://pypi.pacificclimate.org/simple/ -r requirements.txt
(venv)$ pip install -e .

运行开发服务器

可通过Flask命令行工具启动本地开发服务器（详见Flask CLI文档）。需设置环境变量FLASK_APP=ce.wsgi:app，可选设置FLASK_DEBUG=1启用代码热重载。

数据库连接串通过MDDB_DSN环境变量配置，默认值为postgresql://httpd_meta@monsoon.pcic.uvic.ca/pcic_meta。

bash
(venv)$ MDDB_DSN=postgresql://dbuser:dbpass@dbhost/dbname FLASK_APP=ce.wsgi:app flask run -p <端口号>

测试方法

虚拟环境内测试

bash
pip install pytest
py.test -v

使用Docker容器测试本地代码

bash
sudo docker run --rm -it -v ${PWD}:/app --name backend-test pcic/climate-explorer-backend bash -c "pip install pytest; py.test -v ce/tests"

使用Docker容器测试远程代码变更

bash
sudo docker run --rm -it --name backend-test pcic/climate-explorer-backend bash -c "apt-get update; apt-get install -yq git; git fetch; git checkout <commit-ish>; pip install pytest; py.test -v ce/tests"

Docker部署

构建镜像

bash
git clone https://github.com/pacificclimate/climate-explorer-backend
cd climate-explorer-backend
docker build -t climate-explorer-backend-image .

创建数据容器

建议创建独立的只读数据容器，供多个后端实例共享。可通过多个-v参数挂载不同位置的数据，确保文件路径与元数据库中定义一致。

bash
docker run --name ce_data -v /绝对路径/至/数据目录:/storage/data/:ro ubuntu 16.04

运行后端容器

bash
docker run -it -p <外部端口>:8000 \
           -e "MDDB_DSN=postgresql://dbuser:dbpassword@host/databasename" \
           --volumes-from ce_data \
           --name climate-explorer-backend \
           climate-explorer-backend-image

说明：

• 若不使用独立数据容器，可用-v /绝对路径/至/数据目录:/storage/data/替换--volumes-from ce_data
• 如需使用测试数据，可设置-e "MDDB_DSN=sqlite:////app/ce/tests/data/test.sqlite"

版本发布流程

创建版本化发布需执行以下步骤：

1. 在setup.py中更新__version__版本号
2. 在NEWS.md中总结自上次发布后的变更
3. 提交变更并打标签：

bash
git add setup.py NEWS.md
git commit -m"Bump to version x.x.x"
git tag -a -m"x.x.x" x.x.x
git push --follow-tags