ghcr.io/hakwerk/labca-control:build-arm64

LabCA

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

目录

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

背景

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

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

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

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

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

幸运的是，他们将其应用的核心（称为“Boulder”）作为https://github.com/letsencrypt/boulder/%E6%8F%90%E4%BE%9B%E3%80%82%E4%BD%A0%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%85 Boulder，并在内部使用它来颁发证书。只要组织内的所有客户端机器/笔记本电脑信任你的根 CA 证书，它签署的所有证书都会被自动信任，用户在浏览器中会看到绿色锁图标。

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

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

启动

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

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

确保在要运行 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 环境变量。

设置

基础安装完成后，你必须通过浏览器完成设置。为了让你了解设置过程，请参见以下截图：

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

更新

默认情况下，启动 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

一些常用客户端包括：

• 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 **”，请在本地 DNS 中输入主机名解决。对于 docker compose 日志中出现的“**Could not resolve host: **”也同样处理。

颁发证书时，LabCA/boulder 会检查 DNS 中的 CAA（Certification Authority Authorization，证书颁发机构授权）记录，该记录指定允许为域名颁发证书的 CA。如果出现类似“SERVFAIL looking up CAA for internal”或“CAA record for ca01.foo.internal prevents issuance”的错误，可尝试在 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 证书的组织名称使用 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"，且在 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