ricariel/cn2pihole

core-networks2pihole-docker 镜像文档

镜像概述

core-networks2pihole-docker 是一款集成 Core Networks 服务与 Pi-hole 的 Docker 镜像。该镜像旨在通过自动化方式从 Core Networks 平台获取网络相关数据（如 DNS 记录、IP 地址信息等），并将其同步至 Pi-hole 环境，实现 Pi-hole 的动态配置与优化，增强广告拦截、***域名过滤及网络管理能力。

核心功能与特性

• 数据同步：支持定期从 Core Networks API 拉取网络配置数据（如域名解析记录、IP 白名单/黑名单等），并自动同步至 Pi-hole。
• 自动配置：可根据 Core Networks 数据自动更新 Pi-hole 的 DNS 规则、广告拦截列表及客户端配置，减少手动操作。
• 兼容性：兼容主流 Pi-hole 版本及 Core Networks 公开 API，支持自定义同步周期与数据过滤规则。
• 轻量设计：基于 Alpine 基础镜像构建，体积小巧，资源占用低，适合嵌入式设备及家庭/小型网络环境部署。

使用场景与适用范围

• 家庭网络环境：需结合 Core Networks 网络服务（如动态 DNS、域名管理）实现广告拦截与网络过滤的家庭用户。
• 小型企业网络：需要集中管理网络广告过滤策略，并通过 Core Networks 服务监控网络状态的小型办公场景。
• Pi-hole 高级配置：希望基于 Core Networks 实时网络数据动态调整 Pi-hole 规则，提升拦截效率的技术用户。

使用方法与配置说明

前置条件

• 已部署 Docker 环境（Docker Engine 20.10+）。
• 拥有 Core Networks 账号及 API 访问权限（需获取 API 密钥）。
• 已部署 Pi-hole 服务（可独立部署或通过 Docker 容器运行）。

快速启动（Docker Run）

bash
docker run -d \
  --name core-networks2pihole \
  -e CORE_NETWORKS_API_KEY="your_core_networks_api_key" \
  -e CORE_NETWORKS_DOMAIN="your-domain.example.com" \
  -e PIHOLE_HOST="pihole-container-ip" \
  -e PIHOLE_API_KEY="your-pihole-api-key" \
  -e SYNC_INTERVAL="3600" \  # 同步周期（秒），默认3600
  core-networks2pihole-docker:latest

Docker Compose 配置示例

yaml
version: '3'
services:
  core-networks2pihole:
    image: docker.xuanyuan.run/core-networks2pihole-docker:latest
    container_name: core-networks2pihole
    environment:
      - CORE_NETWORKS_API_KEY=your_core_networks_api_key
      - CORE_NETWORKS_DOMAIN=your-domain.example.com
      - PIHOLE_HOST=pihole  # 若Pi-hole在同一compose网络中，可使用服务名
      - PIHOLE_PORT=80  # Pi-hole Web端口，默认80
      - PIHOLE_API_KEY=your-pihole-api-key
      - SYNC_INTERVAL=3600
      - LOG_LEVEL=info  # 日志级别：debug/info/warn/error，默认info
    restart: unless-stopped
    networks:
      - pihole-network  # 需与Pi-hole在同一网络

networks:
  pihole-network:
    external: true  # 若Pi-hole网络已存在

环境变量说明

注意事项

• 确保 Core Networks API 密钥具有足够权限（如读取域名记录、网络配置等）。
• Pi-hole 需开启 API 访问功能（在 Web 界面“设置-API”中启用）。
• 首次运行时建议设置 LOG_LEVEL=debug，以便排查同步过程中的问题。
• 同步周期不宜过短，避免频繁请求 Core Networks API 导致限制。