Mailgun Logger

概述和主要用途

Mailgun Logger是一个基于Phoenix/Elixir构建的简单管理工具，通过Mailgun API定期从Mailgun获取事件并存储到MySQL数据库。由于Mailgun仅提供有限时间的事件存储（免费账户最多三天），该工具解决了事件持久化需求。它会获取最近两天的事件（考虑到部分事件可能延迟进入系统），并通过数据库唯一约束确保仅插入新事件。

重要声明

本应用与Mailgun及其子公司或关联公司无任何关联、授权或背书。Mailgun网站为Mailgun。

本工具并非旨在替代Mailgun提供的优秀在线工具，仅用于简单的事件存储。

Jack + Joe不对您使用本工具的行为负责，也不提供任何持久化保证。免费工具存在一定风险 :)

核心功能和特性

• 定期事件获取：通过Mailgun API定期检索事件，默认获取最近两天数据以处理事件延迟问题
• 持久化存储：将Mailgun事件存储到MySQL数据库，突破Mailgun事件存储时间限制
• 数据唯一性保障：通过数据库唯一约束确保仅存储新事件，避免重复数据
• 可配置参数：支持自定义数据库连接信息、每页事件数量及日志级别

使用场景和适用范围

适用于需要长期保存Mailgun事件日志的用户，尤其是：

• 使用Mailgun免费账户，需突破三天事件存储限制的用户
• 需要将Mailgun事件持久化到本地或私有数据库以便后续查询、分析的场景
• 希望通过简单配置实现Mailgun事件自动备份的个人或企业用户

详细使用方法和配置说明

镜像获取

Mailgun Logger作为Docker镜像发布，可从Docker Hub获取。

环境变量配置

必填变量

• ML_DB_USER：数据库用户名
• ML_DB_PASSWORD：数据库密码
• ML_DB_NAME：数据库名称
• ML_DB_HOST：数据库主机地址

可选变量

• ML_PAGESIZE：每页事件数量
• ML_LOG_LEVEL：日志级别（info、debug、warn等）

Docker快速启动

使用以下命令直接运行容器：

bash
$ docker run -d -p 5050:5050 \
  -e "ML_DB_USER=username" \
  -e "ML_DB_PASSWORD=password" \
  -e "ML_DB_NAME=mailgun_logger" \
  -e "ML_DB_HOST=my_db_host" \
  --name mailgun_logger jackjoe/mailgun_logger

Docker Compose部署

创建docker-compose.yml文件：

yaml
version: "3"

services:
  db:
    image: mysql
    networks:
      - webnet
    environment:
      - MYSQL_PASSWORD=logger
      - MYSQL_USER=logger
      - MYSQL_DATABASE=mailgun_logger
      - MYSQL_RANDOM_ROOT_PASSWORD=yes
    volumes:
      - db_data:/var/lib/mysql

  web:
    image: jackjoe/mailgun_logger
    depends_on:
      - db
    entrypoint: ["./wait-for", "db:3306", "--", "./start.sh"]
    ports:
      - "5050:5050"
    networks:
      - webnet
    environment:
      - ML_DB_USER=logger
      - ML_DB_PASSWORD=logger
      - ML_DB_NAME=mailgun_logger
      - ML_DB_HOST=db

networks:
  webnet:
    external: false

volumes:
  db_data: {}

启动服务：

bash
$ docker-compose up

服务启动后访问[***]

贡献指南

本地运行需先配置环境。Mailgun Logger依赖MySQL数据库，通过以下环境变量配置（含默认值）：

elixir
# config/config.ex
config :mailgun_logger, MailgunLogger.Repo,
  username: System.get_env("ML_DB_USER", "mailgun_logger_ci"),
  password: System.get_env("ML_DB_PASSWORD", "johndoe"),
  database: System.get_env("ML_DB_NAME", "mailgun_logger_ci_test"),
  hostname: System.get_env("ML_DB_HOST", "localhost"),

可导出自定义环境变量或使用默认值，然后运行：

bash
# 安装依赖、配置开发证书并启动服务
$ make install

启动项目：

bash
# 运行iex -S mix phx.server
$ make run

若使用自定义环境变量，建议整理到.env文件，运行前加载：

bash
# POSIX系统使用
$ . .env && make run

服务启动后访问[***]

TODO

• 测试覆盖率
• 提供通用日志代理（不依赖papertrail）

许可证

本软件采用MIT许可证授权。

关于Jack + Joe

Mailgun Logger是我们的第一个开源项目，我们很高兴将其发布！我们热爱开源，多年来为各类工具贡献过代码，现在终于有了自己的项目！我们自己也在使用它。

查看发布文章。

了解更多项目，欢迎联系。jackjoe.be