OpenMRS电子病历系统

版本选择指南

重要提醒：O3 和 2.x 可以同时运行，因为它们使用不同端口。如果你不确定，可以先部署 O3 体验现代界面-14。

步骤一：环境准备

确保服务器满足以下条件：

• 内存：至少 8GB（官方论坛的部署指南明确建议 8GB+ RAM）-11
• 磁盘：至少 5GB 可用空间（Docker 镜像约 2-3GB）-9
• Docker：已安装 Docker Engine 和 Docker Compose
• 网络：能访问 Docker Hub

验证环境：

docker --version
docker compose version

Windows 用户注意：需要使用 PowerShell（以管理员身份运行），并确保 Docker Desktop 显示绿色“running”状态-11。

步骤二：创建项目目录

mkdir -p /opt/openmrs-o3
cd /opt/openmrs-o3

步骤三：创建 docker-compose.yml

O3 的部署需要四个核心服务：gateway（反向代理）、frontend（前端）、backend（OpenMRS 后端）、db（MariaDB 数据库）。

在项目目录下创建 docker-compose.yml：

version: '3.7'

services:
  gateway:
    image: openmrs/openmrs-reference-application-3-gateway:3.0.0-beta.20
    restart: unless-stopped
    depends_on:
      - frontend
    ports:
      - "8082:80"

  frontend:
    image: openmrs/openmrs-reference-application-3-frontend:3.0.0-beta.20
    restart: unless-stopped
    environment:
      SPA_PATH: /openmrs/spa
      API_URL: /openmrs
      SPA_CONFIG_URLS: /openmrs/spa/config-core_demo.json
      SPA_DEFAULT_LOCALE: en
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost/"]
      timeout: 5s
    depends_on:
      - backend

  backend:
    image: openmrs/openmrs-reference-application-3-backend:3.0.0-beta.20
    restart: unless-stopped
    depends_on:
      - db
    environment:
      OMRS_CONFIG_MODULE_WEB_ADMIN: "true"
      OMRS_CONFIG_AUTO_UPDATE_DATABASE: "true"
      OMRS_CONFIG_CREATE_TABLES: "true"
      OMRS_CONFIG_CONNECTION_SERVER: db
      OMRS_CONFIG_CONNECTION_DATABASE: openmrs
      OMRS_CONFIG_CONNECTION_USERNAME: openmrs
      OMRS_CONFIG_CONNECTION_PASSWORD: openmrs
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/openmrs"]
      timeout: 5s
    volumes:
      - openmrs-data:/openmrs/data

  db:
    image: mariadb:10.11.7
    restart: unless-stopped
    command: "mysqld --character-set-server=utf8mb4 --collation-server=utf8mb4_general_ci"
    healthcheck:
      test: 'mysql --user=openmrs --password=openmrs --execute "SHOW DATABASES;"'
      interval: 3s
      timeout: 1s
      retries: 5
    environment:
      MYSQL_DATABASE: openmrs
      MYSQL_USER: openmrs
      MYSQL_PASSWORD: openmrs
      MYSQL_ROOT_PASSWORD: openmrs
    volumes:
      - db-data:/var/lib/mysql

volumes:
  openmrs-data:
  db-data:

关键配置说明：

安全警告：以上配置使用了默认弱密码，仅适用于本地测试。任何暴露到公网的部署都必须修改所有密码。

步骤四：启动服务

docker compose up -d

首次启动会拉取约 2-3GB 的镜像，可能需要几分钟。启动后检查状态：

docker compose ps

所有服务应显示 Up 或 healthy。查看后端日志确认启动完成：

docker compose logs -f backend

等待看到类似 OpenMRS is ready 或 Server startup 的消息。

步骤五：访问系统

在浏览器中打开：

http://你的服务器IP:8082/openmrs/spa

默认登录凭据：

• 用户名：admin
• 密码：Admin123?

登录后立即修改密码。

常见问题：如果访问出现 404 或空白页，等待 1-2 分钟让后端完全初始化。O3 的前端和后端分离，首次启动时后端需要更长时间完成数据库迁移和模块加载。

步骤六：初始配置

登录后，建议完成以下配置：

修改管理员密码：在“我的账户”设置中修改。

了解概念字典：这是 OpenMRS 的核心。进入系统管理区域，查看“概念字典”的结构，理解如何定义临床数据项。对于测试用途，O3 参考应用已经预置了一些概念。

探索 O3 引导教程：O3 内置了 8 个交互式教程，首次使用时系统会引导你完成患者注册、记录生命体征等核心操作。这是最快了解系统的方式。

后续维护命令

查看所有服务日志：

docker compose logs -f

查看特定服务日志：

docker compose logs -f backend
docker compose logs -f db

停止服务：

docker compose down

重启服务：

docker compose restart

更新到新版本：

docker compose pull
docker compose up -d

数据库备份（生产环境必做）：

docker compose exec -T db mysqldump -uopenmrs -popenmrs openmrs > backup-$(date +%Y%m%d-%H%M%S).sql

恢复数据库：

docker compose exec -T db mysql -uopenmrs -popenmrs openmrs < backup-20260101-120000.sql

备份建议：设置每日自动备份，并将备份文件存储到服务器之外的介质（如 S3、NAS）。医疗数据丢失的代价极高-5。

常见问题速查

问题：访问 http://localhost:8082/openmrs/spa 显示空白页？
等待后端完成初始化。查看 docker compose logs -f backend，确认看到 OpenMRS is ready 后再访问。如果持续空白，尝试硬刷新（Ctrl+Shift+R）。

问题：想用 HTTPS？
O3 官方提供了 SSL 配置方案。在项目根目录创建 .env 文件：

COMPOSE_FILE=docker-compose.yml:docker-compose.ssl.yml
SSL_MODE=dev

开发模式会生成自签名证书，访问 https://localhost/openmrs/spa。生产模式使用 Let‘s Encrypt，需设置 SSL_MODE=prod、CERT_WEB_DOMAINS 和 CERT_CONTACT_EMAIL。

问题：数据库连接失败？
检查 db 容器的健康状态。如果健康检查失败，查看日志 docker compose logs db。常见原因是密码不匹配或数据库初始化未完成。

问题：想同时运行 2.x Legacy 版本？
2.x 使用端口 8080，O3 使用 8082，不冲突。可以分别部署，互不影响。

问题：如何添加中文界面？
O3 支持多语言。登录后在账户设置中切换语言。中文翻译的完整度可能有限，社区在持续完善中。

问题：内存不足怎么办？
8GB RAM 是官方论坛建议的最低值。如果服务器内存不足，O3 可能启动失败或运行缓慢。考虑增加内存或使用云服务器。