内容

目录

报告错误之前

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 对它们的响应。
  • Wiki – 搜索Wiki。那是每个人都可以贡献的非官方文档。
  • 常见问题解答 – 搜索Tomcat 常见问题解答，它是 Wiki 的一部分。

Apache Tomcat 讨论列表

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

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

另请参阅查找帮助页面。

已知问题

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

最新版本

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

查找已知问题

搜索错误数据库

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

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

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

以下是一些搜索技巧。

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

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

  2. 跨不同版本的 Tomcat 搜索。

    在错误数据库中，Tomcat 由多个“产品”表示。同一个问题应该只报告一次，但修复程序可以应用于不同的 Tomcat 版本。在此过程中，错误报告在不同的产品之间移动。最初针对 Tomcat 9 报告的错误将移至 Tomcat 8，以后可能移至 Tomcat 7。因此，一次搜索所有版本是有意义的。

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

    • Tomcat 11、Tomcat 10、Tomcat 9 和 Tomcat 8 – Tomcat 11.0.x、10.1.x、9.0.x 和 8.5.x
    • Tomcat Connectors – Tomcat 与其他 Web 服务器的集成
    • Tomcat Native – 基于 APR 的 Tomcat 原生 HTTP 和 AJP 连接器
    • Tomcat Modules – 其他 Tomcat 组件
    • Taglibs – Apache Taglibs 子项目

  3. 不仅搜索摘要字段，还搜索注释字段

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

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

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

  5. 一些错误不属于 Tomcat。

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

变更日志

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

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

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

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

    这些文件可在源代码中获得。

    它们采用 XML 格式，并附带样式表。因此，现代 Web 浏览器可以很好地显示它们。

    这些文件还可以在夜间文档构建中获得。有关详细信息，请参阅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 8.5 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 Modules 的一部分 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 8 – Tomcat 8.5.x
    • Tomcat Connectors – Tomcat 与其他 Web 服务器的集成。适用于 Apache HTTPD 和其他 Web 服务器的 mod_jk 模块。
    • Tomcat Native – 使用本机代码并与 Apache APR 和 OpenSSL 库链接的 Tomcat 的 HTTP 和 AJP 连接器
    • Tomcat Modules – 其他 Tomcat 组件，例如 jdbc-pool
    • Taglibs – Apache Taglibs 子项目

  • 版本 – Apache Tomcat 版本。

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

  • 组件 – 出现错误的组件。

    如果您不知道，请猜测。

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

  • 严重性 – 对于常规错误报告，这是 normal，对于增强请求，这是 enhancement。

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

  • 配置详细信息

    请在文本中提及这些内容

    • Java 版本 – 供应商和 Java 运行时环境版本，用于运行 Tomcat。
    • 如果 Tomcat 在 Apache HTTPD 或其他 Web 服务器后面使用 - 其版本以及如何配置它。
    • 正在使用的 Tomcat 连接器。Tomcat 中有几种连接器的实现。在 Tomcat 启动期间，日志中会显示正在使用哪一个。

  • 附件

    如果它们有助于追踪错误，请附加配置文件和 Tomcat 日志文件。

  • 重现器

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

如何提交补丁和增强请求

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

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

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

准备文档补丁

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

要构建文档，只需具备 Java 运行时和 Apache Ant 副本即可。编译 Tomcat 代码是不必要的。

通用参考

安全问题

与安全相关的错误尤为重要。如果您有经过验证的安全错误需要报告，请不要将其发布到公共电子邮件列表，也不要提交错误报告。请参阅 安全报告 页面了解如何报告这些错误。