小陈-SSL管家 · 使用说明
版本 4.9.x ｜ 适用于单机部署（宝塔 / 自建 LNMP 均可） 平台定位：SSL 证书代签 / 转售的一站式托管 —— 签发、续签、部署到客户服务器、到期提醒，全流程自动化。
1. 平台能做什么
| 能力 | 说明 |
|---|---|
| 一键签发 | 提交域名（单域名 / 泛域名 / 多域名），通过 ACME（Let's Encrypt）签发 90 天证书 |
| 自动续签 | 到期前 30 天平台自动续签（每日巡检），网站全程无感 |
| 自动部署 | 新证书自动推送到客户服务器并重载 Nginx，三种通道可选（见 §6） |
| 部署自检 | 平台对客户站点做真实 TLS 握手验证，部署是否成功一目了然 |
| 告警通知 | 签发失败 / 即将到期 / 部署失败 / 服务器失联，企业微信 / 邮件推送 |
| 开放 API | 客户可用令牌自助拉取证书、回执部署结果 |
客户的全部操作只有三件：① 永久加一条 CNAME 解析；② 装一次自动部署（或对接宝塔）；③ 之后什么都不用做。
2. 环境要求与安装
2.1 服务器要求
- PHP 8.x（需启用
exec / shell_exec / putenv、openssl、curl扩展） - MySQL 5.7+（库名 / 账号建议与站点同名，便于识别）
- Nginx（宝塔环境自带；自建需可执行
nginx -t与 reload） - 出网正常（需访问 Let's Encrypt 与 DNS 服务商 API）
2.2 安装步骤
- 上传代码到站点目录，配置
config.php（数据库连接、APP_NAME、ACME_HOME、验证域等）。 - 浏览器访问任意页面 —— 所有数据表自动创建，后续升级的新表 / 新列也会自动迁移，无需手工 SQL。
- 用默认管理员登录：
admin / admin123（登录后立即改密码）。 - 进入「系统设置」：
- 开启开放 API（自动部署与 API 功能的前提）；
- 配置 DNS 服务商凭据（如阿里云 AccessKey，存放于
data/dns.env，0600 权限）。
- 配置续签巡检 cron（关键！不配就不会自动续签）：
0 3 * * * su -s /bin/sh www -c "php /www/wwwroot/你的站点/cron/renew.php"⚠️ 必须以 www 身份运行（与 Web 进程一致）。root 身份运行会造成 acme 目录属主撕裂，导致后续续签报
Permission denied（平台已内置fixPerms()自愈，但仍建议口径统一）。
3. 快速上手（管理员）
- 客户管理 → 新建客户（或生成邀请码让客户自助注册）。
- 域名管理 → 添加域名，归属到客户，填写服务期等售卖信息。
- 对域名发起签发：
- 通用场景：客户在 DNS 里加一条永久 CNAME：
_acme-challenge.客户域名 → 验证域（验证域见系统设置，如auth.zeiot.net）； - 便捷场景：客户域名与平台在同一 DNS 账号（如都在你的阿里云里）时，免 CNAME 直接签。
- 通用场景：客户在 DNS 里加一条永久 CNAME：
- 签发完成（约 1 分钟），证书进入「证书下载」，客户即可部署。
- 引导客户开启自动部署（§6），之后续签自动换新。
4. 管理员功能一览
| 菜单 | 用途 |
|---|---|
| 总览 | 域名 / 证书 / 客户概况，近期动态 |
| 客户管理 | 客户增删改、查看登录记录（弹窗固定显示最近 6 条） |
| 域名管理 | 域名、SAN、状态、所属客户；支持按"客户显示名"搜索 |
| 续签日志 | 每次签发 / 续签的完整记录与失败原因 |
| 续费看板 | 按服务期查看续费节奏（日历视图） |
| 部署看板 | 各域名自动部署通道、最近签到 / 部署结果、失联清单、手动巡检 |
| 运营健康 | 存量证书到期分布、失败率等运营指标 |
| 审计中心 | 域名变更 / 账号登录 / 操作留痕；管理员账号统一显示「管理员」 |
| 告警通知 | 企微 / 邮件配置、事件开关、模板自定义、测试发送 |
| 客服设置 | 用户端在线客服代码 |
| 邀请码 | 生成注册邀请码（含可签配额） |
| 系统设置 | 开放 API 开关、验证域、DNS 凭据等 |
| 数据备份 | 数据库备份下载 |
4.1 两步验证（2FA）
- 管理员可在「两步验证」页用验证器 App（Google Authenticator 等）开启 TOTP。
- 登录验证码页可勾选「记住本设备 7 天」：7 天内该设备登录只输密码（天数由
TRUST_DEVICE_DAYS配置，0= 关闭此功能）。 - 「已记住的设备」卡片可单台 / 全部撤销；改密码或关闭 2FA 会自动撤销全部信任设备。
- 验证码连错 5 次锁定 5 分钟。
5. 客户端功能一览
| 菜单 | 用途 |
|---|---|
| 总览 | 名下域名与证书状态 |
| 我的域名 | 域名列表、服务期 |
| 自助申请 | 凭邀请码配额提交申请（默认泛域名类型） |
| 证书下载 | 下载 zip / nginx 拼接格式 / 各类单独文件；下载留痕 |
| 部署自检 | 真实 TLS 握手检测任意名下域名（含证书链、有效期、是否本平台证书） |
| 自动部署 | 三通道配置与部署记录（§6） |
| API 接口 | 令牌管理、接口说明（默认折叠） |
域名状态：
pending 待申请 → issued 已签发 → 约 60 天时自动续签 → 循环；失败会记录原因并告警。
6. 自动部署（三种通道）
三条通道可并存，按客户环境选；平台默认按「宝塔 → 接收端」顺序自动分派推送。
6.1 方式一 · agent 自查（拉模式，通用性最强）
客户在服务器执行一条命令（平台页面一键生成）：
curl -fsSL "https://平台域名/index.php?m=agent&p=install" | sudo sh -s -- \
--token=<部署令牌> --domain=abc.com --check=分钟数 --api="https://平台域名/index.php?m=api"- 安装到
/opt/ssl-agent/，自动识别站点证书路径（宝塔优先），装好计划任务后完全免维护。 - 自查频率：默认半个月（每月 1、16 号）；可选 5 分钟 ~ 15 天（安全上限：必须明显小于 30 天的提前续签期，超限服务端自动夹取）。改频率 = 重新生成命令再执行一次。
- 工作逻辑：读本机证书指纹 → 与平台比对 → 一致直接退出（零下载） → 不一致才下载 → 备份旧证书 → 替换 →
nginx -t通过才 reload，不通过自动回滚 → 回执平台 → 平台做 TLS 握手自检。 - 多域名：安装命令可重复执行追加域名；删除
/opt/ssl-agent/sites.d/对应.conf即停用该域名。 - 状态 6 种：未安装 / 待首次运行 / 运行中 / 上次失败 / 长期未签到 / 已停用。
6.2 方式二 · 宝塔面板 API（宝塔客户首选，秒级生效）
客户操作：宝塔面板 → 面板设置 → API 接口 → 开启并把平台服务器 IP 加入白名单，拿到 api_sk。
平台用户端填：面板地址 + API 密钥 + 站点名 → 先点「测试连接并保存」（返回面板版本即通）→ 「立即推送」验证。
- 平台通过官方签名调用
/site?action=SetSSL部署证书，宝塔写完自动重载 Nginx，客户服务器零安装。 - 主路径失败自动回退（SaveCert + SetSSL type=1）；两条都失败时如实报错不谎报成功。
api_sk等同于面板管理权：平台侧 AES-256-GCM 加密存储、页面只回显末 4 位；客户换密钥需重新填写。
6.3 方式三 · 接收端文件（非宝塔且有 PHP 环境时用）
- 下载接收端（平台页面给出命令）：
curl -fsSL "https://平台域名/index.php?m=agent&p=receive" -o /www/wwwroot/你的站点/ssl-receive.php - 改文件顶部配置区：粘贴推送令牌、按实际路径填
$TARGETS（证书 / 私钥路径、校验与重载命令）。 - 平台保存接收端地址 + 令牌 → 域名行出现「自检页」链接（已带令牌），打开看到「已就绪」即通。
- （若走收件箱模式）安装 root 搬运脚本：
curl -fsSL "https://平台域名/index.php?m=agent&p=receive_inbox" -o /root/ssl-inbox-deploy.sh，改其中INBOX为实际路径，加 cron 每 5 分钟。
安全设计：
- 来源域名白名单（下载时自动填平台域名，不暴露 IP）+ 可选 IP 白名单；
- 请求不能指定任何路径，写哪里完全由接收端本地配置决定；令牌常量时间比较；
- 目标可写 → 直接替换秒级生效；不可写（宝塔 root 属主）→ 证书收进站点内
.ssl-inbox/（nginx 拒绝访问.开头目录），由 root 脚本搬运，指纹幂等（同一张不重复重载）； - 自检页同样受令牌保护（v1.4+）：不带 / 带错令牌一律返回 nginx 样式 404，扫描者探测不到文件；
- 本地接收日志
.ssl-receive.log文件头带退出指令，浏览器无法直读。
6.4 通道怎么选
| 环境 | 推荐 |
|---|---|
| 宝塔面板 | 方式二（零安装、秒级） |
| 自建 Nginx / 有 PHP | 方式一（最省心）或方式三（要秒级） |
| 无 PHP 环境 | 方式一（只依赖 shell + curl） |
7. 自动续签机制
- 证书有效期 90 天；平台每日巡检（cron/renew.php），到期前 30 天自动续签。
- 续签成功后：按配置的通道自动推送 / 等待 agent 自查替换 → 部署后自动 TLS 自检 → 全程留痕。
- 续签失败：记录原因、触发告警，下轮巡检重试。
- 客户域名 CNAME 是永久性的一次配置，续签无需客户参与。
8. 开放 API
- 认证：请求头
Authorization: Bearer <令牌>，或?token=<令牌>兜底（部分 Nginx 不传授权头）。 - 限流：每令牌 60 次 / 分钟。管理员账号不能持有令牌（仅客户账号可创建）。
- 端点：
| 端点 | 说明 |
|---|---|
GET ?m=api&p=ping |
连通性测试 |
GET ?m=api&p=me |
当前令牌信息与配额 |
GET ?m=api&p=domains |
名下域名与证书状态、剩余天数 |
GET ?m=api&p=cert&id=<id>&f=zip\|nginx\|json |
下载证书包 |
GET ?m=api&p=deploy_check&domain=&fp= |
agent 用：比对指纹，返回是否需要更新 |
POST ?m=api&p=deploy_report |
agent 用：回执部署结果 |
9. 告警通知
- 渠道：企业微信机器人 / SMTP 邮件，均支持测试发送。
- 事件开关：签发失败、临近到期、续签成功、自动部署失败、服务器长期未签到（后两项默认开）。
- 模板可自定义，支持
{域名}{剩余天数}{失败原因}{客户}等占位符。 - 失联判定：按通道自查频率自动推导（2 个周期 + 2 天缓冲），也可在部署看板手动设定。
- 每日巡检自动清理过期信任设备与过期部署记录。
10. 升级与维护
- 增量包升级：解压覆盖站点目录即可 ——
config.php、data/、pages/auth.landing.php（首页）不在包内，客户数据与手改内容不受影响；新表 / 新列自动迁移；升级后可选手工改config.php的APP_VERSION（纯显示）。 - 首页：
pages/auth.landing.php为可手改文件，升级不会覆盖；缺省时自动回退到内置默认版。 - 备份：升级前建议用「数据备份」导出一次；
data/目录含证书与 ACME 账户，属核心资产。
11. 常见问题
Q：客户每年要做什么？ 什么都不用做。CNAME 是永久配置，续签、部署、提醒全部自动；除非换了服务器 / 证书路径，才需要重新跑一次安装命令。
Q：自查频率选多快合适？ 推荐半个月（默认）。平台提前 30 天续签，半个月自查最坏也有 15 天余量；不要超过 15 天。没更新时 agent 只做一次指纹比对，开销可忽略。
Q：为什么部署自检显示「可访问（非本平台证书）」？ 说明该域名能 HTTPS 访问，但平台没有可比亚对的证书（可能还没在平台申请，或证书文件已被清理）。
Q：宝塔环境接收端报 open_basedir 错误？
v1.4+ 接收端不再跨目录读写：证书收进站点内 .ssl-inbox/，由 root 脚本搬运，无需改 PHP 配置。
Q：2FA 验证码不对？ 检查手机时间（容差 ±30 秒）；连错 5 次锁 5 分钟。忘记密钥可让管理员重置账号。
Q：agent 显示「长期未签到」？
多为计划任务被删或服务器失联：登服务器检查 crontab -l 是否还有 ssl-agent/agent.sh 行，或重跑一次安装命令。
Q：忘了管理员密码？
通过数据库重置 users 表对应账号的 password 字段（password_hash() 生成），或重建管理员。
文档对应版本 4.9.2（2026-09-28）。平台各页面的即时提示（如安装命令、令牌）以页面实际输出为准。
