Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

你可以以不同的方式使用Jetty,将Jetty嵌入到应用程序中,从不同的构建系统,不同的基于JVM的语言启动它,或者作为一个独立的分发包(distribution)。

这个指南覆盖了后者,一个独立的分发包适合于发布Web应用程序。

Panel

本页中的内容:

Table of Contents
maxLevel2
minLevel2

相关页面:

下载 Jetty

本页面给予如何下载 Jetty 的指南。

下载 Jetty 的分发包

独立的Jetty分发包可以从Eclipse基金会下载:https://www.eclipse.org/jetty/download.html

它有zip和gzip两种格式;下载适合于你的系统的格式。

注意,有许多扩展名为.sha或者.md5 的文件,这些是校验和文件。当你下载和解压缩二进制文件,它解压到一个目录名为 jetty-distribution-VERSION。将这个目录放到一个对你来说容易访问到的位置。这个文档中剩余的说明参考这个 JETTY_HOME 或者 $(jetty.home) 的位置。

Warning

在生产环境中只使用稳定版本是非常重要的。我们已经不在使用的版本,或者 M 版本(released as Milestones)RC 版本(Release Candidates)都不建议在生产环境上使用,因为这些版本中可能有隐藏的安全问题,没有完全实现或者不能完全工作的的特性等问题。


分发包的内容

分发包内容快速的总结如下。顶层目录包括:

内容

路径描述

license-eplv10-aslv20.html

Jetty 的许可证信息

README.txt

有用的开始使用信息

VERSION.txt

发布信息

bin/

帮助 Jetty 在 Unix 系统上运行的实用 Shell 脚本

demo-base/

Jetty 的基目录用于运行有示例 webapps 的 Jetty 服务器

etc/

Jetty XML 配置文件的目录

lib/

运行 Jetty 需要的所有的 jar

logs/

请求日志目录

modules/

模块定义目录

notice.html

许可证信息和例外

resources/

包含了classpath 的额外的资源,通过配置激活。

start.ini

包含了加入到有效的命令行的参数(modules,properties 和 xml配置文件)

start.jar

调用 Jetty 的 jar (同样可 运行 Jetty)

webapps/

此目录包含了运行于Jetty默认配置的 webapps



下载 Jetty-Home 分发包

Jetty-Home is an alternate version of the distribution that contains only the necessary items to host a Jetty distribution. It is intended for advanced users who are already familiar with Jetty and want to download a smaller distribution package. Jetty-Home can be downloaded from the Maven Central repository:

Jetty-Home http://central.maven.org/maven2/org/eclipse/jetty/jetty-home/

Like the main Jetty distribution, Jetty-Home is available in both zip and gzip formats; download the one most appropriate for your system. Notice that there are a number of other files with extensions of .sha or .md5 which are checksum files. When you download and unpack the binary, it is extracted into a directory called jetty-home-VERSION. Put this directory in a convenient location.

分发内容


A summary of the Jetty-Home’s distribution contents follows. The top-level directory contains:


内容

路径描述

license-eplv10-aslv20.html

Jetty 的许可证文件

VERSION.txt

发布信息

etc/

Jetty XML 配置文件的目录

lib/

运行 Jetty 需要的所有的 jar

modules/

模块定义目录

notice.html

许可证信息和例外

start.jar

调用 Jetty 的 jar (同样可 运行 Jetty)


运行 Jetty

在默认的端口8080上运行Jetty,运行下面的命令:

Code Block
languagetext
> cd $HOME/jetty-distribution-9
> java -jar start.jar


2017-05-16 14:01:46.007:INFO::main: Logging initialized @3247ms to org.eclipse.jetty.util.log.StdErrLog
2017-05-16 14:01:46.509:WARN:oejs.HomeBaseWarning:main: This instance of Jetty is not running from a separate {jetty.base} directory, this is not recommended.  See documentation at http://www.eclipse.org/jetty/documentation/current/startup.html
2017-05-16 14:01:46.586:INFO:oejs.Server:main: jetty-9.4.5.v20170502
2017-05-16 14:01:46.606:INFO:oejdp.ScanningAppProvider:main: Deployment monitor [file:///C:/Users/YuCheng/Dkits/jetty/webapps/] at interval 1
2017-05-16 14:01:46.764:INFO:oejs.AbstractConnector:main: Started [email protected]{HTTP/1.1,[http/1.1]}{0.0.0.0:8080}
2017-05-16 14:01:46.767:INFO:oejs.Server:main: Started @4007ms


你可以打开浏览器指向 http://localhost:8080 的服务器。然而没有 web 应用部署到 $JETTY_HOME 目录,你将会看到 404 的错误信息显示没有内容。

 

Note

HomeBase 警告错误 —— 这个并不建议你从 $JETTY_HOME 目录中运行 Jetty。可选的,请参考下面的 create a Jetty Base 目录。


Demo Base

从 Jetty 的标准分发包中,有一个 demo-base 目录,我们建议你从这个目录中运行 Jetty,而不是从 $JETTY_HOME 目录中运行:

Code Block
> cd $JETTY_HOME/demo-base/
> java -jar $JETTY_HOME/start.jar


C:\Users\YuCheng\Dkits\jetty\demo-base>java -jar ../start.jar
2017-05-16 14:25:12.953:INFO::main: Logging initialized @909ms to org.eclipse.jetty.util.log.StdErrLog
2017-05-16 14:25:13.380:WARN::main: demo test-realm is deployed. DO NOT USE IN PRODUCTION!
2017-05-16 14:25:13.395:INFO:oejs.Server:main: jetty-9.4.5.v20170502
2017-05-16 14:25:13.425:INFO:oejdp.ScanningAppProvider:main: Deployment monitor [file:///C:/Users/YuCheng/Dkits/jetty/demo-base/webapps/] at interval 1
2017-05-16 14:25:14.178:INFO:oeja.AnnotationConfiguration:main: Scanning elapsed time=130ms
2017-05-16 14:25:14.695:INFO:oejs.session:main: DefaultSessionIdManager workerName=node0
2017-05-16 14:25:14.697:INFO:oejs.session:main: No SessionScavenger set, using defaults
2017-05-16 14:25:14.701:INFO:oejs.session:main: Scavenging every 600000ms
2017-05-16 14:25:15.451:INFO:oejsh.ContextHandler:main: Started [email protected]{/proxy,file:///C:/Users/YuCheng/AppData/Local/Temp/jetty-0.0.0.0-8080-xref-proxy.war-_xref-proxy-any-6728519910878774473.dir/webapp/,AVAILABLE}{C:\Users\YuCheng\Dkits\jetty\demo-base\webapps\xref-proxy.war}
2017-05-16 14:25:15.514:INFO:oeja.AnnotationConfiguration:main: Scanning elapsed time=16ms
2017-05-16 14:25:15.552:INFO:oejsh.ContextHandler:main: Started [email protected]{/doc,file:///C:/Users/YuCheng/Dkits/jetty/demo-base/webapps/doc/,AVAILABLE}{C:\Users\YuCheng\Dkits\jetty\demo-base\webapps\doc}
2017-05-16 14:25:15.896:INFO:oeja.AnnotationConfiguration:main: Scanning elapsed time=55ms
2017-05-16 14:25:15.903:WARN::main: async-rest webapp is deployed. DO NOT USE IN PRODUCTION!
2017-05-16 14:25:15.963:INFO:oejsh.ContextHandler:main: Started [email protected]{/async-rest,[file:///C:/Users/YuCheng/AppData/Local/Temp/jetty-0.0.0.0-8080-async-rest.war-_async-rest-any-2908283761663011720.dir/webapp/, jar:file:///C:/Users/YuCheng/AppData/Local/Temp/jetty-0.0.0.0-8080-async-rest.war-_async-rest-any-2908283761663011720.dir/webapp/WEB-INF/lib/example-async-rest-jar-9.4.5.v20170502.jar!/META-INF/resources],AVAILABLE}{C:\Users\YuCheng\Dkits\jetty\demo-base\webapps\async-rest.war}
2017-05-16 14:25:16.635:INFO:oeja.AnnotationConfiguration:main: Scanning elapsed time=72ms
2017-05-16 14:25:16.641:WARN::main: test webapp is deployed. DO NOT USE IN PRODUCTION!
2017-05-16 14:25:17.025:INFO:oejsh.ManagedAttributeListener:main: update PushFilter null->[email protected] on [email protected]{/test,file:///C:/Users/YuCheng/AppData/Local/Temp/jetty-0.0.0.0-8080-test.war-_test-any-8348816481088530097.dir/webapp/,STARTING}{C:\Users\YuCheng\Dkits\jetty\demo-base\webapps/test.war}
2017-05-16 14:25:17.034:INFO:oejsh.ManagedAttributeListener:main: update QoSFilter null->[email protected] on [email protected]{/test,file:///C:/Users/YuCheng/AppData/Local/Temp/jetty-0.0.0.0-8080-test.war-_test-any-8348816481088530097.dir/webapp/,STARTING}{C:\Users\YuCheng\Dkits\jetty\demo-base\webapps/test.war}
2017-05-16 14:25:17.042:WARN:oeju.DeprecationWarning:main: Using @Deprecated Class org.eclipse.jetty.servlets.MultiPartFilter
2017-05-16 14:25:17.191:INFO:oejsh.ContextHandler:main: Started [email protected]{/test,file:///C:/Users/YuCheng/AppData/Local/Temp/jetty-0.0.0.0-8080-test.war-_test-any-8348816481088530097.dir/webapp/,AVAILABLE}{C:\Users\YuCheng\Dkits\jetty\demo-base\webapps/test.war}
2017-05-16 14:25:17.365:INFO:oeja.AnnotationConfiguration:main: Scanning elapsed time=35ms
2017-05-16 14:25:17.371:WARN::main: test-jaas webapp is deployed. DO NOT USE IN PRODUCTION!
2017-05-16 14:25:17.401:INFO:oejsh.ContextHandler:main: Started [email protected]{/test-jaas,file:///C:/Users/YuCheng/AppData/Local/Temp/jetty-0.0.0.0-8080-test-jaas.war-_test-jaas-any-2108594123932318298.dir/webapp/,AVAILABLE}{C:\Users\YuCheng\Dkits\jetty\demo-base\webapps/test-jaas.war}
2017-05-16 14:25:17.812:INFO:oeja.AnnotationConfiguration:main: Scanning elapsed time=16ms
2017-05-16 14:25:17.817:WARN::main: test-jndi webapp is deployed. DO NOT USE IN PRODUCTION!
2017-05-16 14:25:17.905:INFO:oejsh.ContextHandler:main: Started [email protected]{/test-jndi,file:///C:/Users/YuCheng/AppData/Local/Temp/jetty-0.0.0.0-8080-test-jndi.war-_test-jndi-any-6114169873044801101.dir/webapp/,AVAILABLE}{C:\Users\YuCheng\Dkits\jetty\demo-base\webapps/test-jndi.war}
2017-05-16 14:25:17.943:INFO:oeja.AnnotationConfiguration:main: Scanning elapsed time=18ms
2017-05-16 14:25:17.968:INFO:oejsh.ContextHandler:main: Started [email protected]{/,file:///C:/Users/YuCheng/Dkits/jetty/demo-base/webapps/ROOT/,AVAILABLE}{C:\Users\YuCheng\Dkits\jetty\demo-base\webapps\ROOT}
2017-05-16 14:25:17.992:INFO:oejsh.ContextHandler:main: Started [email protected]{/oldContextPath,null,AVAILABLE}
2017-05-16 14:25:18.405:INFO:oeja.AnnotationConfiguration:main: Scanning elapsed time=40ms
2017-05-16 14:25:18.410:WARN::main: test-spec webapp is deployed. DO NOT USE IN PRODUCTION!
2017-05-16 14:25:18.477:INFO:oejsh.ContextHandler:main: Started [email protected]{/test-spec,[file:///C:/Users/YuCheng/AppData/Local/Temp/jetty-0.0.0.0-8080-test-spec.war-_test-spec-any-2971344556627942752.dir/webapp/, jar:file:///C:/Users/YuCheng/AppData/Local/Temp/jetty-0.0.0.0-8080-test-spec.war-_test-spec-any-2971344556627942752.dir/webapp/WEB-INF/lib/test-web-fragment-9.4.5.v20170502.jar!/META-INF/resources],AVAILABLE}{C:\Users\YuCheng\Dkits\jetty\demo-base\webapps/test-spec.war}
2017-05-16 14:25:18.493:INFO:oejs.AbstractConnector:main: Started [email protected]{HTTP/1.1,[http/1.1]}{0.0.0.0:8080}
2017-05-16 14:25:18.538:INFO:oejus.SslContextFactory:main: [email protected](jetty,h=[jetty.eclipse.org],w=[]) for [email protected](file:///C:/Users/YuCheng/Dkits/jetty/demo-base/etc/keystore,file:///C:/Users/YuCheng/Dkits/jetty/demo-base/etc/keystore)
2017-05-16 14:25:18.543:INFO:oejus.SslContextFactory:main: [email protected](mykey,h=[],w=[]) for [email protected](file:///C:/Users/YuCheng/Dkits/jetty/demo-base/etc/keystore,file:///C:/Users/YuCheng/Dkits/jetty/demo-base/etc/keystore)
2017-05-16 14:25:18.628:INFO:oejs.AbstractConnector:main: Started [email protected]{SSL,[ssl, http/1.1]}{0.0.0.0:8443}
2017-05-16 14:25:18.631:INFO:oejs.Server:main: Started @6588ms
Image Removed


你可以打开浏览器指向 http://localhost:8080 的服务器,你可以通过这个页面看到欢迎界面和一些示例的 Web 应用程序。

Warning

示例的 web 应用程序是不安全的。不应该用作生产的 Web 应用程序。

你可以使用下面的命令来查看 demo-base Web 应用程序的配置情况。

Code Block
> cd $JETTY_HOME/demo-base/
> java -jar $JETTY_HOME/start.jar --list-modules
...
Code Block
> java -jar %JETTY_HOME/start.jar --list-config
...


`--list-modules` 命令,将会返回可用的和已经启用的模块的网站列表。
这个命令将会显示模块的路径,被实现的路径,依赖的模块和关联的 jar 文件。


The `--list-config` command displays a trove of  information about the server including the Java and Jetty environments, the configuration order, any JVM arguments or System Properties set, general server properties, a full listing of the Jetty server class path, and active Jetty XML files.命令将会显示 Java 和 Jetty 的服务器环境,配置列表和 JVM 参数或者系统属性,基本的服务器属性,完整的 Jetty class 路径,当前使用的 XML 文件。


Creating a new Jetty Base

The demo-base directory described above is an example of the jetty.base mechanism added in Jetty 9.1. A Jetty base directory allows the configuration and web applications of a server instance to be stored separately from the Jetty distribution, so that upgrades can be done with minimal disruption. Jetty’s default configuration is based on two properties:

jetty.homeThe property that defines the location of the jetty distribution, its libs, default modules and default XML files (typically start.jar, lib, etc)jetty.baseThe property that defines the location of a specific instance of a jetty server, its configuration, logs and web applications (typically start.ini, start.d, logs and webapps)


 Important

Your Jetty Home directory should be treated as a standard of truth and remain unmodified or changed. Changes or additions to your configuration should take place in the Jetty Base directory.

The jetty.home and jetty.base properties may be explicitly set on the command line, or they can be inferred from the environment if used with commands like:

> cd $JETTY_BASE
> java -jar $JETTY_HOME/start.jar

The following commands create a new base directory, enables both the HTTP connector and the web application deployer modules, and copies a demo webapp to be deployed:

> JETTY_BASE=/tmp/mybase
> mkdir $JETTY_BASE
> cd $JETTY_BASE
> java -jar $JETTY_HOME/start.jar

WARNING: Nothing to start, exiting ...

Usage: java -jar start.jar [options] [properties] [configs]
       java -jar start.jar --help  # for more information

> java -jar $JETTY_HOME/start.jar --create-startd
INFO : Base directory was modified
> java -jar $JETTY_HOME/start.jar --add-to-start=http,deploy

INFO: server          initialised (transitively) in ${jetty.base}/start.d/server.ini
INFO: http            initialised in ${jetty.base}/start.d/http.ini
INFO: security        initialised (transitively) in ${jetty.base}/start.d/security.ini
INFO: servlet         initialised (transitively) in ${jetty.base}/start.d/servlet.ini
INFO: webapp          initialised (transitively) in ${jetty.base}/start.d/webapp.ini
INFO: deploy          initialised in ${jetty.base}/start.d/deploy.ini
MKDIR: ${jetty.base}/webapps
INFO: Base directory was modified

> cp $JETTY_HOME/demo-base/webapps/async-rest.war webapps/ROOT.war
> java -jar $JETTY_HOME/start.jar

2015-06-04 11:10:16.286:INFO::main: Logging initialized @274ms
2015-06-04 11:10:16.440:INFO:oejs.Server:main: jetty-9.3.0.v20150601
2015-06-04 11:10:16.460:INFO:oejdp.ScanningAppProvider:main: Deployment monitor [file:///tmp/mybase/webapps/] at interval 1
2015-06-04 11:10:16.581:WARN::main: async-rest webapp is deployed. DO NOT USE IN PRODUCTION!
2015-06-04 11:10:16.589:INFO:oejw.StandardDescriptorProcessor:main: NO JSP Support for /, did not find org.eclipse.jetty.jsp.JettyJspServlet
2015-06-04 11:10:16.628:INFO:oejsh.ContextHandler:main: Started [email protected]{/,[file:///tmp/jetty-0.0.0.0-8080-ROOT.war-_-any-4510228025526425427.dir/webapp/, jar:file:///tmp/jetty-0.0.0.0-8080-ROOT.war-_-any-4510228025526425427.dir/webapp/WEB-INF/lib/example-async-rest-jar-9.3.0.v20150601.jar!/META-INF/resources],AVAILABLE}{/ROOT.war}
2015-06-04 11:10:16.645:INFO:oejs.ServerConnector:main: Started [email protected]{HTTP/1.1,[http/1.1]}{0.0.0.0:8080}
2015-06-04 11:10:16.646:INFO:oejs.Server:main: Started @634ms


Changing the Jetty Port

You can configure Jetty to run on a different port by setting the jetty.http.port Property on the command line:

> cd $JETTY_BASE
> java -jar $JETTY_HOME/start.jar jetty.http.port=8081
...

Alternatively, property values can be added to the effective command line built from either the start.ini file or start.d/http.ini files. By default, the Jetty distribution defines the jetty.http.port property in the start.d/http.ini file, which may be edited to set another value.

 Note

The configuration by properties works via the following chain:

  • The start.d/http.ini file is part of the effective command line and contains the --module=http argument which activates the http module.
  • The modules/http.mod file defines the http module which specifies the etc/jetty-http.xml configuration file and the template ini properties it uses.
  • The jetty.http.port property is used by the Property XML element in etc/jetty.http.xml to inject the ServerConnector instance with the port.


For more information see the Quickstart Configuration Guide and Configuring Connectors.


Adding SSL for HTTPS & HTTP2

To add HTTPS and HTTP2 connectors to a Jetty configuration, the modules can be activated by the following command:

> java -jar $JETTY_HOME/start.jar --add-to-start=https,http2
[...]

> java -jar $JETTY_HOME/start.jar
[...]

2015-06-04 13:52:01.933:INFO:oejs.ServerConnector:main: Started [email protected]{SSL,[ssl, alpn, h2, http/1.1]}{0.0.0.0:8443}
[...]

The --add-to-start command sets up the effective command line in the ini files to run an ssl connection that supports the HTTPS and HTTP2 protocols as follows:

  • creates start.d/ssl.ini that configures an SSL connector (eg port, keystore etc.) by adding etc/jetty-ssl.xml and etc/jetty-ssl-context.xml to the effective command line.
  • creates start.d/alpn.ini that configures protocol negotiation on the SSL connector by adding etc/jetty-alpn.xml to the effective command line.
  • creates start.d/https.ini that configures the HTTPS protocol on the SSL connector by adding etc/jetty-https.xml to the effective command line.
  • creates start.d/http2.ini that configures the HTTP/2 protocol on the SSL connector by adding etc/jetty-http2.xml to the effective command line.
  • checks for the existence of a etc/keystore file and if not present, downloads a demonstration keystore file.


Changing the Jetty HTTPS Port


You can configure the SSL connector to run on a different port by setting the jetty.ssl.port property on the command line:

> cd $JETTY_BASE
> java -jar $JETTY_HOME/start.jar jetty.ssl.port=8444

Alternatively, property values can be added to the effective command line built from the start.ini file or start.d/*.ini files, depending on your set up. Please see the section on Start.ini vs. Start.d for more information.

More start.jar options


The job of the start.jar is to interpret the command line, start.ini and start.d directory (and associated .ini files) to build a Java classpath and list of properties and configuration files to pass to the main class of the Jetty XML configuration mechanism. The start.jar mechanism has many options which are documented in the Chapter 9, Starting Jetty administration section and you can see them in summary by using the command:

> java -jar $JETTY_HOME/start.jar --help


Deploying Web Applications


Jetty Demonstration Web Applications


Jetty server instances that configure the deploy module will have a web application deployer that hot deploys files found in the webappsdirectory.  Standard WAR files and Jetty configuration files that are placed in the webapps directory are hot deployed to the server with the following conventions:

  • A directory called example/ is deployed as a standard web application if it contains a WEB-INF/ subdirectory, otherwise it is deployed as context of static content. The context path is /example (that is, http://localhost:8080/example/) unless the base name is ROOT (case insensitive), in which case the context path is /. If the directory name ends with ".d" it is ignored (but may be used by explicit configuration).
  • A file called example.war is deployed as a standard web application with the context path /example (that is,http://localhost:8080/example/). If the base name is ROOT (case insensitive), the context path is /. If example.war and example/ exist, only the WAR is deployed (which may use the directory as an unpack location).
  • An XML file like example.xml is deployed as a context whose configuration is defined by the XML. The configuration itself must set the context path. If example.xml and example.war exists, only the XML is deployed (which may use the WAR in its configuration).


If you have a standard web application, you can hot deploy it into Jetty by copying it into the webapps directory.

Jetty Demonstration Web Applications


The demo-base/webapps directory contains the following deployable and auxiliary files:

ROOT/A directory of static content that is deployed to the root context / due to it’s name. Contains the Jetty demo welcome page.test.dA directory containing additional configuration files used by test.xml to inject extra configuration into test.war.test.xmlA context configuration file that configures and deploys test.war. The additional configuration includes the context path as well as setting additional descriptors found in the test.d directory.test.warThe demonstration web application that is configured and deployed by test.xml.async-rest.warA web application demonstration of asynchronous REST to eBay, automatically deployed to /async-rest based on the file name.test-jaas.warA demonstration web application utilizing JAAS for authentication.test-jaas.xmlA context configuration file that configures test-jaas.war. Additional configuration includes setting up the LoginService for authentication and authorization.test-jndi.warA demonstration web application showing the use of JNDI.test-jndi.xmlA context configuration file that configures test-jndi.war. Additional configuration includes defining objects in the naming space that can be referenced from the webapp.test-spec.warA demonstration web application that shows the use of annotations, fragments, ServletContainerInitializers and other Servlet Specification 3.0/3.1 features.test-spec.xmlA context configuration file that configures test-spec.war. Additional configuration includes setting up some objects in the naming space that can be referenced by annotations.xref-proxy.warA demonstration web application that uses a transparent proxy to serve the Jetty source xref from the Eclipse Jetty website.example-moved.xmlA demonstration context configuration file that shows how to use the MovedContextHandler to redirect from one path to another.