artcom/cheminova-backend

Cheminova后端

Cheminova网站的Wagtail CMS和API后端，提供以下功能：

• 支持图片的单“首页”页面
• 安全的图片上传和按请求授权
• 带渲染版本和实时页面跟踪的自定义图片模型
• 页面和图片的JSON API端点
• 基于Docker和Docker Compose的容器化开发与部署

目录

• 前提条件
• 安装
• 本地开发（Docker Compose）
• 运行测试
• 部署
• 数据库转储与S3备份
• 恢复数据库
• 图片上传流程
• 图片请求流程（带认证）
• 图片API请求流程（元数据）

前提条件

• uv
• Docker & Docker Compose（用于容器化工作流）

使用uv和invoke运行脚本

脚本定义在tasks.py中，可通过uv运行：

bash
uv run invoke $TASK_NAME

列出可用任务：

bash
uv run invoke --list

可用任务：

• admin-user：创建或更新管理员用户。
• bump：使用uv版本更新版本号并创建Git标签。
• clean-assets：删除数据库中未引用的媒体文件。
• dev：通过Docker Compose运行开发服务器。
• export-dump：转储数据库并导出到S3。
• format：使用ruff格式化代码。
• import-dump：从S3导入转储并加载到数据库。
• init-site：用给定URL初始化默认Wagtail站点。
• randomize-timestamps：随机化图片时间戳。
• remove-edit-history：从数据库中删除所有Wagtail编辑历史。
• sync-assets：在S3和本地存储之间同步静态和媒体资源。
• test：使用Django测试框架运行测试。

安装

克隆仓库：

bash
git clone https://github.com/artcom/cheminova-backend.git
cd cheminova-backend

本地开发（Docker Compose）

• 配置环境变量

  bash
  cp .env.example .env
  

  编辑.env设置所需变量。

• 配置Minio客户端

  bash
  cp config/mc/config.json.example config/mc/config.json
  

  编辑以设置不同环境的访问密钥和秘密密钥。

• 启动完整栈（Postgres、Wagtail、Nginx、Minio）

  bash
  uv run invoke dev
  

• 应用数据库迁移

  bash
  docker compose exec wagtail uv run manage.py migrate
  

• 创建超级用户

  bash
  uv run invoke admin-user --password $ADMIN_PASSWORD
  

• 创建默认站点

  bash
  uv run invoke init-site --site-url http://localhost
  

• 从实时环境导入站点数据（可选）

  从S3桶获取最新转储文件名。

  bash
  uv run invoke import-dump --file-name $LATEST_DUMP_FILENAME
  

• 从S3同步媒体资源（可选）

  bash
  uv run invoke sync-assets
  

• 将前端站点复制到frontend目录（可选）

  bash
  wget https://github.com/artcom/cheminova-frontend/releases/download/v1.0.7/cheminova-frontend-v1.0.7.tar.gz
  rm -rf frontend/*
  tar -xzf cheminova-frontend-v1.0.7.tar.gz -C frontend
  

• Wagtail运行于 http://localhost:8000/cms

• 前端运行于 http://localhost:8080/

• Wagtail CMS管理后台运行于 http://localhost:8080/cms/admin/

• 后端API运行于 http://localhost:8080/cms/api/

• Minio web UI运行于 http://localhost:9001/

运行测试

```bash
uv run invoke test
```

部署

1. 构建并推送Docker镜像。

2. 在生产环境中，确保设置以下环境变量： • SECRET_KEY • POSTGRES_DB、POSTGRES_USER、POSTGRES_PASSWORD、POSTGRES_HOST • （可选）如果在子路径下服务，设置BASE_PATH

3. production.py设置模块将配置： • 安全代理头 • CSRF信任源 • Wagtail管理后台基础URL

数据库转储与S3备份

bash
docker compose exec wagtail uv run manage.py export_dump

恢复数据库

选择S3桶中的转储文件。要从转储文件恢复数据库，可使用以下命令：

bash
docker compose exec wagtail uv run manage.py import_dump $DUMP_FILENAME

除非提供--no-restore-local-data标志，否则用户和站点数据将从本地数据库恢复。

图片上传流程

mermaid
sequenceDiagram
    participant Client
    participant nginx as nginx:8080
    participant wagtail as Wagtail:8000
    participant upload_view as image_upload.views
    participant serializer as ImageModelSerializer
    participant model as CustomImage Model
    participant db as PostgreSQL
    participant fs as File System

    Client->>nginx: POST /api/upload/<br/>(multipart/form-data with image)
    nginx->>wagtail: proxy_pass to wagtail:8000/api/upload/
    wagtail->>upload_view: upload_image_view(request)

    upload_view->>upload_view: Extract file from request.data
    upload_view->>upload_view: Generate UUID filename<br/>(original-{uuid}.ext)
    upload_view->>serializer: ImageModelSerializer(data={file, title})
    serializer->>serializer: validate()

    alt validation successful
        serializer->>model: CustomImage.objects.create()
        model->>db: INSERT image record
        model->>fs: Save image file to /media/original_images/
        model->>serializer: return created instance
        serializer->>upload_view: return serialized data
        upload_view->>wagtail: Response(data, status=201)
        wagtail->>nginx: HTTP 201 with image data
        nginx->>Client: HTTP 201 with image metadata
    else validation failed
        serializer->>upload_view: return errors
        upload_view->>wagtail: Response(errors, status=400)
        wagtail->>nginx: HTTP 400
        nginx->>Client: HTTP 400 with error details
    end

图片请求流程（带认证）

mermaid
sequenceDiagram
    participant Client
    participant nginx as nginx:8080
    participant wagtail as Wagtail:8000
    participant auth_view as image_auth.views
    participant model as CustomImage Model
    participant db as PostgreSQL
    participant fs as File System

    Client->>nginx: GET /media/images/some-image.jpg
    nginx->>nginx: auth_request /api/image-auth/

    nginx->>wagtail: GET /api/image-auth/<br/>(internal, X-Original-URI header)
    wagtail->>auth_view: check_permissions(request)

    alt user is authenticated
        auth_view->>wagtail: Response(200, "OK")
        wagtail->>nginx: HTTP 200
        nginx->>fs: serve file from /media/
        fs->>nginx: image file content
        nginx->>Client: HTTP 200 with image
    else user not authenticated
        auth_view->>auth_view: get_image_file(X-Original-URI)
        auth_view->>auth_view: get_image_type(image_path)

        alt image type is "rendition"
            auth_view->>model: RenditionModel.objects.get(file=path)
            model->>db: SELECT rendition
            db->>model: rendition record
            model->>auth_view: rendition.image
        else image type is "original"
            auth_view->>model: CustomImage.objects.get(file=path)
            model->>db: SELECT image
            db->>model: image record
            model->>auth_view: image
        end

        auth_view->>model: image.get_referenced_live_pages()
        model->>db: Query page references
        db->>model: live page references

        alt image has live page references
            model->>auth_view: [live_pages]
            auth_view->>wagtail: Response(200, "OK")
            wagtail->>nginx: HTTP 200
            nginx->>fs: serve file from /media/
            fs->>nginx: image file content
            nginx->>Client: HTTP 200 with image
        else no live page references
            model->>auth_view: []
            auth_view->>wagtail: Response(401, "Unauthorized")
            wagtail->>nginx: HTTP 401
            nginx->>Client: HTTP 401 Unauthorized
        end
    end

图片API请求流程（元数据）

mermaid
sequenceDiagram
    participant Client
    participant nginx as nginx:8080
    participant wagtail as Wagtail:8000
    participant api_view as custom_images.views
    participant serializer as CustomImageModelSerializer
    participant model as CustomImage Model
    participant db as PostgreSQL

    Client->>nginx: GET /api/images/<br/>(with Authorization header)
    nginx->>wagtail: proxy_pass to wagtail:8000/api/images/
    wagtail->>api_view: CustomImageViewSet.list(request)

    api_view->>api_view: Check IsAuthenticated permission

    alt user is authenticated
        api_view->>model: CustomImage.objects.all()
        model->>db: SELECT * FROM custom_images
        db->>model: image records

        loop for each image
            model->>serializer: CustomImageModelSerializer(image)
            serializer->>model: get_referenced_live_pages()
            model->>db: Query page references
            db->>model: live page references
            model->>serializer: live pages list
            serializer->>serializer: set 'live' field (len > 0)
            serializer->>api_view: serialized image data
        end

        api_view->>wagtail: Response with image list
        wagtail->>nginx: HTTP 200 with JSON
        nginx->>Client: HTTP 200 with image metadata
    else user not authenticated
        api_view->>wagtail: Response(401, "Unauthorized")
        wagtail->>nginx: HTTP 401
        nginx->>Client: HTTP 401 Unauthorized
    end