feat(deploy): 优化 Docker 部署体验，新增一键部署脚本

## 新增功能 - 新增 docker-compose.local.yml：使用本地目录存储数据，便于迁移和备份 - 新增 docker-deploy.sh：一键部署脚本，自动生成安全密钥（JWT_SECRET、TOTP_ENCRYPTION_KEY、POSTGRES_PASSWORD） - 新增 deploy/.gitignore：忽略运行时数据目录 ## 优化改进 - docker-compose.local.yml 包含 PGDATA 环境变量修复，解决 PostgreSQL 18 Alpine 数据丢失问题 - 脚本自动设置 .env 文件权限为 600，增强安全性 - 脚本显示生成的凭证，方便用户记录 ## 文档更新 - 更新 README.md（英文版）：新增"快速开始"章节，添加部署版本对比表 - 更新 README_CN.md（中文版）：同步英文版更新 - 更新 deploy/README.md：详细说明两种部署方式和迁移方法 ## 使用方式一键部署： ```bash curl -sSL https://raw.githubusercontent.com/Wei-Shaw/sub2api/main/deploy/docker-deploy.sh | bash docker-compose -f docker-compose.local.yml up -d ``` 轻松迁移： ```bash tar czf sub2api-complete.tar.gz deploy/ # 传输到新服务器后直接解压启动即可 ```
2026-02-02 16:17:07 +08:00
parent cc7e67b01a
commit 5cda979209
6 changed files with 750 additions and 65 deletions
--- a/README.md
+++ b/README.md
@@ -128,7 +128,7 @@ curl -sSL https://raw.githubusercontent.com/Wei-Shaw/sub2api/main/deploy/install

 ---

-### Method 2: Docker Compose
+### Method 2: Docker Compose (Recommended)

 Deploy with Docker Compose, including PostgreSQL and Redis containers.

@@ -137,87 +137,157 @@ Deploy with Docker Compose, including PostgreSQL and Redis containers.
 - Docker 20.10+
 - Docker Compose v2+

-#### Installation Steps
+#### Quick Start (One-Click Deployment)
+
+Use the automated deployment script for easy setup:
+
+```bash
+# Create deployment directory
+mkdir -p sub2api-deploy && cd sub2api-deploy
+
+# Download and run deployment preparation script
+curl -sSL https://raw.githubusercontent.com/Wei-Shaw/sub2api/main/deploy/docker-deploy.sh | bash
+
+# Start services
+docker-compose -f docker-compose.local.yml up -d
+
+# View logs
+docker-compose -f docker-compose.local.yml logs -f sub2api
+```
+
+**What the script does:**
+- Downloads `docker-compose.local.yml` and `.env.example`
+- Generates secure credentials (JWT_SECRET, TOTP_ENCRYPTION_KEY, POSTGRES_PASSWORD)
+- Creates `.env` file with auto-generated secrets
+- Creates data directories (uses local directories for easy backup/migration)
+- Displays generated credentials for your reference
+
+#### Manual Deployment
+
+If you prefer manual setup:

 ```bash
 # 1. Clone the repository
 git clone https://github.com/Wei-Shaw/sub2api.git
-cd sub2api
+cd sub2api/deploy

-# 2. Enter the deploy directory
-cd deploy
-
-# 3. Copy environment configuration
+# 2. Copy environment configuration
 cp .env.example .env

-# 4. Edit configuration (set your passwords)
+# 3. Edit configuration (generate secure passwords)
 nano .env
 ```

 **Required configuration in `.env`:**

 ```bash
-# PostgreSQL password (REQUIRED - change this!)
+# PostgreSQL password (REQUIRED)
 POSTGRES_PASSWORD=your_secure_password_here

+# JWT Secret (RECOMMENDED - keeps users logged in after restart)
+JWT_SECRET=your_jwt_secret_here
+
+# TOTP Encryption Key (RECOMMENDED - preserves 2FA after restart)
+TOTP_ENCRYPTION_KEY=your_totp_key_here
+
 # Optional: Admin account
 ADMIN_EMAIL=admin@example.com
 ADMIN_PASSWORD=your_admin_password

 # Optional: Custom port
 SERVER_PORT=8080
+```

-# Optional: Security configuration
-# Enable URL allowlist validation (false to skip allowlist checks, only basic format validation)
-SECURITY_URL_ALLOWLIST_ENABLED=false
+**Generate secure secrets:**
+```bash
+# Generate JWT_SECRET
+openssl rand -hex 32

-# Allow insecure HTTP URLs when allowlist is disabled (default: false, requires https)
-# ⚠️ WARNING: Enabling this allows HTTP (plaintext) URLs which can expose API keys
-#             Only recommended for:
-#             - Development/testing environments
-#             - Internal networks with trusted endpoints
-#             - When using local test servers (http://localhost)
-# PRODUCTION: Keep this false or use HTTPS URLs only
-SECURITY_URL_ALLOWLIST_ALLOW_INSECURE_HTTP=false
+# Generate TOTP_ENCRYPTION_KEY
+openssl rand -hex 32

-# Allow private IP addresses for upstream/pricing/CRS (for internal deployments)
-SECURITY_URL_ALLOWLIST_ALLOW_PRIVATE_HOSTS=false
+# Generate POSTGRES_PASSWORD
+openssl rand -hex 32
 ```

 ```bash
+# 4. Create data directories (for local version)
+mkdir -p data postgres_data redis_data
+
 # 5. Start all services
+# Option A: Local directory version (recommended - easy migration)
+docker-compose -f docker-compose.local.yml up -d
+
+# Option B: Named volumes version (simple setup)
 docker-compose up -d

 # 6. Check status
-docker-compose ps
+docker-compose -f docker-compose.local.yml ps

 # 7. View logs
-docker-compose logs -f sub2api
+docker-compose -f docker-compose.local.yml logs -f sub2api
 ```

+#### Deployment Versions
+
+| Version | Data Storage | Migration | Best For |
+|---------|-------------|-----------|----------|
+| **docker-compose.local.yml** | Local directories | ✅ Easy (tar entire directory) | Production, frequent backups |
+| **docker-compose.yml** | Named volumes | ⚠️ Requires docker commands | Simple setup |
+
+**Recommendation:** Use `docker-compose.local.yml` (deployed by script) for easier data management.
+
 #### Access

 Open `http://YOUR_SERVER_IP:8080` in your browser.

+If admin password was auto-generated, find it in logs:
+```bash
+docker-compose -f docker-compose.local.yml logs sub2api | grep "admin password"
+```
+
 #### Upgrade

 ```bash
 # Pull latest image and recreate container
-docker-compose pull
-docker-compose up -d
+docker-compose -f docker-compose.local.yml pull
+docker-compose -f docker-compose.local.yml up -d
+```
+
+#### Easy Migration (Local Directory Version)
+
+When using `docker-compose.local.yml`, migrate to a new server easily:
+
+```bash
+# On source server
+docker-compose -f docker-compose.local.yml down
+cd ..
+tar czf sub2api-complete.tar.gz sub2api-deploy/
+
+# Transfer to new server
+scp sub2api-complete.tar.gz user@new-server:/path/
+
+# On new server
+tar xzf sub2api-complete.tar.gz
+cd sub2api-deploy/
+docker-compose -f docker-compose.local.yml up -d
 ```

 #### Useful Commands

 ```bash
 # Stop all services
-docker-compose down
+docker-compose -f docker-compose.local.yml down

 # Restart
-docker-compose restart
+docker-compose -f docker-compose.local.yml restart

 # View all logs
-docker-compose logs -f
+docker-compose -f docker-compose.local.yml logs -f
+
+# Remove all data (caution!)
+docker-compose -f docker-compose.local.yml down
+rm -rf data/ postgres_data/ redis_data/
 ```

 ---
--- a/README_CN.md
+++ b/README_CN.md
@@ -135,7 +135,7 @@ curl -sSL https://raw.githubusercontent.com/Wei-Shaw/sub2api/main/deploy/install

 ---

-### 方式二：Docker Compose
+### 方式二：Docker Compose（推荐）

 使用 Docker Compose 部署，包含 PostgreSQL 和 Redis 容器。

@@ -144,87 +144,157 @@ curl -sSL https://raw.githubusercontent.com/Wei-Shaw/sub2api/main/deploy/install
 - Docker 20.10+
 - Docker Compose v2+

-#### 安装步骤
+#### 快速开始（一键部署）
+
+使用自动化部署脚本快速搭建：
+
+```bash
+# 创建部署目录
+mkdir -p sub2api-deploy && cd sub2api-deploy
+
+# 下载并运行部署准备脚本
+curl -sSL https://raw.githubusercontent.com/Wei-Shaw/sub2api/main/deploy/docker-deploy.sh | bash
+
+# 启动服务
+docker-compose -f docker-compose.local.yml up -d
+
+# 查看日志
+docker-compose -f docker-compose.local.yml logs -f sub2api
+```
+
+**脚本功能：**
+- 下载 `docker-compose.local.yml` 和 `.env.example`
+- 自动生成安全凭证（JWT_SECRET、TOTP_ENCRYPTION_KEY、POSTGRES_PASSWORD）
+- 创建 `.env` 文件并填充自动生成的密钥
+- 创建数据目录（使用本地目录，便于备份和迁移）
+- 显示生成的凭证供你记录
+
+#### 手动部署
+
+如果你希望手动配置：

 ```bash
 # 1. 克隆仓库
 git clone https://github.com/Wei-Shaw/sub2api.git
-cd sub2api
+cd sub2api/deploy

-# 2. 进入 deploy 目录
-cd deploy
-
-# 3. 复制环境配置文件
+# 2. 复制环境配置文件
 cp .env.example .env

-# 4. 编辑配置（设置密码等）
+# 3. 编辑配置（生成安全密码）
 nano .env
 ```

 **`.env` 必须配置项：**

 ```bash
-# PostgreSQL 密码（必须修改！）
+# PostgreSQL 密码（必需）
 POSTGRES_PASSWORD=your_secure_password_here

+# JWT 密钥（推荐 - 重启后保持用户登录状态）
+JWT_SECRET=your_jwt_secret_here
+
+# TOTP 加密密钥（推荐 - 重启后保留双因素认证）
+TOTP_ENCRYPTION_KEY=your_totp_key_here
+
 # 可选：管理员账号
 ADMIN_EMAIL=admin@example.com
 ADMIN_PASSWORD=your_admin_password

 # 可选：自定义端口
 SERVER_PORT=8080
+```

-# 可选：安全配置
-# 启用 URL 白名单验证（false 则跳过白名单检查，仅做基本格式校验）
-SECURITY_URL_ALLOWLIST_ENABLED=false
+**生成安全密钥：**
+```bash
+# 生成 JWT_SECRET
+openssl rand -hex 32

-# 关闭白名单时，是否允许 http:// URL（默认 false，只允许 https://）
-# ⚠️ 警告：允许 HTTP 会暴露 API 密钥（明文传输）
-#          仅建议在以下场景使用：
-#          - 开发/测试环境
-#          - 内部可信网络
-#          - 本地测试服务器（http://localhost）
-# 生产环境：保持 false 或仅使用 HTTPS URL
-SECURITY_URL_ALLOWLIST_ALLOW_INSECURE_HTTP=false
+# 生成 TOTP_ENCRYPTION_KEY
+openssl rand -hex 32

-# 是否允许私有 IP 地址用于上游/定价/CRS（内网部署时使用）
-SECURITY_URL_ALLOWLIST_ALLOW_PRIVATE_HOSTS=false
+# 生成 POSTGRES_PASSWORD
+openssl rand -hex 32
 ```

 ```bash
+# 4. 创建数据目录（本地版）
+mkdir -p data postgres_data redis_data
+
 # 5. 启动所有服务
+# 选项 A：本地目录版（推荐 - 易于迁移）
+docker-compose -f docker-compose.local.yml up -d
+
+# 选项 B：命名卷版（简单设置）
 docker-compose up -d

 # 6. 查看状态
-docker-compose ps
+docker-compose -f docker-compose.local.yml ps

 # 7. 查看日志
-docker-compose logs -f sub2api
+docker-compose -f docker-compose.local.yml logs -f sub2api
 ```

+#### 部署版本对比
+
+| 版本 | 数据存储 | 迁移便利性 | 适用场景 |
+|------|---------|-----------|---------|
+| **docker-compose.local.yml** | 本地目录 | ✅ 简单（打包整个目录） | 生产环境、频繁备份 |
+| **docker-compose.yml** | 命名卷 | ⚠️ 需要 docker 命令 | 简单设置 |
+
+**推荐：** 使用 `docker-compose.local.yml`（脚本部署）以便更轻松地管理数据。
+
 #### 访问

 在浏览器中打开 `http://你的服务器IP:8080`

+如果管理员密码是自动生成的，在日志中查找：
+```bash
+docker-compose -f docker-compose.local.yml logs sub2api | grep "admin password"
+```
+
 #### 升级

 ```bash
 # 拉取最新镜像并重建容器
-docker-compose pull
-docker-compose up -d
+docker-compose -f docker-compose.local.yml pull
+docker-compose -f docker-compose.local.yml up -d
+```
+
+#### 轻松迁移（本地目录版）
+
+使用 `docker-compose.local.yml` 时，可以轻松迁移到新服务器：
+
+```bash
+# 源服务器
+docker-compose -f docker-compose.local.yml down
+cd ..
+tar czf sub2api-complete.tar.gz sub2api-deploy/
+
+# 传输到新服务器
+scp sub2api-complete.tar.gz user@new-server:/path/
+
+# 新服务器
+tar xzf sub2api-complete.tar.gz
+cd sub2api-deploy/
+docker-compose -f docker-compose.local.yml up -d
 ```

 #### 常用命令

 ```bash
 # 停止所有服务
-docker-compose down
+docker-compose -f docker-compose.local.yml down

 # 重启
-docker-compose restart
+docker-compose -f docker-compose.local.yml restart

 # 查看所有日志
-docker-compose logs -f
+docker-compose -f docker-compose.local.yml logs -f
+
+# 删除所有数据（谨慎！）
+docker-compose -f docker-compose.local.yml down
+rm -rf data/ postgres_data/ redis_data/
 ```

 ---
--- a/deploy/.gitignore
+++ b/deploy/.gitignore
@@ -0,0 +1,19 @@
+# =============================================================================
+# Sub2API Deploy Directory - Git Ignore
+# =============================================================================
+
+# Data directories (generated at runtime when using docker-compose.local.yml)
+data/
+postgres_data/
+redis_data/
+
+# Environment configuration (contains sensitive information)
+.env
+
+# Backup files
+*.backup
+*.bak
+
+# Temporary files
+*.tmp
+*.log
--- a/deploy/README.md
+++ b/deploy/README.md
@@ -13,7 +13,9 @@ This directory contains files for deploying Sub2API on Linux servers.

 | File | Description |
 |------|-------------|
-| `docker-compose.yml` | Docker Compose configuration |
+| `docker-compose.yml` | Docker Compose configuration (named volumes) |
+| `docker-compose.local.yml` | Docker Compose configuration (local directories, easy migration) |
+| `docker-deploy.sh` | **One-click Docker deployment script (recommended)** |
 | `.env.example` | Docker environment variables template |
 | `DOCKER.md` | Docker Hub documentation |
 | `install.sh` | One-click binary installation script |
@@ -24,7 +26,45 @@ This directory contains files for deploying Sub2API on Linux servers.

 ## Docker Deployment (Recommended)

-### Quick Start
+### Method 1: One-Click Deployment (Recommended)
+
+Use the automated preparation script for the easiest setup:
+
+```bash
+# Download and run the preparation script
+curl -sSL https://raw.githubusercontent.com/Wei-Shaw/sub2api/main/deploy/docker-deploy.sh | bash
+
+# Or download first, then run
+curl -sSL https://raw.githubusercontent.com/Wei-Shaw/sub2api/main/deploy/docker-deploy.sh -o docker-deploy.sh
+chmod +x docker-deploy.sh
+./docker-deploy.sh
+```
+
+**What the script does:**
+- Downloads `docker-compose.local.yml` and `.env.example`
+- Automatically generates secure secrets (JWT_SECRET, TOTP_ENCRYPTION_KEY, POSTGRES_PASSWORD)
+- Creates `.env` file with generated secrets
+- Creates necessary data directories (data/, postgres_data/, redis_data/)
+- **Displays generated credentials** (POSTGRES_PASSWORD, JWT_SECRET, etc.)
+
+**After running the script:**
+```bash
+# Start services
+docker-compose -f docker-compose.local.yml up -d
+
+# View logs
+docker-compose -f docker-compose.local.yml logs -f sub2api
+
+# If admin password was auto-generated, find it in logs:
+docker-compose -f docker-compose.local.yml logs sub2api | grep "admin password"
+
+# Access Web UI
+# http://localhost:8080
+```
+
+### Method 2: Manual Deployment
+
+If you prefer manual control:

 ```bash
 # Clone repository
@@ -33,18 +73,36 @@ cd sub2api/deploy

 # Configure environment
 cp .env.example .env
-nano .env  # Set POSTGRES_PASSWORD (required)
+nano .env  # Set POSTGRES_PASSWORD and other required variables

-# Start all services
-docker-compose up -d
+# Generate secure secrets (recommended)
+JWT_SECRET=$(openssl rand -hex 32)
+TOTP_ENCRYPTION_KEY=$(openssl rand -hex 32)
+echo "JWT_SECRET=${JWT_SECRET}" >> .env
+echo "TOTP_ENCRYPTION_KEY=${TOTP_ENCRYPTION_KEY}" >> .env
+
+# Create data directories
+mkdir -p data postgres_data redis_data
+
+# Start all services using local directory version
+docker-compose -f docker-compose.local.yml up -d

 # View logs (check for auto-generated admin password)
-docker-compose logs -f sub2api
+docker-compose -f docker-compose.local.yml logs -f sub2api

 # Access Web UI
 # http://localhost:8080
 ```

+### Deployment Version Comparison
+
+| Version | Data Storage | Migration | Best For |
+|---------|-------------|-----------|----------|
+| **docker-compose.local.yml** | Local directories (./data, ./postgres_data, ./redis_data) | ✅ Easy (tar entire directory) | Production, need frequent backups/migration |
+| **docker-compose.yml** | Named volumes (/var/lib/docker/volumes/) | ⚠️ Requires docker commands | Simple setup, don't need migration |
+
+**Recommendation:** Use `docker-compose.local.yml` (deployed by `docker-deploy.sh`) for easier data management and migration.
+
 ### How Auto-Setup Works

 When using Docker Compose with `AUTO_SETUP=true`:
@@ -89,6 +147,32 @@ SELECT

 ### Commands

+For **local directory version** (docker-compose.local.yml):
+
+```bash
+# Start services
+docker-compose -f docker-compose.local.yml up -d
+
+# Stop services
+docker-compose -f docker-compose.local.yml down
+
+# View logs
+docker-compose -f docker-compose.local.yml logs -f sub2api
+
+# Restart Sub2API only
+docker-compose -f docker-compose.local.yml restart sub2api
+
+# Update to latest version
+docker-compose -f docker-compose.local.yml pull
+docker-compose -f docker-compose.local.yml up -d
+
+# Remove all data (caution!)
+docker-compose -f docker-compose.local.yml down
+rm -rf data/ postgres_data/ redis_data/
+```
+
+For **named volumes version** (docker-compose.yml):
+
 ```bash
 # Start services
 docker-compose up -d
@@ -115,10 +199,11 @@ docker-compose down -v
 | Variable | Required | Default | Description |
 |----------|----------|---------|-------------|
 | `POSTGRES_PASSWORD` | **Yes** | - | PostgreSQL password |
+| `JWT_SECRET` | **Recommended** | *(auto-generated)* | JWT secret (fixed for persistent sessions) |
+| `TOTP_ENCRYPTION_KEY` | **Recommended** | *(auto-generated)* | TOTP encryption key (fixed for persistent 2FA) |
 | `SERVER_PORT` | No | `8080` | Server port |
 | `ADMIN_EMAIL` | No | `admin@sub2api.local` | Admin email |
 | `ADMIN_PASSWORD` | No | *(auto-generated)* | Admin password |
-| `JWT_SECRET` | No | *(auto-generated)* | JWT secret |
 | `TZ` | No | `Asia/Shanghai` | Timezone |
 | `GEMINI_OAUTH_CLIENT_ID` | No | *(builtin)* | Google OAuth client ID (Gemini OAuth). Leave empty to use the built-in Gemini CLI client. |
 | `GEMINI_OAUTH_CLIENT_SECRET` | No | *(builtin)* | Google OAuth client secret (Gemini OAuth). Leave empty to use the built-in Gemini CLI client. |
@@ -127,6 +212,30 @@ docker-compose down -v

 See `.env.example` for all available options.

+> **Note:** The `docker-deploy.sh` script automatically generates `JWT_SECRET`, `TOTP_ENCRYPTION_KEY`, and `POSTGRES_PASSWORD` for you.
+
+### Easy Migration (Local Directory Version)
+
+When using `docker-compose.local.yml`, all data is stored in local directories, making migration simple:
+
+```bash
+# On source server: Stop services and create archive
+cd /path/to/deployment
+docker-compose -f docker-compose.local.yml down
+cd ..
+tar czf sub2api-complete.tar.gz deployment/
+
+# Transfer to new server
+scp sub2api-complete.tar.gz user@new-server:/path/to/destination/
+
+# On new server: Extract and start
+tar xzf sub2api-complete.tar.gz
+cd deployment/
+docker-compose -f docker-compose.local.yml up -d
+```
+
+Your entire deployment (configuration + data) is migrated!
+
 ---

 ## Gemini OAuth Configuration
@@ -359,6 +468,30 @@ The main config file is at `/etc/sub2api/config.yaml` (created by Setup Wizard).

 ### Docker

+For **local directory version**:
+
+```bash
+# Check container status
+docker-compose -f docker-compose.local.yml ps
+
+# View detailed logs
+docker-compose -f docker-compose.local.yml logs --tail=100 sub2api
+
+# Check database connection
+docker-compose -f docker-compose.local.yml exec postgres pg_isready
+
+# Check Redis connection
+docker-compose -f docker-compose.local.yml exec redis redis-cli ping
+
+# Restart all services
+docker-compose -f docker-compose.local.yml restart
+
+# Check data directories
+ls -la data/ postgres_data/ redis_data/
+```
+
+For **named volumes version**:
+
 ```bash
 # Check container status
 docker-compose ps
--- a/deploy/docker-compose.local.yml
+++ b/deploy/docker-compose.local.yml
@@ -0,0 +1,222 @@
+# =============================================================================
+# Sub2API Docker Compose - Local Directory Version
+# =============================================================================
+# This configuration uses local directories for data storage instead of named
+# volumes, making it easy to migrate the entire deployment by simply copying
+# the deploy directory.
+#
+# Quick Start:
+#   1. Copy .env.example to .env and configure
+#   2. mkdir -p data postgres_data redis_data
+#   3. docker-compose -f docker-compose.local.yml up -d
+#   4. Check logs: docker-compose -f docker-compose.local.yml logs -f sub2api
+#   5. Access: http://localhost:8080
+#
+# Migration to New Server:
+#   1. docker-compose -f docker-compose.local.yml down
+#   2. tar czf sub2api-deploy.tar.gz deploy/
+#   3. Transfer to new server and extract
+#   4. docker-compose -f docker-compose.local.yml up -d
+# =============================================================================
+
+services:
+  # ===========================================================================
+  # Sub2API Application
+  # ===========================================================================
+  sub2api:
+    image: weishaw/sub2api:latest
+    container_name: sub2api
+    restart: unless-stopped
+    ulimits:
+      nofile:
+        soft: 100000
+        hard: 100000
+    ports:
+      - "${BIND_HOST:-0.0.0.0}:${SERVER_PORT:-8080}:8080"
+    volumes:
+      # Local directory mapping for easy migration
+      - ./data:/app/data
+      # Optional: Mount custom config.yaml (uncomment and create the file first)
+      # Copy config.example.yaml to config.yaml, modify it, then uncomment:
+      # - ./config.yaml:/app/data/config.yaml:ro
+    environment:
+      # =======================================================================
+      # Auto Setup (REQUIRED for Docker deployment)
+      # =======================================================================
+      - AUTO_SETUP=true
+
+      # =======================================================================
+      # Server Configuration
+      # =======================================================================
+      - SERVER_HOST=0.0.0.0
+      - SERVER_PORT=8080
+      - SERVER_MODE=${SERVER_MODE:-release}
+      - RUN_MODE=${RUN_MODE:-standard}
+
+      # =======================================================================
+      # Database Configuration (PostgreSQL)
+      # =======================================================================
+      - DATABASE_HOST=postgres
+      - DATABASE_PORT=5432
+      - DATABASE_USER=${POSTGRES_USER:-sub2api}
+      - DATABASE_PASSWORD=${POSTGRES_PASSWORD:?POSTGRES_PASSWORD is required}
+      - DATABASE_DBNAME=${POSTGRES_DB:-sub2api}
+      - DATABASE_SSLMODE=disable
+
+      # =======================================================================
+      # Redis Configuration
+      # =======================================================================
+      - REDIS_HOST=redis
+      - REDIS_PORT=6379
+      - REDIS_PASSWORD=${REDIS_PASSWORD:-}
+      - REDIS_DB=${REDIS_DB:-0}
+      - REDIS_ENABLE_TLS=${REDIS_ENABLE_TLS:-false}
+
+      # =======================================================================
+      # Admin Account (auto-created on first run)
+      # =======================================================================
+      - ADMIN_EMAIL=${ADMIN_EMAIL:-admin@sub2api.local}
+      - ADMIN_PASSWORD=${ADMIN_PASSWORD:-}
+
+      # =======================================================================
+      # JWT Configuration
+      # =======================================================================
+      # IMPORTANT: Set a fixed JWT_SECRET to prevent login sessions from being
+      # invalidated after container restarts. If left empty, a random secret
+      # will be generated on each startup.
+      # Generate a secure secret: openssl rand -hex 32
+      - JWT_SECRET=${JWT_SECRET:-}
+      - JWT_EXPIRE_HOUR=${JWT_EXPIRE_HOUR:-24}
+
+      # =======================================================================
+      # TOTP (2FA) Configuration
+      # =======================================================================
+      # IMPORTANT: Set a fixed encryption key for TOTP secrets. If left empty,
+      # a random key will be generated on each startup, causing all existing
+      # TOTP configurations to become invalid (users won't be able to login
+      # with 2FA).
+      # Generate a secure key: openssl rand -hex 32
+      - TOTP_ENCRYPTION_KEY=${TOTP_ENCRYPTION_KEY:-}
+
+      # =======================================================================
+      # Timezone Configuration
+      # This affects ALL time operations in the application:
+      # - Database timestamps
+      # - Usage statistics "today" boundary
+      # - Subscription expiry times
+      # - Log timestamps
+      # Common values: Asia/Shanghai, America/New_York, Europe/London, UTC
+      # =======================================================================
+      - TZ=${TZ:-Asia/Shanghai}
+
+      # =======================================================================
+      # Gemini OAuth Configuration (for Gemini accounts)
+      # =======================================================================
+      - GEMINI_OAUTH_CLIENT_ID=${GEMINI_OAUTH_CLIENT_ID:-}
+      - GEMINI_OAUTH_CLIENT_SECRET=${GEMINI_OAUTH_CLIENT_SECRET:-}
+      - GEMINI_OAUTH_SCOPES=${GEMINI_OAUTH_SCOPES:-}
+      - GEMINI_QUOTA_POLICY=${GEMINI_QUOTA_POLICY:-}
+
+      # =======================================================================
+      # Security Configuration (URL Allowlist)
+      # =======================================================================
+      # Enable URL allowlist validation (false to skip allowlist checks)
+      - SECURITY_URL_ALLOWLIST_ENABLED=${SECURITY_URL_ALLOWLIST_ENABLED:-false}
+      # Allow insecure HTTP URLs when allowlist is disabled (default: false, requires https)
+      - SECURITY_URL_ALLOWLIST_ALLOW_INSECURE_HTTP=${SECURITY_URL_ALLOWLIST_ALLOW_INSECURE_HTTP:-false}
+      # Allow private IP addresses for upstream/pricing/CRS (for internal deployments)
+      - SECURITY_URL_ALLOWLIST_ALLOW_PRIVATE_HOSTS=${SECURITY_URL_ALLOWLIST_ALLOW_PRIVATE_HOSTS:-false}
+      # Upstream hosts whitelist (comma-separated, only used when enabled=true)
+      - SECURITY_URL_ALLOWLIST_UPSTREAM_HOSTS=${SECURITY_URL_ALLOWLIST_UPSTREAM_HOSTS:-}
+
+      # =======================================================================
+      # Update Configuration (在线更新配置)
+      # =======================================================================
+      # Proxy for accessing GitHub (online updates + pricing data)
+      # Examples: http://host:port, socks5://host:port
+      - UPDATE_PROXY_URL=${UPDATE_PROXY_URL:-}
+    depends_on:
+      postgres:
+        condition: service_healthy
+      redis:
+        condition: service_healthy
+    networks:
+      - sub2api-network
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+      start_period: 30s
+
+  # ===========================================================================
+  # PostgreSQL Database
+  # ===========================================================================
+  postgres:
+    image: postgres:18-alpine
+    container_name: sub2api-postgres
+    restart: unless-stopped
+    ulimits:
+      nofile:
+        soft: 100000
+        hard: 100000
+    volumes:
+      # Local directory mapping for easy migration
+      - ./postgres_data:/var/lib/postgresql/data
+    environment:
+      - POSTGRES_USER=${POSTGRES_USER:-sub2api}
+      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD:?POSTGRES_PASSWORD is required}
+      - POSTGRES_DB=${POSTGRES_DB:-sub2api}
+      - PGDATA=/var/lib/postgresql/data
+      - TZ=${TZ:-Asia/Shanghai}
+    networks:
+      - sub2api-network
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER:-sub2api} -d ${POSTGRES_DB:-sub2api}"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+      start_period: 10s
+    # 注意：不暴露端口到宿主机，应用通过内部网络连接
+    # 如需调试，可临时添加：ports: ["127.0.0.1:5433:5432"]
+
+  # ===========================================================================
+  # Redis Cache
+  # ===========================================================================
+  redis:
+    image: redis:8-alpine
+    container_name: sub2api-redis
+    restart: unless-stopped
+    ulimits:
+      nofile:
+        soft: 100000
+        hard: 100000
+    volumes:
+      # Local directory mapping for easy migration
+      - ./redis_data:/data
+    command: >
+        sh -c '
+          redis-server
+          --save 60 1
+          --appendonly yes
+          --appendfsync everysec
+          ${REDIS_PASSWORD:+--requirepass "$REDIS_PASSWORD"}'
+    environment:
+      - TZ=${TZ:-Asia/Shanghai}
+      # REDISCLI_AUTH is used by redis-cli for authentication (safer than -a flag)
+      - REDISCLI_AUTH=${REDIS_PASSWORD:-}
+    networks:
+      - sub2api-network
+    healthcheck:
+      test: ["CMD", "redis-cli", "ping"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+      start_period: 5s
+
+# =============================================================================
+# Networks
+# =============================================================================
+networks:
+  sub2api-network:
+    driver: bridge
--- a/deploy/docker-deploy.sh
+++ b/deploy/docker-deploy.sh
@@ -0,0 +1,171 @@
+#!/bin/bash
+# =============================================================================
+# Sub2API Docker Deployment Preparation Script
+# =============================================================================
+# This script prepares deployment files for Sub2API:
+#   - Downloads docker-compose.local.yml and .env.example
+#   - Generates secure secrets (JWT_SECRET, TOTP_ENCRYPTION_KEY, POSTGRES_PASSWORD)
+#   - Creates necessary data directories
+#
+# After running this script, you can start services with:
+#   docker-compose -f docker-compose.local.yml up -d
+# =============================================================================
+
+set -e
+
+# Colors for output
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+NC='\033[0m' # No Color
+
+# GitHub raw content base URL
+GITHUB_RAW_URL="https://raw.githubusercontent.com/Wei-Shaw/sub2api/main/deploy"
+
+# Print colored message
+print_info() {
+    echo -e "${BLUE}[INFO]${NC} $1"
+}
+
+print_success() {
+    echo -e "${GREEN}[SUCCESS]${NC} $1"
+}
+
+print_warning() {
+    echo -e "${YELLOW}[WARNING]${NC} $1"
+}
+
+print_error() {
+    echo -e "${RED}[ERROR]${NC} $1"
+}
+
+# Generate random secret
+generate_secret() {
+    openssl rand -hex 32
+}
+
+# Check if command exists
+command_exists() {
+    command -v "$1" >/dev/null 2>&1
+}
+
+# Main installation function
+main() {
+    echo ""
+    echo "=========================================="
+    echo "  Sub2API Deployment Preparation"
+    echo "=========================================="
+    echo ""
+
+    # Check if openssl is available
+    if ! command_exists openssl; then
+        print_error "openssl is not installed. Please install openssl first."
+        exit 1
+    fi
+
+    # Check if deployment already exists
+    if [ -f "docker-compose.local.yml" ] && [ -f ".env" ]; then
+        print_warning "Deployment files already exist in current directory."
+        read -p "Overwrite existing files? (y/N): " -r
+        echo
+        if [[ ! $REPLY =~ ^[Yy]$ ]]; then
+            print_info "Cancelled."
+            exit 0
+        fi
+    fi
+
+    # Download docker-compose.local.yml
+    print_info "Downloading docker-compose.local.yml..."
+    if command_exists curl; then
+        curl -sSL "${GITHUB_RAW_URL}/docker-compose.local.yml" -o docker-compose.local.yml
+    elif command_exists wget; then
+        wget -q "${GITHUB_RAW_URL}/docker-compose.local.yml" -O docker-compose.local.yml
+    else
+        print_error "Neither curl nor wget is installed. Please install one of them."
+        exit 1
+    fi
+    print_success "Downloaded docker-compose.local.yml"
+
+    # Download .env.example
+    print_info "Downloading .env.example..."
+    if command_exists curl; then
+        curl -sSL "${GITHUB_RAW_URL}/.env.example" -o .env.example
+    else
+        wget -q "${GITHUB_RAW_URL}/.env.example" -O .env.example
+    fi
+    print_success "Downloaded .env.example"
+
+    # Generate .env file with auto-generated secrets
+    print_info "Generating secure secrets..."
+    echo ""
+
+    # Generate secrets
+    JWT_SECRET=$(generate_secret)
+    TOTP_ENCRYPTION_KEY=$(generate_secret)
+    POSTGRES_PASSWORD=$(generate_secret)
+
+    # Create .env from .env.example
+    cp .env.example .env
+
+    # Update .env with generated secrets (cross-platform compatible)
+    if sed --version >/dev/null 2>&1; then
+        # GNU sed (Linux)
+        sed -i "s/^JWT_SECRET=.*/JWT_SECRET=${JWT_SECRET}/" .env
+        sed -i "s/^TOTP_ENCRYPTION_KEY=.*/TOTP_ENCRYPTION_KEY=${TOTP_ENCRYPTION_KEY}/" .env
+        sed -i "s/^POSTGRES_PASSWORD=.*/POSTGRES_PASSWORD=${POSTGRES_PASSWORD}/" .env
+    else
+        # BSD sed (macOS)
+        sed -i '' "s/^JWT_SECRET=.*/JWT_SECRET=${JWT_SECRET}/" .env
+        sed -i '' "s/^TOTP_ENCRYPTION_KEY=.*/TOTP_ENCRYPTION_KEY=${TOTP_ENCRYPTION_KEY}/" .env
+        sed -i '' "s/^POSTGRES_PASSWORD=.*/POSTGRES_PASSWORD=${POSTGRES_PASSWORD}/" .env
+    fi
+
+    # Create data directories
+    print_info "Creating data directories..."
+    mkdir -p data postgres_data redis_data
+    print_success "Created data directories"
+
+    # Set secure permissions for .env file (readable/writable only by owner)
+    chmod 600 .env
+    echo ""
+
+    # Display completion message
+    echo "=========================================="
+    echo "  Preparation Complete!"
+    echo "=========================================="
+    echo ""
+    echo "Generated secure credentials:"
+    echo "  POSTGRES_PASSWORD:     ${POSTGRES_PASSWORD}"
+    echo "  JWT_SECRET:            ${JWT_SECRET}"
+    echo "  TOTP_ENCRYPTION_KEY:   ${TOTP_ENCRYPTION_KEY}"
+    echo ""
+    print_warning "These credentials have been saved to .env file."
+    print_warning "Please keep them secure and do not share publicly!"
+    echo ""
+    echo "Directory structure:"
+    echo "  docker-compose.local.yml  - Docker Compose configuration"
+    echo "  .env                      - Environment variables (generated secrets)"
+    echo "  .env.example              - Example template (for reference)"
+    echo "  data/                     - Application data (will be created on first run)"
+    echo "  postgres_data/            - PostgreSQL data"
+    echo "  redis_data/               - Redis data"
+    echo ""
+    echo "Next steps:"
+    echo "  1. (Optional) Edit .env to customize configuration"
+    echo "  2. Start services:"
+    echo "     docker-compose -f docker-compose.local.yml up -d"
+    echo ""
+    echo "  3. View logs:"
+    echo "     docker-compose -f docker-compose.local.yml logs -f sub2api"
+    echo ""
+    echo "  4. Access Web UI:"
+    echo "     http://localhost:8080"
+    echo ""
+    print_info "If admin password is not set in .env, it will be auto-generated."
+    print_info "Check logs for the generated admin password on first startup."
+    echo ""
+}
+
+# Run main function
+main "$@"