Конфигурация

Полный справочник — файл docs/config.yaml в репозитории: все ключи с примерами значений. Комментарии в нём пока в основном на китайском, как в upstream.

Формат конфига общий с mihomo, поэтому подходит и документация mihomo с описанием ключей и API контроллера.

Разделы

Ключи	Что настраивают
mixed-port, port, socks-port, redir-port, tproxy-port	Локальные порты прокси.
allow-lan, bind-address, authentication, lan-allowed-ips	Доступ из локальной сети и авторизация.
mode, log-level, ipv6, find-process-mode	Общий режим работы.
log-format, log-timestamp-format	Формат логов: text (по умолчанию) или json, по объекту на строку для Loki и ELK.
tcp-concurrent, tcp-connect-timeout	Исходящие TCP-соединения: параллельный набор всех IP; общий срок установки соединения в миллисекундах (по умолчанию 5000, диапазон 100–600000).
external-controller, external-ui, secret	API контроллера и веб-интерфейс; сетевому адресу нужен secret, см. Безопасность контроллера.
user-stats	Учёт трафика по пользователям входящих (по умолчанию включён), см. Трафик пользователей.
user-limits	Лимиты пользователей входящих: скорость, соединения, адреса, квота, срок, см. Лимиты пользователей.
metrics, health-without-auth	Метрики Prometheus (GET /metrics) и проверки /healthz, /readyz, см. Метрики и здоровье.
egress-guard	Не пускает пользователей серверных входящих через DIRECT в частные и локальные сети, на этот хост и к metadata облака (по умолчанию включено), см. Сервер без root.
tun	TUN-устройство и сетевой стек. В Windows см. TUN в Windows.
dns, hosts	DNS-серверы (в том числе DNSCrypt v2 штампами sdns://), fake IP, политики для DNS-запросов.
dns.serve-expired, dns.serve-expired-ttl, dns.serve-expired-client-timeout	Ответ просроченной записью из кэша, пока она обновляется (RFC 8767). По умолчанию просроченная запись отдаётся сразу и обновляется в фоне, как и раньше; TTL и таймаут клиента дают поведение по RFC 8767.
sniffer	Определение домена по трафику (TLS, HTTP, QUIC) и BitTorrent для правила PROTOCOL; skip-threshold — после скольких неудач адрес больше не сниффится.
proxies, proxy-groups, proxy-providers	Исходящие прокси, группы выбора и удалённые наборы прокси; группы type: chain для каскадов, см. Цепочки; type: desync для прямых соединений в сетях с DPI-фильтрацией, см. Исходящий desync.
rules, sub-rules, rule-providers	Правила маршрутизации и удалённые наборы правил.
listeners, tunnels	Дополнительные входящие, в том числе серверные протоколы. TCP-листенеры могут слушать unix-сокет: listen: unix:/путь, права задаёт unix-mode. Также принимают proxy-protocol: true: каждое TCP-соединение тогда должно начинаться с заголовка PROXY protocol v1 или v2, адрес клиента из него становится адресом источника (журналы, правила, лимиты IP пользователя). Заголовок принимается только от пиров из proxy-protocol-trusted (по умолчанию loopback), остальные соединения закрываются. UDP не затрагивается.
geox-url, geo-auto-update	Откуда и как часто обновлять geodata.

TUN в Windows

При auto-route в Windows собственные соединения ядра выходят с привязкой к исходящему интерфейсу: к интерфейсу по умолчанию при auto-detect-interface (включён по умолчанию) или к интерфейсу из interface-name. Windows не учитывает эту привязку, если на интерфейсе включён Forwarding или WeakHostSend, и соединения возвращаются в TUN: ничего не работает, DNS не отвечает, а журнал заполняется отказами из-за петли. Общий доступ к интернету (ICS) и мобильная точка доступа включают Forwarding на раздаваемом интерфейсе и могут оставить его включённым после выключения.

Ядро эти флаги не меняет: их выключение останавливает раздачу. Оно проверяет их на исходящих интерфейсах (сам TUN не проверяется), для IPv4 и IPv6, при каждом изменении сети и раз в 5 секунд, и сообщает, когда они включаются: одно предупреждение в журнале с именем интерфейса, флагами и семейством адресов и событие tun.forwarding с state: on, чтобы приложение могло предложить исправление. Когда флаги снова выключены или интерфейс перестал быть исходящим, в журнал пишется информационная строка и приходит state: cleared. Чтобы исправить, выключите оба флага от имени администратора:

Set-NetIPInterface -InterfaceAlias "Wi-Fi" -Forwarding Disabled -WeakHostSend Disabled

Раздача этого подключения через мобильную точку доступа или ICS перестанет работать, пока флаги не включат снова.

Правила во время работы

PUT /rules с телом {"rules": ["DOMAIN,a.com,DIRECT", "MATCH,PROXY"]} заменяет правила верхнего уровня без перезагрузки конфига. Строки пишутся так же, как в rules:, и разбираются тем же кодом: цели — прокси и группы, работают RULE-SET, SUB-RULE и логические правила. Список проверяется целиком до замены; ошибка в любой строке — ответ 400 с текстом ошибки, правила не меняются. Прокси из proxy-providers целью быть не могут (как и в конфиге) — указывайте группу. sub-rules и rule-providers остаются прежними.

Замена живёт только в памяти: следующая перезагрузка конфига (PUT /configs, systemctl reload, перезапуск) возвращает правила из файла. Ответ — {"count": N, "ephemeral": true}.

Проверка

citrus -t -f ~/.config/citrus/config.yaml

Команда разбирает конфиг и выходит, ничего не запуская. Пакетная служба перечитывает конфиг по systemctl reload citrus.

Перезагрузка

PUT /configs (с force=true или без) и systemctl reload citrus сразу применяют политику доступа из нового конфига: allow-lan, bind-address, skip-auth-prefixes, lan-allowed-ips, lan-disallowed-ips, authentication, встроенные ss-config и tuic-server. Без force=true встроенные листенеры port, socks-port, redir-port, tproxy-port и mixed-port остаются на своих текущих портах (клиент мог поменять их через PATCH /configs); при смене allow-lan или bind-address они перепривязываются.