Вся настройка «Прокси-агента» — модели, каналы связи, ключи доступа, правила скрытия секретов и значения из окна «Настройки» — лежит не в базе данных, а в обычных текстовых файлах рядом с проектом. Здесь рассказано, что это за файлы, как их безопасно править и почему такую настройку удобно хранить в истории проекта и переносить на другой сервер.
Зачем файлы
Раньше вся настройка лежала в базе данных — как и журналы. Из-за этого перенести продукт на другой сервер было непросто: настройку приходилось собирать заново или восстанавливать из полной копии базы. Теперь настройка живёт отдельно от базы, в текстовых файлах папки проекта.
От этого три выгоды. Настройку видно и можно прочитать глазами, без базы и интерфейса. Её легко перенести на другую установку вместе с папкой проекта. И её можно держать в системе контроля версий — тогда понятно, кто и когда что поменял.
Где лежит настройка
Папка конфигурации по умолчанию — /project/apps/proxy. Задать другое место можно переменной окружения PROXY_APP_CONFIG_FOLDER. Она читается один раз при запуске, поэтому после смены пути нужен перезапуск.
В контейнере эта папка подключается отдельным томом: тогда настройка переживает пересоздание контейнера и её удобно копировать.
Пять файлов и что в них
settings.yml— значения из окна «Настройки» и тут же заданные настройки слушателей: включён ли вход у прокси-службы, сроки хранения отчётов, оформление интерфейса. Каждая строка — пара «имя — значение».models.yml— модели: как обращаться к поставщику, короткая метка, четыре цены за миллион «порций текста» (токенов) и канал, через который идёт трафик.http-providers.yml— каналы связи: HTTP-прокси, SOCKS5, VPN и подписки Happ.keys.yml— ключи доступа: отпечаток, последние знаки, пределы расхода, разрешённые модели и каналы.anonymization.yml— правила скрытия секретов и списки самих секретов.
Как править
Файлы — единственный источник правды, и все три способа ведут в один и тот же файл: правка руками, изменение в интерфейсе и управление по API. Неважно, откуда пришло изменение, — результат окажется в файле на диске.
Интерфейс и API записывают файл аккуратно: сначала готовят временный файл, а потом заменяют им старый. Если запись оборвётся, вы не останетесь с половиной настройки.
Подхват правок и ошибки
Правка руками подхватывается примерно за 300 мс — перезапуск не нужен. Если в файле оказалась ошибка, продукт не падает: он продолжает работать с последним удачным состоянием, а в журнал пишет предупреждение с текстом ошибки. Исправьте файл — и настройка вернётся.
Одно замечание на всякий случай: если править файл одновременно из интерфейса и руками, победит та запись, которая случилась позже.
Секреты ссылками на переменные окружения
Секретные поля — ключ поставщика (apiKey), пароль канала связи, приватный ключ VPN — можно записывать не самим секретом, а ссылкой на переменную окружения вида $ИМЯ_ПЕРЕМЕННОЙ. Значение подставляется в момент обращения к поставщику, так что в файле секрета может не быть вовсе.
Это удобно, когда папку проекта держат в системе контроля версий: перечень настроек попадает в историю, а сами секреты остаются в переменных окружения на сервере. Если переменная не задана, продукт подставит строку как есть, и обращение к поставщику откажет — молча подменять её пустым значением он не станет.
Файл .env: секреты рядом с проектом
Секреты удобно держать не в переменных запуска, а в одном файле .env рядом с проектом. По умолчанию это /project/.env, а другой путь задаётся переменной PROXY_APP_ENV_FILE. Внутри — простые строки ИМЯ=значение: комментарии начинаются с #, пустые строки пропускаются, перед именем можно написать export, а значение взять в кавычки.
Приложение читает файл само при запуске и следит за ним дальше, поэтому отдельный флаг --env-file в команде запуска не нужен. Настоящие переменные окружения всегда важнее файла: если имя задано и там и там, победит внешнее значение. Удалённая из файла строка снимает переменную, а отсутствующий файл ничего не занимает — созданный позже подхватится сам. Нечитаемый файл оставляет последние удачные значения.
На ходу меняются те переменные, которые читаются при использовании: ссылки $ИМЯ_ПЕРЕМЕННОЙ в файлах папки конфигурации, ключ управления, вход администратора и внешние программы (ядро Xray, WireGuard). Переменные, которые читаются один раз при запуске (база, папки данных и конфигурации, лицензия, ключ подписи сессий, ClickHouse, подключение агента), по-прежнему требуют перезапуска контейнера.
Файл стоит держать в .gitignore и не выкладывать в открытый доступ: в нём лежат секреты. В журнал попадают только счётчики изменений — сами значения никогда.
Что остаётся в базе
В файлах лежит только настройка. Объёмные рабочие данные остаются в базе данных: журнал запросов, журнал прокси-службы и суточные суммы расхода по ключам.
Есть и третье место — папка рабочего состояния (PROXY_APP_DATA, по умолчанию /apps/proxy). В ней хранится временное хранилище «размышлений» DeepSeek, ключи подписи сессий, рабочие файлы VPN и рабочие файлы каналов-подписок Happ (happ/). Её тоже стоит подключать томом: иначе после пересоздания контейнера все выданные входы перестанут действовать.
Перенос на другой сервер
Скопируйте папку конфигурации на новую установку — модели, каналы, ключи, правила и настройки окажутся на месте без восстановления базы. База при этом нужна своя: в ней только история, и на новом сервере она начинается с нуля.
Именно поэтому папку полезно держать в системе контроля версий вместе с проектом: видно, кто менял настройку и когда, а возврат к прежнему состоянию — это обычный возврат файла.
Чего делать не стоит
- Не выкладывайте папку с настоящими секретами в открытый доступ. Доступ к такой папке равен доступу к ключам поставщиков. Если папку проекта видят многие, записывайте секреты ссылками на переменные окружения.
- Не правьте файл, пока его меняют из интерфейса. Последняя запись затрёт предыдущую.
- Не рассчитывайте, что копия базы вернёт настройку. Настройка теперь в файлах — копируйте папку конфигурации.
- Не ждите, что смена
PROXY_APP_CONFIG_FOLDERприменится на ходу. Этот путь читается один раз при запуске, после смены нужен перезапуск.
Дальше: как менять настройки из окна «Настройки» — в разделе Настройки, а как вести их программой — в разделе Управление агентом по API.