常见问题

关于产品

CertHub 真的完全免费吗？

是。没有付费、授权、套餐、钱包、邀请返佣等任何商业模块，也不限制流水线数量、站点监控数量、通知渠道数量。可以自由私有化部署。

开源协议是什么？

GPL-3.0。可以自建、可以改、可以内部使用；对外分发衍生作品时需要同样开源。

需要什么环境？

Python 3.11+，一个端口（默认 8000）。构建前端时额外需要 Node.js 18+，但服务器可以直接用构建好的产物。

支持多用户吗？

支持。角色两级（管理员 / 普通用户），数据按用户隔离，另有「用户组」可以按功能键授权（例如只给流水线权限、不给凭据权限）。自助注册默认关闭，需要时在系统设置里打开。

关于证书

支持哪些证书颁发机构？

通过 ACME 对接 Let's Encrypt、Google Trust Services、ZeroSSL、FreeSSL / LiteSSL、Buypass 与自定义 CA；另外支持阿里云、腾讯云、火山引擎的免费证书，TrustAsia 商业证书，本地自签与自有证书导入。完整清单见 生态集成。

泛域名怎么配？

用 DNS-01 验证（HTTP-01 不支持泛域名），域名写 *.example.com，同时把 example.com 也加进域名列表，否则主域不在证书覆盖范围内。

会不会重复申请触发限流？

不会。证书任务有「提前续期天数」（默认 20 天），没到续期时间会自动跳过签发，复用证书库里的证书。定时任务设成每天跑是安全的。

云厂商免费证书有什么限制？

阿里云 / 腾讯云是 3 个月的单域名 DV，火山引擎以控制台为准，都受账号免费额度限制，额度用尽会直接返回业务错误。泛域名请走 ACME。

证书能导出成什么格式？

PEM、DER、PFX（PKCS#12）、P7B、JKS、Nginx 格式，可只导证书或只导私钥。JKS 需要服务器装了 JDK（keytool），没装时建议改用 PFX。

关于部署

能部署到哪些地方？

75 个内置插件：主机与中间件、面板、集群、云 CDN、对象存储，以及 Webhook / 脚本 / 命令等通用任务。完整清单见 部署目标。

内网机器能部署吗？

能。用主机 SSH 授权，从平台所在的机器连过去即可。注意内网地址不要走 HTTP 代理（插件内部已经处理了这点）。

我的平台不在清单里怎么办？

三条通用路径：主机 SSH + 自定义重载命令、Webhook 推给自有系统、在目标主机执行脚本。也可以按 新增插件 自己加一个。

关于安全

为什么接口里能看到明文密钥？

这是刻意的设计：打码会让用户以为「没保存」，排障时也无法确认到底填了什么。所以数据库里 AES-GCM 加密存储，接口按设计明文返回，界面上的密码框默认星号、点「小眼睛」才显示明文。

代价是：数据库文件与备份文件必须当机密文件对待。

编辑时把密码框清空会丢密钥吗？

不会。留空表示「这一项没改」，后端会还原旧值，绝不会把密钥写成空串。

有没有两步验证和审计日志？

有。支持 TOTP 两步验证（扫码绑定）、登录失败锁定、图形验证码、登录提醒，以及记录关键操作的审计日志。

关于数据

数据存在哪里？

默认 backend/data：certd.db（数据库）、certs/（证书文件）、secret.key（加密密钥）。可以用 CERTD_DATA_DIR 改。

怎么备份？

cd backend && python tools/backup.py --dir /data/backup/certhub --keep 30

包含数据库、证书文件与 secret.key。恢复用 --restore，会先把当前库另存一份。详见 备份与升级。

升级会丢数据吗？

不会。数据目录与代码分离，升级只替换代码。但升级前请先备份，尤其是要固定 CERTD_SECRET_KEY / 保留 secret.key。

关于接口

有 API 吗？

有。登录态接口用 Authorization token；给脚本 / CI 用的开放接口用 API 密钥（x-api-key + x-api-secret），可以列流水线、触发运行、读证书。见 架构与目录。

能对接我自己的监控系统吗？

GET /api/health 返回数据库、磁盘、调度器状态，异常时返回 503，可以直接给 Uptime Kuma / 云监控用。

---

没找到答案？看 故障排查，或在 GitHub 仓库提 issue（带上执行历史里的完整日志）。