Isso на сервере: частые ошибки и решения

MAATRIX

Isso — лёгкая система комментариев на Python для статических сайтов: без JS-фреймворков на бэкенде, без обязательной внешней базы, с SQLite из коробки. Именно эта простота и подводит: конфиг из одного файла, самодельный WSGI-процесс и жёсткая проверка домена в CORS дают несколько типичных точек отказа, которые повторяются от установки к установке. Разберём их по порядку — от «комментарии не появляются» до «не приходят письма модератору» — с конкретными командами и причинами.

Комментарии не появляются на странице

Самая частая жалоба: виджет Isso просто не рисуется под статьёй, хотя сервис вроде бы работает. Причины почти всегда на стороне встраивания или CORS, а не самого Isso.

Проверьте код встраивания на странице сайта:

<script data-isso="https://comments.example.com/"
        src="https://comments.example.com/js/embed.min.js"></script>
<section id="isso-thread" data-title="{{ page.title }}"></section>

Ключевой момент — data-isso и src должны указывать на реальный, доступный извне адрес Isso, и оба обязаны заканчиваться слэшем в data-isso. Открыв консоль браузера (F12 → Network), проверьте, что запрос к embed.min.js и последующие запросы к API (/count, /thread/...) возвращают 200, а не 404 или CORS-ошибку.

Если в консоли вы видите ошибку вида «has been blocked by CORS policy», значит домен страницы не совпадает с тем, что указан в isso.cfg:

[general]
host = https://example.com/

Isso сверяет заголовок Origin запроса именно с этим значением, и совпадение должно быть точным — включая протокол и наличие или отсутствие www. Если сайт открывается и по https://example.com/, и по https://www.example.com/, добавьте оба варианта через запятую:

host = https://example.com/, https://www.example.com/

После правки конфига перезапустите сервис (см. следующий раздел) — Isso читает isso.cfg только при старте.

Isso не запускается или падает systemd-юнит

Isso не имеет собственного демона в классическом смысле — обычно его запускают как процесс через systemd, с встроенным сервером на базе gevent/waitress. Типичный юнит:

[Unit]
Description=Isso comment server
After=network.target

[Service]
User=isso
Group=isso
WorkingDirectory=/opt/isso
ExecStart=/opt/isso/venv/bin/isso -c /etc/isso/isso.cfg run
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target

Если сервис не стартует, первым делом смотрите статус и журнал:

systemctl status isso
journalctl -u isso -n 100 --no-pager

Частые причины падения:

• Неверный путь до venv или бинарника — проверьте ExecStart, особенно после переустановки Python или пересборки окружения.
• Конфиг с синтаксической ошибкой — Isso использует формат INI, лишний отступ или незакрытая секция ломают парсинг. Проверьте конфиг вручную: /opt/isso/venv/bin/isso -c /etc/isso/isso.cfg run (запуск в foreground сразу покажет traceback).
• Порт уже занят — если в [server] listen = http://localhost:8080/, а порт 8080 уже слушает другой процесс, Isso не поднимется. Проверьте: ss -tlnp | grep 8080.
• Права на директорию с базой — если пользователь isso не может писать в каталог с dbpath, процесс падает при первом обращении к базе, а не сразу при старте. Смотрите следующий раздел.

Ошибки SQLite: «database is locked» и права на файл

Isso по умолчанию хранит комментарии в SQLite-файле, путь к которому задаётся в isso.cfg:

[general]
dbpath = /var/lib/isso/comments.db

SQLite не рассчитан на параллельную запись из нескольких процессов — и если вы случайно запустили два экземпляра Isso (например, старый процесс не завершился после systemctl restart, и рядом поднялся новый), при попытке записи комментария начнут сыпаться ошибки database is locked. Проверьте, что процесс действительно один:

pgrep -af isso

Если процессов больше одного — остановите лишние и перезапустите сервис штатно через systemd, а не вручную в фоне.

Вторая частая причина — права на файл и каталог. После переноса базы с другого сервера или ручного редактирования владелец файла может не совпадать с пользователем, от имени которого запущен Isso:

chown isso:isso /var/lib/isso/comments.db
chmod 640 /var/lib/isso/comments.db
ls -la /var/lib/isso/

Каталог, где лежит база, тоже должен быть доступен на запись этому пользователю — SQLite создаёт временные journal-файлы рядом с основной базой.

Отдельно стоит сделать резервную копию перед любым вмешательством — база одна и восстановить историю комментариев без бэкапа не получится:

sqlite3 /var/lib/isso/comments.db ".backup /var/backups/isso-$(date +%F).db"

Если после обновления Isso до новой версии сервис не стартует с ошибкой о структуре таблиц — это, как правило, недоведённая миграция схемы базы. В таком случае откатите пакет до прежней версии, восстановите базу из бэкапа и обновляйтесь заново, внимательно читая changelog релиза.

Nginx перед Isso: 502, 504 и проблемы с путями

Isso почти всегда работает за Nginx как reverse proxy — сам он не предназначен для прямого приёма трафика из интернета. Базовый location:

location /comments/ {
    proxy_pass http://127.0.0.1:8080/;
    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 $scheme;
    proxy_read_timeout 60s;
}

Здесь легко ошибиться со слэшами: если location /comments/ (со слэшем в конце) проксирует на proxy_pass http://127.0.0.1:8080/ (тоже со слэшем), Nginx обрежет префикс /comments/ при передаче запроса. Уберите слэш в конце proxy_pass, и префикс, наоборот, будет передан бэкенду целиком, что Isso не ожидает. Держите оба варианта согласованными и после правки сверяйте реальные запросы в логе:

tail -f /var/log/nginx/access.log | grep comments

502 Bad Gateway означает, что Nginx достучался до порта, но процесс Isso не ответил или упал — проверьте systemctl status isso, это отсылка к разделу выше. Если в логе Nginx connect() failed (111: Connection refused) — процесс вообще не слушает нужный адрес; сверьте listen в isso.cfg с тем, что указано в proxy_pass.

504 Gateway Timeout реже, но встречается при большом количестве комментариев на одной странице или при холодном старте после долгого простоя — Isso не оптимизирован под тысячи записей в одном треде. Если такое повторяется стабильно, увеличьте proxy_read_timeout и проверьте нагрузку на диск, где лежит SQLite-файл — на медленном сетевом хранилище это ощутимо. Похожая логика диагностики 502/504 подробно разобрана в статье про Nginx как reverse proxy на сервере, если вы впервые настраиваете прокси именно для Python-приложений.

Если сайт целиком уже переехал под HTTPS, а поддомен для Isso — ещё нет, браузер заблокирует смешанный контент и виджет не подгрузится вовсе. Выпустите отдельный сертификат на поддомен комментариев тем же способом, что и для основного домена; частые причины отказа certbot разобраны в статье про ошибки выпуска SSL в Nginx.

Не приходят письма модератору, комментарии зависают в очереди

По умолчанию у Isso нет отдельной веб-панели с логином для модерации — вместо этого модератор получает письмо на каждый новый комментарий со ссылками «одобрить» и «удалить», защищёнными токеном в самой ссылке. Если письма не приходят, комментарии просто копятся в статусе «на модерации» и никогда не появляются на сайте.

Настройки почты — в секции [smtp] конфига:

[smtp]
username = isso@example.com
password = ваш_пароль_или_токен_приложения
host = smtp.example.com
port = 587
security = starttls
to = admin@example.com
from = isso@example.com

Частые причины, по которым письма не доходят:

• Заблокирован исходящий SMTP-порт у провайдера — многие облачные площадки режут 25-й порт по умолчанию, но 587 обычно открыт; проверьте telnet smtp.example.com 587 с самого сервера.
• Неверный пароль приложения, если почта на Gmail/Yandex — обычный пароль от аккаунта для SMTP через сторонние клиенты не подходит, нужен отдельный пароль приложения.
• security не совпадает с портом — для 587 нужен starttls, для 465 — ssl, перепутанная комбинация даёт ошибку соединения, которую видно в journalctl -u isso.

Если письма явно уходят (это видно в логе Isso при notify = smtp в секции [general]), но не доходят до ящика — проверьте папку «Спам» и SPF/DKIM у домена отправителя: письма от свежего домена без настроенных записей нередко режутся почтовыми провайдерами получателя.

Комментарии не сохраняются: CSRF, cookies и рассинхронизация времени

Реже, но неприятнее: форма отправляется, страница обновляется — а комментарий не появляется, либо в консоли видна ошибка 403 или сообщение о том, что нужно включить cookies. Isso использует cookie для идентификации автора и защиты от подделки запроса (CSRF), и эта cookie привязана к домену из host в конфиге — тому же значению, что отвечает за CORS из первого раздела.

Проверьте три вещи:

1. Совпадение host в конфиге и реального адреса страницы — включая протокол. Если сайт временно доступен и по HTTP, и по HTTPS (например, редирект ещё не настроен), cookie с флагом Secure не проставится на HTTP-версии, и последующая проверка CSRF будет падать.
2. Системное время сервера — если оно расходится с реальным больше чем на пару минут, токены с ограниченным сроком жизни (в том числе антиспам-таймер Isso, который отклоняет слишком быстрые повторные отправки) будут работать некорректно. Синхронизируйте время: timedatectl set-ntp true и timedatectl status.
3. Блокировщики cookies или расширения приватности у читателя — это не серверная проблема, но стоит явно предупредить пользователей в UI, если сайт ориентирован на аудиторию с включённым строгим приватным режимом браузера — часть виджетов комментариев в таком окружении не работает в принципе, и это ограничение архитектуры, а не баг конкретной установки.

Отдельно — антиспам в секции [guard]:

[guard]
enabled = true
ratelimit = 2
direct-reply = 3
reply-to-self = false

Если ratelimit выставлен слишком строго, легитимные читатели с общим IP (офис, VPN, мобильный оператор с NAT) начинают получать отказы при попытке оставить второй комментарий подряд. Если жалобы на «не могу отправить комментарий» участились именно с этой формулировкой — ослабьте лимит и понаблюдайте.

Частые вопросы