infra/install/ISSUES.md

Known Issues — стек платформы

Документ пополняется по мере тестирования и исследований.
Каждая проблема: описание → причина → решение → статус.

Формат записи

### [ID] Название
**Компоненты:** A + B
**Severity:** critical | warning | info
**Статус:** open | fixed | wontfix | bypassed

**Проблема:** что происходит
**Причина:** почему
**Решение:** как исправить (с кодом)
**Источник:** ссылка

🔴 CRITICAL

[I-001] Vaultwarden — мобильные клиенты не работают за Authelia

Компоненты: Vaultwarden + Authelia + Traefik
Severity: critical
Статус: bypassed

Проблема: Bitwarden на Android/iOS, десктоп-клиент и расширение браузера
не могут пройти через Authelia forward-auth. Получают 302 redirect →
показывают "неверный пароль" или "не удаётся подключиться к серверу".

Причина: Нативные клиенты используют свой HTTP-стек, не умеют
следовать cookie-based redirect как браузер.

Решение: Bypass в Authelia для API-путей Vaultwarden:

# authelia/configuration.yml → access_control.rules
- domain: vault.aipd.ru
  resources:
    - "^/api([/?].*)?$"
    - "^/identity([/?].*)?$"
    - "^/notifications([/?].*)?$"
    - "^/icons([/?].*)?$"
  policy: bypass        # Vaultwarden сам авторизует клиентов
- domain: vault.aipd.ru
  resources:
    - "^/admin([/?].*)?$"
  policy: two_factor    # admin-панель защищаем через Authelia
- domain: vault.aipd.ru
  policy: bypass        # остальное тоже Vaultwarden

Источник: github.com/dani-garcia/vaultwarden/discussions/3970

🟡 WARNING

[I-002] WireGuard + Docker — трафик из VPN блокируется

Компоненты: WireGuard + Docker
Severity: warning
Статус: open

Проблема: VPN-клиенты подключаются к WireGuard, но не могут достучаться
до Docker-сервисов. Трафик молча дропается.

Причина: Docker выставляет default DROP на цепочку FORWARD в iptables.
Трафик из wg0 попадает в FORWARD и не имеет разрешающего правила.

Решение: В /etc/wireguard/wg0.conf:

PostUp   = iptables -I DOCKER-USER -i wg0 -j ACCEPT; \
           iptables -I DOCKER-USER -o wg0 -j ACCEPT
PreDown  = iptables -D DOCKER-USER -i wg0 -j ACCEPT; \
           iptables -D DOCKER-USER -o wg0 -j ACCEPT

Примечание: Требует iptables-legacy (см. I-003).

[I-003] Ubuntu 22.04 — конфликт nftables и Docker/WireGuard

Компоненты: Ubuntu 22.04 + Docker + WireGuard
Severity: warning
Статус: open

Проблема: Ubuntu 22.04 использует nftables по умолчанию. Docker и WireGuard
пишут iptables-правила в разные бэкенды → правила не видят друг друга.
Цепочка DOCKER-USER отсутствует в nftables-режиме.

Причина: Системный iptables указывает на iptables-nft, но Docker
ожидает iptables-legacy.

Решение: Переключить до первого запуска Docker:

update-alternatives --set iptables  /usr/sbin/iptables-legacy
update-alternatives --set ip6tables /usr/sbin/ip6tables-legacy
reboot   # или: systemctl restart docker

Важно: Делать ДО docker compose up, иначе правила перемешаются.

[I-004] Gitea + Authelia OIDC — PKCE не поддерживается Gitea

Компоненты: Gitea 1.21 + Authelia 4.38
Severity: warning
Статус: open

Проблема: Authelia 4.38 включает require_pkce: true по умолчанию.
Gitea не отправляет code_challenge → вход через SSO падает с ошибкой.

Решение: В authelia/configuration.yml:

identity_providers:
  oidc:
    clients:
      - client_id: gitea
        require_pkce: false   # ← обязательно
        # ... остальные параметры

Источник: github.com/go-gitea/gitea/issues/34747

[I-005] Gitea + Authelia OIDC — первый admin становится обычным юзером

Компоненты: Gitea 1.21 + Authelia OIDC
Severity: warning
Статус: open

Проблема: При первом входе через OIDC Gitea создаёт пользователя как
обычного (не admin), даже если в claims передан admin-флаг.
При повторном входе — ошибка 500 "cannot delete last admin".

Решение: После первого OIDC-входа вручную через Gitea admin-панель
(/admin/users) назначить пользователю роль администратора до того,
как локальный admin-аккаунт будет удалён.

Источник: github.com/go-gitea/gitea/issues/34358

[I-006] Portainer + Authelia — увеличенные буферы

Компоненты: Portainer CE + Authelia
Severity: warning
Статус: open

Проблема: Portainer отправляет большие auth-заголовки. Дефолтный буфер
Authelia (4096 bytes) может быть мал → периодические 502.

Решение: В authelia/configuration.yml:

server:
  buffers:
    read: 16384
    write: 16384

Источник: github.com/authelia/authelia/discussions/4959

[I-007] Traefik v3 — middleware не найден между стеками

Компоненты: Traefik v3 + Authelia + несколько docker-compose стеков
Severity: warning
Статус: open

Проблема: authelia@docker middleware не виден из других compose-стеков.
Сервисы получают "middleware not found" и падают в 500.

Причина: Traefik видит middleware только если контейнер в той же Docker-сети.

Решение:
1. Все стеки используют общую внешнюю сеть proxy-net
2. На контейнере Authelia явно указать сеть:

labels:
  - "traefik.docker.network=proxy-net"
  1. Authelia подключена только к proxy-net (не к нескольким сетям).

[I-008] Traefik v3 + Authelia — устаревший URL endpoint

Компоненты: Traefik v3 + Authelia 4.38
Severity: warning
Статус: open

Проблема: Старый endpoint /api/verify?rd= более не рекомендуется
в Authelia 4.38. Конфиги скопированные из старых гайдов используют его.

Решение: Использовать актуальный endpoint:

# В labels на контейнере Authelia:
- "traefik.http.middlewares.authelia.forwardAuth.address=\
   http://authelia:9091/api/authz/forward-auth"

Источник: authelia.com/blog/4.38-release-notes

[I-009] Restic — бэкап живых SQLite баз даёт повреждённый файл

Компоненты: Restic + Gitea (SQLite) + Vaultwarden (SQLite)
Severity: warning
Статус: open

Проблема: Прямой бэкап файла *.db пока контейнер работает может
захватить базу в середине транзакции → файл повреждён.
При WAL-режиме дополнительно есть -wal и -shm файлы — бэкап только
основного файла без них тоже повреждён.

Решение — вариант А (рекомендуется, downtime ~5 сек):

docker stop gitea
restic backup /opt/platform/data/gitea/gitea.db
docker start gitea

Решение — вариант Б (без downtime):

docker exec gitea sqlite3 /data/gitea.db ".backup '/tmp/gitea-backup.db'"
restic backup /tmp/gitea-backup.db
rm /tmp/gitea-backup.db

[I-010] Gitea SQLite — медленные запросы фризят весь интерфейс

Компоненты: Gitea + SQLite
Severity: warning
Статус: open

Проблема: SQLite — single-writer. Один тяжёлый запрос (поиск, большой
список репозиториев) блокирует всё: и web UI, и git push по SSH.

Решение: Включить WAL mode в gitea/app.ini:

[database]
DB_TYPE            = sqlite3
SQLITE_JOURNAL_MODE = WAL
SQLITE_TIMEOUT      = 500

Источник: github.com/go-gitea/gitea/issues/28933

🟢 INFO

[I-011] Uptime Kuma — кратковременный "cannot connect" при первом входе

Компоненты: Uptime Kuma + Authelia + Traefik
Severity: info
Статус: open

Проблема: При первом открытии страницы Socket.IO пытается подключиться
до того как Authelia установил cookie → мигает "cannot connect to socket".
Исчезает само после загрузки страницы.

Причина: WebSocket upgrade происходит параллельно с установкой сессии.

Решение: Не требует действий — cosmetic issue.
Убедиться что Traefik v3 стабильный релиз (не RC).

[I-012] Claude Code контейнеры — необходимы memory limits

Компоненты: Docker + Claude Code (Node.js)
Severity: info
Статус: open

Проблема: Один активный Claude Code контейнер может потребить 500MB+.
При 3-5 одновременных — возможен OOM, который убьёт Traefik и весь стек.

Решение: В docker-compose для каждого проектора:

deploy:
  resources:
    limits:
      memory: 2g
      cpus: "2.0"

[I-013] Traefik acme.json — риск повреждения при параллельной записи

Компоненты: Traefik v3 + Let's Encrypt
Severity: info
Статус: open

Проблема: Файл acme.json (хранилище SSL-сертификатов) может быть
повреждён при параллельных обновлениях сертификатов.

Решение:
1. Бэкапить acme.json регулярно через restic
2. Права доступа: chmod 600 acme.json
3. При повреждении: удалить файл → Traefik перевыпустит сертификаты автоматически
(но будет downtime ~1 минута)