305 lines
8.0 KiB
Markdown
305 lines
8.0 KiB
Markdown
# ACME SSL 证书自动管理工具集
|
||
|
||
一个功能强大的 ACME SSL 证书自动管理工具集合，专为 Nginx 服务器环境设计，提供证书更新、环境诊断和自动化管理功能。
|
||
|
||
## 🎯 项目概述
|
||
|
||
本项目包含三个核心脚本，用于解决 SSL 证书管理的常见痛点：
|
||
- **自动证书更新**：智能检测证书有效期并自动更新
|
||
- **环境诊断**：全面检测 ACME 挑战环境配置
|
||
- **一键管理**：简化复杂的证书管理流程
|
||
|
||
## 📋 功能特性
|
||
|
||
### 🔄 自动证书更新 (`update_acme_cert.sh`)
|
||
- **智能过期检测**：自动检查证书剩余有效期（默认30天预警）
|
||
- **多种更新模式**：支持自动更新、强制更新、仅安装模式
|
||
- **Nginx 集成**：自动解析 Nginx 配置文件，提取证书路径
|
||
- **权限管理**：自动设置正确的文件权限和所有者
|
||
- **安全验证**：证书内容验证和指纹检查
|
||
- **彩色日志**：中文彩色输出，便于阅读和调试
|
||
- **完整日志**：详细的操作日志记录到 `/var/log/acme_update.log`
|
||
|
||
### 🔍 环境诊断 (`acme_test.sh`)
|
||
- **DNS 解析检查**：验证域名解析是否正确指向服务器
|
||
- **Webroot 权限测试**：检测挑战文件写入权限
|
||
- **Nginx 配置检查**：验证 ACME 挑战 location 规则
|
||
- **HTTP 访问测试**：模拟 Let's Encrypt 验证过程
|
||
- **网络连通性**：检测端口监听和外部访问
|
||
- **智能清理**：自动清理测试文件
|
||
|
||
### 🛠️ 核心优势
|
||
- **零配置依赖**：自动检测和适配现有环境
|
||
- **错误恢复**：详细的错误提示和解决方案建议
|
||
- **安全加固**：遵循最佳安全实践
|
||
- **中文友好**：完整的中文界面和日志输出
|
||
- **生产就绪**：经过充分测试，适用于生产环境
|
||
|
||
## 🚀 快速开始
|
||
|
||
### 环境要求
|
||
- **操作系统**：Linux (Ubuntu/CentOS/Debian 等)
|
||
- **权限要求**：root 权限或 sudo 访问
|
||
- **依赖软件**：
|
||
- Nginx Web 服务器
|
||
- acme.sh 证书工具
|
||
- curl、openssl、grep 等基础工具
|
||
|
||
### 安装步骤
|
||
|
||
1. **克隆项目**
|
||
```bash
|
||
git clone <项目地址>
|
||
cd acme-ssl-manager
|
||
```
|
||
|
||
2. **设置执行权限**
|
||
```bash
|
||
chmod +x *.sh
|
||
```
|
||
|
||
3. **安装 acme.sh**（如果尚未安装）
|
||
```bash
|
||
curl https://get.acme.sh | sh
|
||
```
|
||
|
||
4. **配置 Nginx**
|
||
确保您的 Nginx 配置包含 ACME 挑战 location 规则：
|
||
```nginx
|
||
location ^~ /.well-known/acme-challenge/ {
|
||
allow all;
|
||
root /var/www/letsencrypt;
|
||
}
|
||
```
|
||
|
||
## 📖 使用指南
|
||
|
||
### 1. 环境诊断（推荐先运行）
|
||
|
||
在使用证书更新功能前，建议先运行环境诊断脚本：
|
||
|
||
```bash
|
||
# 交互式模式
|
||
sudo ./acme_test.sh
|
||
|
||
# 直接指定域名
|
||
sudo ./acme_test.sh example.com
|
||
|
||
# 指定域名和Webroot
|
||
sudo ./acme_test.sh example.com /var/www/letsencrypt
|
||
```
|
||
|
||
诊断脚本将检查：
|
||
- ✅ DNS 解析是否正确
|
||
- ✅ Webroot 目录权限
|
||
- ✅ Nginx 配置完整性
|
||
- ✅ HTTP 访问可用性
|
||
- ✅ 端口监听状态
|
||
|
||
### 2. 证书更新
|
||
|
||
#### 基本用法
|
||
```bash
|
||
# 交互式更新
|
||
sudo ./update_acme_cert.sh
|
||
|
||
# 直接更新指定域名（需要修改脚本）
|
||
# 编辑脚本设置 DOMAIN 变量
|
||
```
|
||
|
||
#### 操作模式
|
||
脚本运行时会根据证书状态提供不同选项：
|
||
|
||
1. **证书即将过期**（<30天）：自动执行更新
|
||
2. **证书仍有效**：提供三个选项
|
||
- **强制更新**：重新颁发证书
|
||
- **仅安装**：跳过更新，仅安装现有证书
|
||
- **退出**：不做任何操作
|
||
|
||
#### 更新流程
|
||
1. **权限检查**：验证 root 权限
|
||
2. **域名输入**：交互式输入目标域名
|
||
3. **配置解析**：自动查找 Nginx 配置文件
|
||
4. **证书检测**：检查当前证书有效期
|
||
5. **证书更新**：使用 acme.sh 颁发新证书
|
||
6. **证书安装**：安装到指定位置
|
||
7. **权限设置**：设置正确的文件权限
|
||
8. **Nginx 重载**：使新证书生效
|
||
9. **最终验证**：确认证书安装成功
|
||
|
||
### 3. 配置文件
|
||
|
||
#### 主要配置项
|
||
编辑脚本文件修改以下配置：
|
||
|
||
```bash
|
||
# acme.sh 路径
|
||
ACME_SH="/root/.acme.sh/acme.sh"
|
||
|
||
# Nginx 配置目录
|
||
NGINX_CONF_DIR="/etc/nginx/conf.d"
|
||
|
||
# Webroot 路径
|
||
WEBROOT="/var/www/letsencrypt"
|
||
|
||
# 证书存储目录
|
||
TLS_BASE_DIR="/etc/nginx/tls"
|
||
|
||
# 日志文件
|
||
LOG_FILE="/var/log/acme_update.log"
|
||
```
|
||
|
||
#### 高级配置
|
||
- **强制更新**：设置 `FORCE_RENEW="true"`
|
||
- **自定义 CA**：修改 `--server` 参数
|
||
- **通知设置**：可集成邮件/Webhook 通知
|
||
|
||
## 🔧 高级功能
|
||
|
||
### 证书指纹验证
|
||
支持自定义证书指纹验证：
|
||
```bash
|
||
# 在 verify_cert_success 函数中启用指纹检查
|
||
if grep -q "YOUR_FINGERPRINT" "$cert_file"; then
|
||
log_info "✅ 证书指纹验证通过"
|
||
return 0
|
||
fi
|
||
```
|
||
|
||
### 多域名支持
|
||
支持通配符域名和多域名证书：
|
||
```bash
|
||
# 修改 renew_certificate 函数
|
||
local cmd="$ACME_SH --issue -d $DOMAIN -d *.${DOMAIN} --webroot $WEBROOT"
|
||
```
|
||
|
||
### 自动续期
|
||
设置定时任务实现自动续期：
|
||
```bash
|
||
# 编辑 crontab
|
||
crontab -e
|
||
|
||
# 添加以下内容（每天凌晨检查）
|
||
0 2 * * * /path/to/update_acme_cert.sh >> /var/log/acme_cron.log 2>&1
|
||
```
|
||
|
||
## 📊 日志和监控
|
||
|
||
### 日志文件
|
||
- **更新日志**：`/var/log/acme_update.log`
|
||
- **定时任务日志**：`/var/log/acme_cron.log`
|
||
|
||
### 日志格式
|
||
```
|
||
[INFO] 2026-03-03 10:30:45 - 目标域名: example.com
|
||
[步骤] 2026-03-03 10:30:45 - 解析配置文件，提取证书路径...
|
||
[警告] 2026-03-03 10:30:45 - 证书即将过期（<30天），需要更新
|
||
```
|
||
|
||
### 监控建议
|
||
- **日志轮转**：配置 logrotate 管理日志文件
|
||
- **监控告警**：监控日志中的错误关键词
|
||
- **证书监控**：设置证书有效期监控告警
|
||
|
||
## 🐛 故障排除
|
||
|
||
### 常见问题
|
||
|
||
#### 1. DNS 解析失败
|
||
```bash
|
||
# 检查域名解析
|
||
dig +short your-domain.com
|
||
# 或
|
||
nslookup your-domain.com
|
||
```
|
||
|
||
#### 2. Webroot 权限问题
|
||
```bash
|
||
# 修正权限
|
||
sudo chown -R www-data:www-data /var/www/letsencrypt
|
||
sudo chmod -R 755 /var/www/letsencrypt
|
||
```
|
||
|
||
#### 3. Nginx 配置错误
|
||
```bash
|
||
# 检查 Nginx 配置
|
||
sudo nginx -t
|
||
# 重载配置
|
||
sudo service nginx force-reload
|
||
```
|
||
|
||
#### 4. 端口未监听
|
||
```bash
|
||
# 检查端口监听
|
||
sudo ss -tlnp | grep ':80'
|
||
# 检查防火墙
|
||
sudo ufw status
|
||
sudo iptables -L
|
||
```
|
||
|
||
#### 5. acme.sh 未安装
|
||
```bash
|
||
# 安装 acme.sh
|
||
curl https://get.acme.sh | sh
|
||
# 重新加载环境
|
||
source ~/.bashrc
|
||
```
|
||
|
||
### 错误代码说明
|
||
|
||
| 错误类型 | 说明 | 解决方案 |
|
||
|---------|------|----------|
|
||
| DNS 解析不一致 | 域名解析 IP 与服务器 IP 不匹配 | 检查 DNS 设置，确认域名指向正确 |
|
||
| Webroot 写入失败 | 无法写入挑战文件 | 检查目录权限和磁盘空间 |
|
||
| HTTP 访问失败 | 无法通过 HTTP 访问挑战文件 | 检查 Nginx 配置和端口监听 |
|
||
| 证书颁发失败 | acme.sh 无法颁发证书 | 检查域名解析、Webroot 配置 |
|
||
|
||
## 🔒 安全考虑
|
||
|
||
### 文件权限
|
||
- **证书文件**：设置为 600（仅所有者可读写）
|
||
- **所有者**：设置为 www-data（Nginx 运行用户）
|
||
- **目录权限**：Webroot 目录设置为 755
|
||
|
||
### 最佳实践
|
||
1. **定期更新**：及时更新证书避免过期
|
||
2. **监控告警**：设置证书有效期监控
|
||
3. **备份配置**：定期备份 Nginx 配置和证书
|
||
4. **访问控制**：限制对证书目录的访问
|
||
5. **日志审计**：定期检查操作日志
|
||
|
||
## 🤝 贡献指南
|
||
|
||
欢迎提交 Issue 和 Pull Request！
|
||
|
||
### 开发规范
|
||
- 遵循 Bash 最佳实践
|
||
- 添加适当的错误处理
|
||
- 保持中文界面友好
|
||
- 更新相关文档
|
||
|
||
### 测试要求
|
||
- 在多种 Linux 发行版上测试
|
||
- 验证不同 Nginx 配置场景
|
||
- 测试错误处理和恢复机制
|
||
|
||
## 📄 许可证
|
||
|
||
本项目采用 MIT 许可证 - 详见 [LICENSE](LICENSE) 文件
|
||
|
||
## 🙏 致谢
|
||
|
||
- [acme.sh](https://github.com/acmesh-official/acme.sh) - 优秀的 ACME 客户端
|
||
- [Let's Encrypt](https://letsencrypt.org/) - 提供免费 SSL 证书
|
||
- [Nginx](https://nginx.org/) - 高性能 Web 服务器
|
||
|
||
## 📞 支持
|
||
|
||
如有问题或建议，请通过以下方式联系：
|
||
- 提交 Issue
|
||
- 发送邮件至：[your-email@example.com]
|
||
- 访问项目主页：[项目地址]
|
||
|
||
---
|
||
|
||
**⭐ 如果这个项目对您有帮助，请给我们一个 Star！** |