وضعیت
توسعهدهندهای یک وبسایت استاتیک را داخل یک ساندباکس (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]
سؤالها
- کدام سمت اتصال را رد کرد: سرور داخل ساندباکس یا بایندینگ (Binding) روی هاست؟ چه چیزی در خروجی این موضوع را نشان میدهد؟
- انتشار بدون تعیین پروتکل به چه آدرسهایی بایند میشود، و این رفتار از کدام نسخه تغییر کرده است؟
- چطور پورت را منتشر کنیم تا هر دو لوپبک پاسخ دهند؟
- فلگ
p-در دستورsbx runهنگام اتصال مجدد (Re-attach) کمکی نکرد. چرا؟ - چطور یک بایندینگ را حذف کنیم، و چگونه مطمئن شویم که حذف شده است؟
اول شواهد را بخوانید و به سؤالها جواب بدهید، بعد راهحل را باز کنید.
راهحل گامبهگام
- ستون پروتکل را بخوانید. در پاسخ به انتشار پیام
Published 127.0.0.1:18081 -> 8080/tcp4برگشت، و فهرست خروجی یک ردیف با آدرس هاست127.0.0.1و پروتکلtcp4را نشان میدهد. بایندینگ هاست فقط IPv4 است. سرور داخل ساندباکس اصلاً درخواستی دریافت نکرده بود. - با دو درخواست ارسالی مطمئن شوید. آدرس
127.0.0.1:18081کد وضعیت 200 را برمیگرداند. ارتباط با[::1]:18081برقرار نمیشود و curl با کد خروج 7 پایان مییابد. سمتی که خطا میدهد، لوپبک هاست است که هیچ سرویسی روی آن گوش نمیدهد. - قاعده را مشخص کنید. بدون تعیین پروتکل، انتشار از
tcp4استفاده میکند؛ بنابراین در سمت هاست فقط127.0.0.1بایند میشود. راهنما تاریخ این تغییر را نگارش v0.42.0 ذکر میکند: پورتی که منتشر میشود دیگر روی::1گوش نمیدهد مگر اینکه پروتکل را صریح بنویسید. پلاگین سال 2025 به هر دو لوپبک بایند میشد، که با رکوردهای C39 تداخل دارد. دستورsbx lsنیز همین بایندینگ را در ستونPORTSنشان میدهد. - برای هر دو خانوادهی آدرس منتشر کنید. دستور
--publish 8080/tcpآدرسهای127.0.0.1و[::1]را روی پورتهای موقت هاست بایند میکند، وsbx ports --jsonسه رکورد را فهرست میکند: اولین بایندینگِtcp4و دو بایندینگِtcp، یعنی برای هر آدرس یکی. هر وقت بستر آزمایشی به پورتی ثابت نیاز داشت، پورت هاست را در الگو مشخص کنید. - موارد غیرلازم را حذف کنید. دستورهای
--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 ثبت کرده است.