Lightmeter ControlCenter (Alpha)

简介

Monitoring and automation for Open Source email servers, starting with Postfix

欢迎来到Lightmeter控制中心，这是一个开源的mailops监控应用程序。

支持的邮件传输代理

目前支持Postfix MTA。未来计划支持更多的MTA。

快速入门

按照你的喜好安装Lightmeter控制中心。
当使用二进制文件时，你可以使用./lightmeter -workspace ~/lightmeter_workspace -watch_dir /var/log
这个命令将启动应用程序实时监控/var/log （包括在那里发现的旧日志），并将操作文件存储在用户主目录下的lightmeter_workspace 。
如果你使用的是docker镜像，请看README.md中的用法、Docker镜像部分
打开http://localhost:8080/ ，查看网络界面
必要时确保对Web UI的网络访问安全（见已知问题
如果有必要，改变日期范围以看到你刚导入的日志期间的图表

安装

使用Docker安装

每个版本都会生成Docker镜像，并在Gitlab的Lightmeter注册表和Docker Hub中发布。

如果需要，你可以使用latest 标签。使用方法见Docker图像。

此外，我们每天晚上（UTC时间）发布两个docker镜像，标签为：nightly-master 和nightly-develop 。nightly-develop 由来自develop 分支的构建组成，包含最新的修改，非常不稳定，适合在生产中使用。nightly-master 更加稳定，包含将在下一个版本中包含的修改，但也不建议在生产中使用。

从源代码构建

在开发过程中需要以下的依赖性。

Bash
Git的任何最新（如2020年）版本。
Go编译器1.15版或更新的版本。
GCC9.3版或更新的版本。
Libc开发文件。glibc和musl都已成功测试。
GNU Make或兼容。
Ragel6.X版本。我们已经成功测试了6.10版本。目前不支持Ragel 7。
vue cli- 用于基于网络的用户界面。

例如，在Alpine Linux 3.12上，它们可以用安装。

$ apk add git make gcc go libc-dev ragel npm
$ npm install -g @vue/cli@v4.5.9 @vue/cli-service-global@4.5.9

要建立一个发布版本，动态链接到本地libc，执行。

make release

而要创建一个静态链接的（只有在你的libc可以静态链接的情况下才支持）版本，请执行。

make static_release

这将下载所有的依赖项，并建立一个名为lightmeter 的文件，
你可以简单地将其复制到你的Postfix服务器上，并按照Usage 部分中的描述使用它。

如果你打算贡献代码（谢谢你！ :-)），请查看开发。

升级

在升级过程中，支持有限的自动数据迁移。由于数据格式还不稳定，我们不能保证100%的数据安全。

我们建议你在进行重大升级之前创建一个工作区目录的备份。
备份可以通过停止controlcenter，将工作区目录复制到其他地方（或创建一个存档等），
升级controlcenter，最后再启动它。

使用基于替换二进制文件的手动升级很容易实现这一点。
对于基于Docker的安装，你应该在Lightmeter Docker容器之外配置一个工作区目录。
关于如何指定Lightmeter应该使用哪个工作区目录，请参阅 "用法"。

我们已经计划在未来的版本中支持即时备份，
这个过程将变得更容易、更安全、更灵活。

安装

从二进制文件安装

我们在Gitlab上提供了预先构建的、与架构相关的二进制文件，它们
应该可以在任何现代Linux发行版上运行。只需下载它们，将其设置为可执行文件，并按用法中所述执行。

你的操作系统应该默认提供证书颁发机构的证书（许多发行版中的ca-certificates包），
但如果你要保留自己的CA证书，你需要将环境变量SSL_CERT_DIR 。

例如，在Alpine linux上，你可以在执行二进制文件之前使用，。

export

但这几乎总是不需要的，因为控制中心能够正确找到它们。

关于如何找到CA证书的更多信息，请查看相应的Go源代码。

Rsync管理的日志

如果通过-watch_dir 传递的日志目录不在postfix写入的同一文件系统中，而是通过rsync复制的，
你必须传递命令行参数-logs_use_rsync ，否则在第一次执行rsync 后收到的新日志行将不会被注意到。

当使用rsync时，请注意不要使用任何就地同步选项，如--append ，因为控制中心期望
在更新文件时
使用默认的rsync行为
，包括首先在目的地创建一个临时文件，在它完全转移后，将其重命名为最终文件。

Docker镜像

使用docker的最新版本的最简单方法是使用命令。

$ docker run -p 8080:8080 -v "<path_to_workspace>:/workspace:rw" -v "/var/log/:/logs:ro" \
  registry.gitlab.com/lightmeter/controlcenter -workspace /workspace -watch_dir /logs

其中<path_to_workspace> 是一个目录，控制中心将在其中保存数据，这些数据必须在重新启动时持续存在。

然后在http://localhost:8080，打开你的浏览器，访问基于网络的用户界面。

你可以在注册表页中找到所有发布的图像。

NixOS软件包和模块

你可以在Github上找到已发布的pkg、模块、测试平台和 "如何构建和安装它 "的说明。

API

Lightmeter提供了一个简单的REST API，是为用户界面设计的。它是由Web UI使用的。

基于Swagger的API文档和实验页面会在开发构建中自动生成。通过http://lightmeter-address:8080/api ，例如http://localhost:8080/api，访问它们。

无头模式（无Web用户界面

无头模式允许ControlCenter只运行后台，没有Web UI。目前，这是为开发目的准备的。无头模式对于只使用应用程序的API部分将是非常有用的。

运行无头模式需要为此目的构建ControlCenter。

make devheadless # Build ControlCenter
./lightmeter -stdin -verbose --listen :8003 # Example command to start ControlCenter quickly (same as running a normal build)

认证

目前默认支持单用户、基于密码的认证。AllowMultipleUsers 通过自我注册的多用户账户，无需批准，可以通过改变auth/auth.go 中的值并重新编译来启用。

密码重置

你可以使用命令行重置管理员密码。

./lightmeter -email_reset '<registration-email>' -password '<new-password>'

删除用户

通过删除<workspace-name>/auth.db* ，删除所有用户。例如：rm -rf /var/lib/lightmeter_workspace/auth.db* 。
使用sqlite手动删除单个用户，使用sqlite3 <workspace-name>/auth.db 'delete from users where email = "<admin email address>"' 。例如：sqlite3 /var/lib/lightmeter_workspace/auth.db 'delete from users where email = "admin@email-address.com"' 。

使用方法

有关详细信息，请查看用法。

运行lightmeter -help ，显示所有可用命令的列表
在编译（或下载）Lightmeter控制中心后，你应该运行二进制文件lightmeter ，读取日志并启动本地网络服务器，这样就可以在同一网络的8080端口的浏览器中通过Web UI查看Lightmeter控制中心，例如：http://localhost:8080/。你可以使用-listen ":9999" ，例如使用不同的端口或网络接口，在这种情况下，所有接口都在9999端口。
网页用户界面的认证会话默认持续1周。
要通过stdin而不是logfile位置提供日志，使用命令行参数-stdin ，如lightmeter -stdin < [log-data] 。
你也可以接收在unix套接字或TCP端口上监听的日志，如-socket "unix;/path/to/socket.sock" 或
-socket "tcp;localhost:9999" 。需要注意的是，这种套接字通信是未经认证和加密的，所以只能在安全的环境中使用它
要提供单一的日志文件，使用命令行参数-stdin ，如tail -f /path-to-file.log | lightmeter -stdin 。
邮件服务器的数据被存储在不同的工作空间中，这样不同的服务器可以被单独监控。工作区的目录默认设置为/var/lib/lightmeter_workspace ，可以用-workspace /path/to/workspace 。
由于Postfix日志不包含作为每行日期一部分的年份，当使用-stdin ，被处理的日志的年份被假定为当前年份。要覆盖这一点并手动指定一个年份，请使用-log_starting_year ，例如-log_starting_year 2018
Lightmeter还可以 "监视 "由logrotate管理的postfix日志目录，导入现有的文件
（即使是用gzip压缩的），并等待导入后发生的新的日志文件。
要使用它，启动lightmeter，参数为-watch_dir /path/to/dir ，它可能是/var/log/mail 。
如果已经导入了这些日志，Lightmeter不会再导入，以防进程重新启动。
你可以在Apache httpd或nginx等反向http代理后面运行它，甚至在不同的路径上。不需要额外的配置。

目前，以下模式的日志文件被 "监视"。

mail.log
mail.warning
mail.err
maillog
zimbra.log

环境变量

对于Lightmeter的云端安装，可能需要通过环境变量来设置参数，而不是命令行参数（不能总是使用）。

下面是你可以通过环境变量设置的所有参数，以及它们各自的命令行等价物。

LIGHTMETER_WORKSPACE=/path/to/workspace (-workspace)
LIGHTMETER_WATCH_DIR=/var/log (-watch_dir)
LIGHTMETER_VERBOSE=true (-verbose)
LIGHTMETER_LISTEN=localhost:9999 (-listen)
LIGHTMETER_LOGS_SOCKET=unix;/path/to/socket.sock (-logs_socket)
LIGHTMETER_LOGS_USE_RSYNC=true (-logs_use_rsync)
LIGHTMETER_LOGS_STARTING_YEAR=2019 (-log_starting_year)
LIGHTMETER_LOG_FORMAT=prepend-rfc3339 (-log_format)

旋转的文件

我们能够识别由logrotate 归档的文件，并在应用程序首次运行时导入这些文件。
目前只支持gzipped和未压缩的文件。

支持存档的日志文件的后缀是。

mail.log.2.gz和类似的文件，文件越老，后缀数字越大。
mail.log-20030102.gz，后缀数字是一个日期，数值越小，文件就越旧。

如果你使用不同的日志命名惯例，请在Gitlab上创建一个问题。

Syslog 兼容性

如果你使用-watch_dir 或LIGHTMETER_WATCH_DIR 环境变量来读取日志，我们目前只支持以下 syslog 文件格式。

rsyslog.conf	命令行选项	环境变量
`RSYSLOG_TraditionalFileFormat`	`-log_format default` 或者根本不通过这个选项	`LIGHTMETER_LOG_FORMAT=default` ，或者根本不定义
`RSYSLOG_SyslogProtocol23Format`	`-log_format rfc3339`	`LIGHTMETER_LOG_FORMAT=rfc3339`

如果你使用不同的格式，请通过Gitlab问题让我们知道。

导入日志

导入过程会花费很长时间，这取决于你有多少个文件和它们有多大。

重要的是，不要把-watch_dir 与其他获取日志的方式一起使用，Lightmeter的未来版本将禁用这种行为。

如果你有一个类似的错误。

2020/05/29 13:45:05 Missing file mail.log . Instead, found:  /var/log/mail/mail.log.2.gz

这意味着你应该有一个文件mail.log ，这意味着你应该检查你的Postfix安装，并确保它正确地发出日志。

从Logstash读取

注意：这是一个非常实验性的支持，没有经过良好的测试或支持。它可以吃掉你的日志!

控制中心可以通过网络或unix域套接字读取日志，这可以用来接收来自Logstash的日志。

需要注意的是，这种支持不支持任何认证或安全，所以一定要在安全的网络中使用它，或者提供你自己的
安全层（VPN、SSH隧道等）。

首先，启动控制中心，选择-socket tcp=:9999 ，在TCP端口9999中监听，或-socket unix=/path/to/socket.sock 。

使用默认的JSON编码的日志

从1.8版本开始，我们支持通过Logstash发送的默认JSON编码的日志，这意味着你不需要改变你的Logstash配置。

你需要添加命令行选项-log_format logstash ，或者设置环境变量LIGHTMETER_LOG_FORMAT=logstash 。

然后按以下方式配置Logstash。

filter {
  if [log][file][path] == "/var/log/mail.log" {
      clone {
        add_field => { "log-type" => "mail" }
        clones => ["lightmeter"]
      }
  }
}

output {
  if [log-type] == "mail" and [type] == "lightmeter"{
        tcp {
            host => "address-of-control-center-host"
            port => 9999
        }
    }
}

使用一个自定义的日志格式

或者，添加命令行选项-log_format prepend-rfc3339 （或环境变量LIGHTMETER_LOG_FORMAT=prepend-rfc3339 ），
这意味着它期望在每个日志行的开头出现一个时间。

然后将Logstash配置为类似于下面的内容（感谢Alexander Landmesser的帮助 :-)）。

filter {
  if [log][file][path] == "/var/log/mail.log" {
      clone {
        add_field => { "log-type" => "mail" }
        clones => ["lightmeter"]
      }
  }
}

output {
  if [log-type] == "mail" and [type] == "lightmeter"{
        tcp {
            host => "address-of-control-center-host"
            port => 9999
            codec => line {
                format => "{[@timestamp]} %{[message]}"
            }
        }
    }
}

重要提示:控制中心希望接收所有的Postfix日志，所以不要使用Logstash或ElasticSearch过滤任何日志，
否则控制中心将无法正常工作。

这样的机制是非常强大的，我们才刚刚开始探索它。如果你的Postfix日志是用其他格式包装的（JSON、Protobuf等），
你应该可以很容易地添加对它的支持。请看一下文件logeater/transform/prepend-rfc3339.go ，看看
上面使用的-log_format prepend-rfc3339
的实现
。

特征文件

通知

集成slack

在你的slack账户上创建一个应用程序，进入api.slack.com/

点击 "Create Custom APP"，之后你会看到一个弹出窗口，用于配置你的应用程序（https://api.slack.com/apps）。

选择一个 "开发Slack工作区"，并给你的应用程序一个名称。

点击 "权限 "卡或在侧边栏点击 "OAuth & Permissions"。
在 "范围 "下点击 "添加一个OAuth范围"。
从下拉菜单中添加 "chat:write"。
在 "OAuth令牌和重定向URLs "下，点击 "安装到工作区"。
在下面的页面中点击 "允许"。
将新生成的OAuth令牌复制到安全的地方。
通过输入所需的频道邀请机器人到你的频道：/invite @bot-name （替换名称，并使用自动完成的提示）。

将令牌和频道的详细信息添加到lightmeter，进入设置页面

祝贺你成功配置了slack通知

域名映射

支持域名映射。这意味着在必要时，相互关联的远程主机被视为一个整体（例如outlook.com和hotmail.com）。

目前，映射在应用程序中是硬编码的 - 改变映射需要重建应用程序。

映射存储在domainmapping/mapping.json ，默认覆盖最大的远程主机。通过编辑该文件，然后重建，可以很容易地定制映射。

请考虑通过提出合并请求来扩展默认的映射，使所有用户受益

消息侦探

管理视图

你可以点击导航栏上的 "搜索 "图标进入信息侦探的管理视图。
使用发件人地址、收件人地址和你想要检查的时间间隔，你可以确定在给定时间范围内处理的任何信息的状态。

搜索结果将包括信息的状态、队列ID、信息被处理的时间和每次递送尝试的状态代码。

一条消息可以有以下状态之一。

发送成功的信息
被收件人的邮件供应商拒绝的邮件被退回。
暂时被拒绝并重新尝试的邮件被推迟发送
递延次数过多而放弃投递，则为过期。
退回：当退回通知被送回给原发件人时（只有当你的Postfix被配置为这样做）。

公共视图

你可以在设置页面中为任何未认证的用户启用信息检测。

你提供链接的认证用户可以使用与管理员相同的搜索条件独立检查邮件的命运。他们也将在搜索结果中看到与管理员相同的信息量。

此外，用户还可以选择将任何退回和过期的结果上报给邮件服务器管理员。
然后Lightmeter将生成一个洞察力，显示所有的细节，包括队列ID，以便管理员进一步调查。
如果你启用了通知功能，这也会触发一个通知。

如果你为你的终端用户启用了消息侦探，请确保与他们分享公共页面的URL。
速率限制适用于搜索次数，目前最大的搜索次数是20次。

已知的问题

高风险

Web UI默认在没有SSL（未加密）的情况下加载，所以如果在公共网络上传输，证书会有风险（计划中的修复：#480）。
由于没有磁盘回收策略，SQLite数据库的大小将永远线性增长（计划修复：#77）。
大容量邮件服务器的内存消耗是未知的（计划修复：#238）。

低风险

一些洞察力的触发过于频繁（取决于使用情况），可能会使主页充满重复的细节（计划修复：#231,#157）。
点击主页上的图表部分可能会导致报告误导性的统计数字（计划修复：#63

开发

使用VueJs的前端开发

ControlCenter的Web UI使用VueJS框架和相关工具。前端实际上是一个独立的Javascript应用程序，它通过API与后端进行交互。当为生产而构建时，ControlCenter的后端为方便起见，为前端文件服务。

前台文件，如javascipt和css，需要被编译并移动到正确的目录中，然后才可以被Web浏览器使用。这个过程是由make命令/构建脚本和VueJS终端工具自动处理的，用于开发。

开发/修改前端文件的最有效的工作流程是将前端与后端分开运行（与生产模式不同），使用Vue CLI提供服务并在开发模式下自动重建文件。这可以让你几乎立即看到对前台文件的修改，而不需要执行任何命令或手动重建或编译任何文件。

说明

打开两个终端窗口或标签，工作目录设置为ControlCenter的资源库根。

在第一个终端中，以无头模式构建并运行ControlCenter。
在第二个终端中启动VueJS前端开发服务器（在开发模式下）。make serve_frontend_dev
第二个终端的输出应该告诉你哪个本地URL/端口可以访问开发界面

对前端文件所做的任何改动都会被自动检测到，必要的文件会被重建，并且改动会在你的本地浏览器中立即生效。要应用对后端文件的修改，你需要从源头上重建后端，因为前端现在是独立运行的，不会影响后端/golang文件。

浏览器自动化测试

这些测试（也被称为用户验收测试）在acceptance_tests 目录中找到，由Gauge和Taiko执行。这些测试是CI/CD的一部分，在每次GitLab提交时执行。

关于如何手动运行这些测试，请参考acceptance_tests/README.md 文件中的具体文档。

使用户界面可被翻译（i18n）。

下面的命令将在界面文件（目前是www 目录下的文件）中寻找可翻译的单词，并生成一个英文的.po 文件。make code2po

使后端字符串可被翻译（i18n

可翻译的字符串可以在不同的文件中找到，比如后端使用的Go代码，或者web ui中使用的Vue/html/js文件。

为了更新可翻译的字符串，用命令使它们对翻译者可用。

$ make messages

例子。

package

故障排除

从x版本升级到y版本后的问题

controlcenter加载ui的许多问题可以通过清除浏览器cookies和cache来解决。

支持单位

本项目在NGI-POINTER项目的框架内得到了欧盟地平线2020研究和创新计划的资助，该项目由第871528号资助协议资助。

该项目在NGI-ZERO项目的框架内得到了欧盟地平线2020研究和创新计划的资助，资助协议号为825310。

许可和版权信息

本项目采用AGPL-3.0许可。然而，一些文件采用了不同的许可证，为了获得准确的信息，请检查个别文件和文件.reuse/dep5 。

GitHub

github.com/lightmeteri…

开源电子邮件服务器的监控和自动化，从Postfix开始