API

Caddy настраивается через точку входа в администрирование, к которой можно получить доступ через HTTP, используя REST API. Вы можете настроить эту точку входа в своей конфигурации Caddy.

По умолчанию адрес: localhost:2019

Адрес по умолчанию можно изменить, задав переменную среды CADDY_ADMIN. Некоторые методы установки могут установить её в другое значение. Адрес в конфигурации Caddy всегда имеет приоритет над значением по умолчанию.

Последняя конфигурация будет сохранена на диске после любых изменений (если не отключено). Вы можете восстановить последнюю рабочую конфигурацию после перезапуска с помощью caddy run --resume, что гарантирует устойчивость конфигурации в случае отключения питания или подобных событий.

Чтобы начать работу с API, попробуйте наш учебник по API или, если у вас есть всего минута, наше руководство по быстрой настройке API.

POST /load Устанавливает или заменяет активную конфигурацию
POST /stop Останавливает активную конфигурацию и завершает процесс
GET /config/[path] Экспортирует конфигурацию по указанному пути
POST /config/[path] Устанавливает или заменяет объект; добавляет в массив
PUT /config/[path] Создаёт новый объект; вставляет в массив
PATCH /config/[path] Заменяет существующий объект или элемент массива
DELETE /config/[path] Удаляет значение по указанному пути
Использование @id в JSON Легко перемещаться по структуре конфигурации
Конкурентные изменения конфигурации Избегайте коллизий при внесении несинхронизированных изменений в конфигурацию
POST /adapt Адаптирует конфигурацию к JSON без её запуска
GET /pki/ca/<id> Возвращает информацию о конкретном приложении PKI CA
GET /pki/ca/<id>/certificates Возвращает цепочку сертификатов конкретного приложения PKI CA
GET /reverse_proxy/upstreams Возвращает текущий статус настроенных прокси-серверов upstream

POST /load

Устанавливает конфигурацию Caddy, перезаписывая любую предыдущую конфигурацию. Он блокируется до тех пор, пока перезагрузка не завершится или не произойдёт ошибка. Изменения конфигурации выполняются быстро, эффективно и без простоев. Если новая конфигурация завершится ошибкой по любой причине, старая конфигурация будет восстановлена без простоев.

Этот пункт входа поддерживает различные форматы конфигурации с использованием адаптеров конфигурации. Заголовок Content-Type запроса указывает формат конфигурации, используемый в теле запроса. Обычно это должно быть application/json, что представляет собой родной формат конфигурации Caddy. Для другого формата конфигурации укажите соответствующий Content-Type, где значение после слэша / — имя адаптера конфигурации для использования. Например, при отправке Caddyfile используйте значение, подобное text/caddyfile; или для JSON 5 используйте значение, такое как application/json5; и т. д.

Если новая конфигурация совпадает с текущей, перезагрузка не произойдёт. Чтобы принудительно выполнить перезагрузку, установите Cache-Control: must-revalidate в заголовках запроса.

Примеры

Установите новую активную конфигурацию:

curl "http://localhost:2019/load" \
	-H "Content-Type: application/json" \
	-d @caddy.json

Примечание: флаг -d curl удаляет новые строки, поэтому если ваш формат конфигурации чувствителен к перерывам строк (например, Caddyfile), используйте --data-binary вместо него:

curl "http://localhost:2019/load" \
	-H "Content-Type: text/caddyfile" \
	--data-binary @Caddyfile

POST /stop

Вежливо завершает работу сервера и завершает процесс. Чтобы остановить только работающую конфигурацию без выхода из процесса, используйте DELETE /config/.

Пример

Остановка процесса:

curl -X POST "http://localhost:2019/stop"

GET /config/[path]

Экспортирует текущую конфигурацию Caddy по указанному пути. Возвращает JSON-тело.

Примеры

Экспорт всей конфигурации и красивый вывод:

curl "http://localhost:2019/config/" | jq
{
	"apps": {
		"http": {
			"servers": {
				"myserver": {
					"listen": [
						":443"
					],
					"routes": [
						{
							"match": [
								{
									"host": [
										"example.com"
									]
								}
							],
							"handle": [
								{
									"handler": "file_server"
								}
							]
						}
					]
				}
			}
		}
	}
}

Экспорт только адресов слушателей:

curl "http://localhost:2019/config/apps/http/servers/myserver/listen"
[":443"]

POST /config/[path]

Изменяет конфигурацию Caddy по указанному пути на JSON-тело запроса. Если целевое значение является массивом, POST добавляет; если объектом, он создаёт или заменяет.

В качестве особого случая, многие элементы могут быть добавлены в массив, если:

путь заканчивается на /...
элемент пути перед /... относится к массиву
payload — это массив

В этом случае элементы в массиве payload будут расширены, и каждый из них будет добавлен в целевой массив. В терминах Go это имело бы тот же эффект, что и:

baseSlice = append(baseSlice, newElems...)

Примеры

Добавление адреса слушателя:

curl \
	-H "Content-Type: application/json" \
	-d '":8080"' \
	"http://localhost:2019/config/apps/http/servers/myserver/listen"

Добавление нескольких адресов слушателей:

curl \
	-H "Content-Type: application/json" \
	-d '[":8080", ":5133"]' \
	"http://localhost:2019/config/apps/http/servers/myserver/listen/..."

PUT /config/[path]

Изменяет конфигурацию Caddy по указанному пути на JSON-тело запроса. Если целевое значение является позицией (индексом) в массиве, PUT вставляет; если объектом, он строго создаёт новое значение.

Пример

Добавление адреса слушателя в первый слот:

curl -X PUT \
	-H "Content-Type: application/json" \
	-d '":8080"' \
	"http://localhost:2019/config/apps/http/servers/myserver/listen/0"

PATCH /config/[path]

Изменяет конфигурацию Caddy по указанному пути на JSON-тело запроса. PATCH строго заменяет существующее значение или элемент массива.

Пример

Замена адресов слушателей:

curl -X PATCH \
	-H "Content-Type: application/json" \
	-d '[":8081", ":8082"]' \
	"http://localhost:2019/config/apps/http/servers/myserver/listen"

DELETE /config/[path]

Удаляет конфигурацию Caddy по указанному пути. DELETE удаляет целевое значение.

Примеры

Чтобы разгрузить всю текущую конфигурацию, но оставить процесс работающим:

curl -X DELETE "http://localhost:2019/config/"

Чтобы остановить только один из ваших HTTP-серверов:

curl -X DELETE "http://localhost:2019/config/apps/http/servers/myserver"

Использование `@id` в JSON

Вы можете встроить идентификаторы в свой JSON-документ для более лёгкого прямого доступа к этим частям JSON.

Просто добавьте поле, называемое "@id", в объект и присвойте ему уникальное имя. Например, если у вас есть обработчик обратного проксирования, к которому вы хотите часто обращаться:

{
	"@id": "my_proxy",
	"handler": "reverse_proxy"
}

Чтобы использовать его, просто сделайте запрос к точке входа API /id/ API так же, как вы бы сделали к соответствующей точке входа /config/, но без всего пути. Идентификатор сразу переносит запрос в тот контекст конфигурации.

Например, чтобы получить доступ к upstream обратного проксирования без идентификатора, путь будет чем-то вроде

/config/apps/http/servers/myserver/routes/1/handle/0/upstreams

но с идентификатором, путь становится

/id/my_proxy/upstreams

что намного легче запоминать и писать вручную.

Конкурентные изменения конфигурации

API конфигурации Caddy обеспечивает гарантии ACID для отдельных запросов, но изменения, которые включают в себя более одного запроса, подвержены коллизиям или потере данных, если они не синхронизированы должным образом.

Например, два клиента могут GET /config/foo одновременно, внести изменения в заданный контекст (путь конфигурации), а затем одновременно вызвать POST|PUT|PATCH|DELETE /config/foo/... для применения своих изменений, что приведёт к коллизии: либо один перезапишет другой, либо второй может оставить конфигурацию в непредвиденном состоянии, поскольку она была применена к другой версии конфигурации, чем та, к которой она была подготовлена. Это потому, что изменения не осведомлены друг о друге.

API Caddy не поддерживает транзакции, охватывающие несколько запросов, а HTTP — это бессостоятельный протокол. Однако вы можете использовать заголовки Etag и If-Match, чтобы обнаруживать и предотвращать коллизии для всех изменений как своего рода оптимистический контроль конкуретности. Это полезно, если есть вероятность одновременного использования точек входа /config/... Caddy без синхронизации. Все ответы на GET /config/... запросы имеют заголовок HTTP, называемый Etag, который содержит путь и хэш содержимого в этом контексте (например, Etag: "/config/apps/http/servers 65760b8e"). Просто установите заголовок If-Match в мутативном запросе, соответствующем заголовку Etag от предыдущего запроса GET.

Базовый алгоритм таков:

Выполните запрос GET в любой контекст S в конфигурации. Сохраните заголовок Etag ответа.
Внесите желаемые изменения в полученную конфигурацию.
Выполните запрос POST|PUT|PATCH|DELETE в контексте S, установив заголовок запроса If-Match в сохранённое значение Etag.
Если ответ — HTTP 412 (Превышение предпосылок), повторите с шага 1, или откажитесь от попыток после слишком большого числа попыток.

Этот алгоритм безопасно позволяет множественным, перекрывающимся изменениям в конфигурации Caddy без явной синхронизации. Он разработан таким образом, что одновременные изменения в разных частях конфигурации не требуют повторной попытки: только изменения, которые перекрывают тот же контекст конфигурации, могут потенциально вызвать коллизию и, следовательно, требуют повторной попытки.

POST /adapt

Адаптирует конфигурацию к Caddy JSON без её загрузки или выполнения. При успешном выполнении результирующий JSON-документ возвращается в теле ответа.

Заголовок Content-Type используется для указания формата конфигурации аналогично тому, как работает /load. Например, чтобы адаптировать Caddyfile, установите Content-Type: text/caddyfile.

Этот пункт входа будет адаптировать любой формат конфигурации, если соответствующий адаптер конфигурации подключён к вашему сборке Caddy.

Примеры

Адаптация Caddyfile к JSON:

curl "http://localhost:2019/adapt" \
	-H "Content-Type: text/caddyfile" \
	--data-binary @Caddyfile

GET /pki/ca/<id>

Возвращает информацию о конкретном приложении PKI CA по его идентификатору. Если запрашиваемый идентификатор CA является по умолчанию (local), то CA будет предоставлен, если он ещё не был. Другие идентификаторы CA вернут ошибку, если они не были предварительно предоставлены.

curl "http://localhost:2019/pki/ca/local" | jq
{
	"id": "local",
	"name": "Caddy Local Authority",
	"root_common_name": "Caddy Local Authority - 2022 ECC Root",
	"intermediate_common_name": "Caddy Local Authority - ECC Intermediate",
	"root_certificate": "-----BEGIN CERTIFICATE-----\nMIIB ... gRw==\n-----END CERTIFICATE-----\n",
	"intermediate_certificate": "-----BEGIN CERTIFICATE-----\nMIIB ... FzQ==\n-----END CERTIFICATE-----\n"
}

GET /pki/ca/<id>/certificates

Возвращает цепочку сертификатов определенного приложения PKI CA по его ID. Если запрашиваемый ID CA является значением по умолчанию (local), то CA будет предоставлен, если он ещё не предоставлен. Другие ID CA вернут ошибку, если они ранее не были предоставлены.

Этот конечная точка используется внутри командой caddy trust для установки корневого сертификата CA в хранилище доверия вашей системы.

curl "http://localhost:2019/pki/ca/local/certificates"
-----BEGIN CERTIFICATE-----
MIIByDCCAW2gAwIBAgIQViS12trTXBS/nyxy7Zg9JDAKBggqhkjOPQQDAjAwMS4w
...
By75JkP6C14OfU733oElfDUMa5ctbMY53rWFzQ==
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
MIIBpDCCAUmgAwIBAgIQTS5a+3LUKNxC6qN3ZDR8bDAKBggqhkjOPQQDAjAwMS4w
...
9M9t0FwCIQCAlUr4ZlFzHE/3K6dARYKusR1ck4A3MtucSSyar6lgRw==
-----END CERTIFICATE-----

GET /reverse_proxy/upstreams

Возвращает текущее состояние настроенных обратных прокси-серверов (бекендов) в виде JSON-документа.

curl "http://localhost:2019/reverse_proxy/upstreams" | jq
[
	{"address": "10.0.1.1:80", "num_requests": 4, "fails": 2},
	{"address": "10.0.1.2:80", "num_requests": 5, "fails": 4},
	{"address": "10.0.1.3:80", "num_requests": 3, "fails": 3}
]

Каждый элемент в массиве JSON — это настроенный upstream, хранящийся в глобальном пуле upstream.

address — адрес подключения к upstream.
num_requests — количество активных запросов, обрабатываемых в данный момент upstream.
fails — текущее количество неудачных запросов, запомненных в соответствии с настройками пассивной проверки работоспособности.

Если вашей целью является определение доступности бэкенда, вам необходимо сравнить соответствующие свойства upstream с конфигурацией обработчика, которую вы используете. Например, если вы включили пассивную проверку работоспособности для ваших прокси-серверов, то вам также необходимо учитывать значения fails и num_requests, чтобы определить, считается ли upstream доступным: убедитесь, что значение fails меньше вашего настроенного максимального количества сбоев для вашего прокси-сервера (например, max_fails), и что num_requests меньше или равно вашему настроенному максимальному количеству запросов на upstream (например, unhealthy_request_count для всего прокси-сервера или max_requests для отдельных upstream).

© 2015-2025 Matthew Holt and The Caddy Authors
Licensed under the Apache License 2.0.
Caddy is a registered trademark of Stack Holdings GmbH.
https://caddyserver.com/docs/api

API

POST /load

Примеры

POST /stop

Пример

GET /config/[path]

Примеры

POST /config/[path]

Примеры

PUT /config/[path]

Пример

PATCH /config/[path]

Пример

DELETE /config/[path]

Примеры

Использование @id в JSON

Конкурентные изменения конфигурации

POST /adapt

Примеры

GET /pki/ca/<id>

GET /pki/ca/<id>/certificates

GET /reverse_proxy/upstreams

Использование `@id` в JSON