سناریوی رخداد

پورتی که فقط روی یکی از آدرس‌های لوپ‌بک پاسخ می‌داد

A published port that answered on one loopback

  • سطح ۱: غربالگری
  • سناریوی رخداد
  • ۱۵ دقیقه

وضعیت

توسعه‌دهنده‌ای یک وب‌سایت استاتیک را داخل یک ساندباکس (Sandbox) روی پورت 8080 اجرا کرده و با دستور sbx ports m101-demo --publish 18081:8080 آن را به هاست فوروارد (Publish) می‌کند. مرورگر روی هاست صفحه را باز می‌کند. اما یک بستر آزمایشی (test harness) روی همان هاست گزارش می‌دهد که نتوانسته متصل شود، و لاگ‌های آن نشان می‌دهد که تلاش کرده به ::1 وصل شود. توسعه‌دهنده شک می‌کند که سرور داخل ساندباکس فقط روی یک اینترفیس گوش می‌دهد و شروع به دست‌کاری تنظیمات آن می‌کند.

شما دستور انتشار (Publish) و فهرست حاصل از آن، فراخوانی همان URL روی هر دو آدرس لوپ‌بک، فهرست موجود در sbx ls، دستور دوم انتشار همراه با نام پروتکل، و فراخوانی‌های لغو انتشار (Unpublish) را در اختیار دارید.

نسخه
sbx v0.47.0
مدل
none; shell commands inside the sandbox
سخت‌افزار
one Mac with the microVM runtime

شواهد

a-dual-stack-publish.txt
title: a publish with the protocol named, and the JSON listing
source: manuals/docker-sandboxes-101/capture/out/05-ports-tcp.txt
lang: console
note: Read the host_ip of each record.
---
$ sbx ports m101-demo --publish 8080/tcp
Published 127.0.0.1:<port> -> 8080/tcp
Published [::1]:<port> -> 8080/tcp
[exit 0]

$ sbx ports m101-demo --json
[
  {
    "host_ip": "127.0.0.1",
    "host_port": 18081,
    "sandbox_port": 8080,
    "protocol": "tcp4"
  },
  {
    "host_ip": "127.0.0.1",
    "host_port": "<port>",
    "sandbox_port": 8080,
    "protocol": "tcp"
  },
  {
    "host_ip": "::1",
    "host_port": "<port>",
    "sandbox_port": 8080,
    "protocol": "tcp"
  }
]
[exit 0]
publish-and-list.txt
title: a port published without a protocol, and the listing
source: manuals/docker-sandboxes-101/capture/out/05-ports.txt
lang: console
note: Read the protocol column.
---
$ sbx ports m101-demo --publish 18081:8080
Published 127.0.0.1:18081 -> 8080/tcp4
[exit 0]

$ sbx ports m101-demo
HOST IP     HOST PORT   SANDBOX PORT   PROTOCOL
127.0.0.1   18081       8080           tcp4
[exit 0]
the-ports-column.txt
title: the binding in the PORTS column of sbx ls
source: manuals/docker-sandboxes-101/capture/out/05-ports-ls.txt
lang: console
note: The column names the host address and the protocol.
---
$ sbx ls
SANDBOX     AGENT   STATUS    PORTS                        WORKSPACE
m101-demo   shell   running   127.0.0.1:18081->8080/tcp4   $CAPTURE/fixtures/repo
[exit 0]
two-loopbacks.txt
title: the same URL on the two loopback addresses
source: manuals/docker-sandboxes-101/capture/out/05-ports-curl.txt
lang: console
note: Read the status code and the exit code of each request.
---
$ curl -sS -o /dev/null -w '%{http_code}\n' http://127.0.0.1:18081/README.md
200
[exit 0]

$ curl -sS -o /dev/null -w '%{http_code}\n' 'http://[::1]:18081/README.md'
curl: (7) Failed to connect to ::1 port 18081 after <n> ms: Couldn't connect to server
000
[exit 7]
unpublish.txt
title: two unpublish calls and the empty listing
source: manuals/docker-sandboxes-101/capture/out/05-ports-unpublish.txt
lang: console
note: The spec of each unpublish matches the spec that published it.
---
$ sbx ports m101-demo --unpublish 18081:8080
Unpublish requested for port 18081 -> 8080
[exit 0]

$ sbx ports m101-demo --unpublish <port>:8080/tcp
Unpublish requested for port <port> -> 8080/tcp
[exit 0]

$ sbx ports m101-demo --json
[]
[exit 0]

سؤال‌ها

  1. کدام سمت اتصال را رد کرد: سرور داخل ساندباکس یا بایندینگ (Binding) روی هاست؟ چه چیزی در خروجی این موضوع را نشان می‌دهد؟
  2. انتشار بدون تعیین پروتکل به چه آدرس‌هایی بایند می‌شود، و این رفتار از کدام نسخه تغییر کرده است؟
  3. چطور پورت را منتشر کنیم تا هر دو لوپ‌بک پاسخ دهند؟
  4. فلگ p- در دستور sbx run هنگام اتصال مجدد (Re-attach) کمکی نکرد. چرا؟
  5. چطور یک بایندینگ را حذف کنیم، و چگونه مطمئن شویم که حذف شده است؟

اول شواهد را بخوانید و به سؤال‌ها جواب بدهید، بعد راه‌حل را باز کنید.

راه‌حل گام‌به‌گام
  1. ستون پروتکل را بخوانید. در پاسخ به انتشار پیام Published 127.0.0.1:18081 -> 8080/tcp4 برگشت، و فهرست خروجی یک ردیف با آدرس هاست 127.0.0.1 و پروتکل tcp4 را نشان می‌دهد. بایندینگ هاست فقط IPv4 است. سرور داخل ساندباکس اصلاً درخواستی دریافت نکرده بود.
  2. با دو درخواست ارسالی مطمئن شوید. آدرس 127.0.0.1:18081 کد وضعیت 200 را برمی‌گرداند. ارتباط با [::1]:18081 برقرار نمی‌شود و curl با کد خروج 7 پایان می‌یابد. سمتی که خطا می‌دهد، لوپ‌بک هاست است که هیچ سرویسی روی آن گوش نمی‌دهد.
  3. قاعده را مشخص کنید. بدون تعیین پروتکل، انتشار از tcp4 استفاده می‌کند؛ بنابراین در سمت هاست فقط 127.0.0.1 بایند می‌شود. راهنما تاریخ این تغییر را نگارش v0.42.0 ذکر می‌کند: پورتی که منتشر می‌شود دیگر روی ::1 گوش نمی‌دهد مگر اینکه پروتکل را صریح بنویسید. پلاگین سال 2025 به هر دو لوپ‌بک بایند می‌شد، که با رکوردهای C39 تداخل دارد. دستور sbx ls نیز همین بایندینگ را در ستون PORTS نشان می‌دهد.
  4. برای هر دو خانواده‌ی آدرس منتشر کنید. دستور --publish 8080/tcp آدرس‌های 127.0.0.1 و [::1] را روی پورت‌های موقت هاست بایند می‌کند، و sbx ports --json سه رکورد را فهرست می‌کند: اولین بایندینگِ tcp4 و دو بایندینگِ tcp، یعنی برای هر آدرس یکی. هر وقت بستر آزمایشی به پورتی ثابت نیاز داشت، پورت هاست را در الگو مشخص کنید.
  5. موارد غیرلازم را حذف کنید. دستورهای --unpublish 18081:8080 و --unpublish <port>:8080/tcp هرکدام نگاشت خود را حذف می‌کنند و فهرست JSON در پایان خالی می‌شود. فلگ p- در sbx run فقط هنگام ساخت اعمال می‌شود؛ بنابراین تغییرات بعدی باید از طریق sbx ports انجام شوند.
نتیجه

سرور مشکلی نداشت. بایندینگ هاست از نوع tcp4 بود، به همین دلیل فقط 127.0.0.1 گوش می‌داد و اتصال بستر آزمایشی به ::1 به هیچ شنونده‌ای نرسید. با انتشار 8080/tcp همراه با تعیین پورت ثابت هاست، هر دو لوپ‌بک بایند می‌شوند و بستر آزمایشی وصل می‌شود. تغییرات اعمال‌شده داخل ساندباکس برگردانده می‌شوند.

مسیرهای اشتباه رایج
  • «سرور داخل ساندباکس را طوری تنظیم کنید که روی همه‌ی اینترفیس‌ها گوش دهد.» سیستم مهمان همان موقع هم از طریق نگاشت IPv4 پاسخ می‌داد. شنونده‌ای که وجود نداشت، روی لوپ‌بک هاست بود.
  • «در sbx run بعدی از p 18081:8080/tcp- استفاده کنید.» روی ساندباکس‌های موجود این فلگ نادیده گرفته می‌شود. از sbx ports استفاده کنید.
  • «IPv6 را در بستر آزمایشی خاموش کنید.» کار می‌کند، ولی قاعده‌ی بایندینگ را پنهان می‌کند و بستر آزمایشی بعدی دوباره به همین مشکل برمی‌خورد.
درس کلی

وقتی یک کلاینت به سرویسی می‌رسد و کلاینت دیگر نمی‌رسد، پیش از دست زدن به سرویس، آدرس‌هایی را که هرکدام استفاده کرده‌اند با هم مقایسه کنید. هر نگاشت پورت خانواده‌ی آدرس (Address family) مخصوص به خود را دارد، و فهرستی که آن را نشان می‌دهد جلوی یک ساعت دست‌کاریِ بیهوده در جای اشتباه را می‌گیرد.

کجای دوره آموزش داده می‌شود

صفحه‌ی پورت‌ها قاعده‌ی tcp4 و جدول پروتکل‌ها را آورده است، و دفتر ثبت تعارض‌ها این تغییر را ذیل رکورد C39 ثبت کرده است.