6 · 开发与操作（Development & Operations）

企业电子文档治理 · 本章是 Mayan EDMS DeepWiki 中文译文的独立章节页，保留原始链接、源码锚点、模块标签和章节层级。

项目Mayan EDMS 章节6 状态全文译文模块测试、发布与运维、工作流与编排、配置治理、文档对象与元数据

项目要点页2.5 参考项目项目章节目录Mayan EDMS DeepWiki 原始章节Development & Operations 上一章5.2 下一章6.1

源码线索

.gitlab-ci.yml
HISTORY.rst
Makefile
config.env
docker/Makefile
docker/rootfs/version
docs/parts/troubleshooting/static_files.txt
mayan/__init__.py
mayan/apps/appearance/management/commands/appearance_prepare_static.py
mayan/apps/common/dependencies.py

模块标签

测试、发布与运维
工作流与编排
配置治理
文档对象与元数据
安装与启动

中文译文

开发与操作（中文译文）

原始 DeepWiki 页面：https://deepwiki.com/mayan-edms/Mayan-EDMS/6-development-and-operations

翻译时间：2026-05-27T08:44:31.486Z

翻译模型：deepseek-chat

原文字符数：15181

项目：Mayan EDMS (mayan-edms)

--- 好的，作为一名资深技术文档翻译专家，我将严格遵循您的要求，将这份 DeepWiki 技术文档全文翻译为中文，并进行专业润色。

---

开发与运维

开发环境搭建

本地开发基础设施

Mayan EDMS 通过 Make 目标和 Docker 容器提供了全面的开发环境。开发环境支持多种数据库后端和服务依赖。

graph TB
    subgraph "开发环境"
        DEV_SETUP["setup-dev-environment"] --> OS_PACKAGES["setup-dev-operating-system-packages"]
        DEV_SETUP --> PYTHON_LIBS["setup-dev-python-libraries"]

        OS_PACKAGES --> SYSTEM_DEPS["系统依赖<br/>exiftool, gcc, tesseract-ocr<br/>graphviz, libreoffice"]
        PYTHON_LIBS --> DEV_DEPS["开发依赖<br/>requirements/development.txt"]
    end

    subgraph "服务容器"
        POSTGRES_DEV["docker-postgresql-start<br/>mayan-development-postgres<br/>端口: 5432"]
        REDIS_DEV["docker-redis-start<br/>mayan-development-redis<br/>端口: 6379"]
        RABBITMQ_DEV["docker-rabbitmq-start<br/>mayan-development-rabbitmq<br/>端口: 5672"]
    end

    subgraph "开发命令"
        RUNSERVER["runserver<br/>./manage.py runserver<br/>--settings=mayan.settings.development"]
        MANAGE_CMD["manage<br/>./manage.py --settings=development"]
        SHELL_PLUS["shell-plus<br/>django-extensions shell"]
    end

    DEV_SETUP --> RUNSERVER
    POSTGRES_DEV --> RUNSERVER
    REDIS_DEV --> RUNSERVER

开发环境使用特定的配置路径和设置模块：

来源: Makefile:512-534, config.env:1-74, requirements/development.txt:1-11

特定数据库的开发

Mayan EDMS 支持多种数据库后端用于开发和测试：

后端	容器	连接设置	Make 目标
PostgreSQL	`mayan-development-postgres`	端口 5432，用户/密码: postgres	`manage-with-postgresql`
MySQL	`mayan-test-mysql`	端口 3306，可配置凭据	`manage-with-mysql`
Oracle	`mayan-test-oracle`	端口 49161，测试容器	`manage-with-oracle`
SQLite	内置	基于文件，无需容器	默认开发

来源: Makefile:377-390, Makefile:412-449, config.env:7-9

构建系统与打包

Python 包构建流程

构建系统采用多阶段方法来创建可分发的包：

graph LR
    subgraph "构建依赖"
        BUILD_REQS["requirements/build.txt<br/>packaging, twine, wheel"]
    end

    subgraph "源码生成"
        SETUP_PY["setup.py<br/>包元数据<br/>查找包"]
        GENERATE_SETUP["generate-setup<br/>更新 setup.py"]
        REQUIREMENTS_GEN["generate-requirements<br/>创建所有需求文件"]
    end

    subgraph "构建目标"
        SDIST["python-sdist<br/>源码分发包<br/>python setup.py sdist"]
        WHEEL["python-wheel<br/>Wheel 分发包<br/>pip wheel --no-deps"]
    end

    subgraph "制品"
        DIST_DIR["dist/<br/>mayan-edms-*.tar.gz<br/>mayan_edms-*.whl"]
    end

    BUILD_REQS --> SDIST
    BUILD_REQS --> WHEEL
    SETUP_PY --> SDIST
    GENERATE_SETUP --> SETUP_PY
    REQUIREMENTS_GEN --> BUILD_REQS
    SDIST --> DIST_DIR
    WHEEL --> DIST_DIR

setup.py 文件会动态发现包并管理依赖：

来源: setup.py:119-160, Makefile:285-298, requirements/build.txt:1-4

Docker 构建系统

Docker 构建流程使用多阶段构建，并配合平台模板：

graph TB
    subgraph "模板系统"
        PLATFORM_TMPL["platform/docker/dockerfile.tmpl"]
        CONFIG_ENV["config.env<br/>构建变量"]
        DOCKERFILE_UPDATE["docker-dockerfile-update<br/>./manage.py platformtemplate"]
    end

    subgraph "构建阶段"
        BASE_IMAGE["base_image<br/>debian:11.4-slim<br/>基础操作系统包"]
        BUILDER_IMAGE["builder_image<br/>Python 构建环境<br/>编译依赖"]
        FINAL_IMAGE["最终镜像<br/>运行时环境<br/>已安装 Mayan EDMS"]
    end

    subgraph "构建目标"
        DOCKER_BUILD["docker-build<br/>标准构建"]
        DOCKER_BUILD_PROXY["docker-build-with-proxy<br/>支持 APT/PIP 代理"]
    end

    CONFIG_ENV --> DOCKERFILE_UPDATE
    PLATFORM_TMPL --> DOCKERFILE_UPDATE
    DOCKERFILE_UPDATE --> BASE_IMAGE
    BASE_IMAGE --> BUILDER_IMAGE
    BUILDER_IMAGE --> FINAL_IMAGE
    DOCKER_BUILD --> FINAL_IMAGE
    DOCKER_BUILD_PROXY --> FINAL_IMAGE

来源: docker/Makefile:15-34, mayan/apps/platform/templates/platform/docker/dockerfile.tmpl:1-204, config.env:20-34

版本管理

版本信息集中管理，并在整个系统中传播：

来源: mayan/__init__.py:1-13, docker/rootfs/version:1-2, Makefile:179-185

测试框架

测试执行基础设施

Mayan EDMS 提供了全面的测试能力，支持多种数据库后端和部署场景：

graph TB
    subgraph "测试配置"
        TEST_COMMAND["TEST_COMMAND<br/>./manage.py test $(MODULE)<br/>--settings=$(SETTINGS) $(SKIPMIGRATIONS)"]
        SETTINGS_FILE["mayan.settings.testing.development<br/>默认测试设置"]
    end

    subgraph "测试类型"
        UNIT_TESTS["test / test-all<br/>应用测试<br/>MODULE=--mayan-apps"]
        MIGRATION_TESTS["test-all-migrations<br/>迁移测试<br/>--tag=migration_test"]
        DEBUG_TESTS["test-debug<br/>调试模式测试<br/>--debug-mode"]
    end

    subgraph "数据库测试"
        SQLITE_TEST["SQLite 测试<br/>默认本地测试"]
        POSTGRES_TEST["PostgreSQL 测试<br/>test-with-postgresql<br/>基于容器"]
        MYSQL_TEST["MySQL 测试<br/>test-with-mysql<br/>基于容器"]
    end

    TEST_COMMAND --> UNIT_TESTS
    TEST_COMMAND --> MIGRATION_TESTS
    SETTINGS_FILE --> UNIT_TESTS
    UNIT_TESTS --> SQLITE_TEST
    UNIT_TESTS --> POSTGRES_TEST
    UNIT_TESTS --> MYSQL_TEST

测试数据库容器

测试基础设施使用专用的 Docker 容器进行数据库测试：

数据库	容器名称	镜像	端口	用途
PostgreSQL	`mayan-test-postgresql`	`postgres:12.11-alpine`	5432	集成测试
MySQL	`mayan-test-mysql`	`mysql:8.0`	3306	跨数据库兼容性
Redis	`mayan-test-redis`	`redis:6.2-alpine`	6379	缓存/消息代理测试
Elasticsearch	`mayan-test-elastic`	`elasticsearch:7.17.0`	9200	搜索后端测试

来源: Makefile:46-114, Makefile:403-458, config.env:26-34

覆盖率与质量保证

测试覆盖率和代码质量工具已集成到开发工作流中：

来源: Makefile:129-136, requirements/testing-base.txt:1-7

持续集成与持续交付管线架构

GitLab CI 管线结构

CI/CD 管线通过平台模板定义，提供全面的自动化能力：

graph LR
    subgraph "管线阶段"
        STAGE_TEST["stage_test<br/>• PostgreSQL 测试<br/>• SQLite 测试<br/>• 升级测试"]
        STAGE_BUILD_PY["stage_build_python<br/>• Python wheel<br/>• 源码分发包"]
        STAGE_BUILD_DOCKER["stage_build_docker<br/>• 多架构构建<br/>• 测试执行"]
        STAGE_BUILD_DOCS["stage_build_documentation<br/>• Sphinx 文档<br/>• HTML 生成"]
    end

    subgraph "推送阶段"
        STAGE_PUSH_PY["stage_push_python<br/>• PyPI 上传<br/>• 测试 PyPI"]
        STAGE_PUSH_DOCKER["stage_push_docker<br/>• Docker Hub<br/>• 版本标签"]
        STAGE_PUSH_DOCS["stage_push_documentation<br/>• 文档站点<br/>• SSH 部署"]
    end

    subgraph "部署"
        STAGE_DEPLOY["stage_deploy<br/>• 演示环境<br/>• 预发布环境"]
    end

    STAGE_TEST --> STAGE_BUILD_PY
    STAGE_TEST --> STAGE_BUILD_DOCKER
    STAGE_TEST --> STAGE_BUILD_DOCS
    STAGE_BUILD_PY --> STAGE_PUSH_PY
    STAGE_BUILD_DOCKER --> STAGE_PUSH_DOCKER
    STAGE_BUILD_DOCS --> STAGE_PUSH_DOCS
    STAGE_PUSH_PY --> STAGE_DEPLOY
    STAGE_PUSH_DOCKER --> STAGE_DEPLOY

CI 作业模板与继承

管线使用 YAML 锚点和作业模板来实现代码复用：

来源: .gitlab-ci.yml:1-431, mayan/apps/platform/templates/platform/gitlab-ci.tmpl:1-431

基于分支的发布策略

不同的发布类型会触发特定的管线行为：

分支模式	触发的作业	制品
`releases/all_major`	完整管线，主版本标签	Python, Docker, 文档
`releases/all_minor`	完整管线，次版本标签	Python, Docker
`releases/testing`	测试构建	测试制品
`releases/nightly`	每日构建	开发镜像
`tests/*`	仅执行测试	测试报告

来源: .gitlab-ci.yml:29-35, .gitlab-ci.yml:300-373

发布管理

版本控制与标签

版本管理遵循语义化版本规范，并实现自动化传播：

graph LR
    subgraph "版本来源"
        MAYAN_INIT["mayan/__init__.py<br/>__version__ = '4.3.1'<br/>__build__ = 0x040301"]
        DOCKER_VERSION["docker/rootfs/version<br/>4.3.1"]
    end

    subgraph "版本命令"
        INCREASE_VERSION["increase-version<br/>PART={major|minor|patch}<br/>更新所有版本文件"]
        VERSION_SCRIPT["contrib/scripts/increase_version.py<br/>版本操作逻辑"]
    end

    subgraph "自动更新"
        SETUP_GENERATION["generate-setup<br/>更新 setup.py 元数据"]
        DOCKER_TAGS["Docker 标签生成<br/>v4.3.1, latest, s4, s4.3"]
    end

    MAYAN_INIT --> INCREASE_VERSION
    VERSION_SCRIPT --> INCREASE_VERSION
    INCREASE_VERSION --> DOCKER_VERSION
    INCREASE_VERSION --> SETUP_GENERATION
    DOCKER_VERSION --> DOCKER_TAGS

发布工作流集成

GitLab 发布分支会触发自动化流程：

来源: Makefile:179-185, mayan/__init__.py:1-5, Makefile:299-350

升级与迁移支持

系统提供了自动化的升级能力：

来源: .gitlab-ci.yml:282-343, mayan/apps/platform/templates/platform/docker/entrypoint.tmpl:36-39

部署策略

基于 Docker 的部署

主要的部署方法使用 Docker，并提供了全面的配置选项：

graph TB
    subgraph "容器入口点"
        ENTRYPOINT_SH["entrypoint.sh<br/>从平台模板生成"]
        INITIAL_SETUP["initial_setup()<br/>common_initial_setup --force"]
        PERFORM_UPGRADE["perform_upgrade()<br/>common_perform_upgrade"]
        MAKE_READY["make_ready()<br/>设置或升级逻辑"]
    end

    subgraph "运行时命令"
        RUN_ALL["run_all<br/>完整应用栈"]
        RUN_FRONTEND["run_frontend<br/>仅 Web 界面"]
        RUN_WORKER["run_worker<br/>Celery 工作者"]
        RUN_CELERY["run_celery<br/>自定义 Celery 配置"]
    end

    subgraph "配置"
        ENV_VARS["环境变量<br/>MAYAN_DATABASES<br/>MAYAN_CELERY_BROKER_URL<br/>MAYAN_SETTINGS_MODULE"]
        CONFIG_ENV_FILE["config.env<br/>默认值"]
    end

    ENTRYPOINT_SH --> MAKE_READY
    MAKE_READY --> INITIAL_SETUP
    MAKE_READY --> PERFORM_UPGRADE
    ENTRYPOINT_SH --> RUN_ALL
    ENTRYPOINT_SH --> RUN_FRONTEND
    ENTRYPOINT_SH --> RUN_WORKER
    ENV_VARS --> ENTRYPOINT_SH
    CONFIG_ENV_FILE --> ENV_VARS

开发与预发布环境

多个部署目标支持不同的使用场景：

来源: mayan/apps/platform/templates/platform/docker/entrypoint.tmpl:1-203, docker/Makefile:79-153, Makefile:462-477

配置管理

特定环境的配置通过多层机制进行管理：

配置层级	文件	用途
默认值	`config.env`	构建时默认值
Docker 环境	`entrypoint.sh`	运行时配置
设置模块	`mayan.settings.*`	应用配置
用户覆盖	环境变量	部署特定覆盖

来源: config.env:1-74, mayan/settings/literals.py:1-63

这套开发与运维基础设施为在各种环境和用例中构建、测试和部署 Mayan EDMS 提供了坚实的基础。