For the complete DHIS2 documentation index, see llms.txt.

DHIS2 系统管理员升级指南{ #dhis2-upgrade-guide-for-system-administrators }¶

介绍¶

本指南提供了升级 DHIS2 及其附属系统的结构化方法，以促进版本之间的无缝过渡。它概述了可操作的步骤，同时强调了全面备份等关键环节，以降低数据丢失的风险。升级 DHIS2 所涉及的不仅仅是更换 WAR 文件；新版本可能需要更新 Java 或 Tomcat 等依赖项。鉴于可能会出现不可预见的问题，全面的准备工作至关重要。通过主动识别潜在风险并制定缓解策略，管理员可以最大限度地减少中断，确保升级成功

目标受众{ #target-audience }¶

本指南面向负责维护 DHIS2 部署的**系统管理员**。由于 DHIS2 仅支持三个最新的年度版本，因此需要定期升级。这些升级通常由系统管理员负责，需要 Linux 专业知识和较强的服务器/应用程序管理技能。这个主要由人工完成的过程需要仔细规划，不仅包括 DHIS2 本身，还包括 PostgreSQL、Java、Tomcat 和基本操作系统等依赖项。

升级{ #importance-of-upgrading } 的重要性¶

DHIS2 仅支持最新的三个主要版本，并提供维护补丁和更新。其依赖系统（如 PostgreSQL、Tomcat 和 Nginx）也是如此，它们遵循各自独立的发布和支持周期。虽然它们的时间表可能各不相同，但过时的版本最终都会达到生命末期，失去官方支持、安全更新以及与较新 DHIS2 版本的兼容性。为确保系统的稳定性、安全性和兼容性，DHIS2 及其依赖系统必须保持在其支持版本的范围内。

升级{ #key-benefits-of-upgrading } 的主要好处¶

确保遵守 DHIS2 支持政策，该政策仅涵盖最新的三个主要版本。
打上最新的安全补丁，防范漏洞。
受益于最新的错误修复，提高系统稳定性。
通过新版本中引入的优化功能提高性能。
获得新功能和增强功能。
与 DHIS2 最新版本所要求的更新依赖项保持兼容。

用于升级{ #components-for-upgrading } 的组件¶

在考虑 DHIS2 升级时，系统管理员必须考虑到整个系统栈。这包括

** 操作系统 (OS)** - 大多数部署使用 Ubuntu LTS，其支持生命周期为五年。在不支持的操作系统上运行 DHIS2 可能会导致兼容性和安全问题。最好先升级操作系统，同时保持 DHIS2 不变，确保在更新应用程序之前有一个稳定的基础。支持的 LTS 版本通常包括 PostgreSQL 等兼容软件。
** 数据库** - PostgreSQL 遵循明确的支持生命周期，仅维护最新的五个主要版本。运行受支持的版本对安全性和性能至关重要。虽然通过软件包管理器（如apt）升级非常简单，但较新版本中的更改（如从 PostgreSQL 12 默认启用 JIT）可能会引入可能影响性能的回归。
依赖关系 - DHIS2依赖于各种组件，如**Tomcat**、Nginx**和**PostgreSQL，所有这些组件都需要定期更新。Linux 软件包管理器（"apt"、"yum"）可简化依赖升级，但在进行升级之前，必须查看 DHIS2 的推荐版本和要求；系统要求可能会随 DHIS2 的新版本而改变。
DHIS2 应用程序升级

DHIS2 升级本身的范围、复杂程度和风险也可能不同。我们可以考虑对核心应用程序进行三种主要类型的升级：

主要升级 - 涉及重大更改和新功能，可能会破坏与旧版本的兼容性。主要升级用第一个版本号的变化来表示（例如，从版本 2.38 到 2.39，或从 v41 到 v42）。它们通常包括对数据库模式的更改，以适应新的功能。新版本每年发布一次。
小规模升级（补丁更新） - 这是一种增量升级，可能会产生（非破坏性的）变化。这种升级通常包含改进和错误修复。从历史上看，DHIS2 团队称其为补丁更新。补丁更新每几个月发布一次。
** 热修复** - 这些是为解决紧急、关键问题而发布的最小更新。这些更新可安全地应用于已运行后续补丁更新的系统。

注

在最新的文档中，DHIS2 版本号中的 2. 已被 v （版本）所取代。其余的版本号由核心团队以下列格式引用： <major>.<patch>.<hotfix> 这等同于经典的语义版本，通常称为 <major>.<minor>.<patch>

所需技术技能和角色{ #technical-skills-and-roles-required }¶

管理和升级 DHIS2 需要多个团队和利益相关者之间的协调，每个团队和利益相关者都要贡献自己的专业知识，以确保平稳过渡和系统稳定。以下是主要角色及其职责的细分。

1.系统管理员¶

系统管理员负责

执行 DHIS2 升级和管理服务器相关任务。
确保操作系统、数据库和依赖项是最新的。
监控服务器性能并排除故障。
管理备份和灾难恢复计划。

2.DHIS2 用户¶

DHIS2 用户以不同身份与系统互动，包括

开发人员/实施人员 - 配置、定制和扩展 DHIS2 功能。
数据录入人员 - 在系统中采集和验证数据。
数据消费者和分析师 - 生成报告和分析数据，以利决策。

3.网络团队¶

在一些组织中，专门的网络团队负责：

配置和维护网络安全，包括防火墙规则。
确保安全访问 DHIS2 服务器和数据库。
排除可能影响系统访问的连接问题。

4.基础设施团队¶

基础设施团队负责

调配和管理虚拟机、存储池和云资源。
为升级前验证设置测试环境。
在需要时确保高可用性和系统冗余。

5.DNS 管理员¶

指定人员或团队负责

管理域名解析，确保可以访问 DHIS2 服务。
在服务器迁移或 IP 变更时更新 DNS 记录。

6.主要利益攸关方¶

其他几个角色在 DHIS2 的管理和升级中发挥着重要作用，包括

管理层和系统所有者（如政府实体） - 监督系统运行的完整性和合规性。
**支持系统的可持续性，确保提供必要的资源。
项目经理 - 协调升级时间表，确保对用户的干扰降到最低。

升级前的准备工作{ #preparations-before-upgrading }¶

1.备份一切¶

数据库备份：使用 pg_dump 创建 PostgreSQL 数据库的完整备份，确保其经过测试并异地存储。
DHIS2 文件备份：备份 DHIS2 主目录、配置文件、文件存储和任何自定义脚本。
服务器快照：如果在虚拟化或云环境中运行，则应拍摄完整的系统快照，以便在需要时快速回滚。

2.查看兼容性和系统要求¶

请查看 DHIS2 的发布说明，了解特定版本的要求。
确保操作系统、PostgreSQL、Java (jre)、Tomcat 和其他依赖项满足新版本的要求。

3.在暂存环境中进行测试¶

在升级生产环境之前，在测试环境中部署新版本。
验证数据完整性和应用程序功能。

4.审查自定义配置和扩展¶

检查是否有任何自定义应用程序、脚本或配置需要修改才能兼容。
确保任何第三方集成都能与新版本配合使用。

5.通知利益相关者并计划停机时间¶

通知用户可能出现的停机和预期的更改。
将升级安排在非高峰时段，以尽量减少中断。

6.记录当前系统¶

记录当前的 DHIS2、PostgreSQL、Tomcat 和操作系统版本。
注意 dhis.conf 和 server.xml 中的配置。

7.准备回滚计划¶

制定经过测试的恢复策略，以防升级失败。
确保备份和快照易于访问。

DHIS2 的升级后步骤{ #post-upgrade-steps-for-dhis2 }¶

升级 DHIS2 后，请按照以下步骤验证系统的稳定性、性能和功能。

1.验证升级¶

使用 ** 关于 DHIS2** 页面（/dhis-web-dashboard → 帮助 → 关于 DHIS2）确认 DHIS2 版本。
检查服务器日志（Tomcat 的 catalina.out、DHIS2 日志）是否有任何错误或警告。
验证数据库迁移日志，确保已应用所有模式更新。

2.测试核心功能¶

登录并确认用户身份验证按预期运行。
打开仪表板、数据输入表、分析工具和报告。
运行关键分析任务（"analyticsTableUpdate"）并确认预期输出。

3.验证数据完整性¶

在**维护应用程序**下运行**数据完整性检查**，以确定不一致之处。
检查是否已正确加载所有跟踪实体、程序和数据元素。

4.监控性能和资源使用情况¶

使用 "htop"、"top "或**服务器监控工具**（如 Munin Zabbix）检查 CPU、内存和磁盘使用情况。
审查 PostgreSQL 性能（"pg_stat_activity"、"EXPLAIN ANALYZE"，用于慢速查询）。
监控系统日志，查找内存泄漏、查询速度慢或其他潜在瓶颈。

5.更新和优化配置¶

检查 dhis.conf 和 server.xml 设置，确保它们针对新版本进行了优化。
检查 PostgreSQL 设置（例如，"work_mem"、"shared_buffers"、"max_connections"）以提高性能。
如果使用缓存（Redis、Nginx），请确保其正常运行。

6.测试集成和外部服务¶

如果 DHIS2 与外部系统（如第三方应用程序接口、数据管道）集成，请确认它们仍在正常运行。
验证计划作业和脚本（如数据同步、备份、通知）。

7.通知用户并提供支持¶

通知用户升级已完成，并分享任何相关变更或新功能。
必要时提供培训或文件。
鼓励用户报告他们遇到的任何问题。

8.执行最后备份¶

确认稳定后，创建数据库和配置文件的完整**升级后备份**。
将其安全存储为还原点，以防将来出现问题。

详细考虑{ #detailed-considerations }¶

分析升级范围{ #analyze-scope-of-the-upgrade }¶

考虑可能需要更新的所有系统组件，如操作系统、PostgreSQL 数据库和其他依赖项。如果有多个组件需要升级（如操作系统、PostgreSQL），应分别处理，从操作系统开始。升级基本操作系统通常包括更新 Tomcat 和 PostgreSQL 等软件。

对于操作系统升级，强烈建议使用目标操作系统构建新服务器并迁移 DHIS2，而不是原地升级。这样可以最大限度地降低风险，并提供更简洁、更可预测的升级路径。确保新操作系统的默认 Tomcat、JRE 和 PostgreSQL 版本与目标 DHIS2 版本兼容。

有关其他依赖项的版本生命周期和支持时间表的更多详情，请参阅

Ubuntu支持生命周期
PostgreSQL支持和发布时间表
[Tomcat 发布和支持时间表］(https://tomcat.apache.org/whichversion.html)

备份{ #backups }¶

对于任何 DHIS2 升级，包括全面备份在内的稳健后备计划都至关重要。问题可能会出现，而恢复到以前的状态往往是最快的恢复方法。虽然完整的系统快照是最理想的，但数据库备份至少是必不可少的。定期的数据库备份对持续的数据连续性也至关重要。对于操作系统升级，应使用目标操作系统构建新服务器并迁移 DHIS2，而不是执行原地升级。确保新操作系统的默认 Tomcat、JRE 和 PostgreSQL 版本与目标 DHIS2 版本兼容。

执行数据库备份有多种方法，pg_dump 工具是逻辑备份最常用的方法之一。

备份策略{ #backup-strategies }¶

完整操作系统备份/快照： 服务器文件系统和配置的完整快照。这样就可以快速回滚到之前的状态。
数据库备份
- 逻辑备份： （例如，pg_dump）：数据库模式和数据的可移植副本。这是用于将数据库恢复到特定时间点的主要备份。
- 增量备份： 仅备份自上次完整或增量备份以来的更改。这些备份比完整备份更小更快，但需要完整备份作为基础。它们对于更精细的恢复和最小化备份窗口非常有用。

备份存储策略{ #backup-storage-strategy }¶

本地备份： 在灾难恢复中，不建议将备份存储在与 DHIS2 实例相同的机器上，因为这会使备份面临与主系统相同的风险（如磁盘崩溃、服务器故障）。不过，在维护或升级时，本地备份还是很有用的。为提高可靠性，可考虑将本地备份推送到网络附加存储 (NAS) 设备上。
异地存储： 备份应与主服务器分开存储。这可以包括对象存储服务（如 AWS S3、Google 云存储、Azure Blob 存储）、专用备份服务器或其他地理位置不同的地点等解决方案。异地存储可防止整个站点发生灾难。
云备份： 云提供商提供各种备份服务，包括管理备份解决方案和适合备份的存储选项。这些服务通常提供加密、版本管理和自动备份计划等功能。如果您已经在使用云，请考虑将云备份作为全面备份策略的一部分。

升级前需要备份的重要项目。¶

数据库 - 完整的 dhis2 数据库备份，使用 pg_dump 创建
dhis.conf，有时会有数据库加密密码
应用程序静态文件，如自定义徽标等
dhis2.war文件，尤其是如果该文件经过重大定制，请确保有备份。此外，还要注意其版本信息。
做好备份记录。
- dhis2 postgresql、代理和其他重要依赖项的版本
- 创建备份转储所需的时间--有利于计划停机时间。

备份提示：¶

确保有足够的磁盘存储空间来存储本地备份。
使用 df -h 命令检查服务器上的可用磁盘空间。
确保有存储备份的远程位置。它可以是对象存储端点、网络附加存储（NAS），也可以是具有足够存储空间的备份服务器、
版本化 - 考虑使用版本化备份，这样可以还原到特定的时间点，而不仅仅是最新的备份。
加密： 加密备份以保护数据安全，尤其是包含敏感信息的数据。
记录： 记录您的恢复程序，并将其保存在易于访问的位置。这可以在危机期间节省宝贵的时间。
云备份： 利用基于云的备份解决方案，实现可扩展性、冗余性和易用性。
快照备份： 如果基础架构支持快照备份，可使用快照备份创建数据和系统的时间点副本。
压缩： 压缩备份以降低存储要求，加快备份和恢复进程。

备份恢复技巧¶

执行模拟运行 - 在生产系统上恢复之前，在安全的环境中测试流程。
测试恢复：- 定期测试备份还原，记录所需的时间，确保它能按预期运行。只有当你能从中恢复时，备份才有价值。
验证：即使在还原后，也要验证数据是否完好无损，应用程序是否按预期运行。
检查文件权限 - 恢复后，验证文件所有权和权限，防止出现访问问题。
匹配软件版本 - 确保操作系统、数据库和应用程序版本与备份一致，避免出现兼容性问题。

升级前评估服务器资源{ #assessing-server-resouces-before-upgrading }¶

硬件资源需求{ #hardware-resource-requirements }¶

服务器大小（包括 RAM 和 CPU）取决于各种因素，如数据库大小、预期增长和用户数量。通过 Zabbix 和 Munin 等工具定期监控资源利用率有助于确定系统需求。云托管服务器可轻松扩展。在许多拥有数据中心的地区，通常会规定运行空数据库所需的最低资源要求。

确保有一个测试服务器，最好与生产实例的规格相同。生产服务器还应有足够的存储空间，以满足升级前的备份需求。

为成功做好升级准备，请提前规划测试资源。您的基础设施应满足这些要求：

快速存储：DHIS2 的 PostgreSQL 数据库 I/O 密集，需要快速磁盘（固态硬盘）。备份存储可以使用速度较慢、成本效益较高的磁盘。
良好的网络：确保分布式环境和异地备份使用快速网络（最好 1Gbps），以避免备份传输过程中出现延迟。

评估新版本的软件要求{ #assess-software-requirements-for-the-new-version }¶

查看 DHIS2 发行说明，并注意以下要求

需要/建议使用 JRE
需要/建议使用 PostgreSQL
所需的 PostGIS 版本/建议
需要/建议的 Tomcate 版本

请注意，dhis2 可以在所需的依赖版本上运行，但最好在推荐版本上运行。

评估其他依赖项是否需要升级{ #assess-whether-other-dependencies-needs-upgrading }¶

确保

基本操作系统仍受支持，如果不再受支持，其中的其他软件（如 postgresql、nginx 和 Tomcat）往往也会过时。
PostgreSQL 发布周期
Tomcat 支持生命周期

如果需要升级基本操作系统和其他组件，建议采用的方法是建立一个新的环境，例如安装所需的操作系统版本和数据库、

如何评估现有元数据{ #how-do-you-assess-the-existing-metadata }¶

升级失败最常见的原因之一是，现有元数据中的异常在现有版本中可能是 "可接受的"，但在新版本中却会导致错误。利用升级的机会清理元数据是一件非常有用的事情，也有助于避免升级时出现问题。

在测试实例上运行元数据评估脚本（在升级之前）

https://github.com/dhis2/metadata-assessment

能修复多少就修复多少

如何测试{ #how-do-you-test }¶

制作一份清单
让用户参与
识别日志文件中的错误
业绩计量

升级 DHIS2（简版）{ #upgrading-dhis2-short-version }¶

步骤	任务	描述	状态
1	入门	识别所有国家系统和关键定制应用程序，不同实例的版本 - 定制应用程序 - 软件版本（java、tomcat、dhis2、PostgreSQL、nginx/apache2 代理等） - 资源 - 测试服务器的可用性。 - 范围 - 是否包括操作系统和数据库？	- 待定 - 进行中 - 已完成
2	备用电流系统	确定备份环境和所需规格。至少对以下项目进行备份： - DHIS2 数据库、 - 配置文件、 - 自定义应用程序、 - 任何外部集成。备份文件 - 注意备份转储的时间。	- 待定 - 进行中 - 已完成
3	审查 DHIS2 发行说明	阅读新版本的发布说明，了解： - 新功能， - 修正 - 潜在的破坏性更改。
4	设置暂存环境	在暂存环境中复制生产设置。在暂存环境中创建测试用例和测试环境。 - 保持 prod 上的版本不变， - 还原 prod 数据库，注意还原时间 - 确保暂存环境与 prod 环境一样运行。
5	测试升级	在测试过程中让用户参与 - 使用工具此处执行元数据清理 - 执行创建的测试用例 - 测试和验证应用程序和功能 - 修复发现的问题
6	通知利益攸关方	通知所有 DHIS2 用户升级计划和预计停机时间。这可确保所有用户对停机做好准备。
7	创建回滚计划	备份 DHIS2 实例（包括应用程序和数据库），作为数据全部丢失或功能严重受损时的回滚策略
8	升级生产	完成暂存测试后，将升级应用到生产系统。
9	升级后测试	在生产环境中测试主要功能，确保升级后一切正常。
19	监控系统	持续监控系统性能和日志，及早发现任何意外问题。
11	文件流程	记录升级过程、面临的任何挑战、使用的解决方案和吸取的经验教训，供今后参考。
12	收集用户反馈	收集 DHIS2 用户对新版本性能、功能以及升级后可能遇到的问题的反馈意见。

升级日历（示例）{ #the-upgrade-calendar-example }¶

新的 DHIS2 版本一般在 5 月左右发布，您需要

双月	活动	资源影响
四月（发行前）	元数据评估和清理开始测试，可能加入 beta 测试计划	用于元数据清理的人力资源用于测试的服务器资源用于安装的系统管理员资源用于测试的人力资源。
五月（新发行）	测试发布开始规划培训、教员培训、在线材料等。	用于测试的服务器资源用于培训准备和培训 TOT 的人力资源
六月	训练	用于安装的系统管理员资源用于培训的服务器资源提供实体或虚拟培训活动
七月	升级生产	用于安装的系统管理员资源