Merge branch 'test' into dev

deploy/.env.example

@@ -20,6 +20,52 @@ SERVER_PORT=8080
 # Server mode: release or debug
 SERVER_MODE=release
 
+# -----------------------------------------------------------------------------
+# Logging Configuration
+# 日志配置
+# -----------------------------------------------------------------------------
+# 日志级别：debug/info/warn/error
+LOG_LEVEL=info
+# 日志格式：json/console
+LOG_FORMAT=json
+# 每条日志附带的 service 字段
+LOG_SERVICE_NAME=sub2api
+# 每条日志附带的 env 字段
+LOG_ENV=production
+# 是否输出调用方位置信息
+LOG_CALLER=true
+# 堆栈输出阈值：none/error/fatal
+LOG_STACKTRACE_LEVEL=error
+
+# 输出开关（建议容器内保持双输出）
+# 是否输出到 stdout/stderr
+LOG_OUTPUT_TO_STDOUT=true
+# 是否输出到文件
+LOG_OUTPUT_TO_FILE=true
+# 日志文件路径（留空自动推导）：
+# - 设置 DATA_DIR：${DATA_DIR}/logs/sub2api.log
+# - 未设置 DATA_DIR：/app/data/logs/sub2api.log
+LOG_OUTPUT_FILE_PATH=
+
+# 滚动配置
+# 单文件最大体积（MB）
+LOG_ROTATION_MAX_SIZE_MB=100
+# 保留历史文件数量（0 表示不限制）
+LOG_ROTATION_MAX_BACKUPS=10
+# 历史日志保留天数（0 表示不限制）
+LOG_ROTATION_MAX_AGE_DAYS=7
+# 是否压缩历史日志
+LOG_ROTATION_COMPRESS=true
+# 滚动文件时间戳是否使用本地时间
+LOG_ROTATION_LOCAL_TIME=true
+
+# 采样配置（高频重复日志降噪）
+LOG_SAMPLING_ENABLED=false
+# 每秒前 N 条日志不采样
+LOG_SAMPLING_INITIAL=100
+# 之后每 N 条保留 1 条
+LOG_SAMPLING_THEREAFTER=100
+
 # Global max request body size in bytes (default: 100MB)
 # 全局最大请求体大小（字节，默认 100MB）
 # Applies to all requests, especially important for h2c first request memory protection

deploy/config.example.yaml

@@ -286,6 +286,70 @@ gateway:
     #   profile_2:
     #     name: "Custom Profile 2"
 
+# =============================================================================
+# Logging Configuration
+# 日志配置
+# =============================================================================
+log:
+  # Log level: debug/info/warn/error
+  # 日志级别：debug/info/warn/error
+  level: "info"
+  # Log format: json/console
+  # 日志格式：json/console
+  format: "console"
+  # Service name field written into each log line
+  # 每条日志都会附带 service 字段
+  service_name: "sub2api"
+  # Environment field written into each log line
+  # 每条日志都会附带 env 字段
+  env: "production"
+  # Include caller information
+  # 是否输出调用方位置信息
+  caller: true
+  # Stacktrace threshold: none/error/fatal
+  # 堆栈输出阈值：none/error/fatal
+  stacktrace_level: "error"
+  output:
+    # Keep stdout/stderr output for container log collection
+    # 保持标准输出用于容器日志采集
+    to_stdout: true
+    # Enable file output (default path auto-derived)
+    # 启用文件输出（默认路径自动推导）
+    to_file: true
+    # Empty means:
+    # - DATA_DIR set: {{DATA_DIR}}/logs/sub2api.log
+    # - otherwise: /app/data/logs/sub2api.log
+    # 留空时：
+    # - 设置 DATA_DIR：{{DATA_DIR}}/logs/sub2api.log
+    # - 否则：/app/data/logs/sub2api.log
+    file_path: ""
+  rotation:
+    # Max file size before rotation (MB)
+    # 单文件滚动阈值（MB）
+    max_size_mb: 100
+    # Number of rotated files to keep (0 means unlimited)
+    # 保留历史文件数量（0 表示不限制）
+    max_backups: 10
+    # Number of days to keep old log files (0 means unlimited)
+    # 历史日志保留天数（0 表示不限制）
+    max_age_days: 7
+    # Compress rotated files
+    # 是否压缩历史日志
+    compress: true
+    # Use local time for timestamp in rotated filename
+    # 滚动文件名时间戳使用本地时区
+    local_time: true
+  sampling:
+    # Enable zap sampler (reduce high-frequency repetitive logs)
+    # 启用 zap 采样（减少高频重复日志）
+    enabled: false
+    # Number of first entries per second to always log
+    # 每秒无采样保留的前 N 条日志
+    initial: 100
+    # Thereafter keep 1 out of N entries per second
+    # 之后每 N 条保留 1 条
+    thereafter: 100
+
 # =============================================================================
 # Sora Direct Client Configuration
 # Sora 直连配置

deploy/docker-compose-aicodex.yml

@@ -162,6 +162,10 @@ services:
     volumes:
       - postgres_data:/var/lib/postgresql/data
     environment:
+      # postgres:18-alpine 默认 PGDATA=/var/lib/postgresql/18/docker（位于镜像声明的匿名卷 /var/lib/postgresql 内）。
+      # 若不显式设置 PGDATA，则即使挂载了 postgres_data 到 /var/lib/postgresql/data，数据也不会落盘到该命名卷，
+      # docker compose down/up 后会触发 initdb 重新初始化，导致用户/密码等数据丢失。
+      - PGDATA=/var/lib/postgresql/data
       - POSTGRES_USER=${POSTGRES_USER:-sub2api}
       - POSTGRES_PASSWORD=${POSTGRES_PASSWORD:?POSTGRES_PASSWORD is required}
       - POSTGRES_DB=${POSTGRES_DB:-sub2api}

deploy/docker-compose-test.yml

@@ -142,6 +142,10 @@ services:
     volumes:
       - postgres_data:/var/lib/postgresql/data
     environment:
+      # postgres:18-alpine 默认 PGDATA=/var/lib/postgresql/18/docker（位于镜像声明的匿名卷 /var/lib/postgresql 内）。
+      # 若不显式设置 PGDATA，则即使挂载了 postgres_data 到 /var/lib/postgresql/data，数据也不会落盘到该命名卷，
+      # docker compose down/up 后会触发 initdb 重新初始化，导致用户/密码等数据丢失。
+      - PGDATA=/var/lib/postgresql/data
       - POSTGRES_USER=${POSTGRES_USER:-sub2api}
       - POSTGRES_PASSWORD=${POSTGRES_PASSWORD:?POSTGRES_PASSWORD is required}
       - POSTGRES_DB=${POSTGRES_DB:-sub2api}

deploy/docker-compose.yml

@@ -166,6 +166,10 @@ services:
     volumes:
       - postgres_data:/var/lib/postgresql/data
     environment:
+      # postgres:18-alpine 默认 PGDATA=/var/lib/postgresql/18/docker（位于镜像声明的匿名卷 /var/lib/postgresql 内）。
+      # 若不显式设置 PGDATA，则即使挂载了 postgres_data 到 /var/lib/postgresql/data，数据也不会落盘到该命名卷，
+      # docker compose down/up 后会触发 initdb 重新初始化，导致用户/密码等数据丢失。
+      - PGDATA=/var/lib/postgresql/data
       - POSTGRES_USER=${POSTGRES_USER:-sub2api}
       - POSTGRES_PASSWORD=${POSTGRES_PASSWORD:?POSTGRES_PASSWORD is required}
       - POSTGRES_DB=${POSTGRES_DB:-sub2api}