Введение
Флаг функции — это настройка, которая включает или отключает функцию без изменения кода приложения. Представьте, что вы готовите новый баннер объявления: вы хотите проверить его в учебной среде, оставив публичную версию отключённой. Workers KV хранит небольшие значения под именами, которые называются ключами. Worker может прочитать ключ, например banner:new, чтобы определить, какой ответ отправить. Это удобно для настроек, которые часто читают и лишь иногда изменяют.
Перед началом этого курса пройдите лабораторную работу Connect LabEx to Your Cloudflare Account. В ней объясняются терминал виртуальной машины LabEx, авторизация устройства, подтверждение аккаунта и account_id. Если вы открыли этот курс напрямую, сначала выполните эту лабораторную работу. Также вы должны уметь писать небольшой JavaScript Worker и развёртывать его с помощью Wrangler из курса для начинающих по Workers. Worker запускает код обработки запросов в Cloudflare, поэтому вам не нужно обслуживать собственный сервер.
В этой работе вы создадите пространство имён — именованный контейнер, который отделяет одну коллекцию ключей от других. Вы подключите его к Worker с помощью привязки — настроенного имени, через которое код обращается к этому ресурсу. Вы потренируетесь выполнять локальные и облачные операции, опубликуете конечную точку только для чтения баннера и удалите временные ресурсы.
Используйте собственный учебный аккаунт. Для этой новой виртуальной машины потребуется отдельный вход с разрешениями на работу с Workers и KV. В упражнении используются один Worker, одно пространство имён и несколько тестовых значений в пределах бесплатных лимитов KV; для небольшого упражнения не нужны приобретённый домен или платный тариф. Текущее использование аккаунта по-прежнему учитывается в его лимитах. Публичная конечная точка не содержит личной информации.
В процессе настройки устанавливаются Node.js 22.22.0 и локальная версия Wrangler 4.131.1 в /home/labex/project/feature-flags. Версии прямых зависимостей зафиксированы, а команда npm install уже выполняется; повторно устанавливать эти инструменты не нужно. Не закрывайте виртуальную машину, пока не будут проверены удаление ресурсов в облаке и выход из аккаунта.
Подключение отдельного пространства имён для флагов
На этом шаге вы зададите для лабораторной работы собственные имена ресурсов и подключите облачное пространство имён к проекту. Отдельное пространство имён не позволяет учебным ключам смешиваться с ключами существующего приложения.
Перейдите в подготовленный проект:
cd /home/labex/project/feature-flags
Один раз сгенерируйте уникальное имя. Команда openssl rand -hex 6 выводит случайный суффикс, а $(...) вставляет его в имя. Переменная оболочки сохранит это имя для следующих команд в данном терминале.
WORKER_NAME="labex-flags-$(openssl rand -hex 6)"
printf '%s\n' "$WORKER_NAME"
Авторизуйте эту виртуальную машину. Помимо чтения данных о вашем аккаунте, разрешение Workers Scripts Write позволяет развёртывать и удалять ресурсы, а Workers KV Write — управлять пространством имён и ключами этой лабораторной работы.
npx wrangler login --device --browser=false --scopes account:read user:read workers_scripts:write workers_kv:write
Откройте показанную ссылку для устройства в браузере, введите текущий код, проверьте запрошенные разрешения и учебный аккаунт, затем авторизуйте Wrangler. На странице согласия также может отображаться разрешение фонового доступа. Вернитесь в терминал и дождитесь завершения входа.
Разверните Developer Platform на странице согласия и сравните запрошенные разрешения с примером ниже. Для этой лабораторной работы необходимы оба разрешения на запись: они позволяют управлять ресурсами, а не только читать флаг.
npx wrangler whoami --json
Убедитесь, что результат содержит loggedIn: true и name учебного аккаунта, даже если указан только один аккаунт. Скопируйте id этого аккаунта. Сохраните его в конфигурации ниже, заменив YOUR_ACCOUNT_ID перед выполнением команды. Здесьструкция cat записывает всё между двумя строками JSON в файл; > заменяет содержимое файла. Кавычки вокруг разделителя не используются, поэтому оболочка подставит значение $WORKER_NAME.
cat > wrangler.jsonc <<JSON
{
"name": "$WORKER_NAME",
"main": "src/index.js",
"compatibility_date": "2026-07-30",
"account_id": "YOUR_ACCOUNT_ID",
"workers_dev": true
}
JSON
Создайте пространство имён в этом аккаунте. В его названии используется уникальное имя Worker, чтобы позже вы могли легко найти эту пару. Параметр --update-config=false оставляет редактирование привязки вам, вместо автоматического изменения файла.
npx wrangler kv namespace create "$WORKER_NAME-flags" --update-config=false
В выводе появится идентификатор нового пространства имён. Скопируйте его, затем замените YOUR_ACCOUNT_ID и YOUR_NAMESPACE_ID в этой полной конфигурации. Имя привязки FLAGS выбирается для вашего кода, а идентификатор указывает на реальный ресурс Cloudflare.
cat > wrangler.jsonc <<JSON
{
"name": "$WORKER_NAME",
"main": "src/index.js",
"compatibility_date": "2026-07-30",
"account_id": "YOUR_ACCOUNT_ID",
"workers_dev": true,
"kv_namespaces": [
{ "binding": "FLAGS", "id": "YOUR_NAMESPACE_ID" }
]
}
JSON
npx wrangler kv namespace list
Найдите пространство имён этой лабораторной работы и сравните его идентификатор с указанным в файле. Другие пространства имён могут присутствовать — не изменяйте их. Эта конфигурация определяет аккаунт и ресурс, которые должны использовать последующие команды. Привязка — это ссылка на пространство имён, а не копия его данных.
Разделение локальных и удалённых флагов
На этом шаге вы сохраните разные значения под одним ключом и убедитесь, что локальные изменения не затрагивают данные в облаке. Локальный означает хранилище внутри виртуальной машины LabEx. Удалённый означает пространство имён в вашем аккаунте Cloudflare. Wrangler использует привязку для определения хранилища, а явный параметр --local или --remote выбирает место выполнения операции.
Сначала оставьте публичную функцию отключённой:
npx wrangler kv key put banner:new disabled --binding FLAGS --remote
Включите эту же функцию в локальном хранилище виртуальной машины:
npx wrangler kv key put banner:new enabled --binding FLAGS --local
Прочитайте оба значения. Команда put записывает ключ, а get получает его значение. Двоеточие в banner:new — это соглашение об именовании, которое группирует связанные ключи; оно не создаёт каталог.
Используйте --text, чтобы декодировать сохранённое значение как UTF-8 и вывести его на отдельной строке.
npx wrangler kv key get banner:new --binding FLAGS --local --text
Ожидаемый результат — enabled.
npx wrangler kv key get banner:new --binding FLAGS --remote --text
Ожидаемый результат — disabled. Если вы случайно изменили удалённое значение, повторите для него команду put со значением disabled, а затем прочитайте его ещё раз. Не определяйте место назначения только по папке проекта.
Теперь потренируйтесь удалять устаревший флаг. Эти команды затрагивают только временное удалённое пространство имён, подключённое через FLAGS.
npx wrangler kv key put banner:old retired --binding FLAGS --remote
npx wrangler kv key list --binding FLAGS --remote
Список содержит имена, например banner:new и banner:old, а не сохранённые значения. Используйте get, когда нужно получить значение.
npx wrangler kv key delete banner:old --binding FLAGS --remote
npx wrangler kv key list --binding FLAGS --remote
npx wrangler kv key list --binding FLAGS --local
Теперь оба списка должны содержать только banner:new. При необходимости снова прочитайте оба значения и убедитесь, что они по-прежнему различаются. Удаление ключа удаляет одну запись, а последующее удаление пространства имён удалит весь контейнер.
KV использует согласованность в конечном счёте: изменения могут появляться в чтении из других мест не сразу. Worker временно может увидеть предыдущее значение, в том числе ранее отсутствовавший ключ. Не перезаписывайте значение многократно, чтобы принудительно сделать его видимым. Эти безвредные флаги отображения допускают такую задержку, но они не подходят для немедленного решения об отзыве доступа. Поведение будет рассмотрено в одной из следующих лабораторных работ. Подробнее о модели хранения см. в разделе как работает KV.
Чтение флага из локального Worker
На этом шаге вы свяжете поведение приложения с сохранённой настройкой. Worker читает env.FLAGS, где env содержит настроенные привязки ресурсов. Метод get() выполняется асинхронно, поэтому await дожидается его значения, прежде чем код определит возвращаемый ответ.
Запишите обработчик. Взятый в кавычки разделитель JS сохраняет JavaScript без изменений и не позволяет оболочке подставлять переменные.
cat > src/index.js <<'JS'
export default {
async fetch(request, env) {
if (new URL(request.url).pathname !== "/banner") {
return new Response("Not found", { status: 404 });
}
const value = await env.FLAGS.get("banner:new");
return Response.json({
feature: "new-banner",
enabled: value === "enabled"
});
}
};
JS
Если ключ отсутствует, возвращается null. Сравнение именно со значением "enabled" означает, что при отсутствии ключа или неожиданном значении этот необязательный баннер останется отключённым. Это простой безопасный вариант по умолчанию: приложение продолжает работать, если настройка не задана. Он не скрывает ошибки подключения, которые отличаются от отсутствующего ключа.
Запустите локальную разработку. Параметр --local запускает Worker в этой виртуальной машине с локальными привязками. > local.log 2>&1 направляет обычный вывод и ошибки в журнал, а & позволяет терминалу принимать следующие команды. $! — идентификатор фонового процесса; здесь он сохраняется, чтобы позже остановить этот процесс.
npx wrangler dev --local --ip 0.0.0.0 --port 8080 > local.log 2>&1 &
DEV_PID=$!
cat local.log
Дождитесь сообщения о готовности на порту 8080. Если запуск ещё продолжается, снова прочитайте журнал перед тем, как двигаться дальше.
curl -i http://127.0.0.1:8080/banner
curl -i показывает заголовки и тело ответа. Ожидайте HTTP-код 200, тип содержимого JSON и такой ответ:
{"feature":"new-banner","enabled":true}
Значение true получено из локального хранилища KV. Запуск сервера разработки не скопировал отключённое значение disabled из удалённого хранилища в виртуальную машину. Оставьте сервер запущенным для следующего сравнения.
Развёртывание и сравнение публичного ответа
На этом шаге вы опубликуете тот же код и увидите, как он читает облачное пространство имён. Развёртывание загружает Worker и его конфигурацию привязок, но не загружает локальные записи KV.
npx wrangler deploy
Изучите вывод развёртывания. Убедитесь, что в нём указаны имя Worker, привязка FLAGS и публичный адрес workers.dev. Сохраните фактический адрес ниже, заменив пример перед выполнением команды. Переменная оболочки избавит вас от повторного ввода длинного URL.
WORKER_URL="https://YOUR_WORKER.YOUR_SUBDOMAIN.workers.dev"
curl -i "$WORKER_URL/banner"
Ожидайте HTTP-код 200 и такой ответ:
{"feature":"new-banner","enabled":false}
Облачная настройка имеет значение disabled, поэтому в публичном ответе указано false. Если новый хост ещё недоступен, немного подождите и повторите запрос. Если ответ отражает предыдущее значение, один раз проверьте удалённый ключ и подождите, пока KV станет доступным для чтения, вместо того чтобы быстро перезаписывать значение. Ошибка сети не считается успешной проверкой.
curl -i http://127.0.0.1:8080/banner
Локальный ответ по-прежнему содержит true. У вас есть один обработчик и два отдельных хранилища данных: локальная разработка читает данные виртуальной машины, а развёрнутый Worker читает пространство имён, указанное привязкой.
В Cloudflare Dashboard выберите тот же учебный аккаунт и откройте Storage & databases → Workers KV. Найдите пространство имён с именем этой лабораторной работы и просмотрите его ключи. Убедитесь, что остался только banner:new со значением disabled. Затем откройте Workers & Pages, выберите Worker этой лабораторной работы и просмотрите представление Bindings. Сравните привязку FLAGS с только что просмотренным пространством имён. Это проверки только для чтения: изменения выполняются в терминале.
Пространство имён открывается на вкладке Metrics. Выберите KV Pairs, чтобы проверить реальные записи: счётчики использования могут обновляться позже записей. Если новый Worker отсутствует в Workers & Pages, нажмите Refresh. В Bindings прокрутите страницу до таблицы и сравните имя привязки с пространством имён.
Сгенерированное имя, идентификатор пространства имён и публичный поддомен отличаются от примеров. Наличие пространства имён в Dashboard подтверждает, где оно находится, а успешный HTTP-ответ подтверждает, что приложение может его использовать.
Удаление временных облачных ресурсов
На этом шаге вы удалите оба ресурса, пока Wrangler всё ещё авторизован. Пространство имён может существовать дольше Worker, поэтому удаление приложения само по себе не очищает его данные.
Остановите процесс локальной разработки, запущенный в этом терминале:
kill "$DEV_PID"
Перед удалением просмотрите сохранённые ссылки на ресурсы:
cat wrangler.jsonc
Убедитесь, что указаны имя Worker labex-flags-... и идентификатор пространства имён FLAGS. Удалите Worker, выбранный этой конфигурацией:
npx wrangler delete
Если появится запрос подтверждения, проверьте, что отображаемое имя относится к этой лабораторной работе, и подтвердите удаление с помощью y. Затем удалите только пространство имён, указанное привязкой FLAGS:
npx wrangler kv namespace delete --binding FLAGS
Перед подтверждением проверьте пространство имён в запросе. Не изменяйте файл wrangler.jsonc, чтобы независимая проверка могла определить ресурсы, которые должны отсутствовать.
npx wrangler kv namespace list
Пространство имён этой лабораторной работы должно отсутствовать, а сторонние пространства имён должны сохраниться. Обновите списки в Dashboard и убедитесь, что Worker и пространство имён этой лабораторной работы исчезли. Ошибка запроса или истёкшая авторизация не доказывают, что удаление выполнено. Запустите проверку этого шага до выхода из аккаунта, чтобы она могла просмотреть авторизованный список ресурсов.
Завершение авторизации виртуальной машины
На этом шаге вы отключите Wrangler после успешной проверки очистки. Выход завершает сохранённую авторизацию Wrangler на этой виртуальной машине, но не удаляет облачные ресурсы и не выполняет выход из обычной сессии Dashboard в браузере.
npx wrangler logout
npx wrangler whoami --json
Убедитесь, что структурированный результат содержит "loggedIn": false. Эта команда без авторизации может завершиться с ненулевым кодом выхода — в данном случае это ожидаемо. Если отображается только ошибка подключения без явного состояния авторизации, повторите команду после восстановления подключения.
Оставшиеся локальные файлы и локальное состояние KV принадлежат этой временной виртуальной машине. Они не связаны с облачными ресурсами, которые вы уже удалили. Теперь лабораторную работу можно завершить.
Итоги
Вы создали изолированное пространство имён KV, подключили его с помощью привязки и использовали явные локальные и удалённые команды для записи, чтения, просмотра списка и удаления ключей. Worker читал один и тот же ключ из разных хранилищ: локальный баннер был включён, а публичный баннер оставался отключённым. Вы также использовали безопасное значение по умолчанию для отсутствующего флага и узнали, почему обновления KV нельзя считать мгновенным глобальным переключателем.
Наконец, вы проверили публичный ответ, удалили Worker и пространство имён с действующей авторизацией и вышли из Wrangler. Далее вы будете использовать структурированные значения JSON для предоставления несекретных настроек аккаунта.
