Uvicorn 監聽 0.0.0.0，但為何 API 只能用 127.0.0.1 訪問？完整解析與最佳實踐！

By徐培鈞
LinkedIn

更新日期： 2025 年 2 月 13 日

本文為 AI 描述優化 api 設計 系列文，第 5 篇：

  1. 如何設計一個商品描述優化 API？—— 完整指南
  2. 設計 AI 優化商品描述的 Prompt
  3. FastAPI：高效且易用的 Python Web 框架
  4. 介紹 Uvicorn：高效能 ASGI 伺服器
  5. Uvicorn 監聽 0.0.0.0，但為何 API 只能用 127.0.0.1 訪問？　👈進度
  6. Tenacity：強大的 Python 重試機制庫
  7. FastAPI 建立商品描述優化 API
  8. 介紹 pytest：Python 測試框架的強大選擇
  9. Python httpx 完整指南：高效的 HTTP 客戶端
  10. Pytest-Benchmark：高效能測試的基準分析工具
  11. 深入解析 monkeypatch：Python 測試中的強大工具
  12. API 自動化測試與效能優化

建議閱讀本文前，先具備 聊天機器人-建議回復 相關系列文的概念。

在使用 Uvicorn 運行 FastAPI 或其他 ASGI 應用時，你可能會注意到，當啟動伺服器時，終端機會顯示類似以下的訊息：

INFO:     Started server process [9640]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)

然而，當你嘗試訪問 API 時，卻需要使用 http://127.0.0.1:8000，而不是 http://0.0.0.0:8000。這可能讓許多開發者感到困惑：

為什麼 Uvicorn 顯示的是 0.0.0.0，但實際訪問時卻要用 127.0.0.1？這兩者有什麼區別？

本文將詳細解析這個問題，幫助你理解 0.0.0.0 與 127.0.0.1 的概念，並提供一些最佳實踐來確保你的應用運行順利。

0.0.0.0 與 127.0.0.1 到底是什麼？

這兩個 IP 地址的概念比較抽象，但其實可以用 現實世界的比喻 來理解。

0.0.0.0：一個「開放的通道」，但沒有特定的目的地

你可以把 0.0.0.0 想像成 一座機場的大門：

  • 這個機場的大門可以讓來自任何地方的人進來，但它本身 不是一個具體的地方。
  • 它只是表示「這裡是一個入口，任何人都可以進來」。

當 Uvicorn 啟動並顯示：

Uvicorn running on http://0.0.0.0:8000

這代表 Uvicorn 允許所有網絡的請求進入這個伺服器，但它自己並沒有特定的「位置」。

🚨 為什麼 0.0.0.0 不能直接在瀏覽器中訪問？

因為 0.0.0.0 只是一個「開放的入口」，但它 沒有具體的目的地，所以你的電腦不知道該把請求發送到哪裡。

🔹 比喻：

你走到機場大門，對著大門說：「我要搭飛機！」但你沒有說要去哪個航站、哪個登機門，所以機場工作人員不知道該怎麼幫你。

🛑 錯誤的做法：

http://0.0.0.0:8000  # ❌ 電腦不知道這是去哪裡

✅ 正確的做法：

http://127.0.0.1:8000  # ✅ 這是本機的具體地址

127.0.0.1：你的電腦「自己找自己」

現在來看看 127.0.0.1，這是一個 特殊的 IP 地址，代表 「本機回環（localhost）」。

你可以把 127.0.0.1 想像成 你家裡的門：

  • 這扇門只連接到你家內部，外面的人（其他設備）是進不來的。
  • 你可以從客廳走到廚房，但外面的人無法直接走進你的家。
  • 換句話說，這是一個 「自己跟自己通信的地址」，不會經過外部網絡。

🚀 當你在瀏覽器輸入 http://127.0.0.1:8000 時，發生了什麼？

  1. 你的電腦會理解：「哦，這是發給我自己的請求！」
  2. 這個請求不會經過網絡，而是直接送到 你電腦裡運行的 Uvicorn 伺服器。
  3. 伺服器收到請求後，回應 API 結果，然後你的瀏覽器就能看到 API 的輸出。

🔹 比喻：
這就像你在家裡喊：「媽媽，幫我倒杯水！」媽媽聽到後，直接從廚房拿水給你，而不需要透過電話或網絡來傳遞訊息。

✅ 正確的做法：

http://127.0.0.1:8000  # ✅ 這是你的電腦「自己找自己」

🛑 錯誤的做法：

http://0.0.0.0:8000  # ❌ 這只是個開放的入口，沒辦法直接當作地址

0.0.0.0 和 127.0.0.1 的核心區別

地址代表什麼？能不能直接用來訪問？什麼時候用？
0.0.0.0允許來自任何地方的請求，但它不是一個具體的 IP 地址❌ 不能讓你的伺服器開放給局域網或外部設備
127.0.0.1電腦自己找自己（本機回環）✅ 可以只想在本機測試 API，不讓其他設備訪問

🔹 簡單來說：

  • 0.0.0.0 是開放的入口，但不是一個具體的地址。
  • 127.0.0.1 是電腦自己的地址，用來與自己通信。

什麼是「回環（Loopback）」？

「回環」其實是一個很簡單的概念，本質上就是 「電腦自己找自己」。

我們平常在上網時，電腦會把請求發送到網路上的伺服器（例如 Google 的伺服器），然後伺服器回應我們的請求。

但是，有時候我們並不想把請求發送到網路上，而是想讓電腦自己發送請求給自己，這時候就會用到「回環」。

用現實世界來比喻「回環」

你可以把「回環」想像成 你自己寫了一封信，然後寄給自己。

  • 一般的網絡請求：
    • 你寫信給朋友（把請求發送到其他電腦）
    • 朋友收到信後，回信給你（伺服器回應你的請求）
  • 回環請求：
    • 你自己寫信給自己，然後從郵箱裡拿出來讀（電腦自己發請求給自己，不經過網絡）

127.0.0.1：專門用來「回環」的 IP

在電腦的網絡系統裡，有一組專門用來做「回環」的 IP 地址，最常見的就是：

127.0.0.1

這個地址的意思是：「請求不要發到網絡上，而是回到自己身上。」

🚀 當你在瀏覽器輸入 http://127.0.0.1:8000 時，發生了什麼？

  1. 你的電腦看到 127.0.0.1，會知道：「這個請求是給我自己的！」
  2. 你的電腦就會把這個請求直接發送給 自己內部運行的 Uvicorn 伺服器，不會經過網絡。
  3. Uvicorn 伺服器處理請求，然後把結果回應給你。

🖥️ 用更直白的方式來解釋：

  • 你在電腦上開啟了一家「餐廳」（Uvicorn 伺服器）
  • 你作為客人點了一道菜（請求 http://127.0.0.1:8000）
  • 這家餐廳 就在你的電腦裡，所以不需要透過外部送餐員，直接把菜端給你（回應 API 結果）

💡 這樣就可以讓你測試你的 API，而不需要真正上網。

為什麼需要「回環」？

✅ 回環的好處

  1. 測試 API 時不需要網絡：
    • 例如你正在開發一個網站，這個網站會向伺服器發送請求。如果你的伺服器運行在 127.0.0.1:8000，那麼你可以在電腦上直接測試，而不需要連到網際網絡。
  2. 速度快，避免網絡延遲：
    • 因為請求根本沒有離開你的電腦，所以比真正的網絡請求要快很多。
  3. 安全性高：
    • 127.0.0.1 只允許本機訪問，其他電腦無法存取，這樣可以確保你的 API 不會被外部攻擊。

127.0.0.1 VS 0.0.0.0

地址代表什麼？什麼時候用？
127.0.0.1回環地址（自己找自己），請求不會發到外部網絡當你只想在自己電腦上測試 API，不讓其他設備訪問
0.0.0.0監聽所有網絡接口，允許來自其他設備的請求當你希望 API 可以被手機或其他電腦訪問時

💡 簡單來說：

  • 如果你只是自己測試 API，用 127.0.0.1。
  • 如果你要讓其他設備（如手機、筆電）存取 API，就用 0.0.0.0，然後用你的內網 IP 訪問。

為什麼 Uvicorn 顯示 0.0.0.0 而不是 127.0.0.1？

當你啟動 Uvicorn 時，伺服器通常會顯示這樣的訊息：

Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)

你可能會疑惑：「既然 0.0.0.0 不能直接訪問，那為什麼 Uvicorn 還要這樣顯示呢？」

其實，這是因為 0.0.0.0 代表 Uvicorn 正在監聽所有網絡接口，這樣你的應用可以被內網或其他設備存取，而不只是你的電腦自己用。

什麼是「監聽所有網絡接口」？

你的電腦其實有很多不同的網絡接口，每個接口都有自己的 IP 地址，例如：

  • 本機回環接口（Loopback Interface）：127.0.0.1（只限於你的電腦自己使用）
  • 內網接口（LAN Interface）：如 192.168.1.100（你的電腦在家用 Wi-Fi 或公司網路中的 IP）
  • 外部網絡接口（Public Interface）：如果你把伺服器部署在雲端，它會有一個公網 IP（如 203.0.113.10）

當 Uvicorn 綁定 0.0.0.0 時，它其實是同時綁定所有這些接口，這樣：

  1. 你可以用 127.0.0.1:8000 來從本機訪問。
  2. 你可以用 192.168.1.100:8000 讓同一個 Wi-Fi 內的手機或其他電腦訪問。
  3. 如果你的電腦有公網 IP，其他人在網際網路上也可以訪問（但通常會有防火牆擋住）。

127.0.0.1 只能本機訪問，無法讓別的設備訪問

假設 Uvicorn 預設使用 127.0.0.1，那麼：

  • 你的電腦自己可以使用 API（✅ 可行）
  • 但你手機、局域網內的其他電腦，就無法存取 API（❌ 無法存取）

因此，Uvicorn 預設會綁定 0.0.0.0，這樣如果你想開放 API 給其他設備，你不需要額外改設定，只需要查詢你的內網 IP，然後直接連線。

如果你只想讓本機訪問 API，而不想開放給外部設備，那你可以手動設定 127.0.0.1：

uvicorn main:app --host 127.0.0.1 --port 8000

這樣，Uvicorn 就只會監聽本機回環接口，其他設備無法訪問你的 API。

但 Uvicorn 顯示 0.0.0.0，我該怎麼訪問？

因為 0.0.0.0 不是一個具體的 IP 地址，它只是告訴你「我已經開放所有接口了」，所以實際上你應該用：

  • http://127.0.0.1:8000（如果你是在本機訪問）
  • http://你的內網 IP:8000（如果你想讓局域網內的設備訪問）

你可以這樣查詢你的內網 IP：

  • Windows： ipconfig 找到 IPv4 Address，例如 192.168.1.100
  • Mac/Linux： ifconfig 或 ip a 找到 inet 192.168.x.x 的部分

如果你的內網 IP 是 192.168.1.100，那麼你的手機或其他電腦就可以輸入：

http://192.168.1.100:8000

來存取 API。

0.0.0.0 的好處

  1. 允許其他設備訪問：
    • 如果你的 API 需要讓手機、平板、其他電腦存取，Uvicorn 預設用 0.0.0.0 會讓你不用額外設定。
  2. 兼容各種網絡環境：
    • 你可能今天在家裡開發，明天到公司，或是將 API 部署到雲端，0.0.0.0 讓 Uvicorn 可以自動適應不同的網絡環境。
  3. 適合部署到伺服器：
    • 如果你的 API 需要放到雲端或企業內部伺服器，0.0.0.0 讓它可以被其他機器存取，不需要額外修改設定。

0.0.0.0 的風險

  1. 不安全，如果沒有防火牆保護
    • 如果你的電腦有公網 IP，其他人就有可能透過你的 IP 存取你的 API（除非你的防火牆擋住了）。
    • 在公網環境下，應該搭配防火牆或設定 127.0.0.1 來確保安全。
  2. 可能會暴露 API 給不該存取的人
    • 例如你在公司內部開發，但不希望 API 被其他同事的電腦存取，那應該使用： uvicorn main:app --host 127.0.0.1 --port 8000

總結

問題答案
為什麼 Uvicorn 顯示 0.0.0.0？因為它讓伺服器開放給所有網絡接口，允許其他設備訪問
0.0.0.0 能直接在瀏覽器中訪問嗎？不能，它只是代表「所有可用的 IP」，要用 127.0.0.1 或內網 IP
怎麼讓 API 只能在本機使用？用 --host 127.0.0.1 來啟動 Uvicorn
怎麼讓手機或其他電腦訪問 API？用 0.0.0.0 啟動，然後用你的內網 IP 訪問
0.0.0.0 有風險嗎？有，在公網環境下應該搭配防火牆或身份驗證

什麼時候該使用 0.0.0.0，什麼時候用 127.0.0.1？

本機開發與測試（使用 127.0.0.1）

如果你只是在開發階段，並且不希望 API 被外部設備訪問，那麼應該讓 Uvicorn 只監聽 127.0.0.1，確保只有本機可以訪問：

uvicorn main:app --host 127.0.0.1 --port 8000

這樣，你只能使用 http://127.0.0.1:8000 來訪問 API，而局域網內的其他設備（如手機、筆電）都無法訪問它。

讓其他設備（如手機或其他電腦）訪問 API（使用 0.0.0.0）

如果你希望 API 可以從局域網內的其他設備訪問，比如：

  • 在電腦上運行 API，但希望手機也能訪問測試
  • 你的應用需要在本地伺服器上運行，並讓內網其他設備訪問

這時，你應該讓 Uvicorn 監聽 0.0.0.0，並使用你的內網 IP 來訪問 API：

uvicorn main:app --host 0.0.0.0 --port 8000

然後，你需要查找你的內網 IP：

  • Windows：
    打開命令提示字元（CMD），輸入： ipconfig 找到 IPv4 Address（通常是 192.168.x.x）。
  • Mac / Linux：
    打開終端（Terminal），輸入： ifconfig 或 ip a 找到 inet 192.168.x.x 的部分。

假設你的內網 IP 是 192.168.1.100，你就可以從局域網內的其他設備訪問：

http://192.168.1.100:8000

這樣，你的 API 就能在手機或其他電腦上測試了。

⚠️ 注意：

  • 如果你要讓外部設備訪問，你的防火牆可能需要允許 8000 端口的流量。
  • Uvicorn 預設沒有開啟 HTTPS，因此在公網環境下使用 0.0.0.0 是不安全的。

如何確保 Uvicorn 安全？

如果你的應用只是在本機開發環境中運行，建議避免使用 0.0.0.0，以免意外暴露 API 給其他設備。

只允許本機訪問

uvicorn main:app --host 127.0.0.1 --port 8000

使用防火牆限制訪問

如果你必須使用 0.0.0.0，但只希望特定 IP 能夠訪問，則可以透過防火牆設定來限制存取，例如：

  • Windows 防火牆：只允許特定內網 IP 連接 8000 端口
  • Linux UFW 防火牆： sudo ufw allow from 192.168.1.100 to any port 8000

結論

監聽地址作用什麼時候使用？
127.0.0.1只允許本機訪問本地開發與測試
0.0.0.0允許所有設備訪問需要讓局域網或其他設備訪問 API
  • 0.0.0.0 只是監聽所有網絡接口，不能直接作為訪問地址。
  • 127.0.0.1 是本機回環地址，適合開發環境使用。
  • 如果要讓其他設備訪問 API，應使用 0.0.0.0，並透過內網 IP 連接。

希望這篇文章能幫助你理解 0.0.0.0 與 127.0.0.1 的區別，讓你更順利地使用 Uvicorn 啟動 API！ 🚀

Similar Posts