first commit
This commit is contained in:
jeremygan2021
305
README.md
Normal file
305
README.md
Normal file
@@ -0,0 +1,305 @@
|
||||
# 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！**
|
||||
Reference in New Issue
Block a user