Mayan EDMS 配置参数详解

目标：讲清 Mayan EDMS 4.12.2 的配置体系——环境变量层（MAYAN_* 前缀）、smart_settings 层（config.yml）、服务进程参数（Gunicorn/Celery）三层的映射关系与全部常用参数，并给出实测验证方法。所有变量取值均来自实测环境（官方 Docker Compose 部署，见 《Mayan EDMS Docker Compose 部署实战》），查询日期 2026-10-28。

一、环境信息

• Mayan EDMS：4.12.2（官方 s4.12 镜像，2026-10-28 实测运行中）
• 部署形态：官方 Docker Compose 默认 profile（应用一体 + PostgreSQL 15.17 + Redis 7.4.8 + RabbitMQ 4.1.8-management）
• 取证命令：应用内 env | grep MAYAN（进程环境实值）、settings_show（生效设置）、编排文件与官方 .env 模板（2026-10-28 自 GitLab master 下载）
• 本文变量名均在 4.12.2 实测存在且生效；config.yml 头部版本戳实测为 # Version: 4.12.2 v4.12.2-39-g16850d008cb_Wed Sep 16 10:01:41 2026

二、配置体系总览

Mayan EDMS 的配置分三层，读取优先级从高到低：

三条实测验证：

1. 前缀映射规则：环境变量名去掉 MAYAN_ 前缀即 Django 设置名。实测应用进程内 MAYAN_CELERY_BROKER_URL=amqp://mayan:mayanrabbitpass@rabbitmq:5672/mayan，settings_show 输出 CELERY_BROKER_URL: amqp://mayan:mayanrabbitpass@rabbitmq:5672/mayan，一一对应。
2. 复杂值用 Python 字面量：MAYAN_DATABASES 的实值是一个字典字符串 {'default':{'ENGINE':'django.db.backends.postgresql','NAME':'mayan','PASSWORD':'mayandbpass','USER':'mayan','HOST':'postgresql','PORT':,'CONN_MAX_AGE':0,}}，官方编排用它把 Compose 变量拼成 Django 的 DATABASES。
3. 配置文件落盘：应用启动后把当前设置快照写到持久卷 config.yml（实测路径 /var/lib/mayan/config.yml，头部带版本戳与时间戳），升级时另存 config_backup.yml。

Compose 部署时，.env 里的变量经编排文件的 env_file 注入全部 Mayan 服务；还支持可选的 .env-local 覆盖层（编排中 required: false），适合在不改动 .env 的机器本地化差异。

三、官方 .env 模板变量全表

以下变量在官方 .env 模板中定义（生效项 + 注释可选项，2026-10-28 版），按功能分组：

3.1 Compose 行为层（作用于编排解析）

3.2 镜像与端口

3.3 数据库与伴生服务连接

3.4 应用行为与初始化

3.5 Traefik（默认关闭）

MAYAN_TRAEFIK_FRONTEND_ENABLE、MAYAN_TRAEFIK_DASHBOARD_ENABLE、MAYAN_TRAEFIK_DASHBOARD_AUTHENTICATION、MAYAN_TRAEFIK_EXTERNAL_DOMAIN、MAYAN_TRAEFIK_LETS_ENCRYPT_EMAIL/_SERVER/_TLS_CHALLENGE/_DNS_CHALLENGE/_DNS_CHALLENGE_PROVIDER、MAYAN_TRAEFIK_RABBITMQ_ENABLE、MAYAN_TRAEFIK_API_INSECURE。注意默认证书指向 Let's Encrypt staging 环境（acme-staging-v02），生产要显式改 MAYAN_TRAEFIK_LETS_ENCRYPT_SERVER 为正式地址。

邮件（SMTP）不在 .env 模板中，属于 Django 设置层：需以 MAYAN_EMAIL_HOST 等 MAYAN_ 前缀环境变量注入（映射 EMAIL_HOST），或用 smart_settings 持久化；发信能力可用 sendtestemail 命令验证（见运维实战篇）。

四、应用内 MAYAN_* 变量实测值

应用进程内 env | grep MAYAN 实测（排序后全量摘录，即 4.12.2 真实生效集）：

MAYAN_AUTOADMIN_PASSWORD=q1w2e3r4
MAYAN_AUTOADMIN_USERNAME=admin
MAYAN_CELERY_BROKER_URL=amqp://mayan:mayanrabbitpass@rabbitmq:5672/mayan
MAYAN_CELERY_RESULT_BACKEND=redis://:mayanredispassword@redis:6379/1
MAYAN_DATABASES={'default':{'ENGINE':'django.db.backends.postgresql','NAME':'mayan','PASSWORD':'mayandbpass','USER':'mayan','HOST':'postgresql','PORT':,'CONN_MAX_AGE':0,}}
MAYAN_DOCKER_WAIT=postgresql:5432 rabbitmq:5672 redis:6379
MAYAN_FRONTEND_HTTP_PORT=8140
MAYAN_LOCK_MANAGER_BACKEND=mayan.apps.lock_manager.backends.redis_lock.RedisLock
MAYAN_LOCK_MANAGER_BACKEND_ARGUMENTS={'redis_url':'redis://:mayanredispassword@redis:6379/2'}
MAYAN_MEDIA_ROOT=/var/lib/mayan
MAYAN_MIRROR_CABINET_NAME=
MAYAN_MIRROR_INDEX_NAME=
MAYAN_SERVER_SIDE_EVENTS_BACKEND=mayan.apps.server_side_events.sse_backends.redis.RedisServerEventStreamBackend
MAYAN_SERVER_SIDE_EVENTS_BACKEND_ARGUMENTS={'url':'redis://:mayanredispassword@redis:6379/3'}
MAYAN_STATIC_ROOT=/opt/mayan-edms/static
MAYAN_WORKER_CUSTOM_QUEUE_LIST=

几个关键语义：

1. Redis 四分库：db0 通用缓存、db1 Celery 结果、db2 分布式锁（RedisLock 后端）、db3 服务端事件流。编排文件注释明确指出锁与结果是语义键而非缓存，故 Redis 以 --maxmemory-policy noeviction 运行——键被淘汰意味着互斥静默失效或任务账本丢失，宁可写失败也要失败得响亮；每个键自带过期时间，内存上限由 --maxmemory 100mb 控制。
2. 路径变量：MAYAN_MEDIA_ROOT=/var/lib/mayan（文档文件与配置落盘点，对应应用数据卷）、MAYAN_STATIC_ROOT=/opt/mayan-edms/static（静态资源，构建于镜像内）。
3. MAYAN_FRONTEND_HTTP_PORT：该值由 Compose 端口映射消费（宿主 8140→应用 8000），并非 Django 设置，settings_show 里找不到它属正常。
4. PORT 为空：MAYAN_DATABASES 里 'PORT':, 是官方编排模板的空参写法，Django 视为空串走 PostgreSQL 默认 5432，非错误。

五、服务进程参数（Gunicorn 与 Celery）

5.1 Gunicorn 实际启动参数

Web 前端由 supervisor 托管，进程命令行实测：

gunicorn --bind 0.0.0.0:8000 --chdir /opt/mayan-edms
  --env DJANGO_SETTINGS_MODULE=mayan.settings.production
  --limit-request-line 4094 --log-level error
  --max-requests 500 --max-requests-jitter 50
  --no-control-socket --worker-tmp-dir=/dev/shm
  --timeout 120 --worker-class gevent --workers 3 mayan.wsgi

调优要点：worker 类是 gevent（协程型，适合长连接轮询的文档管理界面）；--timeout 120 对应大文件上传/下载场景；--max-requests 500 定期回收防内存泄漏；请求行上限放宽到 4094 以容纳长检索串。

5.2 Celery worker 六队列分工

一体内 six 个 worker 的队列映射实测（进程 cmdline 摘录）：

实测要点：OCR 分双队列——常规识别走 worker_b 的 ocr，大页慢任务走 worker_d 的 ocr_slow（独享 1.5 GB 内存上限）；全部 worker 带 --prefetch-multiplier=1（防任务饿死）。队列深度可用队列管理命令观察（见运维实战篇）。

六、smart_settings 层（config.yml）

6.1 读写命令

smart_settings 提供三条管理命令（经管理命令入口执行）：

• settings_show：输出当前生效设置（运行值）
• settings_save：把修改持久化到 config.yml
• settings_revert：回退到默认/上一版本

config.yml 头部实测（含版本戳，升级时自动写 config_backup.yml）：

# Version: 4.12.2 v4.12.2-39-g16850d008cb_Wed Sep 16 10:01:41 2026
# Date and time: 2026-10-28 06:29:22.064195
ALLOWED_HOSTS:
- '*'
APPEARANCE_APP_TEMPLATE_CACHE_VERIFY: false
...

6.2 常用设置项实测摘录

OCR_AUTO_OCR: true
OCR_BACKEND: mayan.apps.ocr.backends.tesseract.Tesseract
OCR_BACKEND_ARGUMENTS:

AUTHENTICATION_LOCKOUT_ENABLED: false
AUTHENTICATION_LOCKOUT_FAILURE_LIMIT: 5
AUTHENTICATION_LOCKOUT_COOLOFF_TIME: 0.25
AUTHENTICATION_LOCKOUT_RESET_ON_SUCCESS: true
AUTHENTICATION_DISABLE_PASSWORD_RESET: false

AUTOADMIN_EMAIL: autoadmin@example.com
AUTOADMIN_PASSWORD: q1w2e3r4
AUTOADMIN_USERNAME: admin

⚠️ 安全提醒：settings_show 会明文显示 AUTOADMIN_PASSWORD 等敏感值。排查配置时不要把输出直接贴到公开渠道；演示环境的弱密码仅限隔离网络。

6.3 与环境变量的优先级

实测结论：环境变量在进程启动时注入，smart_settings 存于数据库/配置文件；同一设置两者都配置时，环境变量优先（settings_show 显示的 AUTOADMIN_PASSWORD 正是 .env 注入值）。日常运维建议：部署期参数进 .env，运行期业务参数用界面/settings_save，避免同一参数两处维护。

七、伴生服务参数（编排内置调优）

官方编排对三个伴生服务已做面向文档管理场景的预调优（编排文件实测）：

八、运行时扩展机制（MAYAN_APT_INSTALLS / MAYAN_PIP_INSTALLS）

官方入口脚本在每次启动时执行两个安装阶段（实测日志）：

Executing `os_package_installs`.   # 读 MAYAN_APT_INSTALLS，apt 安装
Executing `pip_installs`.          # 读 MAYAN_PIP_INSTALLS，pip 安装

实测案例：.env 设 MAYAN_APT_INSTALLS=tesseract-ocr-chi-sim 重建后，tesseract --list-langs 从 2 个语言包（eng/osd）变为 3 个（新增 chi_sim）。注意事项：

1. 这两个变量是每次启动都执行：已装的包会秒过，未联网时会因 apt 失败阻塞启动，离线环境应改用自定义镜像预装。
2. 安装层易失：镜像重建/升级后包会丢，依赖此机制的配置必须保留在 .env（或做持久化自定义镜像）。

九、配置验证与排障

9.1 三条验证路径

1. 看进程实值：应用内 env | grep MAYAN——验证 .env 是否真的注入。
2. 看生效设置：settings_show——验证映射后的 Django 设置值（含 smart_settings 覆盖）。
3. 看解析编排：docker compose config——验证 Compose 层变量替换结果（端口、卷、环境）。

9.2 典型坑

• 改了 .env 不生效：.env 是启动时注入，改完必须重建服务（up -d 会滚动重建受影响服务）。
• 改密码不同步：MAYAN_DATABASE_PASSWORD 等官方注释明示「仅首启前修改」；组件已初始化后再改只会导致连接失败，应按组件自身的改密流程走。
• MAYAN_FRONTEND_HTTP_PORT 在设置里搜不到：它是 Compose 层端口变量不是 Django 设置，验证走 docker compose config。
• ALLOWED_HOSTS 校验失败：设了 MAYAN_ALLOWED_HOSTS 后用未列域名访问会 400；YAML 列表写法，逗号分隔无效。
• 配置项名对不上：老文档里的部分设置名在 4.x 已变（如旧版 showsettings 命令在 4.12.2 已不存在，相应能力由 settings_show/diffsettings 承担），以 settings_show 实际输出为准。

十、参考链接

• Docker 定制章节（.env 优先原则与 compose config 验证法）：https://docs.mayan-edms.com/chapters/docker/docker_compose_customize.html
• 官方 .env 模板（2026-10-28 版）：https://gitlab.com/mayan-edms/mayan-edms/-/blob/master/docker/.env
• 官方编排文件：https://gitlab.com/mayan-edms/mayan-edms/-/blob/master/docker/docker-compose.yml
• First steps（自动管理员变量）：https://docs.mayan-edms.com/chapters/getting_started.html
• 站内互链：《Mayan EDMS Docker Compose 部署实战》、《Mayan EDMS 常用命令与运维实战》、《Mayan EDMS 介绍与选型指南》