Wiki.js - установка и настройка на Debian

[Admin]

Содержание

[Admin]

ВНИМАНИЕ ! Инструкция не проверена

---

Подробная инструкция по установке и настройке Wiki.js на Debian 12/13 с использованием Docker

Эта инструкция основана на анализе распространенных проблем и рекомендаций из обсуждений по установке Wiki.js в Docker. Мы сосредоточимся на стабильной версии Wiki.js 2.x (актуальной на декабрь 2025 года), использовании PostgreSQL как базы данных, настройке прав доступа для избежания ошибок типа EACCES, интеграции с Nginx для HTTPS и поддержке русского языка. Установка будет проводиться в защищенной среде с учетом лучших практик 2025 года.

Wiki.js — это современная вики-система на Node.js, идеальная для многоуровневой документации, включая поддержку кириллицы в путях и навигации. Мы используем Docker для изоляции и простоты управления.

Важные предупреждения:

• Убедитесь, что у вас есть домен (например, wiki.example.com), настроенный на IP вашего сервера.
• Все команды выполняйте от пользователя с sudo-доступом.
• Если вы на Debian 13 (Trixie), инструкции аналогичны Debian 12 (Bookworm), но проверьте обновления пакетов.
• Перед началом обновите систему: sudo apt update && sudo apt upgrade -y.

1. Предварительные требования

• Сервер: Debian 12 или 13 с минимум 2 ГБ RAM и 20 ГБ SSD (рекомендуется VPS или dedicated server).
• Пакеты: Установите необходимые зависимости:

  sudo apt install -y curl git ca-certificates gnupg lsb-release
  

• Firewall: Разрешите порты 80 (HTTP), 443 (HTTPS) и 3000 (временно для Wiki.js):

  sudo ufw allow 80/tcp
  sudo ufw allow 443/tcp
  sudo ufw allow 3000/tcp  # Удалите после настройки Nginx
  sudo ufw reload
  

• Домен и DNS: Настройте A-запись для вашего домена на IP сервера.

2. Установка Docker и Docker Compose

Docker — ключевой компонент для запуска Wiki.js в контейнере. Установите официальную версию:

1. Добавьте репозиторий Docker:

   sudo mkdir -p /etc/apt/keyrings
   curl -fsSL https://download.docker.com/linux/debian/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
   echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/debian $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
   sudo apt update
   

2. Установите Docker:

   sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
   

3. Запустите и добавьте в автозагрузку:

   sudo systemctl start docker
   sudo systemctl enable docker
   

4. Добавьте вашего пользователя в группу docker (чтобы избежать sudo для docker-команд):

   sudo usermod -aG docker $USER
   newgrp docker  # Или перелогиньтесь
   

Проверьте: docker --version и docker compose version (должно быть v2+).

3. Подготовка директорий и конфигурации

Создайте директорию для Wiki.js (рекомендуем /opt/wikijs для системности):

sudo mkdir -p /opt/wikijs/{data,backup,postgres,config}
cd /opt/wikijs

• /opt/wikijs/data: Для данных Wiki.js (страницы, uploads, content).
• /opt/wikijs/backup: Для бэкапов.
• /opt/wikijs/postgres: Для данных PostgreSQL.
• /opt/wikijs/config: Для config.yml (опционально, для ручной правки).

Настройте права (чтобы избежать EACCES ошибок). Wiki.js в контейнере работает от пользователя с UID 1000 (node), так что:

sudo chown -R 1000:1000 /opt/wikijs/data /opt/wikijs/backup /opt/wikijs/config
sudo chmod -R 775 /opt/wikijs/data /opt/wikijs/backup /opt/wikijs/config

4. Создание docker-compose.yml и .env

Создайте файл docker-compose.yml в /opt/wikijs:

version: "3.9"

services:
  postgres:
    image: postgres:17-alpine
    container_name: wikijs-postgres
    restart: unless-stopped
    environment:
      POSTGRES_DB: wikijs
      POSTGRES_USER: wikijs
      POSTGRES_PASSWORD: ${WIKIJS_DB_PASS}
    volumes:
      - /opt/wikijs/postgres:/var/lib/postgresql/data
    logging:
      driver: "none"

  wiki:
    image: ghcr.io/requarks/wiki:2
    container_name: wikijs
    user: "1000:1000"  # Фиксируем UID/GID для прав
    restart: unless-stopped
    depends_on:
      - postgres
    environment:
      DB_TYPE: postgres
      DB_HOST: postgres
      DB_PORT: 5432
      DB_USER: wikijs
      DB_PASS: ${WIKIJS_DB_PASS}
      DB_NAME: wikijs
      HOME: /wiki/data  # Альтернатива для избежания EACCES на /home/node
    ports:
      - "3000:3000"  # Временно для установки
    volumes:
      - /opt/wikijs/data:/wiki/data
      - /opt/wikijs/backup:/wiki/backup
      - /opt/wikijs/config:/wiki/config  # Опционально

Создайте файл .env для безопасного хранения пароля (замените на сильный пароль):

WIKIJS_DB_PASS=Sup3rS3cr3tPass2025!

Это предотвращает хранение пароля в compose-файле.

5. Запуск Wiki.js и начальная настройка

1. Запустите контейнеры:

   cd /opt/wikijs
   docker compose up -d
   

2. Проверьте логи (убедитесь, что нет ошибок):

   docker compose logs wiki
   

   Ищите "Database Connection Successful" и отсутствие EACCES.

3. Откройте в браузере: http://ваш-IP:3000

   • Создайте аккаунт админа (email и пароль).
   • Укажите Site URL: https://wiki.example.com (обязательно с https!).
   • Отключите телеметрию.
   • Нажмите Install.

4. Если возникнут ошибки EACCES при сохранении страниц:

   • Проверьте права на хосте: ls -ld /opt/wikijs/data (должно быть drwxrwxr-x 1000 1000).
   • Если проблема в /home/node, добавьте в environment: HOME: /wiki/data (как в примере выше).
   • Перезапустите: docker compose down && docker compose up -d.

6. Настройка Nginx для reverse proxy и HTTPS

Nginx обеспечит доступ по HTTPS и скроет порт 3000.

1. Установите Nginx и Certbot:

   sudo apt install -y nginx certbot python3-certbot-nginx
   

2. Создайте конфиг для вашего домена (/etc/nginx/sites-available/wiki.example.com):

   server {
       listen 80;
       server_name wiki.example.com;
       return 301 https://$server_name$request_uri;
   }
   
   server {
       listen 443 ssl http2;
       server_name wiki.example.com;
   
       ssl_certificate /etc/letsencrypt/live/wiki.example.com/fullchain.pem;
       ssl_certificate_key /etc/letsencrypt/live/wiki.example.com/privkey.pem;
       include /etc/letsencrypt/options-ssl-nginx.conf;
       ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem;
   
       location / {
           proxy_pass http://127.0.0.1:3000;
           proxy_http_version 1.1;
           proxy_set_header Upgrade $http_upgrade;
           proxy_set_header Connection "upgrade";
           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_set_header X-Forwarded-Host $host;
           proxy_cache off;
           proxy_buffering off;
           proxy_read_timeout 100s;
       }
   
       client_max_body_size 100M;  # Для загрузки больших файлов
   }
   

3. Активируйте конфиг:

   sudo ln -s /etc/nginx/sites-available/wiki.example.com /etc/nginx/sites-enabled/
   sudo nginx -t  # Проверьте синтаксис
   sudo systemctl restart nginx
   

4. Получите сертификат Let’s Encrypt:

   sudo certbot --nginx -d wiki.example.com
   

   • Укажите email, согласитесь с условиями.
   • Certbot обновит конфиг автоматически.

5. Уберите порт 3000 из docker-compose.yml (закомментируйте или удалите строку ports: - "3000:3000").

   docker compose down && docker compose up -d
   

Теперь Wiki.js доступен по https://wiki.example.com.

7. Установка русского языка и настройка навигации

1. Зайдите под админом: Administration > Localization > Language Packs.
2. Нажмите +, найдите "Russian", скачайте.
3. Выберите Russian как основной язык, нажмите Apply.
4. Перезагрузите страницу — интерфейс на русском.

Для многоуровневой документации:

• Создавайте страницы с путями вроде /руководство/подраздел/детали (кириллица поддерживается).
• В Administration > Navigation выберите Custom Navigation для вложенных меню (группы для уровней >2).
• Если ограничение на 2 уровня: Убедитесь в UTF-8 в базе (в контейнере postgres: docker exec -it wikijs-postgres psql -U wikijs -c "SHOW server_encoding;" — должно быть UTF8).

8. Настройка бэкапов

1. В интерфейсе: Administration > Backup > Storage > Local File System.
2. Укажите путь: /wiki/backup.
3. Включите ежедневные бэкапы.

Для автоматического бэкапа базы (cron-скрипт):

• Создайте скрипт /opt/wikijs/backup.sh:

  #!/bin/bash
  docker exec wikijs-postgres pg_dump -U wikijs wikijs > /opt/wikijs/backup/wikijs-$(date +%Y%m%d).sql
  docker cp wikijs:/wiki/backup/* /opt/wikijs/backup/  # Бэкапы из интерфейса
  find /opt/wikijs/backup -type f -mtime +7 -delete  # Удалять старше 7 дней
  

• Сделайте исполняемым: chmod +x /opt/wikijs/backup.sh.
• Добавьте в cron (ежедневно в 02:00): crontab -e

  0 2 * * * /opt/wikijs/backup.sh
  

9. Обновление и обслуживание

• Обновите: cd /opt/wikijs && docker compose pull && docker compose up -d --force-recreate.
• Логи: docker compose logs -f wiki.
• Очистка: docker system prune -f (удаляет старые образы).

10. Устранение неисправностей

• EACCES permission denied: Проверьте права на volumes (chown 1000:1000, chmod 775). Если в логе mkdir '/home/user' — используйте HOME: /wiki/data в environment.
• JSON.parse error: Очистите кэш: docker exec -it wikijs bash -c "rm -rf /wiki/data/cache/*".
• Конфликты сохранения: Вторично от EACCES — исправьте права и перезапустите.
• Бэкапы не сохраняются: Убедитесь в пути /wiki/backup и правах на /opt/wikijs/backup.
• SELinux/AppArmor (если включено): sudo setenforce 0 (временно), затем настройте правила.
• Нет данных после перезапуска: Всегда копируйте перед down: docker cp wikijs:/wiki/data /opt/wikijs/data.

Эта настройка обеспечит стабильную работу Wiki.js для многоуровневой документации на русском языке.