diff --git a/deploy/nginx/wx_service_https.conf b/deploy/nginx/wx_service_https.conf new file mode 100644 index 0000000..1c4dcb2 --- /dev/null +++ b/deploy/nginx/wx_service_https.conf @@ -0,0 +1,49 @@ +upstream wx_service_upstream { + server 127.0.0.1:8080; + keepalive 32; +} + +server { + listen 80; + listen [::]:80; + server_name api.example.com; + + # 强制全站 HTTPS + return 301 https://$host$request_uri; +} + +server { + listen 443 ssl http2; + listen [::]:443 ssl http2; + server_name api.example.com; + + # 证书路径请按实际域名替换 + ssl_certificate /etc/letsencrypt/live/api.example.com/fullchain.pem; + ssl_certificate_key /etc/letsencrypt/live/api.example.com/privkey.pem; + ssl_trusted_certificate /etc/letsencrypt/live/api.example.com/chain.pem; + + ssl_session_timeout 1d; + ssl_session_cache shared:SSL:10m; + ssl_session_tickets off; + + ssl_protocols TLSv1.2 TLSv1.3; + ssl_prefer_server_ciphers off; + + add_header Strict-Transport-Security "max-age=31536000; includeSubDomains; preload" always; + add_header X-Content-Type-Options nosniff always; + add_header X-Frame-Options SAMEORIGIN always; + add_header Referrer-Policy no-referrer-when-downgrade always; + + client_max_body_size 50m; + + location / { + proxy_http_version 1.1; + proxy_set_header Host $host; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header X-Forwarded-Proto https; + proxy_set_header Connection ""; + proxy_pass http://wx_service_upstream; + } +} + diff --git a/docs/ops/https_renewal.md b/docs/ops/https_renewal.md new file mode 100644 index 0000000..1e2f6d4 --- /dev/null +++ b/docs/ops/https_renewal.md @@ -0,0 +1,44 @@ +# 生产 HTTPS 配置与证书续期策略 + +对应 issue:`#10 [P1][T7] 生产 HTTPS 配置与证书续期策略` + +## 1. Nginx HTTPS 强制 + +- 参考配置:`deploy/nginx/wx_service_https.conf` +- 核心策略: + - `80 -> 443` 永久重定向 + - 仅暴露 `443 ssl http2` + - 添加 HSTS 与基础安全响应头 + - 反代到后端 `127.0.0.1:8080` + +部署步骤: + +```bash +sudo cp deploy/nginx/wx_service_https.conf /etc/nginx/conf.d/wx_service.conf +sudo nginx -t +sudo systemctl reload nginx +``` + +## 2. 证书自动续期 + +脚本:`scripts/ops/renew_cert.sh` + +推荐 cron(每天 03:30): + +```bash +30 3 * * * CERTBOT_CMD=/usr/bin/certbot NGINX_RELOAD_CMD="systemctl reload nginx" OPS_ALERT_WEBHOOK="https://example.com/webhook" /path/to/wx_service/scripts/ops/renew_cert.sh >> /var/log/wx_service-cert-renew.log 2>&1 +``` + +## 3. 续期失败与过期告警 + +脚本:`scripts/ops/check_cert_expiry.sh` + +推荐 cron(每天 04:00): + +```bash +0 4 * * * TLS_DOMAIN=api.example.com TLS_CERT_PORT=443 TLS_MIN_DAYS=15 OPS_ALERT_WEBHOOK="https://example.com/webhook" /path/to/wx_service/scripts/ops/check_cert_expiry.sh >> /var/log/wx_service-cert-check.log 2>&1 +``` + +说明: +- 当剩余天数 `<= TLS_MIN_DAYS` 时返回非 0 并推送告警。 +- 当无法获取证书信息时也会告警并返回非 0。 diff --git a/docs/ops/reports/https_renewal_validation_2026-02-28.md b/docs/ops/reports/https_renewal_validation_2026-02-28.md new file mode 100644 index 0000000..5cc6e8f --- /dev/null +++ b/docs/ops/reports/https_renewal_validation_2026-02-28.md @@ -0,0 +1,24 @@ +# HTTPS 与续期策略验证记录(2026-02-28) + +对应 issue:`#10 [P1][T7] 生产 HTTPS 配置与证书续期策略` + +## 验证内容 + +1. 配置文件存在且可读 +- `deploy/nginx/wx_service_https.conf` + +2. 续期与告警脚本语法检查 +- `scripts/ops/renew_cert.sh` +- `scripts/ops/check_cert_expiry.sh` + +## 验证命令 + +```bash +bash -n scripts/ops/renew_cert.sh +bash -n scripts/ops/check_cert_expiry.sh +``` + +## 结果 + +- 语法检查通过。 +- 已提供 HTTP->HTTPS 强制跳转、自动续期、过期/失败告警方案与定时任务示例。 diff --git a/scripts/ops/check_cert_expiry.sh b/scripts/ops/check_cert_expiry.sh new file mode 100755 index 0000000..0f0c76e --- /dev/null +++ b/scripts/ops/check_cert_expiry.sh @@ -0,0 +1,47 @@ +#!/usr/bin/env bash +set -euo pipefail + +# 用法: +# TLS_DOMAIN=api.example.com TLS_CERT_PORT=443 ./scripts/ops/check_cert_expiry.sh + +TLS_DOMAIN="${TLS_DOMAIN:-api.example.com}" +TLS_CERT_PORT="${TLS_CERT_PORT:-443}" +TLS_MIN_DAYS="${TLS_MIN_DAYS:-15}" +OPS_ALERT_WEBHOOK="${OPS_ALERT_WEBHOOK:-}" +ALERT_TITLE="${ALERT_TITLE:-[wx_service] HTTPS 证书即将过期}" + +send_alert() { + local message="$1" + if [[ -z "${OPS_ALERT_WEBHOOK}" ]]; then + echo "ALERT: ${message}" >&2 + return + fi + + curl -fsS -X POST "${OPS_ALERT_WEBHOOK}" \ + -H "Content-Type: application/json" \ + -d "{\"title\":\"${ALERT_TITLE}\",\"message\":\"${message}\"}" >/dev/null || true +} + +if ! command -v openssl >/dev/null 2>&1; then + echo "openssl is required" >&2 + exit 1 +fi + +expiry_line="$(echo | openssl s_client -servername "${TLS_DOMAIN}" -connect "${TLS_DOMAIN}:${TLS_CERT_PORT}" 2>/dev/null | openssl x509 -noout -enddate || true)" +if [[ -z "${expiry_line}" ]]; then + send_alert "无法获取 ${TLS_DOMAIN}:${TLS_CERT_PORT} 的证书过期时间。" + exit 1 +fi + +expiry_raw="${expiry_line#notAfter=}" +expiry_epoch="$(date -d "${expiry_raw}" +%s)" +now_epoch="$(date +%s)" +remaining_days="$(( (expiry_epoch - now_epoch) / 86400 ))" + +if (( remaining_days <= TLS_MIN_DAYS )); then + send_alert "${TLS_DOMAIN} 证书将在 ${remaining_days} 天后过期,请尽快续期。" + exit 1 +fi + +echo "certificate valid: ${remaining_days} days remaining" + diff --git a/scripts/ops/renew_cert.sh b/scripts/ops/renew_cert.sh new file mode 100755 index 0000000..d00c0fc --- /dev/null +++ b/scripts/ops/renew_cert.sh @@ -0,0 +1,35 @@ +#!/usr/bin/env bash +set -euo pipefail + +# 用法: +# CERTBOT_CMD=/usr/bin/certbot NGINX_RELOAD_CMD="systemctl reload nginx" ./scripts/ops/renew_cert.sh + +CERTBOT_CMD="${CERTBOT_CMD:-certbot}" +NGINX_RELOAD_CMD="${NGINX_RELOAD_CMD:-systemctl reload nginx}" +OPS_ALERT_WEBHOOK="${OPS_ALERT_WEBHOOK:-}" +ALERT_TITLE="${ALERT_TITLE:-[wx_service] HTTPS 证书续期失败}" + +send_alert() { + local message="$1" + if [[ -z "${OPS_ALERT_WEBHOOK}" ]]; then + echo "ALERT: ${message}" >&2 + return + fi + + curl -fsS -X POST "${OPS_ALERT_WEBHOOK}" \ + -H "Content-Type: application/json" \ + -d "{\"title\":\"${ALERT_TITLE}\",\"message\":\"${message}\"}" >/dev/null || true +} + +if ! "${CERTBOT_CMD}" renew --quiet; then + send_alert "certbot renew 执行失败,请立即检查生产证书状态。" + exit 1 +fi + +if ! bash -lc "${NGINX_RELOAD_CMD}"; then + send_alert "证书续期后 Nginx reload 失败,请检查服务状态。" + exit 1 +fi + +echo "certificate renew completed" +