Skip to content

Commit d0c5760

Browse files
Artyom Popovalexandrtovmach
Artyom Popov
authored and
alexandrtovmach
committed
[ru] translation of debugging guide (#2754)
1 parent 3a485f9 commit d0c5760

File tree

2 files changed

+248
-1
lines changed

2 files changed

+248
-1
lines changed

‎locale/ru/docs/guides/debugging-getting-started.md‎

Lines changed: 247 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,247 @@
1+
---
2+
title: Отладка - Начало Работы
3+
layout: docs.hbs
4+
---
5+
6+
# <!--debugging-guide-->Руководство по отладке
7+
8+
Это руководство поможет вам начать отладку ваших приложений и скриптов Node.js.
9+
10+
## <!--enable-inspector-->Активация инспектора
11+
12+
При запуске с аргументом `--inspect` процесс Node.js прослушивает клиент отладки.
13+
По умолчанию клиент прослушивается на хосте 127.0.0.1 с портом 9229.
14+
Каждому процессу также назначается уникальный [UUID][].
15+
16+
Клиенты инспектора должны знать и указывать адрес хоста, порт и UUID для подключения.
17+
Полный URL будет выглядеть примерно так:
18+
`ws://127.0.0.1:9229/0f2c936f-b1cd-4ac9-aab3-f63b0f33d55e`.
19+
20+
Процесс Node.js также начнет прослушивать сообщения отладки, если он получит
21+
сигнал `SIGUSR1`. (`SIGUSR1` не доступен в среде Windows.) В Node.js версии 7
22+
и ниже это активирует устаревший Debugger API. В Node.js версии 8 и выше будет
23+
активирован Inspector API.
24+
25+
---
26+
## <!--security-implications-->Последствия для безопасности
27+
28+
Так как дебаггер имеет полный доступ к среде выполнения Node.js, злоумышленник,
29+
способный подключиться к этому порту, сможет выполнить произвольный код от имени
30+
процесса Node. Поэтому важно понимать последствия для безопасности при обличении
31+
порта отладчика в публичных и частных сетях.
32+
33+
### <!--exposing-the-debug-port-publicly-is-unsafe-->Публичное обличение порта отладки небезопасно
34+
35+
Если отладчик привязан к какому-либо публичному IP-адресу, или к 0.0.0.0, любой клиент,
36+
способный достичь вашего IP-адреса сможет подключиться к отладчику без каких-либо
37+
ограничений и сможет запускать произвольный код.
38+
39+
По умолчанию `node --inspect` привязывается к 127.0.0.1. Чтобы разрешить внешние подключения,
40+
вы должны явно предоставить общедоступный IP-адрес или 0.0.0.0 и т.д. Однако это может
41+
подвергнуть приложение потенциально значительной угрозе его безопасности. Мы предлагаем
42+
вам обеспечить наличие файрволов и других соответствующих средств контроля доступа для
43+
того, чтобы предотвратить такую угрозу.
44+
45+
См. раздел '[Включение сценариев удаленной отладки](#enabling-remote-debugging-scenarios)', который
46+
включает рекомендации о том, как безопасно подключить удаленные клиенты отладчика.
47+
48+
### <!--local-applications-have-full-access-to-the-inspector-->Локальные приложения имеют полный доступ к инспектору
49+
50+
Даже если вы привязали порт инспектора к 127.0.0.1 (по умолчанию), любые приложения,
51+
запущенные локально на вашем компьютере, будут иметь неограниченный доступ.
52+
Это сделано для того, чтобы локальные отладчики могли легко подключаться.
53+
54+
### <!--browsers-webSockets-same-origin-policy-->Браузеры, WebSockets, same-origin policy
55+
56+
Веб-сайты, открытые в веб-браузере, могут отправлять запросы WebSocket и HTTP
57+
в соответствии с моделью безопасности браузера. Начальное HTTP-соединение необходимо
58+
для получения уникального идентификатора сеанса отладчика. Правило ограничения домена
59+
(Same Origin Policy) не позволяет веб-сайтам устанавливать это HTTP-соединение.
60+
Для дополнительной защиты от [атак DNS rebinding](https://ru.wikipedia.org/wiki/DNS_rebinding)
61+
Node.js проверяет, что заголовки 'Host' для соединения точно указывают IP-адрес,
62+
localhost или localhost6.
63+
64+
Эти политики безопасности запрещают подключение к удаленному серверу отладки c
65+
указанием имени хоста. Вы можете обойти это ограничение, указав либо IP-адрес,
66+
либо используя ssh-туннели, как описано ниже.
67+
68+
## <!--inspector-clients-->Клиенты инспектора
69+
70+
Несколько коммерческих и открытых инструментов могут подключаться к инспектору Node.js.
71+
Основная информация по ним:
72+
73+
### [node-inspect](https://github.com/nodejs/node-inspect)
74+
75+
* Отладчик CLI, поддерживаемый Фондом Node.js, который использует [Протокол Инспектора][].
76+
* Соответствующая версия собирается вместе с Node.js,
77+
можно использовать с помощью команды `node inspect myscript.js`.
78+
* Последняя версия также может быть установлена независимо (например, `npm install -g node-inspect`)
79+
и использоваться через `node-inspect myscript.js`.
80+
81+
### [Инструменты разработчика Chrome](https://github.com/ChromeDevTools/devtools-frontend) 55+, [Microsoft Edge](https://www.microsoftedgeinsider.com)
82+
83+
* **Вариант 1**: Откройте `chrome://inspect` в браузере на основе Chromium
84+
или `edge://inspect` в браузере Edge. Нажмите кнопку Configure и убедитесь,
85+
что нужные вам хост и порт перечислены в списке.
86+
* **Вариант 2**: Скопируйте значение `devtoolsFrontendUrl` из вывода `/json/list`
87+
(`curl http://localhost:9229/json/list`) или текст подсказки --inspect и откройте его в Chrome.
88+
89+
### [Visual Studio Code](https://github.com/microsoft/vscode) 1.10+
90+
91+
* На панели "Отладка" (Debug) щелкните значок настроек, чтобы открыть файл `.vscode/launch.json`.
92+
Выберите "Node.js" для первоначальной настройки.
93+
94+
### [Visual Studio](https://github.com/Microsoft/nodejstools) 2017
95+
96+
* В меню выберите "Debug > Start Debugging" или нажмите `F5`.
97+
* [Детальные инструкции](https://github.com/Microsoft/nodejstools/wiki/Debugging).
98+
99+
### [JetBrains WebStorm](https://www.jetbrains.com/webstorm/) 2017.1+ и другие IDE JetBrains
100+
101+
* Создайте новую конфигурацию отладки Node.js и нажмите кнопку "Debug" (`Shift+F9`). `--inspect` будет
102+
использоваться по умолчанию для Node.js 7+. Чтобы отключить, снимите флажок
103+
`js.debugger.node.use.inspect` в реестре IDE.
104+
105+
### [chrome-remote-interface](https://github.com/cyrus-and/chrome-remote-interface)
106+
107+
* Библиотека для облегчения подключения к эндпоинтам Протокола Инспектора.
108+
109+
### [Gitpod](https://www.gitpod.io)
110+
* Запустите конфигурацию отладки Node.js из представления `Debug` или нажмите `F5`. [Детальные инструкции](https://medium.com/gitpod/debugging-node-js-applications-in-theia-76c94c76f0a1)
111+
112+
### [Eclipse IDE](https://eclipse.org/eclipseide) c расширением Eclipse Wild Web Developer
113+
114+
* Открыв файл .js, выберите "Debug As... > Node program", или
115+
* Создайте конфигурацию отладки, чтобы присоединить отладчик к запущенному приложению Node (уже запущенному с `--inspect`).
116+
117+
---
118+
119+
## <!--command-line-options-->Аргументы командной строки
120+
121+
В следующей таблице перечислено влияние различных runtime флагов при отладке:
122+
123+
<table class="table-no-border-no-padding">
124+
<tr><th>Флаг</th><th>Значение</th></tr>
125+
<tr>
126+
<td>--inspect</td>
127+
<td>
128+
<ul>
129+
<li>Включить инспектор</li>
130+
<li>Прослушивать адрес и порт по умолчанию (127.0.0.1:9229)</li>
131+
</ul>
132+
</td>
133+
</tr>
134+
<tr>
135+
<td>--inspect=<em>[host:port]</em></td>
136+
<td>
137+
<ul>
138+
<li>Включить инспектор</li>
139+
<li>Прослушивать адрес <em>host</em> (по умолчанию: 127.0.0.1)</li>
140+
<li>Прослушивать порт <em>port</em> (по умолчанию: 9229)</li>
141+
</ul>
142+
</td>
143+
</tr>
144+
<tr>
145+
<td>--inspect-brk</td>
146+
<td>
147+
<ul>
148+
<li>Включить инспектор</li>
149+
<li>Прослушивать адрес и порт по умолчанию (127.0.0.1:9229)</li>
150+
<li>Прервать выполнение сценария перед началом выполнения пользовательского кода</li>
151+
</ul>
152+
</td>
153+
</tr>
154+
<tr>
155+
<td>--inspect-brk=<em>[host:port]</em></td>
156+
<td>
157+
<ul>
158+
<li>Включить инспектор</li>
159+
<li>Прослушивать адрес <em>host</em> (по умолчанию: 127.0.0.1)</li>
160+
<li>Прослушивать порт <em>port</em> (по умолчанию: 9229)</li>
161+
<li>Прервать выполнение сценария перед началом выполнения пользовательского кода</li>
162+
</ul>
163+
</td>
164+
</tr>
165+
<tr>
166+
<td><code>node inspect <em>script.js</em></code></td>
167+
<td>
168+
<ul>
169+
<li>Запустить дочерний процесс для выполнения пользовательского скрипта под флагом --inspect;
170+
использовать основной процесс для запуска отладчика CLI.</li>
171+
</ul>
172+
</td>
173+
</tr>
174+
<tr>
175+
<td><code>node inspect --port=xxxx <em>script.js</em></code></td>
176+
<td>
177+
<ul>
178+
<li>Запустить дочерний процесс для выполнения пользовательского скрипта под флагом --inspect;
179+
использовать основной процесс для запуска отладчика CLI.</li>
180+
<li>Прослушивать порт <em>port</em> (по умолчанию: 9229)</li>
181+
</ul>
182+
</td>
183+
</tr>
184+
</table>
185+
186+
---
187+
188+
## <!--enabling-remote-debugging-scenarios-->Включение сценариев удаленной отладки
189+
190+
Мы рекомендуем, чтобы отладчик никогда не прослушивал общедоступный IP-адрес.
191+
Если вам необходимо разрешить удаленные подключения для отладки, мы рекомендуем
192+
использовать SSH-тунелли. Следующий пример предоставляется только в целях
193+
иллюстрации возможностей. Вы должны понимать все риски информационной безопасности,
194+
связанные с предоставлением удаленного доступа к привилегированной службе.
195+
196+
Допустим вы запускаете на удаленной машине, remote.example.com, приложение Node,
197+
которое вы хотите отлаживать. На этой машине следует запустить процесс Node
198+
с инспектором, прослушивающим только localhost (по умолчанию).
199+
200+
```bash
201+
node --inspect server.js
202+
```
203+
204+
Теперь вы можете настроить ssh-туннель на локальном компьютере, с которого
205+
вы хотите инициировать подключение клиента отладки.
206+
207+
```bash
208+
ssh -L 9221:localhost:9229 [email protected]
209+
```
210+
211+
Это запустит сессию ssh, в которой соединение с портом 9221 на вашем локальном
212+
компьютере будет перенаправлено к порту 9229 на remote.example.com. Теперь вы
213+
можете подключить к localhost:9221 отладчик, такой как Chrome DevTools или
214+
Visual Studio Code, у которого будет возможность отладки так, как если бы приложение
215+
Node.js работало локально.
216+
217+
---
218+
219+
## Устаревший Debugger
220+
221+
**Debugger API устарело начиная с Node.js версии 7.7.0.
222+
Вместо него следует использовать Inspector API с флагом --inspect.**
223+
224+
При запуске с флагом **--debug** или **--debug-brk** в версии 7 или ниже,
225+
Node.js прослушивает команды отладки, определенные протоколом
226+
отладки V8, на порту TCP (по умолчанию `5858`). Любой клиент отладки, который
227+
понимает этот протокол, может подключиться и отладить работающий процесс;
228+
пара популярных клиентов перечислены ниже.
229+
230+
Протокол отладки V8 более не поддерживается и не документируется.
231+
232+
### [Встроенный отладчик](https://nodejs.org/dist/latest-v6.x/docs/api/debugger.html)
233+
234+
Введите `node debug script_name.js` для запуска скрипта со встроенным CLI отладчиком.
235+
Сам скрипт будет запущен с флагом `--debug-brk` в другом процессе Node, а первоначальный
236+
процесс Node запускает скрипт `_debugger.js` и подключается к целевому скрипту.
237+
238+
### [node-inspector](https://github.com/node-inspector/node-inspector)
239+
240+
Отлаживайте приложение Node.js с помощью Chrome DevTools используя
241+
промежуточный процесс, который переводит протокол инспектора, используемый в Chromium,
242+
в протокол отладчика V8, используемый в Node.js.
243+
244+
<!-- refs -->
245+
246+
[Протокол Инспектора]: https://chromedevtools.github.io/debugger-protocol-viewer/v8/
247+
[UUID]: https://tools.ietf.org/html/rfc4122

‎locale/ru/docs/guides/index.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ layout: docs.hbs
88
## Общее
99

1010
* [Первые шаги](/ru/docs/guides/getting-started-guide/)
11-
* [Debugging - Getting Started](/ru/docs/guides/debugging-getting-started/)
11+
* [Отладка - начало работы](/ru/docs/guides/debugging-getting-started/)
1212
* [Easy profiling for Node.js Applications](/ru/docs/guides/simple-profiling/)
1313
* [Diagnostics - Flame Graphs](/en/docs/guides/diagnostics-flamegraph/)
1414
* [Докеризация веб-приложения Node.js](/ru/docs/guides/nodejs-docker-webapp/)

0 commit comments

Comments
 (0)