系统管理指南

DHIS core version 2.34

DHIS2 Documentation Team

Copyright © 2008-2021 DHIS2 Team

最后更新: 2021-09-07

Warranty: THIS DOCUMENT IS PROVIDED BY THE AUTHORS ‘’AS IS’’ AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS MANUAL AND PRODUCTS MENTIONED HEREIN, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

License: Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the source of this documentation, and is available here online: http://www.gnu.org/licenses/fdl.html

目录

安装

安装章节提供了有关如何在以下位置安装DHIS2的信息 各种环境,包括在线中央服务器,离线本地 网络,独立应用程序和称为DHIS2的自包含程序包 生活。

介绍

DHIS2在存在Java Runtime Environment版本8或更高版本的所有平台上运行,其中包括最流行的操作系统,例如Windows,Linux和Mac。 DHIS2在PostgreSQL数据库系统上运行。 DHIS2打包为标准Java Web存档(WAR文件),因此可以在任何Servlet容器例如Tomcat和Jetty上运行。

DHIS2团队建议使用Ubuntu 16.04 LTS操作系统PostgreSQL 数据库系统和Tomcat Servlet容器为首选 服务器安装的环境。

本章提供了设置上述技术堆栈的指南。 但是,应将其作为起步和运行的指南,而不是 作为上述环境的详尽文档。我们提到 到官方的Ubuntu,PostgreSQL和Tomcat文档进行深入了解 阅读。

dhis2-tools Ubuntu软件包可自动执行以下内容中所述的许多任务 以下指南,推荐给大多数用户,尤其是那些 不熟悉命令行或服务器管理。它 在本指南的单独章节中进行了详细说明。

服务器规格

DHIS2是数据库密集型应用程序,需要您的服务器 具有适当数量的RAM,CPU核心数量和快速磁盘。 这些建议应被视为经验法则,而不是 确切的措施。 DHIS2在RAM的数量和数量上线性扩展 CPU内核,因此您负担得起的费用越多,应用程序的性能就会越好。

  • RAM: At least 1 GB memory per 1 million captured data records per month or per 1000 concurrent users. At least 4 GB for a small instance, 12 GB for a medium instance.

  • CPU cores: 4 CPU cores for a small instance, 8 CPU cores for a medium or large instance.

  • Disk: Ideally use an SSD. Otherwise use a 7200 rpm disk. Minimum read speed is 150 Mb/s, 200 Mb/s is good, 350 Mb/s or better is ideal. In terms of disk space, at least 60 GB is recommended, but will depend entirely on the amount of data which is contained in the data value tables. Analytics tables require a significant amount of disk space. Plan ahead and ensure that your server can be upgraded with more disk space as it becomes needed.

软件需求

更高版本的DHIS2需要以下软件版本才能运行。

  • Java JDK或JRE版本8或更高版本。

  • 存在Java JDK或JRE版本8的任何操作系统。

  • PostgreSQL数据库9.6或更高版本。

  • PostGIS数据库扩展版本2.2或更高版本。

  • Tomcat servlet container version 8.5.50 or later, or other Servlet API 3.1 compliant servlet containers.

服务器设置

本节介绍如何在Ubuntu 16.04 64位系统上以PostgreSQL为数据库系统,以Tomcat为Servlet容器设置DHIS2的服务器实例。该指南本身并不是逐步指南,而是作为DHIS2如何在服务器上部署的参考。有许多可能的部署策略,具体取决于所使用的操作系统和数据库以及其他因素。term invoke refers是指在终端中执行给定命令。

对于国家级服务器,建议的配置为四核2 Ghz 处理器或更高以及12 Gb RAM或更高。注意64位 要使用超过4 Gb的RAM,需要操作系统。

对于本指南,我们假设为PostgreSQL分配了8 Gb RAM,为Tomcat / JVM分配了8 GB RAM,并且使用了64位操作系统。 if 如果您正在运行其他配置,请相应地调整建议的值\! 我们建议在数据库和JVM之间大致平均分配可用内存。请记住,将一些物理内存留给操作系统来执行其任务,例如大约2 GB。标记为 optional 的步骤如性能调整步骤可以在以后的阶段进行。

创建一个用户来运行DHIS2

您应该创建一个专用用户来运行DHIS2。

重要

您不应以root用户等特权用户身份运行DHIS2服务器。

通过调用以下命令创建一个名为dhis的新用户:

sudo useradd -d / home / dhis -m dhis -s / bin / false

然后为您的帐户调用设置密码:

须藤密码

确保设置了一个安全密码,该密码至少包含15个随机字符。

创建配置目录

首先为DHIS2配置创建合适的目录 文件。此目录还将用于应用程序,文件和日志文件。 示例目录可以是:

mkdir / home / dhis / config
chown dhis:dhis / home / dhis / config

DHIS2 will look for an environment variable called DHIS2_HOME to locate the DHIS2 configuration directory. This directory will be referred to as DHIS2_HOME in this installation guide. We will define the environment variable in a later step in the installation process.

设置服务器时区和语言环境

可能需要重新配置服务器的时区以匹配 DHIS2服务器将覆盖的位置的时区。 如果您使用的是虚拟专用服务器,则默认时区可能不会 对应于您的DHIS2位置的时区。您可以轻松地 通过调用以下内容并按照以下说明重新配置时区 说明。

sudo dpkg-重新配置tzdata

PostgreSQL对语言环境敏感,因此您可能必须安装 地区优先。要检查现有的语言环境并安装新的语言环境(例如 挪威):

语言环境-a
须藤locale-gen nb_NO.UTF-8

PostgreSQL安装

通过以下方式安装PostgreSQL 调用:

sudo apt-get install postgresql-10 postgresql-contrib-10 postgresql-10-postgis-2.4

Create a non-privileged user called dhis by invoking:

须藤-u postgres createuser -SDRP dhis

在提示符下输入安全密码。通过调用创建数据库:

须藤-u postgres createdb -O dhis dhis2

通过调用exit 返回会话,您现在有一个名为_dhis_的PostgreSQL用户和一个名为_dhis2_的数据库。

The PostGIS extension is needed for several GIS/mapping features to work. DHIS 2 will attempt to install the PostGIS extension during startup. If the DHIS 2 database user does not have permission to create extensions you can create it from the console using the postgres user with the following commands:

sudo -u postgres psql -c“创建扩展名postgis;” dhis2

Exit the console and return to your previous user with \q followed by exit.

PostgreSQL性能调优

Tuning PostgreSQL is necessary to achieve a high-performing system but is optional in terms of getting DHIS2 to run. PostgreSQL is configured and tuned through the postgresql.conf file which can be edited like this:

须藤nano /etc/postgresql/10/main/postgresql.conf

并设置以下属性:

max_connections = 200

确定PostgreSQL允许的最大连接数。

shared_buffers = 3200MB

确定应专门分配多少内存 PostgreSQL缓存。此设置控制共享内核的大小 应该为PostgreSQL保留的内存。应该设置为 PostgreSQL专用内存的40%。

work_mem = 20MB

确定用于内部排序和哈希的内存量 操作。此设置是针对每个连接,针对每个查询的,因此需要大量内存 如果将其提高得太高,可能会被消耗掉。正确设置该值 对于DHIS2聚合性能至关重要。

maintenance_work_mem = 512MB

确定PostgreSQL可用于维护的内存量 创建索引,运行真空,添加外部文件等操作 键。增大此值可能会提高索引创建的性能 在分析生成过程中。

Effective_cache_size = 8000MB

An estimate of how much memory is available for disk caching by the operating system (not an allocation) and isdb.no used by PostgreSQL to determine whether a query plan will fit into memory or not. Setting it to a higher value than what is really available will result in poor performance. This value should be inclusive of the shared_buffers setting. PostgreSQL has two layers of caching: The first layer uses the kernel shared memory and is controlled by the shared_buffers setting. PostgreSQL delegates the second layer to the operating system disk cache and the size of available memory can be given with the effective_cache_size setting.

checkpoint_completion_target = 0.8

设置WAL写过程中用于缓冲的内存。 增大此值可能会提高大量写入系统的吞吐量。

sync_commit =关

指定事务提交是否将等待WAL记录 是否将其写入磁盘,然后再返回客户端。设定这个 关闭将大大提高性能。这也意味着那里 交易之间的轻微延迟被报告为成功 客户端,它实际上是安全的,但是数据库状态不能为 已损坏,这是性能密集型和 像DHIS2这样的重写入系统。

wal_writer_delay = 10000毫秒

指定WAL写操作之间的延迟。将此设置为较高 价值可能会提高大量写入系统的性能,因为 一次刷新到磁盘就可以执行许多写操作。

random_page_cost = 1.1

SSD only. Sets the query planner's estimate of the cost of a non-sequentially-fetched disk page. A low value will cause the system to prefer index scans over sequential scans. A low value makes sense for databases running on SSDs or being heavily cached in memory. The default value is 4.0 which is reasonable for traditional disks.

max_locks_per_transaction = 96

指定为每个事务分配的对象锁的平均数量。设置该参数主要是为了允许完成涉及大量表的升级例程。

通过调用以下命令来重新启动PostgreSQL:

sudo /etc/init.d/postgresql重新启动

系统配置

The database connection information is provided to DHIS2 through a configuration file called dhis.conf. Create this file and save it in the DHIS2_HOME directory. As an example this location could be:

/home/dhis/config/dhis.conf

与上述设置相对应的PostgreSQL配置文件具有 这些属性:

#------------------------------------------------- ---------------------
#数据库连接
#------------------------------------------------- ---------------------

#JDBC驱动程序类
connection.driver_class = org.postgresql.Driver

#数据库连接URL
connection.url = jdbc:postgresql:dhis2

#数据库用户名
connection.username = dhis

#数据库密码
connection.password = xxxx

#------------------------------------------------- ---------------------
#服务器
#------------------------------------------------- ---------------------

#如果部署在HTTPS上则启用安全设置,默认设置为“关”,可以设置为“开”
服务器.https =开启

#服务器基本URL
server.base.url = https://server.com/

It is strongly recommended to enable the server.https setting and deploying DHIS 2 over the encrypted HTTPS protocol. This setting will enable e.g. secure cookies. HTTPS deployment is required when this setting is enabled.

server.base.url设置是指最终用户通过网络访问系统的URL。

请注意,配置文件支持环境变量。这意味着您可以将某些属性设置为环境变量,并解析它们,例如像这样,其中DB \ _PASSWD是环境变量的名称:

connection.password = $ {DB_PASSWD}

Note that this file contains the password for your DHIS2 database in clear text so it needs to be protected from unauthorized access. To do this, invoke the following command which ensures that only the dhis user which owns the file is allowed to read it:

chmod 0600 dhis.conf

Java安装

推荐用于DHIS 2的Java JDK是OpenJDK 8。 GPL许可,可以免费运行。您可以使用 以下命令:

须藤apt-get install openjdk-8-jdk

通过调用以下命令来验证安装是否正确:

Java版本

Tomcat和DHIS2安装

要安装Tomcat Servlet容器,我们将利用Tomcat用户 通过调用打包:

须藤apt-get install tomcat8-user

This package lets us easily create a new Tomcat instance. The instance will be created in the current directory. An appropriate location is the home directory of the dhis user:

cd / home / dhis /
须藤tomcat8-instance-create tomcat-dhis
须藤chown -R dhis:dhis tomcat-dhis /

This will create an instance in a directory called tomcat-dhis. Note that the tomcat7-user package allows for creating any number of dhis instances if that is desired.

Next edit the file tomcat-dhis/bin/setenv.sh and add the lines below. The first line will set the location of your Java Runtime Environment, the second will dedicate memory to Tomcat and the third will set the location for where DHIS2 will search for the dhis.conf configuration file. Please check that the path the Java binaries are correct as they might vary from system to system, e.g. on AMD systems you might see /java-8-openjdk-amd64 Note that you should adjust this to your environment:

导出JAVA_HOME ='/ usr / lib / jvm / java-1.8.0-openjdk-amd64 /'
出口JAVA_OPTS ='-Xmx7500m -Xms4000m'
导出DHIS2_HOME ='/ home / dhis / config'

The Tomcat configuration file is located in tomcat-dhis/conf/server.xml. The element which defines the connection to DHIS is the Connector element with port 8080. You can change the port number in the Connector element to a desired port if necessary. The relaxedQueryChars attribute is necessary to allow certain characters in URLs used by the DHIS2 front-end.

<Connector port="8080" protocol="HTTP/1.1"
  connectionTimeout="20000"
  redirectPort="8443"
  relaxedQueryChars="[]" />

下一步是下载DHIS2 WAR文件并将其放入 Tomcat的webapps目录。您可以下载DHIS2版本2.31 WAR 这样发布(如果您的首选版本替换2.31, 必要):

wget https://releases.dhis2.org/2.33/dhis.war

或者,对于补丁程序版本,文件夹结构基于补丁程序 主发行版下子文件夹中的发行版ID。例如。你可以下载 像这样的DHIS2版本2.31.1 WAR版本(用您的 首选版本,以及带有首选补丁的2.31.1(如有必要):

wget https://releases.dhis2.org/2.33/2.33.1/dhis.war

将WAR文件移到Tomcat webapps目录中。我们想称呼 WAR文件ROOT.war,以使其直接在本地主机上可用 没有上下文路径:

mv dhis.war tomcat-dhis / webapps / ROOT.war

DHIS2绝对不能以特权用户身份运行。修改后 setenv.sh文件,修改启动脚本以检查并验证 脚本尚未以root身份调用。

#!/ bin / sh
设置-e

如果[“ $(id -u)” -eq“ 0”];然后
  回声“此脚本不能以root用户身份运行” 1>&2
  1号出口
科幻

导出CATALINA_BASE =“ / home / dhis / tomcat-dhis”
/usr/share/tomcat8/bin/startup.sh
回显“ Tomcat启动”

运行DHIS2

DHIS2现在可以通过调用来启动:

须藤-u dhis tomcat-dhis / bin / startup.sh

重要

绝对不要以root或其他特权用户身份运行DHIS2服务器。

DHIS2可以通过调用来停止:

须藤-u dhis tomcat-dhis / bin / shutdown.sh

要监视Tomcat的行为,日志是该日志的主要来源 信息。可以使用以下命令查看日志:

尾巴-f tomcat-dhis / logs / catalina.out

假设WAR文件名为ROOT.war,您现在可以访问 DHIS2实例位于以下URL:

http://localhost:8080

文件存储配置

DHIS2 is capable of capturing and storing files. By default, files will be stored on the local file system of the server which runs DHIS2 in a files directory under the DHIS2_HOME external directory location.

You can also configure DHIS2 to store files on cloud-based storage providers. AWS S3 is the only supported provider currently. To enable cloud-based storage you must define the following additional properties in your dhis.conf file:

#文件存储提供者。当前支持“文件系统”和“ aws-s3”。
filestore.provider ='aws-s3'

#本地文件系统上外部目录中的目录,AWS S3上存储桶
filestore.container =文件

#以下配置仅适用于云存储(AWS S3)

#数据中心位置。可选,但出于性能原因建议使用。
filestore.location = eu-west-1

#AWS S3上的用户名/访问密钥
filestore.identity = xxxx

#AWS S3上的密码/密钥(敏感)
filestore.secret = xxxx

This configuration is an example reflecting the defaults and should be changed to fit your needs. In other words, you can omit it entirely if you plan to use the default values. If you want to use an external provider the last block of properties needs to be defined, as well as the provider property is set to a supported provider (currently only AWS S3).

Note

If you’ve configured cloud storage in dhis.conf, all files you upload or the files the system generates will use cloud storage.

对于生产系统,文件存储的初始设置应为 被仔细考虑为在存储提供商之间移动文件,而 保持数据库引用的完整性可能很复杂。保持 请记住,文件存储的内容可能包含敏感内容, 以及完整的信息,并保护对文件夹以及 建议在生产中确保备份计划到位 实施。

Note

AWS S3 is the only supported provider but more providers are likely to be added in the future, such as Google Cloud Store and Azure Blob Storage. Let us know if you have a use case for additional providers.

Google服务帐户配置

DHIS2可以连接到各种Google服务API。例如, DHIS2 GIS组件可以利用Google Earth Engine API加载地图 层。为了提供API访问令牌,您必须设置一个Google 服务帐户并创建私钥:

  • Create a Google service account. Please consult the Google identify platform documentation.

  • Visit the Google cloud console and go to API Manager > Credentials > Create credentials > Service account key. Select your service account and JSON as key type and click Create.

  • Rename the JSON key to dhis-google-auth.json.

After downloading the key file, put the dhis-google-auth.json file in the DHIS2_HOME directory (the same location as the dhis.conf file). As an example this location could be:

/home/dhis/config/dhis-google-auth.json

LDAP配置

DHIS2能够使用LDAP服务器进行用户身份验证。 对于LDAP身份验证,要求在 每个LDAP条目的DHIS2数据库。 DHIS2用户将用于代表 权限/用户角色。

要设置LDAP身份验证,您需要配置LDAP服务器URL, 管理员用户以及LDAP搜索库和搜索过滤器。这个 配置应在主DHIS 2配置文件中完成 (dhis.conf)。 LDAP用户或条目通过区分来标识 名称(此后为DN)。一个示例配置如下所示:

#LDAP服务器网址
ldap.url = ldaps://domain.org:636

#LDAP管理器条目专有名称
ldap.manager.dn = cn = johndoe,dc = domain,dc = org

#LDAP管理员输入密码
ldap.manager.password = xxxx

#LDAP基本搜索
ldap.search.base = dc = domain,dc = org

#LDAP搜索过滤器
ldap.search.filter =(cn = {0})

LDAP配置属性说明如下:

  • ldap.url: The URL of the LDAP server for which to authenticate against. Using SSL/encryption is strongly recommended in order to make authentication secure. As example URL is ldaps://domain.org:636, where ldaps refers to the protocol, domain.org refers to the domain name or IP address, and 636 refers to the port (636 is default for LDAPS).

  • ldap.manager.dn: An LDAP manager user is required for binding to the LDAP server for the user authentication process. This property refers to the DN of that entry. I.e. this is not the user which will be authenticated when logging into DHIS2, rather the user which binds to the LDAP server in order to do the authentication.

  • ldap.manager.password: The password for the LDAP manager user.

  • ldap.search.base: The search base, or the distinguished name of the search base object, which defines the location in the directory from which the LDAP search begins.

  • ldap.search.filter: The filter for matching DNs of entries in the LDAP directory. The {0} variable will be substituted by the DHIS2 username, or alternatively, the LDAP identifier defined for the user with the supplied username.

DHIS2将使用提供的用户名/密码并尝试进行身份验证 针对LDAP服务器条目,然后从中查找用户角色/权限 相应的DHIS2用户。这意味着用户必须具有 LDAP目录中的匹配条目以及DHIS2用户,以便 登录。

在身份验证期间,DHIS2将尝试使用以下方式绑定到LDAP服务器: 配置的LDAP服务器URL以及管理员DN和密码。一旦 绑定完成后,它将使用以下命令在目录中搜索条目 配置的LDAP搜索库和搜索过滤器。

配置的过滤器中的{0}变量将在替换之前 应用过滤器。默认情况下,它将被提供的 用户名。您还可以在相关的 DHIS2用户帐户。可以通过DHIS2用户模块用户来完成 通过设置“ LDAP标识符”,在添加或编辑屏幕中找到界面 属性。设置后,LDAP标识符将替换为{0} 过滤器中的变量。 LDAP通用名称时,此功能很有用 不适合或由于某种原因不能用作DHIS2用户名。

加密配置

DHIS2 allows for encryption of data. This however requires some extra setup. To provide security to the encryption algorithm you will have to set a password in the dhis.conf configuration file through the encryption.password property:

加密密码= xxxx

The encryption.password property is the password used when encrypting and decrypting data in the database. Note that the password must not be changed once it has been set and data has been encrypted as the data can then no longer be decrypted.

密码必须至少为** 24个字符长**。混合数字 推荐使用大小写字母。加密密码 必须保密。

Important

A word of caution: It is not possible to recover encrypted data if the encryption password is lost or changed. If the password is lost, so is the encrypted data.Conversely, the encryption provides no security if the password is compromised. Hence, great consideration should be given to storing the password in a safe place.

读取副本数据库配置

DHIS 2允许利用主数据库的只读副本 (主DHIS 2数据库)。只读副本的目的是为了增强 数据库读取查询的性能并扩展容量 超越了单个数据库的限制。大量读取操作,例如 因为分析和事件查询将从中受益。

该配置要求您已创建主DHIS 2数据库的一个或多个复制实例。 PostgreSQL通过称为_流复制_ 的概念来实现这一点。本指南未涵盖为PostgreSQL配置只读副本。

Read replicas can be defined in the dhis.conf configuration file. You can specify up to 5 read replicas per DHIS 2 instance. Each read replica is denoted with a number between 1 and 5. The JDBC connection URL must be defined per replica. The username and password can be specified; if not, the username and password for the master database will be used instead.

The configuration for read replicas in dhis.conf looks like the below. Each replica is specified with the configuration key readN prefix, where N refers to the replica number.

#读取副本1的配置

#数据库连接URL,用户名和密码
read1.connection.url = jdbc:postgresql://127.0.0.11/dbread1
read1.connection.username = dhis
read1.connection.password = xxxx

#读取副本2的配置

#数据库连接URL,用户名和密码
read2.connection.url = jdbc:postgresql://127.0.0.12/dbread2
read2.connection.username = dhis
read2.connection.password = xxxx

#读取副本3的配置

#数据库连接URL,后退到主用户名和密码
read3.connection.url = jdbc:postgresql://127.0.0.13/dbread3

请注意,您必须重新启动servlet容器才能更改 生效。 DHIS 2将自动在 读取副本。副本的顺序没有任何意义。

Web服务器群集配置

本节介绍如何设置DHIS 2应用程序以在 簇。

群集概述

群集是提高系统可伸缩性和可用性的常用技术。群集是指设置多个Web服务器,例如Tomcat实例,并使它们为单个应用程序提供服务。从可以添加新服务器以提高性能的意义上讲,群集允许_scaling out_ 应用程序。它还允许_高可用性_,因为系统可以容忍发生故障的实例,而不会导致用户无法访问系统。

有一些方面需要配置才能运行DHIS 2 在集群中。

  • Each DHIS 2 instance must specify the other DHIS 2 instance members of the cluster in dhis.conf.

  • A Redis data store must be installed and connection information must be provided for each DHIS 2 application instance in dhis.conf.

  • DHIS 2 实例和服务器必须通过 AWS S3 云文件存储_选项或共享网络驱动器共享用于应用程序和文件上传的相同 _files 文件夹。

  • A load balancer such as nginx must be configured to distribute Web requests across the cluster instances.

DHIS 2实例群集配置

设置多个Tomcat实例时,需要进行 实例彼此了解。这种认识将使DHIS 2能够保持 本地数据(休眠)同步并处于一致状态。 在一个实例上完成更新后,在另一个实例上缓存 必须通知实例,以便实例可以无效并避免 变得陈旧。

A DHIS 2 cluster setup is based on manual configuration of each instance. For each DHIS 2 instance one must specify the public hostname as well as the hostnames of the other instances participating in the cluster.

The hostname of the server is specified using the cluster.hostname configuration property. Additional servers which participate in the cluster are specified using the cluster.members configuration property. The property expects a list of comma separated values where each value is of the format host:port.

主机名必须对网络上的参与服务器可见 为集群工作。您可能需要允许传入和 防火墙中配置的端口号上的传出连接。

The port number of the server is specified using the cluster.cache.port configuration property. The remote object port used for registry receive calls is specified using cluster.cache.remote.object.port. Specifying the port numbers is typically only useful when you have multiple cluster instances on the same server or if you need to explicitly specify the ports to match a firewall configuration. When running cluster instances on separate servers it is often appropriate to use the default port number and omit the ports configuration properties. If omitted, 4001 will be assigned as the listener port and a random free port will be assigned as the remote object port.

An example setup for a cluster of two web servers is described below. For server A available at hostname 193.157.199.131 the following can be specified in dhis.conf:

#服务器A的集群配置

#此Web服务器的主机名
cluster.hostname = 193.157.199.131

#缓存侦听器的端口,可以省略
cluster.cache.port = 4001
cluster.cache.remote.object.port = 5001

#参与集群的Host:port列表
cluster.members = 193.157.199.132:4001

For server B available at hostname 193.157.199.132 the following can be specified in dhis.conf (notice how port configuration is omitted):

#服务器B的集群配置

#此Web服务器的主机名
cluster.hostname = 193.157.199.132

#参与集群的服务器列表
cluster.members = 193.157.199.131:4001

您必须重新启动每个Tomcat实例,以使更改生效。 现在已使两个实例相互了解,DHIS 2将 确保其缓存保持同步。

Redis共享数据存储集群配置

In a cluster setup, a Redis instance is required and will handle shared user sessions, application cache and cluster node leadership.

For optimum performance, Redis Keyspace events for generic commands and expired events need to be enabled in the Redis Server. If you are using a cloud platform-managed Redis server (like AWS ElastiCache for Redis or Azure Cache for Redis) you will have to enable keyspace event notifications using the respective cloud console interfaces. If you are setting up a standalone Redis server, enabling keyspace event notifications can be done in the redis.conf file by adding or uncommenting the following line:

notify-keyspace-events Egx

DHIS2 will connect to Redis if the redis.enabled configuration property in dhis.conf is set to true along with the following properties:

  • redis.host: Specifies where the redis server is running. Defaults to localhost. Mandatory.

  • redis.port: Specifies the port in which the redis server is listening. Defaults to 6379. Optional.

  • redis.password: Specifies the authentication password. If a password is not required it can be left blank.

  • redis.use.ssl: Specifies whether the Redis server has SSL enabled. Defaults to false. Optional. Defaults to false.

When Redis is enabled, DHIS2 will automatically assign one of the running instances as the leader of the cluster. The leader instance will be used to execute jobs or scheduled tasks that should be run exclusively by one instance. Optionally you can configure the leader.time.to.live.minutes property in dhis.conf to set up how frequently the leader election needs to occur. It also gives an indication of how long it would take for another instance to take over as the leader after the previous leader has become unavailable. The default value is 2 minutes. Note that assigning a leader in the cluster is only done if Redis is enabled. An example snippet of the dhis.conf configuration file with Redis enabled and leader election time configured is shown below.

#Redis配置

redis.enabled = true

redis.host = 193.158.100.111

redis.port = 6379

redis.password = <your password>

redis.use.ssl = false

#可选,默认为2分钟
Leader.time.to.live.minutes = 4

文件文件夹配置

DHIS 2将在应用程序本身之外存储几种类型的文件, 例如应用程序,保存在数据输入中的文件和用户头像。部署时 在群集中,这些文件的位置必须在所有实例之间共享。 在本地文件系统上,位置为:

{DHIS2_HOME} /文件

在这里,DHIS2_HOME是指DHIS 2环境变量所指定的DHIS 2配置文件的位置,而files是紧随其后的文件夹。

有两种方法可以实现共享位置:

  • Use the AWS S3 cloud filestorage option. Files will be stored in an S3 bucket which is automatically shared by all DHIS 2 instances in the cluster. See the File store configuration section for guidance.
  • 设置一个共享文件夹,该共享文件夹在群集中的所有DHIS 2实例和服务器之间共享。在Linux上,这可以通过 NFS(网络文件系统)来实现,它是一种分布式文件系统协议。请注意,只能共享DHIS2_HOME下的文件子文件夹,而不是父文件夹。

负载均衡器配置

With a cluster of Tomcat instances set up, a common approach for routing incoming web requests to the backend instances participating in the cluster is using a load balancer. A load balancer will make sure that load is distributed evenly across the cluster instances. It will also detect whether an instance becomes unavailable, and if so, stop routine requests to that instance and instead use other available instances.

Load balancing can be achieved in multiple ways. A simple approach is using nginx, in which case you will define an upstream element which enumerates the location of the backend instances and later use that element in the proxy location block.

http {

  # Upstream element with sticky sessions

  upstream dhis_cluster {
    ip_hash;
    server 193.157.199.131:8080;
    server 193.157.199.132:8080;
  }

  # Proxy pass to backend servers in cluster

  server {
    listen 80;

    location / {
      proxy_pass   http://dhis_cluster/;
    }
  }
}

DHIS 2 keeps server-side state for user sessions to a limited degree. Using "sticky sessions" is a simple approach to avoid replicating the server session state by routing requests from the same client to the same server. The ip_hash directive in the upstream element ensures this.

请注意,为简洁起见,已省略了几条说明 上面的例子。请查阅反向代理部分以获取详细指南。

Analytics缓存配置

DHIS 2支持用于所有分析Web应用程序的分析API响应的服务器端缓存。该缓存位于DHIS 2应用程序内,因此受到DHIS 2身份验证和安全层的保护。您可以配置以秒为单位的缓存条目的到期时间。要启用缓存,您可以在dhis.conf中定义analytics.cache.expiration属性。下面的示例启用了缓存并将过期设置为一小时。

analytics.cache.expiration = 3600

监控

DHIS 2可以导出Prometheus兼容的度量标准以监视DHIS2实例。 DHIS2监视基础结构旨在公开与应用程序运行时相关的指标以及其他与应用程序相关的信息。

与基础架构相关的指标(例如主机指标,Tomcat或Postgres)不会直接由应用程序监视引擎公开,因此必须分别收集它们。该应用程序当前公开的指标是:

  • DHIS 2 API(响应时间,调用次数等)
  • JVM(堆大小,垃圾回收等)
  • 休眠(查询,缓存等)
  • C3P0数据库池
  • 应用正常运行时间
  • 中央处理器

可以使用以下属性在dhis.conf中启用监视(所有属性默认为off):

monitoring.api.enabled =开
monitoring.jvm.enabled =开
monitoring.dbpool.enabled =开
monitoring.hibernate.enabled =关
monitoring.uptime.enabled =开
monitoring.cpu.enabled =开

推荐使用Prometheus和Grafana收集和可视化这些指标的方法。有关更多信息,请参见[监控基础结构](https://github.com/dhis2/wow-backend/blob/master/guides/monitoring.md)页面和[Prometheus and Grafana安装](https:// docs .dhis2.org / master / en / dhis2_system_administration_guide / monitoring.html)一章。

反向代理配置

反向代理是代表服务器运行的代理服务器。使用 反向代理与Servlet容器结合使用是可选的,但 有很多优点:

  • Requests can be mapped and passed on to multiple servlet containers. This improves flexibility and makes it easier to run multiple instances of DHIS2 on the same server. It also makes it possible to change the internal server setup without affecting clients.

  • The DHIS2 application can be run as a non-root user on a port different than 80 which reduces the consequences of session hijacking.

  • The reverse proxy can act as a single SSL server and be configured to inspect requests for malicious content, log requests and responses and provide non-sensitive error messages which will improve security.

基本的Nginx设置

由于以下原因,我们建议使用[nginx](http://www.nginx.org)作为反向代理 其低内存占用和易用性。要安装,请调用 以下:

须藤apt-get install nginx

现在可以使用以下命令启动,重新加载和停止nginx 命令:

sudo /etc/init.d/nginx开始
须藤/etc/init.d/nginx重新加载
sudo /etc/init.d/nginx停止

Now that we have installed nginx we will now continue to configure regular proxying of requests to our Tomcat instance, which we assume runs at http://localhost:8080. To configure nginx you can open the configuration file by invoking:

须藤nano /etc/nginx/nginx.conf

nginx配置围绕代表以下内容的块层次结构构建 http,服务器和位置,其中每个块都从父级继承设置 块。以下代码段将nginx配置为通过代理 (重定向)来自端口80的请求(该端口是nginx监听的端口 默认情况下)到我们的Tomcat实例。包括以下配置 在nginx.conf中:

http {
  gzip on; # Enables compression, incl Web API content-types
  gzip_types
    "application/json;charset=utf-8" application/json
    "application/javascript;charset=utf-8" application/javascript text/javascript
    "application/xml;charset=utf-8" application/xml text/xml
    "text/css;charset=utf-8" text/css
    "text/plain;charset=utf-8" text/plain;

  server {
    listen               80;
    client_max_body_size 10M;

    # Proxy pass to servlet container

    location / {
      proxy_pass                http://localhost:8080/;
      proxy_redirect            off;
      proxy_set_header          Host               $host;
      proxy_set_header          X-Real-IP          $remote_addr;
      proxy_set_header          X-Forwarded-For    $proxy_add_x_forwarded_for;
      proxy_set_header          X-Forwarded-Proto  http;
      proxy_buffer_size         128k;
      proxy_buffers             8 128k;
      proxy_busy_buffers_size   256k;
      proxy_cookie_path         ~*^/(.*) "/$1; SameSite=Lax";
    }
  }
}

You can now access your DHIS2 instance at http://localhost. Since the reverse proxy has been set up we can improve security by making Tomcat only listen for local connections. In /conf/server.xml you can add an address attribute with the value localhost to the Connector element for HTTP 1.1 like this:

<Connector address="localhost" protocol="HTTP/1.1" />

使用nginx {#install_enabling_ssl_on_nginx}启用SSL

In order to improve security it is recommended to configure the server running DHIS2 to communicate with clients over an encrypted connection and to identify itself to clients using a trusted certificate. This can be achieved through SSL which is a cryptographic communication protocol running on top of TCP/IP. First, install the required openssl library:

须藤apt-get install openssl

To configure nginx to use SSL you will need a proper SSL certificate from an SSL provider. The cost of a certificate varies a lot depending on encryption strength. An affordable certificate from Rapid SSL Online should serve most purposes. To generate the CSR (certificate signing request) you can invoke the command below. When you are prompted for the Common Name, enter the fully qualified domain name for the site you are securing.

openssl req -new -newkey rsa:2048 -nodes -keyout server.key -out server.csr

收到证书文件(.pem或.crt)后,您将 需要将其与生成的server.key文件放在一起 nginx可以到达的位置。一个好的位置可以是 与您的nginx.conf文件所在的目录相同。

Below is an nginx server block where the certificate files are named server.crt and server.key. Since SSL connections usually occur on port 443 (HTTPS) we pass requests on that port (443) on to the DHIS2 instance running on http://localhost:8080 The first server block will rewrite all requests connecting to port 80 and force the use of HTTPS/SSL. This is also necessary because DHIS2 is using a lot of redirects internally which must be passed on to use HTTPS. Remember to replace \<server-ip> with the IP of your server. These blocks should replace the one from the previous section.

http {
  gzip on; # Enables compression, incl Web API content-types
  gzip_types
    "application/json;charset=utf-8" application/json
    "application/javascript;charset=utf-8" application/javascript text/javascript
    "application/xml;charset=utf-8" application/xml text/xml
    "text/css;charset=utf-8" text/css
    "text/plain;charset=utf-8" text/plain;

  # HTTP server - rewrite to force use of SSL

  server {
    listen     80;
    rewrite    ^ https://<server-url>$request_uri? permanent;
  }

  # HTTPS server

  server {
    listen               443 ssl;
    client_max_body_size 10M;

    ssl                  on;
    ssl_certificate      server.crt;
    ssl_certificate_key  server.key;

    ssl_session_cache    shared:SSL:20m;
    ssl_session_timeout  10m;

    ssl_protocols              TLSv1 TLSv1.1 TLSv1.2;
    ssl_ciphers                RC4:HIGH:!aNULL:!MD5;
    ssl_prefer_server_ciphers  on;

    # Proxy pass to servlet container

    location / {
      proxy_pass                http://localhost:8080/;
      proxy_redirect            off;
      proxy_set_header          Host               $host;
      proxy_set_header          X-Real-IP          $remote_addr;
      proxy_set_header          X-Forwarded-For    $proxy_add_x_forwarded_for;
      proxy_set_header          X-Forwarded-Proto  https;
      proxy_buffer_size         128k;
      proxy_buffers             8 128k;
      proxy_busy_buffers_size   256k;
      proxy_cookie_path         ~*^/(.*) "/$1; SameSite=Lax";
    }
  }
}

请注意最后一个https头值,该值是用来通知servlet容器请求通过HTTPS发出的。为了使Tomcat使用HTTPS正确生成Location URL头,您还需要在Tomcatserver.xml文件中的连接器中添加其他两个参数:

<Connector scheme="https" proxyPort="443" />

使用Nginx启用缓存

要求提供报告,图表,地图和其他与分析相关的资源 通常会花费一些时间来响应,并且可能会占用大量服务器 资源。为了缩短响应时间,请减少 服务器并隐藏潜在的服务器停机时间,我们可以引入缓存代理 在我们的服务器设置中。缓存的内容将存储在目录中 / var / cache / nginx,最多将分配250 MB的存储空间。 Nginx的 将自动创建此目录。

http {
  ..
  proxy_cache_path  /var/cache/nginx  levels=1:2  keys_zone=dhis:250m  inactive=1d;


  server {
    ..

    # Proxy pass to servlet container and potentially cache response

    location / {
      proxy_pass                http://localhost:8080/;
      proxy_redirect            off;
      proxy_set_header          Host               $host;
      proxy_set_header          X-Real-IP          $remote_addr;
      proxy_set_header          X-Forwarded-For    $proxy_add_x_forwarded_for;
      proxy_set_header          X-Forwarded-Proto  https;
      proxy_buffer_size         128k;
      proxy_buffers             8 128k;
      proxy_busy_buffers_size   256k;
      proxy_cookie_path         ~*^/(.*) "/$1; SameSite=Lax";
      proxy_cache               dhis;
    }
  }
}

Important

Be aware that a server side cache shortcuts the DHIS2 security features in the sense that requests which hit the server side cache will be served directly from the cache outside the control of DHIS2 and the servlet container. This implies that request URLs can be guessed and reports retrieved from the cache by unauthorized users. Hence, if you capture sensitive information, setting up a server side cache is not recommended.

使用Nginx进行速率限制

DHIS 2中的某些Web API调用,如analytics API,是计算密集型的。因此,最好对这些API进行速率限制,以允许系统的所有用户充分利用服务器资源。速率限制可以通过nginx实现。有多种实现速率限制的方法,这旨在记录基于nginx的方法。

以下nginx配置将对analytics网络API进行速率限制,并在_http_和_location_块级别具有以下元素(为简洁起见,配置被缩短):

http {
  ..
  limit_req_zone $binary_remote_addr zone=limit_analytics:10m rate=5r/s;

  server {
    ..

    location ~ ^/api/(\d+/)?analytics(.*)$ {
      limit_req    zone=limit_analytics burst=20;
      proxy_pass   http://localhost:8080/api/$1analytics$2$is_args$args;
      ..
    }
  }
}

配置的各个元素可以描述为:

  • limit_req_zone $binary_remote_addr: Rate limiting is done per request IP.
  • _zone=limit_analytics:20m_: A rate limit zone for the analytics API which can hold up to 10 MB of request IP addresses.
  • rate=20r/s: Each IP is granted 5 requests per second.
  • location ~ ^/api/(\d+/)?analytics(.*)$: Requests for the analytics API endpoint are rate limited.
  • burst = 20:最多20个请求的突发将在以后排队并提供服务;其他请求将导致产生503。

有关完整说明,请查阅[nginx文档](https://www.nginx.com/blog/rate-limiting-nginx/)。

使用Nginx使资源可用

In some scenarios it is desirable to make certain resources publicly available on the Web without requiring authentication. One example is when you want to make data analysis related resources in the web API available in a Web portal. The following example will allow access to charts, maps, reports, report table and document resources through basic authentication by injecting an Authorization HTTP header into the request. It will remove the Cookie header from the request and the Set-Cookie header from the response in order to avoid changing the currently logged in user. It is recommended to create a user for this purpose given only the minimum authorities required. The Authorization value can be constructed by Base64-encoding the username appended with a colon and the password and prefix it "Basic ", more precisely "Basic base64_encode(username:password)". It will check the HTTP method used for requests and return 405 Method Not Allowed if anything but GET is detected.

为此类公共用户设置一个单独的域可能是有利的 使用这种方法时。这是因为我们不想更改 已登录用户访问公共帐户时的凭据 资源。例如,当您的服务器部署在somedomain.com上时, 您可以在api.somedomain.com上设置专用的子域,并指向URL 从您的门户到此子域。

http {
  ..

  server {
    listen       80;
    server_name  api.somedomain.com;

    location ~ ^/(api/(charts|chartValues|reports|reportTables|documents|maps|organisationUnits)|dhis-web-commons/javascripts|images|dhis-web-commons-ajax-json|dhis-web-mapping|dhis-web-visualizer) {
    if ($request_method != GET) {
        return 405;
      }

      proxy_pass         http://localhost:8080;
      proxy_redirect     off;
      proxy_set_header   Host               $host;
      proxy_set_header   X-Real-IP          $remote_addr;
      proxy_set_header   X-Forwarded-For    $proxy_add_x_forwarded_for;
      proxy_set_header   X-Forwarded-Proto  http;
      proxy_set_header   Authorization      "Basic YWRtaW46ZGlzdHJpY3Q=";
      proxy_set_header   Cookie             "";
      proxy_hide_header  Set-Cookie;
    }
  }
}

DHIS2配置参考

The following describes the full set of configuration options for the dhis.conf configuration file. The configuration file should be placed in a directory which is pointed to by a DHIS2_HOME environment variable.

注意

您不应尝试直接使用此配置文件,而应将其用作可用配置选项的参考。许多属性是可选的。

# ----------------------------------------------------------------------
# Database connection for PostgreSQL [Mandatory]
# ----------------------------------------------------------------------

# Hibernate SQL dialect
connection.dialect = org.hibernate.dialect.PostgreSQLDialect

# JDBC driver class
connection.driver_class = org.postgresql.Driver

# Database connection URL
connection.url = jdbc:postgresql:dhis2

# Database username
connection.username = dhis

# Database password (sensitive)
connection.password = xxxx

# Max size of connection pool (default: 40)
connection.pool.max_size = 40

# ----------------------------------------------------------------------
# Database connection for PostgreSQL [Optional]
# ----------------------------------------------------------------------

# Minimum number of Connections a pool will maintain at any given time (default: 5).
connection.pool.min_size=5

# Initial size of connection pool (default : 5)
#Number of Connections a pool will try to acquire upon startup. Should be between minPoolSize and maxPoolSize
connection.pool.initial_size=5

#Determines how many connections at a time will try to acquire when the pool is exhausted.
connection.pool.acquire_incr=5

#Seconds a Connection can remain pooled but unused before being discarded. Zero means idle connections never expire. (default: 7200)
connection.pool.max_idle_time=7200

#Number of seconds that Connections in excess of minPoolSize should be permitted to remain idle in the pool before being culled (default: 0)
connection.pool.max_idle_time_excess_con=0

#If this is a number greater than 0, dhis2 will test all idle, pooled but unchecked-out connections, every this number of seconds. (default: 0)
connection.pool.idle.con.test.period=0

#If true, an operation will be performed at every connection checkout to verify that the connection is valid. (default: false)
connection.pool.test.on.checkout=false

#If true, an operation will be performed asynchronously at every connection checkin to verify that the connection is valid. (default: true)
connection.pool.test.on.checkin=true

#Defines the query that will be executed for all connection tests. Ideally this config is not needed as postgresql driver already provides an efficient test query. The config is exposed simply for evaluation, do not use it unless there is a reason to.
connection.pool.preferred.test.query=select 1

#Configure the number of helper threads used by dhis2 for jdbc operations. (default: 3)
connection.pool.num.helper.threads=3

# ----------------------------------------------------------------------
# Server [Mandatory]
# ----------------------------------------------------------------------

# Base URL to the DHIS 2 instance
server.base.url = https://play.dhis2.org/dev

# Enable secure settings if system is deployed on HTTPS, can be 'off', 'on'
server.https = off

# ----------------------------------------------------------------------
# System [Optional]
# ----------------------------------------------------------------------

# System mode for database read operations only, can be 'off', 'on'
system.read_only_mode = off

# Session timeout in seconds, default is 3600
system.session.timeout = 3600

# SQL view protected tables, can be 'on', 'off'
system.sql_view_table_protection = on

# ----------------------------------------------------------------------
# Encryption [Optional]
# ----------------------------------------------------------------------

# Encryption password (sensitive)
encryption.password = xxxx

# ----------------------------------------------------------------------
# File store [Optional]
# ----------------------------------------------------------------------

# File store provider, currently 'filesystem' and 'aws-s3' are supported
filestore.provider = filesystem

# Directory / bucket name, folder below DHIS2_HOME on file system, 'bucket' on AWS S3
filestore.container = files

# Datacenter location (not required)
filestore.location = eu-west-1

# Public identity / username
filestore.identity = dhis2-id

# Secret key / password (sensitive)
filestore.secret = xxxx

# ----------------------------------------------------------------------
# LDAP [Optional]
# ----------------------------------------------------------------------

# LDAP server URL
ldap.url = ldaps://300.20.300.20:636

# LDAP manager user distinguished name
ldap.manager.dn = cn=JohnDoe,ou=Country,ou=Admin,dc=hisp,dc=org

# LDAP manager user password (sensitive)
ldap.manager.password = xxxx

# LDAP entry distinguished name search base
ldap.search.base = dc=hisp,dc=org

# LDAP entry distinguished name filter
ldap.search.filter = (cn={0})

# ----------------------------------------------------------------------
# Node [Optional]
# ----------------------------------------------------------------------

# Node identifier, optional, useful in clusters
node.id = 'node-1'

# ----------------------------------------------------------------------
# Analytics [Optional]
# ----------------------------------------------------------------------

# Analytics server-side cache expiration in seconds
analytics.cache.expiration = 3600

# ----------------------------------------------------------------------
# System monitoring [Optional]
# ----------------------------------------------------------------------

# System monitoring URL
system.monitoring.url =

# System monitoring username
system.monitoring.username =

# System monitoring password (sensitive)
system.monitoring.password = xxxx

应用程序日志记录

本节介绍DHIS 2中的应用程序日志记录。

日志文件

DHIS2应用程序日志输出定向到多个文件和位置。首先,将日志输出发送到标准输出。 Tomcat Servlet容器通常将标准输出输出到“ logs”下的文件:

 <tomcat-dir> /logs/catalina.out

Second, log output is written to a "logs" directory under the DHIS2 home directory as defined by the DHIS2_HOME environment variables. There is a main log file for all output, and separate log files for various background processes. The main file includes the background process logs as well. The log files are capped at 50 Mb and log content is continuously appended.

 <DHIS2_HOME> /logs/dhis.log
 <DHIS2_HOME> /logs/dhis-analytics-table.log
 <DHIS2_HOME> /logs/dhis-data-exchange.log
 <DHIS2_HOME> /logs/dhis-data-sync.log

日志配置

In order to override the default log configuration you can specify a Java system property with the name log4j.configuration and a value pointing to the Log4j configuration file on the classpath. If you want to point to a file on the file system (i.e. outside Tomcat) you can use the file prefix e.g. like this:

-Dlog4j.configuration =文件:/home/dhis/config/log4j.properties

Java system properties can be set e.g. through the JAVA_OPTS environment variable or in the tomcat startup script.

A second approach to overriding the log configuration is to specify logging properties in the dhis.conf configuration file. The supported properties are:

#日志文件的最大大小,默认为'100MB'
logging.file.max_size = 250MB

#最大滚动日志归档文件数,默认为0
logging.file.max_archives = 2

DHIS2 will eventually phase out logging to standard out / catalina.out and as a result it is recommended to rely on the logs under DHIS2_HOME.

使用PostgreSQL数据库

管理DHIS2实例时的常见操作是转储和 恢复数据库。假设您要转储数据库(副本) 从安装部分进行设置,您可以调用以下命令:

pg_dump dhis2 -U dhis -f dhis2.sql

第一个参数(dhis2)引用数据库的名称。的 第二个参数(dhis)指向数据库用户。最后一个论点 (dhis2.sql)是副本的文件名。如果您要压缩 您可以立即复制文件:

pg_dump dhis2 -U dhis | gzip> dhis2.sql.gz

要在另一个系统上还原此副本,您首先需要创建一个 如安装部分所述清空数据库。你还需要 如果您创建了压缩版本,则将副本打包。您可以 调用:

psql -d dhis2 -U dhis -f dhis2.sql

Upgrading

Upgrading vs. Updating

When we talk about upgrading DHIS2, we generally simply mean "moving to a newer version". However, there is an important distinction between upgrading and updating.

Upgrading : Moving to a newer base version of DHIS2 (for example, from 2.34 to 2.36). Upgrading typically requires planning, testing, training (for new features or interfaces), which may take significant time and effort.

Updating : Moving to a newer patch of the current DHIS2 version (for example, from 2.35.1 to 2.35.4). Updating mainly provides bug fixes without changing the functionality of the software. It is lower risk, and we advise everyone to keep their version up to date.

Before you begin

Caution

It is important to note that once you upgrade you will not be able to use the upgraded database with an older version of DHIS2. That is to say it is not possible to downgrade.

If you wish to revert to an older version, you must do so with a copy of the database that was created from that older version, or a previous version. Therefore, it is almost always a good idea to make a copy of your database before you uprgrade.

Performing the upgrade

Regardless of whether you are upgrading or updating, the technical process is more-or-less identical. We will just refer to it as upgrading.

1 Safeguard your data

Depending on what sort of DHIS2 instance you have, and what you use it for, the first step is to make sure that you can recover any important data if anything goes wrong with the upgrade.

This means performing standard system admin tasks, such as:

  1. Backing up your database
  2. Testing in a development environment
  3. Scheduling down time (to avoid data being entered during the upgrade)
  4. etc.

2 Upgrade the software

From v2.29 or below

If you are starting from v2.29 or below, you must first upgrade to v2.30 version-by-version, manually, following the upgrade notes you find under the specific version numbers on our releases site. When you are at v2.30 you can go to the next section.

From v2.30 or above

If you are starting from at least v2.30:

  1. Read all of the upgrade notes from your current version up to the target version on our releases site. Make sure your environment meets all of the requirements
  2. Make a copy of your database if you didn't do so in step 1
  3. Drop any materialized SQL views from your database
  4. Stop the server
  5. Replace the war file with the target version (There is no need to upgrade to intermediate versions; in fact, it is not recommended)
  6. 启动服务器

You should now be ready to enjoy the new fixes and features.

监控

介绍

DHIS2可以导出[Prometheus](https://prometheus.io/)兼容的度量标准,以监视DHIS2节点。

本节介绍了使用标准安装过程(apt-get)和Docker安装Prometheus和[Grafana](https://grafana.com/)以及配置Grafana以显示DHIS2指标所需的步骤。

有关DHIS2实例公开的指标的列表,请参阅[GitHub](https://github.com/dhis2/wow-backend/blob/master/guides/monitoring.md)上的监视指南。

设定

下一节将介绍如何设置Prometheus和Grafana,以及如何设置Prometheus从一个或多个DHIS2实例中提取数据。

在Ubuntu和Debian上安装Prometheus + Grafana

  • 从官方[下载](https://prometheus.io/download/)页面下载Prometheus。

  • 确保针对您的操作系统和CPU架构(Linux和amd64)进行过滤。

  • 确保选择最新的稳定版本,而不是“ rc”版本,因为目前尚不足够稳定。

  • 通过单击链接或使用wget下载档案。

wget https://github.com/prometheus/prometheus/releases/download/v2.15.2/prometheus-2.15.2.linux-amd64.tar.gz
  • 解开拉链
tar xvzf prometheus-2.15.2.linux-amd64.tar.gz

归档文件包含许多重要文件,但这是您需要了解的主要文件。

  • prometheus.yml:Prometheus的配置文件。这是您将要修改的文件,以调整Prometheus服务器,例如,更改抓取间隔或配置自定义警报。
  • Prometheus:Prometheus服务器的二进制文件。这是您要执行的命令,用于在Linux机器上启动Prometheus实例。
  • promtool:这是一个可以运行以验证Prometheus配置的命令。

将Prometheus配置为服务

  • 使用Prometheus组创建一个Prometheus用户。
useradd -rs / bin / false普罗米修斯
  • 将Prometheus二进制文件移到本地bin目录
cd prometheus-2.15.2.linux-amd64 /
cp prometheus promtool / usr / local / bin
chown prometheus:普罗米修斯/ usr / local / bin / prometheus
  • 在Prometheus的/ etc文件夹中创建一个文件夹,并将控制台文件,控制台库和Prometheus配置文件移动到此新创建的文件夹中。
mkdir / etc / prometheus
cp -R控制台/ console_libraries / prometheus.yml / etc / prometheus

在根目录中创建一个数据文件夹,其中包含一个prometheus文件夹。

mkdir -p数据/普罗米修斯
chown -R prometheus:普罗米修斯/ data / prometheus / etc / prometheus / *

创建Prometheus服务

要创建Prometheus _systemd_服务,请转到/ lib / systemd / system文件夹并创建一个名为prometheus.service的新systemd文件。

cd / lib / systemd / system
touch prometheus.service
  • 编辑新创建的文件,然后将以下内容粘贴到其中:
[单元]
描述=普罗米修斯
Wants = network-online.target
之后= network-online.target

[服务]
类型=简单
用户= prometheus
组=普罗米修斯
ExecStart = / usr / local / bin / prometheus \
  --config.file = / etc / prometheus / prometheus.yml \
  --storage.tsdb.path =“ / data / prometheus” \
  --web.console.templates = / etc / prometheus / consoles \
  --web.console.libraries = / etc / prometheus / console_libraries \
  --web.listen-address = 0.0.0.0:9090 \
  --web.enable-admin-api

重启=总是

[安装]
WantedBy =多用户目标
  • 保存文件并在启动时启用Prometheus服务
systemctl启用普罗米修斯
systemctl启动方法
  • 测试服务是否正在运行
系统状态法

...
活动:活动(运行中)
  • 现在应该可以通过访问 http://localhost:9090 来访问Prometheus UI。

设置Nginx反向代理

Prometheus本身不支持身份验证或TLS加密。如果必须将Prometheus暴露在本地网络的边界之外,则启用身份验证和TLS加密非常重要。以下步骤显示了如何将Nginx用作反向代理。

  • 安装Nginx(如果尚未安装)
apt更新
apt-get安装nginx

默认情况下,Nginx将开始在默认的http端口80中侦听HTTP请求。

如果机器上已经有一个Nginx实例在运行,并且您不确定它在哪个端口上侦听,请运行以下命令:

> lsof | grep LISTEN | grep nginx

nginx 15792根8u IPv4 1140223421 0t0 TCP *:http(LISTEN)

最后一列显示Nginx使用的端口(http->80)。

默认情况下,Nginx配置位于/ etc / nginx / nginx.conf中。

确保nginx.conf包含虚拟主机配置部分

##
#虚拟主机配置
##

包括/etc/nginx/conf.d/*.conf;
包括/ etc / nginx / sites-enabled / *;
  • 在/ etc / nginx / conf.d中创建一个名为prometheus.conf的新文件
触摸/etc/nginx/conf.d/prometheus.conf
  • 编辑新创建的文件,然后将以下内容粘贴到其中:
服务器{
  听1234;

  位置 / {
    proxy_pass http:// localhost:9090 /;
  }
}
  • 重新启动Nginx并浏览到http:// localhost:1234
systemctl重启nginx

#如果出现启动错误
journalctl -f -u nginx.service
  • Configure Prometheus for reverse proxying, by editing /lib/systemd/system/prometheus.service and add the following argument to the list of arguments passed to the Prometheus executable
--web.external-url = https:// localhost:1234
  • 重新启动服务
systemctl守护程序重新加载
systemctl重新启动prometheus


#发生错误时
journalctl -f -u prometheus.service

启用反向代理身份验证

本节说明如何通过反向代理配置基本身份验证。如果您需要其他身份验证机制(SSO等),请检查相关文档。

  • 确保系统上已安装htpasswd
apt-get install apache2-utils
  • 创建认证文件
cd / etc / prometheus
htpasswd -c .credentials管理员

选择一个强密码,并确保正确创建了密码文件。

  • Edit the previously created Nginx configuration file (/etc/nginx/conf.d/prometheus.conf), and add the authentication information.
服务器{
  听1234;

  位置 / {
    auth_basic“ Prometheus”;
    auth_basic_user_file /etc/prometheus/.credentials;
    proxy_pass http:// localhost:9090 /;
  }
}
  • 重新启动Nginx
systemctl重启nginx

#发生错误时
journalctl -f -u nginx.service
  • http://localhost:1234 现在应该提示输入用户名和密码。

在Ubuntu和Debian上安装Grafana

  • 添加一个gpg密钥并从APT回购中安装OSS Grafana软件包
apt-get install -y apt-transport-https

wget -q -O-“ https://packages.grafana.com/gpg.key” | sudo apt键添加-

add-apt-repository“ deb https://packages.grafana.com/oss/deb稳定主程序”

apt-get更新

apt-get install grafana
  • 如果系统使用systemd,则会自动创建一个新的grafana-service。检查systemd文件以获得有关Grafana安装的一些见解
猫/usr/lib/systemd/system/grafana-server.service

该文件非常重要,因为它提供有关新安装的Grafana实例的信息。

该文件显示:

Grafana服务器二进制文件**位于/ usr / sbin / grafana-server。定义所有**环境变量**的文件位于 /etc/default/grafana-server 中。**配置文件**是通过CONF_FILE 环境变量给出的。 **文件的PID **也由PID_FILE_DIR环境变量决定。记录**日志,数据,**插件**和**配置**路径由环境变量给出。

  • 启动服务器
systemctl启动grafana服务器
  • 访问Grafana Web控制台:http:// localhost:3000

Grafana的默认登录名为admin,默认密码也为admin。首次访问时,系统将提示您更改密码。

  • 将Prometheus配置为Grafana数据源

通过左侧菜单中的配置>数据源,访问数据源面板。

点击添加数据源

在下一个窗口中选择Prometheus数据源。

根据Prometheus设置配置数据源(使用身份验证,TSL等)

使用Docker安装Prometheus + Grafana

本节介绍如何启动包含Prometheus和Grafana的Prometheus堆栈。

配置基于以下项目:https://github.com/vegasbrianc/prometheus

docker stack deploy -c docker-stack.yml舞会

上面的命令,可能会导致以下错误:

This node is not a swarm manager. Use "docker swarm init" or "docker swarm join" to connect this node to swarm and try again

如果发生这种情况,则需要启动Swarm。您可以使用以下命令行:

docker swarm初始化--advertise-addr <YOUR_IP>

一旦该命令成功运行,您就应该能够运行上一个命令而不会出现问题。

该堆栈还包含用于Docker监视的Node导出器。如果您对Docker监控不感兴趣,可以在docker-stack.yml文件中注释掉相关部分:

  • node-exporter
  • cadvisor

  • 要停止Prometheus堆栈:

docker stack rm舞会

Prometheus配置文件(prometheus.yml)位于prometheus文件夹中。

  • 通过以下网址访问Grafana Web控制台:http:// localhost:3000,用户名:admin和密码:foobar

配置Prometheus从一个或多个DHIS2实例提取指标

在使用Prometheus之前,需要进行基本配置。因此,我们需要创建一个名为prometheus.yml的配置文件。

注意

Prometheus的配置文件是用YAML编写的,严格禁止使用制表符。如果文件格式错误,Prometheus将不会启动。编辑时要小心。

Prometheus的配置文件分为三个部分:global,rule_files和scrape_configs。

在全局部分中,我们可以找到Prometheus的常规配置:scrape_interval定义Prometheus刮除目标的频率,evaluation_interval控制软件评估规则的频率。规则用于创建新的时间序列并用于生成警报。

rule_files块包含我们希望Prometheus服务器加载的任何规则的位置信息。

配置文件的最后一块名为scape_configs,其中包含Prometheus监视的资源信息。

一个简单的DHIS2 Prometheus监视文件如下例所示:

global:
    scrape_interval: 15s
    evaluation_interval: 15s

scrape_configs:
    - job_name: "dhis2"
      metrics_path: "/dhis/api/metrics"
      basic_auth:
          username: admin
          password: district
      static_configs:
          - targets: ["localhost:80"]

全局的scrape_interval设置为15秒,对于大多数用例来说已经足够了。

在scrape_configs部分中,我们定义了DHIS2导出器。basic_auth块包含访问metricsAPI所需的凭据:考虑创建仅用于访问metrics端点的临时用户。

Prometheus可以与DHIS2在同一服务器上运行,也可以不在同一服务器上运行:在上述配置中,假定Prometheus仅监视一个与Prometheus在同一服务器上运行的DHIS2实例,因此我们使用localhost。

配置DHIS2导出器

DHIS2中默认情况下禁用监视子系统。

必须明确启用每个指标群集,以便导出指标。要将DHIS2配置为导出一个或多个指标,请检查此[document](https://github.com/dhis2/wow-backend/blob/master/guides/monitoring.md#dhis2-monitoring-configuration)。

审核

介绍

DHIS2支持基于Apache ActiveMQ Artemis的新审核服务。 DHIS2将Artemis用作异步消息传递系统。

将实体保存到数据库后,审核消息将发送到Artemis消息使用者服务。然后,该消息将在其他线程中处理。

可以从DHIS2数据库中检索审核日志。当前,没有UI或API端点可用于检索审核条目。

单审核表

所有审核条目将保存到一个名为audit的表中

柱 类型
受审核者 整数
审核类型 文本 读取,创建,更新,删除,搜索
审计范围 文本 元数据,汇总,跟踪器
克拉斯 文本 审核实体Java类名称
属性 jsonb Json字符串存储审计实体的属性,用于搜索。示例:{“ valueType”:“ TEXT”,“ categoryCombo”:“ SWQW313FQY”,“ domainType”:“ TRACKER”}
数据 比蒂亚 审计实体的压缩Json字符串。当前为字节数组格式,无法人工阅读。
创建于 没有时区的时间戳
由...制作 文本
uid 文本
码 文本

新的审核服务利用了两个新概念:审核范围和审核类型。

审核范围

审核范围是可以审核的应用程序的逻辑区域。当前有三个审核范围:

追踪器

元数据

骨料
  • For the Tracker Audit Scope, the audited objects are: Tracked Entity Instance, Tracked Entity Attribute Value, Enrollment, Event

  • 对于元数据范围,将审核所有“元数据”对象。

  • 对于“聚合范围”,将审核“聚合数据值”对象。

审核类型

审核类型是触发审核操作的操作。目前,我们支持以下类型:

读

创造

更新

删除

例如,当创建一个新的“跟踪的实体实例”时,如果像这样进行配置,则使用CREATE操作在审计数据库表中插入一个新的“审计”条目。

Note: the READ Audit Type will generate a lot of data in database and may have an impact on the performance.

设定

审核系统自动配置为审核以下范围和类型:

  • 创建,更新,删除

  • 元数据,跟踪器,聚集

无需采取任何行动即可启动审核。 仍然可以使用“审计矩阵”来配置审计。审核矩阵由dhis.conf中的3个属性驱动:

审计元数据

审计跟踪器

审计汇总

每个属性均接受以分号分隔的有效审计类型列表:

创造

更新

删除

读

例如,为了仅审核与Tracker相关的对象的创建和删除,应在dhis.conf中添加以下属性:

audit.tracker =创建;删除

为了完全禁用审核,这是要使用的配置:

audit.metadata =禁用

audit.tracker =禁用

audit.aggregate =禁用

使用网关进行SMS报告

DHIS2支持通过[SMS](https://docs.dhis2.org/master/en/dhis2_user_manual_en/mobile.html)接受数据,但是,SMS需要以一种隐秘的方式构成以保护信息。 DHIS2 Android应用程序充当透明层,可通过SMS发送信息,而用户不必担心编写SMS。要使用Android App发送SMS,需要正确配置SMS网关。本节说明可用的不同选项以及如何实现。

发送短信

首先,请务必澄清一下,本节主要涉及**接收短信**(从移动设备到DHIS2服务器)的设置,这在考虑使用App发送(同步)记录在App中的信息时是必需的通过SMS连接到DHIS2服务器。在应用程序中,可以在_设置_> _SMS设置_下进行设置

将SMS(即从DHIS2服务器发送到移动设备)的设置相对简单。如果仅需要在发生某些事件(消息,阈值等)时从DHIS2向用户电话发送通知,则仅需要发送SMS。

所有这些都可以在[移动配置部分](https://docs.dhis2.org/master/en/user/html/mobile_sms_service.html)的SMS服务配置页面中进行配置。

There is out of the box support for common providers such as Bulk SMS and Clickatell, and both providers support sending of SMS to numbers in most countries.

另请注意,可以使用其他SMS网关来发送和接收SMS。因此,即使您在下面设置了用于接收SMS的解决方案,仍然可以使用上述上述解决方案之一来发送SMS。

使用Android设备作为SMS网关

到目前为止,最简单的解决方案是使用专用的Android设备作为SMS网关。任何运行Android OS(4.4,Kitkat或更高版本)的手机或平板电脑都可以。为了将消息转发到您的DHIS2服务器,它将需要持续的Internet连接,并且还需要SIM卡来接收传入的SMS。

您需要在移动设备上下载并安装DHIS2 Android SMS网关应用程序。请参阅[版本](https://github.com/dhis2/dhis2-sms-android-gateway/releases)列表,您可以在其中下载最新的APK文件进行安装。应用页面本身上有说明,但实际上,您只需要启动应用并输入DHIS2服务器的详细信息(URL,用户名和密码)即可。

设置并运行该网关后,您可以使用DHIS2 Capture App在任何其他移动设备的配置页面中输入此网关设备的电话号码。然后,当从这些报告设备发送SMS时,它们将在网关设备上接收并自动转发到DHIS2服务器,在该服务器上对其进行处理。

**在测试SMS功能时,使用此网关设备非常理想。**在对需要SMS报告的项目进行试点时,这会很好。只要将设备插入电源并保持稳定的互联网连接,它就可以很好地用于小型项目。

但是,在考虑将项目移交给生产时,有必要研究以下网关的一种更永久和可靠的解决方案。

Sending SMS using an Android Device Gateway

当前不支持也不记录此选项。

专用短信网关

本节讨论更永久和专用的SMS网关的使用以及可用的选项。下面的每个选项都将涉及一个提供商(或您自己)与国家/地区的电话运营商建立SMPP连接,并使用此连接来接收传入的SMS并使用HTTP通过Internet将其转发到您的DHIS2服务器。

这些解决方案可以使用**长号**或**短代码**。长号是大多数人使用的标准移动电话号码,即+61400123123。短代码只是短号,例如311。短代码通常会花费更多的时间来设置和维护。

Ensuring incoming SMS to DHIS2 server are formatted correctly

When sending incoming SMS to a DHIS2 server via the API you use the following URL: https:///api/sms/inbound

在DHIS2版本2.34及更低版本中,此终结点要求入站SMS的格式必须具有非常特定的格式,即消息本身必须是一个名为text的参数,发件人的电话号码必须是一个名为originator的参数。

使用以下所有SMS网关选项时,将它们配置为将传入的SMS转发到另一个Web服务时,它们将各自具有自己的格式,该格式与DHIS2 API期望的格式不同。因此,有必要重新格式化它们,然后再将它们发送到DHIS2服务器。

一种选择是运行您自己的非常简单的Web服务,该服务仅接收来自网关提供商的传入SMS,将其重新格式化为DHIS2所需的格式,然后将其转发到DHIS2 API。此类服务需要由软件开发人员编写。

在DHIS2版本2.35中,计划使用传入SMS的模板系统来支持这些情况,因此您可以指定将从提供商处发送的消息的格式。这样,您可以将DHIS2服务器配置为接受来自任何其他SMS网关提供者的传入SMS,并且它们可以直接将传入SMS发送到DHIS2 API,而无需这种格式的Web服务。

Using RapidPro

[RapidPro](https://rapidpro.io/)是联合国儿童基金会在全球50多个国家/地区提供的服务。它是一套软件,可以与国内电话运营商合作,使组织能够为其项目设计SMS解决方案,例如SMS报告或宣传活动。

RapidPro服务将包括通常通过短码与国内一个或多个电话运营商的SMPP连接,这可能专用于NGO的卫生工作。然后可以添加一个Webhook,以便将传入的SMS转发到另一个Web服务,例如上述的格式化Web服务。如果该短代码也用于其他目的,则可能有必要将报告设备的电话号码添加到单独的组中,以便仅将来自那些设备的传入SMS转发到Webhook。

RapidPro目前在大约一半正在使用或试用DHIS2的国家/地区中建立和运行。在考虑下面的一种解决方案(可能在财务和时间上都可能会付出高昂的代价)之前,值得与Unicef联系,以确定RapidPro是否可用以及在您所在的国家/地区是否可以用于健康报告。

Using commercial SMS gateway providers

在上面的“发送SMS”部分中提到的商业SMS网关提供商中,它们通常在大多数国家/地区具有_send_ SMS的能力,但仅在少数国家/地区支持接收SMS。他们支持 receiving SMS 的大多数国家/地区不是使用DHIS2的国家/地区。在使用DHIS2的国家/地区中,大多数已经在国内运行RapidPro服务了。

但是,值得研究您所在国家/地区可以使用哪些商业选项。在某些国家/地区,会有一些小型国家公司提供SMS服务,它们将与您可以使用的电话提供商建立现有的SMPP连接。

Using phone carriers directly

如果以上解决方案均不可用,则有必要直接与您所在国家的电话运营商联系。向他们询问的第一个问题是,他们是否知道与您有联系的与他们进行SMPP连接的任何公司。

如果不是这样,作为最后的选择,您将需要考虑与电话提供商建立并维护自己的SMPP连接。但是,并非所有电话提供商都可以提供这种服务。

您需要运行自己的服务器,该服务器上运行的软件例如[Kannel](https://www.kannel.org/),该软件(通常通过VPN)连接到在电话提供商网络中运行的SMPP服务。有了此设置,任何配置的长号或短码的传入SMS都会从电话运营商发送到Kannel服务器,然后您可以按照上述方式转发这些消息。

Receiving concatenated or multipart SMS

通过SMS与DHIS2 Android App同步数据时,它使用压缩格式以占用尽可能少的空间(文本字符)。尽管如此,通常情况下,一条消息会超出一个标准SMS的160个字符的限制。在大多数现代移动设备上,这些消息仍将作为一条串联或多部分的SMS发送,并作为一条消息接收。在两个移动设备之间进行发送时,如果将Android设备用作网关,则应毫无问题地进行处理。

然后,在选择SMS网关时,重要的是确认所使用的电话运营商支持级联SMS。他们中的大多数人都将支持此功能,但是重要的是要进行确认,因为如果拆分SMS,SMS功能将无法使用。这依赖于称为UDH(用户数据头)的东西。与提供商讨论时,请确保您询问是否支持。