cleolabs/python

cleo-backend 镜像文档

镜像概述和主要用途

cleo-backend是Lucy应用的Web后端组件，包含移动应用调用的API服务、系统对象管理仪表板、用户注册激活表单以及专家门户（当前仅提供发票审核页面）。该镜像旨在为Lucy应用提供完整的后端支持，需配合PostgreSQL数据库和Redis缓存服务运行。

核心功能和特性

• 多模块集成：包含API服务、管理仪表板、用户激活表单和专家门户四大功能模块
• 地理空间支持：集成GeoDjango contrib模块，依赖GEOS、PROJ.4和GDAL地理空间库
• 依赖管理：使用Pipenv进行Python依赖管理，确保开发环境一致性
• 容器化部署：支持通过Docker Compose快速部署PostgreSQL和Redis等依赖服务
• CI/CD支持：提供CircleCI自定义镜像，满足持续集成需求

使用场景和适用范围

• Lucy应用后端服务的开发与部署
• 本地开发环境快速搭建
• 系统测试与功能验证
• 持续集成/持续部署流程集成

详细使用方法和配置说明

环境要求

• Python 3.7.1
• Pipenv
• 地理空间库（GEOS、PROJ.4、GDAL）
• Docker（可选，用于部署PostgreSQL和Redis）
• PostgreSQL 10（如不使用Docker）
• Redis 4（如不使用Docker）
• Xcode
• Aptible CLI

安装步骤

1. 安装地理空间库

GeoDjango依赖GEOS、PROJ.4和GDAL系统库，macOS可通过Homebrew安装：

bash
$ brew install gdal

该命令会自动安装所有必需的地理空间依赖库。

2. 安装Python和Pipenv

在macOS上使用Homebrew安装Python：

bash
$ brew install python

安装Pipenv依赖管理工具：

bash
$ pip3 install pipenv
$ pipenv install

Pipenv会根据Pipfile创建虚拟环境并安装所有项目依赖。

openssl编译错误解决： 若出现ld: library not found for -lssl错误，需设置编译器标志：

bash
export LDFLAGS="-L/usr/local/opt/openssl/lib"
export CPPFLAGS="-I/usr/local/opt/openssl/include"

3. 部署PostgreSQL和Redis

推荐使用Docker Compose快速启动依赖服务：

bash
# 前台运行服务
$ docker-compose up

# 后台运行服务
$ docker-compose up -d

如需本地安装，参考https://github.com/startwithlucy/lucy/wiki/Environment-Setup---Django-and-Postgres%E3%80%82

4. 配置Xcode和Apple开发者账户

1. 从App Store安装Xcode
2. 使用Apple ID登录Apple开发者网站
3. 按照指南将账户添加到Xcode
4. 将账户提供给Cleo工程负责人以加入开发团队

5. 安装Aptible CLI

bash
$ brew cask install aptible

配置与启动

环境变量配置

复制示例配置文件创建.env：

bash
$ cp .env.example .env

使用Docker部署时配置无需修改；本地部署需调整数据库和Redis连接参数。

数据库设置（本地PostgreSQL）

创建数据库管理员用户：

bash
$ psql -c "CREATE USER admin WITH PASSWORD 'admin'; ALTER ROLE admin SUPERUSER;"

创建数据库：

bash
$ createdb -h localhost --username admin lucy

更新本地数据库数据，参考https://github.com/startwithlucy/cleo-backend/wiki/Development:-Update-Local-Data%E3%80%82

创建超级用户（用于登录管理仪表板）：

bash
$ pipenv run python3 manage.py createsuperuser

启动应用：

bash
$ pipenv run python3 manage.py runserver

常用命令

• pipenv run <command>：在虚拟环境中执行命令
• pipenv shell：进入虚拟环境shell
• pipenv install：安装依赖包
• pipenv lock：生成依赖锁文件
• pipenv graph：查看依赖关系图
• python3 manage.py runserver：启动开发服务器
• docker-compose up [-d]：启动依赖服务（-d表示后台运行）
• docker-compose stop：停止服务（保留数据）
• docker-compose down：停止服务并删除数据卷

注意事项

• 静态资源缓存：开发模式下，浏览器可能缓存样式表，修改后需硬刷新（shift+cmd+r）更新；生产环境中样式表会被编译为带指纹的唯一文件，自动避免缓存问题。

CircleCI配置

cleo-backend需要地理空间库等自定义依赖，提供CircleCI专用Docker镜像。Dockerfile位于：

.circleci/images/Dockerfile

当Python或依赖库升级时，需重新构建并推送镜像：

bash
# 构建镜像
docker build . -t cleolabs/python:3.7.1

# 推送镜像
docker push cleolabs/python:3.7.1