სახელმძღვანელო გამართვის (Debugging) შესახებ

წინამდებარე სახელმძღვანელო დაგეხმარებათ შეისწავლოთ Node.js-აპლიკაციებისა და სკრიპტების გამართვა.

ინსპექტორის გააქტიურება

როდესაც --inspect არგუმენტით ეშვება, Node.js-პროცესი უსმენს შეცდომათა აღმომჩენ (გამმართავ) კლიენტს. ნაგულისხმევად, იგი მოუსმენს შემდეგ ჰოსტზე (მასპინძელზე) და პორტზე: 127.0.0.1:9229. თითოეულ პროცესს ასევე ენიჭება უნიკალური UUID.

კავშირის დასამყარებლად ინსპექტორმა კლიენტებმა უნდა იცოდნენ და მიუთითონ ჰოსტის მისამართი, პორტი და UUID. სრული URL დაახლოებით ასე უნდა გამოიყურებოდეს: ws://127.0.0.1:9229/0f2c936f-b1cd-4ac9-aab3-f63b0f33d55e.

Node.js ასევე დაიწყებს გამართვის შეტყობინებათა მოსმენას, თუკი იგი მიიღებს SIGUSR1 სიგნალს (SIGUSR1 ხელმისაწვდომი არ არის Windows-ის გარემოში). Node.js-ის მე-7 და უფრო ძველ ვერსიებში ეს გაააქტიურებს მოძველებულ Debugger API-ს. Node.js-ის მე-8 და უფრო ახალ ვერსიებში Inspector API გააქტიურდება.

გავლენა უსაფრთხოების დონეზე

რამდენადაც გამმართველს სრული წვდომა აქვს Node.js გამშვებ გარემოზე, ბოროტმოქმედს, რომელსაც შეუძლია ამ პორტთან დაკავშირება, შესაძლებლობა ეძლევა Node.js-პროცესის სახელით გაუშვას თვითნებური კოდი. აქედან გამომდინარე, მნიშვნელოვანია გვესმოდეს გამმართველის პორტის საჯარო ან კერძო ქსელში გამჟღავნების [უარყოფითი] გავლენა უსაფრთხოების დონეზე.

გამართვის (debug) პორტის გასაჯაროება სახიფათოა

თუ გამმართველი მიბმულია საჯარო IP-მისამართთან ან 0.0.0.0-თან, ნებისმიერ კლიენტს, რომელსაც წვდომა აქვს თქვენს IP-მისამართთან, ყოველგვარი შეზღუდის გარეშე შეძლებს გამმართველთან დაკავშირებას და თვითნებური კოდის გაშვებას.

ნაგულისხმევად, node --inspect ებმის 127.0.0.1-ს. გამმართველთან გარე კავშირების დასაშვებად, ცალსახად დაგჭირდებათ, უზრუნველყოთ საჯარო IP-მისამართი ან 0.0.0.0 და ა.შ. [თუმცა,] ამის გაკეთებამ, შესაძლოა პოტენციურად საყურადღებო უსაფრთხოების რისკების წინაშე დაგაყენოთ. ჩვენ გირჩევთ, უზრუნველყოთ სათანადო firewall-ებისა და წვდომის კონტროლის არსებობა, რათა თავიდან აიცილოთ მსგავსი საფრთხეები.

იხილეთ განყოფილება „დისტანციური გამართვის სცენართა გააქტიურება“, რომელშიც მოცემულია რამდენიმე რჩევა იმის შესახებ, თუ როგორ მივცეთ დისტანციურ გამმართველ კლიენტებს უსაფრთხოდ დაკავშირების ნებართვა.

ლოკალურ აპლიკაციებს აქვთ სრული წვდომა ინსპექტორზე

მაშინაც კი, თუ თქვენ ინსპექტორის პორტს მიაბამთ 127.0.0.1-ს (ნაგულისხმევი), ლოკალურად, თქვენს მოწყობილობაზე გაშვებულ ნებისმიერ აპლიკაციას ექნება შეუზღუდავი წვდომა. ასე იმისათვის ხდება, რომ ლოკალურ გამმართველებს მიეცეთ ადვილად მიმაგრების საშუალება.

ბრაუზერები, WebSocket-ები და იგივე წარმოშობის (same-origin) პოლიტიკა

ვებბრაუზერში გახსნილ ვებსაიტებს შეუძლიათ განახორციელონ WebSocket- და HTTP-მოთხოვნები ბრაუზერის უსაფრთხოების მოდელის მიხედვით. საწყისი HTTP კავშირი აუცილებელია გამმართველის სესიის უნიკალური id-ის მისაღებად. იგივე წარმოშობის პოლიტიკა (same-origin-policy) ხელს უშლის ვებსაიტებს ამ HTTP-კავშირის დამყარებაში. დამატებითი დაცვისათვის DNS rebinding შეტევების წინააღმდეგ, Node.js ამოწმებს, ზუსტად არის თუ არა მითითებული კავშირის 'Host' სათაურებში (headers) IP-მისამართი, localhost ან localhost6.

ეს უსაფრთხოების წესები კრძალავს დისტანციურ გამართვის სერვერთან დაკავშირებას ჰოსტის სახელის (hostname) მითითებით. ამ შეზღუდვისათვის გვერდის ავლა შეგიძლიათ IP-მისამართის მითითებით ან ssh-გვირაბების (tunnels) გამოყენებით, როგორც ეს ქვემოთ არის აღწერილი.

ინსპექტორი კლიენტები

მინიმალისტური CLI-გამმართველი ხელმისაწვდომია ბრძანებით node inspect myscript.js. Node.js-ინსპექტორთან დაკავშირება ასევე შეუძლია რამდენიმე კომერციულ და ღიად ხელმისაწვდომ ინსტრუმენტს.

Chrome დეველოპერის ინსტრუმენტები 55+, Microsoft Edge

ვარიანტი 1: გახსენით chrome://inspect Chromium-ზე დაფუძნებულ ბრაუზერში ან edge://inspect — Edge-ში. დააწკაპუნეთ Configure ღილაკზე და დარწმუნდით, რომ სასურველი ჰოსტი და პორტი არის ჩამონათვალში.
ვარიანტი 2: დააკოპირეთ devtoolsFrontendUrl მნიშვნელობა /json/list-დან (იხილეთ ზემოთ) ან --inspect მიმნიშნებელი ტექსტი და ჩასვით Chrome-ში.

გაითვალისწინეთ, რომ Node.js და Chrome ერთსა და იმავე პლატფორმაზე უნდა გაეშვას.

Visual Studio Code 1.10+

„გამართვის“ (Debug) პანელში დააწკაპუნეთ პარამეტრების ხატულაზე, რათა გახსნათ .vscode/launch.json [ფაილი]. აირჩიეთ „Node.js“ საწყისი მოწყობისათვის.

Visual Studio 2017+

მენიუდან აირჩიეთ „Debug > Start Debugging“ ან დააჭირეთ F5-ს.
დეტალური ინსტრუქციები.

JetBrains WebStorm და სხვა JetBrains IDE-ები

შექმენით ახალი Node.js გამართვის კონფიგურაცია და დააჭირეთ „Debug“ ღილაკს. --inspect ნაგულისხმევად იქნება გამოყენებული Node.js 7+-ისთვის. გამოსართავად, IDE-რეესტრში მოხსენით მონიშვნა (uncheck) js.debugger.node.use.inspect-ს. WebStorm-ში და სხვა JetBrains IDE-ებში Node.js-ის გაშვებასა და გამართვასთან დაკავშირებით დეტალური ინფორმაციისათვის იხილეთ WebStorm ონლაინ დახმარება.

chrome-remote-interface

ბიბლიოთეკა, რომელიც ამარტივებს კავშირს Inspector Protocol-ის (ინსპექტორის პროტოკოლის) endpoint-ებთან.

Gitpod

გაუშვით Node.js გამართვის კონფიგურაცია Debug ხედიდან (view) ან დააჭირეთ F5-ს. დეტალური ინსტრუქციები.

Eclipse IDE Eclipse Wild Web Developer დამატებით (extension-ით)

გახსენით .js [გაფართოების მქონე] ფაილი, აირჩიეთ „Debug As... > Node program“, ან
შექმენით გამართვის კონფიგურაცია, რათა მიამაგროთ გამმართველი გაშვებულ Node.js-აპლიკაციას (უკვე დაიწყო --inspect-ით).

ბრძანებათა სტრიქონის არგუმენტები

ქვემოთ მოცემულ ცხრილში ჩამოთვლილია სხვადასხვა არგუმენტების — რომელთა მითითებაც შესაძლებელია გაშვების მომენტში (runtime) — გავლენა გამმართველზე:

დისტანციური გამართვის სცენართა გააქტიურება

ჩვენ გირჩევთ, არასოდეს დაუშვათ გამმართველის მოსმენა საჯარო IP-მისამართზე. თუ გჭირდებათ, რომ დაუშვათ დისტანციური კავშირები გამართვისათვის, გირჩევთ გამოიყენოთ ssh-გვირაბები. ქვემოთ მოცემული მაგალითი მიზნად ისახავს მხოლოდ განმარტებას. სანამ ამას იზამდეთ, მნიშვნელოვანია გესმოდეთ უსაფრთხოებასთან დაკავშირებით არსებული საფრთხეები, რომლებსაც ჰბადებს პრივილეგირებულ სერვისთან დისტანციური კავშირის დამყარების შესაძლებლობა.

ვთქვათ, დისტანციურ მოწყობილობაზე, remote.example.com, გაშვებული გაქვთ Node.js-აპლიკაცია და გსურთ მისი გამართვა. ასეთ შემთხვევაში, ამ [დისტანციურ] მოწყობილობაზე უნდა გაუშვათ node-პროცესი ინსპექტორით, რომელიც უსმენს მხოლოდ localhost-ს (ნაგულისხმევი).

node --inspect server.js

შემდგომ ამისა, ადგილობრივ (ლოკალურ) მოწყობილობაზე, საიდანაც გსურთ წამოიწყოთ გამმართველი კლიენტის კავშირი, შეგიძლიათ შექმნათ ssh-გვირაბი:

ssh -L 9221:localhost:9229 user@remote.example.com

ეს შექმნის ssh-გვირაბის სესიას, რომელშიც კავშირი 9221 პორტთან თქვენს ადგილობრივ მოწყობილობაზე, გადამისამართდება remote.example.com-ის 9229 პორტზე. შემდგომ ამისა, თქვენ შეძლებთ გამმართველის, როგორიცაა Chrome DevTools ან Visual Studio Code, მიმაგრებას localhost:9221-ზე, და შეგეძლებათ გამართვა ისევე, როგორც იმ შემთხვევაში, როცა Node.js-აპლიკაცია გაშვებულია ადგილობრივად (ლოკალურად).

მოძველებული გამმართველი

მოძველებული გამმართველის გამოყენება მიზანშეწონილი აღარ არის Node.js 7.7.0 ვერსიიდან მოყოლებული. ნაცვლად ამისა, გამოიყენეთ ინსპექტორი (--inspect).

როცა მე-7 ან უფრო ადრინდელ ვერსიაში ეშვება --debug ან --debug-brk არგუმენტით, Node.js უსმენს გამართვის ბრძანებებს, რომლებიც განსაზღვრულია V8 გამართვის პროტოკოლით TCP პორტზე (ნაგულისხმევად 5858). ნებისმიერ გამმართველ კლიენტს, რომელსაც ესმის ეს პროტოკოლი, შეუძლია მიმდინარე პროცესთან დაკავშირება და [მისი] გამართვა; ქვემოთ ჩამოთვლილია რამდენიმე პოპულარული კლიენტი.

V8 გამართვის პროტოკოლი აღარ არის მხარდაჭერილი და მისი დოკუმენტირებაც აღარ ხორციელდება.

[ჩაშენებული გამმართველი](https://nodejs.org/dist/{#var currentVersion}/docs/api/debugger.html)

იმისათვის, რომ თქვენი სკრიპტი გაუშვათ ჩაშენებულ CLI-გამმართველთან ერთად, შეიყვანეთ ბრძანება node debug script_name.js. ამით, თქვენი სკრიპტი გაეშვება --debug-brk პარამეტრით სხვა Node-პროცესში, ხოლო საწყისი Node-პროცესი გაუშვებს _debugger.js სკრიპტს და დაუკავშირდება თქვენს სამიზნეს (თქვენს სამიზნე სკრიპტს).

node-inspector

გამართეთ თქვენი Node.js-აპლიკაცია Chrome DevTools-ით შუამავალი პროცესის გამოყენებით, რომელიც Chromium-ში გამოყენებულ Inspector Protocol-ს (ინსპექტორის პროტოკოლს) თარგმნის Node.js-ში გამოყენებულ V8 გამმართველ პროტოკოლად.