diff --git a/README.md b/README.md index 829810b..dc99390 100644 --- a/README.md +++ b/README.md @@ -1,53 +1,104 @@ -# 🚀 TrueNAS SCALE AI Workspace +# 🖥️ TrueNAS SCALE AI Workspace -### code-server + OmniRoute + Claude Code (Kiro AI) +> **code-server + OmniRoute + Claude Code** — полноценное AI-окружение разработчика прямо в браузере, развёрнутое на домашнем сервере TrueNAS SCALE. -![TrueNAS](https://img.shields.io/badge/TrueNAS-SCALE-blue?logo=truenas) -![Docker](https://img.shields.io/badge/Docker-Ready-blue?logo=docker) -![VSCode](https://img.shields.io/badge/code--server-VSCode-green?logo=visualstudiocode) -![Claude](https://img.shields.io/badge/Claude-Code-purple) -![License](https://img.shields.io/badge/license-MIT-green) +--- ------------------------------------------------------------------------- +## 📋 Содержание -## 📦 Стек +1. [О проекте](#о-проекте) +2. [Архитектура стека](#архитектура-стека) +3. [Требования](#требования) +4. [Подготовка системы](#1-подготовка-системы-shell-truenas) +5. [Развёртывание контейнеров](#2-развёртывание-custom-app--docker-compose) +6. [Установка Claude Code](#3-установка-claude-code) +7. [Настройка OmniRoute + Kiro AI](#4-настройка-omniroute--kiro-ai) +8. [Решение проблемы Ambiguous model](#5-решение-проблемы-ambiguous-model) +9. [Удобные алиасы](#6-удобные-алиасы) +10. [Полезные команды Claude Code](#7-полезные-команды-claude-code) +11. [Устранение неполадок](#8-устранение-неполадок) -- **code-server** --- VS Code в браузере\ -- **OmniRoute** --- прокси для AI\ -- **Claude Code** --- CLI агент\ -- **Kiro AI** --- провайдер моделей +--- ------------------------------------------------------------------------- +## О проекте -## 🛠 Подготовка +Этот проект предоставляет готовую конфигурацию для развёртывания AI-окружения на **TrueNAS SCALE 24.x (Electric Eel) и новее**. -``` bash +**Что получите в итоге:** +- 🌐 VS Code в браузере (code-server) на порту `18443` +- 🔀 Единый API-шлюз OmniRoute для управления ключами на порту `20128` +- 🤖 Claude Code CLI, работающий через локальный прокси (без прямых трат на Anthropic API) +- 💾 Доступ к файлам всех приложений прямо из редактора + +--- + +## Архитектура стека + +``` +Браузер + │ + ▼ +code-server (VS Code) :18443 + │ терминал + ▼ +Claude Code CLI + │ ANTHROPIC_BASE_URL + ▼ +OmniRoute (локальный шлюз) :20128 + │ model mapping + ▼ +Kiro AI / Anthropic API +``` + +--- + +## Требования + +| Компонент | Версия | +|-----------|--------| +| TrueNAS SCALE | Electric Eel 24.x+ | +| Docker (встроенный) | любая | +| Пул хранилища | `/mnt/ssd` (замените на свой) | +| UID пользователя apps | `568` | + +--- + +## 1. Подготовка системы (Shell TrueNAS) + +> ⚠️ **Критично:** Выполняйте из Shell TrueNAS, а не из контейнера. Права `568:568` обязательны — без них контейнеры не смогут писать в тома. + +```bash +# Создание директорий на пуле хранилища mkdir -p /mnt/ssd/apps/vscode/config \ /mnt/ssd/apps/vscode/workspace \ /mnt/ssd/apps/omniroute +# Настройка прав доступа (рекурсивно) chown -R 568:568 /mnt/ssd/apps chmod -R 775 /mnt/ssd/apps ``` ------------------------------------------------------------------------- +--- -## 🐳 Docker Compose +## 2. Развёртывание (Custom App / Docker Compose) -``` yaml +Используйте этот YAML при создании **Custom App** в интерфейсе TrueNAS SCALE: + +```yaml services: + code-server: image: lscr.io/linuxserver/code-server:latest container_name: code-server environment: - PUID=568 - PGID=568 - - TZ=Europe/Prague - - PASSWORD=your_password + - TZ=Europe/Moscow + - PASSWORD=your_password_here # Пароль для входа в VS Code volumes: - /mnt/ssd/apps/vscode/config:/config - /mnt/ssd/apps/vscode/workspace:/config/workspace - - /mnt/ssd/apps:/mnt/ssd/apps + - /mnt/ssd/apps:/mnt/ssd/apps # Доступ к конфигам других приложений ports: - 18443:8443 restart: unless-stopped @@ -56,7 +107,11 @@ services: image: diegosouzapw/omniroute:latest container_name: omniroute environment: + - PUID=568 + - PGID=568 - PORT=20128 + - GEMINI_OAUTH_CLIENT_SECRET=not_used # Заглушка (если не используете Gemini) + - GEMINI_OAUTH_CLIENT_ID=not_used volumes: - /mnt/ssd/apps/omniroute:/app/data ports: @@ -64,69 +119,174 @@ services: restart: unless-stopped ``` ------------------------------------------------------------------------- +--- -## 🤖 Установка Claude Code +## 3. Установка Claude Code -``` bash -docker exec -u 0 -it code-server bash -c " -apt update && -apt install -y nodejs npm && -npm install -g @anthropic-ai/claude-code -" +> 💡 Используем `docker exec -u 0` для установки от root — это надёжнее, чем sudo внутри контейнера. + +Выполните из **Shell TrueNAS** (не из терминала VS Code): + +```bash +# Установка Node.js и Claude Code +docker exec -u 0 -it code-server bash -c \ + "apt update && apt install -y nodejs npm && npm install -g @anthropic-ai/claude-code" + +# Настройка PATH и прокси OmniRoute +docker exec -u 0 -it code-server bash -c \ + "echo 'export PATH=\$PATH:/usr/local/bin' >> /config/.bashrc" + +docker exec -u 0 -it code-server bash -c \ + "echo 'export ANTHROPIC_BASE_URL=\"http://192.168.31.100:20128/v1\"' >> /config/.bashrc" + +# Создание системной ссылки (чтобы claude был доступен для всех пользователей) +docker exec -u 0 -it code-server \ + ln -s /usr/local/bin/claude /usr/bin/claude ``` ------------------------------------------------------------------------- +Затем в **терминале VS Code** примените настройки: -## ⚙️ OmniRoute - -Открыть: http://``{=html}:20128 - -**Model Mapping:** - `claude-sonnet-4-6` → `claude-sonnet-4.5` - `*` → -`claude-sonnet-4.5` - ------------------------------------------------------------------------- - -## ▶️ Запуск - -``` bash -claude --model kr/claude-sonnet-4.5 +```bash +source /config/.bashrc +claude # запуск агента ``` ------------------------------------------------------------------------- +--- -## ⚡ Алиасы +## 4. Настройка OmniRoute + Kiro AI -``` bash -alias c4s='claude --model kr/claude-sonnet-4.5' -alias c4h='claude --model kr/claude-haiku-4.5' +1. Откройте **OmniRoute Dashboard**: `http://:20128` +2. Перейдите в раздел **Providers** → добавьте провайдера **Kiro AI** (тип: Custom OpenAI) +3. Укажите Base URL и API-ключ из вашего кабинета Kiro +4. В настройках провайдера добавьте **Model Mapping**: + + | Inbound (что запрашивает Claude) | Outbound (имя в Kiro) | + |-----------------------------------|-----------------------| + | `claude-sonnet-4-6` | `claude-sonnet-4.5` | + | `claude-haiku-4-5` | `claude-haiku-4.5` | + +5. Установите Kiro как **провайдера по умолчанию** для семейства Claude + +--- + +## 5. Решение проблемы "Ambiguous model" + +### Симптом + +``` +API Error: 400 {"error":{"message":"Ambiguous model 'claude-sonnet-4-6'. +Use provider/model prefix (ex: cc/claude-sonnet-4-6 or antigravity/claude-sonnet-4-6)."}} ``` ------------------------------------------------------------------------- +### Причина -## 📂 Доступ к файлам +OmniRoute видит несколько провайдеров для одной модели и не знает, какой выбрать. -Открыть в VS Code: +### Решение A — Быстрое (разово, через флаг) - /mnt/ssd/apps +```bash +claude --model kr/claude-sonnet-4-6 +# или +claude --model kiro/claude-sonnet-4-6 +# (используйте тот префикс, который вы задали провайдеру в Dashboard) +``` ------------------------------------------------------------------------- +### Решение B — Постоянное (через Dashboard OmniRoute) -## 🧠 Возможности +1. `http://:20128` → Providers → Kiro AI +2. Раздел **Model Mapping** → добавить правило (см. таблицу выше) +3. Установить Kiro как **Default** для Claude-моделей -- AI прямо в браузере\ -- централизованный API через OmniRoute\ -- быстрые и дешёвые модели (Haiku)\ -- доступ ко всем конфигам +### Решение C — Через алиас в `.bashrc` ------------------------------------------------------------------------- +```bash +echo "alias claude='claude --model kr/claude-sonnet-4.5'" >> /config/.bashrc +source /config/.bashrc +``` -## 🧩 Архитектура +--- - Browser → code-server → Claude Code → OmniRoute → Kiro AI +## 6. Удобные алиасы ------------------------------------------------------------------------- +Добавьте в терминале VS Code: -## 📜 License +```bash +cat >> /config/.bashrc << 'EOF' -MIT +# Claude Code — быстрое переключение моделей +alias c4s='claude --model kr/claude-sonnet-4.5' # Мощная модель (Sonnet) +alias c4h='claude --model kr/claude-haiku-4.5' # Быстрая модель (Haiku) +alias c='claude --model kr/claude-sonnet-4.5' # Краткий алиас +EOF + +source /config/.bashrc +``` + +**Использование:** +```bash +c4s # запустить Claude Sonnet (сложные задачи) +c4h # запустить Claude Haiku (быстрые вопросы) +``` + +--- + +## 7. Полезные команды Claude Code + +| Команда | Описание | +|---------|----------| +| `/init` | Индексация текущего проекта | +| `/terminal-setup` | Оптимизация горячих клавиш терминала | +| `/help` | Список всех команд | +| `Shift+Enter` | Перенос строки в промпте | +| `Esc` | Прерывание выполнения | +| `exit` | Выход из агента | + +--- + +## 8. Устранение неполадок + +### Claude не находит API + +```bash +# Проверьте переменную окружения +echo $ANTHROPIC_BASE_URL +# Должно быть: http://192.168.31.100:20128/v1 + +# Если пусто — примените профиль +source /config/.bashrc +``` + +### Проверка логов OmniRoute + +```bash +# Из Shell TrueNAS +docker logs omniroute -f --tail=50 +``` + +Или через Dashboard: `http://:20128` → вкладка **Logs**. + +### Права доступа к файлам + +```bash +# Из Shell TrueNAS — сброс прав если что-то пошло не так +chown -R 568:568 /mnt/ssd/apps +chmod -R 775 /mnt/ssd/apps +``` + +### Переустановка Claude Code + +```bash +docker exec -u 0 -it code-server bash -c \ + "npm uninstall -g @anthropic-ai/claude-code && npm install -g @anthropic-ai/claude-code" +``` + +--- + +## Авторы + +Проект подготовлен **Анатолием** на основе реального опыта развёртывания. +Публикуется для сообщества разработчиков на TrueNAS SCALE. + +--- + +> 💬 Нашли ошибку или есть улучшение? Открывайте Issue или Pull Request!