Обновить README.md
This commit is contained in:
@@ -0,0 +1,292 @@
|
||||
# 🖥️ TrueNAS SCALE AI Workspace
|
||||
|
||||
> **code-server + OmniRoute + Claude Code** — полноценное AI-окружение разработчика прямо в браузере, развёрнутое на домашнем сервере TrueNAS SCALE.
|
||||
|
||||
---
|
||||
|
||||
## 📋 Содержание
|
||||
|
||||
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-устранение-неполадок)
|
||||
|
||||
---
|
||||
|
||||
## О проекте
|
||||
|
||||
Этот проект предоставляет готовую конфигурацию для развёртывания AI-окружения на **TrueNAS SCALE 24.x (Electric Eel) и новее**.
|
||||
|
||||
**Что получите в итоге:**
|
||||
- 🌐 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
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. Развёртывание (Custom App / Docker Compose)
|
||||
|
||||
Используйте этот 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/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 # Доступ к конфигам других приложений
|
||||
ports:
|
||||
- 18443:8443
|
||||
restart: unless-stopped
|
||||
|
||||
omniroute:
|
||||
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:
|
||||
- 20128:20128
|
||||
restart: unless-stopped
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. Установка 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** примените настройки:
|
||||
|
||||
```bash
|
||||
source /config/.bashrc
|
||||
claude # запуск агента
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. Настройка OmniRoute + Kiro AI
|
||||
|
||||
1. Откройте **OmniRoute Dashboard**: `http://<IP_ВАШЕГО_СЕРВЕРА>: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 видит несколько провайдеров для одной модели и не знает, какой выбрать.
|
||||
|
||||
### Решение A — Быстрое (разово, через флаг)
|
||||
|
||||
```bash
|
||||
claude --model kr/claude-sonnet-4-6
|
||||
# или
|
||||
claude --model kiro/claude-sonnet-4-6
|
||||
# (используйте тот префикс, который вы задали провайдеру в Dashboard)
|
||||
```
|
||||
|
||||
### Решение B — Постоянное (через Dashboard OmniRoute)
|
||||
|
||||
1. `http://<IP>:20128` → Providers → Kiro AI
|
||||
2. Раздел **Model Mapping** → добавить правило (см. таблицу выше)
|
||||
3. Установить Kiro как **Default** для Claude-моделей
|
||||
|
||||
### Решение C — Через алиас в `.bashrc`
|
||||
|
||||
```bash
|
||||
echo "alias claude='claude --model kr/claude-sonnet-4.5'" >> /config/.bashrc
|
||||
source /config/.bashrc
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. Удобные алиасы
|
||||
|
||||
Добавьте в терминале VS Code:
|
||||
|
||||
```bash
|
||||
cat >> /config/.bashrc << 'EOF'
|
||||
|
||||
# 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://<IP>: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!
|
||||
Reference in New Issue
Block a user