agentic_huge_data_base / wiki
页面 Mayan EDMS · 6.1 开发设置·DeepWiki 中文全文译文
DeepWiki 中文译文 / Mayan EDMS / 6.1

6.1 · 开发设置（Development Setup）

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

项目Mayan EDMS 章节6.1 状态全文译文 模块测试、发布与运维、配置治理、系统架构、安装与启动
项目要点页2.5 参考项目 项目章节目录Mayan EDMS DeepWiki 原始章节Development Setup 上一章6 下一章6.2
源码线索
  • .gitlab-ci.yml
  • .tx/config
  • Makefile
  • config.env
  • contrib/scripts/copy_config_env.py
  • contrib/scripts/password_randomizer.py
  • contrib/scripts/translations_helper.py
  • contrib/settings/ldap_connection_settings.py
  • docker/.env
  • docker/Makefile
模块标签
  • 测试、发布与运维
  • 配置治理
  • 系统架构
  • 安装与启动
  • 存储与持久化

中文译文

开发设置（中文译文）

原始 DeepWiki 页面：https://deepwiki.com/mayan-edms/Mayan-EDMS/6.1-development-setup
翻译时间：2026-05-27T08:44:37.529Z
翻译模型：deepseek-chat
原文字符数：18124
项目：Mayan EDMS (mayan-edms)

---

开发环境搭建

相关源文件

以下文件用于生成此维基页面：

  • .gitlab-ci.yml
  • .tx/config
  • Makefile
  • config.env
  • contrib/scripts/copy_config_env.py
  • contrib/scripts/password_randomizer.py
  • contrib/scripts/translations_helper.py
  • contrib/settings/ldap_connection_settings.py
  • docker/.env
  • docker/Makefile
  • docker/docker-compose.yml
  • docker/stack.yml
  • docs/parts/troubleshooting/static_files.txt
  • mayan/apps/appearance/management/commands/appearance_prepare_static.py
  • mayan/apps/authentication/dependencies.py
  • mayan/apps/cabinets/migrations/0001_initial.py
  • mayan/apps/common/management/base.py
  • mayan/apps/common/tests/test_management_commands.py
  • mayan/apps/mailer/locale/en/LC_MESSAGES/django.po
  • mayan/apps/platform/management/commands/platform_template.py
  • mayan/apps/platform/templates/platform/docker/dockerfile.tmpl
  • mayan/apps/platform/templates/platform/docker/entrypoint.tmpl
  • mayan/apps/platform/templates/platform/docker/supervisord.tmpl
  • mayan/apps/platform/templates/platform/gitlab-ci.tmpl
  • mayan/settings/literals.py

本文档提供了为 Mayan EDMS 搭建本地开发环境的完整指南，涵盖原生安装和基于 Docker 的开发工作流、测试基础设施以及核心开发工具。

关于部署和生产配置，请参见安装与部署。关于构建与发布流程，请参见构建与部署管线。

开发环境架构

graph TB
    subgraph "开发机器"
        DEV_CODE["源代码<br/>mayan/"]
        DEV_TOOLS["开发工具<br/>Makefile, requirements/"]
        DEV_ENV["Python 虚拟环境<br/>venv/"]
    end

    subgraph "本地服务"
        POSTGRES_DEV["PostgreSQL 容器<br/>mayan-test-postgresql"]
        REDIS_DEV["Redis 容器<br/>mayan-test-redis"]
        MYSQL_DEV["MySQL 容器<br/>mayan-test-mysql"]
        ELASTIC_DEV["Elasticsearch 容器<br/>mayan-test-elastic"]
    end

    subgraph "开发服务器"
        DJANGO_SERVER["Django 开发服务器<br/>runserver 命令"]
        CELERY_WORKER["Celery 工作进程<br/>staging-worker 命令"]
        TEST_RUNNER["测试运行器<br/>manage.py test"]
    end

    subgraph "配置"
        CONFIG_ENV["config.env"]
        SETTINGS_DEV["mayan.settings.development"]
        MAKEFILE_CONFIG["Makefile 变量"]
    end

    DEV_CODE --> DEV_ENV
    DEV_TOOLS --> DEV_ENV
    CONFIG_ENV --> DJANGO_SERVER
    SETTINGS_DEV --> DJANGO_SERVER

    DEV_ENV --> DJANGO_SERVER
    DEV_ENV --> CELERY_WORKER
    DEV_ENV --> TEST_RUNNER

    DJANGO_SERVER --> POSTGRES_DEV
    DJANGO_SERVER --> REDIS_DEV
    CELERY_WORKER --> POSTGRES_DEV
    CELERY_WORKER --> REDIS_DEV

    TEST_RUNNER --> POSTGRES_DEV
    TEST_RUNNER --> MYSQL_DEV
    TEST_RUNNER --> ELASTIC_DEV

来源：Makefile:1-552, config.env:1-74, docker/Makefile:1-193

前提条件与操作系统设置

系统依赖

开发环境需要特定的操作系统包来支持文档处理、OCR 及其他核心功能。

graph LR
    subgraph "操作系统包分类"
        IMAGE_PROC["图像处理<br/>libjpeg-dev, libpng-dev<br/>libtiff-dev"]
        OCR_TOOLS["OCR 工具<br/>tesseract-ocr<br/>tesseract-ocr-deu"]
        DOC_TOOLS["文档工具<br/>poppler-utils<br/>libreoffice-*-nogui"]
        BUILD_TOOLS["构建工具<br/>gcc, python3-dev<br/>libffi-dev"]
        GRAPHICS["图形<br/>graphviz<br/>libcairo2"]
    end

    SETUP_CMD["make setup-dev-operating-system-packages"] --> IMAGE_PROC
    SETUP_CMD --> OCR_TOOLS
    SETUP_CMD --> DOC_TOOLS
    SETUP_CMD --> BUILD_TOOLS
    SETUP_CMD --> GRAPHICS

使用提供的 Make 目标安装系统依赖：

make setup-dev-operating-system-packages

该命令会安装 Makefile:517 中定义的包：

  • exiftool - 元数据提取
  • gcc - 编译工具
  • gettext - 国际化支持
  • gnupg1 - GPG 支持
  • graphviz - 图表生成
  • libcairo2, libffi-dev, libjpeg-dev, libpng-dev - 图像处理库
  • poppler-utils - PDF 处理
  • python3-dev - Python 开发头文件
  • sane-utils - 扫描仪支持
  • tesseract-ocr-deu - 德语 OCR 语言包

来源：Makefile:515-517, mayan/apps/platform/templates/platform/docker/dockerfile.tmpl:28-61

Python 环境设置

创建 Python 虚拟环境并安装开发依赖：

make setup-dev-python-libraries

该命令会从多个需求文件中安装包，如 Makefile:521 所定义：

  • requirements.txt - 核心依赖
  • requirements/development.txt - 开发工具
  • requirements/testing-base.txt - 测试框架
  • requirements/documentation.txt - 文档工具
  • requirements/build.txt - 构建工具

来源：Makefile:519-521

本地开发环境设置

数据库配置

Mayan EDMS 支持多种数据库后端用于开发和测试。Makefile 提供了启动容器化数据库服务的命令。

PostgreSQL 开发数据库

启动用于开发的 PostgreSQL 容器：

make docker-postgresql-start

该命令会创建一个名为 mayan-test-postgresql 的容器，其凭据在 config.env:7-9 中定义：

  • 数据库名称：mayan
  • 用户名：mayan
  • 密码：mayanuserpass

使用 PostgreSQL 运行开发服务器：

make manage-with-postgresql runserver

来源：Makefile:437-439, Makefile:388-390, config.env:7-9

其他数据库后端

用于 MySQL 开发：

make docker-mysql-start
make manage-with-mysql runserver

用于 Oracle 开发：

make docker-oracle-start
make manage-with-oracle runserver

来源：Makefile:412-414, Makefile:426-430, Makefile:380-382, Makefile:384-386

开发服务器命令

Makefile 提供了多个运行开发服务器的命令：

命令用途设置模块
make runserver标准 Django 开发服务器mayan.settings.development
make runserver-plusDjango 扩展开发服务器mayan.settings.development
make shell-plus增强型 Django Shellmayan.settings.development

开发服务器默认运行在 Django 标准端口（8000），除非使用 ADDRPORT 变量指定。

来源：Makefile:392-399

预发布环境

如需模拟生产环境进行测试，可使用编排多个服务的预发布环境：

make staging-start    # 启动 PostgreSQL + Redis 并初始化
make staging-frontend # 运行前端服务器
make staging-worker   # 运行 Celery 工作进程（另开终端）
make staging-stop     # 清理服务

预发布环境使用：

  • PostgreSQL 容器作为数据库
  • Redis 容器作为缓存和任务队列
  • 设置模块：mayan.settings.staging.docker

来源：Makefile:462-476

基于 Docker 的开发

开发服务架构
graph TB
    subgraph "Docker 开发栈"
        COMPOSE_FILE["docker-compose.yml"]
        ENV_FILE["docker/.env"]

        subgraph "应用服务"
            APP_CONTAINER["mayan-app<br/>端口 8000"]
            WORKER_A["worker_a<br/>A 类任务"]
            WORKER_B["worker_b<br/>B 类任务"]
            CELERY_BEAT["celery_beat<br/>定时任务"]
        end

        subgraph "基础设施服务"
            POSTGRES_DOCKER["postgresql<br/>端口 5432"]
            REDIS_DOCKER["redis<br/>端口 6379"]
            RABBITMQ_DOCKER["rabbitmq<br/>端口 5672"]
            ELASTICSEARCH_DOCKER["elasticsearch<br/>端口 9200"]
        end

        subgraph "代理与监控"
            TRAEFIK["traefik<br/>端口 80, 443"]
        end
    end

    COMPOSE_FILE --> APP_CONTAINER
    COMPOSE_FILE --> POSTGRES_DOCKER
    COMPOSE_FILE --> REDIS_DOCKER
    ENV_FILE --> APP_CONTAINER

    APP_CONTAINER --> POSTGRES_DOCKER
    APP_CONTAINER --> REDIS_DOCKER
    WORKER_A --> POSTGRES_DOCKER
    WORKER_A --> RABBITMQ_DOCKER
    CELERY_BEAT --> REDIS_DOCKER

    TRAEFIK --> APP_CONTAINER

Docker Compose 配置支持 docker/.env:11 中定义的多个部署配置文件：

  • all_in_one - 包含所有服务的单个容器
  • postgresql - 独立的 PostgreSQL 服务
  • rabbitmq - RabbitMQ 消息代理
  • redis - Redis 缓存和任务队列
  • elasticsearch - 搜索后端

来源：docker/docker-compose.yml:1-290, docker/.env:1-83

Docker 开发命令

构建并运行开发栈：

# 构建 Docker 镜像
make docker-build

# 使用代理支持运行（用于内部开发）
make docker-build-with-proxy

# 启动开发容器
make docker-staging-start

# 清理开发容器
make docker-staging-cleanup

Docker 构建过程使用多阶段构建，定义在 mayan/apps/platform/templates/platform/docker/dockerfile.tmpl 的 Dockerfile 模板中。

来源：docker/Makefile:15-22, docker/Makefile:140-152

测试基础设施

测试执行框架
graph TB
    subgraph "测试管理"
        MAKEFILE_TEST["Makefile 测试目标"]
        MANAGE_PY["manage.py test 命令"]
        SETTINGS_TEST["mayan.settings.testing.*"]
    end

    subgraph "测试数据库后端"
        SQLITE_TESTS["SQLite 测试<br/>内存数据库"]
        POSTGRES_TESTS["PostgreSQL 测试<br/>基于容器"]
        MYSQL_TESTS["MySQL 测试<br/>基于容器"]
        ORACLE_TESTS["Oracle 测试<br/>基于容器"]
    end

    subgraph "测试分类"
        UNIT_TESTS["单元测试<br/>--mayan-apps 标志"]
        MIGRATION_TESTS["迁移测试<br/>--tag=migration_test"]
        UPGRADE_TESTS["升级测试<br/>旧版本 → 当前版本"]
    end

    subgraph "持续集成/持续部署管线"
        GITLAB_CI["GitLab CI 任务"]
        TEST_MATRIX["测试矩阵<br/>多数据库后端"]
    end

    MAKEFILE_TEST --> MANAGE_PY
    MANAGE_PY --> SQLITE_TESTS
    MANAGE_PY --> POSTGRES_TESTS
    MANAGE_PY --> MYSQL_TESTS

    MANAGE_PY --> UNIT_TESTS
    MANAGE_PY --> MIGRATION_TESTS
    MANAGE_PY --> UPGRADE_TESTS

    GITLAB_CI --> TEST_MATRIX
    TEST_MATRIX --> POSTGRES_TESTS
    TEST_MATRIX --> MYSQL_TESTS

来源：Makefile:46-83, .gitlab-ci.yml:345-399

本地运行测试

测试框架支持多种执行模式和数据库后端：

基本测试命令
# 使用 SQLite 运行所有测试（默认）
make test-all

# 运行特定模块的测试
make test MODULE=mayan.apps.documents

# 运行带调试输出的测试
make test-debug MODULE=mayan.apps.documents

# 以调试模式运行所有测试
make test-all-debug

测试命令模板在 Makefile:16 中定义：

./manage.py test $(MODULE) --settings=$(SETTINGS) $(SKIPMIGRATIONS) $(DEBUG) $(ARGUMENTS)
特定数据库测试

针对 PostgreSQL 进行测试：

make docker-postgresql-start  # 启动容器
make test-all-with-postgresql  # 运行测试
make docker-postgresql-stop   # 清理

针对 MySQL 进行测试：

make docker-mysql-start
make test-all-with-mysql
make docker-mysql-stop

来源：Makefile:70-83, Makefile:105-113

迁移测试

运行迁移测试以确保数据库模式变更正常工作：

# 测试所有迁移
make test-all-migrations

# 使用特定数据库测试迁移
make test-all-migrations-with-postgresql

迁移测试使用 --tag=migration_test 标志，并且不会跳过迁移（Makefile:65-68）。

来源：Makefile:65-68, Makefile:110-113

测试配置

测试设置在 mayan.settings.testing.* 下的模块中定义：

设置模块用途
mayan.settings.testing.development本地开发测试
mayan.settings.testing.gitlab-ci持续集成/持续部署管线测试

默认测试设置模块由 Makefile:13 中的 SETTINGS 变量控制。

来源：Makefile:12-14, .gitlab-ci.yml:382-383

GitLab 持续集成/持续部署集成

持续集成管线架构

GitLab CI 配置展示了用于开发验证的完整测试和构建管线。

graph LR
    subgraph "GitLab CI 阶段"
        STAGE_TEST["stage_test"]
        STAGE_BUILD_PY["stage_build_python"]
        STAGE_BUILD_DOCKER["stage_build_docker"]
        STAGE_PUSH["stage_push_*"]
    end

    subgraph "测试任务"
        POSTGRES_TEST["job_postgres_test"]
        SQLITE_TEST["job_sqlite_test"]
        UPGRADE_TEST["job_postgres_upgrade_test"]
    end

    subgraph "构建任务"
        PYTHON_BUILD["job_python_build"]
        DOCKER_BUILD["job_docker_build"]
    end

    subgraph "测试环境"
        TEST_DEPS["系统依赖<br/>tesseract, poppler 等"]
        PYTHON_ENV["Python 虚拟环境<br/>requirements/testing-base.txt"]
        TEST_DB["PostgreSQL 服务<br/>postgres:12.11-alpine"]
    end

    STAGE_TEST --> POSTGRES_TEST
    STAGE_TEST --> SQLITE_TEST
    STAGE_TEST --> UPGRADE_TEST

    POSTGRES_TEST --> TEST_DEPS
    POSTGRES_TEST --> PYTHON_ENV
    POSTGRES_TEST --> TEST_DB

    STAGE_BUILD_PY --> PYTHON_BUILD
    STAGE_BUILD_DOCKER --> DOCKER_BUILD

CI 配置是从 mayan/apps/platform/templates/platform/gitlab-ci.tmpl 的平台模板生成的，使用以下命令：

make gitlab-ci-update

来源：.gitlab-ci.yml:1-431, Makefile:115-117

本地持续集成测试

在本地执行 GitLab CI 任务以进行调试：

make gitlab-ci-run GITLAB_CI_JOB=job_postgres_test

该命令使用 Docker 模式下的 GitLab Runner 在本地复制 CI 环境。

来源：Makefile:119-125

配置管理

环境变量与设置

开发配置通过多层进行管理：

  1. config.env - 基础配置变量
  2. 环境特定设置模块 - Django 设置
  3. Makefile 变量 - 构建和测试配置

关键配置文件：

文件用途用法
config.env基础环境变量被构建脚本引用
mayan/settings/literals.py来自 config.env 的 Python 常量自动生成
docker/.envDocker Compose 环境容器配置

config.env 文件通过 contrib/scripts/copy_config_env.py 处理为 Python 字面量：

make copy-config-env  # 生成 mayan/settings/literals.py

来源：config.env:1-74, mayan/settings/literals.py:1-63, contrib/scripts/copy_config_env.py:1-29

开发与生产设置对比

开发设置继承自基础设置，但会覆盖关键参数：

  • 数据库：默认使用 SQLite，预发布环境使用 PostgreSQL
  • 调试模式：开发环境启用
  • 静态文件服务：Django 开发服务器
  • Celery：开发环境同步执行

设置层级结构：

mayan.settings.base
├── mayan.settings.development
├── mayan.settings.staging.docker
└── mayan.settings.production

来源：Makefile:13, Makefile:465

开发工具与工作流

代码质量与文档

生成项目文档：

make docs-html      # 构建 HTML 文档
make docs-serve     # 实时文档服务器
make docs-spellcheck # 文档拼写检查

运行代码质量检查：

make safety-check           # 安全漏洞扫描
make check-missing-migrations # 验证迁移
make check-missing-inits    # 查找缺失的 __init__.py 文件

来源：Makefile:139-147, Makefile:480-511

翻译管理

Mayan EDMS 通过 Transifex 支持国际化。翻译管理的开发命令：

make translations-make           # 提取可翻译字符串
make translations-compile        # 编译翻译文件
make translations-transifex-push # 上传到 Transifex
make translations-transifex-pull # 下载翻译

位于 contrib/scripts/translations_helper.py 的翻译辅助脚本管理完整的翻译工作流。

来源：Makefile:150-175, contrib/scripts/translations_helper.py:1-321

包构建与测试

构建用于测试的 Python 包：

make python-wheel          # 构建 wheel 包
make python-sdist          # 构建源码分发包
make python-wheel-test-suit # 测试 wheel 包

这些命令会在 dist/ 目录中创建可分发包，并针对打包后的版本运行测试套件，以确保部署兼容性。

来源：Makefile:196-283