Sign inSign up

kouleen/docker-hook

By kouleen

•Updated 15 days ago

Image
0

862

kouleen/docker-hook repository overview

⁠kouleen/docker-hook

⁠项目介绍

kouleen/docker-hook 是一款基于Golang开发的Docker自动化部署WebHook服务，用于对接GitHub Actions等CI流水线，镜像推送完成后通过WebHook回调，自动完成镜像拉取、旧容器销毁、新容器启动上线，实现代码提交一键部署。内置Docker全量操作接口、SQLite部署日志持久化，支持容器端口映射、目录挂载、环境变量注入、重启策略自定义等部署参数。

⁠核心功能

  1. WebHook异步部署 接收CI流水线POST回调，接口快速响应，后台异步执行镜像拉取与容器更新，避免CI任务超时中断。
  2. Docker全量管理API 提供镜像拉取/删除、容器启停/销毁、容器日志实时查看、容器列表查询接口，可直接通过HTTP接口管理宿主机Docker。
  3. 部署记录持久化 内置SQLite数据库自动建表，完整记录每一次WebHook部署、镜像操作、容器操作日志，支持多条件历史检索。
  4. 灵活的容器部署配置 支持自定义端口映射、数据卷挂载、环境变量、网桥/宿主机网络、容器重启策略、旧容器自动清理、自定义启动命令。
  5. 私有Docker仓库适配 通过环境变量传入DockerHub账号凭证，正常拉取私有镜像仓库镜像。
  6. 轻量化镜像 采用Golang多阶段Alpine镜像构建，镜像体积精简，内置Asia/Shanghai时区配置。

⁠运行前置条件

  • 宿主机Docker Engine版本 ≥ 20.10
  • 容器必须挂载宿主机/var/run/docker.sock，用于操作宿主机Docker服务

⁠快速启动

⁠1. docker run 直接运行
docker run -d \
--name docker-hook \
-p 8077:8077 \
-e USERNAME=你的DockerHub账号 \
-e PASSWORD=你的DockerHub密钥/AccessToken \
-v /var/run/docker.sock:/var/run/docker.sock \
-v ./hook.db:/app/hook.db \
kouleen/docker-hook:latest
⁠2. docker-compose 生产部署（推荐）
⁠docker-compose.yml
services:
  docker-hook:
    image: kouleen/docker-hook:latest
    container_name: docker-hook
    restart: always
    ports:
      - "8077:8077"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - ./hook.db:/app/hook.db
    environment:
      - USERNAME=你的DockerHub账号
      - PASSWORD=你的DockerHub访问令牌

启动命令：

docker-compose up -d

⁠核心环境变量说明

环境变量作用
USERNAMEDockerHub登录账号，私有镜像拉取鉴权使用
PASSWORDDockerHub密码或个人AccessToken

⁠关键挂载说明

宿主机路径容器内路径用途
/var/run/docker.sock/var/run/docker.sock核心挂载，容器调用宿主机Docker API
./hook.db/app/hook.dbSQLite部署日志持久化，防止容器销毁丢失记录

⁠默认访问端口

服务默认监听端口：8077，可通过宿主机端口映射修改对外访问端口。

⁠WebHook部署回调接口

POST /api/docker/webhook/put

⁠请求JSON示例
{
  "runId": "123456789",
  "imageName": "kouleen/docker-hook:latest",
  "containerName": "docker-hook",
  "branch": "release",
  "repo": "kouleen/docker-hook",
  "htmlUrl": "https://github.com/kouleen/docker-hook",
  "cloneUrl": "https://github.com/kouleen/docker-hook.git",
  "sshUrl": "[email protected]:kouleen/docker-hook.git",
  "status": "success",
  "actor": "kouleen",
  "commitMessage": "feat: update service",
  "workflow": "GitHub Docker Image CI",
  "triggerType": "push",
  "failRemark": "流水线未发现异常",
  "networkMode": "bridge",
  "restartPolicy": "always",
  "removeOldExist": true,
  "enableIT": true,
  "portMapping": {
    "8077": "8077"
  },
  "envList": [
    "USERNAME=kouleen",
    "PASSWORD=*************"
  ],
  "volumeBinds": [
    "/usr/bin/docker:/usr/bin/docker:ro",
    "/var/run/docker.sock:/var/run/docker.sock"
  ],
  "cmdOverride": ["pwd","ls"]
}

接口成功返回：{"code":0,"data":true}

⁠配套管理接口

  1. WebHook部署历史查询：GET /api/docker/webhook/query
  2. 宿主机镜像列表：GET /api/docker/image/list
  3. 宿主机容器列表：GET /api/docker/container/list
  4. 容器实时日志查看：GET /api/docker/container/log?containerName=xxx

⁠GitHub Actions 集成说明

在CI流水线构建推送镜像成功后，增加WebHook请求步骤，将构建信息、镜像名称、容器配置POST至本服务接口，流水线完成自动触发服务器更新容器上线。

⁠常见故障排查

  1. Docker连接失败：确认已挂载/var/run/docker.sock
  2. 私有镜像拉取401：核对USERNAME、PASSWORD凭证有效性，AccessToken开启仓库读写权限
  3. 镜像拉取EOF中断：宿主机配置Docker国内镜像加速器，缓解DockerHub网络波动
  4. WebHook回调超时：接口为异步任务，收到请求直接返回，镜像拉取与容器重启在后台执行

⁠开源地址

GitHub：https://github.com/kouleen/docker-hook⁠

⁠开源协议

MIT License

Tag summary

Content type

Image

Digest

sha256:d5d05130f…

Size

23.5 MB

Last updated

15 days ago

docker pull kouleen/docker-hook