后端开发工具测试【免费下载链接】maildev:mailbox: SMTP Server Web Interface for viewing and testing emails during development.项目地址https://gitcode.com/gh_mirrors/ma/maildev点击查看免费下载MailDev 是一个面向开发场景的 SMTP 捕获服务器加 Web 查看界面工具而maildev/cli即maildev命令是把存储、SMTP、API、UI 与 MCP 能力编排到一起的总入口。本文以 packages/cli/CHANGELOG.md 为骨架逐条拆解 3.0 稳定版相对上一版本的关键行为变化从「完整项目重建」到 Docker 健康检查修复、port: 0临时端口、HTTPS 支持、存储与消息大小上限、中继状态记录等。读完本文你将能精准理解每个新参数与修复背后的原理并知道如何在自己的开发环境、Docker 容器或并行测试框架中正确使用这些能力。一、3.0.0一次完整的项目重建CHANGELOG 中 3.0.0 的 Major Changes 只有一条Complete project re-build完整项目重建。这不是一次简单的补丁升级而是把整个项目从单体结构重写为 TypeScript pnpm workspace 的 monorepo同时「在最小化破坏性变更的前提下」完成重建。从 packages/cli/package.json 可以看到CLI 包依赖了maildev/api、maildev/core、maildev/mcp、maildev/smtp、maildev/ui五个工作区包并基于commanderv12实现参数解析要求 Node.js 20。重建并不意味着推倒重来v2 的全部 CLI 参数在 v3 中被原样保留。packages/cli/src/options.ts 的注释明确写着 All Commander.js options matching v2 exactly plus new v3 options-s/--smtp、-w/--web、--incoming-*、--outgoing-*等历史参数都继续可用这也是升级路径平滑的原因。对应到代码结构CLI 包的入口 packages/cli/src/index.ts 对外导出三层能力配置层getDefaultConfig、loadConfig、resolveConfig、validateConfig、loadEnvConfig编排层Orchestrator/createOrchestrator负责把存储、SMTP、API 串成一条启动链CLI 层configureOptions、ENV_VARS、CONFIG_FILES。默认配置定义在 packages/cli/src/config/defaults.tsSMTP 端口1025、Web 端口1080、SMTP 绑定::、Web 绑定0.0.0.0、maxEmails: 0无上限、maxMessageSize: 50MB。这些默认值都与 v2 行为对齐。二、Docker 健康检查修复开箱即健康3.0.0 引入了一个独立的健康检查入口dist/bin/healthcheck.js源码见 packages/cli/src/bin/healthcheck.ts它解决了三个实际问题让容器「开箱即报告 healthy」改探127.0.0.1而非localhostissue #537当localhost被解析为 IPv6 地址::1、而 Web 服务器只绑定了 IPv4 时旧的探测会失败。现在统一使用127.0.0.1彻底规避解析歧义。--disable-web时回退为 TCP 探测 SMTP 端口issue #544当 Web UI 被禁用时不存在 HTTP 端点可探健康检查会改为对 SMTP 端口做一次 TCP 连接检测保证这类容器依然能报告 healthy。对应resolveHealthcheck中的逻辑若 MAILDEV_DISABLE_WEB 为真 → 对 127.0.0.1:SMTP_PORT 做 TCP connect 否则 → GET http(s)://127.0.0.1:WEB_PORTbasePath/api/healthz规范化MAILDEV_BASE_PATHNAMEissue #542旧实现中尾随斜杠可能让探测 URL 出现//。normalizeBasePath会把路径统一成或/foo形式保留前导斜杠、去掉所有尾随斜杠再拼接api/healthz。此外当MAILDEV_HTTPS开启时探测会自动改用 HTTPS 并忽略证书校验rejectUnauthorized: false因为 MailDev 的 HTTPS 模式通常使用自签名证书——健康检查只关心回环存活不关心证书合法性。三、port: 0与读取实际绑定地址并行测试的利器旧行为bugnew MailDev({ smtp: 0 })会被静默忽略。原因在于旧代码使用options.port || DEFAULT_PORT这种写法——显式的0被当作「未设置」回退到默认端口 1025。新行为改用??判空因此0现在会向操作系统请求一个由内核分配的临时端口ephemeral port并且实际绑定的端口会从监听 socket 上读回来。配套地两个服务器都暴露了绑定地址读取 APISMTPServer#getAddress()→{ host, port }SMTPServer#getPort()APIServer#getAddress()→{ host, port } | null未监听时为nullAPIServer#getPort()在 packages/cli/src/server/orchestrator.ts 的启动流程中SMTP 启动后会记录this.smtp.getAddress()得到的地址——注释明确指出「记录的是实际绑定地址而非请求值这样smtp: 0会报告 OS 分配的临时端口而不是 0」。典型使用场景并行测试框架如 Vitest/Jest 的 worker 进程中每个 worker 想运行一个独立的 MailDev 实例。过去必须手工为每个 worker 分配不冲突的端口现在直接smtp: 0 读取getPort()每个实例自动获得唯一端口无需任何手工协调。四、MAILDEV_AUTO_RELAY环境变量让 Docker/环境变量方式与 CLI 对齐此前--auto-relay/--auto-relay-rules只能通过命令行开启。3.0 让 Docker 和其他基于环境变量的部署方式获得同等能力新增MAILDEV_AUTO_RELAYMAILDEV_AUTO_RELAY_RULES其中MAILDEV_AUTO_RELAY的取值语义很讲究packages/cli/src/config/env.ts 里的parseAutoRelay是这样实现的环境变量值语义true、1、空字符串存在但为空开启自动转发转发到每封邮件的原始收件人false、0关闭自动转发其他任意值将该值当作覆盖收件人所有邮件转发到该地址特别注意MAILDEV_AUTO_RELAY不能被放进布尔环境变量集合BOOLEAN_VARS中解析——那样会把一个邮箱地址误解析成false。parseBoolean只负责incomingSecure、outgoingSecure、https、disableWeb、mcp、verbose、silent等真正的布尔开关。五、MCP HTTP 传输的多会话支持MailDev 3.0 提供内置 MCP 服务器maildev --mcp暴露在/mcp端点。3.0 修复了一个会导致第二个 MCP 客户端无法连接的问题旧问题所有会话共享同一个 MCP server 实例第二个客户端连接时会报Already connected to a transport.每个传输只能绑定一个会话。新行为每个会话获得独立的 MCP server 实例不再互相阻塞携带未知 session ID 的请求会返回规范的 JSON-RPC 错误关闭时maildev.stop()会主动关闭所有打开的 MCP 会话。关于 MCP 的两个传输HTTP/Streamable、客户端配置、可用工具/资源/提示词的完整说明可参考 docs/mcp.md。六、HTTPSWeb UI / REST API 真正启用 TLS过去--https、--https-cert、--https-key三个参数存在但不生效——标志位定义了但 Web 服务器始终只提供明文 HTTP。3.0 让 Fastify 服务器真正兑现这些选项CLI--https--https-cert file--https-key file环境变量MAILDEV_HTTPS、MAILDEV_HTTPS_CERT、MAILDEV_HTTPS_KEY在 packages/cli/src/config/validate.ts 中开启 HTTPS 时httpsCert和httpsKey都是必填项且会校验文件确实存在existsSync缺失即报错退出。另外 Docker 健康检查会检测MAILDEV_HTTPS并改用 HTTPS 探测见上文第二节确保启用 TLS 的容器也能报告 healthy。七、存储上限maxEmails内存与邮件目录双重有界默认行为保持 MailDev 的历史特性不设上限、无数据丢失--max-emails 0默认值。设置正数上限后新邮件到达且已满时丢弃最旧的邮件连同它的.eml文件与附件一起删除因此内存和持久化邮件目录都能保持有界设置上限后启动时会修剪邮件目录里上次运行遗留的多余文件。编排层 packages/cli/src/server/orchestrator.ts 中的实现顺序很关键先pruneMailDir(maxEmails)修剪磁盘上残留的.eml在第 6b 步SMTP 启动之后、恢复邮件之前再loadMailsFromDirectory()恢复第 6c 步且只加载最新maxEmails封——修剪与加载的数量边界保持一致。maildev --max-emails 1000 # 只保留最新的 1000 封 maildev --max-emails 0 # 全部保留默认Breaking change 提示maildev/core的Storage接口新增了onEvicted回调同时导出了新的EvictHandler类型和mapLimit工具函数——如果你自己实现了自定义存储需要适配这个接口变更。一个值得注意的运维事实来自 packages/cli/README.md不限量的默认配置下内存和邮件目录会随收件箱增长以典型邮件大小估算10,000 封邮件大约占 150 MB 堆内存所以长时间运行或高吞吐场景建议设置上限。八、最大消息大小--max-message-size抵御超大 MIME 攻击新增--max-message-size选项环境变量MAILDEV_MAX_MESSAGE_SIZE默认50 MB即50 * 1024 * 1024见 packages/cli/src/config/defaults.ts。它的作用链路SMTP 服务器通过SIZE扩展向客户端通告大小限制行为规范的客户端会自行跳过超限邮件超过限制的消息被直接拒绝送入解析器的字节数被截断在上限内——这是最关键的一点一个包含海量 MIME 分片sibling-part的恶意 multipart 消息不再能长时间占用解析器对应 issue #531 的 unbounded MIME fanout 问题设为0可完全禁用该限制。maxMessageSize的校验规则在 packages/cli/src/config/validate.ts 中必须是非负整数否则报 must be a non-negative integer (0 disables the limit)。九、中继投递状态relayedAt与relayedTo中继relay成功后存储的邮件现在会记录投递状态relayedAt最后一次中继的时间relayedTo实际投递到的收件人列表。这让 REST API 可以回答「这封邮件是否被中继过、中继到了哪些地址」。实现上它挂接到共享的relayEmail路径——自动中继auto-relay与手动中继端点共用同一条逻辑因此两种方式都会记录状态对应 issue #199。十、重启恢复持久化邮件设置--mail-directoryMAILDEV_MAIL_DIRECTORY后启动时会把目录里已有的.eml文件重新加载回 UI——邮件在重启后仍然可见。典型场景是容器/Pod 重启时挂载了持久卷邮件因此跨重启存活。编排层有一个刻意的设计细节只有显式配置mailDirectory时才会执行恢复。因为未配置时系统会回退到tmpdir()/maildev作为邮件目录见 packages/cli/src/server/orchestrator.ts 的const mailDir this.config.mailDirectory || join(tmpdir(), maildev)如果对临时目录也做恢复就会把以前无关运行残留的邮件重新复活——所以恢复逻辑只在显式持久化时启用。十一、SMTP 端口冲突拒绝启动而非崩溃旧问题issue #568当 SMTP 端口不可用如EADDRINUSE时错误从服务器的error事件里到达再在回调内部被重新抛出——它逃逸成未捕获异常直接拖垮进程而start()的 Promise 永远处于 pending 状态。这意味着try/catch包住await start()根本捕获不到错误。新行为启动错误被路由到start()的 Promise——await maildev.start()会以底层错误如EADDRINUSEreject由调用方决定如何处理启动后的运行时错误仍然通过error事件可观察没有监听器的EventEmitter抛错不再致命。这也体现在MailDev类的 API 设计上packages/cli/src/index.tsstart()返回PromiseServersstop()、isRunning()、getServers()构成完整的生命周期管理接口。十二、配置体系全景四个来源与优先级要完整用好上述所有能力需要理解 CLI 的配置合并规则。CLI 的配置来源与优先级为CLI 参数 环境变量 配置文件 默认值对应 packages/cli/src/config/merge.ts 中resolveConfig的实现顺序先取getDefaultConfig()合并配置文件再合并环境变量最后覆盖 CLI 参数——每一层只覆盖「已定义」的字段。配置文件支持以下形式packages/cli/src/config/loader.ts会自动从当前目录向父目录逐级查找文件格式.maildevrc.jsonJSONmaildev.config.tsTypeScriptmaildev.config.js/.mjs/.cjsJavaScript / ESM / CJS也可以用--config file显式指定路径此时找不到会直接报错。示例{ smtp: 1025, web: 1080, verbose: true }完整参数与对应环境变量速查表与 packages/cli/src/options.ts 定义一致参数环境变量说明-s, --smtp portMAILDEV_SMTP_PORTSMTP 捕获端口默认 1025-w, --web portMAILDEV_WEB_PORTWeb GUI 端口默认 1080--ip addressMAILDEV_IPSMTP 绑定地址默认::--web-ip addressMAILDEV_WEB_IPHTTP 绑定地址默认0.0.0.0--mail-directory pathMAILDEV_MAIL_DIRECTORY邮件持久化目录未设置则用内存存储--max-emails countMAILDEV_MAX_EMAILS保留上限最旧的连同文件一起丢弃默认 0 不限--httpsMAILDEV_HTTPSWeb 改用 HTTPS--https-key fileMAILDEV_HTTPS_KEYSSL 私钥文件路径--https-cert fileMAILDEV_HTTPS_CERTSSL 证书文件路径--incoming-user / --incoming-passMAILDEV_INCOMING_USER/PASSSMTP 入站认证--incoming-secureMAILDEV_INCOMING_SECURE入站 SMTP 使用 SSL--incoming-cert / --incoming-keyMAILDEV_INCOMING_CERT/KEY入站 SSL 证书/私钥--outgoing-host / --outgoing-portMAILDEV_OUTGOING_HOST/PORT出站中继 SMTP 主机/端口端口默认 25--outgoing-user / --outgoing-passMAILDEV_OUTGOING_USER/PASS出站中继认证--outgoing-secureMAILDEV_OUTGOING_SECURE出站中继使用 TLS/SSL--auto-relay [email]MAILDEV_AUTO_RELAY自动中继可选覆盖收件人--auto-relay-rules fileMAILDEV_AUTO_RELAY_RULES自动中继过滤规则文件--web-user / --web-passMAILDEV_WEB_USER/PASSWeb 界面 HTTP Basic 认证--base-pathname pathMAILDEV_BASE_PATHNAMEURL 基础路径默认/--disable-webMAILDEV_DISABLE_WEB禁用 Web 界面--hide-extensions ext—不向客户端通告的 SMTP 扩展逗号分隔--max-message-size bytesMAILDEV_MAX_MESSAGE_SIZE最大消息大小默认 524288000 禁用--mcpMAILDEV_MCP启用/mcp端点的 MCP 服务器--config file—指定配置文件路径-v, --verbose/--silentMAILDEV_VERBOSE/MAILDEV_SILENT详细日志 / 静默--log-mail-contents—以 JSON 形式打印每封入站邮件校验层packages/cli/src/config/validate.ts还会给出有用的防御性检查端口必须是 1–65535 的整数、HTTPS/入站 SSL 需要配套证书与私钥、incomingUser与incomingPass必须成对出现、中继认证的 user/pass 必须同时提供、maxEmails必须是非负整数等同时给出若干警告如 SMTP 与 Web 端口相同、disableWeb与mcp同开、verbose与silent同开且 silent 优先。总结MailDev 3.0 的 CLI 层不只是「重写了一遍」而是把长期存在的几个痛点逐一修复Docker 健康检查现在真正开箱即健康smtp: 0为并行测试提供了零冲突端口方案MAILDEV_AUTO_RELAY等环境变量让容器化部署与命令行体验对齐MCP 支持多会话HTTPS 真正生效maxEmails与max-message-size让长期运行的内存与磁盘占用可控中继状态与重启恢复让邮件的生命周期可观测、可持久。升级时只需注意一个破坏性变更maildev/core的Storage实现需要补充onEvicted。对于从 v2 升级的既有用户所有历史 CLI 参数均保持兼容迁移成本极低。赞分享后端开发工具测试【免费下载链接】maildev:mailbox: SMTP Server Web Interface for viewing and testing emails during development.项目地址https://gitcode.com/gh_mirrors/ma/maildev点击查看免费下载相关推荐Velero存储后端监控存储系统健康检查Velero存储后端监控存储系统健康检查 概述 在Kubernetes集群备份与恢复场景中存储后端的健康状态直接决定了数据保护的有效性。Velero作为业界云原生灾备存储后端GyroFlow免费开源视频防抖神器告别画面抖动专业级稳定效果轻松实现GyroFlow免费开源视频防抖神器告别画面抖动专业级稳定效果轻松实现 你是否曾为拍摄的视频画面抖动而烦恼无论是手持拍摄的日常vlog、运动相机记录下的极视频处理桌面应用音视频RoadRunner容器健康检查Docker健康检查配置RoadRunner容器健康检查Docker健康检查配置 你是否遇到过Docker容器显示运行中但实际服务已崩溃的情况RoadRunner作为高性能PH后端Web服务器上一篇PyTorch-RL环境搭建教程5分钟配置强化学习开发环境下一篇SoniTranslate 2024更新解析新增20语言支持与批量处理功能创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
