Настройка корпоративной сети

Обзор

В корпоративных средах приложениям часто приходится работать за корпоративными прокси и использовать пользовательские центры сертификации (CA) для проверки SSL/TLS. Node.js предоставляет встроенную поддержку этих требований через переменные окружения и флаги командной строки, во многих случаях избавляя от необходимости в сторонних прокси-библиотеках.

Это руководство описывает, как настроить приложения на Node.js для работы в корпоративных сетевых средах:

Настройка прокси через переменную окружения NODE_USE_ENV_PROXY или флаг --use-env-proxy
Добавление центров сертификации из системного хранилища через переменную окружения NODE_USE_SYSTEM_CA или флаг --use-system-ca.

Настройка прокси

Во многих корпоративных средах доступ в интернет к внешним сервисам может потребоваться маршрутизировать через HTTP/HTTPS-прокси в целях безопасности и мониторинга. Это требует, чтобы приложения знали об этих прокси и использовали их при сетевых запросах.

Настройки прокси часто задаются через переменные окружения, такие как HTTP_PROXY, HTTPS_PROXY и NO_PROXY. Node.js поддерживает их, когда включён NODE_USE_ENV_PROXY или --use-env-proxy. Это работает с методами node:http и node:https (v22.21.0 или v24.5.0+), а также с fetch() (v22.21.0 или v24.0.0+).

Пример (POSIX-шеллы):

# Настройки прокси могут быть заданы в системе вашим IT-отделом
# и общими для разных инструментов.
export HTTP_PROXY=http://proxy.company.com:8080
export HTTPS_PROXY=http://proxy.company.com:8080
export NO_PROXY=localhost,127.0.0.1,.company.com

# Чтобы включить это для приложений на Node.js.
export NODE_USE_ENV_PROXY=1
node app.js

Shell

Как вариант, включите это через флаг командной строки --use-env-proxy в Node.js v22.21.0 или v24.5.0 и выше:

# Настройки прокси могут быть заданы в системе вашим IT-отделом
# и общими для разных инструментов.
export HTTP_PROXY=http://proxy.company.com:8080
export HTTPS_PROXY=http://proxy.company.com:8080
export NO_PROXY=localhost,127.0.0.1,.company.com

# Чтобы включить это для приложений на Node.js.
node --use-env-proxy app.js

Shell

Или, если для загрузки переменных окружения из файла используется --env-file:

# В файле .env
HTTP_PROXY=http://proxy.company.com:8080
HTTPS_PROXY=http://proxy.company.com:8080
NO_PROXY=localhost,127.0.0.1,.company.com
NODE_USE_ENV_PROXY=1

txt

После включения запросы http, https и fetch() по умолчанию используют настроенные прокси, если только не переопределён агент или цель не совпадает с NO_PROXY.

Настройка прокси программно

Чтобы настроить прокси программно, переопределите агентов. В настоящее время это поддерживается https.request() и другими построенными на нём методами, такими как https.get().

Чтобы переопределить агента для конкретного запроса, используйте опцию agent в http.request()/https.request() и подобных методах:

const https = require('node:https');

// Создаём пользовательского агента с поддержкой пользовательского прокси.
const agent = new https.Agent({
  proxyEnv: { HTTPS_PROXY: 'http://proxy.company.com:8080' },
});

https.request(
  {
    hostname: 'www.external.com',
    port: 443,
    path: '/',
    agent,
  },
  res => {
    // Этот запрос будет проксирован через proxy.company.com:8080 по протоколу HTTP.
  }
);

JavaScript

Чтобы переопределить агента глобально, переустановите http.globalAgent и https.globalAgent:

Примечание: глобальные агенты не влияют на fetch().

const http = require('node:http');
const https = require('node:https');

http.globalAgent = new http.Agent({
  proxyEnv: { HTTP_PROXY: 'http://proxy.company.com:8080' },
});
https.globalAgent = new https.Agent({
  proxyEnv: { HTTPS_PROXY: 'http://proxy.company.com:8080' },
});

// Последующие запросы все будут использовать настроенные прокси, если только не переопределят опцию agent.
http.request('http://external.com', res => {
  /* ... */
});
https.request('https://external.com', res => {
  /* ... */
});

JavaScript

Использование прокси с аутентификацией

Если прокси требует аутентификации, укажите учётные данные в URL прокси:

export HTTPS_PROXY=http://username:password@proxy.company.com:8080

Примечание по безопасности: избегайте коммита учётных данных в env-файлы. Предпочитайте менеджер секретов и программную настройку.

Настройка обхода прокси

Переменная NO_PROXY поддерживает:

* — обход прокси для всех хостов
company.com — точное совпадение имени хоста
.company.com — совпадение по суффиксу домена (совпадает с sub.company.com)
*.company.com — совпадение домена по маске (wildcard)
192.168.1.100 — точное совпадение IP-адреса
192.168.1.1-192.168.1.100 — диапазон IP-адресов
company.com:8080 — имя хоста с конкретным портом

Если цель совпадает с NO_PROXY, запрос обходит прокси.

Настройка центров сертификации

По умолчанию Node.js использует набор корневых CA от Mozilla и не обращается к хранилищу ОС. Во многих корпоративных средах внутренние CA установлены в хранилище ОС и должны считаться доверенными при подключении к внутренним сервисам; подключения к сертификатам, подписанным этими CA, могут не проходить проверку с ошибками вроде:

Error: self signed certificate in certificate chain

Начиная с Node.js v22.19.0, v24.6.0 и выше Node.js можно настроить на доверие этим пользовательским CA с помощью системного хранилища сертификатов.

Добавление сертификатов CA из системного хранилища

Через переменную окружения: NODE_USE_SYSTEM_CA=1 node app.js
Через флаг командной строки: node --use-system-ca app.js

Когда это включено, Node.js загружает системные CA и использует их в дополнение к встроенным CA при проверке TLS.

Node.js читает сертификаты из разных мест в зависимости от платформы:

Windows: Windows Certificate Store (через Windows Crypto API)
macOS: macOS Keychain
Linux: значения по умолчанию OpenSSL, обычно через SSL_CERT_FILE/SSL_CERT_DIR или пути вроде /etc/ssl/cert.pem и /etc/ssl/certs/ в зависимости от сборки OpenSSL

Node.js следует политике, похожей на политику Chromium. Подробнее см. документацию Node.js.

Добавление дополнительных сертификатов CA

Чтобы добавить конкретные сертификаты CA, не полагаясь на системное хранилище:

export NODE_EXTRA_CA_CERTS=/path/to/company-ca-bundle.pem
node app.js

Shell

Файл должен содержать один или несколько сертификатов в PEM-кодировке.

Комбинирование опций

Можно комбинировать NODE_USE_SYSTEM_CA с NODE_EXTRA_CA_CERTS:

export NODE_USE_SYSTEM_CA=1
export NODE_EXTRA_CA_CERTS=/path/to/additional-cas.pem
node app.js

Shell

Если включены обе опции, Node.js доверяет встроенным CA, системным CA и дополнительным сертификатам, указанным в NODE_EXTRA_CA_CERTS.

Настройка сертификатов CA программно

Настройка глобальных сертификатов CA

Используйте tls.getCACertificates() и tls.setDefaultCACertificates() для настройки глобальных сертификатов CA. Например, чтобы добавить системные сертификаты в хранилище по умолчанию:

const https = require('node:https');
const tls = require('node:tls');
const currentCerts = tls.getCACertificates('default');
const systemCerts = tls.getCACertificates('system');
tls.setDefaultCACertificates([...currentCerts, ...systemCerts]);

// Последующие запросы при проверке используют системные сертификаты.
https.get('https://internal.company.com', res => {
  /* ... */
});
fetch('https://internal.company.com').then(res => {
  /* ... */
});

JavaScript

Настройка сертификатов CA для отдельных запросов

Чтобы переопределить сертификаты CA для конкретного запроса, используйте опцию ca. В настоящее время это поддерживается только tls.connect()/https.request() и построенными на них методами, такими как https.get().

const https = require('node:https');
const specialCerts = ['-----BEGIN CERTIFICATE-----\n...'];
https.get(
  {
    hostname: 'internal.company.com',
    port: 443,
    path: '/',
    method: 'GET',
    // Опция `ca` заменяет значения по умолчанию; при необходимости конкатенируйте встроенные сертификаты.
    ca: specialCerts,
  },
  res => {
    /* ... */
  }
);

JavaScript