介绍

OTOBO is an open source ticket request system with many features to manage customer telephone calls and emails. It is distributed under the GNU General Public License (GPL) and is tested on various Linux platforms.

关于本手册

本手册供系统管理员使用，本章介绍了OTOBO软件的安装和更新。

没有用于安装和更新的图形用户界面。系统管理员必须按照以下章节中描述的步骤进行。

所有控制台命令看起来都是这种格式``username> command-to-execute``。其中用户名表示操作系统的用户帐户，需要使用该帐户来执行命令。如果命令以``root>''开头，则必须以具有root权限的用户身份执行命令。如果命令以“ʻotobo>”开头，则必须以为OTOBO创建的用户身份执行。

Warning

复制命令并将其粘贴到外壳程序时，请勿选择``username>`` 。否则，您将得到一个错误警示。

We assume that OTOBO will be installed to the directory /opt/otobo. If you want to install OTOBO to a different location, then you have to change the path in the commands or create a symbolic link to this directory.

root> ln -s /path/to/otobo /opt/otobo

软硬件要求

The OTOBO web application can be installed on Linux and other Unix derivates, e.g. OpenBSD or FreeBSD. Running OTOBO on Microsoft Windows is not supported.

The web application uses a relational database as backend. So, to run OTOBO, you'll need to run at least a web server and a database server. The web server and the database server may be installed either on the same or on different hosts.

Alternatively, OTOBO can also run under Docker. When running under Docker, the web and the database server are already included in the setup. Support for deployment with Kubernetes is under development.

The OTOBO web application requires Perl along with additional Perl modules from CPAN. The modules can be installed either with a Perl package manager or via the package manager of your operating system (rpm, yast, apt-get). There is a console command for checking the module dependencies:

otobo> /opt/otobo/bin/otobo.CheckModules.pl --inst

If some packages are missing, you can get an install command for your operating system by running the script with the --list option.

otobo> /opt/otobo/bin/otobo.CheckModules.pl --list | more

将以root权限执行列出的命令。

模块检查脚本的输出，会显示已安装的软件包和版本号。缺失的模块会带着注释。

Required packages:
  o Archive::Tar.....................ok (v2.32)
  o Archive::Zip.....................ok (v1.67)
  o Const::Fast......................ok (v0.014)
  o Date::Format.....................ok (v2.24)
  o DateTime.........................ok (v1.51)
    o DateTime::TimeZone.............ok (v2.38)
  o Convert::BinHex..................ok (v1.125)
  o DBI..............................ok (v1.643)
  o Digest::SHA......................ok (v6.02)
  o File::chmod......................ok (v0.42)
  o List::AllUtils...................ok (v0.15)
  o LWP::UserAgent...................ok (v6.26)
  o Moo..............................ok (v2.003006)
  o namespace::autoclean.............ok (v0.29)
  o Net::DNS.........................ok (v1.22)
  o Net::SMTP::SSL...................ok (v1.04)
  o Path::Class......................ok (v0.37)
  o Sub::Exporter....................ok (v0.987)
  o Template::Toolkit................ok (undef)
  o Template::Stash::XS..............ok (undef)
  o Text::CSV........................ok (v1.95)
  o Text::Trim.......................ok (v1.04)
  o Time::HiRes......................ok (v1.9760)
  o Try::Tiny........................ok (v0.30)
  o URI..............................ok (v1.71)
  o XML::LibXML......................ok (v2.0207)
  o YAML::XS.........................ok (v0.81)
  o Unicode::Collate.................ok (v1.27)
  o CGI::PSGI........................ok (v0.15)
  o DBIx::Connector..................ok (v0.56)
  o Path::Class......................ok (v0.37)
  o Plack............................ok (v1.0047)
  o Plack::Middleware::ForceEnv......ok (v0.02)
  o Plack::Middleware::Header........ok (v0.04)
  o Plack::Middleware::Refresh.......ok (undef)
  o Plack::Middleware::ReverseProxy..ok (v0.16)
  o Plack::Middleware::Rewrite.......ok (v2.101)
  o SOAP::Transport::HTTP::Plack.....ok (v0.03)

Recommended features for setups using apache:
  o ModPerl::Util....................ok (v2.000011)

Database support (installing one is required):
  o DBD::mysql.......................ok (v4.050)

Various features for additional functionality:
  o Encode::HanExtra.................ok (v0.23)
  o Net::LDAP........................ok (v0.66)
  o Crypt::Eksblowfish::Bcrypt.......ok (v0.009)
  o XML::LibXSLT.....................ok (v1.99)
  o XML::Parser......................ok (v2.46)

Features enabling communication with a mail-server:
  o Net::SMTP........................ok (v3.11)
  o Mail::IMAPClient.................ok (v3.42)
  o Authen::SASL.....................ok (v2.16)
  o Authen::NTLM.....................ok (v1.09)
  o IO::Socket::SSL..................ok (v2.067)

Optional features which can increase performance:
  o JSON::XS.........................ok (v4.02)
  o Text::CSV_XS.....................ok (v1.41)

Required packages if you want to use PSGI/Plack (experimental and advanced):
  o Gazelle..........................ok (v0.49)
  o Linux::Inotify2..................ok (v2.2)
  o Plack::App::File.................ok (undef)

硬件要求

硬件要求在很大程度上取决于OTOBO的使用情况，因为 OTOBO可以用于每月处理几张工单，或着每天处理数百张工单。而其存储要求还取决于工单的数量和附件的尺寸。

我们建议使用一台计算机进行测试并**至少**具备以下条件：

小CPU

4 GB 内存

10 GB 存储空间

我们建议为生产环境准备一台计算机，并**至少**具备以下条件：

3 GHz Xeon 或兼容的 CPU

8 GB 内存 （建议 16 GB）

40 GB 存储空间

Note

硬件要求取决于OTOBO的使用，请在部署任何硬件之前，联系你的OTOBO顾问。

软件要求

Perl

Perl 5.24.0 或更高版本

Perl packages listed by /opt/otobo/bin/otobo.CheckModules.pl --list console command

Web Server

Apache HTTP Server Version 2.4

数据库

MySQL 5.6或更高版本

MariaDB

PostgreSQL 9.2 或更高版本

Oracle 10g 或更高版本

可选

Elasticsearch 7.x（实时预览的快速搜索功能）

Redis (fast caching)

nginx or any other web server that can be used as a reverse proxy (SSL support and load distribution)

网络浏览器

苹果 Safari

谷歌 Chrome

微软 Internet Explorer 11

微软 Edge

Mozilla Firefox

其他任何支持JavaScript的网络浏览器

OTOBO安装

本章讲述了OTOBO构架核心部分的安装和基本设置。

按照本章的详细步骤在你的服务器上安装OTOBO，而后你就可以从网络接口登陆并管理系统了。

Note

As of OTOBO version 10.0.7, we recommend Docker and Docker Compose for the OTOBO installation. By using the provided Docker images, all recommended dependencies (such as Elasticsearch, Redis Cache, etc.) are installed and configured automatically. Updates are thus greatly simplified and the performance has been improved. You can find the instructions for Docker-based installation at https://doc.otobo.org/manual/installation/stable/en/content/installation-docker.html .

准备工作：SELinux完成安装和激活后，关闭它

Note

如果你的系统是SELinux，需要禁用它，否则OTOBO不能正确运行。

如果你不能确认SELinux是否已经在你的系统上安装激活，可以试一下命令``sestatus`` 和 getenforce 。

命令``sestatus`` 可以返回SELinux的状态和应用的策略。SELinux的状态如果返回“被激活”，就说明SELinux已经激活；当前模式如果返回“强制模式”就说明SELinux是运行在强制模式下；配置文件策略如果返回“目标”，就说明SELinux的目标策略已经激活。

这里是如何在RHEL/CentOS/Fedora中禁用SELinux。

在``/etc/selinux/config``文件中设置 SELINUX=disabled：

# This file controls the state of SELinux on the system.
# SELINUX= can take one of these three values:
#       enforcing - SELinux security policy is enforced.
#       permissive - SELinux prints warnings instead of enforcing.
#       disabled - No SELinux policy is loaded.
SELINUX=disabled
# SELINUXTYPE= can take one of these two values:
#       targeted - Targeted processes are protected,
#       mls - Multi Level Security protection.
SELINUXTYPE=targeted

重启你的系统，重启后，确认一下``getenforce`` 命令返回的是不是“禁用”：

root> getenforce
Disabled

步骤1：打开OTOBO封装和安装

从https://ftp.otobo.org/pub/otobo/下载最新的OTOBO版本软件，打开封装文档（例如使用``tar``命令），并存到目录``/root/otobo-update``：

root> mkdir /opt/otobo-install                                          # Create a temporary install directory
root> cd /opt/otobo-install                                             # Change into the update directory
root> wget https://ftp.otobo.org/pub/otobo/otobo-latest-10.0.tar.gz     # Download he latest OTOBO 10 release
root> tar -xzf otobo-latest-10.0.tar.gz                                 # Unzip OTOBO
root> cp -r otobo-10.x.x /opt/otobo                                     # Copy the new otobo directory to /opt/otobo

步骤2：安装其他程序和Perl模块

用下面的脚本可以对所有已经安装的，以及必须要的CPAN模块和其他外部环境，有一个通盘的了解。

root> perl /opt/otobo/bin/otobo.CheckModules.pl -list
Checking for Perl Modules:
  o Archive::Tar.....................ok (v1.90)
  o Archive::Zip.....................ok (v1.37)
  o Crypt::Eksblowfish::Bcrypt.......ok (v0.009)
...

Note

请注意OTOBO需要一个安装了所有*核心*模块的可以运行的Perl，例如``version``模块。脚本不会对这些模块进行核查，所以针对一些像RHEL的系统，他们不会去默认安装Perl核心模块，你可能需要自己去安装这些 ``perl-core``软件包。

你可以用CPAN或者Linux的软件包管理系统，安装必须的以及可选的软件模块。

执行这个命令就可以取得一个安装命令，去安装那些缺失的外部环境软件：

root> /opt/otobo/bin/otobo.CheckModules.pl -inst

Note

有一些可选的或者可替换的模块，在大多数定制化的OTOBO版本中，也可以安装上。调用CheckModules.pl 毫无疑问可以列出所有功能。

步骤3：创建OTOBO用户

在用户自己的组中，创建一个专用的OTOBO用户：

root> useradd -r -U -d /opt/otobo -c 'OTOBO user' otobo -s /bin/bash

把这个用户加入网站服务器组（如果网站服务器不是作为OTOBO用户运行）：

root> usermod -G www-data otobo
(SUSE=www, Red Hat/CentOS/Fedora=apache, Debian/Ubuntu=www-data)

步骤4：激活默认的配置文件

有一个OTOBO配置文件是捆绑在``$OTOBO_HOME/Kernel/Config.pm.dist``中的，你需要拷贝这个文件并去掉``.dist`` ，以便激活它。

root> cp /opt/otobo/Kernel/Config.pm.dist /opt/otobo/Kernel/Config.pm

步骤5：配置Apache网站服务器

首先，你需要安装Apache2网站服务器和mod_perl：通常你会通过系统的软件管理系统来进行。在下面你看会看到在当前流行的Linux版本上，安装Apache需要的一些命令。

# RHEL / CentOS:
root> yum install httpd mod_perl

# SuSE:
root> zypper install apache2-mod_perl

# Debian/Ubuntu:
root> apt-get install apache2 libapache2-mod-perl2

A critical setting of the Apache web server is the choice of the multi-processing module. For running OTOBO, the recommended choice is the module mpm_prefork. Like other Apache modules the multi-processing module can be managed with the tools a2dismod and a2enmod.

root> # check which MPM is active
root> apache2ctl -M | grep mpm_

All is fine whem mpm_prefork already is enabled.

Disable mpm_event when it is currently active.

root> a2dismod mpm_event

Disable mpm_worker in case that MPM is enabled.

root> a2dismod mpm_worker

Finally activate mpm_prefork.

root> a2enmod mpm_prefork

OTOBO requires a few more Apache modules to be active for optimal operation. Again, on most platforms you can make sure they are active via the tool a2enmod.

root> a2enmod perl
root> a2enmod deflate
root> a2enmod filter
root> a2enmod headers

Note

在一些平台上，不是所有的Apache模块都存在，这样在安装的时候就会显示错误信息。这种情况不用着急，继续完成安装，大部分情况下，没有成功安装的模块往往都不需要。

大部分的Apache安装都包括一个``conf.d``目录，在Linux系统中你可以在``/etc/apache`` 或者 ``/etc/apache2``下面找到这个目录。

在没有SSL支持的情况下配置Apache

Copy the template file /opt/otobo/scripts/apache2-httpd.include.conf to the apache sites-available directory. In most cases no further editing of the template is required. Then enable the new configuration.

# Debian/Ubuntu:
root> cp /opt/otobo/scripts/apache2-httpd.include.conf /etc/apache2/sites-available/zzz_otobo.conf
root> a2ensite zzz_otobo.conf
root> systemctl restart apache2

在 有 SSL 支持的情况下配置Apache

Copy the template files /opt/otobo/scripts/apache2-httpd-vhost-80.include.conf and /opt/otobo/scripts/apache2-httpd-vhost-443.include.conf to the apache sites-available directory.

# Debian/Ubuntu:
root> cp /opt/otobo/scripts/apache2-httpd-vhost-80.include.conf /etc/apache2/sites-available/zzz_otobo-80.conf
root> cp /opt/otobo/scripts/apache2-httpd-vhost-443.include.conf /etc/apache2/sites-available/zzz_otobo-443.conf

请编辑文件并加入一些必须的信息，例如SSL认证存储路径。之后，激活OTOBO Apache配置：

root> a2ensite zzz_otobo-80.conf
root> a2ensite zzz_otobo-443.conf

现在你可以重启你的网站服务器，载入新的配置设定了。在多数系统中，你可以用下面的命令来实现：

root> systemctl restart apache2

步骤6：设置文件许可

请执行下面的命令设置OTOBO的文件和目录许可。系统会尝试为你检测正确的用户和组。

root> /opt/otobo/bin/otobo.SetPermissions.pl

步骤7：建立数据库

首先，你需要安装数据库软件。建议使用你的Linux系统自带的MySQL或者MariaDB，也可以使用PostgreSQL或者Oracle。

你可以通过系统的软件管理进行安装，下面是在常用的Linux版本上安装MySQL数据库的一些命令。

# RHEL / CentOS:
root> yum install mysql-server

# SuSE:
root> zypper install mysql-community-server

# Debian/Ubuntu:
root> apt-get install mysql-server

安装了MySQL服务器后，需要进行配置。

在MySQL 5.7及更高版本中，激活了一个新的认证模块，这样就不能用OTOBO的网络安装软件建立数据库了。这种情况下， 请登陆进入MySQL控制台，设置不同的认证模块和用户``root`` 的密码：

root> mysql -u root
root> ALTER USER 'root'@'localhost' IDENTIFIED WITH mysql_native_password BY 'NewRootPassword';

对MariaDBM 10.1以上版本，用下面的命令：

root> mysql -u root
root> update mysql.user set authentication_string=password('NewRootPassword') plugin='mysql_native_password' where user='root';

如果此命令不起作用，请尝试以下命令：

root> mysql -u root
root> UPDATE mysql.user SET password = PASSWORD('NewRootPassword') WHERE user = 'root';
root> UPDATE mysql.user SET authentication_string = '' WHERE user = 'root';
root> UPDATE mysql.user SET plugin = 'mysql_native_password' WHERE user = 'root';

在OTOBO完成安装后，在需要时也可以更改认证模块。

Note

下面的配置设定是MySQL安装的最低要求。请将下面的脚本加入``[mysqld]`` 下面的MySQL服务器配置文件``/etc/my.cnf``，/etc/mysql/my.cnf 或者 /etc/mysql/mysql.conf.d/mysqld.cnf：

max_allowed_packet   = 64M
innodb_log_file_size = 256M

对MySQL 8.0之前的版本，查询缓存尺寸需要设定：

query_cache_size     = 32M

下面的配置设定是MySQL安装的最低要求。请将下面的脚本加入``[mysqld]`` 下面的MySQL服务器配置文件``/etc/my.cnf``，/etc/mysql/my.cnf 或者 /etc/mysql/mysql.conf.d/mysqld.cnf：

max_allowed_packet   = 64M

出于生产率考虑，我们建议用``mysqltuner`` 工具实现优化。你可以从Github ``https://github.com/major/MySQLTuner-perl``下载脚本，或者通过软件管理在Debian或Ubuntu系统上安装：

root> apt-get install mysqltuner

安装后运行下面的脚本：

root> mysqltuner --user root --pass NewRootPassword

步骤8：安装Elasticsearch弹性搜索

OTOBO建议活性安装Elasticsearch以便快速搜索，最简单的办法就是将Elasticsearch和OTOBO安装在一台主机上，并绑定默认端口。

基于Ubuntu 18.04 LTS的Elasticsearch安装范例

JDK安装

root> apt update
root> apt install openjdk-8-jdk

Elasticsearch安装

root> wget -qO - https://artifacts.elastic.co/GPG-KEY-elasticsearch | sudo apt-key add -
root> echo "deb https://artifacts.elastic.co/packages/7.x/apt stable main" | sudo tee /etc/apt/sources.list.d/elastic-7.x.list
root> apt update
root> apt -y install elasticsearch

在其他Linux版本中的Elasticsearch安装

请遵照 https://www.elastic.co/guide/en/elasticsearch/reference/current/setup.html中的安装教程进行。

Elasticsearch模块安装

另外，OTOBO需要在Elasticsearch上安装插件：

root> /usr/share/elasticsearch/bin/elasticsearch-plugin install --batch ingest-attachment
root> /usr/share/elasticsearch/bin/elasticsearch-plugin install --batch analysis-icu

Elasticsearch配置

Elasticsearch的配置有很多选择和可能。

为了确保无故障运行，你需要调整大型OTOBO系统的jvm堆空间尺寸。这个配置在文件``/etc/elasticsearch/jvm.options``中进行调整。一定要吧JVM堆空间的最大和最小值设置为同一个，例如都设为4GB，设置：

-Xms4g
-Xmx4g

在我们的测试中，对于中型安装，这个值设为4-10GB是最好的。

Note

请遵照 https://www.elastic.co/guide/en/elasticsearch/reference/current/setup.html中的安装教程进行。

现在你可以重启你的Elasticsearch服务器，以便新的配置生效。对于大部分系统，可以用下面的命令实现：

root> systemctl restart elasticsearch

步骤8：系统基础配置

请用 http://localhost/otobo/installer.pl （请用你的主机名替换“localhost”）中的网络安装软件，设置你的数据库和基本系统配置，例如电子邮件账户。

步骤9：首次登陆

现在你可以通过http://localhost/otobo/index.pl登陆你的系统了，用户名``root@localhost`` ，密码是上面生成的（请参考之前描述）。

步骤10：启动OTOBO Daemon

OTOBO守护程序的任务是处理OTOBO系统中的不同步的和重复性的工作。之前在cron文件定义中描述的现在由OTOBO守护程序处理，这是运行OTOBO的需要。守护程序还要处理由用户发起的GenericAgent任务。

otobo> /opt/otobo/bin/otobo.Daemon.pl start

步骤11：OTOBO用户的cron任务

在``/opt/otobo/var/cron/*.dist``中有两个默认的cron文件，目的是确保OTOBO Daemon守护程序已经运行起来了。激活这两个文件只需要不带“.dist"扩展名进行拷贝就好。

root> cd /opt/otobo/var/cron/
root> for foo in *.dist; do cp $foo `basename $foo .dist`; done

root> cd /opt/otobo/
root> bin/Cron.sh start

到这一步，基本的系统配置就完成了。

步骤12：设置Bash Auto-Completion （可选）

所有正常的OTOBO命令行的执行都是通过OTOBO管理接口，管理接口可以实现Linux内核任务的自动完成，从而更方便地找到合适的命令和选项。

你可以通过安装软件包``bash-completion``来激活内核任务自动完成，它将为``otobo`` 用户自动检测并调用``/opt/otobo/.bash_completion``文件。

重启你的shell后，你可以键入这个命令再加上TAB，就会列出所有可用的命令：

otobo> /opt/otobo/bin/otobo.Console.pl

如果你只键入命令名字的几个字母，TAB将会列出所有匹配的命令。键入完整命令，按下TAB键将显示所有的可选项和相应信息。

Note

如果有问题，你可以作为用户``otobo`` 执行下面的命令行，并将它加入你的``~/.bashrc`` ，执行文件中的命令。

source /opt/otobo/.bash_completion

步骤13：更多信息

我们建议你阅读OTOBO文档中的：performance-tuning 章节。

安装应用 Docker和Docker Compose

With the dockerized OTOBO deployment you can get your personal OTOBO instance up and running within minutes. All of OTOBO´s dependencies are already included in the provided collection of Docker images.

MariaDB被设置为默认数据库。

为OTOBO建立Elasticsearch进行强力搜索。

启用Redis进行快速缓存。

Gazelle用来作为快速Perl网站服务器。

nginx作为HTTPS支持的可选网络代理。

We think that this setup will become the perfect environment for an OTOBO installation.

需求

经过测试的所需软件最低版本，请参考下面列表：

Docker 19.03.08

DockerCompose 1.25.0

Git 2.25.1

Note

要得到所需的Ubuntu18.04最低版本，请按照https://www.digitalocean.com/community/tutorials/how-to-install-docker-compose-on-ubuntu-18-04和https://wwwdigitalocean.com/community/tutorials/how-to-install-and-use-docker-on-ubuntu-18-04中的说明进行操作。

可以使用标准系统工具来安装git，Docker和Docker Compose。这是在Ubuntu 20.04上安装的示例：

root> apt-get install git docker docker-compose
root> systemctl enable docker

请查看Git和Docker文档，得到更多步骤的说明。

安装

下面的介绍是在假设所有需要的系统都已经安装，并且你已经有了一个工作的Docker环境。我们假设用户**root**被用来和Docker互动，请注意针对一个生产环境，需要有一个专用用户作为Docker管理员。

1. Clone the otobo-docker repo

The Docker images will eventually be fetched from the repository https://hub.docker.com. But there are some setup and command files that need to be cloned from the otobo-docker Github repository. Make sure that you specify the branch that corresponds to the current version of OTOBO. For example, when OTOBO 10.0.12 is the current version then please use the branch rel-10_0.

Note

克隆副本的位置并不重要，在介绍中我们选择 */opt/otobo-docker*作为工作目录。

docker_admin> cd /opt
docker_admin> git clone https://github.com/RotherOSS/otobo-docker.git --branch <BRANCH> --single-branch
docker_admin> ls otobo-docker    # just a sanity check, README.md should exist

2. Create an initial .env file

The Docker Compose configuration file .env is your primary interface for managing your installation of OTOBO. This file must first be created and then be adapted by yourself. In order to simplify the task there are several example files that should be used as starting point. Which sample file it the best fit depends on your use case. In most cases the decision is between .docker_compose_env_http and .docker_compose_env_https, depending on whether TLS must be supported or not. The other files are for more specialised use cases.

.docker_compose_env_http

The OTOBO web app provides HTTP.

.docker_compose_env_https

The OTOBO web app provides HTTPS by runnning Nginx as a reverse proxy webserver.

.docker_compose_env_https_custom_nginx

Like .docker_compose_env_https but with support for a custom Nginx configuration.

.docker_compose_env_https_kerberos

Like .docker_compose_env_https but with sample setup for single sign on.

.docker_compose_env_http_selenium and .docker_compose_env_https_selenium

These are used only for development when Selenium testing is activated.

Note

Use ls -a for listing the hidden sample files.

默认情况下，OTOBO在标准端口上提供， HTTPS的端口443和端口80。激活HTTPS后，OTOBO Web应用程序实际上始终使用HTTP运行。 HTTPS的支持通过另外的反向代理来实现，该代理通过nginx服务实现。

我们假定以下命令都支持HTTPS。

docker_admin> cd /opt/otobo-docker
docker_admin> cp -p .docker_compose_env_https .env # or .docker_compose_env_http for HTTP

3. Configure the password for the database admin user

调整*.env*文件中的以下数值：

OTOBO_DB_ROOT_PASSWORD=<your_secret_password>

``OTOBO_DB_ROOT_PASSWORD``数据库管理员的密码可以自由选择，数据库管理员创建了数据库用户**otobo**和数据库模式**otobo**。

4. Set up a volume with SSL configuration for the nginx webproxy (optional)

如果OTOBO只能通过HTTP进行，这个步骤就可以跳过。

nginx需要SSL加密的证书和私钥。

Note

为了进行测试和开发，可以使用自签名证书。在一般情况下，必须使用注册证书。

参考<https://www.digitalocean.com/community/tutorials/how-to-create-a-self-signed-ssl-certificate-for-nginx-in-ubuntu-18-04>`中的案例，如何创建自己签名的证书。

Note

在nginx中指定一个带有证书的CA链，需要将这个带有实际证书的CA链文件考入一个文件中去。

证书和私钥存储在一个卷中，以便以后Nginx使用，在任何情况下，都需要手动生成该卷，并且需要将证书和密钥复制到该卷：

docker_admin> docker volume create otobo_nginx_ssl
docker_admin> otobo_nginx_ssl_mp=$(docker volume inspect --format '{{ .Mountpoint }}' otobo_nginx_ssl)
docker_admin> echo $otobo_nginx_ssl_mp  # just a sanity check
docker_admin> cp /PathToYourSSLCert/ssl-cert.crt /PathToYourSSLCert/ssl-key.key $otobo_nginx_ssl_mp

需要在我们新创建的* .env *文件中设置复制文件的名称，例如。

OTOBO_NGINX_SSL_CERTIFICATE=/etc/nginx/ssl/ssl-cert.crt and OTOBO_NGINX_SSL_CERTIFICATE_KEY=/etc/nginx/ssl/ssl-key.key

请仅调整文件名，因为路径* / etc / nginx / ssl / *在Docker映像中是硬编码的。

安装应用 Docker和Docker Compose

Now we start the Docker containers using docker-compose. Per default the Docker images will be fetched from https://hub.docker.com/u/rotheross.

docker_admin> docker-compose up --detach

在使用HTTP的情况下，要验证六个或五个服务是否正在实际运行，请输入：

docker_admin> docker-compose ps
docker_admin> docker volume ls

6. Install and start OTOBO

在http：//yourIPorFQDN/otobo/installer.pl中运行OTOBO安装程序。

Note

Please configure OTOBO inside the installer with a new MySQL database. As MySQL database root password please use the password you configured in the variable OTOBO_DB_ROOT_PASSWORD of your .env file. Please leave the value db for the MySQL hostname untouched.

与OTOBO玩得开心吧！

Note

To change to the OTOBO directory, inside the running container, to work on command line as usual, you can use the following Docker command: docker-compose exec web bash.

附加技术信息

本节对隐含的内容提供了更多的技术见解。

Docker容器列表

容器otobo_web_1

内部端口5000上的OTOBO Web服务器。

容器otobo_daemon_1

OTOBO守护程序。 OTOBO守护程序已启动并定期检查。

容器otobo_db_1

在内部端口3306上运行数据库MariaDB。

容器otobo_elastic_1

在内部端口9200和9300上运行Elasticsearch。

容器otobo_redis_1

将Redis作为缓存服务运行。

可选容器otobo_nginx_1

运行nginx作为反向代理以提供HTTPS支持。

Docker卷概述

Docker卷是在主机上创建的，用于持久性数据。这些允许启动和停止服务而不会丢失数据。请记住，容器是临时的，只有卷中的数据是永久的。

otobo_opt_otobo

contains /opt/otobo in the container web and daemon.

otobo_mariadb_data

contains /var/lib/mysql in the container db.

otobo_elasticsearch_data

contains /usr/share/elasticsearch/datal in the container elastic.

otobo_redis_data

包含容器“ redis”的数据。

otobo_nginx_ssl

包含TLS文件，证书和私钥，必须手动初始化。

Docker环境变量

In the instructions we did only minimal configuration. But the file .env allows to set more variables. Here is a short list of the most important environment variables. Note that more environment variables are supported by the base images.

MariaDB设置

OTOBO_DB_ROOT_PASSWORD

MySQL的根密码。必须设置为运行otobo db。

Elasticsearch设置

Elasticsearch需要在生产环境中进行一些设置。请阅读https://www.elastic.co/guide/zh-CN/elasticsearch/reference/7.8/docker.html#docker-prod-prerequisites了解详细信息。

OTOBO_Elasticsearch_ES_JAVA_OPTS

设置案例：* OTOBO_Elasticsearch_ES_JAVA_OPTS = -Xms512m -Xmx512m *，在生产环境中，请将该值提高为4G。

Webserver设置

OTOBO_WEB_HTTP_PORT

设置以防HTTP端口偏离标准端口80。启用HTTPS时，HTTP端口将重定向到HTTPS。

nginx网络代理设置

这些设置在启用HTTPS时使用。

OTOBO_WEB_HTTP_PORT

设置以防HTTP端口偏离标准端口80。将重定向到HTTPS。

OTOBO_WEB_HTTPS_PORT

设置以防HTTPS端口偏离标准端口443。

OTOBO_NGINX_SSL_CERTIFICATE

Nginx Webproxy的SSL证书。例如：* OTOBO_NGINX_SSL_CERTIFICATE = / etc / nginx / ssl / acme.crt *

OTOBO_NGINX_SSL_CERTIFICATE_KEY

Nginx Webproxy的SSL密钥。例如：* OTOBO_NGINX_SSL_CERTIFICATE_KEY = / etc / nginx / ssl / acme.key *

docker-compose设置

这些设置由docker-compose直接使用。

COMPOSE_PROJECT_NAME

The project name is used as the prefix for the volumes and containers. Per default this prefix is set to otobo, resulting in container names like otobo_web_1 and otobo_db_1. Change this name when you want to run more then one instance of OTOBO on the same server.

COMPOSE_PATH_SEPARATOR

COMPOSE_FILE数值的分隔符

COMPOSE_FILE

使用* docker-compose / otobo-base.yml 作为基础，并添加所需的扩展文件。例如 docker-compose / otobo-override-http.yml 或 docker-compose / otobo-override-https.yml *。

OTOBO_IMAGE_OTOBO, OTOBO_IMAGE_OTOBO_ELASTICSEARCH, OTOBO_IMAGE_OTOBO_NGINX, ...

Used for specifying alternative Docker images. Useful for testing local builds or for using updated versions of the images.

进阶主题

Nginx网络代理的自定义配置

The container otobo_nginx_1 provides HTTPS support by running Nginx as a reverse proxy. The Docker image that runs in the container is composed of the official Nginx Docker image, https://hub.docker.com/_/nginx, along with a OTOBO specific configuration of Nginx.

The default OTOBO specific configuration can be found within the Docker image at /etc/nginx/template/otobo_nginx.conf.template. Actually, this is only a template for the final configuration. There is a process, provided by the Nginx base image, that replaces the macros in the template with the corresponding environment variable. This process runs when the container starts up. In the default template file, the following macros are used:

OTOBO_NGINX_SSL_CERTIFICATE

For configuring SSL.

OTOBO_NGINX_SSL_CERTIFICATE_KEY

For configuring SSL.

OTOBO_NGINX_WEB_HOST

The internally used HTTP host.

OTOBO_NGINX_WEB_PORT

The internally used HTTP port.

See step 4. for how this configuration possibility was used for setting up the SSL certificate.

Warning

只有OTOBO 10.0.4或更高版本支持以下方法。

When the standard macros are not sufficient, then the customisation can go further. This can be achieved by replacing the default config template with a customized version. It is best practice to not simple change the configuration in the running container. Instead we first create a persistent volume that contains the custom config. Then we tell the otobo_nginx_1 to mount the new volume and to use the customized configuration.

First comes generation of the new volume. In these sample commands, we use the existing template as a starting point.

# stop the possibly running containers
docker_admin> cd /opt/otobo-docker
docker_admin> docker-compose down

# create a volume that is initially not connected to otobo_nginx_1
docker_admin> docker volume create otobo_nginx_custom_config

# find out where the new volume is located on the Docker host
docker_admin> otobo_nginx_custom_config_mp=$(docker volume inspect --format '{{ .Mountpoint }}' otobo_nginx_custom_config)
docker_admin> echo $otobo_nginx_custom_config_mp  # just a sanity check
docker_admin> ls $otobo_nginx_custom_config_mp    # another sanity check

# copy the default config into the new volume
docker_admin> docker create --name tmp-nginx-container rotheross/otobo-nginx-webproxy:latest  # use the appropriate label
docker_admin> docker cp tmp-nginx-container:/etc/nginx/templates/otobo_nginx.conf.template $otobo_nginx_custom_config_mp # might need 'sudo'
docker_admin> ls -l $otobo_nginx_custom_config_mp/otobo_nginx.conf.template # just checking, might need 'sudo'
docker_admin> docker rm tmp-nginx-container

# adapt the file $otobo_nginx_custom_config_mp/otobo_nginx.conf.template to your needs
docker_admin> vim $otobo_nginx_custom_config_mp/otobo_nginx.conf.template

Warning

调整后的Nginx配置通常包含指令** listen **，以明确Web服务器的端口。在OTOBO 10.0.3和OTOBO 10.0.4两个版本中，内部使用的端口有所变化。这个变化必须体现在调整后的nginx配置中。因此，对于10.0.3或更早版本，请使用端口80和443。对于OTOBO 10.0.4，请使用端口8080和8443。

After setting up the volume, the adapted configuration must be activated. The new volume is set up in docker-compose/otobo-nginx-custom-config.yml. Therefore this file must be added to COMPOSE_FILE. Then Nginx must be directed to use the new config. This is done by setting NGINX_ENVSUBST_TEMPLATE_DIR in the environment. In order to achieve this, uncomment or add the following lines in your .env file:

COMPOSE_FILE=docker-compose/otobo-base.yml:docker-compose/otobo-override-https.yml:docker-compose/otobo-nginx-custom-config.yml
NGINX_ENVSUBST_TEMPLATE_DIR=/etc/nginx/config/template-custom

更改后的Docker Compose配置可以通过以下方式进行检查：

docker_admin> docker-compose config | more

最后，可以再次启动容器：

docker_admin> docker-compose up --detach

另请参见https://hub.docker.com/_/nginx中的“在nginx配置中使用环境变量（1.19中的新功能）”部分。

选择非标准端口

默认情况下，端口443和80分别为HTTPS和HTTP服务。在某些情况下，其他服务可能已经使用了这些端口中的一个或两个。在这些情况下，可以通过在* .env *文件中指定`OTOBO_WEB_HTTP_PORT`和`OTOBO_WEB_HTTPS_PORT`来覆盖默认端口。

Customizing the OTOBO Docker image

Many customizations can be done in the external volume otobo_opt_otobo which corresponds to the directory /opt/otobo in the Docker image. This works e.g. for local Perl modules, which can be installed into /opt/otobo/local. The advantage of this approach is that the image itself does not have to be modified.

Installing extra Debian packages is a little bit trickier. One approach is to create a custom Dockerfile and use the OTOBO image as the base image. Another approach is to create a modified image directly from a running container. This can be done with the command docker commit, https://docs.docker.com/engine/reference/commandline/commit/. A nice writeup of that process is available at https://phoenixnap.com/kb/how-to-commit-changes-to-docker-image.

But for the latter approach there are two hurdles to overcome. First, the image otobo runs per default as the user otobo with the UID 1000. The problem is that the user otobo is not allowed to install system packages. Thus, the first part of the solution is to pass the option --user root when running the image. However the second hurdle is that the default entrypoint script /opt/otobo_install/entrypoint.sh exits immediately when it is called as root. The reasoning behind that design decision is that running inadvertently as root should be discouraged. So, the second part of the solution is to specify a different entrypoint script that does not care who the caller is. This leaves us with following example commands, where we add fortune cookies to otobo:

Pull a tagged OTOBO image, if we don't have it yet, and check whether the image already provides fortune cookies:

$ docker run rotheross/otobo:rel-10_0_10 /usr/games/fortune
/opt/otobo_install/entrypoint.sh: line 57: /usr/games/fortune: No such file or directory

Add fortune cookies to a named container running the original OTOBO image. This is done in an interactive session as the user root:

$ docker run -it --user root --entrypoint /bin/bash --name otobo_orig rotheross/otobo:rel-10_0_10
root@50ac203409eb:/opt/otobo# apt update
root@50ac203409eb:/opt/otobo# apt install fortunes
root@50ac203409eb:/opt/otobo# exit
$ docker ps -a | head

Create an image from the stopped container and give it a name. Take into account that the default user and entrypoint script must be restored:

$ docker commit -c 'USER otobo'  -c 'ENTRYPOINT ["/opt/otobo_install/entrypoint.sh"]' otobo_orig otobo_with_fortune_cookies

Finally we can doublecheck:

$ docker run otobo_with_fortune_cookies /usr/games/fortune
A platitude is simply a truth repeated till people get tired of hearing it.
                -- Stanley Baldwin

The modified image can be specified in your .env file and then be used for fun and profit.

创建本地镜像

Note

Building Docker images locally is usually only needed during development. Other use cases are when more current base images should be used for an installation or when extra functionality must be added to the images.

The Docker files needed for creating Docker images locally are part of the the git repository https://github.com/RotherOSS/otobo:

otobo.web.dockerfile

otobo.nginx.dockerfile

otobo.elasticsearch.dockerfile

The script for the actual creation of the images is bin/docker/build_docker_images.sh.

docker_admin> cd /opt
docker_admin> git clone https://github.com/RotherOSS/otobo.git
docker_admin> # checkout the wanted branch. e.g. git checkout rel-10_0_11
docker_admin> cd otobo
docker_admin> # modify the docker files if necessary
docker_admin> bin/docker/build_docker_images.sh
docker_admin> docker image ls

The locally built Docker images are tagged as local-<OTOBO_VERSION> using the version set up the file RELEASE.

After building the local images, one can return to the docker-compose directory. The local images are declared by setting OTOBO_IMAGE_OTOBO, OTOBO_IMAGE_OTOBO_ELASTICSEARCH, OTOBO_IMAGE_OTOBO_NGINX in .env.

自动安装

Instead of going through http://yourIPorFQDN/otobo/installer.pl, one can take a short cut. This is useful for running the test suite on a fresh installation.

Warning

docker-compose down -v 将清除所有之前的配置和数据。

docker_admin> docker-compose down -v
docker_admin> docker-compose up --detach
docker_admin> docker-compose stop daemon
docker_admin> docker-compose exec web bash\
-c "rm -f Kernel/Config/Files/ZZZAAuto.pm ; bin/docker/quick_setup.pl --db-password otobo_root"
docker_admin> docker-compose exec web bash\
-c "bin/docker/run_test_suite.sh"
.......
docker_admin> docker-compose start daemon

常用命令列表

** Docker **

docker system prune -a system clean-up (removes all unused images, containers, volumes, networks)

docker version show version

docker build --tag otobo --file=otobo.web.Dockerfile . build an image

docker run --publish 80:5000 otobo run the new image

docker run -it -v opt_otobo:/opt/otobo otobo bash log into the new image

docker run -it -v opt_otobo:/opt/otobo --entrypoint bash otobo try that in case entrypoint.sh is broken

docker ps show running images

docker images show available images

docker volume ls list volumes

docker volume inspect otobo_opt_otobo inspect a volume

docker volume inspect --format '{{ .Mountpoint }}' otobo_nginx_ssl get volume mountpoint

docker volume rm tmp_volume remove a volume

docker inspect <container> inspect a container

docker save --output otobo.tar otobo:latest && tar -tvf otobo.tar list files in an image

docker exec -it nginx-server nginx -s reload reload nginx

docker-compose设置

docker-compose config check and show the configuration

docker-compose ps show the running containers

docker-compose exec nginx nginx -s reload reload nginx

资源

Perl Maven：

Docker Compose快速启动请参考

在Ubuntu 18.04 LTS上运行的Docker Compose更新版本请参考

在Ubuntu 18.04 LTS上运行的Docker更新版本请参考

docker-otrs：

清理：

Dockerfile 最佳实践：

`Docker缓存失效：<https://stackoverflow.com/questions/34814669/when-does-docker-image-cache-invalidation-occur>`_

Docker主机IP地址：

环境：

`自己签名的证书：<https://www.digitalocean.com/community/tutorials/how-to-create-a-self-signed-ssl-certificate-for-nginx-in-ubuntu-18-04>`_

检查失败的创建

从 OTRS / ((OTRS)) Community Edition version 6 转移到 OTOBO version 10

欢迎并感谢大家选择OTOBO！

OTRS，（（OTRS））Community Edition和OTOBO的应用都非常全面和灵活。因此，每次迁移OTOBO都需要进行充分的准备，甚至还可能需要一些返工。

请预留时间进行迁移，并逐步按照这些说明进行操作。

If you have any problem or question, please do not despair. Call our support line, write an email, or post your query in the OTOBO Community forum at https://forum.otobo.org/. We will find a way to help you!

Note

After the migration the data previously available in OTRS 6 will be available in OTOBO 10. We do not modify any data of the OTRS 6 installation during the migration.

Overview over the Supported Migration Szenarios

With the OTOBO Migration Interface it is possible to employ the following migration strategies:

The general migration strategy.

This is the regular way to perform a migration. Many different different combinations are supported:

Change server:

Migrate and simultaneously move to a new application server.

Separate application and web servers:

It's your choice whether you want to run application and database server on the same host or each on a dedictated host. This choice is regardless of the previous setup in OTRS / ((OTRS)) Community Edition.

Different databases:

Migrate from any of the supported databases to any other supported database.

Different operating system:

Switch from any supported operating system to any other supported operating system.

Docker:

Migrate to a Docker-based installation of OTOBO 10.

A variant of the general strategy where the database migration is streamlined.

Use the ETL-like migration when the source database mustn't suffer from increased load or when access to the source database is a bottleneck. In the general strategy, the data is row by row first read from the otrs database and then inserted into the OTOBO database. In this variant, the complete otrs database tables are first exported, then transformed, and then imported into the otobo database.

Migration from an Oracle based OTRS 6 installation to an Oracle based OTOBO installation.

This is a special case that is not supported by the general migration strategy. This means that a variant of the streamlined strategy must be used.

Warning

All strategies work for both Docker-based and native installations. But for Docker-based installations some peculiarities have to be considered. These peculiarities are handled in the optional steps.

Note

It is also feasible to clone the OTRS datase to the OTOBO database server before the actual migration. This can speed up the general migration strategy.

迁移的要求

Basic requirement for a migration is that you already have an ((OTRS)) Community Edition or OTRS 6.0.* running, and that you want to transfer both configuration and data to OTOBO.

Warning

Please consider carefully whether you really need the data and configuration. Experience shows that quite often a new start is the better option. This is because in many cases the previously used installation and configuration was rather suboptimal anyways. It might also make sense to only transfer the ticket data and to change the basic configuration to OTOBO Best Practice. We are happy to advise you, please get in touch at hello@otobo.de or ask your question in the OTOBO Community forum at https://forum.otobo.org/.

您需要一个运行中的OTOBO安装程序，才能从那里开始迁移！

此OTOBO安装必须还包含要在OTOBO中使用的，OTRS中安装的所有OPM软件包。

If you are planning to migrate to another server, then the OTOBO webserver must be able to access the location where your ((OTRS)) Community Edition or OTRS 6.0.* is installed. In most cases, this is the directory /opt/otrs on the server running OTRS. The read access can be effected via SSH or via file system mounts.

The otrs database must be accessible from the server running OTOBO. Readonly access must be granted for external hosts. If access is not possible, or when the speed of the migration should be optimised, then a dump of the database is sufficient.

Note

如果无法在服务器之间进行SSH和数据库访问，请在同一台服务器上进行OTRS到OTOBO的迁移，然后再移动新安装。

步骤 1：安装新的OTOBO系统

Please start with installing a new OTOBO system. Your old OTRS / ((OTRS)) Community Edition installation will be migrated to that new system. We strongly recommend to read the chapter OTOBO安装. For Docker-based installations we refer to the chapter 安装应用 Docker和Docker Compose.

Warning

Under Apache, there are pitfalls with running two independent mod_perl applications under on the same webserver. Therefore, it is advised to run OTRS and OTOBO on separate webservers. Alternatively remove the OTRS configuration from Apache before installing OTOBO. Use the command a2query -s and check the directories /etc/apache2/sites-available and /etc/apache2/sites-enabled for inspecting which configurations are currently available and which are enabled.

After finishing the installation please log in as root@localhost. Navigate to the OTOBO Admin Area Admin -> Packages and install all required OTOBO OPM packages.

以下OPM软件包和OTRS“功能附加组件”不需要，也不应该安装，因为这些功能已在标准的OTOBO版本中提供了：

OTRSHideShowDynamicField

RotherOSSHideShowDynamicField

TicketForms

RotherOSS-LongEscalationPerformanceBoost

Znuny4OTRS - AdvancedDynamicFields

Znuny4OTRS-AutoSelect

Znuny4OTRS-EscalationSuspend

OTRSEscalationSuspend

OTRSDynamicFieldDatabase

OTRSDynamicFieldWebService

OTRSBruteForceAttackProtection

Znuny4OTRS-ExternalURLJump

Znuny4OTRS-QuickClose

Znuny4OTRS-AutoCheckbox

OTRSSystemConfigurationHistory

Znuny4OTRS-PasswordPolicy

Step 2: Deactivate SecureMode on OTOBO

After installing OTOBO, please log in again to the OTOBO Admin Area Admin -> System Configuration and deactivate the config option SecureMode.

Note

Do not forget to actually deploy the changed setting.

Step 3: Stop the OTOBO Daemon

This is necessary when the OTOBO Daemon is actually running. Stopping the Daemon is different between Docker-based and non-Docker-based installations.

In the non-Docker case execute the following commands as the user otobo:

# in case you are logged in as root
root> su - otobo

otobo> /opt/otobo/bin/Cron.sh stop
otobo> /opt/otobo/bin/otobo.Daemon.pl stop --force

When OTOBO is running in Docker, you just need to stop the service daemon:

docker_admin> cd /opt/otobo-docker
docker_admin> docker-compose stop daemon
docker_admin> docker-compose ps     # otobo_daemon_1 should have exited with the code 0

Note

建议此时运行整个OTOBO系统的备份。如果在迁移过程中出现问题，则不必重复整个安装过程，而可以导入备份以进行新的迁移。

See also

我们建议你阅读OTOBO：backup-restore`章节。

Optional Step: Mount /opt/otrs for Convenient Access

Often OTOBO should be running on a new server where /opt/otrs isn't available initially. In these cases the directory /opt/otrs on the OTRS server can be mounted into the file system of the OTOBO server. When a regular network mount is not possible, then using sshfs might be an option.

Optional Step: Install sshpass and rsync when /opt/otrs Should be Copied via ssh

This step is only necessary when you want to migrate OTRS from another server and when /opt/otrs from the remote server hasn't been mounted on the server running OTOBO.

The tools sshpass and rsync are needed so that migration.pl can copy files via ssh. For installing sshpass, please log in on the server as user root and execute one of the following commands:

$ # Install sshpass under Debian / Ubuntu Linux
$ sudo apt-get install sshpass

$ #Install sshpass under RHEL/CentOS Linux
$ sudo yum install sshpass

$ # Install sshpass under Fedora
$ sudo dnf install sshpass

$ # Install sshpass under OpenSUSE Linux
$ sudo zypper install sshpass

如果* rsysnc *不可用，则必须执行相同的操作。

Step 4: Preparing the OTRS / ((OTRS)) Community Edition system

Note

另外，你还要确保你的OTRS /（（OTRS））Community Edition系统具备有效的备份。是的，在迁移过程中我们不会修改任何OTRS数据，但有时各种错误会造成一些麻烦。

现在我们已准备好进行迁移。首先，我们需要确保不再处理任何工单并且没有用户登录到OTRS：

请登录到OTOBO管理员区域 Admin ->  System Maintenance，并插入几个小时的新系统维护。之后，删除所有话务员和用户的会话（“ Admin-> Sessions”），而后退出登陆。

停止所有相关服务和OTRS守护程序

请确保没有正在运行的服务或cron作业。

root> su - otrs
otrs>
otrs> /opt/otrs/bin/Cron.sh stop
otrs> /opt/otrs/bin/otrs.Daemon.pl stop --force
otrs> /opt/otrs/bin/otrs.Console.pl Maint::Cache::Delete
otrs> /opt/otrs/bin/otrs.Console.pl Maint::Session::DeleteAll
otrs> /opt/otrs/bin/otrs.Console.pl Maint::Loader::CacheCleanup
otrs> /opt/otrs/bin/otrs.Console.pl Maint::WebUploadCache::Cleanup

Optional Step for Docker: make required data available inside container

There are some specifics to be considered when your OTOBO installation is running under Docker. The most relevant: processes running in a Docker container generally cannot access directories outside the container. There is an exception though: directories mounted as volumes into the container can be accessed. Also, note that the MariaDB database running in otobo_db_1 is not directly accessible from outside the container network.

Note

下面的介绍是在假设所有需要的系统都已经安装，并且你已经有了一个工作的Docker环境。我们假设用户**root**被用来和Docker互动，请注意针对一个生产环境，需要有一个专用用户作为Docker管理员。

Docker：将* / opt / otrs 复制到卷 otobo_opt_otobo *

在本节中，我们假设Docker主机上有* / opt / otrs *。

最少有两种可能性：

Docker：将* / opt / otrs 复制到卷 otobo_opt_otobo *

挂载* / opt / otrs *作为附加卷

在这里我们集中讨论选项** a.**。

在本节中，我们假设Docker主机上有* / opt / otrs *。

docker_admin> otobo_opt_otobo_mp=$(docker volume inspect --format '{{ .Mountpoint }}' otobo_opt_otobo)
docker_admin> echo $otobo_opt_otobo_mp  # just a sanity check

我们用``rsync``进行安全复制，根据你的Docker设置，这个命令有可能需要和``sudo``一起运行。

docker_admin> # when docker_admin is root
docker_admin> rsync --recursive --safe-links --owner --group --chown 1000:1000 --perms --chmod "a-wx,Fu+r,Du+rx" /opt/otrs/ $otobo_opt_otobo_mp/var/tmp/copied_otrs
docker_admin> ls -la $otobo_opt_otobo_mp/var/tmp/copied_otrs  # just a sanity check

docker_admin> # when docker_admin is not root
docker_admin> sudo rsync --recursive --safe-links --owner --group --chown 1000:1000 --perms --chmod "a-wx,Fu+r,Du+rx" /opt/otrs/ $otobo_opt_otobo_mp/var/tmp/copied_otrs
docker_admin> sudo ls -la $otobo_opt_otobo_mp/var/tmp/copied_otrs  # just a sanity check

该复制的目录应该是容器中的* / opt / otobo / tmp / otrs *。

Optional Step: Streamlined migration of the database

In the general migration strategy, all data in the database tables is copied row by row from the OTRS database into the OTOBO database. Exporting the data from the OTRS database and importing it into the OTOBO database might save time and is more stable in some circumstances.

Note

This variant works for both Docker-based and native installations.

Note

These instructions assume that OTRS is using MySQL as its backend.

First of all, we need a dump of the needed OTRS database tables. Then we need to perform a couple of transformations:

convert the character set to utf8mb4

rename a couple of tables

shorten some table columns

After the transfomation we can overwrite the tables in the OTOBO schema with the transformed data from OTRS. Effectively we need not a single dump file, but several SQL scripts.

当安装了mysqldump并且可以连接到OTRS数据库时，您可以直接在Docker主机上创建数据库转储。脚本* bin / backup.pl *支持这种情况。

Warning

在本节中，我们假设Docker主机上有* / opt / otrs *。

otobo> cd /opt/otobo
otobo> scripts/backup.pl -t migratefromotrs --db-name otrs --db-host=127.0.0.1 --db-user otrs --db-password "secret_otrs_password"

Note

Alternatively, the database can be dumped on another server and then be transferred to the Docker host afterwards. An easy way to do this is to copy /opt/otobo to the server running OTRS and perform the same command as above.

The script bin/backup.pl generates four SQL scripts in a dump directory, e.g. in 2021-04-13_12-13-04 In order to execute the SQL scripts, we need to run the command mysql.

Native installation:

otobo> cd <dump_dir>
otobo> mysql -u root -p<root_secret> otobo < otrs_pre.sql
otobo> mysql -u root -p<root_secret> otobo < otrs_schema_for_otobo.sql
otobo> mysql -u root -p<root_secret> otobo < otrs_data.sql
otobo> mysql -u root -p<root_secret> otobo < otrs_post.sql

Docker-based installation:

Run the command mysql within the Docker container db for importing the database dump files. Note that the password for the database root is now the password that has been set up in the file .env on the Docker host.

docker_admin> cd /opt/otobo-docker
docker_admin> cd <dump_dir>
docker_admin> docker-compose exec -T db mysql -u root -p<root_secret> otobo < <dump_dir>/otrs_pre.sql
docker_admin> docker-compose exec -T db mysql -u root -p<root_secret> otobo < <dump_dir>/otrs_schema_for_otobo.sql
docker_admin> docker-compose exec -T db mysql -u root -p<root_secret> otobo < <dump_dir>/otrs_post.sql
docker_admin> docker-compose exec -T db mysql -u root -p<root_secret> otobo < <dump_dir>/otrs_data.sql

For a quick check whether the import worked, you can run the following commands.

otobo> mysql -u root -p<root_secret> -e 'SHOW DATABASES'
otobo> mysql -u root -p<root_secret> otobo -e 'SHOW TABLES'
otobo> mysql -u root -p<root_secret> otobo -e 'SHOW CREATE TABLE ticket'

or

docker_admin> docker-compose exec -T db mysql -u root -p<root_secret> -e 'SHOW DATABASES'
docker_admin> docker-compose exec -T db mysql -u root -p<root_secret> otobo -e 'SHOW TABLES'
docker_admin> docker-compose exec -T db mysql -u root -p<root_secret> otobo -e 'SHOW CREATE TABLE ticket'

The database is now migrated. This means that during the next step we can skip the database migration. Watch out for the relevant checkbox.

Step 5: Perform the Migration!

Please use the web migration tool at http://localhost/otobo/migration.pl. Be aware that you might have to replace "localhost" with your OTOBO hostname and you might have to add your non-standard port. The application then guides you through the migration process.

Warning

Sometimes, a warning is shown that the deactivation of SecureMode has not been detected. Please restart the webserver in this case. This forces the webserver to read in the current configuration.

# native installation
root> service apache2 restart

# Docker-based installation
docker_admin> cd /opt/otobo-docker
docker_admin> docker-compose restart web
docker_admin> docker-compose ps     # otobo_web_1 should be running again

Note

If OTOBO runs inside a Docker container, keep the default settings localhost for the OTRS server and /opt/otobo/var/tmp/copied_otrs for the OTRS home directory. This is the path of the data that was copied in the optional step.

Note

The default values for OTRS database user and password are taken from Kernel/Config.pm in the OTRS home directory. Change the proposed settings if you are using a dedicated database user for the migration. Also change the settings when you work with a database that was copied into the otobo_db_1 Docker container.

Note

In the Docker case, a database running on the Docker host won't be reachable via 127.0.0.1 from within the Docker container. This means that the setting 127.0.0.1 won't be valid for the input field OTRS Server. In that case, enter one of the alternative IP-addresses reported by the command hostname --all-ip-addresses for OTRS Server.

Note

When migrating to a new application server, or to a Docker-based installation, quite often the database cannot be accessed from the target installation. This is usually due to the fact that the otobo database user can only connect from the host the database runs on. In order to allow access anyways it is recommended to create a dedicated database user for the migration. E.g. CREATE USER 'otrs_migration'@'%' IDENTIFIED BY 'otrs_migration'; and GRANT SELECT, SHOW VIEW ON otrs.* TO 'otrs_migration'@'%';. This user can be dropped again after the migration: DROP USER 'otrs_migration'@'%'.

Custom settings in Kernel/Config.pm are carried over from the old OTRS installation to the new OTOBO installation. When you have custom settings, then please take a look at the migrated file /opt/otobo/Kernel/Config.pm. You might want to adapt custom pathes or LDAP settings. In the best case you might find that some custom setting are longer needed.

迁移完成后，请花点时间测试整个系统。一旦确定迁移成功并且要从现在开始使用OTOBO，请启动OTOBO守护程序：

root> su - otobo
otobo>
otobo> /opt/otobo/bin/Cron.sh start
otobo> /opt/otobo/bin/otobo.Daemon.pl start

在Docker情况下：

docker_admin> cd ~/otobo-docker
docker_admin> docker-compose start daemon

Step 6: After Successful Migration!

如果不再需要，卸载 sshpass。

Drop the databases and database users dedicated to the migration if you created any.

享受OTOBO带来的快乐吧！

Known Migration Problems

1. Login after migration not possible

在我们的迁移测试中，用于迁移的浏览器有时会出现问题。重新启动浏览器后，通常可以解决此问题。使用Safari，有时需要手动删除旧的OTRS会话。

2. Final page of the migration has a strange layout due to missing CSS files

当ScriptAlias的配置不是标准值时，可能会发生这种情况。迁移简单地用otrs代替otobo可能会导致无法在OTOBO中检索CSS和JavaScript。发生这种情况时，请检查Kernel / Config.pm中的设置并将其恢复为合理的值。

3. Migration stops due to MySQL errors

On systems that experienced problems with an upgrade in the past, the migration process may stop due to MySQL errors in the tables ticket and ticket_history. Usually these errors are NULL values in the source table that are no longer allowed in the target table. These conflicts have to be manually resolved before you can resume the migration.

As of OTOBO 10.0.12 there is a check in migration.pl that checks for NULL values before the data transfer is done. Note, that the resolution still needs to be performed manually.

4. Errors in Step 5 when migrating to PostgreSQL

In these cases the not so helpful message "System was unable to complete data transfer." is shown by migration.pl. The Apache logfile, and the OTOBO logfile, show a more meaningful message: "Message: ERROR: permission denied to set parameter "session_replication_role", SQL: 'set session_replication_role to replica;'". In order to give the database user otobo the needed superuser privileges, run the following statement as the PostgreSQL admin: ALTER USER otobo WITH SUPERUSER;. Then retry running http://localhost/otobo/migration.pl. After the migration, return to the normal state by running ALTER USER otobo WITH NOSUPERUSER.

It is not clear yet, whether the extended privileges have to be granted in every setup.

See also

The discussion in https://otobo.de/de/forums/topic/otrs-6-mysql-migration-to-otobo-postgresql/.

5. Problems with the Deployment the Merged System Configuration

The system configuration is migrated after the database tables were migrated. In this context, migration means merging the default settings of OTOBO with the system configuration of the source OTRS system. Inconsistencies can arise in this step. An real life example is the setting Ticket::Frontend::AgentTicketQuickClose###State. This setting is new in OTOBO 10 and the default value is the state closed successful. But this setting is invalid when the state closed successful has been dropped or renamed in the source system. This inconsistency is detected as an error in the migration step Migrate configuration settings. Actually, the merged system configuration is stored in the database, but additional validity checks are performed during deployment.

The problem must be alleviated manually by using OTOBO console commands.

List the inconsistencies with the command bin/otobo.Console.pl Admin::Config::ListInvalid

Interactively fix the invalid values with bin/otobo.Console.pl Admin::Config::FixInvalid

Deploy the collected changes from migration.pl, including the deactivated SecureMode with bin/otobo.Console.pl Maint::Config::Rebuild

After these manual steps you should be able to run migration.pl again. The migration will continue with the step where the error occurred.

步骤 7：手工迁移的任务和修改

1. Password policy rules

如果使用本地身份验证，对于OTOBO 10，代理和客户用户的新的默认密码策略将生效。可以在系统配置（“ PreferencesGroups ### Password”和“ CustomerPersonalPreference #### Password”）中更改密码策略规则。

密码策略规则

默认

`` PasswordMinSize ``

8

`` PasswordMin2Lower2UpperCharacters ``

是

`` PasswordNeedDigit ``

是

`` PasswordHistory ``

10

`` PasswordTTL ``

30天

`` PasswordWarnBeforeExpiry ``

5天

`` PasswordChangeAfterFirstLogin ``

是

2. Under Docker: Manually migrate cron jobs

In a non-Docker installation of OTOBO, there is at least one cron job which checks the health of the Daemon. Under Docker, this cron job no longer exists. Furthermore, there is no cron daemon running in any of the Docker containers. This means that you have to look for an individual solution for OTRS systems with customer-specific cron jobs (e. g. backing up the database).

Special topics

Migration from Oracle to Oracle

For migration to Oracle the ETL-like strategy must be employed. This is because Oracle provides no easy way to temporarily turn off foreign key checks.

On the OTOBO host a Oracle client and the Perl module DBD::Oracle must be installed.

Note

When using the Oracle instant client, then the optional SDK is also needed for installing DBD::Oracle.

There are many ways of cloning a schema. In the sample commands we use expdb and impdb which use Data Pump under the hood.

Note

The connect strings shown in this documentation refer to the case when both source and target database run in a Docker container. See also https://github.com/bschmalhofer/otobo-ideas/blob/master/oracle.md .

Clear out otobo

Stop the webserver for otobo, so that the DB connection for otobo is closed.

-- in the OTOBO database
DROP USER otobo CASCADE

Export the complete OTRS schema.

mkdir /tmp/otrs_dump_dir

-- in the OTRS database
CREATE DIRECTORY OTRS_DUMP_DIR AS '/tmp/otrs_dump_dir';
GRANT READ, WRITE ON DIRECTORY OTRS_DUMP_DIR TO sys;

expdp \"sys/Oradoc_db1@//127.0.0.1/orclpdb1.localdomain as sysdba\" schemas=otrs directory=OTRS_DUMP_DIR dumpfile=otrs.dmp logfile=expdpotrs.log

Import the OTRS schema, renaming the schema to 'otobo'.

impdp \"sys/Oradoc_db1@//127.0.0.1/orclpdb1.localdomain as sysdba\" directory=OTRS_DUMP_DIR dumpfile=otrs.dmp logfile=impdpotobo.log remap_schema=otrs:otobo

-- in the OTOBO database
-- double check
select owner, table_name from all_tables where table_name like 'ARTICLE_DATA_OT%_CHAT';

-- optionally, set the password for the user otobo
    ALTER USER otobo IDENTIFIED BY XXXXXX;

Adapt the cloned schema otobo

cd /opt/otobo
scripts/backup.pl --backup-type migratefromotrs # it's OK that the command knows only about the otobo database, only last line is relevant
sqlplus otobo/otobo@//127.0.0.1/orclpdb1.localdomain < /home/bernhard/devel/OTOBO/otobo/2021-03-31_13-36-55/orclpdb1.localdomain_post.sql >sqlplus.out 2>&1
double check with `select owner, table_name from all_tables where table_name like 'ARTICLE_DATA_OT%_CHAT';

Start the web server for otobo again

Proceed with step 5, that is with running migration.pl.

更新

Note

强烈建议先在单独的测试计算机上对更新进行测试。

步骤 1：停用所有相关服务和OTOBO守护程序

请确保没有其他正在运行的服务或cron作业，会尝试访问OTOBO的，当然这将取决于你对服务的配置。

root> systemctl stop postfix
root> systemctl stop apache2
root> systemctl stop cron

停用OTOBO cron作业和守护程序（按照这个顺序）：

root> su - otobo
otobo> cd /opt/otobo/
otobo> bin/Cron.sh stop
otobo> bin/otobo.Daemon.pl stop

步骤 2：备份文件和数据库

为整个``/opt/otobo``目录和数据库创建备份。

一个标准的 Ubuntu 和 MySQL 的安装案例

root> mkdir /root/otobo-update                      # Create a update directory
root> cd /root/otobo-update                         # Change into the update directory
root> cp -pr /opt/otobo otobo-prod-old              # Backup the hole OTOBO directory to the update directory
root> mysqldump -u otobo -p otobo -r otobo-prod-old.sql   # Backup the otobo database to otobo-prod-old.sql

请检查是否所有文件都有效。现在我们已经拥有了所有需要的数据的备份。

Warning

没有完整的系统备份，请勿继续。你也可以参考：`backup-restore`脚本。

步骤 3：安装新的版本

从https://ftp.otobo.org/pub/otobo/下载最新的OTOBO版本软件，打开封装文档（例如使用``tar``命令），并存到目录``/root/otobo-update``：

root> cd /root/otobo-update                                             # Change into the update directory
root> wget https://ftp.otobo.org/pub/otobo/otobo-latest-10.0.tar.gz     # Download he latest OTOBO 10 release
root> tar -xzf otobo-latest-10.0.tar.gz                                 # Unzip OTOBO
root> cp -r otobo-10.x.x/* /opt/otobo                                   # Copy the new otobo directory to /opt/otobo

恢复旧配置文件

在OTOBO 10中，我们只需要拷贝文件``Kernel/Config.pm`` 。

root> cd /root/otobo-update
root> cp -p otobo-prod-old/Kernel/Config.pm /opt/otobo/Kernel/
root> cp -p otobo-prod-old/var/cron/* /opt/otobo/var/cron/

恢复物品数据

如果你对OTOBO配置，是将物品数据存储在文件系统中，则必须将``article`` 文件夹还原到``/ opt / otobo / var /``或系统配置中指定的文件夹。

root> cd /root/otobo-update
root> cp -pr otobo-prod-old/var/article/* /opt/otobo/var/article/

恢复已经安装的默认统计信息

如果你还有其他带有默认统计信息的软件包，则必须将后缀为``*.installed`` 的XML统计数据文件恢复到/ opt / otobo / var / stats。

root> cd /root/otobo-update/otobo-prod-old/var/stats
root> cp *.installed /opt/otobo/var/stats

设置文件许可

请执行下面的命令设置OTOBO的文件和目录许可。系统会尝试为你检测正确的用户和组。

root> /opt/otobo/bin/otobo.SetPermissions.pl

步骤 4：更新安装软件包

你可以使用下面的命令来更新所有已安装的软件包，这适用于在线存储库中可用的所有软件包。你也可以稍后通过操作系统中的软件包管理器更新其他程序包（这需要运行的OTOBO守护程序）。

root> su - otobo
otobo> /opt/otobo/bin/otobo.Console.pl Admin::Package::ReinstallAll
otobo> /opt/otobo/bin/otobo.Console.pl Admin::Package::UpgradeAll

步骤 5：开始你的服务

现在可以启动服务。这将取决于您的服务配置，下面是一个示例：

root> systemctl start postfix
root> systemctl start apache2
root> systemctl start cron

现在你可以登陆到你的系统。

Updating a Docker-based Installation of OTOBO

For running OTOBO under Docker we need the OTOBO software itself and an environment in which OTOBO can run. The OTOBO Docker image provides the environment and a copy of the OTOBO software. The software itself is installed in the volume otobo_opt_otobo. A named volume is used because run time data, e.g. configuration files and installed packages, is stored in the same directory tree.

When updating to a new version of OTOBO several things have to happen.

The Docker Compose files have to be updated.

更改后的Docker Compose配置可以通过以下方式进行检查。

The new Docker image has to be fetched.

docker volume inspect otobo_opt_otobo 检查一个卷。

Some maintainance tasks must be executed.

Note

In the sample commands below, the version 10.x.y, corresponding to the tag 10_x_y, is used as the example version. Please substitute it with the real version, e.g. 10.0.7.

Warning

只有OTOBO 10.0.4或更高版本支持以下方法。

Updating the Docker Compose files

The OTOBO Docker Compose files can change between releases. Therefore is must be made sure that the correct setup is used.

Note

See https://hub.docker.com/repository/docker/rotheross/otobo/tags for the available releases.

# Change to the otobo docker directory
docker_admin> cd /opt/otobo-docker

# Get the latest tags
docker-admin> git pull --tags

# Update OTOBO docker-compose repository to version 10.x.y.
docker-admin> git checkout rel-10_x_y

Checking the Docker Compose .env file

The file .env controls the OTOBO Docker container. Within that file, the variables OTOBO_IMAGE_OTOBO, OTOBO_IMAGE_OTOBO_ELASTICSEARCH, and OTOBO_IMAGE_OTOBO_NGINX declare which images are used. The latest images are used when these variables are not set. If you want to use a specific version, then please set these variables accordingly.

在Docker情况下

Docker compose can be used for fetching the wanted images from https://hub.docker.com/repository/docker/rotheross/.

# Change to the otobo docker directory
docker_admin> cd /opt/otobo-docker

# fetch the new images, either 'latest' or the specific version declared in .env
docker_admin> docker-compose pull

Update OTOBO

In this step the volume otobo_opt_otobo is updated and the following OTOBO console commands are performed:

Admin::Package::ReinstallAll

Admin::Package::UpgradeAll

Maint::Config::Rebuild

Maint::Cache::Delete

# stop and remove the containers, but keep the named volumes
docker_admin> docker-compose down

# copy the OTOBO software, while containers are still stopped
docker_admin> docker-compose run --no-deps --rm web copy_otobo_next

# start containers again, using the new version and the updated /opt/otobo
docker_admin> docker-compose up --detach

# a quick sanity check
docker_admin> docker-compose ps

# complete the update, with running database
docker_admin> docker-compose exec web /opt/otobo_install/entrypoint.sh do_update_tasks

# inspect the update log
docker_admin> docker-compose exec web cat /opt/otobo/var/log/update.log

Note

The above listed commands can be automated. For that purpose the script scripts/update.sh will be made available in OTOBO 10.0.8. This script runs the commands, starting with the docker-compose pull command.

./scripts/update.sh --help
./scripts/update.sh

备份和恢复

OTOBO有内置的脚本用于备份和恢复，执行脚本时加入``-h``可以看到更详细的信息。

备份

Note

创建一个新的备份，需要用户 ``otobo``具备对目的目录有写的权限。

otobo> /opt/otobo/scripts/backup.pl -h

脚本的输出结果为：

Backup an OTOBO system.

Usage:
 backup.pl -d /data_backup_dir [-c gzip|bzip2] [-r DAYS] [-t fullbackup|nofullbackup|dbonly]
 backup.pl --backup-dir /data_backup_dir [--compress gzip|bzip2] [--remove-old-backups DAYS] [--backup-type fullbackup|nofullbackup|dbonly]

Short options:
 [-h]                   - Display help for this command.
 -d                     - Directory where the backup files should place to.
 [-c]                   - Select the compression method (gzip|bzip2). Default: gzip.
 [-r DAYS]              - Remove backups which are more than DAYS days old.
 [-t]                   - Specify which data will be saved (fullbackup|nofullbackup|dbonly). Default: fullbackup.

Long options:
 [--help]                     - same as -h
 --backup-dir                 - same as -d
 [--compress]                 - same as -c
 [--remove-old-backups DAYS]  - same as -r
 [--backup-type]              - same as -t

Help:
Using -t fullbackup saves the database and the whole OTOBO home directory (except /var/tmp and cache directories).
Using -t nofullbackup saves only the database, /Kernel/Config* and /var directories.
With -t dbonly only the database will be saved.

Override the max allowed packet size:
When backing up a MySQL one might run into very large database fields. In this case the backup fails.
For making the backup succeed one can explicitly add the parameter --max-allowed-packet=<SIZE IN BYTES>.
This setting will be passed on to the command mysqldump.

Output:
 Config.tar.gz          - Backup of /Kernel/Config* configuration files.
 Application.tar.gz     - Backup of application file system (in case of full backup).
 VarDir.tar.gz          - Backup of /var directory (in case of no full backup).
 DataDir.tar.gz         - Backup of article files.
 DatabaseBackup.sql.gz  - Database dump.

恢复

Note

恢复数据库时，请确认数据库``otobo`` 存在并且不包含表单。

otobo> /opt/otobo/scripts/restore.pl -h

脚本的输出结果为：

Restore an OTOBO system from backup.

Usage:
 restore.pl -b /data_backup/<TIME>/ -d /opt/otobo/

Options:
 -b                     - Directory of the backup files.
 -d                     - Target OTOBO home directory.
 [-h]                   - Display help for this command.

在Docker下运行OTOBO的考量

相同的脚本可以用于OTOBO在Docker下的运行，不过要考虑一些Docker特定的限制。

首先我们要确认备份文件创建时所在的文件系统，不是一个容器内部的文件系统。因为在那种情况下，当容器被停止后，所有的数据都会丢失。所以，备份目录必须在一个卷。现在我们先考虑最简单的一种情况，备份目录是Docker主机的一个本地目录。备份目录在容器中的位置可以随意选择。在本例中我们选择本地目录``otobo_backup``作为备份目录在主机的位置， 而在容器中的位置就是``/otobo_backup`` 。

首先我们需要创建卷。

# create the backup directory on the host
docker_admin> mkdir otobo_backup

# create the Docker volume
docker_admin> docker volume create --name otobo_backup --opt type=none --opt device=$PWD/otobo_backup --opt o=bind

# inspect the volume out of curiosity
docker_admin> docker volume inspect otobo_backup

为了创建备份，我们需要一个运行的数据库和卷``otobo_opt_otobo`` 以及 otobo_backup，这意味着网站服务器和Daemon可能，不是必须，被停掉。

# create a backup
docker_admin> docker run -it --rm --volume otobo_opt_otobo:/opt/otobo --volume otobo_backup:/otobo_backup --network otobo_default rotheross/otobo:latest scripts/backup.pl -d /otobo_backup

# check the backup file
docker_admin> tree otobo_backup

为了把备份文件恢复回来，我们需要确认恢复哪个备份文件。占位符``<TIMESTAMP>`` 就如同``2020-09-07_09-38``的标记一样。

# create a backup
docker_admin> docker run -it --rm --volume otobo_opt_otobo:/opt/otobo --volume otobo_backup:/otobo_backup --network otobo_default rotheross/otobo:latest scripts/restore.pl -d /opt/otobo -b /otobo_backup/<TIMESTAMP>

备份和恢复

Please read to the chapter 备份和恢复 for basic information about the backup and restore scripts.

在Docker下运行OTOBO的考量

The standard scripts backup.pl and restore.pl can also be used with OTOBO running under Docker. However some Docker specific limitations have to be considered.

First, we need to make sure that the backup files are not created in the file system that is internal to a Docker container. Because in that case the created files would be lost when the container is stopped. This means that the backup directory must located within in a volume. For this manual we only consider the most simple case, where the backup directory is a local directory on the Docker host. The location of the backup dir in the container can be arbitrarily chosen. In this example we choose the local dir otobo_backup as the location on the host and /otobo_backup as the location in the container.

Secondly, commands in the Docker container usually run as the user otobo with the user id 1000 and the group id 1000. It must be made sure, that this user can write in the backup directory.

首先我们需要创建卷。

# create the backup directory on the host
docker_admin>mkdir otobo_backup

# give the backup dir to the user otobo, elevated privs might be needed for that
docker_admin>chown 1000:1000 otobo_backup

# create the Docker volume
docker_admin>docker volume create --name otobo_backup --opt type=none --opt device=$PWD/otobo_backup --opt o=bind

# inspect the volume out of curiosity
docker_admin>docker volume inspect otobo_backup

For creating the backup we need a running database and the volumes otobo_opt_otobo and otobo_backup. This means that the webserver and the OTOBO daemon may, but don't have to, be stopped.

# create a backup
docker_admin>docker run -it --rm --volume otobo_opt_otobo:/opt/otobo --volume otobo_backup:/otobo_backup --network otobo_default rotheross/otobo:latest scripts/backup.pl -d /otobo_backup

# check the backup file
docker_admin>tree otobo_backup

Note

恢复数据库时，请确认数据库``otobo`` 存在并且不包含表单。

To drop an existing otobo database and create a new one you can use the following commands. First, you have to connect to the MySQL CLI of the db container.

As soon as you are connected to the MySQL server, you can drop and recreate the otobo database.

mysql@4f7783595190:/$>DROP DATABASE otobo;
mysql@4f7783595190:/$>CREATE DATABASE otobo CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
mysql@4f7783595190:/$>GRANT ALL PRIVILEGES ON otobo.* TO 'otobo'@'%';

为了把备份文件恢复回来，我们需要确认恢复哪个备份文件。占位符``<TIMESTAMP>`` 就如同``2020-09-07_09-38``的标记一样。

# restore a backup
docker_admin>docker run -it --rm --volume otobo_opt_otobo:/opt/otobo --volume otobo_backup:/otobo_backup --network otobo_default rotheross/otobo:latest scripts/restore.pl -d /opt/otobo -b /otobo_backup/<TIMESTAMP>

Installing Perl Modules from CPAN

When there are special requirements then the need for additional Perl modules may arise. Fortunately, Perl has an excellent package repository that can satisfy almost all needs. That repository is called CPAN and is available at https://metacpan.org/.

It is recommended to use the command line client cpanm for installing modules. cpanm is often already installed on your system. Please see https://metacpan.org/pod/App::cpanminus for what to do when is isn't already available.

Alternatively, many Perl modules are also available as packages for your operating system. These packages can be installed with your systems regular package manager.

Per default cpanm installs modules into a systemwide location. In this case modules must be installed as the root user. For example, the command

root> cpanm Acme::Dice

结果是：

otobo> perldoc -l Acme::Dice
/usr/local/share/perl/5.30.0/Acme/Dice.pm

Docker-based installations

Special care must be taken when OTOBO runs under Docker. In this case an installation into a systemwide location would initially work as well. However, due to how Docker works, this installed modules would be lost when the container is restarted. Therefore the modules must be installed into a location that does survive a restart. The directory /opt/otobo/local within the volume otobo_opt_otobo can be used for that. Modules that are installed in /opt/otobo/local will be picked up by Perl because the environment variables PERL5LIB and PATH are preset accordingly.

The installed Perl modules will also be available after an upgrade of OTOBO. There is the general rule that files added to /opt/otobo won't be removed by an upgrade.

For installing Perl modules in a specific location we need to modify our install command. Specifically, we need to add the option --local-lib. Here is a sample session in the container web.

# starting a bash session in the container web
docker_admin> cd /opt/otobo-docker/
docker_admin> docker-compose exec web bash
otobo@6ef90ed00cd0:~$ pwd
/opt/otobo

# installing the sample module Acme::Dice
otobo@6ef90ed00cd0:~$ cpanm --local-lib local Acme::Dice
--> Working on Acme::Dice
Fetching http://www.cpan.org/authors/id/B/BO/BOFTX/Acme-Dice-1.01.tar.gz ... OK
Configuring Acme-Dice-1.01 ... OK
Building and testing Acme-Dice-1.01 ... OK
Successfully installed Acme-Dice-1.01
1 distribution installed

# confirm the installation directory
otobo@6ef90ed00cd0:~$ perldoc -l Acme::Dice
/opt/otobo/local/lib/perl5/Acme/Dice.pm

# locally installed module is found because the environment is preset accordingly
otobo@6ef90ed00cd0:~$ echo $PERL5LIB
/opt/otobo_install/local/lib/perl5:/opt/otobo/local/lib/perl5
otobo@6ef90ed00cd0:~$ echo $PATH
/opt/otobo_install/local/bin:/opt/otobo/local/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin

性能调整

有一系列用于OTOBO安装的性能增强技术，包括配置，编码，内存使用等。

工单索引模块

可以通过系统配置``Ticket :: IndexModule''设置工单索引模块，这里有两个后台模块可以为工单队列视图建立索引：

`` Kernel::System::Ticket::IndexAccelerator::RuntimeDB ``

默认选项是从工单列表动态生成队列，这样在你的系统中，未解决的工单数量不超过60,000的情况下，你不会遇到性能问题。

`` Kernel::System::Ticket::IndexAccelerator::StaticDB ``

当你有80,000张以上的工单时，应使用功能更强大的模块，它使用了额外的``ticket_index``表，该表将根据工单数据提取关键字。切换回后台，使用以下命令生成初始索引：

otobo> /opt/otobo/bin/otobo.Console.pl Maint::Ticket::QueueIndexRebuild

工单查询索引

OTOBO使用特殊的搜索索引，对不同通信渠道的文章中的各个字段进行全文搜索。

要创建初始索引，请使用以下命令：

otobo> /opt/otobo/bin/otobo.Console.pl Maint::Ticket::FulltextIndex --rebuild

Note

实际的文章索引是通过OTOBO守护程序在后台进行，虽然刚刚添加到系统中的文章会马上被添加初始索引标记，但可能它们的索引几分钟后才可以使用。

有一些选项可以对搜索索引进行微调：

`` Ticket::SearchIndex::IndexArchivedTickets ``

确认是否将已归档的工单包括在搜索索引中（默认情况下禁用）。建议在拥有已归档工单的大型系统上，索引尽量小。如果启用此选项，将可以通过全文搜索找到已归档的工单。

`` Ticket::SearchIndex::Attribute ``

基础全文字检索设置。

Ticket::SearchIndex::Attribute 设置

Note

运行以下命令以便生成新的索引：

otobo> /opt/otobo/bin/otobo.Console.pl Maint::Ticket::FulltextIndexRebuild

`` WordCountMax ``

定义可以处理建立索引的最大单词数量，例如，文章正文中仅前1000个单词存储在文章搜索索引中。

WordLengthMin and WordLengthMax

字长边界，作为文章搜索索引中上下区间数值，只有在区间数据以内的单词才会存在索引中。

`` Ticket::SearchIndex::Filters ``

Filters based on regular expressions exclude parts of the original text from the full-text index.

Ticket::SearchIndex::Filters 设置

定义了三个默认过滤器：

第一个过滤器会去除特殊字符，例如：，＆<>？ “！* |; []（）+ $ ^ =

第二个过滤器会去除以以下字符之一开头或结尾的单词：'：。

第三个过滤器会去除不包含单词字符的单词：a-z，A-Z，0-9，_

`` Ticket::SearchIndex::StopWords ``

全文索引的英语停用词，这些单词将从搜索索引中删除。

Ticket::SearchIndex::StopWords###en 设置

有些语言定义了所谓的停用词。创建搜索索引时，将跳过这些停用词。

See also

如果您的语言不在系统配置设置中，或者您想添加更多单词，则可以将它们添加到此设置中：

`` Ticket::SearchIndex::StopWords###Custom ``

文档搜索

OTOBO使用Elasticsearch作为其文档搜索，要对Elasticsearch的概念、安装和使用进行介绍，请遵循“入门指南<https://www.elastic.co/guide/zh-cn/elasticsearch/reference/current/getting-started.html>” __ 。

堆尺寸

Elasticsearch用Java编写，可以在任何群集节点上的Java虚拟机（JVM）中运行。这样的JVM使用一部分内存，称为*堆*，其大小可以在配置文件``jvm.options''中进行配置。

默认情况下，堆的最小和最大配置设置为1 GB，可以使用以下选项进行修改：

Xms1g ：最小堆尺寸。

Xmx1g: maximum heap size.

如果``Xms''的值比``Xmx''的值低，那么只要超过当前限制，JVM就会调整已使用堆的大小，直到达到``Xmx''的值为止。这种调整大小会导致服务暂停直到完成为止，这可能会降低搜索或索引操作的速度和反应性。因此，强烈建议将这些配置设置为相等的值。

Warning

如果超过了堆大小的最大值，则相关的群集节点将停止工作，甚至可能关闭服务。

堆最大值设置得越高，Elasticsearch可以使用更多的内存，这也增加了JVM进行垃圾收集的可能暂停。因此建议为``Xmx''设置一个不大于物理内存50％的值。

有关更多信息和有关堆大小的良好经验法则，请遵循`官方文档 <https://www.elastic.co/guide/en/elasticsearch/reference/current/heap-size.html>`__。

磁盘分配

在服务运行期间，Elasticsearch检查可用的磁盘空间，并因此决定是将新的分片分配给相关的群集节点，还是将分片从该特定节点移开。这种行为将由当前磁盘容量控制，并可以在配置文件“ elasticsearch.yml”中进行配置。随附一些重要的配置，这些配置带有较好的默认值，这很重要。

`` cluster.routing.allocation.disk.watermark.low ``

默认值为85％。如果超出此限制，Elasticsearch将不会向相关集群节点分配更多的分片。该节点的操作不会受到影响，并且仍然可以对数据进行索引和搜索。

cluster.routing.allocation.disk.watermark.high

默认值为90％。如果超出此限制，Elasticsearch将尝试将现有分片重新定位到具有足够可用空间的其他节点（如果可能）。

`` cluster.routing.allocation.disk.watermark.flood_stage ``

默认值为95％。如果超出此限制，Elasticsearch将所有索引的配置更新为只读索引块“ index.blocks.read_only_allow_delete”，其中至少一个分片分配给相关的集群节点。从那时起，就不可能将新数据编入此类索引，并且无法进行搜索和删除操作。

After that update, it is no longer possible to index new data to such indices. The indexes are restricted to searches and to delete actions only.

Note

如果超出了洪水阶段，并且某些索引被配置为只读模式，则这种配置*不会*被Elasticsearch自动更改。如果相关磁盘由于手动操作而再次包含足够的可用空间，则需要将配置手动更改回普通模式。

有关磁盘水印和基于磁盘的分片分配的更多信息，请遵循 官方文档。

物品存放

对于电话，电子邮件和内部物品的存储，有两个不同的后端模块。可以在``Ticket :: Article :: Backend :: MIMEBase :: ArticleStorage``中配置使用过的物品存储空间。

`` Kernel::System::Ticket::Article::Backend::MIMEBase::ArticleStorageDB ``

这个默认模块将附件存储在数据库中，还可以与多个前端服务器一起使用，但是需要很多数据库存储空间。

Note

不要将其用于大型系统。

`` Kernel::System::Ticket::Article::Backend::MIMEBase::ArticleStorageFS ``

使用此模块可将附件存储在本地文件系统上。这样速度很快，但是如果你有多个前端服务器，则必须确保文件系统在服务器之间可以共享。可以将其放在NFS共享文件系统，当然最好放在SAN或类似解决方案上。

Note

建议用于大型系统。

您可以即时从一个后端切换到另一个。您可以在系统配置中切换后端，然后运行此命令行实用程序将物品从数据库放到文件系统上，或者以其他方式：

otobo> /opt/otobo/bin/otobo.Console.pl Admin::Article::StorageSwitch --target ArticleStorageFS

您可以使用 --target 选项指定目标后端。

Note

根据您拥有的物品数量、可用的CPU能力和/或网络容量，整个过程可能需要花费大量时间才能运行。

如果要将旧附件保留在数据库中，则可以激活系统配置选项``Ticket :: Article :: Backend :: MIMEBase :: CheckAllStorageBackends``以确保OTOBO仍然可以找到它们。

封存工单

由于OTOBO的数据可用作审查证据，因此删除已关闭的工单可能不是一个好主意，这项功能可让您封存工单。

符合特定条件的故障单可以标记为已存档。这样在你进行常规工单搜索或进行常规话务员工作时，不会访问这些工单。这样系统不再需要处理大量旧工单，而是仅考虑最新的工单，这可以在大型系统上获得巨大的性能提升。

要使用存档功能：

在系统配置中激活 ``Ticket::ArchiveSystem``设置。

定义通用话务员工作：

单击*通用话务员*屏幕中的*添加工作*按钮。

工作配置：为封存工作提供一个名字。

自动化执行：为工作的时间安排选择合适的选项。

选择票证：最好只归档几个月前就已经完成关闭的那些工单。

更新/添加工单属性：将字段*将所选工单存档*设置为*存档工单*。

将工作保存在页面末尾。

单击概述表中的*运行此任务*的链接，查看受到影响的工单。

点击*运行工作*按钮。

Note

手动运行这项工作最多可以修改5000张工单。

搜索工单时，系统默认只搜索未归档的工单。

要搜索已经归档的工单：

打款工单搜索界面。

将*归档搜索*设置为*未归档工单*或者*所有工单*。

进行搜索。

缓存

快速缓存模块在性能方面有很大的帮助，我们建议使用Redis Cache服务器或创建虚拟硬盘。

安装一个 Redis Cache服务器

安装Redis服务器

首先，你需要安装最新的Redis服务器。最简单的方法是在与OTOBO相同的主机上`配置Redis <https://redis.io/topics/quickstart>`__并将其绑定到其默认端口。

安装Redis Perl 模块或者Redis::Fast

你可以选择要使用的Redis模块：Redis`或`Redis :: Fast`（与`Redis`兼容，但**快2倍**）。请使用我们的``otobo.CheckModules.pl --list` 为您选择合适的软件包：

otobo> /opt/otobo/bin/otobo.CheckModules.pl

为Redis进行OTOBO设置

请使用OTOBO`SysConfig`（管理员->系统配置）正确配置OTOBO：

| Setting                       | Description                | Default value  |
| ----------------------------- | -------------------------- | -------------- |
| Cache::Redis###Server         | Redis server URL           | 127.0.0.1:6379 |
| Cache::Redis###DatabaseNumber | Number of logical database | 0              |
| Cache::Redis###RedisFast      | Use or not Redis::Fast     | 0              |
| Cache::Module                 | Activate Redis Cache Module| DB (use Redis) |

虚拟磁盘缓存

OTOBO在/ opt / otobo / var / tmp中缓存了许多临时数据，请确保这里使用的是高性能的文件和存储系统。如果你有足够的RAM，也可以尝试将此目录放在如下所示的虚拟磁盘上：

otobo> /opt/otobo/bin/otobo.Console.pl Maint::Session::DeleteAll
otobo> /opt/otobo/bin/otobo.Console.pl Maint::Cache::Delete
root> mount -o size=16G -t tmpfs none /opt/otobo/var/tmp

Note

在``/ etc / fstab``中添加持久挂载点。

Warning

这不是一个永久性存储，将会在服务器重启时丢失，从而你的所有会话（如果你将它们存储在文件系统中）和缓存数据都会丢失。

集群

对于非常高的生产负载，可能需要在多个前端服务器的群集上运行OTOBO，这项工作很复杂，也有很多陷阱。因此，Rother OSS专门在其 管理OTOBO 环境中为集群应用提供支持。

文档历史

2019 - OTRS安装指南 - OTRS AG (https://otrs.com)

2020 - OTOBO安装教程 - Rother OSS GmbH (https://otobo.de)

由Rother OSS GmbH出版，地址：德国莱布芬市 Oberwalting 31, 94339。作者：OTRS AG (original version)，Rother OSS GmbH (https://rother-oss.com)

在GNU免费文档许可条款（版本1.3或之后由自由软件基金会发布更新版）的要求下，没有不变动的章节，没有前后封面文字。授权文件可以在`GNU网站：<https://www.gnu.org/licenses/fdl-1.3.txt>`上找到。

Index