内网证书安装

目标

产品部署在局域网或专网环境时，服务器通常无法通过 Caddy 自动申请 Let's Encrypt 等公网免费证书。如果安装时选择了 Caddy 内部证书，需要在访问端安装 Caddy 本地根证书，让浏览器信任系统签发的 HTTPS 证书，避免出现“不安全”“证书无效”或“您的连接不是私密连接”等提示。

本节适用于以下场景：

• 使用内网 IP、内网域名或不可公网解析的域名访问系统。
• 安装脚本中选择了“使用 Caddy 自签名证书”或 Caddy internal certificate。
• 管理后台、用户前端或协作链接可以打开，但浏览器提示证书不受信任。

前置条件

• 已完成产品部署，并且服务已经启动。
• 已确认访问地址，例如 https://<APP_DOMAIN>/admin/login 或 https://<APP_DOMAIN>/app/login。
• 可以登录安装服务器并读取安装目录。
• 已明确需要安装证书的终端类型，例如 Windows、macOS、Linux、iOS、Android 或 Firefox。

获取 Caddy 根证书

在安装服务器上找到 Caddy 本地根证书：

$INSTALL_PATH/data/caddy/pki/authorities/local/root.crt

其中 $INSTALL_PATH 是产品安装目录，例如 /opt/sa。可以用以下命令确认文件存在：

ls -l $INSTALL_PATH/data/caddy/pki/authorities/local/root.crt
openssl x509 -in $INSTALL_PATH/data/caddy/pki/authorities/local/root.crt -noout -subject -issuer -fingerprint -sha256

只分发 root.crt 给需要访问系统的用户。不要分发同目录下的私钥文件，也不要把私钥上传到聊天工具、网盘或邮件附件中。

分发建议

将 root.crt 改名为便于识别的文件名，例如：

Sa2web-internal-root-ca.crt

分发给用户时，同时提供以下信息：

项目	说明
证书用途	仅用于信任内网部署的 Sa2web HTTPS 访问
适用地址	https://<APP_DOMAIN>/
证书指纹	使用 openssl ... -fingerprint -sha256 输出的 SHA256 指纹
生效范围	需要访问该系统的办公电脑、测试机或移动设备

如果企业有统一终端管理平台，建议通过域控、MDM、设备管理平台或系统镜像统一下发根证书，避免用户手工安装出错。

Windows 安装

1. 将 root.crt 保存到本机。
2. 双击证书文件，点击“安装证书”。
3. 选择“本地计算机”。如果没有管理员权限，可以选择“当前用户”。
4. 选择“将所有的证书都放入下列存储”。
5. 点击“浏览”，选择“受信任的根证书颁发机构”。
6. 完成导入后，关闭并重新打开浏览器。
7. 重新访问 https://<APP_DOMAIN>/admin/login 验证证书状态。

也可以用管理员 PowerShell 导入到本机根证书库：

Import-Certificate -FilePath .\Sa2web-internal-root-ca.crt -CertStoreLocation Cert:\LocalMachine\Root

macOS 安装

1. 将 root.crt 保存到本机。
2. 双击证书，系统会打开“钥匙串访问”。
3. 将证书导入“系统”钥匙串。
4. 找到该证书，双击打开详情。
5. 展开“信任”，将“使用此证书时”设置为“始终信任”。
6. 输入系统密码保存设置。
7. 退出并重新打开浏览器，再访问系统地址。

如果使用 Chrome、Safari 或 Edge，通常会读取 macOS 系统钥匙串。Firefox 可能需要额外导入，见“Firefox 安装”。

Linux 安装

Debian、Ubuntu 系统：

sudo cp Sa2web-internal-root-ca.crt /usr/local/share/ca-certificates/
sudo update-ca-certificates

RHEL、CentOS、Rocky Linux、AlmaLinux 系统：

sudo cp Sa2web-internal-root-ca.crt /etc/pki/ca-trust/source/anchors/
sudo update-ca-trust

安装后关闭并重新打开浏览器。如果浏览器仍提示不受信任，检查浏览器是否使用自己的证书库，尤其是 Firefox。

Firefox 安装

Firefox 在部分环境中不完全依赖系统证书库，可以直接导入根证书：

1. 打开 Firefox 设置。
2. 进入“隐私与安全”。
3. 找到“证书”，点击“查看证书”。
4. 在“证书颁发机构”页签点击“导入”。
5. 选择 root.crt。
6. 勾选“信任此 CA 来标识网站”。
7. 确认后重启 Firefox。

企业环境也可以启用 Firefox 的企业根证书策略，让 Firefox 信任操作系统证书库。

iOS 与 iPadOS 安装

1. 将 root.crt 通过企业受控渠道发送到设备。
2. 在设备上打开证书文件并安装描述文件。
3. 进入“设置” > “通用” > “VPN 与设备管理”，完成描述文件安装。
4. 进入“设置” > “通用” > “关于本机” > “证书信任设置”。
5. 打开该根证书的“完全信任”开关。
6. 重新打开 Safari 或其他浏览器访问系统地址。

Android 安装

不同厂商入口名称略有差异，通常路径如下：

1. 将 root.crt 保存到设备。
2. 进入“设置” > “安全” > “加密与凭据”。
3. 选择“安装证书”或“安装 CA 证书”。
4. 选择 root.crt 并确认安装。
5. 重新打开浏览器访问系统地址。

部分 Android 版本或企业浏览器可能不信任用户手工安装的 CA 证书。如遇到限制，建议通过 MDM 或设备管理策略下发证书。

验证安装结果

安装完成后，访问以下地址：

https://<APP_DOMAIN>/
https://<APP_DOMAIN>/admin/login
https://<APP_DOMAIN>/app/login

验证标准：

• 浏览器地址栏不再显示证书错误。
• 证书链中可以看到本地 Caddy 根证书。
• 管理后台和用户前端可以正常登录。
• 协作链接在目标访问端也不再提示证书不受信任。

如果需要命令行验证，可以在客户端执行：

curl -I https://<APP_DOMAIN>/

如果客户端系统已经信任该根证书，命令应能正常返回 HTTP 响应头。

证书更新与重装

以下情况需要重新分发并安装根证书：

• 重新安装产品并清空了 $INSTALL_PATH/data/caddy/pki。
• 更换了安装目录或迁移到新服务器后重新生成了 Caddy 内部 CA。
• 人为删除或轮换了 Caddy 本地根证书。
• 用户终端重装系统或清理了受信任根证书库。

升级产品时如果保留了 $INSTALL_PATH/data，通常不需要重新安装根证书。

常见问题

问题	原因	处理方式
浏览器仍提示不安全	证书没有安装到受信任根证书库	按操作系统步骤重新导入，并重启浏览器
只有 Firefox 报错	Firefox 使用了独立证书库	在 Firefox 证书设置中单独导入
手机浏览器仍报错	移动系统未完全信任该 CA	iOS 需要打开“完全信任”，Android 建议用 MDM 下发
访问域名与证书不匹配	访问地址不是安装时配置的域名或 IP	使用安装时配置的系统访问域名，或重新配置证书
找不到 root.crt	Caddy 尚未生成本地 CA 或路径不正确	确认 $INSTALL_PATH，启动服务后再检查该路径
协作用户访问仍报错	协作用户设备未安装根证书	将根证书安装到协作用户实际访问设备

安全注意事项

• 只安装来自管理员确认渠道的根证书。
• 安装前核对 SHA256 指纹，避免安装错误证书。
• 不要分发 Caddy CA 私钥。
• 离职、设备回收或终端报废时，应按企业安全策略移除不再需要的根证书。