XWiki是一个使用Java编写的开源的Wiki引擎，是一个功能强大，类似confluence的知识管理系统，XWiki自称其为“第二代Wiki”。本文主要介绍为什么使用Wiki和XWiki的安装过程

什么是Wiki?

Wiki是在万维网上开放，且可供多人协同创作的超文本系统，由沃德·坎宁安于1995年首先开发。沃德·坎宁安将wiki定义为一种允许一群用户用简单的描述来创建和连接一组网页的社会计算系统。如维基百科就是典型的Wiki应用

作为信息共享和协作工具，Wiki也在互联网企业内部被广泛使用，如商业的企业协作软件Confluence，也有许多开源免费的Wiki软件

为什么需要搭建Wiki系统

Wiki作为团队信息和知识共享和协作工具，可以极大的提高团队协作效率和信息透明度，减少因信息同步不及时、信息分散等原因带来的团队运转效率低下问题，越是需要密切协作的团队，Wiki系统越重要

一个团队可以比作一个网络，每个人可以看作是网络中的一个节点，每个人既需要输出信息给其它人，也需要从其它人输入信息。输出的信息需要快速、准确地传达给其它人

Wiki就是有效的信息管理工具，Wiki的作用包括：

• 信息共享，将个人的知识输出到平台，使其转化为团队的知识。新入职或者新加入项目的人想要了解情况，直接查阅文档，不需要找相关人员了解，因为这样既浪费沟通时间，又可能出现信息传达错误、遗漏等问题
• 信息保存，在项目中，往往有许多约定的规则通常是由少数当事人协商的，如果没有告知其他人，或者即使告知了，其他人也很可能遗忘和忽略，因此记录在Wiki中可以让所有人避免这些坑
• 信息整合，平时分散的信息散落在不同的平台、不同的人、不同的文件中，为了获取资料，经常需要在自己电脑中、聊天群、在线文档查找，或者问别人等，没有做到统一管理，导致有需要的时候获取困难，也不知道是否存在相关的文档。因此将全部文档整合在一个平台并分类管理就显得非常重要了
• 信息同步，文档作者如果更新了文档，会自动通知关注了该文档的人
• 信息修复，由于所有人都可以编辑，所以错误的信息会被立即修复，从而减少信息错误造成的成本

哪些信息需要上传到Wiki？

几乎所有和团队或项目相关的信息都可以上传到Wiki，包括但不限于

• 技术教程
• 技术规范（编码规范、前后端规范、Java规范、Javascript规范等）
• 技术调研（调研过程、技术选型方案对比）
• 后台配置方法、注意事项
• 约定俗成的规则，如早期遗留的，不论是合理的或不合理的，都全部文档化
• 版本计划（如有需求，链接到mockplus）
• 技术方案 对接方案 流程图 （如有接口，链接到YAPI）
• 产品调研 产品方案 效果分析
• 运营策略 运营方案 效果分析
• 研发流程规范
• 发布流程清单 （发布上线整个过程中需要做哪些工作，全部列出，在执行时参照清单，避免遗漏）
• 排期计划
• 测试报告
• 测试方法
• 测试技术
• 会议纪要
• 团建记录（经费、方案等）
• 常见问题FAQ

不应上传的内容

• 重要的账号密码（如生产环境密码）

需要养成的习惯

• 如果自己有问题，先查找wiki，当文档中没有需要的或者没有文档时，再找相关人员
• 如果其它人有问题来找自己，先检查自己是否有输出文档，文档是否完善
• 一旦发现文档有错误或遗漏，应及时修改完善（所有人都可编辑）

Wiki系统的比较

作为企业内部使用的Wiki系统，需要满足以下几点：

• 支持私有化部署，为保证数据安全，应该将全部数据保存在本地
• 支持全文本搜索，可高效获取信息
• 支持多人协作，人人可编辑、评论，如果只有文章作者能编辑，会打消其他人的创作和完善的积极性
• 支持版本控制，可以对一个页面的不同历史版本进行比较，可以回退到任意历史版本
• 目录结构清晰，支持对信息进行统一管理和分类，方便查找
• 良好的使用体验，支持WYSIWYG所见即所得编辑器，方便不熟悉Markdown语法的人员编辑文档

以下为个人对目前比较流行的Wiki系统进行初步体验后的简单对比，仅供参考。一个比较专业的wiki比较网站是WikiMatrix，该网站支持以表格的形式对Wiki系统的各项功能进行详细比较

综合比较，xwiki的功能符合需要，没有明显的缺点，作为团队协作工具是满足需求的

什么是XWiki

XWiki是开源的Wiki管理系统，具有和知名的协作软件confluence类似的功能，如内容管理（浏览、编辑、预览、保存）、支持附件、版本控制、全文本搜索、权限管理、WYSIWYG所见即所得编辑器、丰富的扩展（应用、宏、皮肤、插件、主题等）

安装XWiki

XWiki是基于Java开发的，运行在Servlet容器中，如Tomcat、Jetty等，同时还需要关系型数据库存储内容，如MySQL、PostgreSQL等，但是需要正确的配置

前提条件

• Java版本，最新版本XWiki，需要安装Java 8 或者Java 11，详见Java Support Strategy

  XWiki Versions	Java Version supported
  XWiki < 6.0	Java 6
  XWiki < 8.1	Java 7
  XWiki < 11.3	Java 8
  XWiki >= 11.3	Java 8 & Java 11

• Servlet Container版本，Servlet 3.1 (XWiki < 12 需要Servlet 3.0.1)详见Servlet Container Support Strategy

  Servlet Container	Versions	Reason for supporting it	Installation Instructions
  Tomcat	Latest + LTS version strategy. Currently tested: 9-jdk11 (latest), 8.5-jdk8 (lts), 9-jdk8 (special).	Biggest market share of Servlet Containers and most used by XWiki users	Instructions
  Jetty (XWiki Standalone packaging)	Latest of 9.x.	Provided as a packaging in the XWiki Standalone distribution	Instructions
  Jetty (Official packaging)	Latest + LTS version strategy. Currently tested: 9-jre11 (latest), 9.3-jre8 (lts).	Second most used Container by XWiki users	Instructions

• 数据库和 JDBC 4.2驱动（XWiki版本 < 11.5 需要JDBC 4），支持的数据库详见Database Support Strategy

  Database	Versions	Reason for supporting it
  HyperSQL	Latest	Currently Hypersonic DB is used in embedded mode in our standalone distribution.
  MariaDB	Latest + LTS version strategy. Currently tested: .	MySQL has been replaced by MariaDB in all Debian and most of the Linux distributions, and is thus going to be used more and more (especially when building an open source stack)
  MySQL	Latest + LTS version strategy. Currently tested: .	MySQL is one of the most used open source database.
  PostgreSQL	Latest + LTS version strategy. Currently tested: .	PostgreSQL is also one of the most used database (especially when building an open source stack)
  Oracle	Latest + LTS version strategy. Currently tested: .	Being an enterprise wiki, XWiki also supports Oracle to be “business”-friendly

• 支持的浏览器，除了老版本的IE和冷门浏览器，几乎都支持，详见Browser Support Strategy

• 内存，XWiki需要配置合适的内存，内存不是设置的越大越好，官方推荐设置如下

  • For Java 8 (i.e. XWiki >= 8.1). Notice that there’s no permgen anymore in Java 8:

    • Small and medium installs: A minimum of 1024MB (-Xmx1024m)
    • Large installs: 2048MB or beyond (-Xmx2048m).

  • For Java 7 (i.e. XWiki < 8.1)

    • Small installs: A minimum of 512MB of heap memory and 196MB of permGen (-Xmx512m -XX:MaxPermSize=196m)
    • Medium installs: 1024MB for the heap and 196MB of permGen (-Xmx1024m -XX:MaxPermSize=196m)
    • Large installs: 2048MB (or beyond) for the heap and 196MB of permGen (-Xmx2048m -XX:MaxPermSize=196m).

  • 官方也给出了xwiki.org网站的设置作参考

    CATALINA_OPTS="-server -Xms800m -Xmx1600m -Dfile.encoding=utf-8 -Djava.awt.headless=true -XX:+UseParallelGC -XX:MaxGCPauseMillis=100"
    

安装方法

官方推荐适合在生产使用的安装方法有两种：

• 使用.deb包安装，安装简单，通过包管理器会自动安装所有XWiki所需要的组件，适用于基于Debian的Linux版本
• 使用war包安装，需要手动配置服务器容器、数据库

方式一：使用.deb包安装

• 首先配置包管理

  wget -q "https://maven.xwiki.org/public.gpg" -O- | sudo apt-key add -
  sudo wget "https://maven.xwiki.org/stable/xwiki-stable.list" -P /etc/apt/sources.list.d/
  

• 更新包数据

  sudo apt-get update
  

• 接下来就可以搜索xwiki相关的包

  apt-cache search xwiki
  

• 根据选择，包管理会安装所有必需的依赖项（应用程序服务器，数据库，Java运行时），如使用MySQL，输入以下命令安装，会自动安装tomca9和mysql在安装过程中，dbconfig负责数据库的配置，它会询问数据库密码

  sudo apt-get install xwiki-tomcat9-mysql
  

• 内存设置，默认的Tomcat内存设置对XWiki来说太低了，编辑/etc/default/tomcat9文件，添加合适的内存设置

  JAVA_OPTS="-Djava.awt.headless=true -Xmx1024m"
  

• 安装完成后，在浏览器访问XWiki打开安装向导：http://localhost:8080/xwiki

方式二：使用War包安装

• 下载war包，地址：https://www.xwiki.org/xwiki/bin/view/Download/

• 下载离线安装标准Flavor扩展包XIP Package，扩展包可以看作是基本功能插件合集，在xwiki首次启动后的安装向导界面可以选择离线安装xwiki xip扩展包。如选择在线安装，速度很可能非常慢。xwiki离线扩展包下载地址：https://www.xwiki.org/xwiki/bin/view/Download/

• 安装JAVA并设置环境变量

• 安装Tomcat

  • 创建tomcat用户组

    sudo groupadd tomcat
    

  • 创建tomcat用户，设置禁止登录，设置用户组为tomcat，设置tomcat Home目录为/opt/tomcat

    sudo useradd -s /bin/false -g tomcat -d /opt/tomcat tomcat
    

  • 下载或者上传tomcat tar包到服务器

    curl -O paste_the_tomcat_download_link_here
    

  • 创建/opt/tomcat目录，并解压tar包到该目录，参数--strip-components=1表示去掉解压后的第一层（即最上层）目录

    sudo mkdir /opt/tomcat
    sudo tar xzvf apache-tomcat-*tar.gz -C /opt/tomcat --strip-components=1
    

  • 将tomcat安装目录和子目录授予tomcat用户组

    sudo chgrp -R tomcat /opt/tomcat
    

  • 接下来，授予tomcat组对conf目录及其所有内容的读取权限，以及conf目录本身的执行权限

    sudo chmod -R g+r conf
    sudo chmod g+x conf
    

  • 设置以下目录所有者为tomcat

    sudo chown -R tomcat webapps/ work/ temp/ logs/
    

  • 创建systemd服务文件

    sudo vim /etc/systmd/system/tomcat.service
    

  • 将以下内容添加到tomcat.service，修改JAVA_HOME路径为实际路径

    [Unit]
    Description=Apache Tomcat Web Application Container
    After=network.target
        
    [Service]
    Type=forking
        
    Environment=JAVA_HOME=/usr/lib/jvm/java-11.0.8-openjdk-amd64
    Environment=CATALINA_PID=/opt/tomcat/temp/tomcat.pid
    Environment=CATALINA_HOME=/opt/tomcat
    Environment=CATALINA_BASE=/opt/tomcat
    Environment='CATALINA_OPTS=-Xms512M -Xmx1024M -server -XX:+UseParallelGC'
    Environment='JAVA_OPTS=-Djava.awt.headless=true -Djava.security.egd=file:/dev/./urandom'
        
    ExecStart=/opt/tomcat/bin/startup.sh
    ExecStop=/opt/tomcat/bin/shutdown.sh
        
    User=tomcat
    Group=tomcat
    UMask=0007
    RestartSec=10
    Restart=always
        
    [Install]
    WantedBy=multi-user.target
    

  • 重新加载systemd daemon

    sudo systemctl daemon-reload
    

  • 启动tomcat

    sudo systemctl start tomcat
    

  • 检查tomcat是否运行正常

    sudo systemctl status tomcat
    

  • 访问http://server_domain_or_IP:8080，就可以看到tomcat页面了，如果不能访问，可能是配置了防火墙，则需要使用以下命令开启8080端口

    sudo ufw allow 8080
    

  • 设置tomcat开机启动

    sudo systemctl enable tomcat
    

  • 默认是不能访问tomcat web管理界面的，需要进行配置

    • 添加tomcat web管理账号，可以在tomcat-users标签之间定义一个用户，编辑/opt/tomcat/conf/tomcat-users.xml添加以下内容

      <tomcat-users . . .>
          <user username="admin" password="password" roles="manager-gui,admin-gui"/>
      </tomcat-users>
      

    • tomcat web管理界面中，默认情况下，较新版本的Tomcat将访问Manager和Host Manager限制为来自服务器本身的连接，编辑以下文件注释IP限制

      • 对于Server Status和Manager App，编辑下列文件注释IP限制

        sudo vim /opt/tomcat/webapps/manager/META-INF/context.xml
        

      • 对于Host Manager，编辑下列文件注释IP限制

        sudo vim /opt/tomcat/webapps/host-manager/META-INF/context.xml
        

      • 注释IP限制，注释掉IP地址限制以允许从任何地方进行连接

        <Context antiResourceLocking="false" privileged="true" >
          <!--<Valve className="org.apache.catalina.valves.RemoteAddrValve"
                 allow="127\.\d+\.\d+\.\d+|::1|0:0:0:0:0:0:0:1" />-->
        </Context>
        

    • 重启tomcat，即可从tomcat web管理界面访问Server Status、Manager App 和 Host Manager

      sudo systemctl restart tomcat
      

  • 将xwiki war包解压到tomcat安装目录的webapps/xwiki目录下，并修改所有者权限为tomcat用户和tomcat用户组

    sudo unzip xwiki-platform-distribution-war-12.8.war -d /opt/tomcat/webapps/xwiki
    sudo chown -R tomcat:tomcat /opt/tomcat/webapps/xwiki
    

  • （可选）修改配置xwiki的永久目录，这是xwiki保存数据的地方。编辑设置文件xwiki.properties搜索environment.permanentDirectory字段进行设置xwiki永久目录为/home/username/xwiki/data，注意该目录也需要tomcat服务器具有读写权限

    sudo vim /opt/tomcat/webapps/xwiki/WEB-INF/xwiki.properties
    sudo chown tomcat:tomcat -R /home/username/xwiki
    

• 安装MySQL数据库

  • 下载MySQL：https://dev.mysql.com/downloads/mysql/，并上传到服务器

  • 创建mysql用户组和用户

    sudo groupadd mysql
    sudo useradd -r -g mysql -s /bin/false mysql
    

  • 重命名压缩包，然后解压

    mv mysql-8.0.21-linux-glibc2.17-x86_64-minimal.tar.xz mysql.tar.xz
    tar xvf mysql.tar.xz
    

  • 配置环境变量

    export PATH=$PATH:/path-to-mysql/bin
    

  • 创建mysql-files文件夹并授权

    cd mysql
    mkdir mysql-files
    sudo chown mysql:mysql mysql-files
    sudo chmod 750 mysql-files
    

  • 初始化，mysql服务器会生成一个随机root密码，将其标记为已过期，并输出到日志中

    mysqld --initialize --user=mysql
    

  • 正常启动mysql服务器，使用之前分配的随机root密码登录（手动输入容易出错，建议直接shift+insert粘贴），如果输入mysql -u root -p时提示mysql: error while loading shared libraries: libncurses.so.5: cannot open shared object file: No such file or directory，则安装依赖sudo apt install libncurses5

    #启动mysql服务
    mysqld &
    #连接mysql服务
    mysql -u root -p
    Enter password: (在这里粘贴随机root密码)
    

  • 分配新的root密码，不要遗漏末尾分号

    mysql> ALTER USER 'root'@'localhost' IDENTIFIED BY '12345678';
    

  • 设置Mysql服务开机自动启动

    • 创建mysqld.service文件

      cd /usr/lib/systemd/system
      sudo touch mysqld.service
      sudo chmod 644 mysqld.service
      

    • 在mysql.service文件中添加配置信息

      [Unit]
      Description=MySQL Server
      Documentation=man:mysqld(8)
      Documentation=http://dev.mysql.com/doc/refman/en/using-systemd.html
      After=network.target
      After=syslog.target
            
      [Install]
      WantedBy=multi-user.target
            
      [Service]
      User=mysql
      Group=mysql
            
      # Have mysqld write its state to the systemd notify socket
      Type=notify
            
      # Disable service start and stop timeout logic of systemd for mysqld service.
      TimeoutSec=0
            
      # Start main service
      ExecStart=/home/username/mysql/bin/mysqld --defaults-file=/etc/my.cnf $MYSQLD_OPTS 
            
      # Use this to switch malloc implementation
      EnvironmentFile=-/etc/sysconfig/mysql
            
      # Sets open_files_limit
      LimitNOFILE = 10000
            
      Restart=on-failure
            
      RestartPreventExitStatus=1
            
      # Set environment variable MYSQLD_PARENT_PID. This is required for restart.
      Environment=MYSQLD_PARENT_PID=1
            
      PrivateTmp=false
      

    • 设置mysqld开机启动

      systemctl enable mysqld.service
      

    • 启动mysql

      systemctl start mysqld
      

      如果提示找不到配置文件，则添加/etc/my.cnf文件：

      [client]
      port=3306
      socket=/tmp/mysql.sock
            
      [mysqld]
      port=3306
      socket=/tmp/mysql.sock
      key_buffer_size=16M
      max_allowed_packet=128M
            
      [mysqldump]
      quick
      

  • 创建xwiki数据库，在MySQL 8 中，由于InnoDB是默认的MySQL存储引擎，因此不需要进行额外的设置

    mysql -u root -p -e "create database xwiki default character set utf8mb4 collate utf8mb4_bin"
    

  • 创建MySQL数据库的xwiki用户，密码设置为xwiki

    mysql -u root -p -e "CREATE USER 'xwiki'@'localhost' IDENTIFIED BY 'xwiki'";
    

  • 给MySQL数据库的xwiki用户授权

    mysql -u root -p -e "grant all privileges on *.* to xwiki@localhost"
    

  • 下载MySQL JDBC Driver，如mysql-connector-java-8.0.21.jar，下载地址：https://dev.mysql.com/downloads/connector/j/，将jar复制到/opt/tomcat/webapps/xwiki/WEB-INF/lib目录，并修改权限

    sudo cp /home/username/mysql-connector-java-8.0.21.jar  /opt/tomcat/webapps/xwiki/WEB-INF/lib
    sudo chown tomcat:tomcat /opt/tomcat/webapps/xwiki/WEB-INF/lib/mysql-connector-java-8.0.21.jar
    

  • 编辑xwiki的数据库配置文件WEB-INF/hibernate.cfg.xml，注释默认的数据库配置部分，如下所示

    <!-- Configuration for the default database.
             Comment out this section and uncomment other sections below if you want to use another database.
             Note that the database tables will be created automatically if they don't already exist.
        
             If you want the main wiki database to be different than "xwiki" (or the default schema for schema based engines)
             you will also have to set the property xwiki.db in xwiki.cfg file
        -->
        <!--
        <property name="hibernate.connection.url">jdbc:hsqldb:file:${environment.permanentDirectory}/database/xwiki_db;shutdown=true</property>
        <property name="hibernate.connection.username">sa</property>
        <property name="hibernate.connection.password"></property>
        <property name="hibernate.connection.driver_class">org.hsqldb.jdbcDriver</property>
        
        <property name="hibernate.connection.charSet">UTF-8</property>
        <property name="hibernate.connection.useUnicode">true</property>
        <property name="hibernate.connection.characterEncoding">utf8</property>
        
        <mapping resource="xwiki.hbm.xml"/>
        <mapping resource="feeds.hbm.xml"/>
        <mapping resource="instance.hbm.xml"/>
        <mapping resource="notification-filter-preferences.hbm.xml"/>
        <mapping resource="mailsender.hbm.xml"/>
        -->
        
    

  • 取消注释Mysql数据库配置部分，激活配置，并在这里配置相应的值，如下所示

    <!-- MySQL configuration.
             Uncomment if you want to use MySQL and comment out other database configurations.
             Notes:
               - if you want the main wiki database to be different than "xwiki"
                 you will also have to set the property xwiki.db in xwiki.cfg file
               - if you're using a MySQL 8+ JDBC driver, you don't need the "hibernate.connection.driver_class" which will
                 generate a warning since it's not needed as the driver is registered automatically
        -->
        <property name="hibernate.connection.url">jdbc:mysql://localhost/xwiki?useSSL=false&amp;allowPublicKeyRetrieval=true</property>
        <property name="hibernate.connection.username">xwiki</property>
        <property name="hibernate.connection.password">xwiki</property>
                <property name="hibernate.connection.driver_class">com.mysql.cj.jdbc.Driver</property>
        <property name="hibernate.dialect">org.hibernate.dialect.MySQL5InnoDBDialect</property>
        <property name="hibernate.dbcp.poolPreparedStatements">true</property>
        <property name="hibernate.dbcp.maxOpenPreparedStatements">20</property>
        
        <property name="hibernate.connection.charSet">UTF-8</property>
        <property name="hibernate.connection.useUnicode">true</property>
        <property name="hibernate.connection.characterEncoding">utf8</property>
        
        <mapping resource="xwiki.hbm.xml"/>
        <mapping resource="feeds.hbm.xml"/>
        <mapping resource="instance.hbm.xml"/>
        <mapping resource="notification-filter-preferences.hbm.xml"/>
        <mapping resource="mailsender.hbm.xml"/>
        
    

  • 按照hibernate.cfg.xml中MySQL配置部分的注释说明(if you’re using a MySQL 8+ JDBC driver, you don’t need the “hibernate.connection.driver_class” which will generate a warning since it’s not needed as the driver is registered automatically)，如果使用MySQL 8和以上版本的 JDBC driver，就不需要配置hibernate.connection.driver_class属性。但是实际测试发现，如果注释了下面的配置后启动XWiki，会报错SQL连接异常！

    <!--<property name="hibernate.connection.driver_class">com.mysql.cj.jdbc.Driver</property>-->
    

• 解压xwiki 扩展文件xip文件到xwiki的永久目录xwiki/data/extension/repository，修改所有者和所属用户组为tomcat

  sudo unzip xwiki-platform-distribution-flavor-xip-12.8.xip -d xwiki/data/extension/repository
    
  sudo chown tomcat:tomcat xwiki
  

• 重启tomcat

  sudo systemctl restart tomcat
  

• 访问xwiki：ip:8080/xwiki，首次访问会自动进入安装向导

遇到的问题

安装完成后，首次访问xwiki会进入安装向导，如果没有成功进入安装向导，可以查看tomcat日志

sudo tail -111f /opt/tomcat/logs/catalina.out

出现下列错误

java.sql.SQLException: Cannot create PoolableConnectionFactory (Public Key Retrieval is not allowed)

查找资料发现，MySQL的官方文档中有对这个问题的说明：

如果用户使用了 sha256_password 认证，密码在传输过程中必须使用 TLS 协议保护，但是如果 RSA 公钥不可用，可以使用服务器提供的公钥；可以在连接中通过 ServerRSAPublicKeyFile 指定服务器的 RSA 公钥，或者AllowPublicKeyRetrieval=True参数以允许客户端从服务器获取公钥；但是需要注意的是 AllowPublicKeyRetrieval=True可能会导致恶意的代理通过中间人攻击(MITM)获取到明文密码，所以默认是关闭的，必须显式开启。

有两种解决方式

• 第一种方式可以用mysql_native_password插件鉴权,不要用sha256_password方式鉴权，编辑my.cnf文件（此方法测试不成功）

  sudo vim /etc/my.cnf
  

  添加以下配置到[mysqld]部分，然后重启mysqld

  default-authentication-plugin=mysql_native_password
  

• 第二种方式是连接MySQL的url中添加参数allowPublicKeyRetrieval=true，注意XML中&符号用&表示。编辑xwiki的数据库配置文件WEB-INF/hibernate.cfg.xml，修改MySQL配置部分的hibernate.connection.url设置如下

  <property name="hibernate.connection.url">jdbc:mysql://localhost/xwiki?useSSL=false&amp;allowPublicKeyRetrieval=true</property>
  

参考

Installation

Installation using Debian (.DEB) packages

Installing XWiki .war package manually

How To Install Apache Tomcat 9 on Ubuntu 18.04

Chapter 3 Installing MySQL on Unix/Linux Using Generic Binaries

XWiki_安装和基础配置企业级知识库