Подробная конфигурация
Конфигурация aihelpme.ru состоит из четырёх слоёв, приоритет — от низкого к высокому:
| Слой | Расположение | Назначение |
|---|---|---|
| Основной файл конфигурации | config/config.yaml | Структурированные значения по умолчанию, поставляются вместе с образом |
| Шаблоны / пресеты | config/prompt_templates/*.yaml, builtin_agents.yaml, agent_type_presets.yaml, builtin_models.yaml, models.json | Наложение промптов, встроенных Agent, встроенных моделей и каталога провайдеров моделей |
| Переменные окружения | .env / окружение контейнера | Переопределение уровня развёртывания; после изменения нужен перезапуск |
| Системные настройки времени выполнения | таблица system_settings в базе данных, интерфейс — «Настройки → Система» | Поддерживаемые настройки можно менять на лету; они приоритетнее переменных окружения, большинство применяется сразу |
Режим регистрации, политики и квоты пространств, белый список SSRF, параллелизм задач и пределы параллелизма моделей поддерживают настройку во время выполнения. После изменения в консоли значения в базе данных приоритетнее переменных окружения; только сброс настройки (DELETE /api/v1/system/admin/settings/:key) возвращает использование переменных окружения или встроенных значений по умолчанию. Если переменная окружения не действует, сначала проверьте, нет ли для неё настройки времени выполнения. Полный список настроек — в разделе Управление платформой и системный администратор.
Структура основной конфигурации определена в internal/config/config.go. Ниже описаны значения и условия применения каждой настройки и переменной окружения.
Механизм загрузки конфигурации
Порядок работы LoadConfig() из internal/config/config.go:
- viper последовательно ищет
config.yaml: текущий каталог →./config→$HOME/.appname→/etc/appname/; - подстановка переменных окружения: содержимое файла обрабатывается регулярным выражением,
${ENV_VAR}заменяется значением одноимённой переменной окружения; если переменная не задана, литерал${ENV_VAR}остаётся как есть (так проще заметить ошибку конфигурации); - у viper включён
AutomaticEnv(), а разделитель ключей.отображается на_(то естьserver.portможно переопределить переменной окруженияSERVER_PORT); - из
config/prompt_templates/*.yamlзагружаются шаблоны промптов и по полюxxx_prompt_idзаполняются обратно в конфигурацию conversation (backfillConversationDefaults); - загружаются
builtin_agents.yaml(встроенные Agent) иagent_type_presets.yaml(пресеты типов Agent), разрешаются ссылкиsystem_prompt_id; - применяются переопределения из переменных окружения (группы OIDC, Agent, KnowledgeBase, Auth/Tenant, Audit) и выполняется проверка
ValidateConfig.
Разбор config/config.yaml по секциям
server (ServerConfig)
| Имя | Тип | Значение по умолчанию | Описание |
|---|---|---|---|
server.port | int | 8080 | Порт прослушивания HTTP, допустимый диапазон 1–65535 |
server.host | string | "0.0.0.0" | Адрес прослушивания |
server.log_path | string | пусто | Путь к файлу журнала (можно также задать переменной окружения LOG_PATH) |
server.shutdown_timeout | duration | 30s | Общий бюджет корректной остановки. Общий для дренажа соединений и очистки ресурсов; по умолчанию 5s оставляется на очистку |
conversation (ConversationConfig) — конвейер поиска и ответов
| Имя | Тип | Значение по умолчанию (config.yaml) | Описание |
|---|---|---|---|
max_rounds | int | 5 | Сколько раундов истории переносится в контекст |
keyword_threshold | float | 0.3 | Минимальный балл поиска по ключевым словам |
embedding_top_k | int | 30 | Число возвращаемых результатов векторного поиска (>=0) |
vector_threshold | float | 0.2 | Порог схожести векторов (0–1) |
rerank_top_k | int | 30 | Число, оставляемое после переранжирования |
rerank_threshold | float | 0.3 | Минимальный балл переранжирования (-10–10) |
fallback_strategy | string | "model" | Стратегия при пустой выборке: model (отдать на откуп модели) или фиксированный ответ |
fallback_response | string | "Sorry, I am unable to answer this question." | Текст фиксированного ответа |
enable_rewrite | bool | true | Разрешение местоимений в многораундовом диалоге / переписывание запроса |
enable_query_expansion | bool | true | Расширение запроса |
enable_rerank | bool | true | Включить Rerank |
fallback_prompt_id | string | "default_fallback_prompt" | ID шаблона промпта запасного ответа (prompt_templates/fallback.yaml, mode:"model") |
rewrite_prompt_id | string | "default_rewrite" | ID шаблона переписывания (system-часть content + user-часть user) |
generate_summary_prompt_id | string | "default_summary" | ID шаблона профиля документа (краткое резюме + gist/тема/тип/типичные вопросы, вывод JSON) |
generate_kb_description_prompt_id | string | "default_kb_description" | ID шаблона описания базы знаний (на входе — агрегат профилей документов, а не их текст) |
generate_session_title_prompt_id | string | "default_session_title" | ID шаблона генерации заголовка сессии |
extract_entities_prompt_id / extract_relationships_prompt_id | string | "default_extract_entities" / "default_extract_relationships" | ID шаблонов извлечения графа (graph_extraction.yaml) |
generate_questions_prompt_id | string | "default_generate_questions" | ID шаблона предварительной генерации вопросов |
conversation.summary (SummaryConfig, параметры генерации ответа):
| Имя | Тип | Значение по умолчанию | Описание |
|---|---|---|---|
max_input_chars | int | 8192 | Максимальное число символов, передаваемых в LLM. Для профиля документа достаточно начала, чтобы определить тему, 8k хватает; старые значения 16384/24576 кратно увеличивают стоимость резюме каждого документа |
temperature | float | 0.3 | Температура генерации |
repeat_penalty | float | 1.0 | Штраф за повтор |
max_completion_tokens | int | 1024 | Максимум генерируемых токенов (все поля JSON-профиля короткие) |
no_match_prefix | string | thinking\n</think>\nNO_MATCH | Если вывод модели начинается с этого префикса, он считается «промахом» и запускает fallback |
prompt_id | string | "default_kb" | ID шаблона системного промпта (system_prompt.yaml) |
context_template_id | string | "default_context" | ID шаблона сборки контекста (context_template.yaml) |
max_tokens / top_k / top_p / frequency_penalty / presence_penalty / seed / thinking | разные | не заданы | Дополнительные параметры сэмплинга, передаваемые модели; thinking имеет тип *bool и управляет режимом рассуждения |
knowledge_base (KnowledgeBaseConfig) — глобальные блоки по умолчанию
| Имя | Тип | Значение по умолчанию | Описание |
|---|---|---|---|
chunk_size | int | 512 | Размер блока по умолчанию (>0 и > overlap) |
chunk_overlap | int | 50 | Перекрытие блоков |
split_markers | []string | ["\n\n", "\n", "。"] | Маркеры разделения |
keep_separator | bool | false | Сохранять разделители |
document_process_timeout | duration | 2h | Общий тайм-аут задачи обработки одного документа (переопределяется env WEKNORA_DOCUMENT_PROCESS_TIMEOUT) |
docreader_call_timeout | duration | 30m | Тайм-аут одного RPC DocReader (env WEKNORA_DOCREADER_CALL_TIMEOUT), должен быть меньше предыдущей величины |
image_processing.enable_multimodal | bool | true | Включать мультимодальную обработку изображений при загрузке (OCR/Caption) |
ChunkingConfigкаждой базы знаний переопределяет эти глобальные значения по умолчанию.
extract (ExtractManagerConfig) — шаблоны извлечения графа знаний
extract.extract_graph / extract.extract_entity / extract.fabri_text задают пояснительный текст извлечения графа (description), разрешённые метки отношений (tags, по умолчанию Author, Alias) и примеры few-shot (examples: text + node + relation). «Пробное извлечение / генерация примера текста» в мастере инициализации использует эти конфигурации (%s в fabri_text.with_tag / with_no_tag заменяется списком меток).
tenant (TenantConfig)
| Имя | Тип | Значение по умолчанию | Описание |
|---|---|---|---|
enable_cross_tenant_access | bool | false | Разрешить пользователям с CanAccessAllTenants доступ между пространствами (можно включить во внутренней сети) |
enable_rbac | *bool | true | Обязательная проверка ролей пространства; явное false включает «серый» режим: проверки ролей внутри пространства только логируются, не блокируют, а доступ между пространствами по-прежнему блокируется (env WEKNORA_TENANT_ENABLE_RBAC) |
max_owned_per_user | int | 0 (используется значение handler по умолчанию) | Верхняя граница числа пространств, которые не-супер-админ может создать сам; <0 отключает ограничение (env WEKNORA_TENANT_MAX_OWNED_PER_USER) |
self_service_creation_enabled | *bool | true | Может ли обычный пользователь создавать собственные пространства (env WEKNORA_TENANT_SELF_SERVICE_CREATION_ENABLED) |
default_session_name / default_session_title / default_session_description | string | пусто | Текст по умолчанию для новой сессии |
Секции, поддерживаемые структурой, но не записанные в файл по умолчанию
Приведённые ниже секции присутствуют в структуре Config и могут быть при необходимости добавлены в config.yaml (для большинства есть и вход через переменные окружения):
| Секция | Структура | Ключевые поля и значения по умолчанию |
|---|---|---|
auth | AuthConfig | registration_mode: self_serve (по умолчанию, открытая регистрация) / invite_register (только по приглашениям) / invite_only (регистрация запрещена, используется при DISABLE_REGISTRATION=true); default_tenant_mode: create_personal (по умолчанию) / tenantless |
audit | AuditConfig | retention_days: число дней хранения журнала аудита, при опущенной секции — 90; 0 отключает очистку; <0 вызывает ошибку проверки (env WEKNORA_AUDIT_RETENTION_DAYS) |
oidc_auth | OIDCAuthConfig | enable, issuer_url, jwks_uri, discovery_url (по умолчанию из issuer собирается /.well-known/openid-configuration), client_id, client_secret, authorization_endpoint, token_endpoint, user_info_endpoint, scopes (по умолчанию openid profile email), user_info_mapping.username (по умолчанию name) / email (по умолчанию email); всё переопределяется переменными окружения OIDC_AUTH_* |
agent | AgentConfig | llm_call_timeout: тайм-аут одного вызова LLM в секундах (по умолчанию 120, env WEKNORA_AGENT_LLM_TIMEOUT); tool_approval_timeout_seconds: ожидание ручного подтверждения инструмента MCP (по умолчанию 600, env WEKNORA_AGENT_TOOL_APPROVAL_TIMEOUT) |
im | IMConfig | Параллелизм QA каналов IM: workers (5), global_max_workers (0 = без ограничения, нужен Redis), max_queue_size (50), max_per_user (3), rate_limit_window (60s), rate_limit_max (10) |
docreader | DocReaderConfig | addr (адрес gRPC, например docreader:50051, либо base URL HTTP), transport: grpc (по умолчанию) / http; обычно используются env DOCREADER_ADDR / DOCREADER_TRANSPORT |
vector_database | VectorDatabaseConfig | driver (обычно используется env RETRIEVE_DRIVER) |
stream_manager | StreamManagerConfig | type: memory / redis; redis.address/username/password/db/prefix/ttl; cleanup_timeout (обычно используются env STREAM_MANAGER_TYPE, REDIS_*) |
web_search | WebSearchConfig | timeout: тайм-аут веб-поиска в секундах |
models | []ModelConfig | Устаревший статический список моделей (type/source/model_name/parameters); сейчас рекомендуется использовать builtin_models.yaml или настройку в интерфейсе |
frontend_base_url | string | пусто |
Важные переменные окружения
Приведённые ниже переменные берутся из секции environment app/docreader в docker-compose.yml, из .env.example и из os.Getenv в коде. В продакшн-развёртывании минимум нужно изменить: DB_USER/DB_PASSWORD/DB_NAME, REDIS_PASSWORD, JWT_SECRET, SYSTEM_AES_KEY.
Основы времени выполнения
| Имя | Значение по умолчанию | Описание |
|---|---|---|
GIN_MODE | release | debug — режим разработки (включает Swagger) / release — продакшн |
LOG_LEVEL / LOG_PATH / LOG_FORMAT | debug / пусто / пусто | Уровень логирования, путь к файлу (пусто — только stdout), пользовательский формат |
LLM_DEBUG_LOG | false | При true пишет llm_debug.log в тот же каталог, что LOG_PATH |
TZ | Asia/Shanghai | Часовой пояс |
DEFAULT_LOCALE | пусто | Язык интерфейса фронтенда по умолчанию (читает контейнер frontend): zh-CN / en-US / ru-RU / ko-KR / ja-JP, недопустимые значения игнорируются. Влияет только на пользователей, которые вручную не меняли язык; приоритет: выбранный пользователем язык > эта переменная > zh-CN; после изменения достаточно перезапустить контейнер frontend, пересобирать образ не нужно |
WEKNORA_LANGUAGE | пусто | Язык обработки документов (генерация вопросов/резюме). Приоритет: эта переменная > Accept-Language запроса > встроенный zh-CN. Язык обработки документов можно задавать независимо от языка интерфейса, например обрабатывать корейские документы при английском интерфейсе. Каналы IM без заданного языка ответа тоже используют эту переменную (при отсутствии — zh-CN) как язык ответа по умолчанию |
AUTO_MIGRATE | true | Автоматически выполнять миграции базы данных при запуске |
AUTO_RECOVER_DIRTY | true | Автоматически исправлять состояние dirty в golang-migrate (оставшееся от прерванной миграции). При ручной диагностике проблем миграций следует временно установить false, иначе при запуске записи о версии миграции будут автоматически перезаписаны, см. База данных и миграции |
WEKNORA_TRUSTED_PROXIES | пусто | Доверенные прокси gin в CIDR (через запятую) |
MAX_SKILL_BUNDLE_SIZE_MB | 256 MiB (по умолчанию не меньше MAX_FILE_SIZE_MB, верхний предел 512 MiB) | Ограничение загрузки ZIP-навыка и скачивания из источника; лимит тела запроса обратного прокси тоже должен быть достаточным |
MAX_FILE_SIZE_MB | 50 | Ограничение размера загружаемого файла (общее для app/frontend/docreader); в развёртывании Helm используется global.maxFileSizeMB |
CONCURRENCY_POOL_SIZE | 5 | Общий пул параллелизма |
APP_EXTERNAL_URL / FRONTEND_BASE_URL | пусто | Внешне доступный URL для внешних ссылок на изображения/файлы каналов IM / внешний origin фронтенда |
RESOURCE_URL_MODE | handle | Форма ссылок на файлы в ответах API по умолчанию: handle возвращает внутренний resource://, public — загружаемую временную внешнюю ссылку. Для отдельного запроса можно переопределить через ?resource_urls=, подробнее — Обзор API |
APP_EXTERNAL_URL влияет на то, сможет ли канал IM отображать изображения из базы знаний. Платформе IM нужен публичный http(s) URL; есть два варианта:
- сам бэкенд хранилища публично доступен (для объектного хранилища — публичный endpoint, либо задайте
MINIO_ENDPOINTкак публичный host); тогдаresource://откатывается к предподписанному URL бэкенда и эта переменная не нужна; - задать
APP_EXTERNAL_URL: изображенияresource://переписываются в<APP_EXTERNAL_URL>/r/<token>и идут через саму платформу (нужен прокси nginx для/r/, в официальном образе фронтенда этот location уже есть).
Стандартное внутреннее развёртывание MinIO и бэкенд local могут использовать только второй вариант. Если канал IM включён, а эта переменная пуста, при запуске сервис один раз выводит WARN; если результат переписывания не является http(s) URL, исходная ссылка сохраняется и записывается действенное предупреждение, а не отправляется ссылка, недоступная на стороне IM.
Четыре формы URL и их получение по каждому каналу — в разделе Внешний доступ к изображениям и файлам.
База данных и очереди
| Имя | Значение по умолчанию | Описание |
|---|---|---|
DB_DRIVER | postgres | postgres / sqlite (Lite) |
DB_HOST / DB_PORT / DB_USER / DB_PASSWORD / DB_NAME | postgres / 5432 / пусто / пусто / пусто | Подключение к PostgreSQL (обязательно) |
DB_PATH | — | Путь к файлу базы данных при DB_DRIVER=sqlite |
STREAM_MANAGER_TYPE | пусто (в compose фактически используется redis) | redis / memory |
REDIS_ADDR / REDIS_USERNAME / REDIS_PASSWORD / REDIS_DB / REDIS_PREFIX | redis:6379 / … | Подключение к Redis |
REDIS_USE_TLS | false | Общий переключатель TLS; нужен для управляемого Redis (например, AWS ElastiCache); REDIS_TLS_SERVER_NAME задаёт имя сервера для проверки и SNI (полезно, когда адрес — IP), REDIS_TLS_INSECURE_SKIP_VERIFY пропускает проверку сертификата (небезопасно, только для сред разработки с самоподписанными сертификатами) |
WEKNORA_REDIS_NAMESPACE | пусто | Суффикс пространства имён каналов при общем Redis для нескольких развёртываний |
WEKNORA_ASYNQ_CORE_CONCURRENCY и др. | 8 / 2 / 12 / 4 / 6 | Параллелизм очередей Asynq (core/postprocess/enrichment/maintenance/shared), дополнительно WEKNORA_WIKI_ASYNQ_CONCURRENCY=8, WEKNORA_MODEL_MAX_CONCURRENCY=32 |
Поисковые движки и векторные базы
| Имя | Значение по умолчанию | Описание |
|---|---|---|
RETRIEVE_DRIVER | postgres | Поисковый движок: postgres / elasticsearch_v7 / elasticsearch_v8 / qdrant / milvus / weaviate / opensearch / doris / tencent_vectordb / sqlite (Lite); можно указать несколько через запятую для параллельной работы |
ELASTICSEARCH_ADDR/USERNAME/PASSWORD/INDEX | пусто | Elasticsearch |
QDRANT_HOST/PORT/COLLECTION/API_KEY/USE_TLS | qdrant / 6334 / weknora_embeddings / пусто / false | Qdrant |
MILVUS_ADDRESS/COLLECTION/METRIC_TYPE/... | milvus:19530 / weknora_embeddings / IP | Milvus |
OPENSEARCH_ADDR/USERNAME/PASSWORD/INDEX/INSECURE_SKIP_VERIFY | пусто | OpenSearch |
WEAVIATE_HOST/GRPC_ADDRESS/SCHEME/AUTH_ENABLED/API_KEY | пусто | Weaviate |
DORIS_ADDR/HTTP_PORT/DATABASE/USERNAME/PASSWORD/TABLE_PREFIX/COMPAT_MODE | пусто | Apache Doris 4.1+ |
TENCENT_VECTORDB_ADDR/USERNAME/API_KEY/DATABASE/COLLECTION/REPLICA_NUMBER | пусто | VectorDB |
MULTI_STORE_RETRIEVE_TIMEOUT_SEC | пусто | Тайм-аут параллельного поиска по нескольким движкам |
NEO4J_ENABLE / NEO4J_URI / NEO4J_USERNAME / NEO4J_PASSWORD | пусто / bolt://neo4j:7687 / neo4j / password | Единственный переключатель графа знаний (ENABLE_GRAPH_RAG устарел с v0.1.6) |
Файловое хранилище
| Имя | Значение по умолчанию | Описание |
|---|---|---|
STORAGE_TYPE | local | local / minio / cos / tos / s3 / obs / oss |
STORAGE_ALLOW_LIST | пусто | Белый список типов хранилища, доступных пользователю (через запятую); допустимые значения local, minio, cos, tos, s3, oss, ks3, obs |
LOCAL_STORAGE_BASE_DIR | /data/files | Корневой каталог локального хранилища |
MINIO_ENDPOINT/ACCESS_KEY_ID/SECRET_ACCESS_KEY/BUCKET_NAME/USE_SSL | minio:9000 / minioadmin / minioadmin / пусто / false | MinIO |
COS_SECRET_ID/SECRET_KEY/REGION/BUCKET_NAME/APP_ID/PATH_PREFIX | пусто | COS (дополнительно TEMP_BUCKET/TEMP_REGION) |
S3_* / OBS_* / OSS_* / TOS_* | см. раздел B4 в .env.example | AWS S3 / Huawei OBS / Alibaba OSS / Volcano TOS, все содержат ENDPOINT/REGION/KEY/BUCKET/PATH_PREFIX и др. |
S3_ACCESS_KEY / S3_SECRET_KEY в AWS S3 можно оставить пустыми одновременно: тогда используется цепочка учётных данных AWS SDK по умолчанию, поддерживаются IAM Role EC2/ECS/EKS, IRSA/Web Identity, переменные окружения и общий файл конфигурации — при развёртывании в AWS не нужно класть долгоживущие ключи в переменные окружения. Оба значения должны быть заполнены или пусты одновременно. Если S3_ENDPOINT пуст, используется стандартный endpoint соответствующего Region.
Модели и инференс
| Имя | Значение по умолчанию | Описание |
|---|---|---|
OLLAMA_BASE_URL | http://host.docker.internal:11434 | Единственный адрес локального Ollama. Его совместно используют векторные и диалоговые модели с source=local; при отсутствии переменной процесс использует http://localhost:11434 |
OLLAMA_OPTIONAL | true | При недоступности Ollama только предупреждает и не блокирует запуск |
BATCH_EMBED_SIZE | пусто | Размер пакета embedding |
VLM_HTTP_TIMEOUT_SECONDS | 180 | Тайм-аут одного запроса VLM |
BUILTIN_MODELS_CONFIG | config/builtin_models.yaml | Путь к файлу объявлений встроенных моделей (см. ниже) |
MODELS_CONFIG | config/models.json | Путь к файлу наложения каталога провайдеров моделей для развёртывания (дополнение провайдеров, переопределение адресов или параметров моделей); формат — в разделе Управление моделями |
WEKNORA_LLM_STREAM_RAW_DUMP / _DIR | пусто | Сырой дамп потока LLM (для диагностики) |
Имя векторной модели не определяется переменной окружения. В записи модели задайте name для type=Embedding, source=local равным имени модели Ollama (в примере CLI nomic-embed-text, размерность 768; в быстром старте используется bge-m3, размерность 1024). Если имя пустое, локальный embedder откатывается к nomic-embed-text. EMBEDDING_MODEL_NAME действует только когда на него ссылается ${EMBEDDING_MODEL_NAME} в builtin_models.yaml (см. ниже раздел «config/builtin_models.yaml.example: декларативные встроенные модели» и файл config/builtin_models.yaml.example в репозитории). Отправная точка 8 ГБ из документации по установке не включает веса Ollama; Neo4j по умолчанию отключён (profile neo4j).
Аутентификация, тенанты и безопасность
| Имя | Значение по умолчанию | Описание |
|---|---|---|
JWT_SECRET | пусто | Ключ подписи JWT (обязателен, можно сгенерировать openssl rand -hex 32). Если оставить пустым или использовать примерное значение, при каждом запуске генерируется случайный ключ, и после перезапуска вошедшим пользователям придётся войти снова; для нескольких реплик нужно задать одинаковое значение |
SYSTEM_AES_KEY | пусто | Мастер-ключ AES-256 для шифрования чувствительных полей на диске, обязательно 32 байта (можно сгенерировать openssl rand -hex 16); при потере зашифрованные данные (API Key тенанта, ключи моделей, учётные данные векторных баз и др.) восстановить нельзя, при обновлении используйте прежнее значение. Начиная с v0.4.0 заменяет TENANT_AES_KEY/CRYPTO_MASTER_KEY/CRYPTO_SALT |
SYSTEM_SIGNING_KEY | пусто (с откатом к SYSTEM_AES_KEY) | Ключ подписи встроенных сессий и предподписанных ссылок на файлы (можно сгенерировать openssl rand -hex 32). Если не задан, используется SYSTEM_AES_KEY; если оба отсутствуют, короче 16 символов или являются примерными значениями, подписанные ссылки и встроенные сессии не выдаются. После смены уже выданные ссылки становятся недействительными; для нескольких реплик используйте одно значение |
DISABLE_REGISTRATION | false | При true конфигурация при запуске использует invite_only (запрет регистрации по паролю, включая регистрацию по приглашению); сохранённая в базе данных настройка во время выполнения всё равно имеет приоритет |
WEKNORA_AUTH_DEFAULT_TENANT_MODE | create_personal | Политика создания пространства после регистрации (create_personal / tenantless) |
WEKNORA_TENANT_ENABLE_RBAC | (по умолчанию true) | Переключатель обязательной проверки ролей пространства |
WEKNORA_TENANT_ENABLE_CROSS_TENANT_ACCESS | false | Доступ между пространствами |
WEKNORA_TENANT_SELF_SERVICE_CREATION_ENABLED | true | Создание собственных пространств обычными пользователями |
WEKNORA_TENANT_MAX_OWNED_PER_USER | пусто | Верхний предел собственных пространств |
WEKNORA_TENANT_AUTO_CREATE_API_KEY | false | Автоматически выдавать API Key с full_access при создании пространства (совместимость со старым поведением) |
WEKNORA_TENANT_DEFAULT_STORAGE_QUOTA_GB | 10 | Квота хранилища по умолчанию для нового пространства |
WEKNORA_AUTH_COMPLEX_PASSWORD_ENABLED | false | Политика сложных паролей: заглавные и строчные буквы, цифры, специальные символы; системная настройка auth.complex_password_enabled имеет приоритет |
WEKNORA_TENANT_AUTO_ACCEPT_INVITATION | false | Приглашение по email: существующая учётная запись присоединяется сразу; системная настройка tenant.auto_accept_invitation имеет приоритет |
OIDC_AUTH_JWKS_URI | пусто | Набор открытых ключей для проверки подписи id_token; может дополняться через discovery, проверяется вместе с issuer/audience/сроком действия |
WEKNORA_INVITATION_TTL | 168h | Срок действия ссылки-приглашения |
WEKNORA_AUDIT_RETENTION_DAYS | 90 | Число дней хранения журнала аудита |
WEKNORA_BOOTSTRAP_SYSTEM_ADMIN_EMAIL | пусто | Назначение первого системного администратора. Пользователь не создаётся: этот email нужно сначала зарегистрировать самостоятельно; при следующем запуске, если в развёртывании ещё нет ни одного системного администратора, он будет назначен. После появления администратора переменная больше не действует. Подробнее — Тенанты, пользователи и аутентификация/авторизация |
OIDC_AUTH_ENABLE и OIDC_AUTH_* / OIDC_USER_INFO_MAPPING_* | false / пусто | Полный набор настроек единого входа OIDC |
SSRF_WHITELIST / SSRF_WHITELIST_EXTRA | пусто / searxng,qdrant,milvus,weaviate,doris-fe,doris-be,minio (только app) | Белый список SSRF для исходящих запросов. SSRF_WHITELIST общий для app и docreader; в compose значение по умолчанию задано только для SSRF_WHITELIST_EXTRA у app, а одноимённая переменная docreader по умолчанию пуста |
SSRF_DNS_WHITELIST_ONLY | false | Разрешать исходящие только по белому списку (читают и app, и docreader). После включения хосты вне белого списка отклоняются до DNS-запроса, а прямые подключения по IP вне белого списка тоже отклоняются при проверке URL; домены сопоставляются только по имени, и CIDR в белом списке перестаёт действовать для доменов. Значение разбирается как булево (1/t/true — вкл., 0/f/false — выкл.), непустое неразбираемое значение считается включённым. Подготовка перед включением — ниже |
IMAGE_HOST_KEEP_URL | пусто | Белый список доменов изображений, для которых сохраняется исходный URL |
Перед включением SSRF_DNS_WHITELIST_ONLY
После включения белый список становится всей политикой исходящих запросов, поэтому нужно заранее внести все исходящие адреса в SSRF_WHITELIST или SSRF_WHITELIST_EXTRA. Если docreader тоже обращается к хостам внутри compose, добавьте их в общий для двух сервисов SSRF_WHITELIST (его SSRF_WHITELIST_EXTRA по умолчанию пуст). Обычно также нужно добавить:
- адреса сервисов моделей (chat / embedding / rerank / VLM / ASR, включая
localhostлокального Ollama) dexдля входа OIDC (или домен вашего IdP), адреса сервисов MCP,docreader- объектное хранилище (внешние S3/COS/OSS и др.), внешние векторные базы, адрес Langfuse
- адрес плоскости управления песочницы: после включения «разрешить частные endpoint» больше не обходит белый список
Пути исходящих запросов, которые всё ещё не покрыты, по убыванию влияния:
- Разрешение имён у gRPC-векторных баз во время выполнения: клиенты qdrant / milvus разрешают target собственным resolver'ом gRPC, и dialer получает уже готовый адрес, поэтому такие хосты проверяются по имени до создания клиента (конфигурация из переменных окружения — при запуске, конфигурация, сохранённая в консоли, — через проверку URL), а не перед каждым соединением.
- OTLP-экспортёр Langfuse имеет собственный HTTP-клиент и полностью обходит этот механизм.
LANGFUSE_HOSTпо умолчанию указывает на адрес SaaS; при офлайн-развёртывании отключите трассировку или измените на внутренний адрес. HTTP(S)_PROXY: dialer пропускает хост прокси только если «адрес подключения и host из URL прокси полностью совпадают». При совпадении хост прокси разрешается и подключается, даже если его нет в белом списке; при несовпадении (например, в URL прокси не указан порт) он считается не в белом списке и отклоняется. При офлайн-развёртывании уберите прокси или внесите хост прокси в белый список.
Параметры сборки образов (при сборке из исходников)
Приведённые ниже переменные используются только при сборке образа frontend через docker compose build / make docker-build-frontend; при развёртывании из официального образа задавать их не нужно. Другие параметры сборки (прокси Go, зеркала apt и т. д.) — в разделе A1 файла .env.example.
| Имя | Значение по умолчанию | Описание |
|---|---|---|
VITE_FRONTEND_COMMIT | unknown | Короткий commit фронтенда, записывается на страницу «Системная информация». make docker-build-frontend и start_all.sh --no-pull заполняют его из git автоматически; при прямом docker compose build нужно экспортировать вручную |
NPM_REGISTRY | пусто (источник по умолчанию) | npm registry на этапе сборки; при недоступности npmjs можно задать https://registry.npmmirror.com |
NODE_MAX_OLD_SPACE_SIZE | 4096 | Верхний предел heap Node при сборке Vite (MB); при небольшой памяти Docker Desktop можно снизить до 2048 |
Разбор Docreader (контейнер docreader)
| Имя | Значение по умолчанию | Описание |
|---|---|---|
DOCREADER_ADDR / DOCREADER_TRANSPORT | docreader:50051 / grpc | Адрес и транспорт подключения со стороны app (grpc/http) |
DOCREADER_GRPC_MAX_WORKERS / DOCREADER_GRPC_PORT / DOCREADER_GRPC_MAX_FILE_SIZE_MB | 4 / 50051 / следует за MAX_FILE_SIZE_MB | Параметры сервиса gRPC |
GRPC_TLS_ENABLED/CERT/KEY/CA/SERVER_NAME, GRPC_MTLS_REQUIRE_CLIENT_CERT, GRPC_AUTH_TOKEN | false / пусто | TLS/mTLS и token-аутентификация канала app↔docreader |
DOCREADER_PDF_RENDER_DPI / DOCREADER_PDF_JPEG_QUALITY / DOCREADER_PDF_RENDER_MAX_EDGE | 200 / 85 / 2000 | Рендеринг PDF |
DOCREADER_PDF_FORCE_SCANNED / DOCREADER_PDF_SCAN_IMAGE_RATIO / DOCREADER_PDF_SCAN_MIN_CHARS | false / значения по умолчанию кода | Определение сканов |
DOCREADER_ODL_HYBRID / DOCREADER_ODL_HYBRID_URL / DOCREADER_ODL_HYBRID_MODE / DOCREADER_ODL_HYBRID_FALLBACK | off / http://odl-hybrid:5002 / auto / false | Гибридный разбор OpenDataLoader |
Остальные DOCREADER_PDF_* (межсловные расстояния, боковые панели, скрытый текст, встроенные изображения, области диаграмм и др., более 20) | см. комментарии к секции docreader в docker-compose.yml | Тонкая настройка структуры и извлечения PDF |
DOCREADER_EXTERNAL_HTTP_PROXY / _HTTPS_PROXY | пусто | Прокси исходящих запросов docreader |
Описание генерации и исходящие подключения
| Переменная окружения | По умолчанию | Назначение |
|---|---|---|
KNOWLEDGE_BASE_PROFILE_MAX_TOKENS | 2048 | Бюджет токенов дополнения при генерации описания базы знаний; при недопустимом или неположительном значении возвращается значение по умолчанию; если у модели с рассуждением появляется no gist, можно увеличить |
WEKNORA_OUTBOUND_DIAL_TIMEOUT | 5s | Тайм-аут dial при исходящих соединениях в рамках защиты SSRF, используется длительность Go (например, 10s); это не общий тайм-аут запроса или генерации модели |
Agent, Skills и вложения
| Имя | Значение по умолчанию | Описание |
|---|---|---|
| Настройки Sandbox | Настраиваются на странице настроек по пространству | Бэкенд, учётные данные, шаблоны, тайм-ауты и политика доступа к частным сетям сохраняются по пространству |
WEKNORA_SANDBOX_DOCKER_ENABLED | false | Переключатель отката на бэкенд Docker-песочницы. Системный администратор также может включить его в «Настройки → Системные настройки → Сетевая безопасность» (приоритет у БД, действует сразу). По умолчанию выключен, так как локальный docker.sock равнозначен root на хосте |
WEKNORA_AGENT_LLM_TIMEOUT | 120s | Тайм-аут одного вызова LLM агентом (Go duration или просто число секунд) |
WEKNORA_AGENT_TOOL_APPROVAL_TIMEOUT / _FAIL_OPEN | 600s / fail-close | Ожидание ручного подтверждения инструмента MCP и политика при сбое |
WEKNORA_CHAT_ATTACHMENT_TTL_HOURS / _WAIT_TIMEOUT_SEC / _OCR_CONCURRENCY / _OCR_MAX_PAGES | 24 / 60 / 8 / 8 | Время хранения разбора вложений чата, тайм-аут ожидания и пределы параллелизма/страниц OCR; вложения, на которые больше не ссылается ни одно действующее сообщение диалога, удаляются по TTL, а отправленные вложения, на которые всё ещё ссылаются исходная или разветвлённая сессия, по TTL не удаляются |
WEKNORA_HOUSEKEEPING_ENABLED | включено | Сбор «мусорных» данных, застрявших в processing |
WEKNORA_DOCUMENT_PROCESS_TIMEOUT / WEKNORA_DOCREADER_CALL_TIMEOUT | 2h / 30m | Тайм-ауты задачи обработки документа и одного RPC |
WEKNORA_PADDLEOCR_VL_TIMEOUT | 1000s | Тайм-аут HTTP-запроса к собственному PaddleOCR-VL; поддерживает положительное значение Go duration (например, 5400s, 90m); пустое, недопустимое или неположительное значение использует значение по умолчанию. У внешнего тайм-аута должен быть запас: например, здесь 90m, у DocReader 100m, у задачи документа 2h |
WEKNORA_MINERU_TIMEOUT | 1000s | Тайм-аут одного разбора собственным MinerU (в API V1 — вся задача разбора, в старых версиях — запрос /file_parse), формат и правила значения по умолчанию такие же; для очень больших PDF также нужен запас внешнего тайм-аута |
WEKNORA_MINERU_CLOUD_TIMEOUT | 600s | Максимальное время опроса результата разбора MinerU Cloud (mineru.net), формат и правила значения по умолчанию такие же |
WEKNORA_PADDLEOCR_VL_CLOUD_TIMEOUT | 600s | Максимальное время опроса результата разбора PaddleOCR-VL Cloud (AI Studio), формат и правила значения по умолчанию такие же |
WEKNORA_WEKNORACLOUD_TIMEOUT | 20m | Максимальное время опроса результата задачи managed docreader в aihelpme.ruCloud, формат и правила значения по умолчанию такие же; должно быть меньше WEKNORA_DOCREADER_CALL_TIMEOUT |
Бэкенды песочницы, сетевые политики, переключатели скриптов и личные переменные окружения управляются через конфигурацию пространства/API, см. Навыки и песочница. Долговременная память и автоматические метки по умолчанию выключены и используют соответственно memory_config тенанта и auto_tag_config базы знаний; не заменяйте конфигурацию отдельных пространств глобальными переменными окружения.
Локальный браузер (BrowserSkill, опционально)
Пользователь подключает свой браузер к платформе через расширение Chrome. Образ app в Docker уже содержит bsk и сопутствующее расширение; адрес подключения по умолчанию строится по адресу страницы, к которой обращается пользователь, поэтому настройка обычно не требуется.
| Имя | Значение по умолчанию | Описание |
|---|---|---|
BROWSERSKILL_BINARY | В образе Docker /opt/weknora/browserskill/bsk | Абсолютный путь к исполняемому файлу bsk; при нативном развёртывании нужно собрать и настроить самостоятельно; явно заданное пустое значение отключает эту функцию |
BROWSERSKILL_EXTENSION_PATH | В образе Docker предустановлено | Путь к ZIP-архиву расширения для скачивания в «Панель инструментов → Подключение браузера → Ручная установка (запасной вариант)» |
BROWSERSKILL_PUBLIC_URL | пусто (строится по адресу страницы) | Переопределять только если шлюз использует отдельный домен или путь; при удалённом развёртывании обязательно wss:// |
BROWSERSKILL_MAX_CONNECTIONS | 32 | Верхний предел одновременно подключённых браузерных устройств на один экземпляр приложения |
BROWSERSKILL_INTERNAL_URL / BROWSERSKILL_CLUSTER_SECRET | пусто | Развёртывание с несколькими репликами: каждый узел указывает адрес, напрямую доступный другим узлам (не используйте адрес балансировщика), все реплики используют один случайный ключ (не менее 32 символов) |
Способы развёртывания и ограничения — в разделе Локальный браузер.
Наблюдаемость (Langfuse)
Если задать одновременно LANGFUSE_PUBLIC_KEY + LANGFUSE_SECRET_KEY, функция включается автоматически; LANGFUSE_HOST (по умолчанию https://cloud.langfuse.com, для собственного стека — http://langfuse-web:3000), LANGFUSE_ENABLED, LANGFUSE_RELEASE, LANGFUSE_ENVIRONMENT, LANGFUSE_SAMPLE_RATE, LANGFUSE_FLUSH_AT/FLUSH_INTERVAL/QUEUE_SIZE/REQUEST_TIMEOUT/DEBUG — параметры тонкой настройки; в собственном стеке с --profile langfuse есть также LANGFUSE_SALT, LANGFUSE_ENCRYPTION_KEY, LANGFUSE_NEXTAUTH_SECRET, LANGFUSE_INIT_* (автосоздание организации/проекта/администратора при первом запуске) и др., см. разделы I1/I2 в .env.example.
Опциональные сервисы: SearXNG и MCP Server
Эти две группы переменных нужны только при включении соответствующего compose profile и не зависят от основного сервиса.
SearXNG (самостоятельный метапоиск, --profile searxng / full):
| Имя | Значение по умолчанию | Описание |
|---|---|---|
SEARXNG_PORT | 8888 | Порт на хосте. Не должен совпадать с APP_PORT (по умолчанию 8080), иначе запросы к localhost могут сначала попасть в SearXNG и эндпоинт входа вернёт HTML 404 |
SEARXNG_BIND | 127.0.0.1 | По умолчанию слушает только локальный хост. Поставляемая с платформой конфигурация отключает собственное ограничение скорости SearXNG (иначе бэкенд был бы заторможен), поэтому не следует выставлять его напрямую в LAN; если всё же нужно открыть, явно измените на 0.0.0.0 и самостоятельно усильте защиту |
SEARXNG_SECRET | пусто | Входной скрипт использует его для замены secret_key в settings.yml; при открытии наружу обязательно задать |
При собственном развёртывании SearXNG не забудьте добавить 127.0.0.1 в SSRF_WHITELIST, иначе защита от SSRF на бэкенде отклонит локальный адрес. Использование — в разделе Веб-поиск и извлечение веб-страниц.
MCP Server (открывает платформу для MCP-клиентов вроде Claude Desktop, --profile full):
| Имя | Значение по умолчанию | Описание |
|---|---|---|
WEKNORA_API_KEY | пусто | Ключ, которым mcp-server обращается к REST платформы; создаётся в «Настройки → API Keys» |
MCP_SERVER_AUTH_TOKEN | пусто | Обязателен для транспорта HTTP/SSE; при отсутствии процесс отказывается запускаться; клиент передаёт его как Authorization: Bearer |
WEKNORA_CHAT_TIMEOUT | 300 | Тайм-аут чтения при вызове REST платформы (секунды) |
WEKNORA_VERIFY_SSL | true | Проверять ли TLS-сертификат бэкенда; при самоподписанном сертификате можно задать false |
MCP_ALLOWED_UPLOAD_DIRS | пусто | Белый список каталогов, разрешённых для загрузки (через запятую); пусто отключает инструмент загрузки файлов |
Полное описание — в разделе Интеграция с MCP.
config/prompt_templates/: шаблоны промптов
Для каждого типа промпта — отдельный YAML-файл с единой структурой templates: (список); поля одного шаблона (структура PromptTemplate, internal/config/config.go):
| Поле | Описание |
|---|---|
id | Уникальный ID, на который ссылаются *_prompt_id в config.yaml, system_prompt_id встроенных Agent и пресеты типов |
name / description | Отображаемое имя и описание |
content | Текст промпта системной стороны (обязателен для всех шаблонов) |
user | Промпт пользовательской стороны (используется только в парных шаблонах system+user, например rewrite, keywords_extraction) |
default | Является ли шаблоном по умолчанию для этого типа |
mode | Различение подтипов (например, model в fallback означает промпт запасного ответа модели) |
has_knowledge_base / has_web_search | Отметки применимости шаблона |
i18n | Многоязычные name/description (ключ — locale, например zh-CN) |
Назначение файлов и содержащиеся в них ID шаблонов:
| Файл | Назначение | ID шаблонов |
|---|---|---|
system_prompt.yaml | Системный промпт вопросов-ответов (quick-answer / RAG) | default_kb (по умолчанию), expert_assistant, customer_service, technical_support, pure_chat, web_search_assistant |
context_template.yaml | Шаблон сборки результатов поиска в контекст | default_context, detailed_context, simple_context, qa_context |
rewrite.yaml | Переписывание запроса в многораундовом диалоге (пары content+user) | default_rewrite, standard_rewrite, strict_rewrite |
fallback.yaml | Запасной ответ при промахе (фиксированный ответ + запасной ответ модели mode:"model") | default_fallback, polite_fallback, brief_fallback, model_fallback, default_fallback_prompt |
generate_session_title.yaml | Генерация заголовка сессии | default_session_title |
generate_summary.yaml | Генерация резюме документа | default_summary |
generate_questions.yaml | Предварительная генерация вопросов по документу | default_generate_questions |
keywords_extraction.yaml | Извлечение ключевых слов | default_keywords_extraction |
graph_extraction.yaml | Извлечение сущностей/отношений графа | default_extract_entities, default_extract_relationships |
agent_system_prompt.yaml | Системный промпт Agent (smart-reasoning) | pure_agent, progressive_rag_agent, data_analyst, wiki_researcher, wiki_fixer, hybrid_rag_wiki_agent |
intent_prompts.yaml | Системные промпты по намерениям для маршрутизации намерений (ID шаблона = значение намерения) | greeting, chitchat, follow_up, image_only, summarize, web_search, doc_only |
Точки кастомизации: редактируйте content шаблона напрямую либо добавьте новую запись шаблона и измените соответствующий *_prompt_id в config.yaml на новый ID; изменения вступают в силу после перезапуска (в compose ./config/config.yaml уже смонтирован, каталог шаблонов идёт с образом/монтируется). Если ID не найден, в журнале запуска выводится Warning: xxx_prompt_id not found.
config/agent_type_presets.yaml: пресеты типов Agent
Для настраиваемого Agent в режиме smart-reasoning доступно «заполнение одним нажатием»: каждый пресет (AgentTypePresetEntry, internal/types/agent_type_preset.go) содержит id, i18n (многоязычные label/description), config (предзаполненные значения; нулевые значения не применяются) и опциональный kb_filter (предикаты возможностей any_of / all_of / none_of, ограничивающие доступные базы знаний; имена возможностей: vector, keyword, wiki, graph, faq). Фронтенд читает их через GET /agents/type-presets.
Встроено пять пресетов:
| id | Системный промпт | Белый список инструментов | Примечания |
|---|---|---|---|
rag-qa | progressive_rag_agent | search_knowledge, read_document, list_documents | temperature 0.7, max_iterations 30, приоритет FAQ |
wiki-qa | wiki_researcher | wiki_search, wiki_read_page, read_document, wiki_flag_issue | Нужна база знаний с включённым Wiki |
hybrid-rag-wiki | hybrid_rag_wiki_agent | Полный набор инструментов Wiki + RAG | max_iterations 40, самый гибкий пресет |
data-analysis | data_analyst | data_schema, data_analysis | temperature 0.3; kb_filter: none_of: [faq]; поддерживаются csv/xlsx |
custom | нет | без предзаполнения | Полностью ручная настройка |
Устаревшие имена инструментов, встречающиеся в сохранённых конфигурациях (knowledge_search, grep_chunks → search_knowledge; list_knowledge_chunks, get_document_info, wiki_read_source_doc → read_document), автоматически отображаются на новые инструменты во время выполнения; переписывать их вручную не нужно.
config/builtin_agents.yaml: встроенные Agent
Определяют Agent, поставляемые вместе с системой и видимые всем тенантам (BuiltinAgentEntry, internal/types/builtin_agent_config.go). Каждая запись содержит id, avatar, is_builtin: true, i18n (имя и описание для default/zh-CN/zh-TW/ja-JP/ko-KR) и полный config (CustomAgentConfig). В файле встроено пять Agent:
builtin-quick-answer:agent_mode: quick-answer, ссылается наsystem_prompt_id: default_kbиcontext_template_id: default_context, с полными параметрами поиска (embedding_top_k: 10,vector_threshold: 0.5,rerank_threshold: 0.3, порог прямого ответа FAQ 0.9 и др.);builtin-smart-reasoning:agent_mode: smart-reasoning,agent_type: rag-qa,max_iterations: 50;builtin-data-analyst,builtin-wiki-researcher,builtin-wiki-fixer: ориентированы соответственно на анализ таблиц и сценарии Wiki.
system_prompt_id в config при запуске разрешается функцией resolveBuiltinAgentPromptIDs в фактическое содержимое из agent_system_prompt.yaml. Чтобы изменить поведение встроенных Agent, отредактируйте этот файл и перезапустите систему.
config/builtin_models.yaml.example: декларативные встроенные модели
Скопируйте в config/builtin_models.yaml (или укажите путь через BUILTIN_MODELS_CONFIG); тогда его записи при каждом запуске записываются в таблицу models с пометкой is_builtin=true и видны всем тенантам (в compose раскомментируйте строку монтирования - ./config/builtin_models.yaml:/app/config/builtin_models.yaml:ro). Формат:
builtin_models:
- id: builtin-llm-default # стабильный ID; повторный запуск обновляет по ID идемпотентно
type: KnowledgeQA # KnowledgeQA | Embedding | Rerank | VLLM | ASR
source: remote # remote (по умолчанию) | local
is_default: true # сделать ли моделью по умолчанию для этого типа
name: ${LLM_MODEL_NAME} # все строковые поля поддерживают ссылки ${ENV} (.env передаётся в контейнер через env_file)
parameters:
base_url: ${LLM_BASE_URL}
api_key: ${LLM_API_KEY}
provider: ${LLM_PROVIDER} # openai | generic | aliyun | moonshot | ...
embedding_parameters: # только для типа Embedding
dimension: 1536
truncate_prompt_tokens: 0Внимание: незаданные ${ENV} остаются литералами, чтобы было заметно ошибку конфигурации; нестроковые поля (type, source, is_default, dimension и др.) должны быть заданы литеральными значениями; удаление записи из файла не удаляет её из базы автоматически — нужно очистить вручную.
Локальный Ollama: укажите source как local, а в name — имя модели Ollama (на векторной стороне можно использовать ${EMBEDDING_MODEL_NAME}). Полный пример с комментариями — в секции «one local Ollama» файла config/builtin_models.yaml.example; dimension должен быть литералом (в примере CLI nomic-embed-text — 768).
Памятка по приоритету конфигурации
Для конфигураций с одним и тем же смыслом приоритет таков: таблица system_settings в базе данных (только ключи, зарегистрированные в таблице) > переменные окружения > config.yaml > встроенные значения по умолчанию в коде; конфигурации уровня тенанта/базы знаний (RetrievalConfig, ChunkingConfig и др., хранятся в базе данных) во время выполнения переопределяют глобальные значения по умолчанию. После изменения .env нужно перезапустить контейнер (docker compose up -d app); hot-reload air в режиме разработки не перечитывает .env, поэтому нужен перезапуск dev-скрипта.