CapRover项目中自定义HTTPS证书的配置指南

背景说明

CapRover作为一款开源PaaS平台，默认提供了通过Let's Encrypt自动获取SSL证书的功能。但在企业级生产环境中，我们经常会遇到以下特殊需求场景：

1. 服务器位于防火墙后，无法进行Let's Encrypt的域名验证
2. 需要使用企业自签名证书或商业CA颁发的证书
3. 需要统一管理多个应用的SSL证书

核心问题分析

当用户尝试在CapRover管理界面点击"Enable HTTPS"按钮时，系统会触发以下流程：

1. 尝试通过Certbot获取Let's Encrypt证书
2. 验证域名所有权（需要80/443端口可被外部访问）
3. 自动配置Nginx使用新证书

在防火墙限制环境下，这个流程会因无法完成域名验证而失败（错误代码1107）。即使设置了skipVerifyingDomains参数，系统仍会尝试证书获取过程。

解决方案详解

对于使用自定义证书的场景，我们需要绕过CapRover的自动化证书管理，直接修改Nginx配置模板。以下是具体操作步骤：

1. 准备证书文件

将您的证书文件（.crt和.key）上传至服务器，建议存放在统一目录如：

/nginx-shared/certificates/

2. 修改Nginx配置模板

找到CapRover的Nginx应用模板（通常位于/captain/data/nginx-shared），修改SSL相关配置段：

if (s.hasSsl) {
    listen              443 ssl http2;
    ssl_certificate     /nginx-shared/certificates/your_domain.crt;
    ssl_certificate_key /nginx-shared/certificates/your_domain.key;
}

对于需要强制HTTPS的应用，可以将条件判断改为：

if (true) {
    // 保持相同配置
}

3. 配置验证与重载

完成修改后，需要：

1. 验证Nginx配置语法
2. 重载Nginx服务

可以通过CapRover命令行工具执行：

docker service scale captain-captain=0
docker service scale captain-captain=1

最佳实践建议

1. 证书管理：建议使用统一的证书存储位置，便于后续更新维护
2. 配置备份：修改前备份原始模板文件
3. 监控设置：由于绕过了自动续期，需建立证书过期监控机制
4. 安全加固：考虑添加额外的SSL参数如HSTS、OCSP Stapling等

技术原理深度解析

CapRover的HTTPS管理功能实际上包含两个独立部分：

1. 证书获取（Certbot集成）
2. Nginx配置管理

在自定义证书场景下，我们只需要利用其Nginx配置管理能力，而绕过证书获取环节。这种解耦设计使得系统在自动化失效时仍能保持灵活性。

对于企业用户，可以考虑开发自定义插件或脚本，实现：

• 证书自动轮换
• 多域名证书管理
• 证书与密钥的安全存储

通过这种方式，既保持了CapRover的易用性，又能满足企业级安全需求。