xwiki tomcat 安装官方文档-翻译

2019独角兽企业重金招聘Python工程师标准>>>

Tomcat Installation xwiki

Last modified by Vincent Massol on 2017/09/06

Installation Steps

Tomcat项目已经改变了处理RequestDispatcher的方式，这导致了XWiki在某些版本的Tomcat中的回归。因此，你应该不使用下面的Tomcat版本：

• > = 9.0.0.M5和9.0.0分支的9.0.0.M10（固定在9.0.0.M10）
• > = 8.5.1和8.5.5（8.5.5）
• > = 8.0.34，8.0.x分支为8.0.37（固定在8.0.37）
• > 7.0.7分，7.0.71分（7.0.71分）
•  
• 下载并安装Tomcat。有很多方法来安装Tomcat，有关更多信息，请参阅Tomcat网站。我们来调用它安装的目录TOMCAT_HOME。
• 确保给Java足够的内存，因为默认情况下，Tomcat没有为XWiki配置足够的内存。
• 编辑conf / server.xml文件以设置UTF-8编码：

• <Connector port="8080" ... URIEncoding="UTF-8"/>

   

• 提取XWiki实现WAR到指定的目录XWiki实现在TOMCAT_HOME/webapps /下
• 打开TOMCAT_HOME/webapps/WEB-INF/xwiki.properties文件并配置永久目录
• 启动Tomcat
• 当Tomcat通过访问 http://localhost:8080//xwiki/bin/view/Main/
• 注意 - 如果您有最大缓存大小的问题 - 在 $CATALINA_BASE/conf/context.xml 中，在</Context>之前添加以下内容：

  <Resources cachingAllowed="true" cacheMaxSize="100000" />

   

激活无头模式

如果您在没有安装X11库的Linux服务器上运行XWiki，则必须为Tomcat安装启用无头模式。有时这在Windows平台上也是必需的。典型的例外是：

• 异常：无法初始化类sun.awt.X11.XToolkit
• java.lang.InternalError: 无法使用'localhost：10.0'作为DISPLAY变量的值连接到X11窗口服务器
• 在Linux上创建一个文件/TOMCAT_HOME/bin/setenv.sh并插入以下代码：

  #!/bin/sh

  export JAVA_OPTS="${JAVA_OPTS} -Djava.awt.headless=true"
• 在Windows上创建一个文件/TOMCAT_HOME/bin/setenv.bat并插入以下代码：

  set JAVA_OPTS=%JAVA_OPTS% -Djava.awt.headless=true

• 当作为Windows服务运行时，setenv.bat不工作。有关类似设置，请参阅注册表HKEY_LOCAL_MACHINE\SOFTWARE\Apache Software Foundation\Procrun 2.0\FOOBAR\Parameters\Java。

 

可选配置

• 编辑你的conf/server.xml以启用gzip压: 

• <Connector port="8080" ... compression="on" compressionMinSize="2048" compressableMimeType="text/html,text/xml,text/css,text/javascript,application/x-javascript"/>

   

• 如果要修改Tomcat运行的端口，请编辑TOMCAT_HOME /conf/server.xml/。搜索8080（有时候是8180，如果你在Linux下），并替换你想要使用的端口值。
• 可以将Tomcat Java Server设置为UNIX守护程序 - JSVC。只需按照这些说明。使Tomcat成为守护进程的唯一原因是使其在第80个端口可运行，可以在第80个端口上使用NginX作为代理，然后将其转发到第8080个端口。

 

策略配置

对于那些激活Tomcat的安全管理器的人员，请从Tomcat安装中将这部分代码添加到conf/catalina.policy文件的末尾。您可以调整适用于您的服务器和不同数据库的OpenOffice / LibreOffice的可用安装代码：

grant codeBase "file:${catalina.base}/webapps/xwiki/WEB-INF/lib/-" {

  // for mySQL connection

  permission java.net.SocketPermission "127.0.0.1:3306", "connect,resolve";

 

  // XWiki must have access to all properties in read/write

  permission java.util.PropertyPermission "*", "read, write";

 

  // Generic detected permissions

  permission java.lang.reflect.ReflectPermission "suppressAccessChecks";

  permission java.lang.RuntimePermission "createClassLoader";

  permission java.lang.RuntimePermission "setContextClassLoader";

  permission java.lang.RuntimePermission "accessClassInPackage.org.apache.catalina.loader";

  permission java.lang.RuntimePermission "accessDeclaredMembers";

  permission java.lang.RuntimePermission "getenv.ProgramFiles";

  permission java.lang.RuntimePermission "getenv.APPDATA";

  permission java.lang.RuntimePermission "accessClassInPackage.sun.reflect";

  permission java.lang.RuntimePermission "getClassLoader";

  permission java.lang.RuntimePermission "accessClassInPackage.org.apache.catalina.connector";

  permission java.lang.RuntimePermission "accessClassInPackage.org.apache.tomcat.util.threads";

  permission java.lang.RuntimePermission "reflectionFactoryAccess";

  permission java.lang.RuntimePermission "accessClassInPackage.com.sun.jmx.interceptor";

  permission java.lang.RuntimePermission "accessClassInPackage.com.sun.jmx.mbeanserver";

  permission java.lang.RuntimePermission "modifyThread";

  permission java.lang.RuntimePermission "getProtectionDomain";

 

  // JAXB permissions

  permission javax.xml.bind.JAXBPermission "setDatatypeConverter";

 

  // Serialization related permissions

  permission java.io.SerializablePermission "allowSerializationReflection";

  permission java.io.SerializablePermission "creator";

  permission java.io.SerializablePermission "enableSubclassImplementation";

 

  // Internal resources access permissions

  permission java.io.FilePermission "synonyms.txt", "read";

  permission java.io.FilePermission "lang/synonyms_en.txt", "read";

  permission java.io.FilePermission "quartz.properties", "read";

  permission java.io.FilePermission "/templates/-", "read";

  permission java.io.FilePermission "/skins/-", "read";

  permission java.io.FilePermission "/resources/-", "read";

 

  // MBean related permissions

  permission javax.management.MBeanServerPermission "createMBeanServer";

  permission javax.management.MBeanPermission "*", "registerMBean";

  permission javax.management.MBeanPermission "*", "unregisterMBean";

  permission javax.management.MBeanTrustPermission "register";

  permission javax.management.MBeanPermission "-#-[-]", "queryNames";

  permission javax.management.MBeanServerPermission "findMBeanServer";

 

  // LibreOffice/OpenOffice related permissions

  permission java.io.FilePermission "/opt/openoffice.org3/program/soffice.bin", "read";

  permission java.io.FilePermission "/opt/libreoffice/program/soffice.bin", "read";

  permission java.io.FilePermission "/usr/lib/openoffice/program/soffice.bin", "read";

  permission java.io.FilePermission "/usr/lib/libreoffice/program/soffice.bin", "read";

 

  // Allow file storage directory reading - for directory and everything underneath

  // This is dependent on the setting of environment.permanentDirectory in xwiki.properties

  permission java.io.FilePermission "${catalina.base}${file.separator}xwikidata${file.separator}", "read,write,delete";

  permission java.io.FilePermission "${catalina.base}${file.separator}xwikidata${file.separator}-", "read,write,delete";

 

  // Allow file storage directory reading - temporary directory and everything underneath

  // This is dependent on the setting of environment.temporaryDirectory in xwiki.properties.

  permission java.io.FilePermission "${catalina.base}${file.separator}temp${file.separator}", "read,write,delete";

  permission java.io.FilePermission "${catalina.base}${file.separator}temp${file.separator}-", "read,write,delete";

};

请注意，此策略配置文件已在CentOS 5.9上使用Sun JDK 1.7.0u21在安装了XWiki 5.0.1的Tomcat 7.0.40上进行了测试。

 

使用Nginx作为Tomcat的反向代理（http / https）

由于各种原因，允许用户直接连接到tomcat是不理想的。反向代理Web服务器的流行选择是Nginx。 这些说明将逐步介绍nginx的基本部署，作为Tomcat XWiki应用程序的反向代理。

经过典型的XWiki安装后，XWiki将在http://localhost:8080/xwiki上运行。最终我们希望通过http://mydomain.com在标准http（80）或https（443）端口上访问XWiki 。要完成这个不安全的http流量，以下基本配置文件让我们开始。

http (unsecure)

• 创建此文件/etc/nginx/conf.d/tomcat.conf
• 把下面的代码放在里面

• server {

      listen       80;

      server_name  mydomain.com;

   

     # Normally root should not be accessed, however, root should not serve files that might compromise the security of your server.

      root /var/www/html;

   

      location / {

         # All "root" requests will have /xwiki appended AND redirected to mydomain.com

          rewrite ^ $scheme://$server_name/xwiki$request_uri? permanent;

      }

   

     location ^~ /xwiki {

        # If path starts with /xwiki - then redirect to backend: XWiki application in Tomcat

        # Read more about proxy_pass: http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_pass

         proxy_pass http://localhost:8080;

         proxy_set_header        X-Real-IP $remote_addr;

         proxy_set_header        X-Forwarded-For $proxy_add_x_forwarded_for;

         proxy_set_header        Host $http_host;

         proxy_set_header        X-Forwarded-Proto $scheme;

      }

  }
• 重新启动nginx

现在所有的http://mydomain.com/*请求都将导致XWiki应用程序。请注意，这些设置是基本的。有关更灵活的解决方案，请参考Nginx文档。 . 

 

https（安全）

有关如何创建nginx的安全配置的许多指南。开始：

• 在nginx上强大的SSL安全性
• 如何在Ubuntu 16.04上安装Nginx与LetsEncrypt

以下配置假定您正在使用LetsEncrypt，并且您的XWiki托管在http://localhost：8080/上。此配置将重定向所有不安全的请求到https：//，并为安全的nginx + tomcat设置设置正确的代理标头。

首先，您需要将以下配置添加到tomcat的server.xml（位于Ubuntu 16.04 上的/etc/tomcat8/server.xml）。第一行应该已经在文件中，我将其包含在内，以便您可以搜索（该行位于Ubuntu 16.04 tomcat8包中的第108行）。这将帮助tomcat找到你的代理头。

<Engine name="Catalina" defaultHost="localhost">

  <Valve className="org.apache.catalina.valves.RemoteIpValve"

    internalProxies="127\.0\.[0-1]\.1"

    remoteIpHeader="x-forwarded-for"

    requestAttributesEnabled="true"

    protocolHeader="x-forwarded-proto"

    protocolHeaderHttpsValue="https"/>

接下来，将以下nginx配置文件添加到您的nginx配置文件夹，将wiki.yourdomain.com替换为您的实际域信息：

server {

    listen      80;

    server_name wiki.yourdomain.com;

 

    location ~ /.well-known {

        allow all;

    }

 

   rewrite     ^   https://$server_name$request_uri? permanent;

 

   access_log /var/log/nginx-xwiki/access.log;

   error_log /var/log/nginx-xwiki/error.log;

 

}

 

server {

    listen      443;

    server_name wiki.yourdomain.com;

 

    root /var/www/html;

 

    ssl on;

    ssl_certificate /etc/letsencrypt/live/wiki.yourdomain.com/fullchain.pem;

    ssl_certificate_key /etc/letsencrypt/live/wiki.yourdomain.com/privkey.pem;

 

    access_log /var/log/nginx-xwiki/access_ssl.log;

    error_log /var/log/nginx-xwiki/error_ssl.log;

 

    location / {

        proxy_set_header Host $http_host;

        proxy_set_header X-Real-IP $remote_addr;

        proxy_set_header X-Forward-For $proxy_add_x_forwarded_for;

        proxy_set_header X-Forwarded-Proto $scheme;

        proxy_set_header X-Scheme $scheme;

        proxy_redirect off;

        if (!-f $request_filename) {

            proxy_pass http://127.0.0.1:8080;

            break;

        }

   }

 

   location ~ /.well-known {

        allow all;

    }

}

有关此配置的更多背景信息，请参阅此机票的讨论：XWIKI-13963。

 

配置tomcat为https

虽然不允许用户直接连接到tomcat，但由于各种原因，可能需要配置tomcat以通过https连接提供页面。

• 如果使用HTTPS访问XWiki，则必须进行若干修改以确保正确的功能。由于URL是从相对路径生成的（/xwiki/bin/show/Space/Page），Tomcat必须知道要使用哪个协议，否则JSON重定向请求失败（附件上传，扩展更新等）
• 将连接器（在server.xml中）修改为<Connector port =“8080”... secure =“true”scheme =“https”/>
• 修改主机（在server.xml中）并添加Remote Ip Valve <Valve className =“org.apache.catalina.valves.RemoteIpValve”remoteIpHeader =“x-forwarding-for”protocolHeader =“x-forwarding-proto”/>（only如果使用另一个服务器用于HTTPS）

 

如果使用其他服务器作为HTTPS代理（如Nginx或Apache httpd），则必须设置X-Forwarded-For和X-Forwarded-Proto头文件！

 

故障排除

内存不足错误

当您使用默认设置在Tomcat中运行XWiki时，由于默认的Tomcat内存设置不够，您可能会收到Out Of Memory错误（java.lang.OutOfMemoryError：Java堆空间或java.lang.OutOfMemoryError：PermGen空间）对于XWiki内存要求。 您需要为JVM分配更多的内存。 

配置Tomcat内存的一个简单的解决方案是在[TOMCAT_HOME]/bin/（其中[TOMCAT_HOME]是您安装Tomcat的位置）中创建一个setenv.sh文件（或Windows上的setenv.bat），并在此文件中添加以下内容（根据XWiki内存要求调整内存值）。例如：

CATALINA_OPTS="-Xmx1024m -XX:MaxPermSize=192m"

在大部分Linux上，这也可以在实现在/etc/tomcatX/tomcatX.conf或etc/conf.d/tomcatX.conf（其中X是Tomcat版本安装）。

在Windows上，如果您正在运行Tomcat作为服务，则定义CATALINA_OPTS将无济于事。在Tomcat安装的bin文件夹中提供了一个实用程序（例如对于Tomcat 5.x在Windows上，它被称为tomcat5w.exe）。它是一个GUI工具，可用于设置各种选项，包括堆大小。

 

Java安全管理器

默认情况下，Tomcat配置为启用Java安全管理器。有关详细信息，请参阅示例策略文件。

如果要关闭Tomcat的Java Security Manager，请编辑Tomcat启动脚本。您可能还需要检查/etc/init.d/tomcat文件或/etc/default/tomcat5.5。您应该看到以下代码：

# Use the Java security manager? (yes/no)

TOMCAT5_SECURITY=

将其设置为否，以关闭安全管理器

 

允许页面名称中的“/”

当URL中有一个％2F时，Tomcat完全变得怪异，它不是XWiki中可以更改的东西。有关详细信息，请参阅本说明。

您可以通过启用以下方式配置Tomcat：

org.apache.tomcat.util.buf.UDecoder.ALLOW_ENCODED_SLASH

请注意，如果您使用Apache，您还需要配置Apache以允许编码/和\。

NotSerializableException

如果您得到以下内容：:

SEVERE: IOException while loading persisted sessions: java.io.WriteAbortedException: writing aborted; java.io.NotSerializableException: org.xwiki.model.internal.reference.LocalStringEntityReferenceSerializer

java.io.WriteAbortedException: writing aborted; java.io.NotSerializableException: org.xwiki.model.internal.reference.LocalStringEntityReferenceSerializer

 at java.io.ObjectInputStream.readObject0(Unknown Source)

 at java.io.ObjectInputStream.defaultReadFields(Unknown Source)

这意味着在启动时，Tomcat会尝试加载已保存的会话，而不能这样做。在这种情况下，它会失败，因为一些非可序列化的对象被放在Servlet会话中。要解决此问题，您可以告诉Tomcat不保存会话

SEVERE: Error listenerStart

如果您在Tomcat日志中收到此错误，那么您需要启用更细粒度的日志记录配置，以查看问题。对于Tomcat 6.x / 7.x，这涉及将以下内容复制到WEB-INF/classes/logging.properties文件中：WEB-INF/classes/logging.properties file:

org.apache.catalina.core.ContainerBase.[Catalina].level = INFO

org.apache.catalina.core.ContainerBase.[Catalina].handlers = java.util.logging.ConsoleHandler

 

 

转载于:https://my.oschina.net/ch66880/blog/1539823