security(server): nginx 安全头片段化与 compose 强制配置校验

Author: Aparencia

server/.env.production.example

@@ -0,0 +1,56 @@
+# ===========================================
+# entropy-decrease 生产环境配置模板
+# ===========================================
+# 使用方法：复制为 .env.production 并填入真实值
+#   cp .env.production.example .env.production
+# 所有 CHANGE_ME 占位符必须在部署前替换为真实值（deploy.sh 会硬校验）。
+# .env.production 含敏感信息，已被 .gitignore 排除，切勿提交到 Git。
+
+# --- 应用环境 ---
+APP_ENV=production
+
+# --- 数据库配置 ---
+# DB_USER: PostgreSQL 用户名
+DB_USER=CHANGE_ME
+# DB_PASSWORD: PostgreSQL 密码（使用强随机密码，如 openssl rand -base64 32）
+DB_PASSWORD=CHANGE_ME
+# DB_NAME: 数据库名称
+DB_NAME=CHANGE_ME
+
+# --- Redis 配置 ---
+# REDIS_PASSWORD: Redis 认证密码（使用强随机密码；docker-compose.prod.yml
+# 使用 :? 语法强制要求显式配置，缺省即拒绝启动）
+REDIS_PASSWORD=CHANGE_ME
+
+# --- JWT 安全密钥（生成方法: openssl rand -hex 32）---
+JWT_SECRET=CHANGE_ME
+
+# --- AI 模型 API Key ---
+# 通义千问：https://dashscope.aliyun.com
+QWEN_API_KEY=CHANGE_ME
+
+# DeepSeek：https://platform.deepseek.com
+DEEPSEEK_API_KEY=CHANGE_ME
+
+# 智谱 GLM：https://open.bigmodel.cn
+GLM_API_KEY=CHANGE_ME
+
+# Gemini（用于视频分析功能）：https://aistudio.google.com/app/apikey
+GEMINI_API_KEY=CHANGE_ME
+
+# --- Supabase（如使用）---
+# 从 Supabase Dashboard > Settings > API > JWT Settings 获取 JWT Signing Secret（非 anon key）
+SUPABASE_JWT_SECRET=CHANGE_ME
+# 项目 URL：从 Supabase Dashboard > Settings > API 获取
+SUPABASE_URL=CHANGE_ME
+# JWKS URL：通常为 <SUPABASE_URL>/auth/v1/.well-known/jwks.json
+SUPABASE_JWKS_URL=CHANGE_ME
+
+# --- CORS 允许的域名（多个用逗号分隔）---
+# 生产环境仅保留正式域名，禁止使用通配符 *（compose 强制要求显式配置）
+# https://entropydecrease.com —— 官网主域名（HTTPS），用于网站前端请求 AI 网关与同步服务
+# http://entropydecrease.com —— HTTP 回退域名，兼容未启用 HTTPS 的过渡期流量
+CORS_ORIGINS=https://entropydecrease.com,http://entropydecrease.com
+
+# --- AI 网关开发者白名单（最高权限身份，切勿填普通用户）---
+DEV_USER_IDS=dev@example.com

server/deploy.sh

@@ -2,9 +2,14 @@
 # =============================================================================
 # entropy-decrease 后端服务一键部署脚本
 # 用法：chmod +x deploy.sh && ./deploy.sh
+#
+# 重部署前置条件：必须在 .env.production 中补齐 REDIS_PASSWORD 与 CORS_ORIGINS——
+# docker-compose.prod.yml 对二者使用 ${VAR:?...} 强制插值，缺失会在 compose
+# 阶段报难读错误；本脚本在第 2 节提前做可读校验（三维复审 #10 护栏）。
 # =============================================================================
 
-set -e
+# 严格模式：未定义变量/命令失败/管道失败均立即退出，避免静默错误继续部署
+set -euo pipefail
 
 RED='\033[0;31m'
 GREEN='\033[0;32m'
@@ -53,15 +58,33 @@ if [ ! -f "$ENV_FILE" ]; then
     exit 1
 fi
 
-# 检查关键配置是否已修改
+# 检查关键配置是否已修改（硬失败：生产环境禁止带占位符部署，不提供跳过选项）
 if grep -q "CHANGE_ME" "$ENV_FILE"; then
-    log_warn "检测到 $ENV_FILE 中仍有 CHANGE_ME 占位符"
-    echo "  请编辑 $ENV_FILE，替换所有 CHANGE_ME 为真实值"
-    read -p "  是否继续？(y/N) " -n 1 -r
-    echo
-    if [[ ! $REPLY =~ ^[Yy]$ ]]; then
-        exit 1
-    fi
+    log_error "检测到 $ENV_FILE 中仍有 CHANGE_ME 占位符，部署已中止"
+    echo "  请编辑 $ENV_FILE，替换所有 CHANGE_ME 为真实值后重新运行"
+    exit 1
+fi
+
+# compose 强制项迁移护栏（三维复审 #10）：REDIS_PASSWORD / CORS_ORIGINS 在
+# docker-compose.prod.yml 中以 ${VAR:?...} 强制插值——变量缺失时 compose 阶段
+# 才报错且信息难读；此处提前 source 校验，转为可读提示快速失败。
+# 临时放宽 -u：env 文件中可能存在 ${VAR} 自引用占位行，source 时不应因
+# 未定义变量中止（与第 7 节 Redis 健康检查同口径）
+set +u
+set -a
+# shellcheck source=/dev/null
+source "$ENV_FILE"
+set +a
+set -u
+
+MISSING_VARS=""
+if [ -z "${REDIS_PASSWORD:-}" ]; then MISSING_VARS="$MISSING_VARS REDIS_PASSWORD"; fi
+if [ -z "${CORS_ORIGINS:-}" ]; then MISSING_VARS="$MISSING_VARS CORS_ORIGINS"; fi
+if [ -n "$MISSING_VARS" ]; then
+    log_error "$ENV_FILE 缺少 compose 强制配置:$MISSING_VARS"
+    echo "  请编辑 $ENV_FILE 补齐上述变量后重新部署"
+    echo "  （docker-compose.prod.yml 以 \${VAR:?} 强制要求，缺失将无法启动）"
+    exit 1
 fi
 
 log_info "$ENV_FILE 已就绪 ✓"
@@ -143,12 +166,34 @@ else
     ERRORS=$((ERRORS + 1))
 fi
 
-# Redis
-if docker exec entropy-decrease-redis redis-cli -a "$(grep REDIS_PASSWORD "$ENV_FILE" | cut -d= -f2)" ping > /dev/null 2>&1; then
-    log_info "Redis ✓ 运行正常"
-else
-    log_error "Redis ✗ 未就绪"
+# Redis：密码经 REDISCLI_AUTH 环境变量注入容器（redis-cli 官方支持的认证方式），
+# 完全不在宿主机/容器命令行出现密码参数（-a 方式在进程列表可见；
+# --env VAR 无值形式从当前进程环境透传，同样不落命令行）
+# 临时放宽 -u：env 文件中可能存在 ${VAR} 自引用占位行，source 时不应因
+# 未定义变量中止（本处仅需 REDIS_PASSWORD）
+set +u
+set -a
+# shellcheck source=/dev/null
+source "$ENV_FILE"
+set +a
+set -u
+
+if [ -z "${REDIS_PASSWORD:-}" ]; then
+    log_error "Redis ✗ REDIS_PASSWORD 未在 $ENV_FILE 中配置"
     ERRORS=$((ERRORS + 1))
+else
+    # 三维复审 #1 修复：--env REDISCLI_AUTH（无值形式）仅从**当前进程环境**透传，
+    # 而 source 出的变量名为 REDIS_PASSWORD——此前 REDISCLI_AUTH 在环境中不存在，
+    # docker 静默丢弃该 --env，redis-cli 无认证必然 NOAUTH 失败。
+    # 显式 export 把密码映射到 REDISCLI_AUTH 后，现有 --env 透传写法即生效。
+    export REDISCLI_AUTH="$REDIS_PASSWORD"
+    if docker exec --env REDISCLI_AUTH entropy-decrease-redis \
+         redis-cli ping > /dev/null 2>&1; then
+        log_info "Redis ✓ 运行正常"
+    else
+        log_error "Redis ✗ 未就绪"
+        ERRORS=$((ERRORS + 1))
+    fi
 fi
 
 # sync-service

server/docker-compose.prod.yml

@@ -42,11 +42,12 @@ services:
     restart: unless-stopped
     ports:
       - "127.0.0.1:6379:6379"
-    command: redis-server --requirepass ${REDIS_PASSWORD:-entropy-decrease_redis_prod}
+    # 生产环境禁止默认密码回退：REDIS_PASSWORD 必须在 .env.production 显式配置，缺省即拒绝启动
+    command: redis-server --requirepass ${REDIS_PASSWORD:?REDIS_PASSWORD 必须在 .env.production 显式配置}
     volumes:
       - redis_data:/data
     healthcheck:
-      test: ["CMD", "redis-cli", "-a", "${REDIS_PASSWORD:-entropy-decrease_redis_prod}", "ping"]
+      test: ["CMD", "redis-cli", "-a", "${REDIS_PASSWORD:?REDIS_PASSWORD 必须在 .env.production 显式配置}", "ping"]
       interval: 10s
       timeout: 5s
       retries: 5
@@ -67,13 +68,15 @@ services:
     container_name: entropy-decrease-sync-service
     restart: unless-stopped
     ports:
-      - "0.0.0.0:8080:8080"
+      # 仅绑定宿主机回环：对外流量统一由 nginx 同宿主反代（80/443），
+      # 避免内部服务端口直接暴露公网
+      - "127.0.0.1:8080:8080"
     environment:
       PORT: "8080"
       APP_ENV: production
       GIN_MODE: release
       DATABASE_URL: postgres://${DB_USER:-entropy-decrease}:${DB_PASSWORD}@postgres:5432/${DB_NAME:-entropy-decrease}
-      REDIS_URL: redis://:${REDIS_PASSWORD:-entropy-decrease_redis_prod}@redis:6379/0
+      REDIS_URL: redis://:${REDIS_PASSWORD:?REDIS_PASSWORD 必须在 .env.production 显式配置}@redis:6379/0
       JWT_SECRET: ${JWT_SECRET}
       SUPABASE_JWT_SECRET: ${SUPABASE_JWT_SECRET:-}
     depends_on:
@@ -104,15 +107,17 @@ services:
     container_name: entropy-decrease-ai-gateway
     restart: unless-stopped
     ports:
-      - "0.0.0.0:8000:8000"
+      # 仅绑定宿主机回环：对外流量统一由 nginx 同宿主反代（80/443），
+      # 避免内部服务端口直接暴露公网
+      - "127.0.0.1:8000:8000"
     environment:
       APP_ENV: production
       QWEN_API_KEY: ${QWEN_API_KEY:-}
       DEEPSEEK_API_KEY: ${DEEPSEEK_API_KEY:-}
       GLM_API_KEY: ${GLM_API_KEY:-}
       # Gemini API 密钥：用于视频分析功能（多模态视觉理解），从 .env.production 注入
       GEMINI_API_KEY: ${GEMINI_API_KEY:-}
-      REDIS_URL: redis://:${REDIS_PASSWORD:-entropy-decrease_redis_prod}@redis:6379/1
+      REDIS_URL: redis://:${REDIS_PASSWORD:?REDIS_PASSWORD 必须在 .env.production 显式配置}@redis:6379/1
       SYNC_SERVICE_URL: http://sync-service:8080
       # JWT 验证密钥：网关校验请求方身份（与 sync-service 同一套签发/验证密钥）
       JWT_SECRET: ${JWT_SECRET}
@@ -136,7 +141,8 @@ services:
       GATEWAY_ALLOW_DEV_AUTH: "false"
       # OpenTelemetry 导出（可选）
       OTEL_EXPORTER_OTLP_ENDPOINT: ${OTEL_EXPORTER_OTLP_ENDPOINT:-}
-      CORS_ORIGINS: ${CORS_ORIGINS:-*}
+      # 生产环境禁止通配符回退：CORS 白名单必须在 .env.production 显式配置
+      CORS_ORIGINS: ${CORS_ORIGINS:?CORS_ORIGINS 必须在 .env.production 显式配置（禁止通配符 *）}
     depends_on:
       redis:
         condition: service_healthy
@@ -166,6 +172,9 @@ services:
       - "443:443"
     volumes:
       - ./nginx/nginx.conf:/etc/nginx/nginx.conf:ro
+      # 安全响应头统一片段（nginx.conf 内 include conf.d/security_headers.conf，
+      # 相对路径基于 nginx 前缀 /etc/nginx 解析，故挂载到 conf.d/ 下）
+      - ./nginx/conf.d/security_headers.conf:/etc/nginx/conf.d/security_headers.conf:ro
       - ./nginx/certs:/etc/nginx/certs:ro
       - /opt/Entropydecrease/website:/usr/share/nginx/html:ro
       # 安装包下载目录：独立于 website（其部署会 rm 清空目录），由 release.yml 同步

server/nginx/conf.d/security_headers.conf

@@ -0,0 +1,22 @@
+# =============================================================================
+# 安全响应头统一片段（可 include 复用）
+# =============================================================================
+# Why: nginx 的 add_header 继承规则——location 内一旦出现任何 add_header，
+# 就不再继承 server 级的 add_header。因此所有自带 add_header 的 location
+# （缓存头/CORS 头等）必须显式 include 本片段，否则安全头会在这些路径丢失。
+# 新增带 add_header 的 location 时，务必同步 include 本文件。
+
+# HSTS：强制浏览器后续全部走 HTTPS（仅应在 HTTPS server 块内 include）
+add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;
+# 防点击劫持：禁止被第三方站点以 iframe 嵌入
+add_header X-Frame-Options "SAMEORIGIN" always;
+# 防 MIME 嗅探：禁止浏览器猜测 Content-Type
+add_header X-Content-Type-Options "nosniff" always;
+# 限制 Referer 泄露：跨站请求仅携带 origin
+add_header Referrer-Policy "strict-origin-when-cross-origin" always;
+# 内容安全策略：官网为静态站（Next.js 静态导出），采用保守基线——
+# 默认仅允许同源；样式允许同源与内联（Next.js 静态导出含内联 style）；
+# 图片允许同源与 data:（少量 base64 图标）；脚本仅同源（无第三方脚本）。
+# 后续如需引入第三方资源，按需最小化放宽，勿回退为 unsafe-eval/*。
+add_header Content-Security-Policy "default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' data:; font-src 'self' data:; connect-src 'self'; object-src 'none'; base-uri 'self'; frame-ancestors 'self'" always;
+# 注：X-XSS-Protection 已被现代浏览器废弃且可引入新攻击面，不再启用。

server/nginx/nginx.conf

@@ -47,6 +47,9 @@ http {
     # HTTP → HTTPS 重定向
     server {
         listen 80;
+        # 公网 IP 保留在 server_name：用于 IP 直连访问/域名验证场景（如 CDN 归属验证、
+        # 证书签发前的连通性测试）命中本 server 块而非默认块；删除会导致此类请求落入
+        # 错误 server 块，故保留不删
         server_name entropydecrease.com www.entropydecrease.com 121.40.24.242;
 
         # 域名归属验证与 ACME http-01 挑战必须在 HTTP 下直接可达：
@@ -102,12 +105,10 @@ http {
         ssl_session_cache   shared:SSL:10m;
         ssl_session_timeout 10m;
 
-        # 安全头
-        add_header X-Frame-Options "SAMEORIGIN" always;
-        add_header X-Content-Type-Options "nosniff" always;
-        add_header X-XSS-Protection "1; mode=block" always;
-        add_header Referrer-Policy "strict-origin-when-cross-origin" always;
-        add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;
+        # 安全头（统一片段，含 HSTS/X-Frame-Options/nosniff/Referrer-Policy/CSP）
+        # 注意：下方任何自带 add_header 的 location 都不会继承此处，
+        # 必须各自 include 该片段（见 conf.d/security_headers.conf 头部说明）
+        include conf.d/security_headers.conf;
 
         # AI 网关健康检查（转发到 ai-gateway，不可用时降级为 Nginx 自检）
         location /health {
@@ -131,7 +132,10 @@ http {
         # 健康检查降级 fallback（ai-gateway 不可达时由 Nginx 直接响应）
         # 命名 location 不继承 server 级 add_header，且不经过 FastAPI CORSMiddleware，必须自带 CORS 头
         location @health_fallback {
-            add_header Access-Control-Allow-Origin "*" always;
+            # 命名 location 内出现 add_header 即不再继承 server 级安全头，需显式 include
+            include conf.d/security_headers.conf;
+            # CORS 收敛为官网主域（与 CORS_ORIGINS 一致），不再允许任意来源
+            add_header Access-Control-Allow-Origin "https://entropydecrease.com" always;
             add_header Access-Control-Allow-Methods "GET, POST, OPTIONS" always;
             add_header Access-Control-Allow-Headers "Authorization, Content-Type" always;
             return 200 '{"status":"degraded","service":"ai-gateway","version":"unknown","error":"gateway unreachable"}';
@@ -152,6 +156,8 @@ http {
             proxy_read_timeout 300s;
             # SSE 必需配置：禁用缓存
             proxy_cache off;
+            # 本 location 自带 add_header，不再继承 server 级安全头，需显式 include
+            include conf.d/security_headers.conf;
             add_header X-Accel-Buffering no;
         }
 
@@ -255,10 +261,13 @@ http {
             limit_conn dl_total 64;
 
             # 更新元数据（latest.yml / latest.json）禁止缓存，
-            # 否则客户端会长期读到旧版本信息；允许 www 子域跨域读取
+            # 否则客户端会长期读到旧版本信息；仅允许官网域跨域读取
             location ~* \.(yml|json)$ {
+                # 本 location 自带 add_header，不再继承 server 级安全头，需显式 include
+                include conf.d/security_headers.conf;
                 add_header Cache-Control "no-cache" always;
-                add_header Access-Control-Allow-Origin "*" always;
+                # CORS 收敛为官网主域（www 已 301 至主域，无需额外放行）
+                add_header Access-Control-Allow-Origin "https://entropydecrease.com" always;
             }
         }
 
@@ -274,15 +283,19 @@ http {
         location ^~ /pwa/assets/ {
             root /usr/share/nginx;
             expires 365d;
+            # 本 location 自带 add_header，不再继承 server 级安全头，需显式 include
+            include conf.d/security_headers.conf;
             add_header Cache-Control "public, immutable";
             access_log off;
         }
         location = /pwa/manifest.webmanifest {
             root /usr/share/nginx;
+            include conf.d/security_headers.conf;
             add_header Cache-Control "no-cache" always;
         }
         location = /pwa/sw.js {
             root /usr/share/nginx;
+            include conf.d/security_headers.conf;
             add_header Cache-Control "no-cache" always;
         }
 
@@ -301,6 +314,8 @@ http {
         location /_next/static/ {
             root /usr/share/nginx/html;
             expires 365d;
+            # 本 location 自带 add_header，不再继承 server 级安全头，需显式 include
+            include conf.d/security_headers.conf;
             add_header Cache-Control "public, immutable";
             access_log off;
         }
@@ -309,6 +324,8 @@ http {
         location ~* \.(png|jpg|jpeg|gif|ico|svg|webp|woff|woff2|ttf)$ {
             root /usr/share/nginx/html;
             expires 30d;
+            # 本 location 自带 add_header，不再继承 server 级安全头，需显式 include
+            include conf.d/security_headers.conf;
             add_header Cache-Control "public";
             access_log off;
         }