Docker コンテナからホストへアクセス：host.docker.internal 完全ガイド

金曜の午後 3 時、ターミナルに Connection refused と表示されていました。

正直かなりしんどかったです。ローカルの MySQL は問題なく動いていて、Navicat でも CLI でも入れるのに、コンテナ内のアプリだけが繋がらない。接続文字列 localhost:3306 は 3 回見直した。ユーザー名もパスワードも合っている。どこがおかしいんだろう？

原因は localhost の 3 文字にありました。

Docker コンテナ内で localhost や 127.0.0.1 を使ってホストのサービスに繋ごうとして失敗したことがあるなら、この記事はまさにそのためのものです。コンテナ内の localhost が思っているものと違う理由を、できるだけ平易に説明します。そして host.docker.internal という「魔法のドメイン名」で、きれいに解決する方法をお伝えします。

この記事で学べること：

• コンテナのネットワーク隔離の仕組み（専門用語は最小限）
• Mac・Windows・Linux それぞれの正しい設定
• すぐ使えるトラブルシュート一覧（次に困ったとき用）

なぜ localhost は使えないのか

まず結論から。コンテナには独立したネットワークの世界があります。

少し抽象的に聞こえるかもしれません。コンテナを「独立した小さな家」と想像してください。自分の住所、自分の郵便受け、自分のすべてを持っています。コンテナ内で「localhost」や「127.0.0.1」を叩くとき、探しているのはその小さな家の中であり、外のホストマシンではありません。

具体的には：

• ホスト上では localhost はホスト自身を指す
• コンテナ内では localhost はコンテナ自身を指す
• 同じ localhost でも、まったく別物

私も初めて知ったときは驚きました。PC 上で MySQL は動いているのに、なぜコンテナからは見えないのか。理由はここにあります。コンテナは自分の世界の中で MySQL を探しているので、当然見つからないのです。

コンテナのネットワーク隔離の仕組み

Docker は各コンテナに独立した「ネットワーク名前空間」を作ります（難しい言葉は一旦置いておきましょう）。

各コンテナは自分の NIC、自分の IP、自分のルーティングテーブルを持ちます。同じ建物に住んでいても、Wi-Fi のパスワードは別、というイメージです。

コンテナとホストは docker0 という仮想ブリッジでつながります。コンテナの IP はだいたい 172.17.0.x で、コンテナから見たホストは 172.17.0.1（ブリッジのゲートウェイ）です。

コンテナ内で localhost にアクセスすると、コンテナの 127.0.0.1 に届きます。ホストの 127.0.0.1 ではないので、ホストの MySQL には繋がりません。

典型的なエラーは次のとおりです。

Error: connect ECONNREFUSED 127.0.0.1:3306

または：

Can't connect to MySQL server on 'localhost' (111)

コンテナ内で localhost を使ってホストのサービスに繋ごうとしたときによく出るエラーです。

host.docker.internal とは

localhost が使えないなら、コンテナからホストへどうアクセスするか。

Docker 公式の答えは host.docker.internal です。特別なドメイン名で、自動的にホストの IP に解決されます。ホストの「ニックネーム」のようなもの。実 IP が 192.168.1.100 でも 10.0.0.5 でも、ネットワークが変わっても、この名前でホストに届きます。

例えばホストで MySQL が 3306 を待受しているなら、コンテナ内では次のように接続します。

mysql://user:[email protected]:3306/dbname

かなり便利ですよね。

バージョンとプラットフォーム対応

ただし、ここには落とし穴があります。

Mac / Windows ユーザー（Docker Desktop）

Docker Desktop（GUI 付き）なら、18.03（2018 年 3 月）以降は host.docker.internal が標準で使えます。追加設定は不要です。

コードにそのまま書けば OK です。

const mysql = require('mysql2');
const connection = mysql.createConnection({
  host: 'host.docker.internal',  // これだけ
  port: 3306,
  user: 'root',
  password: 'your_password'
});

Linux ユーザー（Docker Engine）

Linux は少し運が悪いです。Mac/Windows のように VM が間に入るわけではなく、Engine 上では host.docker.internal はデフォルトでは存在しません。

良いニュースは、Docker Engine 20.10（2020 年 12 月）以降なら手動で有効化できること。具体的な設定は次の節で説明します。

もっと古いバージョンなら：

Vultr - 高性能NVMeクラウドサーバー、世界32拠点、Dockerワンクリック展開対応

価格を見る →広告

• 172.17.0.1（Docker デフォルトブリッジのゲートウェイ IP）
• Docker ネットワーク上のホストの実 IP
• docker.for.mac.host.internal（Mac の旧バージョンのみ）

3 プラットフォームの設定方法

ここからは実践編。コピペできる設定です。

Mac/Windows の設定（Docker Desktop）

いちばん簡単なパターンです。

方法 1：コードでそのまま使う

追加設定は不要。host.docker.internal を書くだけです。

# docker-compose.yml
version: '3'
services:
  app:
    image: myapp:latest
    environment:
      - DB_HOST=host.docker.internal  # そのまま
      - DB_PORT=3306

方法 2：明示的に宣言（任意）

必須ではありませんが、明示したい場合は extra_hosts を追加できます。

version: '3'
services:
  app:
    image: myapp:latest
    extra_hosts:
      - "host.docker.internal:host-gateway"
    environment:
      - DB_HOST=host.docker.internal

host-gateway は Docker 20.10+ の構文で、「ホストのゲートウェイアドレス」を意味します。

docker run の場合：

docker run -d \
  --add-host=host.docker.internal:host-gateway \
  -e DB_HOST=host.docker.internal \
  myapp:latest

Linux の設定（Docker Engine）

Linux は少し手間がかかります。

方法 1：推奨 — host-gateway を使う

Docker 20.10+ なら、すべてのプラットフォームで使える一般的な方法です。

# docker-compose.yml
version: '3'
services:
  app:
    image: myapp:latest
    extra_hosts:
      - "host.docker.internal:host-gateway"  # ここがポイント
    environment:
      - DB_HOST=host.docker.internal
      - DB_PORT=3306

docker run：

docker run -d \
  --add-host=host.docker.internal:host-gateway \
  -e DB_HOST=host.docker.internal \
  myapp:latest

クロスプラットフォーム — 同じ設定が Mac・Windows・Linux で動き、OS ごとに書き換える必要がありません。

方法 2：代替 — Docker ブリッジ IP

host-gateway が使えない（Docker が古い）場合は、デフォルトブリッジのゲートウェイ IP を指定します。

version: '3'
services:
  app:
    image: myapp:latest
    extra_hosts:
      - "host.docker.internal:172.17.0.1"  # Docker デフォルトゲートウェイ
    environment:
      - DB_HOST=host.docker.internal

172.17.0.1 は Docker bridge のデフォルトゲートウェイです。多くの環境で正しいですが、ネットワーク設定を変えている場合は注意してください。

方法 3：最終手段 — host ネットワークモード

どうしてもダメなときの切り札です。

docker run -d \
  --network=host \
  -e DB_HOST=localhost \  # ここでは localhost が使える
  myapp:latest

docker-compose では：

version: '3'
services:
  app:
    image: myapp:latest
    network_mode: "host"  # ホストのネットワークを共有
    environment:
      - DB_HOST=localhost

メリット：シンプル。コンテナはホストと同じネットワークスタックを使うので、localhost が本当の localhost になる。

デメリット：

• コンテナのネットワーク隔離が壊れる
• ポートがホストと共有され、衝突しやすい（例：8080 が既にホストで使用中）
• Linux のみ。Mac/Windows では VM 内で動くため期待どおりにならない
• 本番では非推奨。ローカル開発・デバッグ向け

クロスプラットフォーム共通設定（強く推奨）

チームに Mac と Linux が混在する、または複数環境で同じ compose を使うなら、次の設定を使ってください。

# docker-compose.yml
version: '3'
services:
  app:
    image: myapp:latest
    extra_hosts:
      - "host.docker.internal:host-gateway"  # 全 OS で認識される
    environment:
      - DB_HOST=host.docker.internal
      - DB_PORT=3306
      - DB_USER=root
      - DB_PASSWORD=your_password

Docker 20.10+（2020 年末以降）なら、すべてのプラットフォームで動きます。まだ 2020 年以前の Docker を使っているなら、そろそろアップグレードを検討した方がいいでしょう。

ホスト側サービスの設定ポイント

コンテナ側を直しただけでは足りません。

ホスト上のサービスも正しく設定しないと、やはり繋がりません。見落とされがちなので、ここだけ切り出して説明します。

サービスは正しいアドレスで待受する

いちばん多い落とし穴です。

多くのサービスはデフォルトで 127.0.0.1 のみを待受し、ローカルからの接続だけを受け付けます。Docker コンテナは「ローカル」ではないので、ブリッジ経由のリクエストは拒否されます。

0.0.0.0 で待受するよう変更してください。「すべての NIC からの接続を受け付ける」という意味です。

MySQL の設定

設定ファイルの場所の例：

• Linux: /etc/mysql/mysql.conf.d/mysqld.cnf
• Mac（Homebrew）: /usr/local/etc/my.cnf
• Windows: C:\ProgramData\MySQL\MySQL Server 8.0\my.ini

bind-address を変更します。

[mysqld]
# 変更前の例
# bind-address = 127.0.0.1

# 変更後
bind-address = 0.0.0.0

変更後、MySQL を再起動します。

# Linux
sudo systemctl restart mysql

# Mac
brew services restart mysql

# Windows
# サービス管理から MySQL を再起動

Redis の設定

redis.conf（/etc/redis/redis.conf や /usr/local/etc/redis.conf など）を編集します。

# 変更前
bind 127.0.0.1 -::1

# 変更後
bind 0.0.0.0

再起動：

# Linux
sudo systemctl restart redis

# Mac
brew services restart redis

PostgreSQL の設定

postgresql.conf：

listen_addresses = '*'  # すべてのアドレスで待受

pg_hba.conf で Docker サブネットを許可します。

# 172.17.0.0/16 からのアクセスを許可
host    all             all             172.17.0.0/16           md5

ユーザー権限の設定（MySQL）

MySQL が 0.0.0.0 で待受していても、ユーザー権限で弾かれることがあります。

MySQL の権限は「ユーザー@接続元ホスト」で管理されます。root@localhost と root@% は別ユーザーです。

KiloClaw - 企業向けマネージド OpenClaw、AI エージェントのオーケストレーションとスマートルーティングを加速

今すぐ始める →広告

localhost のみ許可されていると、コンテナからは繋がりません。Docker サブネットからのアクセスを許可してください。

-- 案 1：すべてのホストから（簡単だがセキュリティは弱い）
GRANT ALL PRIVILEGES ON *.* TO 'your_user'@'%' IDENTIFIED BY 'your_password';

-- 案 2：Docker サブネットのみ（より安全）
GRANT ALL PRIVILEGES ON *.* TO 'your_user'@'172.17.0.%' IDENTIFIED BY 'your_password';

FLUSH PRIVILEGES;

MySQL 8.0+ の場合：

CREATE USER 'your_user'@'%' IDENTIFIED BY 'your_password';
GRANT ALL PRIVILEGES ON *.* TO 'your_user'@'%';
FLUSH PRIVILEGES;

ファイアウォール

OS のファイアウォールが、コンテナからホストへの接続をブロックしていることもあります。

状態確認：

# Linux (ufw)
sudo ufw status

# Linux (firewalld)
sudo firewall-cmd --state

Docker サブネットを許可（MySQL 3306 の例）：

# ufw
sudo ufw allow from 172.17.0.0/16 to any port 3306

# firewalld
sudo firewall-cmd --permanent --zone=public --add-rich-rule='rule family="ipv4" source address="172.17.0.0/16" port port="3306" protocol="tcp" accept'
sudo firewall-cmd --reload

セキュリティ上の注意

0.0.0.0 で待受すると、LAN 上の他マシンからも見えるリスクがあります。

本番環境：

1. 特定 NIC のみ待受：Docker が使うインターフェースだけに絞る

   bind-address = 172.17.0.1

2. ファイアウォールと併用：Docker サブネットだけ許可し、それ以外は拒否

3. DB もコンテナ化：ホストに DB を置かず、Compose で DB コンテナを立て、アプリと DB を同じネットワークに置く（より安全）

ローカル開発：

正直、開発 PC なら 0.0.0.0 でも大きな問題にはなりにくいです。外から直接触れない環境がほとんどなので、あまり神経質にならなくて大丈夫です。

よくある問題のトラブルシュート一覧

接続できないときは、この順で確認してください。

問題 1：Connection refused（接続拒否）

いちばん多いエラーです。

Error: connect ECONNREFUSED host.docker.internal:3306

または：

Can't connect to MySQL server on 'host.docker.internal' (111)

確認手順：

ステップ 1：ホストでサービスが動いているか

# MySQL
sudo systemctl status mysql    # Linux
brew services list              # Mac

# ポート待受の確認
netstat -an | grep 3306
# または
lsof -i :3306

動いていなければ、先にサービスを起動します。

ステップ 2：待受アドレス

sudo netstat -tlnp | grep 3306

出力例：

tcp  0  0 0.0.0.0:3306  0.0.0.0:*  LISTEN  1234/mysqld

3 列目が 0.0.0.0:3306 なら OK。127.0.0.1:3306 なら、前述のとおり bind-address を 0.0.0.0 に変更します。

ステップ 3：ファイアウォール

一時的にオフにして切り分けます。

# Linux (ufw)
sudo ufw disable

# Linux (firewalld)
sudo systemctl stop firewalld

# Mac
# システム設定 → プライバシーとセキュリティ → ファイアウォール → オフ

オフにすると繋がるなら、ファイアウォールが原因です。ルールを設定してから再度有効化してください。

問題 2：Connection timeout（タイムアウト）

Error: connect ETIMEDOUT host.docker.internal:3306

拒否より厄介で、パケットは出ているが戻ってこない状態です。

ステップ 1：host.docker.internal が解決できるか

docker exec -it your_container sh
ping host.docker.internal

unknown host なら、host.docker.internal の設定が足りません。

Linux：docker-compose.yml または docker run に --add-host=host.docker.internal:host-gateway があるか確認してください。

ステップ 2：ポート番号

本当に 3306 か。カスタムポートなら合わせてください。

sudo netstat -tlnp | grep mysqld

ステップ 3：コンテナからホストへの疎通

telnet host.docker.internal 3306
# telnet がなければ
nc -zv host.docker.internal 3306

問題 3：Unknown host（名前解決失敗）

getaddrinfo ENOTFOUND host.docker.internal

DNS で host.docker.internal が解決できていません。

services:
  app:
    extra_hosts:
      - "host.docker.internal:host-gateway"

または：

docker run --add-host=host.docker.internal:host-gateway ...

問題 4：認証失敗（Access denied）

Access denied for user 'root'@'172.17.0.2' (using password: YES)

MySQL には届いているが、権限が足りません。

SELECT user, host FROM mysql.user WHERE user='root';

CREATE USER 'root'@'%' IDENTIFIED BY 'your_password';
GRANT ALL PRIVILEGES ON *.* TO 'root'@'%';
FLUSH PRIVILEGES;

問題 5：クロスプラットフォームで設定がずれる

Mac では動くが Linux では動かない、というときは host-gateway で統一します。

services:
  app:
    extra_hosts:
      - "host.docker.internal:host-gateway"

Docker は 20.10 以上に揃えてください。

クイック確認の順番

1. サービスは起動しているか → systemctl status / brew services list
2. 待受は 0.0.0.0 か → netstat -tlnp
3. コンテナに extra_hosts があるか
4. DNS は通るか → コンテナ内で ping host.docker.internal
5. ポートは開いているか → telnet / nc
6. ファイアウォールか
7. MySQL ユーザーは @localhost だけか

多くの場合、最初の 3 つで片付きます。

実践ケース

理論のあとは、具体例です。

ケース 1：Spring Boot からホストの MySQL へ接続

シナリオ：Spring Boot を Docker で動かし、ローカルの MySQL に繋ぎたい。

ステップ 1：Spring Boot の設定

application.yml：

Alibaba Cloud - 開発者向けクラウドの第一候補、Lighthouse サーバー15%OFF、プロジェクトの迅速な立ち上げを支援

15%割引を入手 →広告

spring:
  datasource:
    url: jdbc:mysql://host.docker.internal:3306/mydb?useSSL=false&serverTimezone=UTC
    username: root
    password: your_password
    driver-class-name: com.mysql.cj.jdbc.Driver

ステップ 2：Docker Compose

docker-compose.yml：

version: '3.8'

services:
  app:
    build: .
    ports:
      - "8080:8080"
    extra_hosts:
      - "host.docker.internal:host-gateway"
    environment:
      SPRING_DATASOURCE_URL: jdbc:mysql://host.docker.internal:3306/mydb
      SPRING_DATASOURCE_USERNAME: root
      SPRING_DATASOURCE_PASSWORD: your_password

ステップ 3：ホストの MySQL

/etc/mysql/mysql.conf.d/mysqld.cnf：

[mysqld]
bind-address = 0.0.0.0

sudo systemctl restart mysql

CREATE USER 'root'@'%' IDENTIFIED BY 'your_password';
GRANT ALL PRIVILEGES ON *.* TO 'root'@'%';
FLUSH PRIVILEGES;

ステップ 4：起動テスト

docker-compose up --build

HikariPool-1 - Start completed のようなログが出れば成功です。

実際の切り分け例：

初回は Connection refused になりました。

1. systemctl status mysql → 起動済み
2. netstat -tlnp | grep 3306 → 127.0.0.1:3306 のみ待受
3. bind-address = 0.0.0.0 に変更して再起動 → 接続成功

ケース 2：Node.js からホストの Redis へ接続

シナリオ：Node.js アプリのキャッシュ用に、ホスト上の Redis を使う。

ステップ 1：Node.js

// redis-client.js
const redis = require('redis');

const client = redis.createClient({
  host: process.env.REDIS_HOST || 'host.docker.internal',
  port: process.env.REDIS_PORT || 6379,
  password: process.env.REDIS_PASSWORD
});

client.on('connect', () => {
  console.log('Redis connected successfully');
});

client.on('error', (err) => {
  console.error('Redis error:', err);
});

module.exports = client;

ステップ 2：Docker Compose

version: '3.8'

services:
  app:
    build: .
    ports:
      - "3000:3000"
    extra_hosts:
      - "host.docker.internal:host-gateway"
    environment:
      NODE_ENV: development
      REDIS_HOST: host.docker.internal
      REDIS_PORT: 6379

ステップ 3：ホストの Redis

bind 127.0.0.1 ::1
# ↓
bind 0.0.0.0

protected-mode yes の場合、ローカル開発では：

protected-mode no  # 本番では使わないこと

sudo systemctl restart redis   # Linux
brew services restart redis    # Mac

ステップ 4：確認

docker-compose up

Redis connected successfully が出れば OK です。

extra_hosts: ["host.docker.internal:host-gateway"] を入れておけば、Mac も Linux も同じ compose で動きます。OS ごとに分ける必要はほぼありません。

ケース 3：開発環境のテンプレート

アプリコンテナからホストの MySQL と Redis に繋ぐ例です。

# docker-compose.yml
version: '3.8'

services:
  app:
    build: .
    ports:
      - "8080:8080"
    extra_hosts:
      - "host.docker.internal:host-gateway"
    environment:
      DB_HOST: host.docker.internal
      DB_PORT: 3306
      DB_NAME: myapp
      DB_USER: root
      DB_PASSWORD: your_password
      REDIS_HOST: host.docker.internal
      REDIS_PORT: 6379
      NODE_ENV: development
      PORT: 8080
    volumes:
      - .:/app
      - /app/node_modules
    command: npm run dev

ホスト側のチェックリスト：

# MySQL: bind-address = 0.0.0.0 → 再起動

# Redis: bind 0.0.0.0, protected-mode no（開発のみ）→ 再起動

# ファイアウォール（必要なら）
sudo ufw allow from 172.17.0.0/16 to any port 3306
sudo ufw allow from 172.17.0.0/16 to any port 6379

Mac でも Linux でも、そのままコピーして使えます。

まとめ

要点は 3 つです。

1. 仕組みを理解する

コンテナには独自のネットワーク世界があります。コンテナ内の localhost はコンテナ自身を指し、ホストではありません。これは Docker の設計であり、バグではありません。

2. 方法を選ぶ

3. ホスト側も整える

コンテナだけ直しても不十分です。

• 待受を 0.0.0.0 に
• MySQL ユーザーに Docker サブネットからの権限
• ファイアウォールで Docker サブネットを許可

クイック決定フロー

ホストのサービスに繋がらない？
  ↓
Mac/Windows か Linux か？
  ↓
Mac/Windows:
  → host.docker.internal を使う
  → まだダメならホスト側のサービス設定を確認

Linux:
  → Docker 20.10 以上？
      はい → extra_hosts: host-gateway
      いいえ → extra_hosts: 172.17.0.1
  → ホスト側の設定・ファイアウォールを確認

それでもダメ？
  → この記事のトラブルシュート一覧を順に
  → 最後の手段：--network=host（ローカル開発のみ）

コンテナ開発は便利ですが、ネットワークの落とし穴も多いです。host.docker.internal と host-gateway を押さえておけば、大半は解決できます。

この記事をブックマークしておけば、次に Connection refused が出たときすぐ確認できます。チームで同じ問題に悩んでいる人がいたら、共有してあげてください。

変わったコンテナネットワークの話や、もっと良いやり方があれば、コメントで教えてください。他の人の助けになるかもしれません。