Устранение неполадок

Эта страница охватывает распространённые проблемы и их решения при работе с OpenPR.

Подключение к базе данных

API не запускается с ошибкой "connection refused"

API-сервер запускается раньше, чем PostgreSQL готов.

Решение: Файл Docker Compose включает проверки работоспособности и depends_on с condition: service_healthy. Если проблема сохраняется, увеличьте start_period PostgreSQL:

postgres:
  healthcheck:
    start_period: 30s  # Увеличьте с 10с по умолчанию

"role openpr does not exist"

Пользователь PostgreSQL не был создан.

Решение: Убедитесь, что POSTGRES_USER и POSTGRES_PASSWORD установлены в окружении Docker Compose. При ручном запуске PostgreSQL:

createuser -U postgres openpr
createdb -U postgres -O openpr openpr

Миграции не применены

Миграции запускаются автоматически только при первом запуске контейнера PostgreSQL (через docker-entrypoint-initdb.d).

Решение: Если база данных уже существует, примените миграции вручную:

docker exec -it openpr-postgres psql -U openpr -d openpr
# Затем выполните каждый файл SQL миграции по порядку

Или пересоздайте том:

docker-compose down -v
docker-compose up -d

Потеря данных

docker-compose down -v удаляет том базы данных. Сначала создайте резервную копию данных.

Аутентификация

"Invalid token" после перезапуска сервера

JWT-токены подписываются с помощью JWT_SECRET. Если это значение меняется между перезапусками, все существующие токены становятся недействительными.

Решение: Установите фиксированный JWT_SECRET в .env:

JWT_SECRET=your-fixed-random-secret-here

Первый пользователь не является admin

Роль admin присваивается первому зарегистрировавшемуся пользователю. Если вы видите role: "user" вместо role: "admin", другой аккаунт был зарегистрирован первым.

Решение: Обновите роль через базу данных:

docker exec -it openpr-postgres psql -U openpr -d openpr \
  -c "UPDATE users SET role = 'admin' WHERE email = '[email protected]';"

Docker / Podman

Сборка Podman завершается с ошибкой DNS

Стандартная сеть Podman не имеет DNS-доступа во время сборки.

Решение: Всегда используйте --network=host при сборке образов с Podman:

sudo podman build --network=host --build-arg APP_BIN=api -f Dockerfile.prebuilt -t openpr_api .

Фронтенд показывает "502 Bad Gateway"

Контейнер Nginx не может подключиться к API-серверу.

Решение: Проверьте, что:

1. Контейнер API запущен: docker-compose ps
2. Проверка работоспособности API проходит: docker exec openpr-api curl -f http://localhost:8080/health
3. Оба контейнера находятся в одной сети: docker network inspect openpr_openpr-network

Конфликты портов

Другой сервис использует тот же порт.

Решение: Измените маппинг внешнего порта в docker-compose.yml:

api:
  ports:
    - "8082:8080"  # Изменено с 8081

MCP-сервер

"tools/list возвращает пустой список"

MCP-сервер не может подключиться к API.

Решение: Проверьте переменные окружения:

docker exec openpr-mcp-server env | grep OPENPR

Убедитесь, что:

• OPENPR_API_URL указывает на правильный эндпоинт API
• OPENPR_BOT_TOKEN — действительный токен бота (начинается с opr_)
• OPENPR_WORKSPACE_ID — действительный UUID рабочего пространства

Транспорт stdio не работает

Бинарный файл MCP должен быть настроен как команда в вашем AI-клиенте.

Решение: Убедитесь, что путь к бинарному файлу правильный и переменные окружения установлены:

{
  "mcpServers": {
    "openpr": {
      "command": "/absolute/path/to/mcp-server",
      "args": ["--transport", "stdio"],
      "env": {
        "OPENPR_API_URL": "http://localhost:3000",
        "OPENPR_BOT_TOKEN": "opr_...",
        "OPENPR_WORKSPACE_ID": "..."
      }
    }
  }
}

Соединение SSE обрывается

SSE-соединения могут быть закрыты прокси-серверами с коротким таймаутом.

Решение: При использовании обратного прокси увеличьте таймаут для SSE-эндпоинта:

# Caddy
reverse_proxy /sse localhost:8090 {
    flush_interval -1
}

Фронтенд

Пустая страница после развёртывания

Сборка фронтенда может использовать неправильный URL API.

Решение: Установите VITE_API_URL перед сборкой:

VITE_API_URL=https://your-domain.example.com/api npm run build

Вход работает, но страницы пустые

API-запросы завершаются неудачей без видимых ошибок. Проверьте консоль браузера (F12) на наличие ошибок 401 или CORS.

Решение: Убедитесь, что API доступен из браузера и CORS настроен. Фронтенд должен проксировать API-запросы через Nginx.

Производительность

Медленный поиск

PostgreSQL полнотекстовый поиск может быть медленным на больших наборах данных без надлежащих индексов.

Решение: Убедитесь, что индексы FTS существуют (они создаются миграциями):

-- Проверка существующих индексов
SELECT indexname FROM pg_indexes WHERE tablename = 'work_items';

Высокое потребление памяти

API-сервер обрабатывает загрузку файлов в памяти.

Решение: Ограничьте размеры загружаемых файлов и следите за директорией uploads/. Рассмотрите настройку периодической очистки старых загрузок.

Получение помощи

Если ваша проблема не описана здесь:

1. Проверьте GitHub Issues на наличие известных проблем.
2. Просмотрите логи API и MCP-сервера на наличие сообщений об ошибках.
3. Откройте новый issue с логами ошибок, деталями окружения и шагами воспроизведения.