Skip to content

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接口 → 添加:

字段填写方式
角色证书获取
授权模式指定证书
证书选择此服务器需要的证书
备注填写服务器用途,便于识别
启用开启
平台 API Key 添加表单,选择证书获取角色与指定证书
图 20 · 创建证书获取 Key示例数据 · 点击图片放大

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

API Key 列表中的证书获取角色、证书范围与启用状态
图 21 · 复制对应 Key示例数据 · 点击图片放大

3. 登录后台并配置 ​

在服务器执行:

bash
vk-ssl web

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

服务器工具后台,包含证书操作、定时任务、本地证书与运行日志
图 22 · 工具后台示例数据 · 点击图片放大

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

工具配置管理:API Key、证书保存目录、Nginx 路径
图 23 · 填写 Key 与路径示例数据 · 点击图片放大

Nginx 路径填写可执行文件,例如 /usr/sbin/nginx,不能填 /etc/nginx 或 nginx.conf。安装时检测成功会自动填入;未检测到时,点击检测按钮或执行:

bash
vk-ssl nginx setup

点击 测试,通过后点击 保存配置。路径留空时只能获取证书,无法重载 Nginx。

工具返回 Nginx 配置测试成功
图 24 · 测试 Nginx 路径示例数据 · 点击图片放大

4. 获取证书 ​

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

工具本地证书列表中的域名、剩余天数和部署按钮
图 25 · 证书已保存到服务器示例数据 · 点击图片放大

工具会将授权范围内的已签发证书保存为 .crt、.key、.pem 文件,文件名以本地列表和实际目录为准。

5. 首次部署 ​

在本地证书列表点击目标证书的 部署,核对扫描出的站点域名与配置文件路径。

Nginx 站点扫描结果,完全匹配站点默认勾选,部分匹配站点未勾选
图 26 · 选择目标站点示例数据 · 点击图片放大
匹配结果处理方式
完全匹配证书覆盖站点全部域名,默认勾选;确认是目标站点
部分匹配默认不勾选,先处理未覆盖的域名
不匹配不能作为本次部署目标

例如 example.com 与 *.example.com 可覆盖根域名和 www.example.com,不能覆盖 a.b.example.com 或 other.example.net。

点击 部署并自动续期,确认目标数量后执行。工具会备份配置、写入证书路径、测试并重载 Nginx,最后检查本机 TLS。

工具首次部署成功的结果提示
图 27 · 首次部署成功示例数据 · 点击图片放大

部署后,站点会引用工具维护的证书文件。后续证书签发由平台负责,工具负责下载和应用。

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 随机选定一个分钟,每日检查更新。实际时间见 定时任务状态,服务重启后可能变化。

工具定时任务状态,显示服务器时间、每日执行时间和下一次执行时间
图 28 · 查看每日更新时间示例数据 · 点击图片放大

Nginx 工具主动拉取流程:每日检查、本地缺失或不足14天、下载保存、重载及网站验证

本地证书状态处理方式
缺失、无法解析,或剩余整数天数不足 14 天下载并保存平台当前证书
剩余整数天数至少 14 天跳过下载,显示无需更新

手动点击 更新证书也遵守此规则。因此平台已续签、本地仍有至少 14 天有效期时,不会立即同步。下载成功后,工具重载已配置的 Nginx;站点需保持引用首次部署时关联的文件。

平台续签条件见 自动续期与套餐续购。

日志与排错 ​

打开 部署记录查看证书、站点、时间和结果。需要还原备份时,先核对当前配置改动,还原会覆盖对应文件。

Nginx 部署记录中的证书文件、配置文件、时间和成功状态
图 31 · 查看部署记录示例数据 · 点击图片放大

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

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

常用检查命令:

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

更多处理方法见 常见问题与排错。

申请 · 续期 · 部署 · 验证