Способ 1: Docker Compose (Рекомендуется)

version: '3.8'
services:
  neko-main:
    image: docker.gh-proxy.org/ghcr.io/project-n-e-k-o/n.e.k.o:latest
    container_name: neko
    restart: unless-stopped
    ports:
      - "48911:80"   # HTTP порт
      - "48912:443"  # HTTPS порт
    volumes:
      - ./N.E.K.O:/root/Documents/N.E.K.O
      - ./logs:/app/logs
      - ./ssl:/root/ssl
    networks:
      - neko-network
networks:
  neko-network:
    driver: bridge

docker-compose up -d

Способ 2: Docker Run

NEKO_BASE_PATH="/home/neko/neko-data" && \
docker network create --driver bridge neko-network 2>/dev/null || true
docker run -d \
  --name neko \
  --restart unless-stopped \
  -p 48911:80 \
  -p 48912:443 \
  -v "${NEKO_BASE_PATH}/N.E.K.O:/root/Documents/N.E.K.O" \
  -v "${NEKO_BASE_PATH}/logs:/app/logs" \
  -v "${NEKO_BASE_PATH}/ssl:/root/ssl" \
  --network neko-network \
  docker.gh-proxy.org/ghcr.io/project-n-e-k-o/n.e.k.o:latest

текущий_каталог/
├── N.E.K.O/      # Конфигурация и данные
├── logs/         # Логи приложения
├── ssl/          # SSL-сертификаты
└── docker-compose.yml

🔐 Настройка SSL-сертификата

mkdir -p ./ssl
cp your-cert.crt ./ssl/N.E.K.O.crt
cp your-cert.key ./ssl/N.E.K.O.key

docker-compose down
cp your-cert.crt ./ssl/N.E.K.O.crt
cp your-cert.key ./ssl/N.E.K.O.key
docker-compose up -d

docker exec neko openssl x509 -in /root/ssl/N.E.K.O.crt -noout -text

⚙️ Переменные окружения

environment:
  # API ключи
  - NEKO_CORE_API_KEY=${NEKO_CORE_API_KEY}
  - NEKO_ASSIST_API_KEY_QWEN=${NEKO_ASSIST_API_KEY_QWEN}
  - NEKO_ASSIST_API_KEY_OPENAI=${NEKO_ASSIST_API_KEY_OPENAI}
  - NEKO_ASSIST_API_KEY_GLM=${NEKO_ASSIST_API_KEY_GLM}
  - NEKO_ASSIST_API_KEY_STEP=${NEKO_ASSIST_API_KEY_STEP}
  - NEKO_ASSIST_API_KEY_SILICON=${NEKO_ASSIST_API_KEY_SILICON}
  - NEKO_MCP_TOKEN=${NEKO_MCP_TOKEN}

  # API провайдеры
  - NEKO_CORE_API=${NEKO_CORE_API:-qwen}
  - NEKO_ASSIST_API=${NEKO_ASSIST_API:-qwen}

  # Модели
  - NEKO_SUMMARY_MODEL=${NEKO_SUMMARY_MODEL:-qwen-plus}
  - NEKO_CORRECTION_MODEL=${NEKO_CORRECTION_MODEL:-qwen-max}
  - NEKO_EMOTION_MODEL=${NEKO_EMOTION_MODEL:-qwen-turbo}
  - NEKO_VISION_MODEL=${NEKO_VISION_MODEL:-qwen3-vl-plus-2025-09-23}

  # SSL
  - SSL_DOMAIN=${SSL_DOMAIN:-project-neko.online}
  - SSL_DAYS=${SSL_DAYS:-365000}
  - DISABLE_SSL=${DISABLE_SSL:-0}
  - AUTO_REGENERATE_CERT=${AUTO_REGENERATE_CERT:-1}
  - NGINX_AUTO_RELOAD=${NGINX_AUTO_RELOAD:-1}

cat > .env << EOF
NEKO_CORE_API_KEY=your_core_api_key_here
NEKO_ASSIST_API_KEY_QWEN=your_qwen_api_key
NEKO_MCP_TOKEN=your_mcp_token
SSL_DOMAIN=your-domain.com
EOF

docker-compose --env-file .env up -d

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

ss -tulpn | grep ':4891[12]'
# Решение: измените маппинг портов в docker-compose.yml

mkdir -p N.E.K.O logs ssl
chmod 755 N.E.K.O logs ssl

docker-compose logs --tail=100
docker logs neko --tail=100

rm -f ssl/N.E.K.O.crt ssl/N.E.K.O.key
docker-compose up -d

curl -v http://localhost:48911/health
curl -v -k https://localhost:48912/health

docker ps | grep neko
docker logs neko
docker exec -it neko bash

docker system prune -f
docker-compose down && docker volume prune -f

# Попробуйте альтернативный источник в docker-compose.yml:
# image: ghcr.io/project-n-e-k-o/n.e.k.o:latest

📊 Мониторинг системы

curl http://localhost:48911/health
curl -k https://localhost:48912/health

docker stats neko
docker top neko
docker inspect neko

docker-compose logs -f
docker-compose logs --tail=100
docker-compose logs | grep -i error

tar -czf neko-backup-$(date +%Y%m%d).tar.gz \
  N.E.K.O/ \
  ssl/ \
  docker-compose.yml

docker-compose pull
docker-compose up -d

🌐 Адреса доступа

После запуска контейнера:

• HTTP: http://IP-вашего-сервера:48911
• HTTPS: https://IP-вашего-сервера:48912

⏱️ Краткая справка

Полная документация для разработчиков на project-neko.online

Требования: Python 3.11 (другие версии не поддерживаются), пакетный менеджер uv, Node.js (>=20.19)

# 1. Клонировать проект
git clone https://github.com/Project-N-E-K-O/N.E.K.O.git
cd N.E.K.O

# 2. Установить Python-зависимости
uv sync

# 3. Собрать фронтенд-проекты (требуется Node.js >= 20.19; необходимо при первом запуске или после изменений фронтенда)
#    Рекомендуется: используйте скрипт (это официально поддерживаемый способ сборки)
#      Windows:      build_frontend.bat
#      Linux/macOS:  ./build_frontend.sh
#    Ручная сборка (должна совпадать с тем, что делает скрипт):
# cd frontend/react-neko-chat && npm install && npm run build && cd ../..
# cd frontend/plugin-manager && npm install && npm run build-only && cd ../..

# 4. Запустить сервисы (минимум main_server и memory_server)
uv run python memory_server.py
uv run python main_server.py
# Опционально: запуск Agent-сервиса
uv run python agent_server.py

# 5. Перейдите на http://localhost:48911 для настройки API Key и начала работы

Разработчикам рекомендуется присоединиться к QQ-группе 995414391.

Настройка API Key

Настройте сторонние ИИ-сервисы для дополнительных функций:

• Core API (голосовой разговор в реальном времени): Должен поддерживать Realtime API. Рекомендуется: Alibaba Cloud.
• Assist API (память/эмоции/зрение): Поддерживает стандартный интерфейс ChatCompletion. Доступно 14+ провайдеров.

Перейдите на http://localhost:48911/api_key для настройки через веб-интерфейс.

Получение Alibaba Cloud API: Зарегистрируйтесь на платформе Bailian от Alibaba Cloud официальный сайт. Новые пользователи получают значительные бесплатные кредиты после верификации. После регистрации перейдите в консоль для получения API Key.

Изменение персоны персонажа

• Перейдите на http://localhost:48911/character_card_manager для входа на страницу редактирования персонажа. Имя по умолчанию — XiaoTian; рекомендуется изменить имя и поочерёдно добавлять или изменять базовые настройки персоны.

• Расширенные настройки включают параметры модели Live2D/VRM/MMD и настройки голоса. Для смены модели аватара сначала скопируйте каталог модели в папку static. В расширенных настройках войдите в интерфейс управления моделями для переключения и настройки положения/размера. Для смены голоса персонажа подготовьте чистую непрерывную запись длительностью ~5 секунд. Войдите на страницу клонирования голоса и загрузите запись.

• Поддерживается экспорт карточки персонажа — в формате «только определение» или «полная карточка» для обмена и резервного копирования.

• В расширенных настройках также есть system_prompt для полной кастомизации системных инструкций, но модификация не рекомендуется.

Изменение API-провайдера

• Перейдите на http://localhost:48911/api_key для переключения провайдеров Core API и Assist API.

Обзор памяти

• Перейдите на http://localhost:48911/memory_browser для просмотра и проверки недавних воспоминаний и саммари, что может помочь с проблемами повторений и когнитивных ошибок модели.

Архитектура проекта

N.E.K.O/
├── 📁 .agent/                   # 🤖 Правила и навыки для ИИ-ассистентов (конвенция Google Antigravity)
├── 📁 brain/                    # 🧠 Модули агента
│   ├── computer_use.py          # Управление компьютером
│   ├── browser_use_adapter.py   # Автоматизация браузера
│   ├── openclaw_adapter.py      # Облачное подключение OpenClaw
│   ├── openfang_adapter.py      # Безголовый бэкенд OpenFang
│   ├── task_executor.py         # Движок выполнения задач
│   └── 📁 cua/                  # Подсистема Computer Use Agent
├── 📁 config/                   # ⚙️ Управление конфигурацией
│   ├── api_providers.json       # Конфигурация API-провайдеров
│   └── 📁 prompts/              # Промпты персонажей, системы и функций
│       ├── prompts_chara.py     # Промпты персонажей
│       └── prompts_sys.py       # Системные промпты
├── 📁 main_logic/               # 🔧 Основные модули
│   ├── core.py                  # Основной модуль диалога
│   ├── cross_server.py          # Межсерверная коммуникация
│   ├── omni_realtime_client.py  # Клиент Realtime API
│   ├── omni_offline_client.py   # Текстовый API клиент (ChatCompletion)
│   └── tts_client.py            # 🔊 Адаптер TTS-движка
├── 📁 main_routers/             # 🌐 API-маршруты (14 маршрутов)
├── 📁 memory/                   # 🧠 Пятимерная система памяти (частичные примеры)
│   ├── facts/                   # Память фактов
│   ├── reflection/              # Память рефлексий
│   └── persona/                 # Память персоны
├── 📁 frontend/                 # 🖥️ Современные фронтенд-проекты
│   ├── react-neko-chat/         # React компонент чата
│   └── plugin-manager/          # Vue панель управления плагинами
├── 📁 plugin/                   # 🔌 Система плагинов
│   ├── sdk/                     # SDK плагинов
│   └── server/                  # Сервер плагинов
├── 📁 static/                   # 🌐 Статические ресурсы фронтенда (вкл. артефакты сборки)
├── 📁 templates/                # 📄 HTML-шаблоны фронтенда (14 страниц)
├── 📁 utils/                    # 🛠️ Утилиты
├── main_server.py               # 🌐 Основной сервер
├── agent_server.py              # 🤖 Сервер ИИ-агента
└── memory_server.py             # 🧠 Сервер памяти

Разработка с помощью ИИ: Каталог .agent/ следует открытой конвенции Google Antigravity и содержит правила разработки и наборы навыков проекта. Только Antigravity загружает автоматически; все остальные ИИ-инструменты (включая Claude Code) требуют ручного импорта. См. руководство по адаптации.

Поток данных

Полная документация для разработчиков на project-neko.online

Дорожная карта

v0.7: ✅ Функции, связанные с агентом. Завершено.

v0.8: Функции памяти, функциональность типа OpenClaw. Ожидается: Март 2026.

v0.9: Поддержка мультисистемности (Linux, мобильные). Запуск сети N.E.K.O. Ожидается: Апрель 2026.

v1.0: Фокус на собственных больших моделях и агентных системах. Ожидается: Июнь 2026.

Телеметрия (Telemetry)

N.E.K.O. по умолчанию включает анонимную телеметрию использования LLM-токенов — она нужна, чтобы отслеживать совместимость версий, распределение использования моделей и частоту ошибок. Мы признаём, что данные нужны для улучшения продукта, но ещё сильнее убеждены: ничего не должно собираться втайне от пользователя.

Отключить одной строкой (opt-out): задайте переменную окружения DO_NOT_TRACK=1 (или NEKO_DO_NOT_TRACK=1). Телеметрия отключается мгновенно, пересборка не нужна. Мы следуем общепринятой open-source-конвенции Console Do Not Track.

Что собираем / не собираем:

О псевдонимизированном идентификаторе устройства: односторонний SHA-256, необратим, не содержит пользовательских данных. Одна и та же машина (одна и та же установка ОС) даёт тот же идентификатор, поэтому в классификации GDPR / PIPL это псевдонимизированный идентификатор, а не полностью анонимные данные. Используется только для подсчёта DAU с дедупликацией и атрибуции по версиям.

О Steam64: это публичный числовой ID, который Steam-клиент после входа выдаёт любому стороннему SDK (число в конце URL вашего профиля Steam — это он). Он не содержит email, телефона или настоящего имени, но стабилен между сессиями. Фактическое условие срабатывания определяется кодом, а не меткой канала дистрибуции: app/main_server.py безусловно вызывает initialize_steamworks() при запуске, а _get_telemetry_steam_user_id() в utils/token_tracker.py отправляет любой ненулевой Steam ID, не разделяя каналы source / release / steam. Типичный сценарий — Steam-сборка, но source-чекаут с установленным Python-пакетом steamworks, сохранённым steam_appid.txt и активной сессией Steam также будет отправлять Steam64. Чтобы он не отправлялся: (1) самый надёжный способ — DO_NOT_TRACK=1 для полного отключения; (2) выйти из Steam-клиента; (3) source-пользователи могут удалить пакет steamworks или убрать steam_appid.txt из рабочего каталога.

Полная реализация и протокол передачи — в utils/token_tracker.py и local_server/telemetry_server/README.md: подпись HMAC-SHA256, окно защиты от повторов ±5 мин, ограничение по скользящему окну (120 req/h/device), хранилище только на запись. Каждый серверный процесс отправляет данные не чаще раза в ~60 секунд (использует тот же таймер троттлинга, что и локальная запись на диск) — на основной поток это не влияет.