ghcr.io/hakwerk/labca-boulder:25.09

LabCA

基于Let's Encrypt(tm)的开源ACME（自动化证书管理环境）实现的内部（实验室）专用私有证书颁发机构。

目录

• 背景
• 启动
• 使用
• 故障排除
• 适用于step-ca的独立版本
• 遗留模式
• 贡献
• 许可协议

背景

越来越多的网站和应用通过HTTPS提供服务，浏览器与Web服务器之间的所有流量均已加密。使用标准HTTP时，（表单）数据未加密，容易被窃听者和黑客监听用户与网站之间的通信。因此，Chrome浏览器现在甚至会警告不安全的纯HTTP网站，以促使用户使用HTTPS。

在较小程度上，这也适用于未公开暴露的内部应用和站点。仅仅因为内部用户可能比公共网站用户具有更高的信任度，并不意味着敏感内容不应得到尽可能多的保护。许多黑客***和数据盗窃都发生在公司内部（无论是虚拟还是实体环境）。此外，任何用户都不应习惯忽略浏览器警告（例如关于自签名证书的警告），即使是内部站点也不例外。

任何用户都不应习惯忽略浏览器警告

对于公共互联网，Let's Encrypt™ 通过以简单且自动化的方式提供免费HTTPS证书产生了重大影响。有许多客户端可用于与其所谓的ACME（自动化证书管理环境）交互。他们还提供测试环境，允许您在颁发受信任证书之前进行调试，并降低触发速率限制的风险。

然而，一个技术要求是需要有一个可公开访问的位置，供客户端应用与其服务器交换信息（至少对于HTTP-01挑战类型是如此，另外还有DNS-01方法）。对于内网/公司内部应用或组织内的测试客户端，这可能并不总是可行的。

幸运的是，他们已将其应用的核心（称为“Boulder”）作为https://github.com/letsencrypt/boulder/%E6%8F%90%E4%BE%9B%E3%80%82%E6%82%A8%E5%8F%AF%E4%BB%A5%E5%9C%A8%E8%87%AA%E5%B7%B1%E7%9A%84%E6%9C%8D%E5%8A%A1%E5%99%A8%E4%B8%8A%E5%AE%89%E8%A3%85Boulder%EF%BC%8C%E5%B9%B6%E5%9C%A8%E5%86%85%E9%83%A8%E4%BD%BF%E7%94%A8%E5%AE%83%E6%9D%A5%E9%A2%81%E5%8F%91%E8%AF%81%E4%B9%A6%E3%80%82%E5%8F%AA%E8%A6%81%E7%BB%84%E7%BB%87%E5%86%85%E7%9A%84%E6%89%80%E6%9C%89%E5%AE%A2%E6%88%B7%E7%AB%AF%E6%9C%BA%E5%99%A8/%E7%AC%94%E8%AE%B0%E6%9C%AC%E7%94%B5%E8%84%91%E9%83%BD%E4%BF%A1%E4%BB%BB%E6%82%A8%E7%9A%84%E6%A0%B9CA%E8%AF%81%E4%B9%A6%EF%BC%8C%E5%AE%83%E7%AD%BE%E7%BD%B2%E7%9A%84%E6%89%80%E6%9C%89%E8%AF%81%E4%B9%A6%E9%83%BD%E4%BC%9A%E8%A2%AB%E8%87%AA%E5%8A%A8%E4%BF%A1%E4%BB%BB%EF%BC%8C%E7%94%A8%E6%88%B7%E4%BC%9A%E5%9C%A8%E6%B5%8F%E8%A7%88%E5%99%A8%E4%B8%AD%E7%9C%8B%E5%88%B0%E7%BB%BF%E8%89%B2%E9%94%81%E5%9B%BE%E6%A0%87%E3%80%82

此外，如果您正在开发自己的客户端应用或将ACME客户端集成到自己的应用中，本地测试ACME会非常有用。互联网上有很多关于设置自己的PKI（公钥基础设施）的信息，但这些通常都不是自动化的。

不过，Boulder的设置和运行有相当大的学习曲线，这正是LabCA的用武之地。它是一个自包含的安装包，在Boulder之上构建了友好的Web GUI，让您可以快速开始使用。所有常规管理任务都可以通过Web界面完成。

启动

[!NOTE] LabCA 依赖于 boulder 引擎，该引擎无法在树莓派（Raspberry Pi）上运行。

[!NOTE] 为使 boulder 引擎能够为 LabCA 机器颁发证书，其主机名必须存在于本地 DNS 中。

确保在要运行 LabCA 的机器上安装了带有 compose 插件的 docker，例如在 Ubuntu/Debian 机器上执行：

sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin

初始设置时，需要导出环境变量 LABCA_FQDN，其值为 FQDN（完全限定域名，即您在浏览器中访问网页时使用的名称）。LabCA 不能仅通过 IP 地址运行，必须存在 DNS 映射。

git clone https://github.com/hakwerk/labca.git
cd labca/build
export LABCA_FQDN=labca.example.com
docker compose up -d

要跟踪日志（尤其是出现问题时）：

docker compose logs -f

所有数据都存储在 docker 卷中，建议将这些卷纳入常规备份。

如果运行 docker compose up 后出现如下错误：

Error response from daemon: failed to create shim task: OCI runtime create failed: runc create failed: unable to start container process: exec: "labca/entrypoint.sh": stat labca/entrypoint.sh: no such file or directory: unknown

则说明您忘记导出 LABCA_FQDN 环境变量。

设置

基础安装完成后，必须在浏览器中完成设置。有关设置过程的大致情况，请参见以下截图：

设置完成后，请务必备份您的根证书和颁发者证书！它们可以从“管理”页面的“证书”选项卡导出。在“备份”选项卡上，您还可以创建服务器相关数据的备份。备份文件应同步到外部位置，不过这超出了本文档的范围。

更新

默认情况下，启动 LabCA 时使用 latest 版本的 docker 镜像标签。如果有更新的镜像版本可用，可以通过以下方式更新到新的 :latest 版本：

cd build
docker compose down
git pull
docker compose pull
docker compose up -d --remove-orphans
docker image prune

或者您可以使用类似 watchtower 的工具自动更新镜像，或使用 Diun 来获取新镜像的通知。

如果您希望使用特定版本的镜像，并且仅在明确需要时才更新，可以将环境变量 LABCA_IMAGE_VERSION 设置为明确的版本号。最简单的方法是在 docker-compose.yml 文件所在目录中使用 .env 文件，例如：

echo "LABCA_IMAGE_VERSION=v25.03"
> labca.env

使用

LabCA 设置完成后，您的实例即可为内部应用提供 HTTPS 证书。

管理员

管理员部分仅对设置开始时创建的用户账户开放。仪表板提供 LabCA 实例当前状态的概览。通过菜单，您可以导航到 ACME 对象（如证书）的详细信息、多个系统日志文件以及各种管理任务（如备份/恢复和更改密码）。

以下截图预览了管理员部分：

ACME 客户端

要为您的应用请求并自动续期证书，您需要使用众多标准 ACME 客户端中的一个。只需确保将服务器主机名配置为您的 LabCA 实例即可。

一些常用客户端包括：

• https://github.com/certbot/certbot
• https://github.com/diafygi/acme-tiny
• https://github.com/lukas2511/dehydrated
• ...

确保将客户端配置为使用服务器URL "[***]"。

公共页面

组织/实验室中的最终用户可以访问LabCA实例的公共页面，以获取一些基本信息，并下载需要安装在每台应信任LabCA实例生成证书的设备上的根证书。以下是公共页面的大致样子：

故障排除

安装后，应用有时可能无法正常启动，且原因可能难以排查。 首先，确保所有六个容器均在运行：

root@testpki:/home/labca/labca# docker compose ps -a
NAME               IMAGE                                  COMMAND                  SERVICE       CREATED        STATUS        PORTS                                                                
labca-bconsul-1    hashicorp/consul:1.15.4                "docker-entrypoint.s…"   bconsul       19 hours ago   Up 14 hours   8300-8302/tcp, 8500/tcp, 8301-8302/udp, 8600/tcp, 8600/udp          
labca-bmysql-1     mariadb:10.5                           "docker-entrypoint.s…"   bmysql        15 hours ago   Up 14 hours   3306/tcp                                                             
labca-boulder-1    hakwerk/labca-boulder:latest           "labca/entrypoint.sh"    boulder       15 hours ago   Up 14 hours   0.0.0.0:4001-4003->4001-4003/tcp, [::]:4001-4003->4001-4003/tcp     
labca-bpkimetal-1  ghcr.io/pkimetal/pkimetal:v1.19.0      "/app/pkimetal"          bpkimetal     15 hours ago   Up 14 hours                                                           
labca-bredis-1     redis:6.2.7                            "docker-entrypoint.s…"   bredis        15 hours ago   Up 14 hours   6379/tcp                                                             
labca-control-1    hakwerk/labca-control:latest           "./control.sh"           control       15 hours ago   Up 14 hours   3030/tcp                                                             
labca-gui-1        hakwerk/labca-gui:latest               "bin/labca-gui"          gui           15 hours ago   Up 14 hours   3000/tcp                                                             
labca-nginx-1      nginx:latest                           "/docker-entrypoint.…"   nginx         15 hours ago   Up 14 hours   0.0.0.0:80->80/tcp, [::]:80->80/tcp, 0.0.0.0:443->443/tcp, [::]:443->443/tcp

出现问题时可检查以下日志文件（所有命令均应在 docker-compose.yml 所在目录中运行）：

• docker compose exec control cat /etc/nginx/ssl/certbot.log
• docker compose exec control cat /opt/logs/commander.log（如果存在）
• docker compose logs control
• docker compose logs boulder
• docker compose logs labca
• （可能需要）docker compose logs nginx

常见错误消息

如果在 certbot.log 中看到“**No valid IP addresses found for ”（未找到的有效IP地址），请在本地DNS中输入主机名解决。对于 docker compose 日志中的“**Could not resolve host: ”（无法解析主机：）错误，解决方法相同。

颁发证书时，LabCA/boulder 会检查DNS中的CAA（证书颁发机构授权）记录，该记录指定允许为域名颁发证书的CA。如果遇到类似“SERVFAIL looking up CAA for internal”（查找 internal 的 CAA 记录时出现 SERVFAIL）或“CAA record for ca01.foo.internal prevents issuance”（ca01.foo.internal 的 CAA 记录阻止颁发证书）的错误，可尝试在DNS域中添加如下记录：

foo.internal. CAA 0 issue "foo.internal"

issue字段的值应为LabCA实例的域名，而非主机名。此值可在 va.json 文件的 issuerDomain 属性中找到：

docker compose exec boulder grep "issuerDomain" /opt/boulder/labca/config/va.json

另请参见 Let's Encrypt™ CAA 页面。

如果起初一切正常，但成功颁发两个证书后遇到速率限制，请确保在（配置选项卡的管理部分中的）白名单/锁定域列表中包含所有要使用的子域。例如，如果要为 abc.dev.lan、def.dev.lan 以及 xyz.home.lan 颁发证书，则应同时包含 dev.lan 和 home.lan。在此示例中仅使用 lan 将触发速率限制。

将现有CA证书导入为LabCA根证书时，生成颁发证书可能会出现错误“The organizationName field is different between CA certificate (MyOrg) and the request (MyOrg)”（CA证书（MyOrg）和请求（MyOrg）的organizationName字段不同）。尽管显示的名称看似相同，但这意味着在二进制层面，导入的CA证书对组织名称使用PRINTABLESTRING，而LabCA使用的openssl使用UTF8STRING。可通过命令 openssl asn1parse -in data/root-ca.pem 和 openssl asn1parse -in data/issuer/ca-int.csr 验证这一点。此时应使用现有CA自行生成颁发证书，然后一并上传。

如果在 boulder 日志中看到“failed to load chain.: failed to load certificate "labca/certs/webpki/issuer-01-cert.pem"”（无法加载链：无法加载证书 "labca/certs/webpki/issuer-01-cert.pem"），且在 gui 日志中看到“Root key file not present on the system: cannot upgrade automatically!”（系统上不存在根密钥文件：无法自动升级！）：过去曾支持将LabCA根私钥离线存储，仅在需要时通过GUI上传。自 v25.02 版本起，此功能不再支持：根CA密钥必须存在于系统中。如果尝试升级没有根CA密钥在线的现有LabCA安装，升级将失败！解决方法是要么全新安装LabCA并导入包含密钥的证书，要么继续使用旧版本。系统变更使得未来难以支持根CA密钥离线模式。

[!NOTE] 尽管LabCA力求尽可能健壮，但使用风险自负。如果您依赖它，请确保您清楚自己在做什么！

step-ca 独立版本

遗留模式

有关旧版 install 脚本安装方法，请参见 master 分支上的 https://github.com/hakwerk/labca/blob/master/README.md%E3%80%82

贡献

许可

"Commons Clause" 许可条件 v1.0

许可方根据本许可（定义如下）向您提供本软件，但需遵守以下条件。

在不限制许可中其他条件的前提下，许可授予的权利不包括、且许可不向您授予“销售”本软件的权利。

就上述而言，“销售”指行使许可授予您的任何或所有权利，向第三方提供产品或服务（无论是收费还是其他对价，包括但不限于与本软件相关的托管或咨询/支持服务费用），且该产品或服务的价值全部或主要源自本软件的功能。许可要求的任何许可通知或归属声明还必须包含本 Commons Clause 许可条件通知。

软件：LabCA

许可：Mozilla Public License 2.0

许可方：https://github.com/hakwerk