keyfactor/ejbca-ce

EJBCA Community Edition Docker镜像文档

镜像概述和主要用途

EJBCA Community Edition（EJBCA CE）是一款开源的公钥基础设施（PKI）和证书颁发机构（CA）软件，是运行时间最长的CA软件项目之一。EJBCA平台独立，可满足从证书注册、证书管理到证书验证的全流程需求。

EJBCA基于Java开发，可在OpenJDK等JVM上运行，支持Linux、Windows等多数平台。EJBCA分为两个版本：

• EJBCA Community（EJBCA CE）：免费开源，通过OSI认证的开源软件
• EJBCA Enterprise（EJBCA EE）：商业版本，通过通用标准（Common Criteria）认证

最低系统要求：

• 至少2个CPU核心
• 至少1GB内存

核心功能和特性

基础PKI功能

EJBCA实例可部署用于以下一种或多种场景，支持从小型到超大型部署：

证书颁发机构（CA）

• 为设备、人员及其他实体颁发完全可定制的X.509证书
• 证书可用于提供安全性、身份验证、安全通信（如TLS/DTLS）或证明IoT设备的真实性
• 支持标准化的颁发、吊销等PKI协议，实现平滑集成和高度自动化

验证机构（VA）

• 回答证书是否有效的问题
• 支持在线证书状态协议（OCSP）进行在线检查
• 支持证书吊销列表（CRL），适用于间歇性联网或隔离环境

注册机构（RA）

• 自助服务门户，可将证书管理权限部分或全部委托给组织内的授权团队成员

使用场景和适用范围

EJBCA适用于需要建立和管理PKI的各类场景，包括但不限于：

• 企业内部PKI：为员工、服务器、网络设备颁发证书，实现身份认证和加密通信
• IoT设备认证：为物联网设备颁发唯一证书，确保设备身份和数据传输安全
• SSL/TLS证书管理：为网站、应用服务颁发和管理TLS证书，保障HTTPS通信
• 文档签名：提供数字签名证书，用于文档、代码等的真实性和完整性验证
• 大型分布式系统：支持集群部署，适用于超大规模PKI基础设施需求

使用方法和配置说明

获取镜像

通过Docker命令直接拉取最新EJBCA Community镜像：

bash
sudo docker pull keyfactor/ejbca-ce

快速启动

临时测试实例（无认证访问）

启动临时测试实例，允许无认证网络访问管理系统：

bash
docker run -it --rm -p 80:8080 -p 443:8443 -h mycahostname -e TLS_SETUP_ENABLED="simple" keyfactor/ejbca-ce

说明：

• --rm：容器停止后自动删除
• -p 80:8080：映射HTTP端口（8080容器内→80主机）
• -p 443:8443：映射TLS端口（8443容器内→443主机）
• -h mycahostname：设置容器主机名
• TLS_SETUP_ENABLED="simple"：生成管理CA和服务器TLS证书，但允许任何人通过HTTPS管理系统（仅用于测试，生产环境禁用）

容器完全启动后，访问 https://mycahostname:443/ejbca/adminweb/ 进入管理界面。

经典工作流（客户端证书认证访问）

启动需要客户端证书认证的实例：

bash
docker run -it --rm -p 80:8080 -p 443:8443 -h mycahostname -e TLS_SETUP_ENABLED="true" keyfactor/ejbca-ce

说明：

• TLS_SETUP_ENABLED="true"：首次启动时生成管理CA，为服务器和初始管理员生成客户端TLS证书
• 容器启动后，控制台会输出管理员证书的注册信息，需将证书导入浏览器
• 重启浏览器（或使用隐私窗口）访问 https://mycahostname:443/ejbca/adminweb/，通过客户端证书认证

环境变量配置

容器行为可通过环境变量自定义，以下为关键配置：

安全参数

生产环境必须自定义以下安全相关密码：

设置示例：

bash
docker run -it --rm -p 80:8080 -p 443:8443 -h mycahostname \
  -e PASSWORD_ENCRYPTION_KEY="myrandomkey" \
  -e CA_KEYSTOREPASS="anotherrandomkey" \
  -e EJBCA_CLI_DEFAULTPASSWORD="randompassphrase" \
  keyfactor/ejbca-ce

其他重要环境变量

通过 docker inspect keyfactor/ejbca-ce:latest 可查看所有环境变量及默认值，常用变量包括：

外部数据库配置

EJBCA支持外部数据库实现集群部署，默认使用内置H2数据库（仅适合测试），生产环境建议使用MariaDB/MySQL或PostgreSQL。

数据库连接URL格式

使用外部数据库示例（MariaDB）

bash
docker run -it --rm -p 80:8080 -p 443:8443 -h mycahostname \
  -e TLS_SETUP_ENABLED="true" \
  -e DATABASE_JDBC_URL="jdbc:mariadb://172.26.0.1:3306/ejbcatest?characterEncoding=UTF-8" \
  -e DATABASE_USER="ejbca" \
  -e DATABASE_PASSWORD="password" \
  keyfactor/ejbca-ce

注意：首次启动时会自动创建数据库表结构，后续启动将复用现有数据。

代理后端配置

适用于在反向代理（如Nginx、Apache Httpd）后部署，需禁用容器内部TLS配置，通过代理处理TLS。

关键配置变量

说明：配置代理后会禁用管理CA创建，需手动配置EJBCA。

邮件通知配置

EJBCA通过JavaMail服务发送邮件通知，可通过环境变量配置SMTP参数：

Gmail SMTP示例：

bash
docker run -it --rm -p 80:8080 -p 443:8443 -h mycahostname \
  -e TLS_SETUP_ENABLED="simple" \
  -e SMTP_DESTINATION="smtp.gmail.com" \
  -e SMTP_DESTINATION_PORT="587" \
  -e SMTP_USERNAME="user@gmail.com" \
  -e SMTP_PASSWORD="userssecretpassword" \
  -e SMTP_FROM="user@gmail.com" \
  -e SMTP_SSL_ENABLED="false" \
  keyfactor/ejbca-ce

重要目录说明

以下目录用于持久化数据、配置和密钥，生产环境建议通过Docker卷挂载：

Docker部署示例

1. 使用外部H2数据库卷持久化数据

bash
# 创建卷
docker volume create ejbca-persistent-data

# 启动容器，挂载卷
docker run -it --rm -p 80:8080 -p 443:8443 -h mycahostname \
  -v ejbca-persistent-data:/mnt/persistent \
  keyfactor/ejbca-ce

2. 自定义HTTPS端口

bash
# 映射主机9443端口到容器8443端口
docker run -it --rm -p 80:8080 -p 9443:8443 -h mycahostname keyfactor/ejbca-ce

修复静态链接端口：
创建web.properties文件，设置httpserver.external.privhttps=9443，挂载到容器：

bash
docker run -it --rm -p 80:8080 -p 9443:8443 -h mycahostname \
  -v $PWD/config/web.properties:/opt/primekey/ejbca/conf/web.properties \
  keyfactor/ejbca-ce

3. 挂载外部插件

bash
# 创建插件目录并放入JAR文件
mkdir -p ejbca-plugins && cp my-plugin.jar ejbca-plugins/

# 启动容器，挂载插件目录
docker run -it --rm -p 80:8080 -p 443:8443 -h mycahostname \
  -v $PWD/ejbca-plugins:/opt/primekey/ejbca/plugins \
  keyfactor/ejbca-ce

社区支持与资源

社区支持

• 社区贡献：开源项目，欢迎贡献代码和文档
• 支持方式：无SLA，基于社区最佳努力支持
• 参与渠道：EJBCA社区指南

商业支持

EJBCA Enterprise版本提供商业支持，详情见EJBCA Enterprise。

教程资源

• ***教程：KeyfactorCommunity频道，包括：
  • EJBCA Docker容器快速启动
  • Kubernetes部署EJBCA容器
  • 使用Helm部署EJBCA
• 文档：EJBCA官方文档

许可证

EJBCA Community版基于LGPL许可证开源。