外观
Nginx 自动部署工具
在 Linux 服务器安装无忧 SSL 自动部署工具,通过 API Key 主动拉取平台已签发的证书,部署到 Nginx 站点并定时更新。
准备条件
| 项目 | 要求 |
|---|---|
| 服务器 | 使用 systemd 的 Linux,具备 systemctl、flock,架构为 x86_64/amd64 或 aarch64/arm64 |
| 权限与网络 | 使用 root 操作,服务器能访问安装下载地址和平台 API |
| Nginx | 已安装并创建目标站点,工具服务有权限读写站点配置 |
| 平台 | 目标证书已签发,账号累计积分至少 1000,满足证书获取 API 权益要求 |
API 权益检查的是累计积分,非当前余额;实际以接口提示和账号权益页面为准。
1. 安装工具
以 root 执行:
bash
curl -fsSL https://gitee.vk168.top/vk168/vk-ssl-auto-deploy-go/raw/master/install.sh | bash安装程序会注册并启动 systemd 服务,自动检测和测试 Nginx。检测失败时,可在第 3 步补充路径。
| 配置项 | 默认值 |
|---|---|
| 安装目录 | /vk-ssl |
| 配置文件 | /vk-ssl/config.json |
| 证书保存目录 | /vk-cert |
| systemd 服务名 | vk-ssl-auto-deploy |
| 管理端口 | 16001,以终端显示为准 |
源码与上游说明:vk-ssl-auto-deploy-go。
2. 创建证书获取 Key
进入平台 我的 → API接口 → 添加:
| 字段 | 填写方式 |
|---|---|
| 角色 | 证书获取 |
| 授权模式 | 指定证书 |
| 证书 | 选择此服务器需要的证书 |
| 备注 | 填写服务器用途,便于识别 |
| 启用 | 开启 |

保存后,从列表复制完整 Key。以后新增证书时,需将其加入授权范围;原证书续签无需重新授权。

3. 登录后台并配置
在服务器执行:
bash
vk-ssl web使用命令显示的地址和管理口令登录。命令会尝试放行本机防火墙端口;使用云服务器时,还需在安全组允许管理来源访问该端口。管理口令可在配置管理中修改,与平台 API Key 分开使用。

打开 配置管理,粘贴 API Key,证书保存目录保留 /vk-cert,检查 Nginx 路径。

Nginx 路径填写可执行文件,例如 /usr/sbin/nginx,不能填 /etc/nginx 或 nginx.conf。安装时检测成功会自动填入;未检测到时,点击检测按钮或执行:
bash
vk-ssl nginx setup点击 测试,通过后点击 保存配置。路径留空时只能获取证书,无法重载 Nginx。

4. 获取证书
回到首页,点击 更新证书并确认。等待日志完成,再点击 刷新证书列表,核对目标域名与有效期。

工具会将授权范围内的已签发证书保存为 .crt、.key、.pem 文件,文件名以本地列表和实际目录为准。
5. 首次部署
在本地证书列表点击目标证书的 部署,核对扫描出的站点域名与配置文件路径。

| 匹配结果 | 处理方式 |
|---|---|
| 完全匹配 | 证书覆盖站点全部域名,默认勾选;确认是目标站点 |
| 部分匹配 | 默认不勾选,先处理未覆盖的域名 |
| 不匹配 | 不能作为本次部署目标 |
例如 example.com 与 *.example.com 可覆盖根域名和 www.example.com,不能覆盖 a.b.example.com 或 other.example.net。
点击 部署并自动续期,确认目标数量后执行。工具会备份配置、写入证书路径、测试并重载 Nginx,最后检查本机 TLS。

部署后,站点会引用工具维护的证书文件。后续证书签发由平台负责,工具负责下载和应用。
6. 验证网站证书
打开实际 HTTPS 网站,检查浏览器中的证书域名和有效期。也可用 OpenSSL 比较本地文件与网站返回证书的序列号、到期时间,将示例域名和文件名替换为实际值:
bash
# 本地证书
openssl x509 -in /vk-cert/example.com-2.crt -noout -subject -issuer -dates -serial
# 网站返回的证书,-servername 指定 SNI 域名
openssl s_client -connect example.com:443 -servername example.com </dev/null 2>/dev/null \
| openssl x509 -noout -subject -issuer -dates -serial两者应与预期的新证书一致。需要检查证书链时,直接运行 openssl s_client 查看完整验证结果。
域名经过 CDN/负载均衡时,公网可能返回入口层证书。将 -connect 改为源站 IP 并保留 -servername,可单独检查源站;本机检查通过后仍需验证公网访问。
定时更新
工具启动后,会在服务器当地时间 02:00—06:00 随机选定一个分钟,每日检查更新。实际时间见 定时任务状态,服务重启后可能变化。

| 本地证书状态 | 处理方式 |
|---|---|
| 缺失、无法解析,或剩余整数天数不足 14 天 | 下载并保存平台当前证书 |
| 剩余整数天数至少 14 天 | 跳过下载,显示无需更新 |
手动点击 更新证书也遵守此规则。因此平台已续签、本地仍有至少 14 天有效期时,不会立即同步。下载成功后,工具重载已配置的 Nginx;站点需保持引用首次部署时关联的文件。
平台续签条件见 自动续期与套餐续购。
日志与排错
打开 部署记录查看证书、站点、时间和结果。需要还原备份时,先核对当前配置改动,还原会覆盖对应文件。

运行日志可查看证书获取、保存、Nginx 测试与重载结果。

| 问题 | 检查与处理 |
|---|---|
| 安装失败 | 核对系统、架构、root 权限和网络 |
| 后台无法访问 | 检查服务状态、vk-ssl web 显示的地址、防火墙和安全组 |
| Key 无效或无权限 | 检查完整 Key、启用状态、证书获取角色和 API 权益 |
| 本地列表为空 | 确认证书已签发且在 Key 授权范围内,再执行更新 |
| 扫描不到站点或没有完全匹配项 | 检查配置是否被 Nginx 加载,以及证书是否覆盖全部 server_name |
| 配置写入、测试或重载失败 | 按错误提示检查可执行文件路径、配置语法、证书路径和读写权限 |
| 定时任务未执行 | 检查服务状态、服务器时间、下一次执行时间和日志 |
| 网站仍是旧证书 | 依次核对平台是否续签、本地更新条件、站点引用路径、重载结果与公网入口 |

常用检查命令:
bash
# 服务状态与开机启动
systemctl status vk-ssl-auto-deploy --no-pager
systemctl is-enabled vk-ssl-auto-deploy
# 工具状态与定时任务
vk-ssl status
# Nginx 配置测试
vk-ssl nginx test
# 最近 100 行服务日志
journalctl -u vk-ssl-auto-deploy -n 100 --no-pager更多处理方法见 常见问题与排错。
