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/
 ```

 ---