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

6.1 · 开发设置（Development Setup）

企业电子文档治理 · 聚焦本章的模块关系、源码依据与实现要点。

项目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

开发环境搭建

相关源文件

本章引用的主要源码文件：

  • .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 的开发工作流、测试基础设施以及核心开发工具。

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

开发环境架构

Mayan EDMS · 开发环境架构 · 图 1
Mayan EDMS · 开发环境架构 · 图 1

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

前提条件与操作系统设置

系统依赖

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

Mayan EDMS · 系统依赖 · 图 2
Mayan EDMS · 系统依赖 · 图 2

使用提供的 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 的开发

开发服务架构
Mayan EDMS · 开发服务架构 · 图 3
Mayan EDMS · 开发服务架构 · 图 3

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

测试基础设施

测试执行框架
Mayan EDMS · 测试执行框架 · 图 4
Mayan EDMS · 测试执行框架 · 图 4

来源：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 配置展示了用于开发验证的完整测试和构建管线。

Mayan EDMS · 持续集成管线架构 · 图 5
Mayan EDMS · 持续集成管线架构 · 图 5

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