阅读 1200

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

背景

在平时的工作中,把常规工作进行文档整理非常重要,无论是平时工作处理或是工作交接,实时的维护文档资料可以提高工作效率。如果采用传统的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
复制代码

整个网页版的安装工作都在页面中完成,跟着向导一步一步操作。

image-20181211164006079

配置管理员账号

image-20181211164110063

安装常用插件

标准插件包的安装过程比较慢,耐心等待十几分钟到几十分钟。。。(国外网站,你懂滴)

PS:如果因为网络原因无法在线安装扩展和插件,可以使用离线安装的方式。

image-20181211164253921

看到下面的界面,就说明安装成功了。

image-20181211174529633

配置Markdown

默认不支持Markdown语法,所以我们需要安装额外的扩展来实现。

image-20181211174819234

扩展安装成功后,还需要在编辑器里面启用语法支持。如下图的配置,我们只保留了Markdown语法。

image-20181211175537996

配置自定义LOGO

公司内部使用,所以还是换上公司的LOGO比较规范。

image-20181211180006950

配置中文界面

XWiki界面原生支持多语言,不过经过简单使用后发现,界面的中文化并不完全,显得有点LOW,还不如用英文。

image-20181211180520436

日常维护

新建组和用户

建立组和用户很简单,新建的所有用户都会默认属于一个叫 XWikiAllGroup 的组。从权限管理的角度出发,我们需要把每个用户归属到不同的组当中。

image-20181211181330814

设置目录权限

公司内部使用的XWiki,在权限管理上要满足下列要求

  • Admin组成员拥有系统管理权限;
  • 每个组有专属的文档目录(如运维组有自己专属的根目录,技术组同理);
  • 普通用户归属于各自的组;
  • 注册用户和匿名用户拥有所有文档的读权限(特殊要求的除外);
  • 组成员对组目录下的文档都有编辑权限;
  • 文档作者及指定管理人员有文档的删除权限;

举例,权限管理矩阵关系如下

组 \ 目录 DIR-01 (G01根目录) DIR-02(G02根目录)
Admin full full
Group-01 read, write read
Group-02 read read, write

全局权限

为了实现后面基于目录的细粒度控制,首先在全局取消默认的用户权限。如下图

image-20181212112420529

目录权限

以Dir01为例,选中指定目录后点选管理页面,如下图

image-20181212112608990

为避免用户误操作修改根目录内容,先在页面级别取消组G01的编辑权限,如下图

image-20181212112751251

然后给组G01赋予Dir01下级所有子目录的读写权限,如下图

image-20181212112911968

备份恢复

具体的备份脚本本文暂不提供,仅说明安装前文进行安装之后需要进行备份的部分。完整的备份恢复请参考官方手册

  • 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,会出现如下图的错误信息

image-20181213103756541

查看系统日志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即可恢复。

关注下面的标签,发现更多相似文章
评论