使用 Jetty

下载 Jetty

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

下载 Jetty 的分发包

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

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

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

分发包的内容

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

内容

下载 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:

内容

运行 Jetty

在默认的端口8080上运行Jetty，运行下面的命令：

> 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 ServerConnector@6093dd95{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 的错误信息显示没有内容。

Demo Base

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

> 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 o.e.j.w.WebAppContext@60285225{/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 o.e.j.w.WebAppContext@1c7696c6{/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 o.e.j.w.WebAppContext@5149d738{/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->org.eclipse.jetty.servlets.PushCacheFilter@503f91c3 on o.e.j.w.WebAppContext@52f27fbd{/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->org.eclipse.jetty.servlets.QoSFilter@730d2164 on o.e.j.w.WebAppContext@52f27fbd{/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 o.e.j.w.WebAppContext@52f27fbd{/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 o.e.j.w.WebAppContext@3f1d2e23{/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 o.e.j.w.WebAppContext@93081b6{/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 o.e.j.w.WebAppContext@6e01f9b0{/,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 o.e.j.s.h.MovedContextHandler@4066c471{/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 o.e.j.w.WebAppContext@1ae8bcbc{/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 ServerConnector@36a5cabc{HTTP/1.1,[http/1.1]}{0.0.0.0:8080}
2017-05-16 14:25:18.538:INFO:oejus.SslContextFactory:main: x509=X509@42530531(jetty,h=[jetty.eclipse.org],w=[]) for SslContextFactory@5a3bc7ed(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: x509=X509@181e731e(mykey,h=[],w=[]) for SslContextFactory@5a3bc7ed(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 ServerConnector@17d88132{SSL,[ssl, http/1.1]}{0.0.0.0:8443}
2017-05-16 14:25:18.631:INFO:oejs.Server:main: Started @6588ms

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

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

> cd $JETTY_HOME/demo-base/
> java -jar $JETTY_HOME/start.jar --list-modules
...

> java -jar %JETTY_HOME/start.jar --list-config
...

`--list-modules` 命令，将会返回可用的和已经启用的模块的网站列表。

这个命令将会显示模块的路径，被实现的路径，依赖的模块和关联的 jar 文件。

`--list-config` 命令将会显示 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 o.e.j.w.WebAppContext@1a407d53{/,[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 ServerConnector@3abbfa04{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 ServerConnector@6f1fba17{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.