agentic_huge_data_base / wiki
页面 Mayan EDMS · 2.1 安装与部署·DeepWiki 中文全文译文
DeepWiki 中文译文 / Mayan EDMS / 2.1

2.1 · 安装与部署（Installation & Deployment）

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

项目Mayan EDMS 章节2.1 状态全文译文 模块安装与启动、测试、发布与运维、配置治理、存储与持久化
项目要点页2.5 参考项目 项目章节目录Mayan EDMS DeepWiki 原始章节Installation & Deployment 上一章2 下一章2.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/2.1-installation-and-deployment

安装与部署

相关源文件

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

  • .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 的部署、环境配置以及持续集成/持续部署（CI/CD）管线。文档重点介绍了容器化部署方式，这也是推荐的生产环境部署方法。

关于部署后的配置管理信息，请参见配置管理。关于开发环境搭建，请参见开发环境搭建。

概述

Mayan EDMS 提供了多种部署方法，其中 Docker Compose 是生产环境部署的主要推荐方式。该系统采用微服务架构设计，可以部署为单一的全功能容器，也可以拆分为独立服务以实现可伸缩性。

部署架构

Mayan EDMS · 部署架构 · 图 1
Mayan EDMS · 部署架构 · 图 1

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

Docker Compose 部署

服务配置

Docker Compose 配置使用配置（profile）来控制部署哪些服务：

配置服务用途
all_in_oneapp包含所有组件的单一容器
postgresqlpostgresqlPostgreSQL 数据库
redisredisRedis 缓存与锁管理器
rabbitmqrabbitmqRabbitMQ 消息代理
elasticsearchelasticsearchElasticsearch 搜索后端
extra_frontendfrontend独立的前端服务
extra_worker_*worker_a、worker_b 等独立的工作进程
traefiktraefik带 SSL 的反向代理
核心服务配置
Mayan EDMS · 核心服务配置 · 图 2
Mayan EDMS · 核心服务配置 · 图 2

来源：docker/docker-compose.yml:3-21

环境配置

部署使用 .env 文件和 config.env 中定义的环境变量：

安全配置：

MAYAN_DATABASE_PASSWORD=mayandbpass
MAYAN_REDIS_PASSWORD=mayanredispassword
MAYAN_RABBITMQ_PASSWORD=mayanrabbitpass

服务端点：

MAYAN_DOCKER_WAIT="postgresql:5432 rabbitmq:5672 redis:6379"

Compose 配置：

COMPOSE_PROFILES=all_in_one,postgresql,rabbitmq,redis

来源：docker/.env:1-83、config.env:1-74

容器构建流程

Mayan EDMS · 容器构建流程 · 图 3
Mayan EDMS · 容器构建流程 · 图 3

来源：mayan/apps/platform/templates/platform/docker/dockerfile.tmpl:1-204

多阶段构建详情

Docker 构建过程采用多阶段方法：

  1. 基础镜像（base_image）：安装运行时依赖
    • 操作系统包（tesseract-ocr、libreoffice 等）
    • 创建 mayan 用户
    • 配置 FUSE 用于文档索引
  1. 构建镜像（builder_image）：编译应用程序
    • 安装构建依赖（gcc、python3-dev 等）
    • 从源码构建 Python Wheel
    • 使用 appearance_prepare_static 收集静态文件
  1. 最终镜像：将基础镜像与构建产物合并
    • 从构建镜像复制 Wheel 和静态文件
    • 生成入口点和 supervisord 配置
    • 设置卷挂载并暴露端口 8000

来源：mayan/apps/platform/templates/platform/docker/dockerfile.tmpl:8-204

持续集成/持续部署（CI/CD）管线

Mayan EDMS · 持续部署（CI · 图 4
Mayan EDMS · 持续部署（CI · 图 4

来源：.gitlab-ci.yml:1-431

测试任务

CI 管线包含全面的测试：

数据库测试：

  • job_postgres_test：针对 PostgreSQL 12.11 进行测试
  • job_sqlite_test：针对 SQLite 进行测试
  • 环境变量：MAYAN_DATABASES 配置数据库连接

升级测试：

  • job_postgres_upgrade_test：安装旧版本、创建测试数据、执行升级
  • job_sqlite_upgrade_test：针对 SQLite 的类似升级测试
  • 使用 common_perform_upgrade 管理命令

来源：.gitlab-ci.yml:375-398、.gitlab-ci.yml:313-343

管理命令

初始设置

common_initial_setup 命令用于初始化新安装：

mayan-edms.py common_initial_setup [--force] [--no-dependencies]

流程：

  1. 创建媒体目录结构
  2. 生成 SECRET_KEY 文件
  3. 创建用户设置文件夹
  4. 安装依赖（除非指定 --no-dependencies）
  5. 通过 autoadmin_create 创建管理员用户
  6. 准备静态文件

来源：mayan/apps/common/management/base.py:36-86

升级流程

common_perform_upgrade 命令用于处理版本升级：

mayan-edms.py common_perform_upgrade [--no-dependencies]

流程：

  1. 发送 signal_pre_upgrade 信号
  2. 如果用户设置文件夹缺失则创建
  3. 安装依赖（除非指定 --no-dependencies）
  4. 发送 signal_perform_upgrade 信号
  5. 发送 signal_post_upgrade 信号

来源：mayan/apps/common/management/base.py:95-126

环境变量

核心配置
变量用途默认值
MAYAN_DATABASES数据库配置字典SQLite
MAYAN_CELERY_BROKER_URL消息代理 URLredis://localhost
MAYAN_CELERY_RESULT_BACKEND任务结果后端redis://localhost
MAYAN_LOCK_MANAGER_BACKEND分布式锁RedisLock
MAYAN_MEDIA_ROOT文档存储路径/var/lib/mayan
工作进程配置

每个工作进程类可以单独配置并发数和资源限制：

MAYAN_WORKER_A_CONCURRENCY=0  # 自动检测
MAYAN_WORKER_A_MAX_MEMORY_PER_CHILD=300000
MAYAN_WORKER_A_MAX_TASKS_PER_CHILD=100

来源：config.env:62-73、mayan/apps/platform/templates/platform/docker/entrypoint.tmpl:102-130

构建自动化

Makefile 目标

Makefile 提供了部署自动化功能：

Docker 操作：

  • docker-build：构建本地 Docker 镜像
  • docker-compose-up：启动完整堆栈
  • docker-staging-start：启动预发布环境

发布管理：

  • gitlab-release-all-major：触发主版本发布
  • gitlab-release-docker-minor：仅 Docker 的次版本发布
  • increase-version：递增版本号

开发：

  • staging-start：使用 PostgreSQL/Redis 进行本地开发
  • manage-with-postgresql：针对 PostgreSQL 运行命令

来源：Makefile:15-477、docker/Makefile:15-193

版本管理

版本信息存储在多个文件中：

  • mayan/__init__.py：Python 包版本
  • docker/rootfs/version：Docker 镜像版本
  • 构建号以十六进制计算：0x{主版本}{次版本}{补丁版本}

来源：Makefile:179-185

生产部署注意事项

资源需求

最低配置：

  • 2 个 CPU 核心
  • 4GB 内存
  • 10GB 应用存储空间
  • 额外的文档存储空间

扩展配置：

  • 按类别分离工作进程容器
  • 在负载均衡器后部署多个前端实例
  • 使用外部 PostgreSQL 和 Redis 实例
安全

数据库安全：

  • 在 .env 文件中更改默认密码
  • 使用通过 contrib/scripts/password_randomizer.py 生成的强密码
  • 将数据库访问限制在应用网络内

SSL/TLS：

  • 启用 Traefik 以自动获取 SSL 证书
  • 配置 MAYAN_TRAEFIK_LETS_ENCRYPT_EMAIL
  • 设置 MAYAN_TRAEFIK_LETS_ENCRYPT_TLS_CHALLENGE=true

来源：docker/.env:22-52、contrib/scripts/password_randomizer.py:1-30