1. 环境准备认识你的“工具箱”大家好我是老张在医疗影像IT这块儿摸爬滚打了十来年从早期的胶片到现在的云PACS算是都经历了一遍。今天咱们不聊那些虚的就来点最干的活从源代码开始亲手把dcm4chee-arc-light这个医疗影像归档系统给“搭”起来。我知道一看到“源码编译”、“部署”这些词很多刚接触的朋友可能就头大了感觉像是要面对一堆看不懂的代码和复杂的配置。别慌咱们今天的目标就是“手把手”我踩过的坑、绕过的弯都会给你讲明白保证你跟着做就能跑起来。首先咱们得搞清楚要准备哪些“家伙事儿”。你可以把这想象成要组装一台高性能电脑得先买齐CPU、主板、内存这些配件。部署dcm4chee-arc-light也一样它不是一个独立的软件而是一个运行在复杂环境下的企业级应用。你需要准备以下几个核心组件Java开发环境JDK这是整个系统的“土壤”因为dcm4chee本身就是用Java写的。我推荐使用JDK 11或17这是目前比较稳定且兼容性好的长期支持版本。别用太老的版本可能会遇到奇怪的兼容性问题。应用服务器WildFly你可以把它理解为我们电脑的“操作系统”。Tomcat大家可能更熟悉但WildFly是一个功能更全的Java EE应用服务器dcm4chee需要它提供的一些高级服务比如消息队列、分布式事务管理等。咱们就把它当作一个更强大的Tomcat来用就行。目录服务OpenLDAP这个可能是最陌生的。你可以把它想象成一个专门用来存储“用户名、密码、角色”这些信息的特殊数据库。它的特点是查询速度极快非常适合存储不常变动但需要频繁验证的信息。在dcm4chee里它用来管理用户认证和系统配置信息有点像我们项目里用的Nacos配置中心不过它是基于LDAP协议的。关系型数据库MySQL这个大家都很熟了。dcm4chee的核心业务数据比如患者信息、检查记录、影像存储路径等都存在MySQL里。它是系统的“记忆中枢”。源码本身dcm4che dcm4chee-arc-light这就是我们要编译的“蓝图”。dcm4che是一套处理DICOM标准的底层Java工具库而dcm4chee-arc-light是在此基础上构建的、带Web管理界面的完整归档系统。我建议你先在本地电脑Windows/Mac/Linux都可以上搞一个测试环境内存最好给到8G以上因为WildFly和MySQL跑起来还是挺吃资源的。准备好了这些概念咱们就进入实操环节第一步就是把JDK和MySQL这些基础环境给装好、配好。2. 基础环境搭建打好地基万事开头难但只要把基础打牢了后面就会顺利很多。这一部分咱们一步步来确保每个环节都跑通。2.1 安装与配置JDK首先去Oracle官网或者Adoptium这样的开源站点下载JDK。我个人的习惯是直接下载压缩包.tar.gz或.zip解压到某个目录比如D:\Java\jdk-17这样比较干净不会在系统里留下太多垃圾。接下来是配置环境变量这是让系统知道去哪找Java命令的关键一步。以Windows为例新建系统变量JAVA_HOME值就是你的JDK解压路径比如D:\Java\jdk-17。编辑系统变量Path添加一条新记录%JAVA_HOME%\bin。打开命令行输入java -version和javac -version如果都能正确显示版本号恭喜你第一步成功了。Linux或Mac用户也是类似原理修改~/.bashrc或~/.zshrc文件添加export JAVA_HOME你的路径和export PATH$JAVA_HOME/bin:$PATH即可。2.2 安装与初始化MySQLMySQL的安装过程我就不赘述了用安装包或者Docker都能快速搞定。安装完成后重点是要为dcm4chee创建专用的数据库和用户。用命令行或者MySQL Workbench这样的工具连接上你的MySQL服务然后执行以下SQL语句-- 创建一个专门用于dcm4chee的数据库字符集用utf8mb4以支持更全面的字符 CREATE DATABASE dcm4chee CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci; -- 创建一个用户并授予他对这个数据库的全部权限 -- 请将 your_strong_password 替换成一个你自己设定的复杂密码 CREATE USER dcm4cheelocalhost IDENTIFIED BY your_strong_password; GRANT ALL PRIVILEGES ON dcm4chee.* TO dcm4cheelocalhost; FLUSH PRIVILEGES;这里有个小坑需要注意如果你打算让WildFly应用服务器和MySQL不在同一台机器上那么上面的localhost就需要改成%表示允许从任何主机连接但这样会带来安全风险生产环境一定要谨慎。咱们测试环境用localhost就行。2.3 安装与配置OpenLDAPOpenLDAP的安装方式比较灵活。在Windows上你可以直接下载官方二进制安装包基本上就是一路“下一步”。在Mac或Linux上用包管理器如brew install openldap或者Docker会更方便。我以Docker方式为例因为这样最干净不影响宿主机环境docker run -p 389:389 -p 636:636 \ --name my-openldap \ --env LDAP_ADMIN_PASSWORDsecret \ --detach osixia/openldap:latest这条命令会拉取一个现成的OpenLDAP镜像并运行起来管理员密码设为了“secret”。容器跑起来后LDAP服务就在本地的389端口可用了。不过光有空的LDAP服务器还不行我们还需要把dcm4chee需要的“数据结构”导入进去也就是LDAP的schema文件。这些schema文件定义了dcm4chee中用户、角色、设备等对象该长什么样。你需要从我们后续会下载的dcm4chee-arc-light源码包里找到ldap/schema目录里面有一堆.schema文件如dicom.schema,dcm4chee-archive.schema。把这些文件复制到你的OpenLDAP服务器的schema配置目录下如果是Docker容器可能需要拷贝到容器内或者通过挂载卷的方式。然后修改OpenLDAP的主配置文件通常是slapd.conf或cnconfig的动态配置通过include语句把这些schema文件都加载进去。这个过程稍微有点繁琐但就像盖房子要先画好设计图一样这一步必不可少。3. 获取与编译源码从“蓝图”到“零件”基础环境齐备现在我们来处理核心部分——源码。dcm4che的项目都在GitHub上我们需要编译两个部分底层的dcm4che工具库和上层的dcm4chee-arc-light应用。3.1 编译dcm4che核心库首先打开终端找一个你喜欢的目录把dcm4che的源码仓库克隆下来git clone https://github.com/dcm4che/dcm4che.git cd dcm4che这是一个比较大的项目包含了处理DICOM文件、网络通信、图像压缩等众多模块。进入目录后我们使用Maven进行编译和安装到本地仓库mvn clean install -DskipTests这里我加了-DskipTests参数是为了跳过测试加快编译速度。第一次编译会非常耗时因为Maven需要下载大量的依赖包。我实测下来网络状况好的话也得二三十分钟。如果中间某个模块失败了别急着全部重来可以单独进入那个失败的模块目录再次执行mvn install。这个过程考验耐心泡杯茶等着就好。编译成功后你本地的Maven仓库通常在~/.m2/repository目录下里就会有一大堆org.dcm4che开头的jar包了。这些就是构建上层应用的“砖瓦”。3.2 编译dcm4chee-arc-light应用接下来克隆最终的应用项目git clone https://github.com/dcm4che/dcm4chee-arc-light.git cd dcm4chee-arc-light用IDE如IntelliJ IDEA打开这个项目或者直接在命令行操作。首先我们需要关注一下它的数据库配置。默认情况下项目可能是为PostgreSQL或HSQLDB预配置的。我们需要将它改成我们使用的MySQL。关键文件在configuration/dcm4chee-arc.xml里但现在先不急着改。更直接的方法是修改项目的Maven父POM文件通常是根目录下的pom.xml找到里面关于数据库驱动的profile配置激活MySQL的profile。或者你可以直接找到dcm4chee-arc-5.x.x-mysql这个子模块不同版本路径可能略有不同它本身就是为MySQL准备的。确认你在项目的根目录下然后同样执行Maven安装命令mvn clean install -DskipTests这次编译会打包生成最终的WAR文件一个Java Web应用归档包位置通常在dcm4chee-arc-5.x.x-mysql/target目录下名字类似dcm4chee-arc-5.x.x-mysql.war。这个WAR包就是我们最终要部署到WildFly上的“成品软件”。编译过程中Maven会利用上一步我们安装到本地的dcm4che库所以顺序不能错。4. 配置与整合让“零件”协同工作现在“零件”WAR包有了“操作系统”WildFly和“数据库”MySQL, OpenLDAP也准备好了接下来就是最关键的组装和配置环节。这一步的细节最多也最容易出错咱们慢慢来。4.1 部署与配置WildFly去WildFly官网下载最新的稳定版比如26.x, 27.x解压到一个没有中文和空格的路径比如D:\wildfly。WildFly本身不需要安装解压即用。我们需要做的是为dcm4chee定制一个配置文件。在dcm4chee-arc-light项目的发布包里或者在你编译输出的target目录同级你能找到一个configuration文件夹里面有两个关键的XML文件standalone.xml和dcm4chee-arc.xml。我们把dcm4chee-arc.xml复制到WildFly的standalone/configuration/目录下。这个文件是WildFly运行dcm4chee的专属配置里面预置了数据源、安全域、线程池等大量设置。接下来需要安装一个安全适配器模块。这是因为dcm4chee-arc-light使用了Keycloak一个开源身份认证管理工具进行安全控制。你需要下载对应版本的keycloak-oidc-wildfly-adapter压缩包。在dcm4chee-arc-light的发布包中通常会在jboss-modules目录下提供一个或者你需要根据WildFly版本去Keycloak官网下载。将这个ZIP文件解压会得到一个modules文件夹。将这个modules文件夹整个复制到WildFly的根目录下与WildFly自带的modules合并。现在我们需要修改dcm4chee-arc.xml文件主要是告诉它我们的MySQL和OpenLDAP在哪里。用文本编辑器打开这个文件搜索“MySQL”或“datasource”找到数据源配置部分。你需要修改JDBC连接URL、用户名和密码指向你之前创建的MySQL数据库。大概长这样datasource jndi-namejava:/PacsDS pool-namePacsDS enabledtrue connection-urljdbc:mysql://localhost:3306/dcm4chee?useSSLfalseamp;serverTimezoneUTC/connection-url drivermysql/driver security user-namedcm4chee/user-name passwordyour_strong_password/password /security /datasource同时还要搜索“LDAP”相关配置将bindDN、bindCredential以及baseDN等值修改为你的OpenLDAP服务器地址和管理员信息。这一步配置项比较多一定要仔细核对。4.2 初始化数据库与LDAP数据配置好WildFly后先别急着启动。我们需要用命令行工具向WildFly发送指令让它去创建MySQL的数据表和初始化LDAP中的数据。进入WildFly的bin目录你会看到一个jboss-cli脚本Windows下是jboss-cli.bat。首先启动WildFly服务器但使用我们刚才配置好的文件# Windows standalone.bat -c dcm4chee-arc.xml # Linux/Mac ./standalone.sh -c dcm4chee-arc.xml服务器会在前台启动看到日志里没有明显的ERROR并且最后出现类似WFLYSRV0025:的提示表示启动成功在某个端口默认是8080监听。不要关闭这个终端窗口另外打开一个终端同样进入WildFly的bin目录运行CLI工具连接上正在运行的服务器jboss-cli.bat -c # Windows ./jboss-cli.sh -c # Linux/Mac连接成功后命令行提示符会变成[standalonelocalhost:9990 /]。现在我们需要执行几个准备好的CLI脚本。这些脚本通常位于dcm4chee-arc-light源码包的cli目录下。你需要根据你的实际路径来执行例如# 在jboss-cli的连接状态下执行外部脚本文件 run-batch --fileD:/dcm4chee/dcm4chee-arc-light/cli/add-data-source-mysql.cli run-batch --fileD:/dcm4chee/dcm4chee-arc-light/cli/ldap-setup.cli run-batch --fileD:/dcm4chee/dcm4chee-arc-light/cli/setup.cli这些脚本会做以下几件重要的事在WildFly中注册MySQL的JDBC驱动、创建我们配置中提到的数据源PacsDS、向OpenLDAP中导入初始的管理员用户、角色和系统配置条目。执行每个脚本后留意输出是否有错误。全部成功后在第一个终端运行的WildFly控制台里输入:reload命令让服务器重新加载配置。5. 启动验证与排错点亮系统经过上面一番“折腾”终于到了最激动人心的启动时刻。如果前面的步骤都正确无误现在系统应该已经可以正常工作了。5.1 启动系统并访问确保WildFly服务器正在运行就是我们之前用standalone.bat -c dcm4chee-arc.xml启动的那个。打开你的浏览器访问http://localhost:8080/dcm4chee-arc/ui2/。如果一切顺利你应该会看到dcm4chee-arc-light的Web登录界面。默认的管理员用户名和密码通常在LDAP初始化脚本里设置好了常见的是admin/admin。成功登录后你就进入了系统的管理后台。在这里你可以配置设备AETitle、IP、端口、管理用户、查看归档的影像研究等等。5.2 常见问题与排查思路当然一次成功是理想情况实际部署中多少会遇到些问题。这里我分享几个我踩过的坑和排查方法端口冲突WildFly默认用8080端口如果被别的程序比如你本地的Tomcat占了就会启动失败。可以在dcm4chee-arc.xml里搜索socket-binding修改port的值比如改成8081。数据库连接失败这是最常见的问题。首先确认MySQL服务是否真的在运行。其次检查dcm4chee-arc.xml里数据源的连接URL、用户名、密码是否正确。特别注意密码里是否有特殊字符在XML里可能需要转义。可以在WildFly的管理控制台http://localhost:9990的“Configuration” - “Subsystems” - “Datasources Drivers”里测试连接。LDAP连接失败同样先确认OpenLDAP服务是否运行telnet localhost 389。检查dcm4chee-arc.xml中LDAP安全域security-domain的配置尤其是bindDN管理员账号和bindCredential密码是否正确。密码可能是明文也可能是加密过的要跟LDAP初始化脚本里设置的一致。我推荐使用Apache Directory Studio这个图形化LDAP客户端它能直观地连接到你的OpenLDAP服务器浏览和修改里面的数据是排查LDAP问题的神器。应用部署失败如果WAR包本身有问题在WildFly的启动日志里会看到WFLYCTL0080: Failed services这样的错误。可能是编译时依赖缺失或者WAR包内的配置有误。回头检查Maven编译过程是否有错误并确保使用的是正确的dcm4chee-arc-5.x.x-mysql.war包。内存不足WildFly和MySQL都是内存大户。如果启动过程中很慢或者运行时报OutOfMemoryError需要调整JVM参数。在启动WildFly的脚本standalone.conf或standalone.conf.bat中找到JAVA_OPTS设置增加堆内存例如-Xms2g -Xmx4g。部署完成后你可以尝试用DICOM仿真器比如dcm4che工具包里的dcm4che-tool-storescu发送一张测试影像到系统看看能否成功接收、存储并在Web界面中查询到。这个过程能完整地验证整个PACS工作流是否通畅。