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

安装与部署（中文译文）

原始 DeepWiki 页面：https://deepwiki.com/mayan-edms/Mayan-EDMS/2.1-installation-and-deployment

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

翻译模型：deepseek-chat

原文字符数：14249

项目：Mayan EDMS (mayan-edms)

---

安装与部署

相关源文件

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

• .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 是生产环境部署的主要推荐方式。该系统采用微服务架构设计，可以部署为单一的全功能容器，也可以拆分为独立服务以实现可伸缩性。

部署架构

graph TB
    subgraph "Docker Compose 服务"
        FRONTEND["前端<br/>Gunicorn WSGI 服务器"]
        APP["应用<br/>全功能配置"]

        subgraph "工作进程服务"
            WORKER_A["worker_a<br/>A 类任务"]
            WORKER_B["worker_b<br/>B 类任务"]
            WORKER_C["worker_c<br/>C 类任务"]
            WORKER_D["worker_d<br/>D 类任务"]
        end

        subgraph "基础设施服务"
            POSTGRES["postgresql<br/>主数据库"]
            REDIS["redis<br/>缓存与锁管理器"]
            RABBITMQ["rabbitmq<br/>消息代理"]
            ELASTIC["elasticsearch<br/>搜索后端"]
        end

        subgraph "辅助服务"
            TRAEFIK["traefik<br/>反向代理"]
            CELERY_BEAT["celery_beat<br/>调度器"]
        end
    end

    subgraph "卷存储"
        APP_VOL["应用<br/>文档存储"]
        POSTGRES_VOL["postgres<br/>数据库数据"]
        REDIS_VOL["redis<br/>缓存数据"]
        RABBITMQ_VOL["rabbitmq<br/>队列数据"]
        ELASTIC_VOL["elasticsearch<br/>搜索索引"]
    end

    FRONTEND --> POSTGRES
    FRONTEND --> REDIS
    FRONTEND --> RABBITMQ

    APP --> POSTGRES
    APP --> REDIS
    APP --> RABBITMQ

    WORKER_A --> POSTGRES
    WORKER_A --> REDIS
    WORKER_A --> RABBITMQ

    WORKER_B --> POSTGRES
    WORKER_B --> REDIS
    WORKER_B --> RABBITMQ

    WORKER_C --> POSTGRES
    WORKER_C --> REDIS
    WORKER_C --> RABBITMQ

    WORKER_D --> POSTGRES
    WORKER_D --> REDIS
    WORKER_D --> RABBITMQ

    POSTGRES --> POSTGRES_VOL
    REDIS --> REDIS_VOL
    RABBITMQ --> RABBITMQ_VOL
    ELASTIC --> ELASTIC_VOL
    FRONTEND --> APP_VOL
    APP --> APP_VOL

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

Docker Compose 部署

服务配置

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

配置	服务	用途
all_in_one	app	包含所有组件的单一容器
postgresql	postgresql	PostgreSQL 数据库
redis	redis	Redis 缓存与锁管理器
rabbitmq	rabbitmq	RabbitMQ 消息代理
elasticsearch	elasticsearch	Elasticsearch 搜索后端
extra_frontend	frontend	独立的前端服务
extra_worker_*	worker_a、worker_b 等	独立的工作进程
traefik	traefik	带 SSL 的反向代理

核心服务配置

graph LR
    subgraph "环境变量"
        BROKER_URL["MAYAN_CELERY_BROKER_URL<br/>amqp://user:pass@rabbitmq:5672/vhost"]
        RESULT_BACKEND["MAYAN_CELERY_RESULT_BACKEND<br/>redis://:password@redis:6379/1"]
        DATABASES["MAYAN_DATABASES<br/>PostgreSQL 连接字典"]
        LOCK_MANAGER["MAYAN_LOCK_MANAGER_BACKEND<br/>RedisLock"]
    end

    subgraph "基础容器配置"
        IMAGE["镜像: mayanedms/mayanedms:s4.3"]
        VOLUMES["卷: app:/var/lib/mayan"]
        NETWORK["网络: mayan (桥接)"]
        RESTART["重启策略: unless-stopped"]
    end

    BROKER_URL --> RABBITMQ_SVC["rabbitmq:5672"]
    RESULT_BACKEND --> REDIS_SVC["redis:6379"]
    DATABASES --> POSTGRES_SVC["postgresql:5432"]
    LOCK_MANAGER --> REDIS_SVC

来源：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

容器构建流程

flowchart TD
    subgraph "构建阶段"
        BASE["基础镜像<br/>FROM debian:11.4-slim<br/>安装运行时包"]
        BUILDER["构建镜像<br/>FROM 基础镜像<br/>安装构建依赖"]
        FINAL["最终镜像<br/>FROM 基础镜像<br/>复制构建产物"]
    end

    subgraph "构建产物"
        PYTHON_WHEEL["Python Wheel<br/>mayan_edms-*.whl"]
        STATIC_FILES["静态文件<br/>收集的 CSS/JS"]
        DEPENDENCIES["依赖<br/>第三方包"]
    end

    subgraph "运行时脚本"
        ENTRYPOINT["entrypoint.sh<br/>容器初始化"]
        SUPERVISORD["supervisord.conf<br/>进程管理"]
        RUN_SCRIPTS["run_*.sh<br/>服务启动器"]
    end

    BASE --> BUILDER
    BUILDER --> PYTHON_WHEEL
    BUILDER --> STATIC_FILES
    BUILDER --> DEPENDENCIES

    BASE --> FINAL
    PYTHON_WHEEL --> FINAL
    STATIC_FILES --> FINAL
    DEPENDENCIES --> FINAL

    FINAL --> ENTRYPOINT
    FINAL --> SUPERVISORD
    FINAL --> RUN_SCRIPTS

来源：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）管线

graph TB
    subgraph "GitLab CI 阶段"
        TEST_STAGE["stage_test<br/>PostgreSQL 和 SQLite 测试<br/>升级测试"]
        BUILD_PYTHON["stage_build_python<br/>Python 包构建"]
        BUILD_DOCKER["stage_build_docker<br/>Docker 镜像构建"]
        BUILD_DOCS["stage_build_documentation<br/>Sphinx 文档构建"]
        PUSH_PYTHON["stage_push_python<br/>PyPI 发布"]
        PUSH_DOCKER["stage_push_docker<br/>Docker Hub 推送"]
        PUSH_DOCS["stage_push_documentation<br/>文档部署"]
        DEPLOY["stage_deploy<br/>演示/预发布部署"]
    end

    subgraph "分支触发条件"
        RELEASE_MAJOR["releases/all_major<br/>releases/docker_major<br/>releases/python_major"]
        RELEASE_MINOR["releases/all_minor<br/>releases/docker_minor<br/>releases/python_minor"]
        TEST_BRANCHES["tests/all<br/>tests/base<br/>tests/upgrade"]
        NIGHTLY["releases/nightly<br/>releases/staging"]
    end

    TEST_STAGE --> BUILD_PYTHON
    TEST_STAGE --> BUILD_DOCKER
    TEST_STAGE --> BUILD_DOCS

    BUILD_PYTHON --> PUSH_PYTHON
    BUILD_DOCKER --> PUSH_DOCKER
    BUILD_DOCS --> PUSH_DOCS

    PUSH_PYTHON --> DEPLOY
    PUSH_DOCKER --> DEPLOY

    RELEASE_MAJOR --> BUILD_PYTHON
    RELEASE_MAJOR --> BUILD_DOCKER
    RELEASE_MINOR --> BUILD_PYTHON
    RELEASE_MINOR --> BUILD_DOCKER
    TEST_BRANCHES --> TEST_STAGE
    NIGHTLY --> BUILD_DOCKER

来源：.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	消息代理 URL	redis://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