7.1 · 配置参考（Configuration Reference）

配置参考（中文译文）

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

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

翻译模型：deepseek-chat

原文字符数：20786

项目：Mayan EDMS (mayan-edms)

---

配置参考

相关源文件

以下文件被用作生成此 Wiki 页面的上下文：

• 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
• mayan/apps/common/tests/test_links.py
• mayan/apps/common/urls.py
• mayan/apps/common/views.py
• mayan/apps/django_gpg/serializers.py
• mayan/apps/document_parsing/serializers.py
• mayan/apps/events/api_views.py
• mayan/apps/events/tests/test_api.py
• mayan/apps/metadata/tests/__init__.py
• mayan/apps/permissions/links.py
• mayan/apps/smart_settings/apps.py
• mayan/apps/smart_settings/classes.py
• mayan/apps/smart_settings/icons.py
• mayan/apps/smart_settings/links.py
• mayan/apps/smart_settings/literals.py
• mayan/apps/smart_settings/management/commands/settings_revert.py
• mayan/apps/smart_settings/permissions.py
• mayan/apps/smart_settings/settings.py
• mayan/apps/smart_settings/tests/literals.py
• mayan/apps/smart_settings/tests/mixins.py
• mayan/apps/smart_settings/tests/mocks.py
• mayan/apps/smart_settings/tests/test_classes.py
• mayan/apps/smart_settings/tests/test_utils.py
• mayan/apps/smart_settings/tests/test_views.py
• mayan/apps/smart_settings/urls.py
• mayan/apps/smart_settings/utils.py
• mayan/apps/smart_settings/views.py
• mayan/apps/task_manager/literals.py
• mayan/apps/task_manager/locale/bs/LC_MESSAGES/django.po
• mayan/apps/task_manager/locale/cs/LC_MESSAGES/django.po
• mayan/apps/task_manager/locale/el/LC_MESSAGES/django.po
• mayan/apps/task_manager/settings.py
• mayan/settings/base.py
• mayan/settings/testing/base.py

本文档提供了 Mayan EDMS 中所有可用配置设置的全面参考。它涵盖了智能设置系统、环境变量、配置文件，以及设置在整个应用生命周期中的解析和管理方式。

有关特定于部署的配置指南，请参见配置管理。有关开发环境设置，请参见开发设置。

配置系统概述

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

graph TD
    subgraph "配置源（按优先级）"
        ENV["环境变量<br/>MAYAN_*"]
        CONFIG["配置文件<br/>config.yml"]
        DJANGO["Django 设置<br/>settings.py"]
        DEFAULT["默认值"]
    end

    subgraph "智能设置系统"
        NAMESPACE["SettingNamespace"]
        SETTING["Setting"]
        SINGLETON["SettingNamespaceSingleton"]
    end

    subgraph "引导流程"
        BOOTSTRAP["引导设置"]
        GLOBALS["Django 全局变量"]
        READY["应用就绪"]
    end

    ENV --> SETTING
    CONFIG --> SETTING
    DJANGO --> SETTING
    DEFAULT --> SETTING

    SETTING --> NAMESPACE
    NAMESPACE --> SINGLETON

    SINGLETON --> BOOTSTRAP
    BOOTSTRAP --> GLOBALS
    GLOBALS --> READY

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

配置解析流程

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

flowchart TD
    START["设置值请求"]

    CHECK_ENV["检查环境变量<br/>MAYAN_{SETTING_NAME}"]
    ENV_FOUND{"环境变量<br/>是否找到？"}
    YAML_PARSE_ENV["解析 YAML 值"]

    CHECK_CONFIG["检查配置文件<br/>config.yml"]
    CONFIG_FOUND{"配置文件中<br/>是否有该设置？"}
    MIGRATE["应用迁移"]

    CHECK_DJANGO["检查 Django 设置<br/>settings.py"]
    DJANGO_FOUND{"Django 设置中<br/>是否有该设置？"}

    USE_DEFAULT["使用默认值"]

    VALIDATE["校验设置"]
    CACHE["缓存结果"]
    RETURN["返回值"]

    START --> CHECK_ENV
    CHECK_ENV --> ENV_FOUND
    ENV_FOUND -->|是| YAML_PARSE_ENV
    ENV_FOUND -->|否| CHECK_CONFIG

    YAML_PARSE_ENV --> VALIDATE

    CHECK_CONFIG --> CONFIG_FOUND
    CONFIG_FOUND -->|是| MIGRATE
    CONFIG_FOUND -->|否| CHECK_DJANGO

    MIGRATE --> VALIDATE

    CHECK_DJANGO --> DJANGO_FOUND
    DJANGO_FOUND -->|是| VALIDATE
    DJANGO_FOUND -->|否| USE_DEFAULT

    USE_DEFAULT --> VALIDATE
    VALIDATE --> CACHE
    CACHE --> RETURN

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

设置命名空间

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

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

graph LR
    subgraph "设置命名空间结构"
        NS["SettingNamespace<br/>名称：'common'<br/>标签：'Common'<br/>版本：'0002'"]

        S1["Setting<br/>COMMON_PROJECT_TITLE"]
        S2["Setting<br/>COMMON_HOME_VIEW"]
        S3["Setting<br/>COMMON_DISABLED_APPS"]

        MIG["SettingNamespaceMigration<br/>migrate()"]
    end

    NS --> S1
    NS --> S2
    NS --> S3
    NS --> MIG

    S1 --> |"有默认值"| D1["'Mayan EDMS'"]
    S2 --> |"有默认值"| D2["'common:home'"]
    S3 --> |"有默认值"| D3["()"]

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

环境变量处理流程

sequenceDiagram
    participant App as "应用"
    participant Env as "环境"
    participant YAML as "YAML 解析器"
    participant Setting as "设置对象"

    App->>Setting: 请求设置值
    Setting->>Env: 检查 MAYAN_{SETTING_NAME}
    Env-->>Setting: 环境变量值
    Setting->>YAML: 解析为 YAML
    YAML-->>Setting: 解析后的值
    Setting->>Setting: 应用校验
    Setting-->>App: 最终值

来源：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 应用完全初始化之前可用。这些引导设置使用一个特殊的单例系统，可以在启动过程的早期解析配置。

graph TB
    subgraph "引导设置流程"
        START["应用启动"]
        SINGLETON["SettingNamespaceSingleton<br/>创建"]

        subgraph "关键设置"
            MEDIA["MEDIA_ROOT"]
            CONFIG_PATH["CONFIGURATION_FILEPATH"]
            APPS["COMMON_DISABLED_APPS<br/>COMMON_EXTRA_APPS"]
        end

        LOAD_CONFIG["加载 config.yml"]
        UPDATE_GLOBALS["更新 Django 全局变量"]
        DJANGO_READY["Django 就绪"]
    end

    START --> SINGLETON
    SINGLETON --> MEDIA
    SINGLETON --> CONFIG_PATH
    SINGLETON --> APPS

    MEDIA --> LOAD_CONFIG
    CONFIG_PATH --> LOAD_CONFIG
    LOAD_CONFIG --> UPDATE_GLOBALS
    APPS --> UPDATE_GLOBALS
    UPDATE_GLOBALS --> DJANGO_READY

引导设置类型

设置类	用途	示例
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

数据库解析逻辑

flowchart TD
    CHECK_DATABASES["检查 DATABASES 设置"]
    DATABASES_SET{"DATABASES<br/>是否已配置？"}

    CHECK_ENGINE["检查 DATABASE_ENGINE"]
    ENGINE_SET{"DATABASE_ENGINE<br/>是否已设置？"}

    BUILD_CONFIG["从单独设置<br/>构建数据库配置"]
    USE_SQLITE["使用 SQLite 默认值<br/>db.sqlite3 位于 MEDIA_ROOT"]

    FINAL_CONFIG["最终数据库配置"]

    CHECK_DATABASES --> DATABASES_SET
    DATABASES_SET -->|是| FINAL_CONFIG
    DATABASES_SET -->|否| CHECK_ENGINE

    CHECK_ENGINE --> ENGINE_SET
    ENGINE_SET -->|是| BUILD_CONFIG
    ENGINE_SET -->|否| USE_SQLITE

    BUILD_CONFIG --> FINAL_CONFIG
    USE_SQLITE --> FINAL_CONFIG

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

应用配置流程

sequenceDiagram
    participant Base as "settings/base.py"
    participant Common as "通用设置"
    participant Apps as "INSTALLED_APPS"
    participant Validation as "校验"

    Base->>Common: 加载 COMMON_* 设置
    Base->>Apps: 构建基础 INSTALLED_APPS
    Common-->>Base: COMMON_EXTRA_APPS_PRE
    Base->>Apps: 前置添加额外应用
    Common-->>Base: COMMON_EXTRA_APPS
    Base->>Apps: 追加额外应用
    Common-->>Base: COMMON_DISABLED_APPS
    Base->>Apps: 移除禁用的应用
    Base->>Validation: 检查冲突
    Validation-->>Base: 校验后的应用列表

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

设置类型与校验

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

设置校验流程

graph TD
    subgraph "设置值处理"
        INPUT["原始设置值"]
        VALIDATION["校验函数"]
        VALID{"校验<br/>是否通过？"}
        CACHE["缓存有效值"]
        ERROR["ValidationError"]
        POST_EDIT["编辑后函数"]
        FINAL["最终值"]
    end

    INPUT --> VALIDATION
    VALIDATION --> VALID
    VALID -->|是| CACHE
    VALID -->|否| ERROR
    CACHE --> POST_EDIT
    POST_EDIT --> FINAL

校验函数示例

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