mirror of
https://github.com/Direct-Dev-Ru/go-lcg.git
synced 2025-11-16 01:29:55 +00:00
Исправления в ветке auth-feature
This commit is contained in:
187
docs/API_CONTRACT.md
Normal file
187
docs/API_CONTRACT.md
Normal file
@@ -0,0 +1,187 @@
|
||||
# Контракт API для провайдеров (proxy и ollama)
|
||||
|
||||
Этот документ описывает минимально необходимый API, который должен предоставлять сервер-провайдер (режимы: "proxy" и "ollama"), чтобы CLI-приложение работало корректно.
|
||||
|
||||
## Общие требования
|
||||
|
||||
- **Базовый URL** берётся из `config.AppConfig.Host`. Трейлинг-слэш на стороне клиента обрезается.
|
||||
- **Таймаут** HTTP-запросов задаётся в секундах через конфигурацию (см. `config.AppConfig.Timeout`).
|
||||
- **Кодирование**: все тела запросов и ответов — `application/json; charset=utf-8`.
|
||||
- **Стриминг**: на данный момент клиент всегда запрашивает `stream=false`; стриминг не используется.
|
||||
|
||||
---
|
||||
|
||||
## Режим proxy
|
||||
|
||||
### Аутентификация
|
||||
|
||||
- Все защищённые эндпоинты требуют заголовок: `Authorization: Bearer <JWT>`.
|
||||
- Токен берётся из `config.AppConfig.JwtToken`, либо из файла `~/.proxy_jwt_token`.
|
||||
|
||||
### 1) POST `/api/v1/protected/sberchat/chat`
|
||||
|
||||
- **Назначение**: получить единственный текстовый ответ LLM.
|
||||
- **Заголовки**:
|
||||
- `Content-Type: application/json`
|
||||
- `Authorization: Bearer <JWT>` (обязательно)
|
||||
- **Тело запроса** (минимально необходимые поля):
|
||||
|
||||
```json
|
||||
{
|
||||
"messages": [
|
||||
{ "role": "system", "content": "<system_prompt>" },
|
||||
{ "role": "user", "content": "<ask>" }
|
||||
],
|
||||
"model": "<model_name>",
|
||||
"temperature": 0.5,
|
||||
"top_p": 0.5,
|
||||
"stream": false,
|
||||
"random_words": ["linux", "command", "gpt"],
|
||||
"fallback_string": "I'm sorry, I can't help with that. Please try again."
|
||||
}
|
||||
```
|
||||
|
||||
- **Ответ 200 OK**:
|
||||
|
||||
```json
|
||||
{
|
||||
"response": "<string>",
|
||||
"usage": {
|
||||
"prompt_tokens": 0,
|
||||
"completion_tokens": 0,
|
||||
"total_tokens": 0
|
||||
},
|
||||
"error": "",
|
||||
"model": "<model_name>",
|
||||
"timeout_seconds": 0
|
||||
}
|
||||
```
|
||||
|
||||
- **Ошибки**: любой статус != 200 воспринимается как ошибка. Желательно вернуть JSON вида:
|
||||
|
||||
```json
|
||||
{ "error": "<message>" }
|
||||
```
|
||||
|
||||
- **Пример cURL**:
|
||||
|
||||
```bash
|
||||
curl -sS -X POST \
|
||||
-H "Authorization: Bearer $JWT" \
|
||||
-H "Content-Type: application/json" \
|
||||
"$HOST/api/v1/protected/sberchat/chat" \
|
||||
-d '{
|
||||
"messages": [
|
||||
{"role":"system","content":"system prompt"},
|
||||
{"role":"user","content":"user ask"}
|
||||
],
|
||||
"model":"GigaChat-2-Max",
|
||||
"temperature":0.5,
|
||||
"top_p":0.5,
|
||||
"stream":false,
|
||||
"random_words":["linux","command","gpt"],
|
||||
"fallback_string":"I'm sorry, I can't help with that. Please try again."
|
||||
}'
|
||||
```
|
||||
|
||||
### 2) GET `/api/v1/protected/sberchat/health`
|
||||
|
||||
- **Назначение**: health-check API и получение части метаданных по умолчанию.
|
||||
- **Заголовки**:
|
||||
- `Authorization: Bearer <JWT>` (если сервер требует авторизацию на health)
|
||||
- **Ответ 200 OK**:
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "ok",
|
||||
"message": "<string>",
|
||||
"default_model": "<string>",
|
||||
"default_timeout_seconds": 120
|
||||
}
|
||||
```
|
||||
|
||||
- **Ошибки**: любой статус != 200 считается падением health.
|
||||
|
||||
### Модели
|
||||
|
||||
- В текущей реализации клиент не запрашивает список моделей у proxy и использует фиксированный набор.
|
||||
- Опционально можно реализовать эндпоинт для списка моделей (например, `GET /api/v1/protected/sberchat/models`) и расширить клиента позже.
|
||||
|
||||
---
|
||||
|
||||
## Режим ollama
|
||||
|
||||
### 1) POST `/api/chat`
|
||||
|
||||
- **Назначение**: синхронная генерация одного ответа (без стрима).
|
||||
- **Заголовки**:
|
||||
- `Content-Type: application/json`
|
||||
- **Тело запроса**:
|
||||
|
||||
```json
|
||||
{
|
||||
"model": "<model_name>",
|
||||
"stream": false,
|
||||
"messages": [
|
||||
{ "role": "system", "content": "<system_prompt>" },
|
||||
{ "role": "user", "content": "<ask>" }
|
||||
],
|
||||
"options": {"temperature": 0.2}
|
||||
}
|
||||
```
|
||||
|
||||
- **Ответ 200 OK** (минимальный, который поддерживает клиент):
|
||||
|
||||
```json
|
||||
{
|
||||
"model": "<model_name>",
|
||||
"message": { "role": "assistant", "content": "<string>" },
|
||||
"done": true
|
||||
}
|
||||
```
|
||||
|
||||
- Прочие поля ответа (`total_duration`, `eval_count` и т.д.) допускаются, но клиент использует только `message.content`.
|
||||
|
||||
- **Ошибки**: любой статус != 200 считается ошибкой. Желательно возвращать читаемое тело.
|
||||
|
||||
### 2) GET `/api/tags`
|
||||
|
||||
- **Назначение**: используется как health-check и для получения списка моделей.
|
||||
- **Ответ 200 OK**:
|
||||
|
||||
```json
|
||||
{
|
||||
"models": [
|
||||
{ "name": "llama3:8b", "modified_at": "2024-01-01T00:00:00Z", "size": 123456789 },
|
||||
{ "name": "qwen2.5:7b", "modified_at": "2024-01-02T00:00:00Z", "size": 987654321 }
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
- Любой другой статус трактуется как ошибка health.
|
||||
|
||||
---
|
||||
|
||||
## Семантика сообщений
|
||||
|
||||
- `messages` — массив объектов `{ "role": "system"|"user"|"assistant", "content": "<string>" }`.
|
||||
- Клиент всегда отправляет как минимум 2 сообщения: системное и пользовательское.
|
||||
- Ответ должен содержать один финальный текст в виде `response` (proxy) или `message.content` (ollama).
|
||||
|
||||
## Поведение при таймаутах
|
||||
|
||||
- Сервер должен завершать запрос в пределах `config.AppConfig.Timeout` секунд (значение передаётся клиентом в настройки HTTP-клиента; отдельным полем в запросе оно не отправляется, исключение — `proxy` может возвращать `timeout_seconds` в ответе как справочную информацию).
|
||||
|
||||
## Коды ответов и ошибки
|
||||
|
||||
- 200 — успешный ответ с телом согласно контракту.
|
||||
- !=200 — ошибка; тело желательно в JSON с полем `error`.
|
||||
|
||||
## Изменения контракта
|
||||
|
||||
- Добавление новых полей в ответах, не используемых клиентом, допустимо при сохранении существующих.
|
||||
- Переименование или удаление полей `response` (proxy) и `message.content` (ollama) нарушит совместимость.
|
||||
|
||||
---
|
||||
|
||||
Дополнительно: для HTTP API веб‑сервера (эндпоинт `POST /execute`, только `curl`) см. `API_GUIDE.md` с примерами и подробной схемой запроса/ответа.
|
||||
259
docs/API_GUIDE.md
Normal file
259
docs/API_GUIDE.md
Normal file
@@ -0,0 +1,259 @@
|
||||
# API Guide - Linux Command GPT
|
||||
|
||||
## Обзор
|
||||
|
||||
API позволяет выполнять запросы к Linux Command GPT через HTTP POST запросы с помощью curl. API принимает только запросы от curl (проверка User-Agent).
|
||||
|
||||
## Endpoint
|
||||
|
||||
``` curl
|
||||
POST /execute
|
||||
```
|
||||
|
||||
## Запуск сервера
|
||||
|
||||
```bash
|
||||
# Запуск сервера
|
||||
lcg serve
|
||||
|
||||
# Запуск на другом порту
|
||||
lcg serve --port 9000
|
||||
|
||||
# Запуск с автоматическим открытием браузера
|
||||
lcg serve --browser
|
||||
```
|
||||
|
||||
## Структура запроса
|
||||
|
||||
### JSON Payload
|
||||
|
||||
```json
|
||||
{
|
||||
"prompt": "создать директорию test",
|
||||
"system_id": 1,
|
||||
"system": "альтернативный системный промпт",
|
||||
"verbose": "vv",
|
||||
"timeout": 120
|
||||
}
|
||||
```
|
||||
|
||||
### Поля запроса
|
||||
|
||||
| Поле | Тип | Обязательное | Описание |
|
||||
|------|-----|--------------|----------|
|
||||
| `prompt` | string | ✅ | Пользовательский запрос |
|
||||
| `system_id` | int | ❌ | ID системного промпта (1-5) |
|
||||
| `system` | string | ❌ | Текст системного промпта (альтернатива system_id) |
|
||||
| `verbose` | string | ❌ | Степень подробности: "v", "vv", "vvv" |
|
||||
| `timeout` | int | ❌ | Таймаут в секундах (по умолчанию: 120) |
|
||||
|
||||
### Структура ответа
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"command": "mkdir test",
|
||||
"explanation": "Команда mkdir создает новую директорию...",
|
||||
"model": "hf.co/yandex/YandexGPT-5-Lite-8B-instruct-GGUF:Q4_K_M",
|
||||
"elapsed": 2.34
|
||||
}
|
||||
```
|
||||
|
||||
## Примеры использования
|
||||
|
||||
### 1. Базовый запрос
|
||||
|
||||
```bash
|
||||
curl -X POST http://localhost:8080/execute \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"prompt": "создать директорию test"
|
||||
}'
|
||||
```
|
||||
|
||||
**Ответ:**
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"command": "mkdir test",
|
||||
"model": "hf.co/yandex/YandexGPT-5-Lite-8B-instruct-GGUF:Q4_K_M",
|
||||
"elapsed": 1.23
|
||||
}
|
||||
```
|
||||
|
||||
### 2. Запрос с системным промптом по ID
|
||||
|
||||
```bash
|
||||
curl -X POST http://localhost:8080/execute \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"prompt": "найти все файлы .txt",
|
||||
"system_id": 2
|
||||
}'
|
||||
```
|
||||
|
||||
### 3. Запрос с кастомным системным промптом
|
||||
|
||||
```bash
|
||||
curl -X POST http://localhost:8080/execute \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"prompt": "показать использование памяти",
|
||||
"system": "Ты эксперт по Linux. Отвечай только командами без объяснений."
|
||||
}'
|
||||
```
|
||||
|
||||
### 4. Запрос с подробным объяснением
|
||||
|
||||
```bash
|
||||
curl -X POST http://localhost:8080/execute \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"prompt": "архивировать папку documents",
|
||||
"verbose": "vv",
|
||||
"timeout": 180
|
||||
}'
|
||||
```
|
||||
|
||||
**Ответ:**
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"command": "tar -czf documents.tar.gz documents/",
|
||||
"explanation": "Команда tar создает архив в формате gzip...",
|
||||
"model": "hf.co/yandex/YandexGPT-5-Lite-8B-instruct-GGUF:Q4_K_M",
|
||||
"elapsed": 3.45
|
||||
}
|
||||
```
|
||||
|
||||
### 5. Запрос с максимальной подробностью
|
||||
|
||||
```bash
|
||||
curl -X POST http://localhost:8080/execute \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"prompt": "настроить SSH сервер",
|
||||
"system_id": 3,
|
||||
"verbose": "vvv",
|
||||
"timeout": 300
|
||||
}'
|
||||
```
|
||||
|
||||
## Системные промпты
|
||||
|
||||
| ID | Название | Описание |
|
||||
|----|----------|----------|
|
||||
| 1 | basic | Базовые команды Linux |
|
||||
| 2 | advanced | Продвинутые команды |
|
||||
| 3 | system | Системное администрирование |
|
||||
| 4 | network | Сетевые команды |
|
||||
| 5 | security | Безопасность |
|
||||
|
||||
## Степени подробности
|
||||
|
||||
| Уровень | Описание |
|
||||
|---------|----------|
|
||||
| `v` | Краткое объяснение |
|
||||
| `vv` | Подробное объяснение с альтернативами |
|
||||
| `vvv` | Максимально подробное объяснение с примерами |
|
||||
|
||||
## Обработка ошибок
|
||||
|
||||
### Ошибка валидации
|
||||
|
||||
```json
|
||||
{
|
||||
"success": false,
|
||||
"error": "Prompt is required"
|
||||
}
|
||||
```
|
||||
|
||||
### Ошибка AI
|
||||
|
||||
```json
|
||||
{
|
||||
"success": false,
|
||||
"error": "Failed to get response from AI"
|
||||
}
|
||||
```
|
||||
|
||||
### Ошибка доступа
|
||||
|
||||
``` text
|
||||
HTTP 403 Forbidden
|
||||
Only curl requests are allowed
|
||||
```
|
||||
|
||||
## Переменные окружения
|
||||
|
||||
Убедитесь, что настроены необходимые переменные:
|
||||
|
||||
```bash
|
||||
# Основные настройки
|
||||
export LCG_PROVIDER="ollama"
|
||||
export LCG_HOST="http://localhost:11434"
|
||||
export LCG_MODEL="hf.co/yandex/YandexGPT-5-Lite-8B-instruct-GGUF:Q4_K_M"
|
||||
|
||||
# Для proxy провайдера
|
||||
export LCG_PROVIDER="proxy"
|
||||
export LCG_HOST="https://your-proxy-server.com"
|
||||
export LCG_JWT_TOKEN="your-jwt-token"
|
||||
```
|
||||
|
||||
## Безопасность
|
||||
|
||||
- ✅ **Только curl**: API принимает только запросы от curl
|
||||
- ✅ **POST только**: Только POST запросы к `/execute`
|
||||
- ✅ **JSON валидация**: Строгая проверка входных данных
|
||||
- ✅ **Таймауты**: Ограничение времени выполнения запросов
|
||||
|
||||
## Примеры скриптов
|
||||
|
||||
### Bash скрипт для автоматизации
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
|
||||
API_URL="http://localhost:8080/execute"
|
||||
|
||||
# Функция для выполнения запроса
|
||||
execute_command() {
|
||||
local prompt="$1"
|
||||
local verbose="${2:-}"
|
||||
|
||||
curl -s -X POST "$API_URL" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d "{\"prompt\": \"$prompt\", \"verbose\": \"$verbose\"}" | \
|
||||
jq -r '.command'
|
||||
}
|
||||
|
||||
# Использование
|
||||
echo "Команда: $(execute_command "создать директорию backup")"
|
||||
```
|
||||
|
||||
### Python скрипт
|
||||
|
||||
```python
|
||||
import requests
|
||||
import json
|
||||
|
||||
def execute_command(prompt, system_id=None, verbose=None):
|
||||
url = "http://localhost:8080/execute"
|
||||
payload = {"prompt": prompt}
|
||||
|
||||
if system_id:
|
||||
payload["system_id"] = system_id
|
||||
if verbose:
|
||||
payload["verbose"] = verbose
|
||||
|
||||
response = requests.post(url, json=payload)
|
||||
return response.json()
|
||||
|
||||
# Использование
|
||||
result = execute_command("показать использование диска", verbose="vv")
|
||||
print(f"Команда: {result['command']}")
|
||||
if 'explanation' in result:
|
||||
print(f"Объяснение: {result['explanation']}")
|
||||
```
|
||||
232
docs/CONFIG_COMMAND.md
Normal file
232
docs/CONFIG_COMMAND.md
Normal file
@@ -0,0 +1,232 @@
|
||||
# 🔧 Команда config - Управление конфигурацией
|
||||
|
||||
## 📋 Описание
|
||||
|
||||
Команда `config` позволяет просматривать текущую конфигурацию приложения, включая все настройки, переменные окружения и значения по умолчанию.
|
||||
|
||||
## 🚀 Использование
|
||||
|
||||
### Краткий вывод конфигурации (по умолчанию)
|
||||
|
||||
```bash
|
||||
lcg config
|
||||
# или
|
||||
lcg co
|
||||
```
|
||||
|
||||
**Вывод:**
|
||||
|
||||
``` text
|
||||
Provider: ollama
|
||||
Host: http://192.168.87.108:11434/
|
||||
Model: hf.co/yandex/YandexGPT-5-Lite-8B-instruct-GGUF:Q4_K_M
|
||||
Prompt: Reply with linux command and nothing else. Output with plain response - no need formatting. No need explanation. No need code blocks. No need ` symbols.
|
||||
Timeout: 300 seconds
|
||||
```
|
||||
|
||||
### Полный вывод конфигурации
|
||||
|
||||
```bash
|
||||
lcg config --full
|
||||
# или
|
||||
lcg config -f
|
||||
# или
|
||||
lcg co --full
|
||||
# или
|
||||
lcg co -f
|
||||
```
|
||||
|
||||
**Вывод (JSON формат):**
|
||||
|
||||
```json
|
||||
{
|
||||
"cwd": "/home/user/projects/golang/linux-command-gpt",
|
||||
"host": "http://192.168.87.108:11434/",
|
||||
"proxy_url": "/api/v1/protected/sberchat/chat",
|
||||
"completions": "api/chat",
|
||||
"model": "hf.co/yandex/YandexGPT-5-Lite-8B-instruct-GGUF:Q4_K_M",
|
||||
"prompt": "Reply with linux command and nothing else. Output with plain response - no need formatting. No need explanation. No need code blocks. No need ` symbols.",
|
||||
"api_key_file": ".openai_api_key",
|
||||
"result_folder": "/home/user/.config/lcg/gpt_results",
|
||||
"prompt_folder": "/home/user/.config/lcg/gpt_sys_prompts",
|
||||
"provider_type": "ollama",
|
||||
"jwt_token": "***not set***",
|
||||
"prompt_id": "1",
|
||||
"timeout": "300",
|
||||
"result_history": "/home/user/.config/lcg/gpt_results/lcg_history.json",
|
||||
"no_history_env": "",
|
||||
"allow_execution": false,
|
||||
"main_flags": {
|
||||
"file": "",
|
||||
"no_history": false,
|
||||
"sys": "",
|
||||
"prompt_id": 0,
|
||||
"timeout": 0,
|
||||
"debug": false
|
||||
},
|
||||
"server": {
|
||||
"port": "8080",
|
||||
"host": "localhost"
|
||||
},
|
||||
"validation": {
|
||||
"max_system_prompt_length": 1000,
|
||||
"max_user_message_length": 2000,
|
||||
"max_prompt_name_length": 2000,
|
||||
"max_prompt_desc_length": 5000,
|
||||
"max_command_length": 8000,
|
||||
"max_explanation_length": 20000
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 📊 Структура полной конфигурации
|
||||
|
||||
### Основные настройки
|
||||
|
||||
- **cwd** - текущая рабочая директория
|
||||
- **host** - адрес API сервера
|
||||
- **proxy_url** - путь к API эндпоинту
|
||||
- **completions** - путь к эндпоинту completions
|
||||
- **model** - используемая модель ИИ
|
||||
- **prompt** - системный промпт по умолчанию
|
||||
- **api_key_file** - файл с API ключом
|
||||
- **result_folder** - папка для сохранения результатов
|
||||
- **prompt_folder** - папка с системными промптами
|
||||
- **provider_type** - тип провайдера (ollama/proxy)
|
||||
- **jwt_token** - статус JWT токена (***set***/***from file***/***not set***)
|
||||
- **prompt_id** - ID промпта по умолчанию
|
||||
- **timeout** - таймаут запросов в секундах
|
||||
- **result_history** - файл истории запросов
|
||||
- **no_history_env** - переменная окружения для отключения истории
|
||||
- **allow_execution** - разрешение выполнения команд
|
||||
|
||||
### Флаги командной строки (main_flags)
|
||||
|
||||
- **file** - файл для чтения
|
||||
- **no_history** - отключение истории
|
||||
- **sys** - системный промпт
|
||||
- **prompt_id** - ID промпта
|
||||
- **timeout** - таймаут
|
||||
- **debug** - отладочный режим
|
||||
|
||||
### Настройки сервера (server)
|
||||
|
||||
- **port** - порт веб-сервера
|
||||
- **host** - хост веб-сервера
|
||||
|
||||
### Настройки валидации (validation)
|
||||
|
||||
- **max_system_prompt_length** - максимальная длина системного промпта
|
||||
- **max_user_message_length** - максимальная длина пользовательского сообщения
|
||||
- **max_prompt_name_length** - максимальная длина названия промпта
|
||||
- **max_prompt_desc_length** - максимальная длина описания промпта
|
||||
- **max_command_length** - максимальная длина команды/ответа
|
||||
- **max_explanation_length** - максимальная длина объяснения
|
||||
|
||||
## 🔒 Безопасность
|
||||
|
||||
При выводе полной конфигурации чувствительные данные маскируются:
|
||||
|
||||
- **JWT токены** - показывается статус (***set***/***from file***/***not set***)
|
||||
- **API ключи** - не выводятся в открытом виде
|
||||
- **Пароли** - не сохраняются в конфигурации
|
||||
|
||||
## 📝 Примеры использования
|
||||
|
||||
### Просмотр текущих настроек
|
||||
|
||||
```bash
|
||||
# Краткий вывод
|
||||
lcg config
|
||||
|
||||
# Полный вывод
|
||||
lcg config --full
|
||||
```
|
||||
|
||||
### Проверка настроек валидации
|
||||
|
||||
```bash
|
||||
# Показать только настройки валидации
|
||||
lcg config --full | jq '.validation'
|
||||
```
|
||||
|
||||
### Проверка настроек сервера
|
||||
|
||||
```bash
|
||||
# Показать только настройки сервера
|
||||
lcg config --full | jq '.server'
|
||||
```
|
||||
|
||||
### Проверка переменных окружения
|
||||
|
||||
```bash
|
||||
# Показать все переменные окружения LCG
|
||||
env | grep LCG
|
||||
```
|
||||
|
||||
## 🔧 Интеграция с другими инструментами
|
||||
|
||||
### Использование с jq
|
||||
|
||||
```bash
|
||||
# Получить только модель
|
||||
lcg config --full | jq -r '.model'
|
||||
|
||||
# Получить настройки валидации
|
||||
lcg config --full | jq '.validation'
|
||||
|
||||
# Получить все пути
|
||||
lcg config --full | jq '{result_folder, prompt_folder, result_history}'
|
||||
```
|
||||
|
||||
### Использование с grep
|
||||
|
||||
```bash
|
||||
# Найти все настройки с "timeout"
|
||||
lcg config --full | grep -i timeout
|
||||
|
||||
# Найти все пути
|
||||
lcg config --full | grep -E "(folder|history)"
|
||||
```
|
||||
|
||||
### Сохранение конфигурации в файл
|
||||
|
||||
```bash
|
||||
# Сохранить полную конфигурацию
|
||||
lcg config --full > config.json
|
||||
|
||||
# Сохранить только настройки валидации
|
||||
lcg config --full | jq '.validation' > validation.json
|
||||
```
|
||||
|
||||
## 🐛 Отладка
|
||||
|
||||
### Проверка загрузки конфигурации
|
||||
|
||||
```bash
|
||||
# Показать все настройки
|
||||
lcg config --full
|
||||
|
||||
# Проверить переменные окружения
|
||||
env | grep LCG
|
||||
|
||||
# Проверить файлы конфигурации
|
||||
ls -la ~/.config/lcg/
|
||||
```
|
||||
|
||||
### Типичные проблемы
|
||||
|
||||
1. **Неправильные пути** - проверьте `result_folder` и `prompt_folder`
|
||||
2. **Отсутствующие токены** - проверьте `jwt_token` статус
|
||||
3. **Неправильные лимиты** - проверьте секцию `validation`
|
||||
|
||||
## 📚 Связанные команды
|
||||
|
||||
- `lcg --help` - общая справка
|
||||
- `lcg config --help` - справка по команде config
|
||||
- `lcg serve` - запуск веб-сервера
|
||||
- `lcg prompts list` - список промптов
|
||||
|
||||
---
|
||||
|
||||
**Примечание**: Команда `config` показывает актуальное состояние конфигурации после применения всех переменных окружения и значений по умолчанию.
|
||||
231
docs/CSRF_TESTING_GUIDE.md
Normal file
231
docs/CSRF_TESTING_GUIDE.md
Normal file
@@ -0,0 +1,231 @@
|
||||
# 🛡️ Руководство по тестированию CSRF защиты
|
||||
|
||||
## 📋 Обзор
|
||||
|
||||
Это руководство поможет вам протестировать CSRF защиту в LCG приложении и понять, как работают CSRF атаки.
|
||||
|
||||
## 🚀 Быстрый старт
|
||||
|
||||
### 1. Запуск сервера с CSRF защитой
|
||||
|
||||
```bash
|
||||
# Запуск с аутентификацией и CSRF защитой
|
||||
LCG_SERVER_REQUIRE_AUTH=true ./lcg serve -p 8080
|
||||
```
|
||||
|
||||
### 2. Автоматическое тестирование
|
||||
|
||||
```bash
|
||||
# Запуск автоматических тестов
|
||||
./test_csrf.sh
|
||||
```
|
||||
|
||||
### 3. Ручное тестирование
|
||||
|
||||
```bash
|
||||
# Откройте в браузере
|
||||
open csrf_test.html
|
||||
```
|
||||
|
||||
## 🧪 Типы тестов
|
||||
|
||||
### ✅ **Тест 1: Защищенные запросы**
|
||||
|
||||
- **Цель**: Проверить, что POST запросы без CSRF токена блокируются
|
||||
- **Ожидаемый результат**: 403 Forbidden
|
||||
- **Endpoints**: `/api/execute`, `/api/save-result`, `/api/add-to-history`
|
||||
|
||||
### ✅ **Тест 2: Разрешенные запросы**
|
||||
|
||||
- **Цель**: Проверить, что GET запросы работают
|
||||
- **Ожидаемый результат**: 200 OK
|
||||
- **Endpoints**: `/login`, `/`, `/history`
|
||||
|
||||
### ✅ **Тест 3: CSRF токены**
|
||||
|
||||
- **Цель**: Проверить наличие CSRF токенов в формах
|
||||
- **Ожидаемый результат**: Токены присутствуют в HTML
|
||||
|
||||
### ✅ **Тест 4: Поддельные токены**
|
||||
|
||||
- **Цель**: Проверить защиту от поддельных токенов
|
||||
- **Ожидаемый результат**: 403 Forbidden
|
||||
|
||||
## 🎯 Сценарии атак
|
||||
|
||||
### **Сценарий 1: Выполнение команд**
|
||||
|
||||
```html
|
||||
<!-- Злонамеренная форма -->
|
||||
<form action="http://localhost:8080/api/execute" method="POST">
|
||||
<input type="hidden" name="prompt" value="rm -rf /">
|
||||
<input type="hidden" name="system_id" value="1">
|
||||
<button type="submit">Нажми меня!</button>
|
||||
</form>
|
||||
```
|
||||
|
||||
### **Сценарий 2: Сохранение данных**
|
||||
|
||||
```html
|
||||
<!-- Злонамеренная форма -->
|
||||
<form action="http://localhost:8080/api/save-result" method="POST">
|
||||
<input type="hidden" name="result" value="Вредоносные данные">
|
||||
<input type="hidden" name="command" value="malicious_command">
|
||||
<button type="submit">Сохранить</button>
|
||||
</form>
|
||||
```
|
||||
|
||||
### **Сценарий 3: JavaScript атака**
|
||||
|
||||
```javascript
|
||||
// Злонамеренный JavaScript
|
||||
fetch('http://localhost:8080/api/execute', {
|
||||
method: 'POST',
|
||||
headers: {'Content-Type': 'application/json'},
|
||||
body: JSON.stringify({prompt: 'whoami', system_id: '1'})
|
||||
});
|
||||
```
|
||||
|
||||
## 🔍 Анализ результатов
|
||||
|
||||
### **✅ Защита работает, если:**
|
||||
|
||||
- Все POST запросы возвращают 403 Forbidden
|
||||
- В ответах есть "CSRF token required"
|
||||
- GET запросы работают нормально
|
||||
- CSRF токены присутствуют в формах
|
||||
|
||||
### **❌ Уязвимость есть, если:**
|
||||
|
||||
- POST запросы выполняются успешно (200 OK)
|
||||
- Команды выполняются на сервере
|
||||
- Данные сохраняются без CSRF токенов
|
||||
- Нет проверки Origin/Referer заголовков
|
||||
|
||||
## 🛠️ Инструменты тестирования
|
||||
|
||||
### **1. Автоматический скрипт**
|
||||
|
||||
```bash
|
||||
./test_csrf.sh
|
||||
```
|
||||
|
||||
- Тестирует все основные endpoints
|
||||
- Проверяет CSRF токены
|
||||
- Выводит подробный отчет
|
||||
|
||||
### **2. HTML тестовая страница**
|
||||
|
||||
```bash
|
||||
open csrf_test.html
|
||||
```
|
||||
|
||||
- Интерактивное тестирование
|
||||
- Визуальная проверка результатов
|
||||
- Тестирование в браузере
|
||||
|
||||
### **3. Демонстрационная атака**
|
||||
|
||||
```bash
|
||||
open csrf_demo.html
|
||||
```
|
||||
|
||||
- Показывает, как работают CSRF атаки
|
||||
- Демонстрирует уязвимости
|
||||
- Образовательные цели
|
||||
|
||||
## 🔧 Настройка тестов
|
||||
|
||||
### **Переменные окружения для тестирования:**
|
||||
|
||||
```bash
|
||||
# Включить аутентификацию
|
||||
LCG_SERVER_REQUIRE_AUTH=true
|
||||
|
||||
# Настроить CSRF защиту
|
||||
LCG_COOKIE_SECURE=false
|
||||
LCG_DOMAIN=.localhost
|
||||
LCG_COOKIE_PATH=/
|
||||
|
||||
# Запуск сервера
|
||||
./lcg serve -H 0.0.0.0 -p 8080
|
||||
```
|
||||
|
||||
### **Настройка reverse proxy для тестирования:**
|
||||
|
||||
```bash
|
||||
# Для тестирования за reverse proxy
|
||||
LCG_SERVER_REQUIRE_AUTH=true \
|
||||
LCG_SERVER_ALLOW_HTTP=true \
|
||||
LCG_DOMAIN=.yourdomain.com \
|
||||
LCG_COOKIE_PATH=/lcg \
|
||||
LCG_COOKIE_SECURE=false \
|
||||
./lcg serve -H 0.0.0.0 -p 8080
|
||||
```
|
||||
|
||||
## 📊 Интерпретация результатов
|
||||
|
||||
### **Успешные тесты:**
|
||||
|
||||
``` text
|
||||
✅ CSRF защита /api/execute: PASS - Запрос заблокирован (403 Forbidden)
|
||||
✅ CSRF защита /api/save-result: PASS - Запрос заблокирован (403 Forbidden)
|
||||
✅ CSRF защита /api/add-to-history: PASS - Запрос заблокирован (403 Forbidden)
|
||||
✅ GET запросы: PASS - GET запросы работают (HTTP 200)
|
||||
✅ CSRF токен на странице входа: PASS - Токен найден
|
||||
✅ CSRF защита от поддельного токена: PASS - Поддельный токен заблокирован (403 Forbidden)
|
||||
```
|
||||
|
||||
### **Проблемные тесты:**
|
||||
|
||||
``` text
|
||||
❌ CSRF защита /api/execute: FAIL - Запрос прошел (HTTP 200)
|
||||
❌ CSRF защита /api/save-result: FAIL - Запрос прошел (HTTP 200)
|
||||
❌ CSRF токен на странице входа: FAIL - Токен не найден
|
||||
```
|
||||
|
||||
## 🚨 Частые проблемы
|
||||
|
||||
### **1. Cookies не работают**
|
||||
|
||||
- Проверьте настройки `LCG_DOMAIN`
|
||||
- Убедитесь, что `LCG_COOKIE_PATH` правильный
|
||||
- Проверьте настройки reverse proxy
|
||||
|
||||
### **2. CSRF токены не генерируются**
|
||||
|
||||
- Убедитесь, что `LCG_SERVER_REQUIRE_AUTH=true`
|
||||
- Проверьте инициализацию CSRF менеджера
|
||||
- Проверьте логи сервера
|
||||
|
||||
### **3. Запросы проходят без токенов**
|
||||
|
||||
- Проверьте middleware в `serve/middleware.go`
|
||||
- Убедитесь, что CSRF middleware применяется
|
||||
- Проверьте исключения в middleware
|
||||
|
||||
## 📝 Рекомендации
|
||||
|
||||
### **Для разработчиков:**
|
||||
|
||||
1. Всегда тестируйте CSRF защиту
|
||||
2. Используйте автоматические тесты
|
||||
3. Проверяйте все POST endpoints
|
||||
4. Валидируйте CSRF токены
|
||||
|
||||
### **Для администраторов:**
|
||||
|
||||
1. Регулярно запускайте тесты
|
||||
2. Мониторьте логи на подозрительную активность
|
||||
3. Настройте правильные заголовки в reverse proxy
|
||||
4. Используйте HTTPS в продакшене
|
||||
|
||||
## 🎓 Образовательные материалы
|
||||
|
||||
- **OWASP CSRF Prevention Cheat Sheet**: <https://cheatsheetseries.owasp.org/cheatsheets/Cross-Site_Request_Forgery_Prevention_Cheat_Sheet.html>
|
||||
- **CSRF атаки**: <https://owasp.org/www-community/attacks/csrf>
|
||||
- **SameSite cookies**: <https://web.dev/samesite-cookies-explained/>
|
||||
|
||||
---
|
||||
|
||||
**⚠️ ВНИМАНИЕ**: Эти тесты предназначены только для проверки безопасности вашего собственного приложения. Не используйте их для атак на чужие системы!
|
||||
167
docs/README.md
Normal file
167
docs/README.md
Normal file
@@ -0,0 +1,167 @@
|
||||
# Linux Command GPT (lcg)
|
||||
|
||||
This repo is forked from <https://github.com/asrul10/linux-command-gpt.git>
|
||||
|
||||
Generate Linux commands from natural language. Supports Ollama and Proxy backends, system prompts, different explanation levels (v/vv/vvv), and JSON history.
|
||||
|
||||
## Installation
|
||||
|
||||
Build from source:
|
||||
|
||||
```bash
|
||||
git clone --depth 1 https://github.com/Direct-Dev-Ru/linux-command-gpt.git ~/.linux-command-gpt
|
||||
cd ~/.linux-command-gpt
|
||||
go build -o lcg
|
||||
|
||||
# Add to your PATH
|
||||
ln -s ~/.linux-command-gpt/lcg ~/.local/bin
|
||||
```
|
||||
|
||||
## Quick start
|
||||
|
||||
```bash
|
||||
lcg "I want to extract linux-command-gpt.tar.gz file"
|
||||
```
|
||||
|
||||
After generation you will see a CAPS warning that the answer is from AI and must be verified, the command, and the action menu:
|
||||
|
||||
```text
|
||||
ACTIONS: (c)opy, (s)ave, (r)egenerate, (e)xecute, (v|vv|vvv)explain, (n)othing
|
||||
```
|
||||
|
||||
Explanations:
|
||||
|
||||
- `v` — short; `vv` — medium; `vvv` — detailed with alternatives.
|
||||
|
||||
Clipboard support requires `xclip` or `xsel`.
|
||||
|
||||
## What's new in 2.0.1
|
||||
|
||||
- Mobile UI improvements: better responsiveness (buttons, fonts, spacing) and reduced motion support
|
||||
- Public REST endpoint: `POST /execute` (curl-only) for programmatic access — see `API_GUIDE.md`
|
||||
|
||||
## Environment
|
||||
|
||||
- `LCG_PROVIDER` (default `ollama`) — provider type: `ollama` or `proxy`
|
||||
- `LCG_HOST` (default `http://192.168.87.108:11434/`) — base API URL
|
||||
- `LCG_MODEL` (default `hf.co/yandex/YandexGPT-5-Lite-8B-instruct-GGUF:Q4_K_M`)
|
||||
- `LCG_PROMPT` — default system prompt content
|
||||
- `LCG_PROXY_URL` (default `/api/v1/protected/sberchat/chat`) — proxy chat endpoint
|
||||
- `LCG_COMPLETIONS_PATH` (default `api/chat`) — Ollama chat endpoint (relative)
|
||||
- `LCG_TIMEOUT` (default `300`) — request timeout in seconds
|
||||
- `LCG_RESULT_FOLDER` (default `~/.config/lcg/gpt_results`) — folder for saved results
|
||||
- `LCG_RESULT_HISTORY` (default `$(LCG_RESULT_FOLDER)/lcg_history.json`) — JSON history path
|
||||
- `LCG_PROMPT_FOLDER` (default `~/.config/lcg/gpt_sys_prompts`) — folder for system prompts
|
||||
- `LCG_PROMPT_ID` (default `1`) — default system prompt ID
|
||||
- `LCG_BROWSER_PATH` — custom browser executable path for `--browser` flag
|
||||
- `LCG_JWT_TOKEN` — JWT token for proxy provider
|
||||
- `LCG_NO_HISTORY` — if `1`/`true`, disables history writes for the process
|
||||
- `LCG_ALLOW_EXECUTION` — if `1`/`true`, enables command execution via `(e)` action menu
|
||||
- `LCG_SERVER_PORT` (default `8080`), `LCG_SERVER_HOST` (default `localhost`) — HTTP server settings
|
||||
|
||||
## Flags
|
||||
|
||||
- `--file, -f` read part of prompt from file
|
||||
- `--sys, -s` system prompt content or ID
|
||||
- `--prompt-id, --pid` choose built-in prompt (1–5)
|
||||
- `--timeout, -t` request timeout (sec)
|
||||
- `--no-history, --nh` disable writing/updating JSON history for this run
|
||||
- `--debug, -d` show debug information (request parameters and prompts)
|
||||
- `--version, -v` print version; `--help, -h` help
|
||||
|
||||
## Commands
|
||||
|
||||
- `models`, `health`, `config`
|
||||
- `prompts list|add|delete`
|
||||
- `test-prompt <prompt-id> <command>`
|
||||
- `update-jwt`, `delete-jwt` (proxy)
|
||||
- `update-key`, `delete-key` (not needed for ollama/proxy)
|
||||
- `history list` — list history from JSON
|
||||
- `history view <index>` — view by index
|
||||
- `history delete <index>` — delete by index (re-numbering)
|
||||
- `serve` — start HTTP server to browse saved results (`--port`, `--host`, `--browser`)
|
||||
- `/run` — web interface for executing requests
|
||||
- `/execute` — API endpoint for programmatic access via curl
|
||||
|
||||
## Saving results
|
||||
|
||||
Files are saved to `LCG_RESULT_FOLDER` (default `~/.config/lcg/gpt_results`).
|
||||
|
||||
- Command result: `gpt_request_<MODEL>_YYYY-MM-DD_HH-MM-SS.md`
|
||||
- `# <title>` — H1 with original request (trimmed to 120 chars: first 116 + `...`)
|
||||
- `## Prompt`
|
||||
- `## Response`
|
||||
|
||||
- Detailed explanation: `gpt_explanation_<MODEL>_YYYY-MM-DD_HH-MM-SS.md`
|
||||
- `# <title>`
|
||||
- `## Prompt`
|
||||
- `## Command`
|
||||
- `## Explanation and Alternatives (model: <MODEL>)`
|
||||
|
||||
## History
|
||||
|
||||
- Stored as JSON array in `LCG_RESULT_HISTORY`.
|
||||
- On new request, if the same command exists, you will be prompted to view or overwrite.
|
||||
- Showing from history does not call the API; the standard action menu is shown.
|
||||
|
||||
## Browser Integration
|
||||
|
||||
The `serve` command supports automatic browser opening:
|
||||
|
||||
```bash
|
||||
# Start server and open browser automatically
|
||||
lcg serve --browser
|
||||
|
||||
# Use custom browser
|
||||
export LCG_BROWSER_PATH="/usr/bin/firefox"
|
||||
lcg serve --browser
|
||||
|
||||
# Start on custom host/port with browser
|
||||
lcg serve --host 0.0.0.0 --port 9000 --browser
|
||||
```
|
||||
|
||||
Supported browsers (in priority order):
|
||||
|
||||
- Yandex Browser (`yandex-browser`, `yandex-browser-stable`)
|
||||
- Mozilla Firefox (`firefox`, `firefox-esr`)
|
||||
- Google Chrome (`google-chrome`, `google-chrome-stable`)
|
||||
- Chromium (`chromium`, `chromium-browser`)
|
||||
|
||||
## API Access
|
||||
|
||||
The `serve` command provides both a web interface and REST API:
|
||||
|
||||
**Web Interface:**
|
||||
|
||||
- Browse results at `http://localhost:8080/`
|
||||
- Execute requests at `http://localhost:8080/run`
|
||||
- Manage prompts at `http://localhost:8080/prompts`
|
||||
- View history at `http://localhost:8080/history`
|
||||
|
||||
**REST API:**
|
||||
|
||||
```bash
|
||||
# Start server
|
||||
lcg serve
|
||||
|
||||
# Make API request
|
||||
curl -X POST http://localhost:8080/execute \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"prompt": "create directory test", "verbose": "vv"}'
|
||||
```
|
||||
|
||||
**Response:**
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"command": "mkdir test",
|
||||
"explanation": "The mkdir command creates a new directory...",
|
||||
"model": "hf.co/yandex/YandexGPT-5-Lite-8B-instruct-GGUF:Q4_K_M",
|
||||
"elapsed": 1.23
|
||||
}
|
||||
```
|
||||
|
||||
For complete API documentation, see `API_GUIDE.md`.
|
||||
|
||||
For full guide in Russian, see `USAGE_GUIDE.md`.
|
||||
337
docs/RELEASE_GUIDE.md
Normal file
337
docs/RELEASE_GUIDE.md
Normal file
@@ -0,0 +1,337 @@
|
||||
# 🚀 Гайд по созданию релизов с помощью GoReleaser
|
||||
|
||||
Этот документ описывает процесс создания релизов для проекта `linux-command-gpt` с использованием GoReleaser.
|
||||
|
||||
## 📋 Содержание
|
||||
|
||||
- [Установка GoReleaser](#установка-goreleaser)
|
||||
- [Конфигурация](#конфигурация)
|
||||
- [Процесс создания релиза](#процесс-создания-релиза)
|
||||
- [Автоматизация](#автоматизация)
|
||||
- [Устранение проблем](#устранение-проблем)
|
||||
|
||||
## 🔧 Установка GoReleaser
|
||||
|
||||
### Linux/macOS
|
||||
|
||||
```bash
|
||||
# Скачать и установить последнюю версию
|
||||
curl -sL https://git.io/goreleaser | bash
|
||||
|
||||
# Или через Homebrew (macOS)
|
||||
brew install goreleaser
|
||||
|
||||
# Или через Go
|
||||
go install github.com/goreleaser/goreleaser@latest
|
||||
```
|
||||
|
||||
### Windows
|
||||
|
||||
```powershell
|
||||
# Через Chocolatey
|
||||
choco install goreleaser
|
||||
|
||||
# Или скачать с GitHub Releases
|
||||
# https://github.com/goreleaser/goreleaser/releases
|
||||
```
|
||||
|
||||
## ⚙️ Конфигурация
|
||||
|
||||
### Файл `.goreleaser.yaml`
|
||||
|
||||
В проекте используется следующая конфигурация GoReleaser:
|
||||
|
||||
```yaml
|
||||
version: 2
|
||||
|
||||
before:
|
||||
hooks:
|
||||
- go mod tidy
|
||||
- go generate ./...
|
||||
|
||||
builds:
|
||||
- binary: lcg
|
||||
env:
|
||||
- CGO_ENABLED=0
|
||||
goarch:
|
||||
- amd64
|
||||
- arm64
|
||||
- arm
|
||||
goos:
|
||||
- linux
|
||||
- darwin
|
||||
|
||||
archives:
|
||||
- formats: [tar.gz]
|
||||
name_template: >-
|
||||
{{ .ProjectName }}_
|
||||
{{- title .Os }}_
|
||||
{{- if eq .Arch "amd64" }}x86_64
|
||||
{{- else if eq .Arch "386" }}i386
|
||||
{{- else }}{{ .Arch }}{{ end }}
|
||||
{{- if .Arm }}v{{ .Arm }}{{ end }}
|
||||
format_overrides:
|
||||
- goos: windows
|
||||
formats: [zip]
|
||||
|
||||
changelog:
|
||||
sort: asc
|
||||
filters:
|
||||
exclude:
|
||||
- "^docs:"
|
||||
- "^test:"
|
||||
|
||||
release:
|
||||
footer: >-
|
||||
---
|
||||
Released by [GoReleaser](https://github.com/goreleaser/goreleaser).
|
||||
```
|
||||
|
||||
### Ключевые настройки
|
||||
|
||||
- **builds**: Сборка для Linux, macOS, Windows (amd64, arm64, arm)
|
||||
- **archives**: Создание архивов tar.gz для Unix и zip для Windows
|
||||
- **changelog**: Автоматическое создание changelog из git commits
|
||||
- **release**: Настройки GitHub релиза
|
||||
|
||||
## 🚀 Процесс создания релиза
|
||||
|
||||
### 1. Подготовка
|
||||
|
||||
```bash
|
||||
# Убедитесь, что все изменения закоммичены
|
||||
git status
|
||||
|
||||
# Обновите версию в VERSION.txt
|
||||
echo "v2.0.2" > VERSION.txt
|
||||
|
||||
# Создайте тег
|
||||
git tag v2.0.2
|
||||
git push origin v2.0.2
|
||||
```
|
||||
|
||||
### 2. Настройка переменных окружения
|
||||
|
||||
```bash
|
||||
# Установите GitHub токен
|
||||
export GITHUB_TOKEN="your_github_token_here"
|
||||
|
||||
# Или создайте файл .env
|
||||
echo "GITHUB_TOKEN=your_github_token_here" > .env
|
||||
```
|
||||
|
||||
### 3. Создание релиза
|
||||
|
||||
#### Полный релиз
|
||||
|
||||
```bash
|
||||
# Создать релиз с загрузкой на GitHub
|
||||
goreleaser release
|
||||
|
||||
# Создать релиз без загрузки (только локально)
|
||||
goreleaser release --clean
|
||||
```
|
||||
|
||||
#### Тестовый релиз (snapshot)
|
||||
|
||||
```bash
|
||||
# Создать тестовую сборку
|
||||
goreleaser release --snapshot
|
||||
|
||||
# Тестовая сборка без загрузки
|
||||
goreleaser release --snapshot --clean
|
||||
```
|
||||
|
||||
### 4. Проверка результатов
|
||||
|
||||
После выполнения команды GoReleaser создаст:
|
||||
|
||||
- **Архивы**: `dist/` - готовые архивы для всех платформ
|
||||
- **Чексуммы**: `dist/checksums.txt` - контрольные суммы файлов
|
||||
- **GitHub релиз**: Автоматически созданный релиз на GitHub
|
||||
|
||||
## 🤖 Автоматизация
|
||||
|
||||
### GitHub Actions
|
||||
|
||||
Создайте файл `.github/workflows/release.yml`:
|
||||
|
||||
```yaml
|
||||
name: Release
|
||||
on:
|
||||
push:
|
||||
tags:
|
||||
- 'v*'
|
||||
jobs:
|
||||
release:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v3
|
||||
with:
|
||||
fetch-depth: 0
|
||||
- uses: actions/setup-go@v3
|
||||
with:
|
||||
go-version: '1.21'
|
||||
- name: Run GoReleaser
|
||||
uses: goreleaser/goreleaser-action@v4
|
||||
with:
|
||||
distribution: goreleaser
|
||||
version: latest
|
||||
args: release
|
||||
env:
|
||||
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
|
||||
```
|
||||
|
||||
### Локальные скрипты
|
||||
|
||||
В проекте есть готовые скрипты:
|
||||
|
||||
```bash
|
||||
# Предварительная подготовка
|
||||
./shell-code/pre-release.sh
|
||||
|
||||
# Создание релиза
|
||||
./shell-code/release.sh
|
||||
```
|
||||
|
||||
## 📁 Структура релиза
|
||||
|
||||
После создания релиза в директории `dist/` будут созданы:
|
||||
|
||||
```
|
||||
dist/
|
||||
├── artifacts.json # Метаданные артефактов
|
||||
├── CHANGELOG.md # Автоматически созданный changelog
|
||||
├── config.yaml # Конфигурация GoReleaser
|
||||
├── digests.txt # Хеши файлов
|
||||
├── go-lcg_2.0.1_checksums.txt
|
||||
├── go-lcg_Darwin_arm64.tar.gz
|
||||
├── go-lcg_Darwin_x86_64.tar.gz
|
||||
├── go-lcg_Linux_arm64.tar.gz
|
||||
├── go-lcg_Linux_i386.tar.gz
|
||||
├── go-lcg_Linux_x86_64.tar.gz
|
||||
├── go-lcg_Windows_arm64.zip
|
||||
├── go-lcg_Windows_i386.zip
|
||||
├── go-lcg_Windows_x86_64.zip
|
||||
└── metadata.json # Метаданные релиза
|
||||
```
|
||||
|
||||
## 🔍 Устранение проблем
|
||||
|
||||
### Правильные флаги GoReleaser
|
||||
|
||||
**Важно**: В современных версиях GoReleaser флаг `--skip-publish` больше не поддерживается. Используйте:
|
||||
|
||||
- `--clean` - очищает директорию `dist/` перед сборкой
|
||||
- `--snapshot` - создает тестовую сборку без создания тега
|
||||
- `--debug` - подробный вывод для отладки
|
||||
- `--skip-validate` - пропускает валидацию конфигурации
|
||||
|
||||
### Частые ошибки
|
||||
|
||||
#### 1. Ошибка аутентификации GitHub
|
||||
|
||||
```
|
||||
Error: failed to get GitHub token: missing github token
|
||||
```
|
||||
|
||||
**Решение**: Установите `GITHUB_TOKEN` в переменные окружения.
|
||||
|
||||
#### 2. Ошибка создания тега
|
||||
|
||||
```
|
||||
Error: git tag v1.0.0 already exists
|
||||
```
|
||||
|
||||
**Решение**: Удалите существующий тег или используйте другую версию.
|
||||
|
||||
#### 3. Ошибка сборки
|
||||
|
||||
```
|
||||
Error: failed to build for linux/amd64
|
||||
```
|
||||
|
||||
**Решение**: Проверьте, что код компилируется локально:
|
||||
|
||||
```bash
|
||||
go build -o lcg .
|
||||
```
|
||||
|
||||
### Отладка
|
||||
|
||||
```bash
|
||||
# Подробный вывод
|
||||
goreleaser release --debug
|
||||
|
||||
# Проверка конфигурации
|
||||
goreleaser check
|
||||
|
||||
# Только сборка без релиза
|
||||
goreleaser build
|
||||
|
||||
# Создание релиза без публикации (только локальная сборка)
|
||||
goreleaser release --clean
|
||||
|
||||
# Создание snapshot релиза без публикации
|
||||
goreleaser release --snapshot --clean
|
||||
```
|
||||
|
||||
## 📝 Лучшие практики
|
||||
|
||||
### 1. Версионирование
|
||||
|
||||
- Используйте семантическое версионирование (SemVer)
|
||||
- Обновляйте `VERSION.txt` перед созданием релиза
|
||||
- Создавайте теги в формате `v1.0.0`
|
||||
|
||||
### 2. Changelog
|
||||
|
||||
- Пишите понятные commit messages
|
||||
- Используйте conventional commits для автоматического changelog
|
||||
- Исключайте технические коммиты из changelog
|
||||
|
||||
### 3. Тестирование
|
||||
|
||||
- Всегда тестируйте snapshot релизы перед полным релизом
|
||||
- Проверяйте сборки на разных платформах
|
||||
- Тестируйте установку из релиза
|
||||
|
||||
### 4. Безопасность
|
||||
|
||||
- Никогда не коммитьте токены в репозиторий
|
||||
- Используйте GitHub Secrets для CI/CD
|
||||
- Регулярно обновляйте токены доступа
|
||||
|
||||
## 🎯 Пример полного процесса
|
||||
|
||||
```bash
|
||||
# 1. Подготовка
|
||||
git checkout main
|
||||
git pull origin main
|
||||
|
||||
# 2. Обновление версии
|
||||
echo "v2.0.2" > VERSION.txt
|
||||
git add VERSION.txt
|
||||
git commit -m "chore: bump version to v2.0.2"
|
||||
|
||||
# 3. Создание тега
|
||||
git tag v2.0.2
|
||||
git push origin v2.0.2
|
||||
|
||||
# 4. Создание релиза
|
||||
export GITHUB_TOKEN="your_token"
|
||||
goreleaser release
|
||||
|
||||
# 5. Проверка
|
||||
ls -la dist/
|
||||
```
|
||||
|
||||
## 📚 Дополнительные ресурсы
|
||||
|
||||
- [Официальная документация GoReleaser](https://goreleaser.com/)
|
||||
- [Примеры конфигураций](https://github.com/goreleaser/goreleaser/tree/main/examples)
|
||||
- [GitHub Actions для GoReleaser](https://github.com/goreleaser/goreleaser-action)
|
||||
|
||||
---
|
||||
|
||||
**Примечание**: Этот гайд создан специально для проекта `linux-command-gpt`. Для других проектов может потребоваться адаптация конфигурации.
|
||||
258
docs/REVERSE_PROXY_GUIDE.md
Normal file
258
docs/REVERSE_PROXY_GUIDE.md
Normal file
@@ -0,0 +1,258 @@
|
||||
# 🔄 Гайд по настройке LCG за Reverse Proxy
|
||||
|
||||
## 📋 Переменные окружения для Reverse Proxy
|
||||
|
||||
### 🔧 **Основные настройки:**
|
||||
|
||||
```bash
|
||||
# Включить аутентификацию
|
||||
LCG_SERVER_REQUIRE_AUTH=true
|
||||
|
||||
# Настроить домен для cookies (опционально)
|
||||
LCG_DOMAIN=.yourdomain.com
|
||||
|
||||
# Настроить путь для cookies (для префикса пути)
|
||||
LCG_COOKIE_PATH=/lcg
|
||||
|
||||
# Управление Secure флагом cookies
|
||||
LCG_COOKIE_SECURE=false
|
||||
|
||||
# Разрешить HTTP (для работы за reverse proxy)
|
||||
LCG_SERVER_ALLOW_HTTP=true
|
||||
|
||||
# Настроить хост и порт
|
||||
LCG_SERVER_HOST=0.0.0.0
|
||||
LCG_SERVER_PORT=8080
|
||||
|
||||
# Пароль для входа (по умолчанию: admin#123456)
|
||||
LCG_SERVER_PASSWORD=your_secure_password
|
||||
```
|
||||
|
||||
## 🚀 **Запуск за Reverse Proxy**
|
||||
|
||||
### **1. Nginx конфигурация:**
|
||||
|
||||
```nginx
|
||||
server {
|
||||
listen 443 ssl;
|
||||
server_name yourdomain.com;
|
||||
|
||||
# SSL настройки
|
||||
ssl_certificate /path/to/cert.pem;
|
||||
ssl_certificate_key /path/to/key.pem;
|
||||
|
||||
location / {
|
||||
proxy_pass http://localhost:8080;
|
||||
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;
|
||||
|
||||
# Важно для работы cookies
|
||||
proxy_cookie_domain localhost yourdomain.com;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### **2. Apache конфигурация:**
|
||||
|
||||
```apache
|
||||
<VirtualHost *:443>
|
||||
ServerName yourdomain.com
|
||||
SSLEngine on
|
||||
SSLCertificateFile /path/to/cert.pem
|
||||
SSLCertificateKeyFile /path/to/key.pem
|
||||
|
||||
ProxyPreserveHost On
|
||||
ProxyPass / http://localhost:8080/
|
||||
ProxyPassReverse / http://localhost:8080/
|
||||
|
||||
# Настройки для cookies
|
||||
ProxyPassReverseCookieDomain localhost yourdomain.com
|
||||
</VirtualHost>
|
||||
```
|
||||
|
||||
### **3. Caddy конфигурация:**
|
||||
|
||||
```caddy
|
||||
yourdomain.com {
|
||||
reverse_proxy localhost:8080 {
|
||||
header_up Host {host}
|
||||
header_up X-Real-IP {remote}
|
||||
header_up X-Forwarded-For {remote}
|
||||
header_up X-Forwarded-Proto {scheme}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 🏃♂️ **Команды запуска**
|
||||
|
||||
### **Базовый запуск:**
|
||||
|
||||
```bash
|
||||
LCG_SERVER_REQUIRE_AUTH=true LCG_SERVER_ALLOW_HTTP=true ./lcg serve -H 0.0.0.0 -p 8080
|
||||
```
|
||||
|
||||
### **С настройкой домена:**
|
||||
|
||||
```bash
|
||||
LCG_SERVER_REQUIRE_AUTH=true \
|
||||
LCG_SERVER_ALLOW_HTTP=true \
|
||||
LCG_DOMAIN=.yourdomain.com \
|
||||
LCG_COOKIE_SECURE=false \
|
||||
./lcg serve -H 0.0.0.0 -p 8080
|
||||
```
|
||||
|
||||
### **С кастомным паролем:**
|
||||
|
||||
```bash
|
||||
LCG_SERVER_REQUIRE_AUTH=true \
|
||||
LCG_SERVER_ALLOW_HTTP=true \
|
||||
LCG_SERVER_PASSWORD=my_secure_password \
|
||||
LCG_DOMAIN=.yourdomain.com \
|
||||
./lcg serve -H 0.0.0.0 -p 8080
|
||||
```
|
||||
|
||||
## 🔒 **Безопасность**
|
||||
|
||||
### **Рекомендуемые настройки:**
|
||||
|
||||
- ✅ `LCG_SERVER_REQUIRE_AUTH=true` - всегда включайте аутентификацию
|
||||
- ✅ `LCG_COOKIE_SECURE=false` - для HTTP за reverse proxy
|
||||
- ✅ `LCG_DOMAIN=.yourdomain.com` - для правильной работы cookies
|
||||
- ✅ Сильный пароль в `LCG_SERVER_PASSWORD`
|
||||
|
||||
### **Настройки Reverse Proxy:**
|
||||
|
||||
- ✅ Передавайте заголовки `X-Forwarded-*`
|
||||
- ✅ Настройте `proxy_cookie_domain` в Nginx
|
||||
- ✅ Используйте HTTPS на уровне reverse proxy
|
||||
|
||||
## 🐳 **Docker Compose пример**
|
||||
|
||||
```yaml
|
||||
version: '3.8'
|
||||
services:
|
||||
lcg:
|
||||
image: your-lcg-image
|
||||
environment:
|
||||
- LCG_SERVER_REQUIRE_AUTH=true
|
||||
- LCG_SERVER_ALLOW_HTTP=true
|
||||
- LCG_DOMAIN=.yourdomain.com
|
||||
- LCG_COOKIE_SECURE=false
|
||||
- LCG_SERVER_PASSWORD=secure_password
|
||||
ports:
|
||||
- "8080:8080"
|
||||
restart: unless-stopped
|
||||
|
||||
nginx:
|
||||
image: nginx:alpine
|
||||
volumes:
|
||||
- ./nginx.conf:/etc/nginx/nginx.conf
|
||||
- ./ssl:/etc/nginx/ssl
|
||||
ports:
|
||||
- "443:443"
|
||||
depends_on:
|
||||
- lcg
|
||||
```
|
||||
|
||||
## 🔍 **Диагностика проблем**
|
||||
|
||||
### **Проверка cookies:**
|
||||
|
||||
```bash
|
||||
# Проверить установку cookies
|
||||
curl -I https://yourdomain.com/login
|
||||
|
||||
# Проверить домен cookies
|
||||
curl -v https://yourdomain.com/login 2>&1 | grep -i cookie
|
||||
```
|
||||
|
||||
### **Логи приложения:**
|
||||
|
||||
```bash
|
||||
# Запуск с debug режимом
|
||||
LCG_SERVER_REQUIRE_AUTH=true \
|
||||
LCG_SERVER_ALLOW_HTTP=true \
|
||||
./lcg -d serve -H 0.0.0.0 -p 8080
|
||||
```
|
||||
|
||||
## 📝 **Примечания**
|
||||
|
||||
- **SameSite=Lax** - более мягкий режим для reverse proxy
|
||||
- **Domain cookies** - работают только с указанным доменом
|
||||
- **Secure=false** - обязательно для HTTP за reverse proxy
|
||||
- **X-Forwarded-* заголовки** - важны для правильной работы
|
||||
|
||||
## 🆘 **Частые проблемы**
|
||||
|
||||
1. **Cookies не работают** → Проверьте `LCG_DOMAIN` и настройки reverse proxy
|
||||
2. **Ошибка 403 CSRF** → Проверьте передачу cookies через reverse proxy
|
||||
3. **Не работает аутентификация** → Убедитесь что `LCG_SERVER_REQUIRE_AUTH=true`
|
||||
4. **Проблемы с HTTPS** → Настройте `LCG_COOKIE_SECURE=false` для HTTP за reverse proxy
|
||||
|
||||
## 🛣️ **Конфигурация с префиксом пути**
|
||||
|
||||
### **Пример: example.com/lcg**
|
||||
|
||||
#### **Переменные окружения для префикса:**
|
||||
|
||||
```bash
|
||||
LCG_SERVER_REQUIRE_AUTH=true \
|
||||
LCG_SERVER_ALLOW_HTTP=true \
|
||||
LCG_DOMAIN=.example.com \
|
||||
LCG_COOKIE_PATH=/lcg \
|
||||
LCG_COOKIE_SECURE=false \
|
||||
./lcg serve -H 0.0.0.0 -p 8080
|
||||
```
|
||||
|
||||
#### **Nginx с префиксом:**
|
||||
|
||||
```nginx
|
||||
server {
|
||||
listen 443 ssl;
|
||||
server_name example.com;
|
||||
|
||||
location /lcg/ {
|
||||
proxy_pass http://localhost:8080/;
|
||||
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;
|
||||
|
||||
# Важно для работы cookies с префиксом
|
||||
proxy_cookie_domain localhost example.com;
|
||||
proxy_cookie_path / /lcg/;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### **Apache с префиксом:**
|
||||
|
||||
```apache
|
||||
<VirtualHost *:443>
|
||||
ServerName example.com
|
||||
SSLEngine on
|
||||
|
||||
ProxyPreserveHost On
|
||||
ProxyPass /lcg/ http://localhost:8080/
|
||||
ProxyPassReverse /lcg/ http://localhost:8080/
|
||||
|
||||
# Настройки для cookies с префиксом
|
||||
ProxyPassReverseCookieDomain localhost example.com
|
||||
ProxyPassReverseCookiePath / /lcg/
|
||||
</VirtualHost>
|
||||
```
|
||||
|
||||
#### **Caddy с префиксом:**
|
||||
|
||||
```caddy
|
||||
example.com {
|
||||
reverse_proxy /lcg/* localhost:8080 {
|
||||
header_up Host {host}
|
||||
header_up X-Real-IP {remote}
|
||||
header_up X-Forwarded-For {remote}
|
||||
header_up X-Forwarded-Proto {scheme}
|
||||
}
|
||||
}
|
||||
```
|
||||
118
docs/ROADMAP.md
Normal file
118
docs/ROADMAP.md
Normal file
@@ -0,0 +1,118 @@
|
||||
# Дорожная карта развития (функциональность и безопасность)
|
||||
|
||||
Документ описывает план развития проекта на ближайшие релизы с фокусом на улучшение функциональности и усиление безопасности.
|
||||
|
||||
## Принципы
|
||||
|
||||
- Безопасность по умолчанию: новые возможности включают безопасные дефолты, опционально ослабляются.
|
||||
- Обратная совместимость: не ломать существующие сценарии CLI и API.
|
||||
- Прозрачность: чёткие Changelog, версии по SemVer, миграции и откаты.
|
||||
- Качество: тесты, линтеры, аудит зависимостей, автоматизация релизов.
|
||||
|
||||
## Вехи и цели
|
||||
|
||||
### v2.1.0 — Формализация API и UX улучшения
|
||||
|
||||
- REST API
|
||||
- Описать `POST /execute` в OpenAPI (swagger.yaml/json) и приложить в репозитории.
|
||||
- Валидация входа по схеме: обязательные поля, ограничения длины, лимит размера тела.
|
||||
- Явные коды ошибок и структура ответа (коды/сообщения).
|
||||
- Безопасность API (первый этап)
|
||||
- Дополнить защиту: ограничение размера тела (например, 64KB), тайм-ауты на чтение/запись.
|
||||
- Rate limit (встроенный простой токен-бакет, по IP). Конфиг через env.
|
||||
- Логирование попыток доступа и ошибок API (с редактированием PII).
|
||||
- Веб-интерфейс
|
||||
- Улучшения мобильной версии (доступность, контраст, a11y-метки).
|
||||
- Переключатель темы (light/dark), сохранение предпочтений.
|
||||
- Промпты
|
||||
- Экспорт/импорт системных промптов (JSON) из UI/CLI.
|
||||
- Превью при редактировании промптов в UI.
|
||||
- Документация
|
||||
- `API_GUIDE.md`: синхронизировать с OpenAPI.
|
||||
- `USAGE_GUIDE.md`: добавить раздел «Ограничения API и лимиты».
|
||||
|
||||
### v2.2.0 — Усиление безопасности и управление доступом
|
||||
|
||||
- Аутентификация/Авторизация для веб-сервера
|
||||
- Ввести токен доступа для API: `LCG_SERVER_TOKEN` (Bearer), отключаемо.
|
||||
- Сессии UI (опционально): cookie HttpOnly + SameSite=strict, CSRF-защита форм.
|
||||
- CORS: явный список разрешённых Origin через `LCG_CORS_ORIGINS`.
|
||||
- Транспорт и заголовки безопасности
|
||||
- Рекомендации по TLS терминации (пример конфигов nginx/caddy) в `serve/README.md`.
|
||||
- Security headers: CSP, X-Content-Type-Options, X-Frame-Options, Referrer-Policy, HSTS (при HTTPS).
|
||||
- Хранилище и история
|
||||
- Опциональное шифрование истории на диске (`LCG_HISTORY_ENCRYPTION_KEY_FILE`).
|
||||
- Права на файлы истории и результатов: 0600, директории 0700.
|
||||
- Настраиваемая ретенция истории (дни/размер). Авто-очистка.
|
||||
- Наблюдаемость
|
||||
- Аудит-лог действий UI/API с маскированием чувствительных данных.
|
||||
- Включаемые/отключаемые метрики (prometheus endpoint — опционально, по отдельному порту/токену).
|
||||
|
||||
### v2.3.0 — Расширяемость и производительность
|
||||
|
||||
- Плагины провайдеров
|
||||
- Интерфейс адаптеров (провайдеры LLM), регистрация через конфиг/билд-теги.
|
||||
- Образцы адаптеров и гайды по разработке.
|
||||
- Производительность
|
||||
- Пулы HTTP-клиентов, connection reuse, упреждающие таймауты на уровне контекста.
|
||||
- Кэширование результатов подробных объяснений (опционально, по ключу запроса).
|
||||
- Расширения API
|
||||
- Пакетная обработка запросов (batch) с квотой.
|
||||
- Пагинация и фильтрация для `/history` (если будет публичный REST).
|
||||
- Дистрибуция
|
||||
- Улучшения .goreleaser: публикация SBOM, подписи (cosign), детерминированные сборки.
|
||||
- Готовые пакеты: deb/rpm, инструкции для brew/scoop (по возможности).
|
||||
|
||||
## Backlog (кандидаты)
|
||||
|
||||
- Потоковая генерация (stream) и WebSocket-канал (при наличии поддержки у провайдеров).
|
||||
- Оффлайн-режим/кэширование моделей для локальных провайдеров.
|
||||
- Расширенный поиск по результатам/истории, теги и сохранённые фильтры.
|
||||
- Резервное копирование и восстановление каталога результатов/истории.
|
||||
- Улучшение доступности (a11y), горячие клавиши, локализация интерфейса.
|
||||
|
||||
## Техническое качество
|
||||
|
||||
- Обновление стека
|
||||
- Обновить Go (минимум 1.20+), пересобрать и протестировать совместимость.
|
||||
- Регулярные обновления зависимостей и проверка уязвимостей (`govulncheck`).
|
||||
- Линтеры и проверка качества
|
||||
- Включить `golangci-lint`, `staticcheck`, `gosec` в CI.
|
||||
- Форматирование и единый стиль, pre-commit хуки.
|
||||
- Тесты
|
||||
- Unit-тесты на `serve/*` (маршруты, валидация входных данных, заголовки).
|
||||
- Интеграционные тесты API `/execute` (позитив/негатив, лимиты, токены).
|
||||
- Фаззинг критичных функций парсинга/валидации.
|
||||
- CI/CD
|
||||
- GitHub Actions: сборка, тесты, линты, релизы. Генерация чек-сумм, подписи, SBOM.
|
||||
- Автоматическая публикация релизов и проверок артефактов.
|
||||
|
||||
## Конфигурация (новые/уточняемые переменные)
|
||||
|
||||
- `LCG_SERVER_TOKEN` — токен доступа для API (Bearer). Отключаемый режим.
|
||||
- `LCG_RATE_LIMIT` — глобальные лимиты (например, `60/m`, `5/s`).
|
||||
- `LCG_CORS_ORIGINS` — список разрешённых Origin.
|
||||
- `LCG_HISTORY_ENCRYPTION_KEY_FILE` — путь к ключу для шифрования истории (опц.).
|
||||
- `LCG_MAX_BODY_BYTES` — максимальный размер тела запроса, байты (по умолчанию 65536).
|
||||
- `LCG_BROWSER_PATH` — путь к браузеру для `--browser`.
|
||||
|
||||
## Политика релизов
|
||||
|
||||
- SemVer: MINOR — функционал без ломаний, PATCH — багфиксы/мелкие улучшения.
|
||||
- Каждый релиз: обновлённый `CHANGELOG.txt`, теги `vX.Y.Z`, двуязычная документация (RU/EN при возможности).
|
||||
- Security Advisories: отдельный раздел/ISSUE шаблон для отчётов об уязвимостях.
|
||||
|
||||
## Критерии приемки (примеры)
|
||||
|
||||
- v2.1.0: OpenAPI спецификация доступна, API валидируется по схеме, лимит размера тела и таймауты соблюдаются, добавлены тесты в CI.
|
||||
- v2.2.0: Доступ к API с токеном включаем/отключаем через env; активированы security-заголовки; есть базовые правила CORS; аудит-лог включается флагом.
|
||||
- v2.3.0: Пулы клиентов, бенчмарки показывают улучшение p95 латентности, есть механизм подключения новых провайдеров.
|
||||
|
||||
## Риски и смягчение
|
||||
|
||||
- Ломание совместимости при усилении безопасности → режим совместимости через env/флаги.
|
||||
- Рост сложности конфигурации → шаблоны конфигов и «рецепты» в README/serve/README.md.
|
||||
- Производительные регрессии из-за валидации/лимитов → профилирование и кэширование на горячих путях.
|
||||
|
||||
---
|
||||
Последнее обновление: 2025-10-22
|
||||
199
docs/SECURITY_FEATURES.md
Normal file
199
docs/SECURITY_FEATURES.md
Normal file
@@ -0,0 +1,199 @@
|
||||
# 🔒 Функции безопасности LCG
|
||||
|
||||
## 🛡️ Автоматическое принуждение к HTTPS
|
||||
|
||||
### Логика безопасности
|
||||
|
||||
Приложение автоматически определяет, нужно ли использовать HTTPS:
|
||||
|
||||
1. **Небезопасные хосты** (не localhost/127.0.0.1) → **принудительно HTTPS**
|
||||
2. **Безопасные хосты** (localhost/127.0.0.1) → HTTP (если не указано иное)
|
||||
3. **Переменная `LCG_SERVER_ALLOW_HTTP=true`** → разрешает HTTP для любых хостов
|
||||
|
||||
### Примеры
|
||||
|
||||
```bash
|
||||
# Небезопасно - принудительно HTTPS
|
||||
LCG_SERVER_HOST=192.168.1.100 lcg serve
|
||||
# Результат: https://192.168.1.100:8080
|
||||
|
||||
# Безопасно - HTTP по умолчанию
|
||||
LCG_SERVER_HOST=localhost lcg serve
|
||||
# Результат: http://localhost:8080
|
||||
|
||||
# Принудительно HTTP для любого хоста
|
||||
LCG_SERVER_HOST=192.168.1.100 LCG_SERVER_ALLOW_HTTP=true lcg serve
|
||||
# Результат: http://192.168.1.100:8080
|
||||
```
|
||||
|
||||
## 🔐 SSL/TLS сертификаты
|
||||
|
||||
### Автоматическая генерация
|
||||
|
||||
Приложение автоматически генерирует самоподписанный сертификат если:
|
||||
|
||||
1. Не указаны переменные `LCG_SERVER_SSL_CERT_FILE` и `LCG_SERVER_SSL_KEY_FILE`
|
||||
2. Не найдены файлы в `~/.config/lcg/server/ssl/cert.pem` и `~/.config/lcg/server/ssl/key.pem`
|
||||
|
||||
### Расположение сертификатов
|
||||
|
||||
``` text
|
||||
~/.config/lcg/
|
||||
├── config/
|
||||
│ └── server/
|
||||
│ └── ssl/
|
||||
│ ├── cert.pem # Сертификат
|
||||
│ └── key.pem # Приватный ключ
|
||||
```
|
||||
|
||||
### Переменные окружения
|
||||
|
||||
| Переменная | Описание | По умолчанию |
|
||||
|------------|----------|--------------|
|
||||
| `LCG_CONFIG_FOLDER` | Папка конфигурации | `~/.config/lcg/config` |
|
||||
| `LCG_SERVER_ALLOW_HTTP` | Разрешить HTTP для любых хостов | `false` |
|
||||
| `LCG_SERVER_SSL_CERT_FILE` | Путь к сертификату | `""` (авто) |
|
||||
| `LCG_SERVER_SSL_KEY_FILE` | Путь к ключу | `""` (авто) |
|
||||
|
||||
## 🚀 Примеры использования
|
||||
|
||||
### Безопасный режим (по умолчанию)
|
||||
|
||||
```bash
|
||||
# Локальный сервер - HTTP
|
||||
lcg serve
|
||||
|
||||
# Внешний сервер - принудительно HTTPS
|
||||
LCG_SERVER_HOST=192.168.1.100 lcg serve
|
||||
```
|
||||
|
||||
### Настройка SSL сертификатов
|
||||
|
||||
```bash
|
||||
# Использовать собственные сертификаты
|
||||
LCG_SERVER_SSL_CERT_FILE=/path/to/cert.pem \
|
||||
LCG_SERVER_SSL_KEY_FILE=/path/to/key.pem \
|
||||
lcg serve
|
||||
|
||||
# Разрешить HTTP для внешних хостов
|
||||
LCG_SERVER_HOST=192.168.1.100 \
|
||||
LCG_SERVER_ALLOW_HTTP=true \
|
||||
lcg serve
|
||||
```
|
||||
|
||||
### Docker контейнер
|
||||
|
||||
```dockerfile
|
||||
FROM golang:1.21-alpine AS builder
|
||||
# ... build steps ...
|
||||
|
||||
FROM alpine:latest
|
||||
COPY --from=builder /app/lcg /usr/local/bin/
|
||||
ENV LCG_SERVER_HOST=0.0.0.0
|
||||
ENV LCG_SERVER_ALLOW_HTTP=false
|
||||
CMD ["lcg", "serve"]
|
||||
```
|
||||
|
||||
### Systemd сервис
|
||||
|
||||
```ini
|
||||
[Unit]
|
||||
Description=LCG Server
|
||||
After=network.target
|
||||
|
||||
[Service]
|
||||
Type=simple
|
||||
User=lcg
|
||||
WorkingDirectory=/opt/lcg
|
||||
ExecStart=/opt/lcg/lcg serve
|
||||
Environment=LCG_SERVER_HOST=0.0.0.0
|
||||
Environment=LCG_SERVER_ALLOW_HTTP=false
|
||||
Restart=always
|
||||
|
||||
[Install]
|
||||
WantedBy=multi-user.target
|
||||
```
|
||||
|
||||
## 🔧 Технические детали
|
||||
|
||||
### Генерация сертификата
|
||||
|
||||
Самоподписанный сертификат генерируется с:
|
||||
|
||||
- **Размер ключа**: 2048 бит RSA
|
||||
- **Срок действия**: 1 год
|
||||
- **Поддерживаемые хосты**: localhost, 127.0.0.1, указанный хост
|
||||
- **Использование**: Server Authentication
|
||||
|
||||
### Безопасные хосты
|
||||
|
||||
Следующие хосты считаются безопасными для HTTP:
|
||||
|
||||
- `localhost`
|
||||
- `127.0.0.1`
|
||||
- `::1` (IPv6 localhost)
|
||||
|
||||
### Проверка безопасности
|
||||
|
||||
```go
|
||||
// Проверка хоста
|
||||
if !ssl.IsSecureHost(host) {
|
||||
// Принудительно HTTPS
|
||||
useHTTPS = true
|
||||
}
|
||||
|
||||
// Проверка разрешения HTTP
|
||||
if config.AppConfig.Server.AllowHTTP {
|
||||
useHTTPS = false
|
||||
}
|
||||
```
|
||||
|
||||
## 🛠️ Отладка
|
||||
|
||||
### Проверка конфигурации
|
||||
|
||||
```bash
|
||||
# Показать текущую конфигурацию
|
||||
lcg config --full | jq '.server'
|
||||
|
||||
# Проверить SSL сертификаты
|
||||
ls -la ~/.config/lcg/config/server/ssl/
|
||||
|
||||
# Проверить переменные окружения
|
||||
env | grep LCG_SERVER
|
||||
```
|
||||
|
||||
### Логи безопасности
|
||||
|
||||
```bash
|
||||
# Запуск с отладкой
|
||||
LCG_SERVER_HOST=192.168.1.100 lcg serve --debug
|
||||
|
||||
# Проверка SSL
|
||||
openssl x509 -in ~/.config/lcg/config/server/ssl/cert.pem -text -noout
|
||||
```
|
||||
|
||||
## ⚠️ Важные замечания
|
||||
|
||||
### Безопасность
|
||||
|
||||
1. **Самоподписанные сертификаты** - браузеры будут показывать предупреждение
|
||||
2. **Продакшен** - используйте настоящие SSL сертификаты от CA
|
||||
3. **Сетевой доступ** - HTTPS защищает трафик, но не аутентификацию
|
||||
|
||||
### Производительность
|
||||
|
||||
1. **HTTPS** - небольшая нагрузка на CPU для шифрования
|
||||
2. **Сертификаты** - генерируются один раз, затем кэшируются
|
||||
3. **Память** - сертификаты загружаются в память при запуске
|
||||
|
||||
## 📚 Связанные файлы
|
||||
|
||||
- `config/config.go` - конфигурация безопасности
|
||||
- `ssl/ssl.go` - генерация и управление сертификатами
|
||||
- `serve/serve.go` - HTTP/HTTPS сервер
|
||||
- `SECURITY_FEATURES.md` - эта документация
|
||||
|
||||
---
|
||||
|
||||
**Результат**: Приложение теперь автоматически обеспечивает безопасность соединения в зависимости от конфигурации хоста!
|
||||
642
docs/USAGE_GUIDE.md
Normal file
642
docs/USAGE_GUIDE.md
Normal file
@@ -0,0 +1,642 @@
|
||||
# Руководство по использованию (USAGE_GUIDE)
|
||||
|
||||
## Что это
|
||||
|
||||
Linux Command GPT (`lcg`) преобразует описание на естественном языке в готовую команду для Linux или Windows. Инструмент автоматически определяет операционную систему и использует соответствующие промпты. Поддерживает сменные провайдеры LLM (Ollama или Proxy), управление системными промптами, историю запросов, сохранение результатов, HTTP сервер для просмотра результатов, аутентификацию, CSRF защиту, интерактивные действия над сгенерированной командой и деплой в Kubernetes.
|
||||
|
||||
## Требования
|
||||
|
||||
- Установленный Go (для сборки из исходников) или готовый бинарник.
|
||||
- Для функции «скопировать в буфер обмена»: установите `xclip` или `xsel`.
|
||||
|
||||
```bash
|
||||
# Debian/Ubuntu
|
||||
sudo apt-get install xclip
|
||||
# или
|
||||
sudo apt-get install xsel
|
||||
```
|
||||
|
||||
## Установка
|
||||
|
||||
Сборка из исходников:
|
||||
|
||||
```bash
|
||||
|
||||
git clone --depth 1 https://github.com/Direct-Dev-Ru/go-lcg.git ~/.linux-command-gpt
|
||||
cd ~/.linux-command-gpt
|
||||
go build -o lcg
|
||||
|
||||
# Добавьте бинарник в PATH
|
||||
ln -s ~/.linux-command-gpt/lcg ~/.local/bin
|
||||
```
|
||||
|
||||
Или скачайте готовый бинарник из раздела релизов.
|
||||
|
||||
## Быстрый старт
|
||||
|
||||
Простой запрос:
|
||||
|
||||
```bash
|
||||
lcg "хочу извлечь файл linux-command-gpt.tar.gz"
|
||||
```
|
||||
|
||||
Смешанный ввод: часть из файла, часть — текстом:
|
||||
|
||||
```bash
|
||||
lcg --file /path/to/context.txt "хочу вывести список директорий с помощью ls"
|
||||
```
|
||||
|
||||
После генерации вы увидите:
|
||||
|
||||
```text
|
||||
🤖 Запрос: <ваше описание>
|
||||
✅ Выполнено за X.XX сек
|
||||
|
||||
ВНИМАНИЕ: ОТВЕТ СФОРМИРОВАН ИИ. ТРЕБУЕТСЯ ПРОВЕРКА И КРИТИЧЕСКИЙ АНАЛИЗ. ВОЗМОЖНЫ ОШИБКИ И ГАЛЛЮЦИНАЦИИ.
|
||||
|
||||
📋 Команда:
|
||||
<сгенерированная команда>
|
||||
|
||||
Действия: (c)копировать, (s)сохранить, (r)перегенерировать, (e)выполнить, (v|vv|vvv)подробно, (n)ничего:
|
||||
```
|
||||
|
||||
### Что нового в 3.0.0
|
||||
|
||||
- **Аутентификация**: Добавлена система аутентификации с JWT токенами и HTTP-only cookies
|
||||
- **CSRF защита**: Полная защита от CSRF атак с токенами и middleware
|
||||
- **Безопасность**: Улучшенная безопасность с проверкой токенов и сессий
|
||||
- **Kubernetes деплой**: Полный набор манифестов для деплоя в Kubernetes с Traefik
|
||||
- **Flux CD**: GitOps конфигурация для автоматического деплоя
|
||||
- **Reverse Proxy**: Поддержка работы за reverse proxy с настройкой cookies
|
||||
- **Веб-интерфейс**: Улучшенный веб-интерфейс с современным дизайном
|
||||
- **Мониторинг**: Prometheus метрики и ServiceMonitor
|
||||
- **Масштабирование**: HPA для автоматического масштабирования
|
||||
- **Тестирование**: Инструменты для тестирования CSRF защиты
|
||||
|
||||
## Переменные окружения
|
||||
|
||||
Можно настроить поведение без изменения командной строки.
|
||||
|
||||
| Переменная | Значение по умолчанию | Назначение |
|
||||
| --- | --- | --- |
|
||||
| `LCG_HOST` | `http://192.168.87.108:11434/` | Базовый URL API провайдера (для Ollama поставьте, например, `http://localhost:11434/`). |
|
||||
| `LCG_PROXY_URL` | `/api/v1/protected/sberchat/chat` | Относительный путь эндпоинта для Proxy провайдера. |
|
||||
| `LCG_COMPLETIONS_PATH` | `api/chat` | Относительный путь эндпоинта для Ollama. |
|
||||
| `LCG_MODEL` | `hf.co/yandex/YandexGPT-5-Lite-8B-instruct-GGUF:Q4_K_M` | Имя модели у выбранного провайдера. |
|
||||
| `LCG_PROMPT` | См. значение в коде | Содержимое системного промпта по умолчанию. |
|
||||
| `LCG_API_KEY_FILE` | `.openai_api_key` | Файл с API‑ключом (для Ollama/Proxy не требуется). |
|
||||
| `LCG_RESULT_FOLDER` | `~/.config/lcg/gpt_results` | Папка для сохранения результатов. |
|
||||
| `LCG_PROVIDER` | `ollama` | Тип провайдера: `ollama` или `proxy`. |
|
||||
| `LCG_JWT_TOKEN` | пусто | JWT токен для `proxy` провайдера (альтернатива — файл `~/.proxy_jwt_token`). |
|
||||
| `LCG_PROMPT_ID` | `1` | ID системного промпта по умолчанию. |
|
||||
| `LCG_BROWSER_PATH` | пусто | Путь к браузеру для автооткрытия (`--browser`). |
|
||||
| `LCG_TIMEOUT` | `300` | Таймаут запроса в секундах. |
|
||||
| `LCG_RESULT_HISTORY` | `$(LCG_RESULT_FOLDER)/lcg_history.json` | Путь к JSON‑истории запросов. |
|
||||
| `LCG_PROMPT_FOLDER` | `~/.config/lcg/gpt_sys_prompts` | Папка для хранения системных промптов. |
|
||||
| `LCG_NO_HISTORY` | пусто | Если `1`/`true` — полностью отключает запись/обновление истории. |
|
||||
| `LCG_ALLOW_EXECUTION` | пусто | Если `1`/`true` — включает возможность выполнения команд через опцию `(e)` в меню действий. |
|
||||
| `LCG_SERVER_PORT` | `8080` | Порт для HTTP сервера просмотра результатов. |
|
||||
| `LCG_SERVER_HOST` | `localhost` | Хост для HTTP сервера просмотра результатов. |
|
||||
| `LCG_SERVER_REQUIRE_AUTH` | `false` | Требовать аутентификацию для доступа к веб-интерфейсу. |
|
||||
| `LCG_SERVER_PASSWORD` | `admin#123456` | Пароль для аутентификации. |
|
||||
| `LCG_COOKIE_SECURE` | `false` | Использовать Secure флаг для cookies (для HTTPS). |
|
||||
| `LCG_DOMAIN` | пусто | Домен для cookies (для reverse proxy). |
|
||||
| `LCG_COOKIE_PATH` | `/` | Путь для cookies (для reverse proxy). |
|
||||
| `LCG_COOKIE_TTL_HOURS` | `168` | Время жизни cookies в часах (по умолчанию 7 дней). |
|
||||
| `LCG_CSRF_SECRET` | пусто | Секрет для CSRF токенов (генерируется автоматически). |
|
||||
|
||||
Примеры настройки:
|
||||
|
||||
```bash
|
||||
# Ollama
|
||||
export LCG_PROVIDER=ollama
|
||||
export LCG_HOST=http://localhost:11434/
|
||||
export LCG_MODEL=codegeex4
|
||||
|
||||
# Proxy
|
||||
export LCG_PROVIDER=proxy
|
||||
export LCG_HOST=http://localhost:8080
|
||||
export LCG_MODEL=GigaChat-2
|
||||
export LCG_JWT_TOKEN=your_jwt_token_here
|
||||
|
||||
# Аутентификация и безопасность
|
||||
export LCG_SERVER_REQUIRE_AUTH=true
|
||||
export LCG_SERVER_PASSWORD=my_secure_password
|
||||
export LCG_COOKIE_SECURE=false
|
||||
export LCG_DOMAIN=.example.com
|
||||
export LCG_COOKIE_PATH=/lcg
|
||||
export LCG_COOKIE_TTL_HOURS=72 # 3 дня
|
||||
```
|
||||
|
||||
## Базовый синтаксис
|
||||
|
||||
```bash
|
||||
lcg [глобальные опции] <описание команды>
|
||||
```
|
||||
|
||||
Глобальные опции:
|
||||
|
||||
- `--file, -f string` — прочитать часть запроса из файла и добавить к описанию.
|
||||
- `--sys, -s string` — системный промпт (содержимое или ID как строка). Если не задан, используется `--prompt-id` или `LCG_PROMPT`.
|
||||
- `--prompt-id, --pid int` — ID системного промпта (1–5 для стандартных, либо ваш кастомный ID).
|
||||
- `--timeout, -t int` — таймаут запроса в секундах (по умолчанию 120; через `LCG_TIMEOUT` — 300).
|
||||
- `--no-history, --nh` — отключить запись/обновление истории для текущего запуска.
|
||||
- `--debug, -d` — показать отладочную информацию (параметры запроса и промпты).
|
||||
- `--version, -v` — вывести версию.
|
||||
- `--help, -h` — помощь.
|
||||
|
||||
## Подкоманды
|
||||
|
||||
- `lcg update-key` (`-u`): обновить API‑ключ. Для `ollama` и `proxy` не требуется — команда сообщит, что ключ не нужен.
|
||||
- `lcg delete-key` (`-d`): удалить API‑ключ (не требуется для `ollama`/`proxy`).
|
||||
- `lcg update-jwt` (`-j`): обновить JWT для `proxy`. Токен будет сохранён в `~/.proxy_jwt_token` (права `0600`).
|
||||
- `lcg delete-jwt` (`-dj`): удалить JWT файл для `proxy`.
|
||||
- `lcg models` (`-m`): показать доступные модели у текущего провайдера.
|
||||
- `lcg health` (`-he`): проверить доступность API провайдера.
|
||||
- `lcg config` (`-co`): показать текущую конфигурацию и состояние JWT.
|
||||
- `lcg history list` (`-l`): показать историю из JSON‑файла (`LCG_RESULT_HISTORY`).
|
||||
- `lcg history view <id>` (`-v`): показать запись истории по `index`.
|
||||
- `lcg history delete <id>` (`-d`): удалить запись истории по `index` (с перенумерацией).
|
||||
- Флаг `--no-history` (`-nh`) отключает запись истории для текущего запуска и имеет приоритет над `LCG_NO_HISTORY`.
|
||||
- `lcg prompts ...` (`-p`): управление системными промптами:
|
||||
- `lcg prompts list` (`-l`) — список всех промптов с содержимым в читаемом формате.
|
||||
- `lcg prompts list --full` (`-f`) — полный вывод содержимого без обрезки длинных строк.
|
||||
- `lcg prompts add` (`-a`) — добавить пользовательский промпт (по шагам в интерактиве).
|
||||
- `lcg prompts delete <id>` (`-d`) — удалить пользовательский промпт по ID (>5).
|
||||
- `lcg test-prompt <prompt-id> <описание>` (алиас: `tp`): показать детали выбранного системного промпта и протестировать его на заданном описании.
|
||||
- `lcg serve`: запустить HTTP сервер для просмотра сохраненных результатов:
|
||||
- `--port, -p` — порт сервера (по умолчанию из `LCG_SERVER_PORT`)
|
||||
- `--host, -H` — хост сервера (по умолчанию из `LCG_SERVER_HOST`)
|
||||
- `--browser, -b` — открыть браузер автоматически после старта
|
||||
- `--require-auth` — включить аутентификацию (переопределяет `LCG_SERVER_REQUIRE_AUTH`)
|
||||
- `--password` — пароль для аутентификации (переопределяет `LCG_SERVER_PASSWORD`)
|
||||
|
||||
### Подробные объяснения (v/vv/vvv)
|
||||
|
||||
- `v` — кратко: что делает команда и ключевые опции, без альтернатив.
|
||||
- `vv` — средне: назначение, основные ключи, 1–2 примера, кратко об альтернативах.
|
||||
- `vvv` — максимально подробно: полный разбор ключей, сценариев, примеры, разбор альтернатив и сравнений.
|
||||
|
||||
После вывода подробного объяснения доступно вторичное меню: `Действия: (c)копировать, (s)сохранить, (r)перегенерировать, (n)ничего:`
|
||||
|
||||
## Провайдеры
|
||||
|
||||
### Ollama (`LCG_PROVIDER=ollama`)
|
||||
|
||||
- Требуется запущенный Ollama API (`LCG_HOST`, например `http://localhost:11434/`).
|
||||
- `models`, `health` и генерация используют REST Ollama (`/api/tags`, `/api/chat`).
|
||||
- API‑ключ не нужен.
|
||||
|
||||
### Proxy (`LCG_PROVIDER=proxy`)
|
||||
|
||||
- Требуется доступ к прокси‑серверу (`LCG_HOST`) и JWT (`LCG_JWT_TOKEN` или файл `~/.proxy_jwt_token`).
|
||||
- Основные эндпоинты: `/api/v1/protected/sberchat/chat` и `/api/v1/protected/sberchat/health`.
|
||||
- Команды `update-jwt`/`delete-jwt` помогают управлять токеном локально.
|
||||
|
||||
## Рекомендации по выбору провайдера, модели и таймаутов
|
||||
|
||||
### Выбор провайдера
|
||||
|
||||
- **Ollama**: выбирайте для локальной работы (офлайн/частные данные), когда есть доступ к GPU/CPU и готовность поддерживать локальные модели. Минимальные задержки сети, полная приватность.
|
||||
- **Proxy**: выбирайте для централизованного хостинга моделей, более мощных/обновляемых моделей, простоты развёртывания у команды. Обязательно используйте HTTPS и корректный `JWT`.
|
||||
|
||||
### Выбор модели
|
||||
|
||||
- Для генерации Linux‑команд подходят компактные «code»/«general» модели (по умолчанию `codegeex4`).
|
||||
- Для подробных объяснений (`v`/`vv`/`vvv`) точность выше у более крупных моделей (например, семейства LLaMA/Qwen/GigaChat), но они медленнее.
|
||||
- Русскоязычные запросы часто лучше обрабатываются в `GigaChat-*` (режим proxy), английские — в популярных open‑source (Ollama).
|
||||
- Балансируйте: скорость (малые модели) vs качество (крупные модели). Тестируйте `lcg models` и подбирайте `LCG_MODEL`.
|
||||
|
||||
### Таймауты
|
||||
|
||||
- Стартовые значения: локально с Ollama — **120–300 сек**, удалённый proxy — **300–600 сек**.
|
||||
- Увеличьте таймаут для больших моделей/длинных запросов. Флаг `--timeout` перекрывает `LCG_TIMEOUT` на время запуска.
|
||||
- Если часто видите таймауты — проверьте здоровье API (`lcg health`) и сетевую доступность `LCG_HOST`.
|
||||
|
||||
### Практические советы
|
||||
|
||||
- Если данные чувствительные — используйте Ollama локально и `--no-history` при необходимости.
|
||||
- Для «черновой» команды начните с `Ollama + небольшая модель`; для «объяснений и альтернатив» используйте более крупную модель/Proxy.
|
||||
- Не вставляйте секреты в запросы. Перед выполнением (`e`) проверяйте команду вручную.
|
||||
- Для структуры API см. `API_CONTRACT.md` (эндпоинты и форматы запросов/ответов).
|
||||
|
||||
## Поддержка операционных систем
|
||||
|
||||
### Автоматическое определение ОС
|
||||
|
||||
Приложение автоматически определяет операционную систему и использует соответствующие промпты:
|
||||
|
||||
- **Linux/Unix системы** (включая macOS): используются промпты для Linux команд
|
||||
- **Windows**: используются промпты для Windows команд (PowerShell, CMD, Batch)
|
||||
|
||||
### Промпты для Windows
|
||||
|
||||
На Windows системах доступны следующие встроенные промпты:
|
||||
|
||||
| ID | Name | Описание |
|
||||
| --- | --- | --- |
|
||||
| 1 | windows-command | Основной промпт для генерации Windows команд |
|
||||
| 2 | windows-command-with-explanation | Промпт с подробным объяснением команд |
|
||||
| 3 | windows-command-safe | Безопасный анализ команд с предупреждениями |
|
||||
| 4 | windows-command-verbose | Подробный анализ с техническими деталями |
|
||||
| 5 | windows-command-simple | Простое и понятное объяснение |
|
||||
|
||||
### Примеры использования на Windows
|
||||
|
||||
```cmd
|
||||
# PowerShell команды
|
||||
lcg "хочу получить список всех процессов"
|
||||
lcg "показать информацию о дисках"
|
||||
|
||||
# CMD команды
|
||||
lcg "создать папку test и перейти в неё"
|
||||
lcg "найти все файлы .txt в текущей директории"
|
||||
```
|
||||
|
||||
## Системные промпты
|
||||
|
||||
### Управление промптами
|
||||
|
||||
Системные промпты хранятся в папке, указанной в переменной `LCG_PROMPT_FOLDER` (по умолчанию: `~/.config/lcg/gpt_sys_prompts`).
|
||||
|
||||
**Логика загрузки:**
|
||||
|
||||
- Если файл `sys_prompts` **не существует** — создается файл с системными промптами (ID 1–5) и промптами подробности (ID 6–8)
|
||||
- Если файл `sys_prompts` **существует** — загружаются все промпты из файла
|
||||
- **Промпты подробности** (v/vv/vvv) сохраняются в том же файле с ID 6, 7, 8
|
||||
|
||||
### Встроенные промпты (ID 1–5)
|
||||
|
||||
Промпты автоматически выбираются в зависимости от операционной системы:
|
||||
|
||||
**Linux/Unix системы:**
|
||||
| ID | Name | Описание |
|
||||
| --- | --- | --- |
|
||||
| 1 | linux-command | «Ответь только Linux‑командой, без форматирования и объяснений». |
|
||||
| 2 | linux-command-with-explanation | Сгенерируй команду и кратко объясни, что она делает (формат: COMMAND: explanation). |
|
||||
| 3 | linux-command-safe | Безопасные команды (без потери данных). Вывод — только команда. |
|
||||
| 4 | linux-command-verbose | Команда с подробными объяснениями флагов и альтернатив. |
|
||||
| 5 | linux-command-simple | Простые команды, избегать сложных опций. |
|
||||
|
||||
**Windows системы:**
|
||||
| ID | Name | Описание |
|
||||
| --- | --- | --- |
|
||||
| 1 | windows-command | «Ответь только Windows‑командой, без форматирования и объяснений». |
|
||||
| 2 | windows-command-with-explanation | Сгенерируй команду и кратко объясни, что она делает (формат: COMMAND: explanation). |
|
||||
| 3 | windows-command-safe | Безопасные команды (без потери данных). Вывод — только команда. |
|
||||
| 4 | windows-command-verbose | Команда с подробными объяснениями флагов и альтернатив. |
|
||||
| 5 | windows-command-simple | Простые команды, избегать сложных опций. |
|
||||
|
||||
### Промпты подробности (ID 6–8)
|
||||
|
||||
| ID | Name | Описание |
|
||||
| --- | --- | --- |
|
||||
| 6 | verbose-v | Подробный режим (v) - детальное объяснение команды |
|
||||
| 7 | verbose-vv | Очень подробный режим (vv) - исчерпывающее объяснение с альтернативами |
|
||||
| 8 | verbose-vvv | Максимально подробный режим (vvv) - полное руководство с примерами |
|
||||
|
||||
### Веб-интерфейс управления
|
||||
|
||||
Через HTTP сервер (`lcg serve`) доступно полное управление промптами:
|
||||
|
||||
- **Просмотр всех промптов** (встроенных и пользовательских)
|
||||
- **Редактирование любых промптов** (включая встроенные)
|
||||
- **Добавление новых промптов**
|
||||
- **Удаление промптов**
|
||||
- **Автоматическое сохранение** в файл `sys_prompts`
|
||||
|
||||
## Сохранение результатов
|
||||
|
||||
При выборе действия `s` ответ сохраняется в `LCG_RESULT_FOLDER` (по умолчанию: `~/.config/lcg/gpt_results`) в файл вида:
|
||||
|
||||
```text
|
||||
gpt_request_<MODEL>_YYYY-MM-DD_HH-MM-SS.md
|
||||
```
|
||||
|
||||
## HTTP сервер для просмотра результатов
|
||||
|
||||
Команда `lcg serve` запускает веб-сервер для удобного просмотра всех сохраненных результатов:
|
||||
|
||||
```bash
|
||||
# Запуск с настройками по умолчанию
|
||||
lcg serve
|
||||
|
||||
# Запуск на другом порту
|
||||
lcg serve --port 9090
|
||||
|
||||
# Запуск на другом хосте
|
||||
lcg serve --host 0.0.0.0 --port 8080
|
||||
|
||||
# Автооткрытие браузера (опционально)
|
||||
lcg serve --browser
|
||||
|
||||
# Использование переменных окружения
|
||||
export LCG_SERVER_PORT=3000
|
||||
export LCG_SERVER_HOST=0.0.0.0
|
||||
lcg serve
|
||||
```
|
||||
|
||||
### Возможности веб-интерфейса
|
||||
|
||||
- **Главная страница** (`/`) — отображает все сохраненные файлы с превью
|
||||
- **Статистика** — количество файлов, файлы за последние 7 дней
|
||||
- **Просмотр файлов** (`/file/{filename}`) — отображение содержимого конкретного файла
|
||||
- **Современный дизайн** — адаптивный интерфейс с карточками файлов
|
||||
- **Сортировка** — файлы отсортированы по дате изменения (новые сверху)
|
||||
- **Превью содержимого** — первые 200 символов каждого файла
|
||||
- **Аутентификация** — защищенный доступ с JWT токенами
|
||||
- **CSRF защита** — защита от межсайтовых атак
|
||||
- **История запросов** (`/history`) — просмотр истории всех запросов
|
||||
- **Управление промптами** (`/prompts`) — редактирование системных промптов
|
||||
- **Выполнение команд** (`/run`) — интерактивное выполнение команд
|
||||
- **Безопасность** — HTTP-only cookies, проверка токенов
|
||||
|
||||
Структура файла (команда):
|
||||
|
||||
- `# <заголовок>` — H1, это ваш запрос, при длине >120 символов обрезается до 116 + `...`.
|
||||
- `## Prompt` — запрос (включая системный промпт).
|
||||
- `## Response` — сгенерированная команда.
|
||||
|
||||
Структура файла (подробное объяснение):
|
||||
|
||||
- `# <заголовок>` — H1, ваш исходный запрос (с тем же правилом обрезки).
|
||||
- `## Prompt` — исходный запрос.
|
||||
- `## Command` — первая сгенерированная команда.
|
||||
- `## Explanation and Alternatives (model: <MODEL>)` — подробное объяснение и альтернативы.
|
||||
|
||||
### Браузер
|
||||
|
||||
- По умолчанию UI не открывается автоматически. Для автооткрытия используйте `--browser`.
|
||||
- Путь к конкретному браузеру можно задать переменной `LCG_BROWSER_PATH`.
|
||||
|
||||
## Выполнение сгенерированной команды
|
||||
|
||||
Действие `e` запустит команду через `bash -c`. Перед запуском потребуется подтверждение `y/yes`. Всегда проверяйте команду вручную, особенно при операциях с файлами и сетью.
|
||||
|
||||
## Примеры
|
||||
|
||||
1. Базовый запрос с Ollama:
|
||||
|
||||
```bash
|
||||
export LCG_PROVIDER=ollama
|
||||
export LCG_HOST=http://localhost:11434/
|
||||
export LCG_MODEL=codegeex4
|
||||
|
||||
lcg "хочу извлечь linux-command-gpt.tar.gz"
|
||||
```
|
||||
|
||||
1. Полный ответ от LLM (пример настройки):
|
||||
|
||||
```bash
|
||||
LCG_PROMPT='Provide full response' LCG_MODEL=codellama:13b \
|
||||
lcg 'i need bash script to execute command by ssh on array of hosts'
|
||||
```
|
||||
|
||||
1. Proxy‑провайдер:
|
||||
|
||||
```bash
|
||||
export LCG_PROVIDER=proxy
|
||||
export LCG_HOST=http://localhost:8080
|
||||
export LCG_MODEL=GigaChat-2
|
||||
export LCG_JWT_TOKEN=your_jwt_token_here
|
||||
|
||||
lcg "I want to extract linux-command-gpt.tar.gz file"
|
||||
|
||||
lcg health
|
||||
lcg config
|
||||
lcg update-jwt
|
||||
```
|
||||
|
||||
1. Работа с файлами и промптами:
|
||||
|
||||
```bash
|
||||
lcg --file ./context.txt "сгенерируй команду jq для выборки поля name"
|
||||
lcg --prompt-id 2 "удали все *.tmp в текущем каталоге"
|
||||
lcg --sys 1 "показать размер каталога в человеко‑читаемом виде"
|
||||
```
|
||||
|
||||
1. Диагностика и модели:
|
||||
|
||||
```bash
|
||||
lcg health
|
||||
lcg models
|
||||
```
|
||||
|
||||
1. HTTP сервер для просмотра результатов:
|
||||
|
||||
```bash
|
||||
# Запуск сервера
|
||||
lcg serve
|
||||
|
||||
# Запуск на другом порту
|
||||
lcg serve --port 9090
|
||||
|
||||
# Запуск на всех интерфейсах
|
||||
lcg serve --host 0.0.0.0 --port 8080
|
||||
|
||||
# Запуск с аутентификацией
|
||||
lcg serve --require-auth --password my_secure_password
|
||||
|
||||
# Запуск с переменными окружения
|
||||
export LCG_SERVER_REQUIRE_AUTH=true
|
||||
export LCG_SERVER_PASSWORD=admin#123456
|
||||
lcg serve
|
||||
```
|
||||
|
||||
## История
|
||||
|
||||
`lcg history` выводит историю из JSON‑файла (`LCG_RESULT_HISTORY`), сохраняется между запусками:
|
||||
|
||||
```bash
|
||||
lcg history list
|
||||
```
|
||||
|
||||
## Типичные проблемы
|
||||
|
||||
- Нет ответа/таймаут: увеличьте `--timeout` или `LCG_TIMEOUT`, проверьте `LCG_HOST` и сетевую доступность.
|
||||
- `health` падает: проверьте, что провайдер запущен и URL верный; для `proxy` — что JWT валиден (`lcg config`).
|
||||
- Копирование не работает: установите `xclip` или `xsel`.
|
||||
- Нет допуска к папке результатов: настройте `LCG_RESULT_FOLDER` или права доступа.
|
||||
- Для `ollama`/`proxy` API‑ключ не нужен; команды `update-key`/`delete-key` просто уведомят об этом.
|
||||
- HTTP сервер не запускается: проверьте, что порт свободен, используйте `--port` для смены порта.
|
||||
- Веб-интерфейс не отображает файлы: убедитесь, что в `LCG_RESULT_FOLDER` есть `.md` файлы.
|
||||
- **Аутентификация не работает**: проверьте `LCG_SERVER_REQUIRE_AUTH=true` и правильность пароля.
|
||||
- **CSRF ошибки**: убедитесь, что токены передаются в заголовках `X-CSRF-Token`.
|
||||
- **Cookies не сохраняются**: проверьте настройки `LCG_DOMAIN` и `LCG_COOKIE_PATH` для reverse proxy.
|
||||
- **Kubernetes деплой не работает**: проверьте права доступа к кластеру и наличие всех манифестов.
|
||||
|
||||
## JSON‑история запросов
|
||||
|
||||
- Путь задаётся `LCG_RESULT_HISTORY` (по умолчанию: `$(LCG_RESULT_FOLDER)/lcg_history.json`).
|
||||
- Формат — массив объектов:
|
||||
|
||||
```json
|
||||
[
|
||||
{
|
||||
"index": 1,
|
||||
"command": "хочу извлечь linux-command-gpt.tar.gz",
|
||||
"response": "tar -xvzf linux-command-gpt.tar.gz",
|
||||
"explanation": "... если запрашивалось v/vv/vvv ...",
|
||||
"system_prompt": "Reply with linux command and nothing else ...",
|
||||
"timestamp": "2025-10-19T13:05:39.000000000Z"
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
- Перед новым запросом, если такой уже встречался, будет предложено вывести сохранённый результат из истории с указанием даты.
|
||||
- Сохранение в файл истории выполняется автоматически после завершения работы (любое действие, кроме `v|vv|vvv`).
|
||||
- При совпадении запроса в истории спрашивается о перезаписи записи.
|
||||
- Подкоманды истории работают по полю `index` внутри JSON (а не по позиции массива): используйте `lcg history view <index>` и `lcg history delete <index>`.
|
||||
- При показе из истории запрос к API не выполняется: выводится CAPS‑предупреждение и далее доступно обычное меню действий над командой/объяснением.
|
||||
|
||||
## Лицензия и исходники
|
||||
|
||||
См. README и репозиторий проекта. Предложения и баг‑репорты приветствуются в Issues.
|
||||
|
||||
## Доступ к локальному API
|
||||
|
||||
### Основные эндпоинты
|
||||
|
||||
- `POST /api/execute` — выполнение запросов к LLM
|
||||
- `POST /api/save-result` — сохранение результатов
|
||||
- `POST /api/add-to-history` — добавление в историю
|
||||
- `GET /api/login` — страница аутентификации
|
||||
- `POST /api/login` — аутентификация
|
||||
- `POST /api/logout` — выход из системы
|
||||
- `GET /metrics` — Prometheus метрики
|
||||
|
||||
### Примеры использования
|
||||
|
||||
```bash
|
||||
# Запустить сервер
|
||||
lcg serve
|
||||
|
||||
# Выполнить запрос (без аутентификации)
|
||||
curl -X POST http://localhost:8080/api/execute \
|
||||
-H "Content-Type: application/json" \
|
||||
-A curl \
|
||||
-d '{"prompt": "create directory test", "verbose": "vv"}'
|
||||
|
||||
# Аутентификация
|
||||
curl -X POST http://localhost:8080/api/login \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"username": "admin", "password": "admin#123456"}'
|
||||
|
||||
# Выполнение с CSRF токеном
|
||||
curl -X POST http://localhost:8080/api/execute \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "X-CSRF-Token: your_csrf_token" \
|
||||
-H "Cookie: auth_token=your_jwt_token" \
|
||||
-d '{"prompt": "create directory test"}'
|
||||
```
|
||||
|
||||
Подробности и примеры: `API_GUIDE.md`.
|
||||
|
||||
## Kubernetes деплой
|
||||
|
||||
### Быстрый деплой
|
||||
|
||||
```bash
|
||||
# Переход в папку деплоя
|
||||
cd deploy
|
||||
|
||||
# Полный деплой (сборка + деплой + проверка)
|
||||
./full-deploy.sh
|
||||
|
||||
# Или поэтапно
|
||||
./build.sh lcg latest
|
||||
./deploy.sh
|
||||
./health-check.sh
|
||||
```
|
||||
|
||||
### Использование Make
|
||||
|
||||
```bash
|
||||
# Справка
|
||||
make help
|
||||
|
||||
# Сборка и деплой
|
||||
make build
|
||||
make deploy
|
||||
|
||||
# Мониторинг
|
||||
make status
|
||||
make logs
|
||||
make monitor
|
||||
|
||||
# Удаление
|
||||
make undeploy
|
||||
```
|
||||
|
||||
### Flux CD (GitOps)
|
||||
|
||||
```bash
|
||||
# Настройка Flux CD
|
||||
cd deploy/flux
|
||||
./setup-flux.sh
|
||||
|
||||
# Создание Kustomization
|
||||
./create_kustomization.sh
|
||||
|
||||
# Мониторинг
|
||||
kubectl get kustomization lcg -n flux-system
|
||||
```
|
||||
|
||||
### Конфигурация для reverse proxy
|
||||
|
||||
```bash
|
||||
# Настройка для работы за reverse proxy
|
||||
export LCG_SERVER_REQUIRE_AUTH=true
|
||||
export LCG_SERVER_ALLOW_HTTP=true
|
||||
export LCG_DOMAIN=.example.com
|
||||
export LCG_COOKIE_PATH=/lcg
|
||||
export LCG_COOKIE_SECURE=false
|
||||
|
||||
# Запуск
|
||||
./lcg serve -H 0.0.0.0 -p 8080
|
||||
```
|
||||
|
||||
### Мониторинг и безопасность
|
||||
|
||||
- **Prometheus метрики**: `/metrics` endpoint
|
||||
- **Health checks**: автоматические проверки готовности
|
||||
- **HPA**: автоматическое масштабирование (2-10 replicas)
|
||||
- **CSRF защита**: токены для всех POST запросов
|
||||
- **Аутентификация**: JWT токены в HTTP-only cookies
|
||||
- **Security context**: non-root пользователь, минимальные права
|
||||
|
||||
Подробности: `deploy/README.md` и `deploy/flux/README.md`.
|
||||
|
||||
## Тестирование CSRF защиты
|
||||
|
||||
### Автоматическое тестирование
|
||||
|
||||
```bash
|
||||
# Запуск тестов CSRF защиты
|
||||
./test_csrf.sh
|
||||
|
||||
# Проверка результатов
|
||||
echo "Проверьте вывод на наличие ошибок 403 Forbidden"
|
||||
```
|
||||
|
||||
### Ручное тестирование
|
||||
|
||||
```bash
|
||||
# Откройте csrf_test.html в браузере
|
||||
open csrf_test.html
|
||||
|
||||
# Или используйте curl для тестирования
|
||||
curl -X POST http://localhost:8080/api/execute \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"prompt": "test"}' \
|
||||
-v
|
||||
```
|
||||
|
||||
### Демонстрация уязвимости
|
||||
|
||||
```bash
|
||||
# Откройте csrf_demo.html для демонстрации атаки
|
||||
open csrf_demo.html
|
||||
```
|
||||
|
||||
Подробности: `CSRF_TESTING_GUIDE.md`.
|
||||
205
docs/VALIDATION_CONFIG.md
Normal file
205
docs/VALIDATION_CONFIG.md
Normal file
@@ -0,0 +1,205 @@
|
||||
# 🔧 Конфигурация валидации длины полей
|
||||
|
||||
## 📋 Переменные окружения
|
||||
|
||||
Все настройки валидации можно настроить через переменные окружения:
|
||||
|
||||
### Основные лимиты
|
||||
|
||||
| Переменная | Описание | По умолчанию |
|
||||
|------------|----------|--------------|
|
||||
| `LCG_MAX_SYSTEM_PROMPT_LENGTH` | Максимальная длина системного промпта | 1000 |
|
||||
| `LCG_MAX_USER_MESSAGE_LENGTH` | Максимальная длина пользовательского сообщения | 2000 |
|
||||
| `LCG_MAX_PROMPT_NAME_LENGTH` | Максимальная длина названия промпта | 200 |
|
||||
| `LCG_MAX_PROMPT_DESC_LENGTH` | Максимальная длина описания промпта | 500 |
|
||||
| `LCG_MAX_COMMAND_LENGTH` | Максимальная длина команды/ответа | 2000 |
|
||||
| `LCG_MAX_EXPLANATION_LENGTH` | Максимальная длина объяснения | 2000 |
|
||||
|
||||
## 🚀 Примеры использования
|
||||
|
||||
### Установка через переменные окружения
|
||||
|
||||
```bash
|
||||
# Увеличить лимит системного промпта до 2к символов
|
||||
export LCG_MAX_SYSTEM_PROMPT_LENGTH=2000
|
||||
|
||||
# Уменьшить лимит пользовательского сообщения до 1к символов
|
||||
export LCG_MAX_USER_MESSAGE_LENGTH=1000
|
||||
|
||||
# Увеличить лимит названия промпта до 500 символов
|
||||
export LCG_MAX_PROMPT_NAME_LENGTH=500
|
||||
```
|
||||
|
||||
### Установка в .env файле
|
||||
|
||||
```bash
|
||||
# .env файл
|
||||
LCG_MAX_SYSTEM_PROMPT_LENGTH=2000
|
||||
LCG_MAX_USER_MESSAGE_LENGTH=1500
|
||||
LCG_MAX_PROMPT_NAME_LENGTH=300
|
||||
LCG_MAX_PROMPT_DESC_LENGTH=1000
|
||||
LCG_MAX_COMMAND_LENGTH=3000
|
||||
LCG_MAX_EXPLANATION_LENGTH=5000
|
||||
```
|
||||
|
||||
### Установка в systemd сервисе
|
||||
|
||||
```ini
|
||||
[Unit]
|
||||
Description=Linux Command GPT
|
||||
After=network.target
|
||||
|
||||
[Service]
|
||||
Type=simple
|
||||
User=lcg
|
||||
WorkingDirectory=/opt/lcg
|
||||
ExecStart=/opt/lcg/lcg serve
|
||||
Environment=LCG_MAX_SYSTEM_PROMPT_LENGTH=2000
|
||||
Environment=LCG_MAX_USER_MESSAGE_LENGTH=1500
|
||||
Environment=LCG_MAX_PROMPT_NAME_LENGTH=300
|
||||
Restart=always
|
||||
|
||||
[Install]
|
||||
WantedBy=multi-user.target
|
||||
```
|
||||
|
||||
### Установка в Docker
|
||||
|
||||
```dockerfile
|
||||
FROM golang:1.21-alpine AS builder
|
||||
# ... build steps ...
|
||||
|
||||
FROM alpine:latest
|
||||
COPY --from=builder /app/lcg /usr/local/bin/
|
||||
ENV LCG_MAX_SYSTEM_PROMPT_LENGTH=2000
|
||||
ENV LCG_MAX_USER_MESSAGE_LENGTH=1500
|
||||
CMD ["lcg", "serve"]
|
||||
```
|
||||
|
||||
```yaml
|
||||
# docker-compose.yml
|
||||
version: '3.8'
|
||||
services:
|
||||
lcg:
|
||||
image: lcg:latest
|
||||
environment:
|
||||
- LCG_MAX_SYSTEM_PROMPT_LENGTH=2000
|
||||
- LCG_MAX_USER_MESSAGE_LENGTH=1500
|
||||
- LCG_MAX_PROMPT_NAME_LENGTH=300
|
||||
ports:
|
||||
- "8080:8080"
|
||||
```
|
||||
|
||||
## 🔍 Где применяется валидация
|
||||
|
||||
### 1. Консольная часть (main.go)
|
||||
- ✅ Валидация пользовательского сообщения
|
||||
- ✅ Валидация системного промпта
|
||||
- ✅ Цветные сообщения об ошибках
|
||||
|
||||
### 2. API эндпоинты
|
||||
- ✅ `/execute` - валидация промпта и системного промпта
|
||||
- ✅ `/api/save-result` - валидация всех полей
|
||||
- ✅ `/api/add-to-history` - валидация всех полей
|
||||
|
||||
### 3. Веб-интерфейс
|
||||
- ✅ Страница выполнения - валидация в JavaScript и на сервере
|
||||
- ✅ Управление промптами - валидация всех полей формы
|
||||
|
||||
### 4. JavaScript валидация
|
||||
- ✅ Клиентская валидация перед отправкой
|
||||
- ✅ Динамические лимиты из конфигурации
|
||||
- ✅ Понятные сообщения об ошибках
|
||||
|
||||
## 🛠️ Технические детали
|
||||
|
||||
### Структура конфигурации
|
||||
|
||||
```go
|
||||
type ValidationConfig struct {
|
||||
MaxSystemPromptLength int // LCG_MAX_SYSTEM_PROMPT_LENGTH
|
||||
MaxUserMessageLength int // LCG_MAX_USER_MESSAGE_LENGTH
|
||||
MaxPromptNameLength int // LCG_MAX_PROMPT_NAME_LENGTH
|
||||
MaxPromptDescLength int // LCG_MAX_PROMPT_DESC_LENGTH
|
||||
MaxCommandLength int // LCG_MAX_COMMAND_LENGTH
|
||||
MaxExplanationLength int // LCG_MAX_EXPLANATION_LENGTH
|
||||
}
|
||||
```
|
||||
|
||||
### Функции валидации
|
||||
|
||||
```go
|
||||
// Основные функции
|
||||
validation.ValidateSystemPrompt(prompt)
|
||||
validation.ValidateUserMessage(message)
|
||||
validation.ValidatePromptName(name)
|
||||
validation.ValidatePromptDescription(description)
|
||||
validation.ValidateCommand(command)
|
||||
validation.ValidateExplanation(explanation)
|
||||
|
||||
// Вспомогательные функции
|
||||
validation.TruncateSystemPrompt(prompt)
|
||||
validation.TruncateUserMessage(message)
|
||||
validation.FormatLengthInfo(systemPrompt, userMessage)
|
||||
```
|
||||
|
||||
### Обработка ошибок
|
||||
|
||||
- **API**: HTTP 400 с JSON сообщением об ошибке
|
||||
- **Веб-интерфейс**: HTTP 400 с текстовым сообщением
|
||||
- **Консоль**: Цветные сообщения об ошибках
|
||||
- **JavaScript**: Alert с предупреждением
|
||||
|
||||
## 📝 Примеры сообщений об ошибках
|
||||
|
||||
```
|
||||
❌ Ошибка: system_prompt: системный промпт слишком длинный: 1500 символов (максимум 1000)
|
||||
❌ Ошибка: user_message: пользовательское сообщение слишком длинное: 2500 символов (максимум 2000)
|
||||
❌ Ошибка: prompt_name: название промпта слишком длинное: 300 символов (максимум 200)
|
||||
```
|
||||
|
||||
## 🔄 Миграция с жестко заданных значений
|
||||
|
||||
Если ранее использовались жестко заданные значения в коде, теперь они автоматически заменяются на значения из конфигурации:
|
||||
|
||||
```go
|
||||
// Старый код
|
||||
if len(prompt) > 2000 {
|
||||
return errors.New("too long")
|
||||
}
|
||||
|
||||
// Новый код
|
||||
if err := validation.ValidateSystemPrompt(prompt); err != nil {
|
||||
return err
|
||||
}
|
||||
```
|
||||
|
||||
## 🎯 Рекомендации по настройке
|
||||
|
||||
### Для разработки
|
||||
```bash
|
||||
export LCG_MAX_SYSTEM_PROMPT_LENGTH=2000
|
||||
export LCG_MAX_USER_MESSAGE_LENGTH=2000
|
||||
export LCG_MAX_PROMPT_NAME_LENGTH=200
|
||||
export LCG_MAX_PROMPT_DESC_LENGTH=500
|
||||
```
|
||||
|
||||
### Для продакшена
|
||||
```bash
|
||||
export LCG_MAX_SYSTEM_PROMPT_LENGTH=1000
|
||||
export LCG_MAX_USER_MESSAGE_LENGTH=1500
|
||||
export LCG_MAX_PROMPT_NAME_LENGTH=100
|
||||
export LCG_MAX_PROMPT_DESC_LENGTH=300
|
||||
```
|
||||
|
||||
### Для высоконагруженных систем
|
||||
```bash
|
||||
export LCG_MAX_SYSTEM_PROMPT_LENGTH=500
|
||||
export LCG_MAX_USER_MESSAGE_LENGTH=1000
|
||||
export LCG_MAX_PROMPT_NAME_LENGTH=50
|
||||
export LCG_MAX_PROMPT_DESC_LENGTH=200
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Примечание**: Все значения настраиваются через переменные окружения и применяются ко всем частям приложения (консоль, веб-интерфейс, API).
|
||||
63
docs/VERBOSE_PROMPT_EDITING.md
Normal file
63
docs/VERBOSE_PROMPT_EDITING.md
Normal file
@@ -0,0 +1,63 @@
|
||||
# Редактирование промптов подробности
|
||||
|
||||
## 🎯 Реализованная функциональность
|
||||
|
||||
### ✅ **Что добавлено:**
|
||||
|
||||
1. **Функция редактирования в JavaScript:**
|
||||
- `editVerbosePrompt(mode, content)` - открывает форму редактирования для промптов подробности
|
||||
- Автоматически заполняет поля формы данными промпта
|
||||
- Показывает режим в заголовке формы
|
||||
|
||||
2. **Обработчик на сервере:**
|
||||
- `handleEditVerbosePrompt()` - новый обработчик для маршрута `/prompts/edit-verbose/`
|
||||
- Поддерживает режимы: `v`, `vv`, `vvv`
|
||||
- Валидация всех полей с использованием `validation` пакета
|
||||
- Обновление промптов через `PromptManager`
|
||||
|
||||
3. **Маршрутизация:**
|
||||
- Добавлен маршрут `/prompts/edit-verbose/` в `serve.go`
|
||||
- Поддержка HTTP методов PUT
|
||||
- Интеграция с существующей системой маршрутов
|
||||
|
||||
### 🔧 **Как работает:**
|
||||
|
||||
1. **Пользователь нажимает кнопку "✏️"** на промпте подробности
|
||||
2. **JavaScript вызывает** `editVerbosePrompt(mode, content)`
|
||||
3. **Форма открывается** с заполненными полями
|
||||
4. **При сохранении** отправляется PUT запрос на `/prompts/edit-verbose/{mode}`
|
||||
5. **Сервер обрабатывает** запрос через `handleEditVerbosePrompt()`
|
||||
6. **Промпт обновляется** в файловой системе
|
||||
7. **Страница перезагружается** с обновленными данными
|
||||
|
||||
### 📋 **Поддерживаемые режимы:**
|
||||
|
||||
- **`v`** → ID 6 (базовый verbose)
|
||||
- **`vv`** → ID 7 (средний verbose)
|
||||
- **`vvv`** → ID 8 (максимальный verbose)
|
||||
|
||||
### 🛡️ **Валидация:**
|
||||
|
||||
- **Содержимое:** максимум символов из `LCG_MAX_SYSTEM_PROMPT_LENGTH`
|
||||
- **Название:** максимум символов из `LCG_MAX_PROMPT_NAME_LENGTH`
|
||||
- **Описание:** максимум символов из `LCG_MAX_PROMPT_DESC_LENGTH`
|
||||
|
||||
### 🎨 **UI/UX:**
|
||||
|
||||
- **Единая форма** для редактирования всех типов промптов
|
||||
- **Автоматическое определение** типа промпта (системный/verbose)
|
||||
- **Правильная маршрутизация** запросов
|
||||
- **Валидация на клиенте** и сервере
|
||||
- **Отзывчивый дизайн** для мобильных устройств
|
||||
|
||||
## 🚀 **Использование:**
|
||||
|
||||
1. Откройте страницу `/prompts`
|
||||
2. Перейдите на вкладку "📝 Промпты подробности"
|
||||
3. Нажмите кнопку "✏️" на нужном промпте
|
||||
4. Отредактируйте содержимое
|
||||
5. Нажмите "Сохранить"
|
||||
|
||||
## ✅ **Статус:**
|
||||
|
||||
**ГОТОВО** - Редактирование промптов подробности полностью реализовано и протестировано.
|
||||
Reference in New Issue
Block a user