Документ приведен к единому формату эксплуатационной документации DreamDocs: цель, область применения, требования, подготовка, установка, проверка, типовые ошибки и контрольный чек-лист.
Паспорт документа
| Параметр | Значение |
|---|---|
| Наименование | Инструкция по установке DreamDocs |
| Назначение | Описание порядка установки и первичной проверки работоспособности DreamDocs |
| Версия документа | 1.0 |
| Дата документа | 1 июня 2026 года |
| Целевая аудитория | Системные администраторы, DevOps-инженеры, инженеры сопровождения |
| Уровень доступа | Техническая документация. Не содержит учетных данных и закрытых ключей. |
История изменений
| Версия | Дата | Описание изменений |
|---|---|---|
| 1.0 | 01.06.2026 | Первичная редакция. Исходная техническая инструкция структурирована, очищена от черновых комментариев и приведена к единому формату документации. |
1. Назначение и область применения
Документ описывает типовой порядок установки DreamDocs на Linux-сервер с использованием компонентов DreamOCR, DocaML, Doca, Nginx и, при необходимости, PostgreSQL и локального LLM-сервера.
Инструкция применима для первичного развертывания стенда, подготовки тестового контура, установки продуктивного экземпляра и восстановления среды на новом сервере.
Конкретные версии дистрибутива, ссылка на архив, файл лицензии, доменное имя, параметры базы данных и политика TLS/mTLS должны быть уточнены до начала работ.
Роли участников
| Роль | Зона ответственности |
|---|---|
| Системный администратор | Подготовка ОС, пользователей, директорий, Nginx, PostgreSQL, systemd-сервисов. |
| Инженер внедрения DreamDocs | Установка дистрибутива, настройка doca.yaml и dreamocr.yaml, запуск миграций, проверка OCR и обработки документов. |
| Администратор безопасности | Проверка учетных записей, TLS/mTLS, прав доступа к файлам, сетевых правил и хранения лицензии. |
2. Термины и условные обозначения
| Обозначение | Описание | Пример |
|---|---|---|
| <version> | Версия устанавливаемого дистрибутива DreamDocs | 1.8.7.3 |
| $DREAMDOCS_RELEASE | Каталог конкретного релиза | /srv/dreamdocs-1.8.7.3 |
| $DREAMDOCS_HOME | Символическая ссылка на активный релиз | /srv/dreamdocs |
| <server_ip> | IP-адрес сервера | 192.0.2.10 |
| <server_name> | DNS-имя сервера | dreamdocs.example.ru |
| <license_path> | Путь к файлу лицензии | /srv/dreamdocs/demo.license |
| <db_name> | Имя базы данных PostgreSQL | dreamdocs |
| <db_user> | Пользователь БД | dreamdocs_user |
Для удобства установки можно задать переменные окружения в текущей сессии администратора:
export DD_VERSION="<version>"
export DREAMDOCS_RELEASE="/srv/dreamdocs-${DD_VERSION}"
export DREAMDOCS_HOME="/srv/dreamdocs"
export SERVER_IP="$(hostname -I | awk '{print $1}')"
export SERVER_NAME="<server_name>"В командах ниже значения в угловых скобках необходимо заменить на фактические значения проекта. Угловые скобки в команду не включаются.
3. Требования перед установкой
3.1 Права доступа
- Требуется:доступ к учетной записи с правами sudo.
- Требуется:право создавать системных пользователей, директории и systemd-сервисы.
- Требуется:право устанавливать системные пакеты через apt или использовать подготовленный офлайн-архив пакетов.
3.2 Программная среда
| Компонент | Требование |
|---|---|
| Операционная система | Linux-дистрибутив с apt-пакетным менеджером. Для офлайн-сценария может использоваться подготовленный архив пакетов под Astra Linux. |
| Браузер администратора | Современная версия Google Chrome, Microsoft Edge или Firefox. |
| Интернет | Рекомендуется. При отсутствии интернета необходимо заранее подготовить архивы системных пакетов, wheel-пакеты Python, дистрибутив и лицензию. |
| Python | Python 3.8.10 или совместимая версия, указанная в составе поставки. |
| Веб-сервер | Nginx. |
| База данных | PostgreSQL - при использовании внешней/выделенной БД. |
3.3 Пакеты поставки
- Архив дистрибутива DreamDocs: dreamdocs-<version>-full.zip.
- Файл лицензии DreamDocs.
- Архив системных пакетов для офлайн-установки, если сервер не имеет доступа в интернет.
- Архив Python wheel-пакетов для офлайн-установки зависимостей, если сервер не имеет доступа в интернет.
- Сертификаты и ключи TLS/mTLS, если контур требует защищенного доступа по сертификатам.
4. Подготовка сервера
4.1 Обновление пакетов
sudo apt update -y
sudo apt autoremove -y
sudo apt clean4.2 Создание пользователя и группы
Рекомендуется запускать компоненты приложения от отдельного пользователя dream, а не от root.
sudo groupadd --system dream || true
sudo useradd --system --create-home --shell /bin/bash --gid dream dream || true
sudo usermod -aG sudo dream4.3 Создание директорий
sudo mkdir -p "$DREAMDOCS_RELEASE" /srv/downloads /media/ocr
sudo ln -sfn "$DREAMDOCS_RELEASE" "$DREAMDOCS_HOME"
sudo chown -R dream:dream "$DREAMDOCS_RELEASE" "$DREAMDOCS_HOME" /srv/downloads /media/ocr
sudo chmod -R u+rwX,g+rwX,o-rwx "$DREAMDOCS_RELEASE" /srv/downloads /media/ocrНе рекомендуется использовать chmod 777 на продуктивных стендах. Если временно требуется широкий доступ на тестовом контуре, после диагностики права должны быть возвращены к ограниченной модели.
4.4 Определение IP-адреса сервера
| hostname -I | awk '{print $1}' |
|---|
4.5 Переход под пользователя приложения
sudo su - dream5. Установка системных зависимостей
5.1 Онлайн-установка
Если сервер имеет доступ к репозиториям ОС, установите системные зависимости через apt:
sudo apt install -y zlib1g-dev libncurses5-dev libgdbm-dev libnss3-dev libssl-dev libsqlite3-dev libreadline-dev libffi-dev curl libbz2-dev
sudo apt install -y libncursesw5-dev tk-dev libc6-dev libvlccore-dev libvlc-dev liblzma-dev lzma cmake
sudo apt install -y --reinstall pkg-config cmake-data
sudo apt install -y libpoppler-cpp-dev
sudo apt install -y --no-install-recommends libreoffice-calc libreoffice-common libzbar0 poppler-utils screen
sudo apt install -y tesseract-ocr tesseract-ocr-rus zbar-tools git unzip5.2 Офлайн-установка
Если сервер работает без доступа в интернет, используйте заранее подготовленный архив системных пакетов, соответствующий версии ОС.
cd /srv/downloads
curl -O <system_packages_archive_url>
tar -xvzf <system_packages_archive_name>.tgz
cd <system_packages_directory>
# В install.sh должен быть указан корректный путь до каталога packages.
./install.shПосле установки проверьте вывод install.sh. Если указаны ошибки обработки пакетов, установите недостающие пакеты вручную из локального каталога packages или повторите установку через apt при наличии доступа в интернет.
5.3 Проверка системных утилит
python3 --version || true
nginx -v || true
tesseract --version || true
pdftotext -v || true
soffice --version || true6. Загрузка и подготовка дистрибутива
6.1 Создание структуры данных
cd "$DREAMDOCS_HOME"
mkdir -p data/db data/files data/lock data/logs data/models data/search data/dump_workspace6.2 Загрузка дистрибутива
cd "$DREAMDOCS_HOME"
curl -O <dreamdocs_distribution_url>/dreamdocs-<version>-full.zip6.3 Распаковка дистрибутива
cd "$DREAMDOCS_HOME"
unzip dreamdocs-<version>-full.zip -d "$DREAMDOCS_HOME"
rm dreamdocs-<version>-full.zipЕсли unzip блокирует архив по механизму защиты от zipbomb, используйте обход только для доверенного архива поставщика: UNZIP_DISABLE_ZIPBOMB_DETECTION=TRUE unzip ... . Не отключайте защиту на неизвестных архивах.
6.4 Создание символических ссылок
Для версий 1.7.0 и выше создайте ссылки между компонентами:
ln -rsf "$DREAMDOCS_HOME/docrender/docrender" "$DREAMDOCS_HOME/dreamocr"
ln -rsf "$DREAMDOCS_HOME/docrender/docrender" "$DREAMDOCS_HOME/docaml/backend"
ln -rsf "$DREAMDOCS_HOME/docrender/docrender" "$DREAMDOCS_HOME/doca/backend"
ln -rsf "$DREAMDOCS_HOME/dreamocr/dreamocr" "$DREAMDOCS_HOME/docaml/backend"
ln -rsf "$DREAMDOCS_HOME/docanorm" "$DREAMDOCS_HOME/doca/backend"
ln -rsf "$DREAMDOCS_HOME/docanorm" "$DREAMDOCS_HOME/docaml/backend"Для версий ниже 1.7.0 используется сокращенная ссылка:
ln -rs "$DREAMDOCS_HOME/dreamocr/dreamocr" "$DREAMDOCS_HOME/docaml/backend"7. Настройка конфигурационных файлов
7.1 Файл doca.yaml
Создайте или отредактируйте файл doca.yaml в корневом каталоге DreamDocs.
cd "$DREAMDOCS_HOME"
cp -n doca.yaml doca.yaml.backup 2>/dev/null || true
mcedit doca.yamlРекомендуемая структура файла:
OCR_KEY: "<ocr_token>"
DREAMOCR_DATA_PATH: "/srv/dreamdocs/dreamocr.data"
ALLOWED_HOSTS:
- "localhost"
- "127.0.0.1"
- "0.0.0.0"
- "<server_ip>"
- "<server_name>"
LICENSE_PATH: "<license_path>"7.2 Файл dreamocr.yaml
Создайте или отредактируйте файл dreamocr.yaml в корневом каталоге DreamDocs.
cd "$DREAMDOCS_HOME"
cp -n dreamocr.yaml dreamocr.yaml.backup 2>/dev/null || true
mcedit dreamocr.yamlРекомендуемая структура файла:
OCR_TIMEOUT: -1
DREAMOCR_DATA_PATH: "/srv/dreamdocs/dreamocr.data"
ALLOWED_TOKENS:
"<ocr_token>": "<ocr_token>"
ALLOWED_HOSTS:
- "localhost"
- "127.0.0.1"
- "0.0.0.0"
- "<server_ip>"
- "<server_name>"
LICENSE_PATH: "<license_path>"Для продуктивного стенда не используйте тестовый токен test/test. Значение OCR_KEY в doca.yaml должно соответствовать токену, разрешенному в dreamocr.yaml.
8. Установка Python и зависимостей приложения
8.1 Загрузка исходников Python
cd /srv
mkdir -p .Python3.8
cd .Python3.8
curl -O https://www.python.org/ftp/python/3.8.10/Python-3.8.10.tar.xz
tar -xf Python-3.8.10.tar.xz
rm Python-3.8.10.tar.xz8.2 Сборка и установка Python
cd /srv/.Python3.8/Python-3.8.10
./configure --enable-optimizations
make -j 4
sudo make altinstall
python3.8 -VОжидаемый результат проверки версии: Python 3.8.10.
8.3 Создание виртуального окружения
cd "$DREAMDOCS_HOME"
python3.8 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip setuptools wheel8.4 Установка Python-зависимостей онлайн
cd "$DREAMDOCS_HOME"
pip install -r doca/requirements.txt
pip install -r docaml/requirements.txt
pip install -r dreamocr/requirements.txt8.5 Установка Python-зависимостей офлайн
При отсутствии доступа в интернет заранее перенесите архив wheel-пакетов на сервер в /srv/downloads.
cd /srv/downloads
unzip pypack-<version>.zip -d /srv/downloads/pypack-<version>
cd "$DREAMDOCS_HOME"
pip install --no-index --find-links /srv/downloads/pypack-<version> -r doca/requirements.txt
pip install --no-index --find-links /srv/downloads/pypack-<version> -r docaml/requirements.txt
pip install --no-index --find-links /srv/downloads/pypack-<version> -r dreamocr/requirements.txt8.6 Символические ссылки виртуального окружения
ln -rsf "$DREAMDOCS_HOME/.venv" "$DREAMDOCS_HOME/doca"
ln -rsf "$DREAMDOCS_HOME/.venv" "$DREAMDOCS_HOME/docaml"
ln -rsf "$DREAMDOCS_HOME/.venv" "$DREAMDOCS_HOME/dreamocr"Если при запуске возникает ошибка No module named IPython, установите пакет в активированном виртуальном окружении командой pip install ipython. Если ошибка связана с компиляцией зависимости, сначала установите недостающий системный пакет, затем пересоздайте .venv.
9. Настройка Nginx
9.1 Установка и подготовка
sudo apt install -y nginx
sudo usermod -aG dream www-data || true
sudo cp /etc/nginx/nginx.conf /etc/nginx/nginx.conf.backup.$(date +%Y%m%d%H%M%S)9.2 Конфигурация HTTP
Базовая конфигурация для доступа через HTTP:
events {
worker_connections 1024;
}
http {
include /etc/nginx/mime.types;
server {
listen 80;
server_name 127.0.0.1 <server_ip> <server_name>;
root /srv/dreamdocs/doca/public/;
index index.html;
charset utf-8;
source_charset utf-8;
client_max_body_size 2500M;
location / {
proxy_read_timeout 600s;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto http;
proxy_cache_bypass $http_upgrade;
proxy_pass http://127.0.0.1:8000;
proxy_redirect off;
}
location ~ ^/(lib|css|js|img|fonts|v2design|favicon.ico) {
try_files $uri /empty.html;
}
location /static/ {
alias /srv/dreamdocs/doca/static/;
try_files $uri =404;
}
location /files/ {
alias /srv/dreamdocs/data/files/;
try_files $uri =404;
}
}
}9.3 Конфигурация HTTPS/mTLS
Если контур требует взаимную аутентификацию по сертификатам, используйте HTTPS-конфигурацию с mTLS:
events {
worker_connections 1024;
}
http {
include /etc/nginx/mime.types;
server {
listen 443 ssl;
server_name <server_name>;
ssl_certificate /path/to/certs/app.crt;
ssl_certificate_key /path/to/certs/private/app.key;
ssl_client_certificate /path/to/certs/rootCA.pem;
ssl_verify_client on;
ssl_protocols TLSv1.2 TLSv1.3;
ssl_prefer_server_ciphers on;
ssl_ciphers HIGH:!aNULL:!MD5;
root /srv/dreamdocs/doca/public/;
index index.html;
charset utf-8;
source_charset utf-8;
client_max_body_size 2500M;
location / {
proxy_read_timeout 600s;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto https;
proxy_cache_bypass $http_upgrade;
proxy_pass http://127.0.0.1:8000;
proxy_redirect off;
}
location /static/ {
alias /srv/dreamdocs/doca/static/;
try_files $uri =404;
}
location /files/ {
alias /srv/dreamdocs/data/files/;
try_files $uri =404;
}
}
}9.4 Проверка и перезапуск Nginx
sudo nginx -t
sudo systemctl restart nginx
sudo systemctl status nginx --no-pager10. Настройка PostgreSQL
Раздел выполняется, если используется PostgreSQL. Если в поставке применяется иной режим хранения данных, используйте параметры, указанные в проектной конфигурации.
10.1 Установка PostgreSQL
sudo apt install -y postgresql
sudo systemctl enable postgresql
sudo systemctl status postgresql --no-pager10.2 Создание базы данных и пользователя
sudo su - postgres
psql
CREATE DATABASE <db_name>;
CREATE USER <db_user> WITH PASSWORD '<db_password>';
ALTER DATABASE <db_name> OWNER TO <db_user>;
\q
exit10.3 Настройка сетевого доступа
Если приложение и PostgreSQL размещены на одном сервере, рекомендуется оставлять PostgreSQL доступным только локально. Если требуется удаленный доступ, измените listen_addresses и pg_hba.conf согласно политике безопасности контура.
sudo mcedit /etc/postgresql/<postgres_version>/main/postgresql.conf
# listen_addresses = 'localhost' # локальный режим
# listen_addresses = '*' # только если требуется удаленный доступ
sudo mcedit /etc/postgresql/<postgres_version>/main/pg_hba.conf
sudo systemctl restart postgresql10.4 Подключение PostgreSQL в doca.yaml и dreamocr.yaml
DATABASES:
default:
ENGINE: "django.db.backends.postgresql"
NAME: "<db_name>"
USER: "<db_user>"
PASSWORD: "<db_password>"
HOST: "<db_host>"
PORT: "5432"10.5 Подключение PostgreSQL с mTLS
DATABASES:
default:
ENGINE: "django.db.backends.postgresql"
NAME: "<db_name>"
USER: "<db_user>"
PASSWORD: ""
HOST: "<db_host>"
PORT: "5432"
OPTIONS:
sslmode: "verify-full"
sslrootcert: "/app/certs/rootCA.pem"
sslcert: "/app/certs/app.crt"
sslkey: "/app/certs/app.key"10.6 Версионный workaround для длины hash/thash
Для отдельных версий при использовании PostgreSQL может потребоваться увеличить длину полей hash и thash в модели DreamOCR. Выполняйте этот шаг только при наличии соответствующей ошибки миграции или рекомендации от команды сопровождения.
cd /srv/dreamdocs/dreamocr/backend/ocr
mcedit models.py
# В модели File: изменить max_length=32 на max_length=64 для поля hash.
# В модели Task: изменить max_length=32 на max_length=64 для поля thash.Ручное изменение models.py является версионным workaround, а не стандартной операцией. Зафиксируйте изменение в журнале установки.
11. Миграции, лицензия и дополнительные модули
11.1 Применение миграций
source /srv/dreamdocs/.venv/bin/activate
cd /srv/dreamdocs/dreamocr
make migrate
cd /srv/dreamdocs/doca
make migrate11.2 Установка лицензии
Поместите файл лицензии в защищенный каталог и укажите путь к нему в doca.yaml и dreamocr.yaml.
cd /srv/dreamdocs
curl -O <license_url>
# или скопируйте файл лицензии вручную:
# scp demo.license dream@<server_ip>:/srv/dreamdocs/demo.license
chmod 640 /srv/dreamdocs/*.license 2>/dev/null || true11.3 Настройка локального GPT-модуля
Раздел выполняется только если в поставке используется локальная LLM-модель.
cd /srv/dreamdocs/docaml
make gpt-server-downloadДобавьте в /srv/dreamdocs/doca.yaml:
LOCALGPT_ENABLE: true
DEFAULT_GPT: "localgpt"
LOCALGPT_API_KEY: "<local_gpt_api_key>"
LOCALGPT_MODEL: "mistral-7b-instruct-v0.2"Запустите проверку:
cd /srv/dreamdocs/docaml
make reload
make gpt-server-cpu
make chatЕсли ответ в чате не появляется дольше 10-15 минут, проверьте screen-сессии ml-gpt-server и ml-chat.
12. Запуск компонентов DreamDocs
12.1 Запуск DreamOCR
source /srv/dreamdocs/.venv/bin/activate
cd /srv/dreamdocs/dreamocr
make _build_pyx
make runЗапустите воркеры DreamOCR. Количество воркеров зависит от числа CPU-ядер:
| CPU-ядер | Рекомендуемое количество dreamocr-worker |
|---|---|
| 8 | 3 |
| 12 | 4 |
| 16 | 6 |
cd /srv/dreamdocs/dreamocr
make worker
make worker
make worker12.2 Проверка DreamOCR
- Откройте в браузере http://127.0.0.1:9900 или http://<server_ip>:9900.
- Загрузите изображение с текстом и нажмите «Отправить».
- Проверьте, что в результате появился текстовый слой, который можно выделить мышью.
12.3 Запуск DocaML
source /srv/dreamdocs/.venv/bin/activate
cd /srv/dreamdocs/docaml
make run12.4 Запуск Doca
source /srv/dreamdocs/.venv/bin/activate
cd /srv/dreamdocs/doca
make run12.5 Проверка веб-интерфейса
- Откройте http://localhost:8000, http://<server_ip>:8000 или адрес, опубликованный через Nginx.
- Авторизуйтесь учетной записью администратора.
- Создайте тестовый проект.
- Загрузите тестовое изображение или PDF с текстом.
- Дождитесь обработки и проверьте, что документ появился в списке документов.
- Откройте документ и убедитесь, что текстовый слой выделяется и доступен для поиска.
13. Запуск Broker для версий 1.8.3+
Для версий DreamDocs выше 1.8.3 необходимо дополнительно настроить и запустить службу Broker.
13.1 Блок Nginx для Broker
Добавьте в конфигурацию Nginx блок:
location /api/evs/ {
proxy_pass http://127.0.0.1:9347/api/evs/;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto https;
proxy_set_header X-Forwarded-Referrer $http_referer;
proxy_set_header Referer $http_referer;
proxy_cache_bypass $http_upgrade;
proxy_redirect off;
}sudo nginx -t
sudo systemctl restart nginx13.2 Запуск Broker и broker-worker
cd /srv/dreamdocs/doca
make broker
cd /srv/dreamdocs/docaml
make broker-workerПо умолчанию Broker слушает 127.0.0.1:9347. При медленной обработке допустимо запустить до 3 broker-worker, если это согласовано с ресурсами сервера.
14. Импорт готовой рабочей области
Если поставляется готовый архив рабочей области, загрузите его в каталог dump_workspace и выполните импорт.
cd /srv/dreamdocs/data/dump_workspace
curl -O <workspace_dump_url>
cd /srv/dreamdocs/doca/backend
./manage.py load_workspace -wid=<workspace_id> -P <password> /srv/dreamdocs/data/dump_workspaceworkspace_id должен соответствовать номеру скачанного архива или идентификатору, указанному поставщиком. Пароль передается только по защищенному каналу.
15. Установка системных сервисов
После ручной проверки компонентов установите systemd-сервисы для штатного запуска DreamDocs.
cd /srv/dreamdocs/dreamdocs
make deploy-scripts
sudo make deploy-services
sudo systemctl daemon-reload
sudo systemctl enable dreamdocs
sudo systemctl start dreamdocs
sudo systemctl status dreamdocs --no-pager15.1 Проверка screen-сессий
screen -lsОжидаемый набор процессов после штатного запуска:
| Процесс | Ожидаемое количество | Назначение |
|---|---|---|
| dreamocr-server | 1 | OCR-сервер |
| dreamocr-worker | 3-6 | OCR-воркеры; количество зависит от CPU |
| doca-web | 1 | Веб-приложение |
| prod-indexer | 1 | Индексация данных |
| prod-trainer | 1 | Обучение моделей |
| prod-statemachine | 1 | Управление статусами обработки |
| prod-predict-fields | 2 | Предсказание полей |
| prod-predict-doctypes | 1 | Предсказание типов документов |
| broker / broker-worker | 1 / 1-3 | Службы EVS для версий 1.8.3+ |
Для выхода из screen-сессии без остановки процесса используйте Ctrl+A, затем Ctrl+D.
16. Проверка работоспособности
16.1 Технические проверки
| Проверка | Команда / действие | Ожидаемый результат |
|---|---|---|
| Nginx | sudo nginx -t | syntax is ok, test is successful |
| PostgreSQL | sudo systemctl status postgresql | Сервис active/running |
| DreamDocs services | sudo systemctl status dreamdocs | Сервис active/running |
| Screen-сессии | screen -ls | Отображаются процессы DreamDocs |
| Порты | ss -lntp | grep -E "8000|9900|9347" | Порты компонентов слушают локально или на ожидаемом интерфейсе |
16.2 Функциональные проверки
- Войти в веб-интерфейс под учетной записью администратора.
- Создать тестовый проект.
- Загрузить изображение, PDF или DOCX с читаемым текстом.
- Дождаться смены статуса обработки. Если статус «Загружается» не меняется более 10 минут, перейти к диагностике.
- Открыть документ и проверить наличие выделяемого текстового слоя.
- Проверить, что в карточке документа отображаются тип, статус, качество распознавания и распознанные поля.
16.3 Проверка логов при задержке обработки
screen -x dreamocr-worker
screen -x doca-statemachine
# Для выхода без остановки: Ctrl+A, Ctrl+D17. Типовые ошибки и устранение
| Симптом | Вероятная причина | Действие |
|---|---|---|
| Документ долго остается в статусе «Загружается» | Не запущен dreamocr-worker или statemachine; ошибка OCR; нет доступа к data/files | Проверить screen -ls, логи dreamocr-worker и doca-statemachine, права на /srv/dreamdocs/data. |
| Nginx не стартует | Ошибка в nginx.conf, неверный путь к сертификатам, занят порт | Выполнить sudo nginx -t, проверить пути, порт и синтаксис location-блоков. |
| Ошибка подключения к PostgreSQL | Неверные db_host/db_user/db_password, нет правила pg_hba.conf, PostgreSQL не слушает адрес | Проверить DATABASES, systemctl status postgresql, listen_addresses и pg_hba.conf. |
| pip не устанавливает зависимость | Не хватает системного dev-пакета или wheel в офлайн-архиве | Установить системный пакет, пересобрать/пересоздать .venv, повторить pip install. |
| Нет ответа от локального GPT | Не запущен gpt-server или chat, не скачана модель, не хватает ресурсов | Проверить screen -x ml-gpt-server и ml-chat, наличие модели и ресурсы сервера. |
| Статика не загружается в браузере | Неверный root/alias в Nginx или права на /srv/dreamdocs/doca/static | Проверить nginx.conf, права группы dream и членство www-data в группе dream. |
| Лицензия не найдена | Неверный LICENSE_PATH или файл недоступен пользователю приложения | Проверить путь, права chmod/chown и наличие файла. |
18. Контрольный чек-лист установки
| № | Контрольный пункт | Статус |
|---|---|---|
| 1 | Получены версия дистрибутива, ссылка на архив и файл лицензии. | □ |
| 2 | Создан пользователь dream и рабочие каталоги. | □ |
| 3 | Права на каталоги ограничены и проверены. | □ |
| 4 | Установлены системные зависимости. | □ |
| 5 | Дистрибутив распакован в /srv/dreamdocs-<version>, ссылка /srv/dreamdocs указывает на активный релиз. | □ |
| 6 | Созданы каталоги data/db, data/files, data/logs, data/models, data/search, data/dump_workspace. | □ |
| 7 | Настроены doca.yaml и dreamocr.yaml. | □ |
| 8 | Создано виртуальное окружение Python и установлены зависимости. | □ |
| 9 | Настроен и проверен Nginx. | □ |
| 10 | PostgreSQL настроен, если используется в контуре. | □ |
| 11 | Миграции dreamocr и doca выполнены без ошибок. | □ |
| 12 | Файл лицензии установлен и доступен приложению. | □ |
| 13 | DreamOCR, DocaML и Doca запускаются вручную. | □ |
| 14 | Для версии 1.8.3+ настроен Broker. | □ |
| 15 | Создан тестовый проект и успешно обработан тестовый документ. | □ |
| 16 | Установлены systemd-сервисы и настроен автозапуск. | □ |
| 17 | Результаты установки зафиксированы в журнале работ. | □ |
19. Рекомендации по безопасности после установки
- Заменить все тестовые токены и пароли на уникальные значения.
- Ограничить доступ к административным портам и внутренним сервисам правилами firewall.
- Использовать HTTPS; для закрытых контуров рассмотреть mTLS.
- Хранить файл лицензии и сертификаты с правами не шире 640.
- Не оставлять открытым доступ к PostgreSQL за пределами доверенной сети.
- Не использовать chmod 777 на продуктивном контуре.
- Проверить, что учетная запись dream используется только для эксплуатации DreamDocs.
- Настроить резервное копирование каталога data и базы данных, если используется PostgreSQL.