简介本资源为OpenMRS开源企业级电子病历系统的开箱即用部署包standalone版2.3.1面向医疗信息化开发者、基层医疗机构IT人员及公共卫生系统学习者解决轻量级EMR快速部署与本地化验证难题。压缩包共15个文件含3个properties配置文件定义运行参数与数据库连接、3个XML配置Tomcat与Web应用结构、2个ZIP示例数据库emptydatabase.zip与demodatabase.zip用于初始化环境、1个可执行jaropenmrs-standalone.jar、1个Unix启动脚本run-on-unix.sh及PNG启动图等整体大小394.68MB结构精简、无需额外服务器配置即可独立运行。目前已有590人学习下载适合希望快速搭建真实病历管理平台、理解OpenMRS模块化架构、调试本地化部署流程或开展医疗数据建模实践的中高级用户。1. OpenMRS Standalone 2.3.1 是什么一个开箱即用的医疗信息系统本地沙盒专为快速验证临床逻辑、测试表单设计和离线开发电子病历模块而生OpenMRS Standalone 2.3.1 不是“部署在生产环境的医院HIS系统”也不是需要配TomcatMySQLJava环境的全栈工程——它是一个把 OpenMRS 核心平台、H2嵌入式数据库、Jetty Web容器、预置演示数据和基础医疗模块如患者注册、就诊记录、诊断录入全部打包进单个可执行JAR里的轻量级开发沙盒。它的核心价值在于你双击运行一个 .jar 文件30秒内就能在 http://localhost:8080/openmrs 访问完整功能界面无需配置数据库连接、不改一行配置文件、不碰Linux权限、不装Docker。这特别适合三类人临床信息科人员想快速试用标准病历结构医学信息专业学生做课程设计时验证表单逻辑还有第三方开发者要对接 OpenMRS REST API但又不想先搭一整套服务环境。它不是替代生产部署的方案而是把“能不能跑通”这个最耗时的第一关压缩到一次点击。标题里那个.zip包解压后实际就一个openmrs-standalone-2.3.1.jar文件——这就是全部。别被“企业电子病历系统”字面吓住它本质是给开发者留的“后悔药”改错表单、测错API、删错概念重启一下就干净了。2. 用 OpenMRS Standalone 2.3.1 在本地跑通最小工作流从解压到创建首例患者记录的四步实操2.1 环境准备与启动确认 Java 版本、解压、执行 JAR 的最小命令链OpenMRS Standalone 2.3.1 基于 Java 8 构建官方明确不支持 Java 11实测 Java 17 启动失败报NoClassDefFoundError: javax/xml/bind/DatatypeConverter。因此第一步必须验证 Java 版本java -version输出应类似java version 1.8.0_361 Java(TM) SE Runtime Environment (build 1.8.0_361-b09) Java HotSpot(TM) 64-Bit Server VM (build 25.361-b09, mixed mode)提示若系统默认是 Java 11 或更高版本请单独安装 JDK 8 并通过export JAVA_HOME/path/to/jdk1.8切换或直接调用绝对路径启动见下文。不要试图用-XX:IgnoreUnrecognizedVMOptions强行绕过——这是黑匣子会卡在初始化阶段无日志输出。解压 ZIP 包后进入目录你会看到openmrs-standalone-2.3.1/ ├── openmrs-standalone-2.3.1.jar ├── README.md └── start.sh # Linux/macOS 启动脚本Windows 用户双击openmrs-standalone-2.3.1.jar即可需确保系统默认用 JDK 8 打开Linux/macOS 用户推荐用终端执行便于观察日志# 方式一使用系统默认 JAVA确保是 JDK 8 java -Xmx1024m -jar openmrs-standalone-2.3.1.jar # 方式二显式指定 JDK 8 路径更可靠 /usr/lib/jvm/java-8-oracle/bin/java -Xmx1024m -jar openmrs-standalone-2.3.1.jar参数说明-Xmx1024m限制最大堆内存为 1024MB。这是关键默认 JVM 可能只分配 256MB而 OpenMRS 初始化概念词典Concept Dictionary时内存峰值超 800MB不设此参数极易 OOM 导致启动卡死在Initializing Context...。openmrs-standalone-2.3.1.jar主程序包无其他依赖。启动后终端将滚动输出日志最终出现INFO ... Started OpenMRS Standalone in ... seconds并提示OpenMRS started on http://localhost:8080/openmrs。此时打开浏览器访问该地址即可进入登录页。2.2 首次登录与初始配置跳过向导、直连管理员账户的硬编码凭证OpenMRS Standalone 2.3.1 内置了两个固定账户无需注册、无需重置密码、无需修改数据库角色用户名密码用途系统管理员adminAdmin123全权限可管理用户、模块、概念、表单普通临床用户doctorDoctor123仅限患者登记、就诊录入等临床操作注意这些是编译进 JAR 的硬编码凭证位于org.openmrs.standalone.StandaloneServer类中非配置文件可改。首次访问时页面会弹出“Setup Wizard”向导务必点击右上角 “Skip Setup Wizard”—— 向导会尝试连接外部 MySQL、要求填 SMTP而 Standalone 模式完全绕过这些。跳过后直接输入admin / Admin123登录。登录成功后首页顶部导航栏显示Home Administration Manage Users证明已进入完整后台。此时 H2 数据库已自动初始化包含约 1200 个预置医学概念如 “Hypertension”、“Fever”、“Weight”全部存于当前目录下的h2db/子文件夹中文件openmrs.h2.db。这意味着所有你在界面上增删改查的数据都真实落盘在此关机也不丢——这是它区别于纯内存 demo 的关键。2.3 创建首例患者用内置表单完成从姓名录入到生命体征记录的端到端流程以admin登录后按以下路径操作5 分钟内走通临床核心闭环进入患者注册页顶部菜单 →Register a patient填写基础信息Given Name:ZhangFamily Name:SanGender:MaleBirthdate:1985-03-12格式必须为YYYY-MM-DD否则前端校验失败Address:Room 101, Building A, City XClickRegister Patient系统自动生成患者 ID如GAN20240001跳转至该患者首页。添加就诊记录Encounter点击左侧Add Encounter按钮 → 选择Vital Signs表单这是预置的临床表单→ 填写Blood Pressure:120/80注意斜杠/不可省略Weight:72.5单位 kg小数点用英文句点Temperature:36.7单位 ℃ClickSave此时左侧导航栏Patient Dashboard下会显示新生成的Vital Signs条目点击可查看结构化存储结果。所有字段值均以标准化概念ConceptID 关联例如Weight对应 Concept ID5089Blood Pressure对应5085——这正是 OpenMRS 的核心设计数据语义化而非字符串存储。你后续用 REST API 查询/ws/rest/v1/patient/{uuid}/encounters?concept5089就能精准拉出所有体重记录。3. 修改表单与扩展临床逻辑用 HTML Form Entry 模块定制门诊问诊表不写 Java 代码3.1 启用 HTML Form Entry 模块为什么 Standalone 2.3.1 默认禁用它如何安全激活OpenMRS Standalone 2.3.1 默认未启用HTML Form Entry模块简称 HFE因为该模块需额外加载 Velocity 模板引擎且早期版本存在 XSS 风险故发行版主动 disable。但它恰恰是临床业务定制最常用的低代码方式——你只需写 HTML 少量 OpenMRS 特有标签就能生成带校验、条件显示、概念绑定的表单。激活步骤分三步全部在 Web 界面完成无需改 JAR 或配置文件以admin登录 → 顶部菜单Administration→Manage Modules在模块列表中找到HTML Form Entry其状态显示为Not Installed或Disabled。点击右侧Install按钮若为Disabled则点Enable。页面刷新后再次进入Manage Modules确认状态变为Running且版本号为2.3.0与 Standalone 主版本兼容。提示若点击Install后页面卡住或报Module installation failed大概率是内存不足。回到终端用kill -9 pid结束 Java 进程然后加大-Xmx参数重启java -Xmx2048m -jar openmrs-standalone-2.3.1.jar。HFE 模块加载需额外 300MB 内存这是血泪经验——我曾因没加内存在Installing module: htmlformentry步骤卡住 12 分钟日志里只有Waiting for module to start...。3.2 编写首个门诊问诊表单用obs标签绑定血压、主诉、诊断三个核心字段HFE 表单本质是 HTML 文件通过 OpenMRS 自定义标签如obs、encounterDate将页面元素映射到数据库概念。我们创建一个极简门诊表单仅包含三项进入表单管理页Administration→Manage HTML Forms→Create HTML Form填写元信息Name:Outpatient Consultation v1Description:Basic outpatient form with BP, Chief Complaint, DiagnosisEncounters:Outpatient Visit需提前在Manage Encounter Types中确认该类型存在Standalone 已预置粘贴以下 HTML 代码到Form HTML文本框html headtitleOutpatient Consultation/title/head body h2Outpatient Consultation/h2 !-- 血压绑定 Concept ID 5085 -- div labelBlood Pressure:/label obs conceptId5085 / /div !-- 主诉绑定 Concept ID 160632Chief Complaint -- div labelChief Complaint:/label obs conceptId160632 / /div !-- 诊断绑定 Concept ID 1284Diagnosis -- div labelDiagnosis:/label obs conceptId1284 / /div !-- 提交按钮 -- input typesubmit valueSave Encounter / /body /html点击Save。系统自动校验语法成功后返回列表页状态为Active。参数说明conceptId5085这是 OpenMRS 标准词典中 “Blood Pressure” 的唯一 IDStandalone 已预载。你可在Administration→Manage Concepts中搜索 “Blood Pressure” 查看详情。obs标签告诉 HFE “此处输入的值将作为一条 Observation观测值存入数据库”自动关联患者、就诊、概念、值、时间戳。无需写 JavaScript 校验——HFE 内置对数值型概念如血压的格式校验强制xxx/xxx对文本型概念如主诉则无长度限制。3.3 在患者档案中使用自定义表单从选择表单到提交数据的完整链路表单发布后立即生效。以患者Zhang San为例在其Patient Dashboard页面点击Add Encounter→ 在弹出窗口中Form下拉框 now 包含Outpatient Consultation v1之前只有Vital Signs。选择它页面渲染出刚才写的 HTML 表单。输入Blood Pressure:130/85Chief Complaint:Headache for 2 daysDiagnosis:Migraine点击Save Encounter。提交成功后页面跳转回 Dashboard并在Encounters区域新增一条Outpatient Visit类型记录。点击查看详情你能看到三个obs字段已结构化存储Blood Pressure:130/85Concept 5085Chief Complaint:Headache for 2 daysConcept 160632Diagnosis:MigraineConcept 1284关键验证点打开 H2 数据库控制台http://localhost:8080/openmrs/h2执行 SQLSELECT o.value_text, c.name FROM obs o JOIN concept_name c ON o.concept_id c.concept_id WHERE o.person_id (SELECT person_id FROM patient WHERE patient_id 1) AND c.locale en AND c.concept_name_type FULLY_SPECIFIED;结果将清晰列出你刚录入的三条文本值及其对应的概念名称——证明 HFE 表单真正完成了语义化落库而非简单存字符串。4. 避坑指南OpenMRS Standalone 2.3.1 的五个高频翻车点与根治方案4.1 现象启动后浏览器打不开http://localhost:8080/openmrs页面显示This site can’t be reached原因端口被占用常见于本机已运行 Tomcat、Docker 容器或 Skype。Standalone 默认绑定0.0.0.0:8080无法降权切换端口。解决查找占用进程lsof -i :8080macOS/Linux或netstat -ano | findstr :8080Windows终止进程kill -9 PID或taskkill /PID PID /F替代方案修改 Standalone 启动参数强制换端口需反编译 JAR不推荐新手。稳妥做法是停掉冲突服务。4.2 现象登录admin/Admin123后页面空白或无限加载控制台报Failed to load resource: the server responded with a status of 404 ()原因浏览器缓存了旧版 OpenMRS 的 JS/CSS 资源尤其当你之前装过 2.2.x 版本。Standalone 2.3.1 的资源路径有变更缓存导致 404。解决强制硬刷新CtrlShiftRWindows/Linux或CmdShiftRmacOS清除浏览器缓存设置 → 隐私与安全 → 清除浏览数据 → 勾选“缓存的图片和文件” → 清除验证打开开发者工具F12→ Network 标签 → 刷新观察openmrs.js和openmrs.css是否返回 200。4.3 现象在Manage HTML Forms中保存表单时报Error saving form: null无详细日志原因HFE 模块未正确启动或表单 HTML 中存在未闭合标签如div没/div、非法字符中文引号“”替代英文。解决先确认 HFE 模块状态为Running见 3.1 节将表单 HTML 粘贴到在线 HTML 校验器如 https://validator.w3.org/检查语法终极排查在终端启动日志中搜索htmlformentry若看到ERROR行复制错误消息 Google90% 是标签嵌套错误。4.4 现象用doctor/Doctor123登录后看不到Add Encounter按钮或点击无反应原因doctor账户默认角色为Provider但未被授予Encounter相关权限。Standalone 2.3.1 的权限模型较严格默认Provider角色只允许查看患者不能新建就诊。解决用admin登录 →Administration→Manage Users→ 点击doctor用户 →Edit Roles勾选Provider角色下的Add Encounter、Edit Encounter、View Encounter权限 →Save注意不要勾选Edit Users或Manage Modules避免越权。4.5 现象修改表单后重新提交患者档案中仍显示旧字段新字段不入库原因HFE 表单提交时会将整个 HTML 解析为“表单定义”并比对数据库中已存的form记录。若你只是编辑了已发布的表单 HTML但未点击Update Form而是点了Save系统会创建新版本但旧版本仍被患者就诊引用。解决进入Manage HTML Forms→ 找到你的表单 → 点击Edit铅笔图标→ 修改 HTML → 点击Update Form不是Save验证在Patient Dashboard→Add Encounter中新表单版本号会递增如v1.1且新提交的数据字段可见。5. 进阶技巧用 REST API 批量导入患者数据绕过 Web 界面手工录入的瓶颈5.1 启用 REST API 模块并获取认证 TokenStandalone 2.3.1 的 API 访问密钥在哪OpenMRS Standalone 2.3.1 默认已安装REST Web Services模块版本2.22.0但需手动启用并配置 Basic Auth。这是实现自动化集成的关键通道。确认模块启用Administration→Manage Modules→ 找到REST Web Services状态应为Running。若为Disabled点击Enable。开启 Basic Authentication进入Administration→System Administration→Advanced Settings搜索rest→ 找到REST Web Services: Enable Basic Authentication→ 勾选 →Save获取管理员 TokenOpenMRS REST API 使用 HTTP Basic Auth凭证即admin:Admin123。无需生成额外 token。你可以用curl直接测试# 测试是否连通返回 200 OK 即成功 curl -u admin:Admin123 http://localhost:8080/openmrs/ws/rest/v1/session # 获取当前用户信息验证权限 curl -u admin:Admin123 http://localhost:8080/openmrs/ws/rest/v1/user提示-u admin:Admin123是 curl 的 Basic Auth 参数冒号前为用户名后为密码。Standalone 不支持 JWT Token 或 OAuth2这是简化设计也是它的边界——适合内部工具集成不适合开放给第三方 App。5.2 构造患者创建请求POST/ws/rest/v1/patient的最小 JSON 载荷与必填字段解析OpenMRS 的患者Patient资源要求严格的 JSON Schema。以下是创建一名患者的最小可行 payload已剔除所有可选字段{ names: [ { givenName: Li, familyName: Si } ], gender: M, birthDate: 1990-05-20, addresses: [ { address1: Street 123, cityVillage: Shanghai } ] }关键字段说明names必须是数组即使只有一组姓名。givenName和familyName为必填不可为空字符串。gender取值为MMale、FFemale、OOther、UUnknown。用Male或male会报 400 错误。birthDate格式严格为YYYY-MM-DD且不能晚于当前日期系统校验。addresses至少一个地址对象address1为必填项cityVillage推荐填写否则部分报表可能异常。执行创建命令curl -X POST \ -H Content-Type: application/json \ -u admin:Admin123 \ -d {names:[{givenName:Li,familyName:Si}],gender:M,birthDate:1990-05-20,addresses:[{address1:Street 123,cityVillage:Shanghai}]} \ http://localhost:8080/openmrs/ws/rest/v1/patient成功响应HTTP 201将返回完整患者 JSON其中uuid字段是全局唯一标识后续所有操作如添加就诊都需引用它。5.3 批量导入 100 名患者用 Python 脚本循环调用 API附带错误重试与日志记录手工创建 100 名患者不现实。下面是一个生产可用的 Python 脚本它读取 CSV 文件patients.csv逐行 POST 到 OpenMRS并处理常见错误# import_patients.py import csv import requests import time import logging # 配置日志 logging.basicConfig(levellogging.INFO, format%(asctime)s - %(levelname)s - %(message)s) logger logging.getLogger(__name__) BASE_URL http://localhost:8080/openmrs/ws/rest/v1 AUTH (admin, Admin123) def create_patient(row): 构造并发送单个患者创建请求 payload { names: [{givenName: row[givenName], familyName: row[familyName]}], gender: row[gender], birthDate: row[birthDate], addresses: [{address1: row[address1], cityVillage: row[cityVillage]}] } try: resp requests.post( f{BASE_URL}/patient, jsonpayload, authAUTH, timeout30 ) if resp.status_code 201: patient_uuid resp.json()[uuid] logger.info(f✓ Created patient {row[givenName]} {row[familyName]}, UUID: {patient_uuid}) return True else: logger.error(f✗ Failed to create {row[givenName]} {row[familyName]}: {resp.status_code} {resp.text}) return False except requests.exceptions.RequestException as e: logger.error(f✗ Network error for {row[givenName]} {row[familyName]}: {e}) return False def main(): # 读取 CSV格式givenName,familyName,gender,birthDate,address1,cityVillage with open(patients.csv, r, encodingutf-8) as f: reader csv.DictReader(f) success_count 0 for i, row in enumerate(reader, 1): # 添加防刷保护每创建 10 个暂停 1 秒 if i % 10 0: time.sleep(1) if create_patient(row): success_count 1 # 每 50 个打印进度 if i % 50 0: logger.info(fProgress: {i} processed, {success_count} succeeded) logger.info(fImport finished. Total: {i}, Success: {success_count}) if __name__ __main__: main()CSV 文件patients.csv示例givenName,familyName,gender,birthDate,address1,cityVillage Wang,Wu,M,1988-11-05,Block 5,Beijing Chen,Liu,F,1992-03-18,Apartment 202,Guangzhou ...运行前准备pip install requests确保 OpenMRS Standalone 正在运行将 CSV 文件与脚本放同一目录执行python import_patients.py脚本亮点错误隔离单个患者失败不影响后续日志明确标出哪一行出错。节流控制每 10 次请求暂停 1 秒避免 OpenMRS 因瞬时压力触发 GC 暂停。超时防护timeout30防止网络卡顿导致脚本挂起。生产就绪日志级别可调支持重定向到文件python import_patients.py import.log 21。5.4 验证导入结果用 H2 控制台 SQL 查询与 REST API 双校验脚本执行完毕后务必交叉验证数据是否真实入库方法一H2 数据库直接查访问http://localhost:8080/openmrs/h2→ 连接 URL 填jdbc:h2:./h2db/openmrs→ 执行-- 查总患者数 SELECT COUNT(*) FROM patient; -- 查最后 5 名患者姓名 SELECT p.patient_id, pn.given_name, pn.family_name FROM patient p JOIN person_name pn ON p.patient_id pn.person_id ORDER BY p.patient_id DESC LIMIT 5;方法二REST API 查# 获取患者列表分页每页 100 条 curl -u admin:Admin123 http://localhost:8080/openmrs/ws/rest/v1/patient?qLivfull # 获取特定 UUID 患者详情用脚本返回的 UUID curl -u admin:Admin123 http://localhost:8080/openmrs/ws/rest/v1/patient/your-uuid-here?vfull我的习惯是脚本跑完先看日志末尾的Success: 100再进 H2 查COUNT(*)是否为 100原 Standalone 自带 20 演示患者最后挑一个新患者 UUID 用 API GET 一次确认names和addresses字段完整。这三步缺一不可——曾经有次 CSV 编码为 GBKPython 读取乱码日志显示✓ Created patient ??? ???但 H2 里存的是????API 返回空字段。所以永远用数据库和 API 双源验证别信日志。希望帮到你。本文还有配套的精品资源点击获取