costela/docker-etchosts

docker-etchosts镜像说明

镜像概述

docker-etchosts是一款自动管理本地Docker容器在/etc/hosts文件中条目的工具，灵感来源于vagrant-hostmanager和docker-hostmanager。其核心价值在于解决多Web项目开发时需跟踪容器端口的问题，通过生成可预测的域名映射，简化本地访问流程。

核心功能

1. 实时更新：监听Docker daemon事件，容器创建/销毁时自动更新hosts条目；
2. 多别名生成：为容器生成多种域名别名（容器名、别名+项目名、别名+网络名等）；
3. 安全清理：工具终止时自动移除所有管理的条目，恢复hosts文件初始状态；
4. compose兼容：自动关联docker-compose项目名生成别名，适配团队协作场景。

使用场景

• 本地多Web项目开发：无需记忆容器暴露的端口，直接用容器名.项目名等别名访问；
• 团队协作环境：统一容器访问域名规则，避免端口冲突；
• 自动化测试：快速映射容器域名，简化测试脚本编写。

配置说明

通过环境变量配置工具行为：

• ETCHOSTS_LOG_LEVEL：日志级别，可选debug/info/warn/error，默认warn；
• ETCHOSTS_ETC_HOSTS_PATH：hosts文件路径，默认/etc/hosts。

部署示例

Docker容器运行

bash
docker run -d \
  --network none --restart always \
  -v /etc/hosts:/etc/hosts -v /var/run/docker.sock:/var/run/docker.sock \
  costela/docker-etchosts

参数说明：

• --network none：容器无需网络；
• --restart always：异常退出后自动重启；
• -v /etc/hosts:/etc/hosts：挂载本地hosts文件；
• -v /var/run/docker.sock:/var/run/docker.sock：监听Docker事件。

源码安装（需Go >=1.13）

bash
go get -d github.com/costela/docker-etchosts
cd $GOPATH/src/github.com/costela/docker-etchosts
go install
# 启动工具
docker-etchosts

使用示例

假设docker-compose项目someproject中有服务someservice，网络somenet并设置别名somealias：

yaml
services:
  someservice:
    networks:
      somenet:
        aliases:
          - somealias

工具会生成如下hosts条目：

x.x.x.x someservice someservice.somenet someservice.someproject someservice.someproject.somenet somealias somealias.somenet somealias.someproject somealias.someproject.somenet

注意：Docker不保证别名唯一性，建议使用带项目名和网络名的长别名避免冲突；手动添加的容器IP条目需删除，以免工具无法管理。