背景
在平时的工作中，把常规工作进行文档整理非常重要，无论是平时工作处理或是工作交接，实时的维护文档资料可以提高工作效率。如果采用传统的TXT文档或者Word文档来记录的话修改查询都不太方便，采用在线Wiki可以更好的让大家实时地查看或者修改文档资料。
在开源Wiki系统中，XWiki是做的最好的产品之一。因为它提供的功能与Confluence的功能非常相似，不需要学习任何语法格式，可以直接在线像编辑Word一样编辑WIKI页面。通过配置插件和扩展，还可以实现包括Markdown语法之内的各种延展功能。
本文仅记录必须的安装步骤，更完整的信息请参考官方手册。
软件版本
CentOS 7
OpenJDK 1.8
MySQL 5.7
Tomcat 7.0.90
XWiki 10.10
准备工作
建立数据库和用户
生产环境下，我们需要把元数据保存在外部的RDBMS中。我们先在MySQL中建立用户和库。
PS：本文不涉及MySQL的安装，如果需要可以参考网上文章。
-- 建立对应的DB和User
drop user xwiki;
drop database if exists xwiki;
-- 注意修改用户名和密码
create database xwiki default charset utf8;
grant all privileges on xwiki.* to 'xwiki'@'%' identified by 'xwiki';
flush privileges;
安装OpenOffice
为了在XWiki中实现导入导出Office Word文档，需要单独安装OpenOffice，并在XWiki中进行调用。
PS: 使用yum安装的OO目录是在 /usr/lib64/libreoffice/ ，记录下来后面要配置
yum install -y libreoffice libreoffice-headless
建立OS用户
根据运维规范，我们需要使用一个独立的用户来运行XWiki。这里先建立用户和相关目录。
# 新建用户
useradd xwiki
passwd xwiki
# 建立用于保存XWiki附件的目录
mkdir /data/xwiki_data
chown -R xwiki.xwiki /data/xwiki_data
配置Tomcat
因为XWiki运行过程中对容器有一些特殊的配置要求，所以我们使用一个独立的Tomcat来承载XWiki服务。如果没有现成的，我们这里重新安装一个。
### 使用二进制安装
unzip apache-tomcat-7.0.90.zip -d /usr/local/
mv /usr/local/apache-tomcat-7.0.90/ /usr/local/xwiki_app/
chown -R xwiki.xwiki /usr/local/xwiki_app
### 设置字符集为utf8
vi /usr/local/xwiki_app/conf/server.xml
#
<Connector port="8080"
URIEncoding="UTF-8"
protocol="HTTP/1.1"
connectionTimeout="20000"
redirectPort="8443" />
### 必须修改默认JVM内存大小，否则启动XWiki后会报错。
### 因为我们使用的是二进制安装Tomcat，所以修改bin/catalina.sh 这个文件。
### 如果是yum安装的需要修改如/etc/tomcat7/tomcat7.conf 这个文件 (未验证yum安装这种方法)
vi /usr/local/xwiki_app/bin/catalina.sh
# 在开头增加这样一句
JAVA_OPTS="-Xmx2048m"
安装和启动前配置
下载安装
### 下载指定版本
wget http://nexus.xwiki.org/nexus/content/groups/public/org/xwiki/platform/xwiki-platform-distribution-war/10.10/xwiki-platform-distribution-war-10.10.war
### 安装到webapps目录下
unzip xwiki-platform-distribution-war-10.10.war -d /usr/local/xwiki_app/webapps/xwiki/
### 拷贝数据库驱动程序
wget http://repo1.maven.org/maven2/mysql/mysql-connector-java/5.1.26/mysql-connector-java-5.1.26.jar
cp mysql-connector-java-5.1.26.jar /usr/local/xwiki_app/webapps/xwiki/WEB-INF/lib/
配置数据库
默认情况下XWiki使用的是自带的HSQLDB，我们需要修改成使用外部MySQL。
### 数据库相关的配置在hibernate.cfg.xml
vi /usr/local/xwiki_app/webapps/xwiki/WEB-INF/hibernate.cfg.xml
# 首先要注释掉 Configuration for the default database 这部分，具体操作略
# 取消注释并修改 MySQL configuration 这部分。修改IP，Port，User，Passwd信息
<property name="connection.url">jdbc:mysql://x.x.x.x:3306/xwiki?useSSL=false</property>
<property name="connection.username">xwiki</property>
<property name="connection.password">xxxxxx</property>
配置OpenOffice
前面的步骤中，我们已经安装了OO，在XWiki中进行配置就可以在启动阶段自动连接OO服务器。
###
vi /usr/local/xwiki_app/webapps/xwiki/WEB-INF/xwiki.properties
# 修改下列信息
openoffice.autoStart=true
openoffice.homePath=/usr/lib64/libreoffice/
配置附件管理
默认情况下，XWiki使用数据库存储附件，所以对文件尺寸有一定限制。使用文件系统存储可以上传更大的附件，所以我们修改为文件系统。
### 启用文件系统保存附件
vi /usr/local/xwiki_app/webapps/xwiki/WEB-INF/xwiki.cfg
# 修改下列信息
xwiki.store.attachment.hint = file
xwiki.store.attachment.versioning.hint = file
xwiki.store.attachment.recyclebin.content.hint=file
xwiki.store.attachment.recyclebin.hint = file
xwiki.store.recyclebin.content.hint = file
### 指定存放附件文件的目录
vi /usr/local/xwiki_app/webapps/xwiki/WEB-INF/xwiki.properties
# 指定前面创建的目录
environment.permanentDirectory=/data/xwiki_data/
启动后初始化配置
首次启动XWiki的过程中，还需要完成一系列配置
### 首次安装Tomcat后需要赋予sh文件执行权限
find /usr/local/xwiki_app/ -name *.sh | xargs chmod +x
### 启动Tomcat
sh /usr/local/xwiki_app/bin/startup.sh
整个网页版的安装工作都在页面中完成，跟着向导一步一步操作。
配置管理员账号
安装常用插件
标准插件包的安装过程比较慢，耐心等待十几分钟到几十分钟。。。（国外网站，你懂滴）
PS：如果因为网络原因无法在线安装扩展和插件，可以使用离线安装的方式。
看到下面的界面，就说明安装成功了。
配置Markdown
默认不支持Markdown语法，所以我们需要安装额外的扩展来实现。
扩展安装成功后，还需要在编辑器里面启用语法支持。如下图的配置，我们只保留了Markdown语法。
配置自定义LOGO
公司内部使用，所以还是换上公司的LOGO比较规范。
配置中文界面
XWiki界面原生支持多语言，不过经过简单使用后发现，界面的中文化并不完全，显得有点LOW，还不如用英文。
日常维护
新建组和用户
建立组和用户很简单，新建的所有用户都会默认属于一个叫 XWikiAllGroup 的组。从权限管理的角度出发，我们需要把每个用户归属到不同的组当中。
设置目录权限
公司内部使用的XWiki，在权限管理上要满足下列要求
- Admin组成员拥有系统管理权限；
- 每个组有专属的文档目录（如运维组有自己专属的根目录，技术组同理）；
- 普通用户归属于各自的组；
- 注册用户和匿名用户拥有所有文档的读权限（特殊要求的除外）；
- 组成员对组目录下的文档都有编辑权限；
- 文档作者及指定管理人员有文档的删除权限；
举例，权限管理矩阵关系如下
| 组 \ 目录 | DIR-01 （G01根目录） | DIR-02（G02根目录） |
|---|---|---|
| Admin | full | full |
| Group-01 | read, write | read |
| Group-02 | read | read, write |
全局权限
为了实现后面基于目录的细粒度控制，首先在全局取消默认的用户权限。如下图
目录权限
以Dir01为例，选中指定目录后点选管理页面，如下图
为避免用户误操作修改根目录内容，先在页面级别取消组G01的编辑权限，如下图
然后给组G01赋予Dir01下级所有子目录的读写权限，如下图
备份恢复
具体的备份脚本本文暂不提供，仅说明安装前文进行安装之后需要进行备份的部分。完整的备份恢复请参考官方手册。
- MySQL中的xwiki库。这里保存的是所有基础数据。
- /data/xwiki_data/ 目录。这里保存的是所有附件文件，以及一些运行时数据。
- /usr/local/xwiki_app/webapps/xwiki/ 目录。这里是XWiki应用，因为修改了Tomcat的默认配置，所以建议把整个 /usr/local/xwiki_app/ 目录进行备份。
Troubleshooting
离线安装标准扩展包
此处记录必须操作，更多详细的原理和流程请参看官方手册。
### 下载标准扩展
wget http://nexus.xwiki.org/nexus/content/groups/public/org/xwiki/platform/xwiki-platform-distribution-flavor-xip/10.10/xwiki-platform-distribution-flavor-xip-10.10.xip
### 解压缩xip文件
unzip xwiki-platform-distribution-flavor-xip-10.10.xip -d /data/xwiki_data/extension/repository/
### 重启XWiki
sh /usr/local/xwiki_app/bin/shutdown.sh
sh /usr/local/xwiki_app/bin/startup.sh
Tomcat版本问题
在使用Tomcat 8.5.31测试过程中发现，后台会出现字符集问题。换用7.0.90版本后问题不再出现。
PS：在官方手册中这里有对于Tomcat版本的需求，但是并没有说8.5.31有问题。
警告 [xwiki/bin/download/Main/SolrSearch/dark-grey-disclosure-arrow-down.png] org.apache.catalina.connector.Response.setCharacterEncoding The encoding [] is not recognised by the JRE
java.lang.IllegalArgumentException: java.io.UnsupportedEncodingException: The character encoding [] is not supported
重启OpenOffice
在测试过程中发现，如果XWiki意外挂掉，在后续启动的过程中XWiki不能自动连接到OO服务器上。这个时候XWiki的基本功能都是正常的，但是不能导入导出Office文档。
如果在管理界面重启OO，会出现如下图的错误信息
查看系统日志catalina.out中会出现类似这样的错误信息
# 类似这样的错误信息
Caused by: java.lang.IllegalStateException: a process with acceptString 'socket,host=127.0.0.1,port=8100' is already running; pid 9099
at org.artofsolving.jodconverter.office.OfficeProcess.start(OfficeProcess.java:72)
这个时候的解决办法是，根据错误信息中的OO进程号（如上图中的pid），手工杀掉OO进程。
#### 查找确认一下端口号对应的进程
lsof -i:8100
#
COMMAND PID USER FD TYPE DEVICE SIZE/OFF NODE NAME
soffice.b 9099 xwiki 17u IPv4 2322562 0t0 TCP localhost:xprint-server (LISTEN)
### 手工杀掉OO进程
kill -9 9099
然后在管理页面重启OO即可恢复。
