Конфигурация сервера¶
Используя стандартный образ Docker, вся необходимая конфигурация может быть выполнена через браузер. Однако в зависимости от развертывания может потребоваться настроить конфигурацию сервера.
Эта страница перечисляет все методы изменения конфигурации и все существующие параметры конфигурации.
Конфигурационный файл против переменных окружения¶
Для настроек вы можете использовать либо конфигурационный файл, либо переменные окружения.
Когда вы используете настройку на основе Docker Compose, вы можете включить конфигурационный файл, добавив следующий элемент списка под ключом volumes: в блоке grampsweb::
- /path/to/config.cfg:/app/config/config.cfg
/path/to/config.cfg — это путь к конфигурационному файлу в файловой системе вашего сервера (правая сторона ссылается на путь в контейнере и не должна изменяться).
При использовании переменных окружения,
- добавьте префикс
GRAMPSWEB_к каждому имени настройки, чтобы получить имя переменной окружения - Используйте двойные подчеркивания для вложенных настроек словаря, например,
GRAMPSWEB_THUMBNAIL_CACHE_CONFIG__CACHE_DEFAULT_TIMEOUTустановит значение параметра конфигурацииTHUMBNAIL_CACHE_CONFIG['CACHE_DEFAULT_TIMEOUT']
Обратите внимание, что параметры конфигурации, установленные через окружение, имеют приоритет над параметрами в конфигурационном файле. Если оба присутствуют, переменная окружения "выигрывает".
Устаревшие переменные окружения без префикса
По историческим причинам несколько настроек – TREE, SECRET_KEY, USER_DB_URI, POSTGRES_USER, POSTGRES_PASSWORD, MEDIA_BASE_DIR, SEARCH_INDEX_DIR, EMAIL_HOST, EMAIL_PORT, EMAIL_HOST_USER, EMAIL_HOST_PASSWORD, DEFAULT_FROM_EMAIL, BASE_URL и STATIC_PATH – все еще могут быть установлены через переменную окружения без префикса GRAMPSWEB_. Это устарело, вызывает предупреждение при запуске и перестанет работать в будущих версиях. Всегда используйте префиксированный вариант, например, GRAMPSWEB_TREE вместо TREE.
Обратите внимание, что это касается только переменных окружения. В конфигурационном файле имена настроек всегда используются без префикса.
Проверка устаревших опций
Устаревшие параметры конфигурации, от которых ваш сервер все еще зависит – такие как устаревшие переменные окружения, SEARCH_INDEX_DIR или EMAIL_USE_TLS – регистрируются как предупреждения при запуске. Начиная с Gramps Web API 3.22, они также перечисляются, вместе с их заменой и версией, в которой поддержка будет удалена, в верхней части страницы Информация о системе (доступно через значок пользователя в верхней панели приложения), когда вы вошли в систему как администратор.
Существующие параметры конфигурации¶
Существуют следующие параметры конфигурации.
Обязательные настройки¶
| Ключ | Описание |
|---|---|
TREE |
Имя базы данных семейного дерева для использования. Показать доступные деревья с помощью gramps -l. Если дерево с этим именем не существует, будет создано новое пустое. |
SECRET_KEY |
Секретный ключ для Flask. Секрет не должен быть общедоступным. Изменение его аннулирует все токены доступа. |
USER_DB_URI |
URL базы данных пользовательской базы данных. Разрешен любой URL, совместимый с SQLAlchemy. |
Info
Вы можете сгенерировать безопасный секретный ключ, например, с помощью команды
python3 -c "import secrets;print(secrets.token_urlsafe(32))"
Необязательные настройки¶
| Ключ | Описание |
|---|---|
MEDIA_BASE_DIR |
Путь, который следует использовать в качестве базового каталога для медиафайлов, переопределяя базовый каталог медиа, установленный в Gramps. При использовании S3 должен иметь вид s3://<bucket_name> |
TREE_ID |
Имя каталога базы данных семейного дерева, которое следует использовать в режиме одного дерева (когда TREE не установлено в *). Когда установлено, сервер идентифицирует дерево по его имени каталога, а не по его отображаемому имени, что более надежно при переименовании. Обязательно, если вы хотите переименовать дерево через API. Имя каталога можно найти через GET /api/trees/- (поле id). |
SEARCH_INDEX_DB_URI |
URL базы данных для поискового индекса. Разрешены только sqlite или postgresql в качестве бэкендов. По умолчанию sqlite:///indexdir/search_index.db, создавая файл SQLite в папке indexdir относительно пути, где выполняется скрипт. |
SEARCH_INDEX_DIR |
Устарело (используйте SEARCH_INDEX_DB_URI вместо этого). Каталог, содержащий поисковый индекс. Если установлен, когда SEARCH_INDEX_DB_URI не установлен, URL поискового индекса выводится как sqlite:///<SEARCH_INDEX_DIR>/search_index.db. |
STATIC_PATH |
Путь для обслуживания статических файлов (например, статический веб-фронтенд) |
BASE_URL |
Базовый URL, по которому можно получить доступ к API (например, https://mygramps.mydomain.com/). Это необходимо, например, для построения правильных ссылок для сброса пароля. |
CORS_ORIGINS |
Происхождения, с которых разрешены CORS-запросы. По умолчанию все запрещены. Используйте "*" для разрешения запросов с любого домена. |
EMAIL_HOST |
Хост SMTP-сервера (например, для отправки писем для сброса пароля) |
EMAIL_PORT |
Порт SMTP-сервера. По умолчанию 465 |
EMAIL_HOST_USER |
Имя пользователя SMTP-сервера |
EMAIL_HOST_PASSWORD |
Пароль SMTP-сервера |
EMAIL_USE_TLS |
Устарело (используйте EMAIL_USE_SSL или EMAIL_USE_STARTTLS вместо этого). Логическое значение, указывающее, следует ли использовать TLS для отправки писем. По умолчанию True. При использовании STARTTLS установите это значение в False и используйте порт, отличный от 25. |
EMAIL_USE_SSL |
Логическое значение, указывающее, следует ли использовать неявный SSL/TLS для SMTP (v3.6.0+). По умолчанию True, если EMAIL_USE_TLS не установлен явно. Обычно используется с портом 465. |
EMAIL_USE_STARTTLS |
Логическое значение, указывающее, следует ли использовать явный STARTTLS для SMTP (v3.6.0+). По умолчанию False. Обычно используется с портом 587 или 25. |
DEFAULT_FROM_EMAIL |
Адрес "От" для автоматических писем |
THUMBNAIL_CACHE_CONFIG |
Словарь с настройками для кэша миниатюр. См. Flask-Caching для возможных настроек. |
REQUEST_CACHE_CONFIG |
Словарь с настройками для кэша запросов. См. Flask-Caching для возможных настроек. |
PERSISTENT_CACHE_CONFIG |
Словарь с настройками для постоянного кэша, используемого, например, для телеметрии. См. Flask-Caching для возможных настроек. |
CELERY_CONFIG |
Настройки для очереди фоновых задач Celery. См. Celery для возможных настроек. |
REPORT_DIR |
Временный каталог, в котором будет храниться вывод выполнения отчетов Gramps |
EXPORT_DIR |
Временный каталог, в котором будет храниться вывод экспорта базы данных Gramps |
REGISTRATION_DISABLED |
Если True, запрещает регистрацию новых пользователей (по умолчанию False) |
DISABLE_TELEMETRY |
Если True, отключает телеметрию статистики (по умолчанию False). См. телеметрия для получения подробной информации. |
PILLOW_MAX_IMAGE_PIXELS |
Устанавливает параметр PIL.Image.MAX_IMAGE_PIXELS, который указывает количество пикселей, которое может содержать обрабатываемое изображение. См. документацию для получения подробной информации. |
MAX_THUMBNAIL_FILE_BYTES |
Устанавливает жесткий максимальный размер файла для миниатюр. По умолчанию 50 * 1024 * 1024 (50 МБ). Увеличение этого значения может значительно увеличить использование памяти и привести к сбоям из-за нехватки памяти или потере данных, если большие файлы распаковываются в памяти. |
Info
При использовании переменных окружения для конфигурации логические параметры, такие как EMAIL_USE_SSL, должны быть либо строкой true, либо false (регистр имеет значение!).
Настройки для баз данных PostgreSQL¶
Эти настройки обязательны, если ваши семейные деревья размещены в базе данных PostgreSQL с использованием дополнения SharedPostgreSQL.
| Ключ | Описание |
|---|---|
POSTGRES_USER |
Имя пользователя для подключения к базе данных |
POSTGRES_PASSWORD |
Пароль для пользователя базы данных |
Настройки, относящиеся к размещению нескольких деревьев¶
Следующие настройки актуальны при размещении нескольких деревьев.
| Ключ | Описание |
|---|---|
MEDIA_PREFIX_TREE |
Логическое значение, указывающее, следует ли использовать отдельную подпапку для медиафайлов каждого дерева. По умолчанию False, но настоятельно рекомендуется использовать True в настройках с несколькими деревьями. |
NEW_DB_BACKEND |
Бэкенд базы данных для новых семейных деревьев. Должен быть одним из sqlite или sharedpostgresql. По умолчанию sqlite. Значение postgresql все еще принимается, но устарело, так как бэкенд PostgreSQL будет удален в будущей версии. |
POSTGRES_HOST |
Имя хоста сервера PostgreSQL, используемого для создания новых деревьев при использовании настройки с несколькими деревьями с бэкендом SharedPostgreSQL |
POSTGRES_PORT |
Порт сервера PostgreSQL, используемого для создания новых деревьев при использовании настройки с несколькими деревьями с бэкендом SharedPostgreSQL |
Настройки для аутентификации OIDC¶
Эти настройки необходимы, если вы хотите использовать аутентификацию OpenID Connect (OIDC) с внешними провайдерами. Для получения подробных инструкций по настройке и примеров см. Аутентификация OIDC.
| Ключ | Описание |
|---|---|
OIDC_ENABLED |
Логическое значение, указывающее, следует ли включить аутентификацию OIDC. По умолчанию False. |
OIDC_ISSUER |
URL-адрес провайдера OIDC (для пользовательских провайдеров OIDC) |
OIDC_CLIENT_ID |
Идентификатор клиента OAuth (для пользовательских провайдеров OIDC) |
OIDC_CLIENT_SECRET |
Секрет клиента OAuth (для пользовательских провайдеров OIDC) |
OIDC_NAME |
Пользовательское отображаемое имя для провайдера. По умолчанию "OIDC" |
OIDC_SCOPES |
OAuth области. По умолчанию "openid email profile" |
OIDC_USERNAME_CLAIM |
Утверждение, используемое для имени пользователя. По умолчанию "preferred_username" |
OIDC_OPENID_CONFIG_URL |
Необязательно: URL-адрес конечной точки конфигурации OpenID Connect (если не используется стандартный /.well-known/openid-configuration) |
OIDC_PKCE |
Логическое значение, указывающее, следует ли использовать PKCE. Если не установлено, PKCE используется, когда документ обнаружения провайдера перечисляет S256. См. PKCE |
OIDC_DISABLE_LOCAL_AUTH |
Логическое значение, указывающее, следует ли отключить локальную аутентификацию по имени пользователя/паролю. По умолчанию False |
OIDC_AUTO_REDIRECT |
Логическое значение, указывающее, следует ли автоматически перенаправлять на OIDC, когда настроен только один провайдер. По умолчанию False |
Встроенные провайдеры OIDC¶
Для встроенных провайдеров (Google, Microsoft) используйте следующие настройки:
| Ключ | Описание |
|---|---|
OIDC_GOOGLE_CLIENT_ID |
Идентификатор клиента для Google OAuth |
OIDC_GOOGLE_CLIENT_SECRET |
Секрет клиента для Google OAuth |
OIDC_MICROSOFT_CLIENT_ID |
Идентификатор клиента для Microsoft OAuth |
OIDC_MICROSOFT_CLIENT_SECRET |
Секрет клиента для Microsoft OAuth |
OIDC_GOOGLE_PKCE |
Логическое значение, настройка PKCE для Google, см. PKCE |
OIDC_MICROSOFT_PKCE |
Логическое значение, настройка PKCE для Microsoft, см. PKCE |
Сопоставление ролей OIDC¶
Эти настройки позволяют сопоставить группы/роли OIDC из вашего провайдера идентификации с ролями пользователей Gramps Web:
| Ключ | Описание |
|---|---|
OIDC_ROLE_CLAIM |
Имя утверждения в токене OIDC, которое содержит группы/роли пользователя. По умолчанию "groups" |
OIDC_GROUP_ADMIN |
Имя группы/роли из вашего провайдера OIDC, которое сопоставляется с ролью "Администратор" Gramps |
OIDC_GROUP_OWNER |
Имя группы/роли из вашего провайдера OIDC, которое сопоставляется с ролью "Владелец" Gramps |
OIDC_GROUP_EDITOR |
Имя группы/роли из вашего провайдера OIDC, которое сопоставляется с ролью "Редактор" Gramps |
OIDC_GROUP_CONTRIBUTOR |
Имя группы/роли из вашего провайдера OIDC, которое сопоставляется с ролью "Участник" Gramps |
OIDC_GROUP_MEMBER |
Имя группы/роли из вашего провайдера OIDC, которое сопоставляется с ролью "Участник" Gramps |
OIDC_GROUP_GUEST |
Имя группы/роли из вашего провайдера OIDC, которое сопоставляется с ролью "Гость" Gramps |
Настройки только для функций ИИ¶
Эти настройки необходимы, если вы хотите использовать функции, основанные на ИИ, такие как чат или семантический поиск.
| Ключ | Описание |
|---|---|
LLM_BASE_URL |
Базовый URL для совместимого с OpenAI API чата. По умолчанию None, что использует API OpenAI. |
LLM_MODEL |
Модель, которую следует использовать для совместимого с OpenAI API чата. Если не установлено (по умолчанию), чат отключен. Начиная с версии 3.6.0, помощник ИИ использует Pydantic AI с возможностями вызова инструментов. |
VECTOR_EMBEDDING_MODEL |
Модель, которую следует использовать для векторных встраиваний семантического поиска. При использовании локальной модели это должно быть название модели Sentence Transformers. При использовании удаленного API (см. VECTOR_EMBEDDING_BASE_URL) это название модели, передаваемое удаленному провайдеру. Если не установлено (по умолчанию), семантический поиск и чат отключены. |
VECTOR_EMBEDDING_BASE_URL |
Базовый URL для удаленного API встраивания, совместимого с OpenAI (например, Ollama, OpenAI, LiteLLM). Если не установлено (по умолчанию), используется локальная модель Sentence Transformers. См. Использование удаленного API встраивания для получения подробной информации. |
VECTOR_EMBEDDING_API_KEY |
Ключ API для аутентифицированных удаленных провайдеров встраивания. Необходим только при установке VECTOR_EMBEDDING_BASE_URL и если провайдер требует аутентификации. |
LLM_MAX_CONTEXT_LENGTH |
Ограничение по количеству символов для контекста семейного дерева, предоставляемого LLM. По умолчанию 50000. |
LLM_SYSTEM_PROMPT |
Пользовательский системный запрос для помощника чата LLM (v3.6.0+). Если не установлено, используется стандартный оптимизированный для генеалогии запрос. |
Пример конфигурационного файла¶
Минимальный конфигурационный файл для продакшена может выглядеть так: ```python TREE="Мое семейное дерево" BASE_URL="https://mytree.example.com" SECRET_KEY="..." # ваш секретный ключ USER_DB_URI="sqlite:////path/to/users.sqlite" EMAIL_HOST="mail.example.com" EMAIL_PORT=465 EMAIL_USE_SSL=True # Используйте неявный SSL для порта 465 EMAIL_HOST_USER="gramps@example.com" EMAIL_HOST_PASSWORD="..." # ваш SMTP пароль DEFAULT_FROM_EMAIL="gramps@example.com"