内容

目录

报告错误前

Apache Tomcat® 社区由 Apache Tomcat 用户、在讨论列表中帮助回答问题的人、贡献文档和补丁的人以及开发和维护 Apache Tomcat 代码的人组成。几乎所有日常协助解决错误报告的人都是出于各种原因而这样做，并且几乎所有这些工作都是在他们自己的业余时间完成的。

许多报告的错误最终并非 Apache Tomcat 代码中的错误，而是由于配置错误、已安装应用程序引起的问题、操作系统问题等。

在报告错误之前，请尽力自行解决问题。

如果您需要帮助，请在用户邮件列表上提问。

本文档的其余部分将引导您使用可用于解决您所遇到问题的资源。

Bugzilla 不是支持论坛

Bugzilla 是一个用于跟踪错误报告和功能请求的工具。它用于组织 Apache Tomcat 项目的工作，以确保此类问题不会被遗忘，并记录它们是如何解决的。

Bugzilla 不是一个提问如何配置您自己的系统，或如何解释您不理解的错误消息或行为的地方。如果您有问题，请在用户邮件列表上提问。

当您收集到足够的信息来诊断您的问题，并且它确实是 Apache Tomcat 中可以修复的错误时，请随意为其创建或重新打开您的 Bugzilla 问题。您可以在邮件列表归档中找到您讨论的链接，并将其包含在您的错误报告中。

帮助解决 Apache Tomcat 问题的资源

以下是一些您可以在报告错误之前用来帮助解决您所遇到问题的资源。

问题排查

  • 文档 – 查阅您正在使用的 Apache Tomcat 版本的文档。您面临的问题可能已在文档中得到解决。请注意，文档是可搜索的。
  • 日志 – Apache Tomcat 生成的日志在诊断问题时是非常宝贵的资源。请仔细查阅它们。您可能希望在 Apache Tomcat 配置中启用调试输出，以便获得更多信息来帮助诊断问题。您可能希望配置访问日志（一个阀门）来记录哪些请求到达了 Tomcat 以及 Tomcat 对它们的响应。
  • 维基 – 搜索维基。那是每个人都可以贡献的非官方文档。
  • 常见问题 – 搜索作为维基一部分的Tomcat 常见问题。

Apache Tomcat 讨论列表

您很可能不是第一个遇到问题的人。其他人可能已经找到了解决方案。邮件列表归档可能包含有助于您解决问题的讨论。

有关列表的更多信息，请参阅邮件列表页面。

另请参阅寻求帮助页面。

已知问题

请搜索错误数据库，查看您遇到的错误是否已被报告。请查看变更日志页面，了解已修复的错误。未发布版本的 Tomcat 变更日志也可用。更多详情如下。

最新版本

尝试使用最新发布的 Apache Tomcat 版本重现您的问题。

查找已知问题

搜索错误数据库

请搜索错误数据库，查看您遇到的错误是否已被报告。

  • 该错误可能已修复，并在更高版本或每夜构建中可用。
  • 其他人可能已经报告了该错误，您可以添加支持信息以帮助重现和解决该错误。

搜索页面在此处。还有高级搜索页面。

以下是一些搜索技巧。

  1. 搜索已关闭的错误以及未关闭的错误。

    在高级搜索页面，您可以清除“状态”字段以避免按状态过滤。

  2. 搜索不同版本的 Tomcat。

    在错误数据库中，Tomcat 由多个“产品”表示。同一个问题只应报告一次，但修复可能适用于不同的 Tomcat 版本。这样做时，错误报告会在不同的产品之间移动。最初针对 Tomcat 9 报告的错误可能会被移至 Tomcat 8，甚至稍后移至 Tomcat 7。因此，一次性搜索所有版本是有意义的。

    以下是支持产品的快速列表

    • Tomcat 11, Tomcat 10 和 Tomcat 9 – Tomcat 11.0.x, 10.1.x 和 9.0.x
    • Tomcat 连接器 – Tomcat 与其他 Web 服务器的集成
    • Tomcat 原生 – 基于 APR 的 Tomcat 原生 HTTP 和 AJP 连接器
    • Tomcat 模块 – 额外的 Tomcat 组件
    • Taglibs – Apache Taglibs 子项目

  3. 不仅搜索摘要字段，也搜索评论字段

    在高级搜索页面打开“详细错误信息”，然后将您的查询输入到“评论”字段中。

  4. 您可以将结果限制为最近更改的问题。

    在高级搜索页面打开“按更改历史记录搜索”，然后在“之间”字段对中的第一个字段中键入“-2m”以将结果限制为过去 2 个月内更改的问题。

  5. 有些错误不属于 Tomcat。

    Tomcat 捆绑了来自其他几个项目的库。您可以在您的发行版中查看 RELEASE-NOTES 和 NOTICE 文件以获取详细信息。更多详情请参见下面的单独部分。

变更日志

如果您正在寻找最近修复的问题，有几个地方可以查看。

  • 已发布版本的变更日志文件

    这些文件发布在 Tomcat 网站上。

  • 尚未发布版本的变更日志文件

    这些在源代码中可用。

    它们是 XML 格式，并附有样式表。因此，现代网络浏览器可以很好地显示它们。

    这些文件也可在每晚文档构建中获得。有关详情，请参阅Buildbot页面。

链接

产品 变更日志 (已发布) 变更日志 (未发布)
Tomcat 11.0 (主分支) changelog.html changelog.html - CI
Tomcat 10.1 changelog.html changelog.html - CI
Tomcat 9.0 changelog.html changelog.html - CI
Tomcat 连接器 changelog.html changelog.xml
Tomcat Native 2.0 changelog.html changelog.xml
Tomcat Native 1.2 changelog.html changelog.xml

第三方组件

Tomcat 捆绑了来自其他几个项目的库。有关详细信息，请参阅您的发行版中的 RELEASE-NOTES 和 NOTICE 文件。用于构建 Tomcat 的组件版本定义在源代码发行版中的 build.properties.default 文件中。

值得注意的组件有

  • Tomcat 服务启动器 – commons-daemon-*, tomcatN.exe, tomcatNw.exe

    该服务启动器由 Apache Commons Daemon 项目提供。

    根据该项目的术语，*nixes 启动器称为 jsvc，Windows 启动器称为 procrun。Tomcat 发行版中的 tomcatN.exe 和 tomcatNw.exe 程序只是 Apache Commons Daemon 二进制发行版中 prunsrv.exe 和 prunmgr.exe 的重命名版本。

  • DBCP 数据库连接池实现 – tomcat-dbcp.jar。

    此连接池实现由 Apache Commons Pool 和 Apache Commons DBCP 项目提供。

    来自这两个项目的类被重命名到不同的包中，以避免当 Web 应用程序使用相同库时，重新编译并打包到单个 JAR 文件中可能产生的冲突。

  • JDBC 数据库连接池实现 – tomcat-jdbc.jar。

    此连接池实现适用于 Tomcat 7 及更高版本，它来自作为 Tomcat 模块一部分的 jdbc-pool 项目。此库与主 Tomcat 并行开发。

  • Tomcat Maven 插件子项目在 JIRA 数据库中跟踪其问题。

报告 Apache Tomcat 错误

请确保问题是 Apache Tomcat 中的错误，而不是您的 Web 应用程序中的错误。

请注意，安全相关问题不应通过 Bugzilla 报告。

如何撰写错误报告

请提供尽可能多的信息。如果调查问题的人无法重现错误，则很难修复。另请参阅错误撰写指南。

错误提交从此处开始。您必须在错误报告中包含以下信息

  • 产品。以下是支持产品的列表

    • Tomcat 11 – Tomcat 11.1.x 和 tomcat.apache.org 网站
    • Tomcat 10 – Tomcat 10.1.x
    • Tomcat 9 – Tomcat 9.0.x
    • Tomcat 连接器 – Tomcat 与其他 Web 服务器的集成。用于 Apache HTTPD 及其他 Web 服务器的 mod_jk 模块。
    • Tomcat 原生 – 使用原生代码并链接 Apache APR 和 OpenSSL 库的 Tomcat HTTP 和 AJP 连接器
    • Tomcat 模块 – 额外的 Tomcat 组件，例如 jdbc-pool
    • Taglibs – Apache Taglibs 子项目

  • 版本 – Apache Tomcat 版本。

    请不仅从列表中选择，还要在您的文本中提及。错误描述可以更新，因此在文本中提及版本也很重要。

  • 组件 – 存在错误的组件。

    如果您不知道，请随意猜测。

  • 平台和操作系统 – Tomcat 运行所在的硬件平台和操作系统。

  • 严重程度 – 对于普通错误报告为 normal，对于增强请求为 enhancement。

    如果您倾向于将其标记为 critical，您可能做错了。很可能该问题已已知并已修复，或者根本不是一个问题。

  • 配置详情

    请在您的文本中提及这些

    • Java 版本 – 用于运行 Tomcat 的 Java 运行时环境的供应商和版本。
    • 如果 Tomcat 在 Apache HTTPD 或其他 Web 服务器后面使用 – 请说明其版本和配置方式。
    • 正在使用的 Tomcat 连接器。Tomcat 中有多种连接器实现。正在使用哪种连接器会在 Tomcat 启动期间的日志中显示。

  • 附件

    如果有助于跟踪错误，请附上配置文件和 Tomcat 日志文件。

  • 重现步骤

    请描述如何在干净的 Tomcat 安装上重现您的问题。如果可能，请提供一个简单的示例 Web 应用程序来演示该问题。

如何提交补丁和增强请求

Tomcat 的增强请求提交流程与错误报告相同，但在严重程度字段中，您将选择“enhancement”值。

对于通过 GitHub 可用的组件，您可以将建议的补丁作为拉取请求提供。或者，您可以将建议的补丁附加到 Bugzilla 问题中。提供补丁时，请说明它适用于源代码的哪个版本。欢迎任何补丁，但我们更喜欢使用统一差异 (Unified Diff) 格式的补丁。这些可以使用 diff -u 命令或 svn diff 或 git diff 命令生成。

要修补和构建 Apache Tomcat，请参阅以下参考资料

  • Apache Tomcat 的存储库访问
  • 阅读源代码发行版中的 BUILDING.txt

准备文档补丁

阅读源代码发行版中 BUILDING.txt 文件中关于构建文档的部分。通常，某个版本的 Tomcat 文档位于源代码的 webapps/docs/ 目录中，可以使用 ant build-docs 命令构建。

构建文档只需 Java 运行时和一份 Apache Ant 即可。编译 Tomcat 代码应该是不必要的。

通用参考

安全问题

安全相关的错误是特别受关注的问题。如果您有一个经过验证的安全错误需要报告，请不要将其发布到公共邮件列表，也不要提交错误报告。请参阅安全报告页面了解如何报告它们。