Установка Прокси-агента

Не хотите читать всё это?

Просто скиньте в любой ИИ-чат (Claude, ChatGPT и т.д.) ссылку на https://pastukhov.com/agents/proxy/install.md или на https://pastukhov.com/llms.txt и попросите сгенерировать конфигурационные файлы и команды. Он прочитает документацию, задаст несколько вопросов о вашей настройке и выдаст готовую конфигурацию. Экономьте время — пусть модель читает за вас.

Вы также можете связаться со мной через Telegram — я всегда рад помочь. И это не просто вежливость — мне действительно нравится общаться с единомышленниками, особенно если вы так же увлечены программированием, как и я.

«Прокси-агент» — это одна точка входа ко всем моделям, которыми пользуется ваша команда. Программа живёт на вашем сервере и разворачивается одним контейнером Docker, а рядом нужна база PostgreSQL — это единственная обязательная настройка. После установки все ваши программы обращаются не к десятку поставщиков по отдельности, а к адресу вашего сервера: ключи поставщиков, лимиты расхода и журнал запросов остаются у вас, а не расходятся по компьютерам сотрудников.

Что понадобится

Сервер или компьютер с Docker — подойдёт Windows, Linux или macOS, а для постоянной работы достаточно недорогого сервера.
База PostgreSQL — отдельная и обязательная. Внутри контейнера базы нет: без строки подключения приложение не запустится. Проще всего поднять базу рядом в том же файле запуска, как показано ниже.
Один свободный порт для интерфейса и запросов (в примерах — 5000). Если понадобится прокси для обычного трафика, добавьте отдельный порт на каждый канал, которому его разрешите: сколько каналов, столько портов.
Лицензионный ключ — без него интерфейс откроется, а трафик через сервер не пойдёт. Ключ передаётся переменной AGENT_LICENSE.
По желанию — адрес и ключ вашего Pastukhov Agent: без них работает всё, кроме чата с ИИ-агентом внутри продукта.

Продукт экономно расходует ресурсы сервера. В простое процессор не нагружается: фоновые проверки не крутятся по кругу, а просыпаются, когда появляется работа. Через 15 минут без работы освобождается память, занятая последним потоком запросов, и возвращается серверу — при новом обращении всё поднимается само. Поэтому «Прокси-агент» спокойно соседствует с другими сервисами на одном сервере, и настраивать для этого ничего не нужно.

Установка через Docker Compose

Создайте файл compose.yml с таким содержимым. Здесь две службы: база и само приложение.

services:
  postgres:
    image: postgres:17
    container_name: proxyagent-postgres
    environment:
      - POSTGRES_DB=proxyagent
      - POSTGRES_USER=proxyagent
      - POSTGRES_PASSWORD=смените-этот-пароль
    volumes:
      - proxyagent-db:/var/lib/postgresql/data
    restart: unless-stopped

  proxyagent:
    image: maxpastukhov/proxy-agent:main-latest
    container_name: proxyagent
    ports:
      - "5000:80"
      # Порт прокси-службы публикуется отдельной строкой — по одной на каждый
      # канал, которому вы задали порт слушателя на странице «HTTP-прокси».
      # - "5010:5010"
    volumes:
      # Рабочее состояние: ключи защиты данных, ключ подписи сессий,
      # «размышления», хранилище секретов, конфигурации VPN.
      - proxyagent-data:/apps/proxy
      # Конфигурация: файлы настроек, моделей, каналов, ключей и правил.
      - proxyagent-config:/project/apps/proxy
    environment:
      - ASPNETCORE_ENVIRONMENT=Production
      - PROXY_APP_DATABASE=Host=postgres;Port=5432;User Id=proxyagent;Password=смените-этот-пароль;Database=proxyagent;
      - PROXY_APP_DATA=/apps/proxy
      - PROXY_APP_CONFIG_FOLDER=/project/apps/proxy
      - PROXY_APP_ADMIN_LOGIN=admin
      - PROXY_APP_ADMIN_PASSWORD=<сумма SHA-256 от пароля, строчными буквами>
      - JWT_SECRET_KEY=<случайная строка не короче 32 знаков>
      # Лицензионный ключ: без него интерфейс откроется, а трафик не пойдёт.
      # - AGENT_LICENSE=${AGENT_LICENSE}
    restart: unless-stopped

volumes:
  proxyagent-db:
  proxyagent-data:
  proxyagent-config:

Образ maxpastukhov/proxy-agent:main-latest — русская сборка с русским интерфейсом. Затем запустите:

docker compose up -d

Интерфейс появится на порту 5000: http://<адрес-сервера>:5000. Пароль базы замените на свой и подставьте его же в строку PROXY_APP_DATABASE — это одна и та же пара значений. Лицензионный ключ задаётся переменной AGENT_LICENSE: без действующего ключа интерфейс и настройки открыты, но трафик через сервер не пойдёт.

Запуск без Compose

Можно обойтись и одной командой docker run — базу в этом случае поднимите отдельно:

docker run -d \
  --name proxyagent \
  -p 5000:80 \
  -v proxyagent-data:/apps/proxy \
  -v proxyagent-config:/project/apps/proxy \
  -e PROXY_APP_DATABASE="Host=адрес-базы;Port=5432;User Id=proxyagent;Password=ваш-пароль;Database=proxyagent;" \
  -e PROXY_APP_DATA=/apps/proxy \
  -e PROXY_APP_CONFIG_FOLDER=/project/apps/proxy \
  -e PROXY_APP_ADMIN_LOGIN=admin \
  -e PROXY_APP_ADMIN_PASSWORD=ваша-сумма-sha256 \
  -e JWT_SECRET_KEY=ваша-случайная-строка-не-короче-32-знаков \
  -e AGENT_LICENSE=ваш-лицензионный-ключ \
  --restart unless-stopped \
  maxpastukhov/proxy-agent:main-latest

Остальные переменные удобно держать в файле .env рядом с проектом (по умолчанию /project/.env, путь меняется переменной PROXY_APP_ENV_FILE). Приложение читает его само при запуске и перечитывает на ходу, поэтому отдельный флаг --env-file в команде не нужен — так переменные проще менять, не переписывая длинную строку запуска. Настоящие переменные окружения всегда важнее файла, а сам файл стоит держать в .gitignore: в нём лежат секреты.

Основные переменные окружения

Настройки задаются переменными окружения — их прописывают один раз в compose.yml и меняют без правки кода. Почти все имена начинаются с PROXY_APP_. Прежние имена с приставкой PROXYAGENT_ больше не читаются — при обновлении их нужно переименовать.

Переменная	Что задаёт	По умолчанию
`PROXY_APP_ENV_FILE`	путь к файлу с переменными окружения, который подмешивается при запуске и перечитывается при изменении	`/project/.env`
`PROXY_APP_DATABASE`	строка подключения к PostgreSQL — единственная обязательная настройка	нет; без неё приложение не запускается
`PROXY_APP_ADMIN_LOGIN`, `PROXY_APP_ADMIN_PASSWORD`	вход администратора; пароль — сумма SHA-256, записанная строчными буквами (в форме входа есть встроенный генератор)	не заданы — показывается «первоначальная настройка»
`JWT_SECRET_KEY`, `DEV_FALLBACK_JWT_KEY`	подпись сессий входа (не короче 32 знаков); второй — последний запасной ключ, если файл с ключом недоступен. С заданным ключом сессии переживают пересоздание контейнера	генерируется и сохраняется в файле
`AGENT_LICENSE`	лицензионный ключ либо путь к файлу с ключом; читается один раз при запуске — после смены ключа нужен перезапуск	не задано — трафик не идёт
`PROXY_APP_HASH`	сумма SHA-256 (строчными буквами) ключа управления по API; закрывает адреса `/api/agent/*` заголовком `X-API-Key`	не задано — управление по API выключено
`AGENT_API_URL`, `AGENT_API_KEY`	чат с ИИ-агентом внутри продукта (подключение Pastukhov Agent); читаются один раз при запуске	не заданы — чат скрыт
`PROXY_APP_BASE_PATH`	размещение в первой подпапке (например, `/proxy`)	не задано — работа в корне домена
`PROXY_APP_CONFIG_FOLDER`	папка конфигурации с файлами настроек, моделей, каналов, ключей и правил скрытия секретов; читается один раз при запуске	`/project/apps/proxy`
`PROXY_APP_DATA`	корень рабочего состояния (ключи защиты данных, ключ подписи сессий, «размышления», хранилище секретов, конфигурации VPN); читается один раз при запуске	`/apps/proxy`
`PROXY_APP_ANONYMIZER_DB`	папка хранилища скрытия секретов: правила, соответствия и события утечек	`/apps/proxy/anonymizer`
`PROXY_APP_CLICKHOUSE_URL`	отправка статистики в ClickHouse; при заданном значении в аналитике появляется кнопка восстановления пропущенных дней	не задано — выключено
`PROXY_APP_BRAND`	бренд сборки; `pastukhov` — русская сборка, на ней интерфейс по умолчанию русский (пока язык не выбран вручную)	`xedant`
`ASPNETCORE_URLS`	адрес прослушивания внутри контейнера	`http://+:80`
`ASPNETCORE_ENVIRONMENT`	`Production` включает защиту и строгую страницу ошибок	`Production`

Где хранятся данные

Данные разложены по трём местам, и путать их не стоит.

Конфигурация — файлы settings.yml, models.yml, http-providers.yml, keys.yml и anonymization.yml в папке /project/apps/proxy. Здесь модели, каналы, ключи доступа, правила скрытия секретов и настройки. Папку можно положить в систему контроля версий и переносить вместе с проектом, а правки руками подхватываются примерно за 300 мс. Секретные поля можно записывать ссылкой на переменную окружения вида $ИМЯ_ПЕРЕМЕННОЙ.
Рабочее состояние — том /apps/proxy: auth/ (ключи защиты данных), appdata/.jwt-secret (ключ подписи сессий входа), reasoning_cache.sqlite3 (сохранённые «размышления» DeepSeek), anonymizer/ (хранилище скрытия секретов), vpn/ (конфигурации VPN) и happ/ (рабочие файлы каналов-подписок Happ — сейчас это happ/{id}/). Содержимое happ/ восстанавливается само: при следующем обращении подписка запрашивается заново.
Журналы и расходы — PostgreSQL: журнал запросов, журнал прокси-службы и суточные суммы расхода по ключам.

Поэтому в примере выше подключены два тома. Без тома рабочего состояния при пересоздании контейнера пропадут сохранённые «размышления» и соответствия секретов (уже отправленные в модель обозначения перестанут возвращаться на место), а без постоянного JWT_SECRET_KEY перестанут действовать все выданные сессии входа.

Первый вход

Откройте интерфейс в браузере. Логин и пароль администратора задаются переменными PROXY_APP_ADMIN_LOGIN и PROXY_APP_ADMIN_PASSWORD; если они не заданы, продукт честно сообщает о «первоначальной настройке» и работать не даст. В переменной хранится не сам пароль, а его необратимая сумма SHA-256 — при входе вы вводите пароль, приложение считает сумму от введённого и сравнивает с заданной. Готовую сумму удобно получить встроенным генератором прямо в форме входа. Сессия входа живёт 90 дней, и переменные читаются на каждом запросе, поэтому пароль можно поменять без перезапуска контейнера.

Что сделать после запуска

Когда интерфейс открылся, до первого запроса остаётся несколько шагов:

Заведите первую модель в разделе «Ключи → Модели»: публичное имя, адрес и ключ поставщика, цены за миллион «порций текста» (токенов). Подробнее — в разделе Модели и цены.
Нажмите «Проверить» у модели — продукт сходит к поставщику настоящим путём и скажет, отвечает ли связь.
Создайте ключ доступа для первой программы. Ключ показывается ровно один раз — сохраните его сразу.
Подключите программу: вместо адреса поставщика укажите адрес вашего сервера, вместо ключа поставщика — ключ доступа. Как именно — в разделе Подключение программ.
Отправьте первый запрос и убедитесь, что он появился в журнале запросов: там видно модель, ключ, токены и стоимость.

Прокси для обычного трафика

Кроме работы с моделями продукт умеет быть обычным прокси-сервером для браузеров и программ, не связанных с ИИ. По умолчанию эта возможность выключена: пока ни одному HTTP-прокси не задан порт слушателя, ничего не слушает.

Каждый канал получает свой порт слушателя: на странице «HTTP-прокси» задайте порт и включите приём соединений. Порт публикуется отдельной строкой в файле запуска — только тогда он будет доступен снаружи.
Вход по ключу доступа включён по умолчанию: без ключа в интернет никто не выйдет. Отключать проверку стоит только внутри закрытой сети.
Если нужен канал связи через VPN, контейнеру потребуются права NET_ADMIN и установленный WireGuard внутри образа: готовый образ их не содержит.
Если нужен канал по подписке Happ, доустанавливать ничего не нужно: ядро Xray уже в образе. В своей сборке без ядра продукт сам скажет, что такой канал недоступен.

Такой трафик считается в объёме, но не в деньгах и не расходует лимиты ключей. Подробнее — в разделе Прокси для обычного трафика.

Установка через Pastukhov MultiAgent

Если у вас несколько серверов, удобнее ставить продукт из Pastukhov MultiAgent: он сам поднимает контейнер, выдаёт постоянный адрес и HTTPS, подключает базу. «Прокси-агент» есть в каталоге продуктов (порт 6040): строку подключения к базе и остальные переменные MultiAgent подставляет сам, а связанный Pastukhov Agent подключается к чату. Подробнее о самом MultiAgent — на странице MultiAgent.

Лицензия и обновления

Продукт проверяет лицензию: действующий ключ нужен, чтобы через сервер пошёл трафик, а интерфейс, настройки, журналы и управление по API открыты и без него. Ключ задаётся переменной AGENT_LICENSE, а его состояние видно строкой в интерфейсе. Лицензия — это право использования, 12 месяцев бесплатных обновлений и поддержка. Цены те же, что у соседних продуктов: персональная — 19 700 ₽, корпоративная — 49 700 ₽, сервисная — 97 000 ₽. Подробнее — на странице Лицензирование.

Дальше стоит заглянуть в Начало работы — там коротко о том, как продукт устроен изнутри.

← Вернуться на главную раздела Прокси-агент