7.1 · 配置参考（Configuration Reference）

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

项目Mayan EDMS 章节7.1 状态全文译文模块存储与持久化、配置治理、文档对象与元数据、测试、发布与运维

项目要点页2.5 参考项目项目章节目录Mayan EDMS DeepWiki 原始章节Configuration Reference 上一章7 下一章7.2

源码线索

mayan/apps/common/api_views.py
mayan/apps/common/apps.py
mayan/apps/common/classes.py
mayan/apps/common/forms.py
mayan/apps/common/links.py
mayan/apps/common/literals.py
mayan/apps/common/serializers.py
mayan/apps/common/settings.py
mayan/apps/common/tests/mixins.py
mayan/apps/common/tests/test_api.py

模块标签

存储与持久化
配置治理
文档对象与元数据
测试、发布与运维
工作流与编排

章节正文

配置参考

原始 DeepWiki 页面https://deepwiki.com/mayan-edms/Mayan-EDMS/7.1-configuration-reference

配置参考

配置系统概述

Mayan EDMS 使用一个名为"智能设置"的复杂多层配置系统，该系统支持多个配置源，并具有明确的优先级顺序。该系统围绕命名空间构建，用于组织相关设置，并为配置变更提供迁移能力。

Mayan EDMS · 配置系统概述 · 图 1

来源：mayan/apps/smart_settings/classes.py:168-417, mayan/apps/smart_settings/utils.py:119-175, mayan/settings/base.py:18-28

配置解析流程

配置系统使用严格的优先级顺序来解析设置值，这确保了环境变量可以覆盖任何其他源，从而提供安全性和部署灵活性。

Mayan EDMS · 配置解析流程 · 图 2

来源：mayan/apps/smart_settings/classes.py:403-408, mayan/apps/smart_settings/utils.py:137-175

设置命名空间

设置被组织到逻辑命名空间中，这些命名空间将相关的配置选项分组。每个命名空间可以有自己的版本和迁移类，以处理软件版本之间的配置更新。

命名空间	用途	版本管理
`django`	Django 核心框架设置	基础版本控制
`celery`	任务队列和工作进程配置	基础版本控制
`common`	应用级通用设置	高级版本控制（含迁移）
`documents`	文档管理设置	高级版本控制（含迁移）
`ocr`	OCR 处理设置	高级版本控制（含迁移）
`storage`	文件存储后端设置	高级版本控制（含迁移）

Mayan EDMS · 设置命名空间 · 图 3

来源：mayan/apps/smart_settings/classes.py:49-111, mayan/apps/common/settings.py:15-98

环境变量

所有设置都可以使用前缀为 MAYAN_ 的环境变量进行覆盖。环境变量具有最高优先级，并会被解析为 YAML 值。

关键环境变量

变量	用途	示例
`MAYAN_SECRET_KEY`	Django 用于加密签名的密钥	`your-secret-key-here`
`MAYAN_DATABASES`	数据库配置	`{"default": {"ENGINE": "django.db.backends.postgresql"}}`
`MAYAN_CELERY_BROKER_URL`	Celery 的消息代理 URL	`redis://redis:6379/0`
`MAYAN_MEDIA_ROOT`	媒体文件存储路径	`/app/media`
`MAYAN_STATIC_ROOT`	静态文件存储路径	`/app/static`
`MAYAN_DEBUG`	启用 Django 调试模式	`false`
`MAYAN_ALLOWED_HOSTS`	允许的 HTTP 主机	`["localhost", "example.com"]`

环境变量处理流程

Mayan EDMS · 环境变量处理流程 · 图 4

来源：mayan/apps/smart_settings/classes.py:328-339, mayan/apps/smart_settings/utils.py:161-174, mayan/settings/base.py:30-39

配置文件

主要的配置文件是位于媒体目录下的 config.yml。该文件以 YAML 格式存储所有非默认的设置值，并支持用于迁移的命名空间版本控制。

配置文件结构

SMART_SETTINGS_NAMESPACES:
  common:
    version: "0002"
  django:
    version: "0001"

# 数据库配置
DATABASES:
  default:
    ENGINE: "django.db.backends.postgresql"
    NAME: "mayan"
    USER: "mayan"
    PASSWORD: "password"
    HOST: "db"
    PORT: 5432

# Celery 配置
CELERY_BROKER_URL: "redis://redis:6379/0"
CELERY_RESULT_BACKEND: "redis://redis:6379/1"

# 应用设置
COMMON_PROJECT_TITLE: "My Document Management"
COMMON_DISABLED_APPS:
  - "mayan.apps.announcements"

配置文件管理

操作	管理命令	用途
保存当前配置	设置变更时自动执行	将设置持久化到 `config.yml`
备份配置	启动时自动执行	创建 `config_backup.yml`
恢复配置	`./manage.py settings_revert`	从备份恢复
查看设置	Web 界面或 API	浏览当前值

来源：mayan/apps/smart_settings/classes.py:242-285, mayan/apps/smart_settings/literals.py:3-4, mayan/apps/smart_settings/management/commands/settings_revert.py:6-18

引导设置

某些关键设置必须在 Django 应用完全初始化之前可用。这些引导设置使用一个特殊的单例系统，可以在启动过程的早期解析配置。

Mayan EDMS · 引导设置 · 图 5

引导设置类型

设置类	用途	示例
`FilesystemBootstrapSetting`	相对于 BASE_DIR 的文件系统路径	`MEDIA_ROOT`
`MediaBootstrapSetting`	相对于 MEDIA_ROOT 的路径	`CONFIGURATION_FILEPATH`
`BaseSetting`	具有默认值的标准设置	`DATABASES`, `DEBUG`

来源：mayan/apps/smart_settings/utils.py:177-250, mayan/settings/base.py:18-28

数据库配置

数据库设置既支持简单的连接参数，也支持完整的 Django 数据库配置字典。该系统提供了单独的数据库连接设置和一个完整的 DATABASES 设置。

单独的数据库设置

设置	用途	默认值
`DATABASE_ENGINE`	Django 数据库后端	`None`（使用 SQLite）
`DATABASE_NAME`	数据库名称	`None`
`DATABASE_USER`	数据库用户名	`None`
`DATABASE_PASSWORD`	数据库密码	`None`
`DATABASE_HOST`	数据库主机	`None`
`DATABASE_PORT`	数据库端口	`None`
`DATABASE_CONN_MAX_AGE`	连接最大存活时间（秒）	`0`

数据库解析逻辑

Mayan EDMS · 数据库解析逻辑 · 图 6

来源：mayan/settings/base.py:353-372, mayan/apps/smart_settings/utils.py:404-437

Celery 任务管理器设置

Celery 配置控制用于后台处理的分布式任务队列系统。设置组织在 celery 命名空间下。

核心 Celery 设置

设置	用途	默认值
`CELERY_BROKER_URL`	消息代理 URL	`memory://`
`CELERY_RESULT_BACKEND`	结果存储后端	`None`
`CELERY_BROKER_LOGIN_METHOD`	AMQP 登录方法	`AMQPLAIN`
`CELERY_BROKER_USE_SSL`	为代理连接启用 SSL	`None`

Django 设置中的 Celery 配置

引导系统还会直接在 Django 中配置额外的 Celery 设置：

# 来自 mayan/settings/base.py:287-300
CELERY_ACCEPT_CONTENT = ('json',)
CELERY_BEAT_SCHEDULE = {}
CELERY_BEAT_SCHEDULER = 'django_celery_beat.schedulers.DatabaseScheduler'
CELERY_DISABLE_RATE_LIMITS = True
CELERY_ENABLE_UTC = True
CELERY_RESULT_SERIALIZER = 'json'
CELERY_TASK_ALWAYS_EAGER = False
CELERY_TASK_CREATE_MISSING_QUEUES = True
CELERY_TASK_DEFAULT_QUEUE = 'celery'
CELERY_TASK_EAGER_PROPAGATES = True
CELERY_TASK_QUEUES = []
CELERY_TASK_ROUTES = {}
CELERY_TASK_SERIALIZER = 'json'
CELERY_TIMEZONE = 'UTC'

来源：mayan/apps/task_manager/settings.py:10-43, mayan/settings/base.py:287-300

通用应用设置

common 命名空间包含影响 Mayan EDMS 整体行为的应用级设置。

通用设置参考

设置	用途	默认值	示例
`COMMON_PROJECT_TITLE`	在 UI 中显示的应用标题	`Mayan EDMS`	`My Document System`
`COMMON_PROJECT_URL`	项目主页 URL	`https://www.mayan-edms.com`	`https://docs.example.com`
`COMMON_HOME_VIEW`	登录后的默认视图	`common:home`	`documents:document_list`
`COMMON_HOME_VIEW_DASHBOARD_NAME`	在主页视图上显示的仪表盘	`user`	`admin`
`COMMON_DISABLED_APPS`	要从安装中排除的应用	`()`	`["mayan.apps.announcements"]`
`COMMON_EXTRA_APPS`	要安装的额外应用	`()`	`["custom.apps.integration"]`
`COMMON_EXTRA_APPS_PRE`	要在核心应用之前安装的额外应用	`()`	`["custom.apps.middleware"]`
`COMMON_DISABLE_LOCAL_STORAGE`	禁用本地文件存储	`False`	`True`

应用配置流程

Mayan EDMS · 应用配置流程 · 图 7

来源：mayan/apps/common/settings.py:15-98, mayan/settings/base.py:325-351

Django 核心设置

django 命名空间包含直接对应于 Django 框架配置选项的设置。

关键 Django 设置

设置	用途	默认值
`ALLOWED_HOSTS`	允许的 HTTP Host 请求头	`['127.0.0.1', 'localhost', '[::1]']`
`DEBUG`	启用 Django 调试模式	`False`
`LANGUAGE_CODE`	默认语言代码	`en-us`
`TIME_ZONE`	默认时区	`UTC`
`DATABASES`	数据库配置字典	`{}`
`EMAIL_BACKEND`	电子邮件后端类	`django.core.mail.backends.smtp.EmailBackend`
`EMAIL_HOST`	SMTP 服务器主机名	`localhost`
`EMAIL_PORT`	SMTP 服务器端口	`25`
`EMAIL_HOST_USER`	SMTP 用户名	`''`
`EMAIL_HOST_PASSWORD`	SMTP 密码	`''`
`EMAIL_USE_TLS`	为电子邮件使用 TLS	`False`
`EMAIL_USE_SSL`	为电子邮件使用 SSL	`False`

来源：mayan/apps/smart_settings/settings.py:26-328

设置类型与校验

智能设置系统支持不同的设置类型，并具备校验能力。

设置校验流程

Mayan EDMS · 设置校验流程 · 图 8

校验函数示例

def validate_database_engine(setting, raw_value):
    """校验数据库引擎设置"""
    if raw_value and not raw_value.startswith('django.db.backends.'):
        raise ValidationError('数据库引擎必须是 Django 后端')
    return raw_value

来源：mayan/apps/smart_settings/classes.py:397-401, mayan/apps/smart_settings/tests/mocks.py:31-35

管理命令

智能设置系统提供了用于配置操作的管理命令。

设置管理命令

命令	用途	用法
`settings_revert`	从备份恢复配置	`./manage.py settings_revert`

Web 界面

设置也可以通过 Web 界面进行管理：

命名空间列表：在 /settings/namespaces/ 查看所有设置命名空间
命名空间详情：在 /settings/namespaces/{namespace}/ 查看命名空间中的设置
设置编辑：在 /settings/namespaces/settings/{setting}/edit/ 编辑单个设置

注意：当 COMMON_DISABLE_LOCAL_STORAGE 为 True 时，通过 Web 界面的设置编辑功能会被禁用。

来源：mayan/apps/smart_settings/management/commands/settings_revert.py:6-18, mayan/apps/smart_settings/views.py:18-101, mayan/apps/smart_settings/urls.py:7-20

测试配置

Mayan EDMS 包含一个专门的测试配置，该配置会覆盖许多设置，以优化测试执行的性能和隔离性。

测试设置覆盖

设置	测试值	用途
`CELERY_TASK_ALWAYS_EAGER`	`True`	同步执行任务
`CELERY_BROKER_URL`	`memory://`	使用内存代理
`COMMON_HOME_VIEW_DASHBOARD_NAME`	`None`	禁用仪表盘
`DOCUMENT_PARSING_AUTO_PARSING`	`False`	禁用自动解析
`OCR_AUTO_OCR`	`False`	禁用自动 OCR
`SEARCH_BACKEND`	`TestSearchBackend`	使用测试搜索后端
`PASSWORD_HASHERS`	`MD5PasswordHasher`	使用快速密码哈希

来源：mayan/settings/testing/base.py:1-60