Implement compression quota refunds and admin manual subscription

2025-12-19 23:28:32 +08:00
commit 11f48fd3dd
106 changed files with 27848 additions and 0 deletions
--- a/docs/deployment.md
+++ b/docs/deployment.md
@@ -0,0 +1,711 @@
+# 部署指南
+
+## 环境准备
+
+### 系统要求
+
+- Linux (Ubuntu 22.04+ / Debian 12+ 推荐)
+- 2+ CPU 核心（启用独立 Worker 建议 4+）
+- 4GB+ 内存
+- 50GB+ 磁盘空间
+
+### 依赖安装
+
+```bash
+# Ubuntu/Debian
+sudo apt update
+sudo apt install -y \
+    build-essential \
+    pkg-config \
+    libssl-dev \
+    libpq-dev \
+    cmake \
+    nasm \
+    libjpeg-dev \
+    libpng-dev \
+    libwebp-dev
+
+# 安装 Rust
+curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
+source ~/.cargo/env
+
+# 初始化数据库会用到 psql（建议安装 PostgreSQL client）
+sudo apt install -y postgresql-client
+
+# 安装 Node.js (前端构建)
+curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
+sudo apt install -y nodejs
+```
+
+---
+
+## 本地开发
+
+### 1. 启动数据库服务
+
+```bash
+# 使用 Docker Compose 启动 PostgreSQL 和 Redis
+docker-compose -f docker/docker-compose.dev.yml up -d
+```
+
+`docker/docker-compose.dev.yml`:
+```yaml
+version: '3.8'
+
+services:
+  postgres:
+    image: postgres:16-alpine
+    environment:
+      POSTGRES_USER: imageforge
+      POSTGRES_PASSWORD: devpassword
+      POSTGRES_DB: imageforge
+    ports:
+      - "5432:5432"
+    volumes:
+      - postgres_data:/var/lib/postgresql/data
+
+  redis:
+    image: redis:7-alpine
+    ports:
+      - "6379:6379"
+    volumes:
+      - redis_data:/data
+
+  # 可选：MinIO（S3 兼容，本地开发更接近生产）
+  # minio:
+  #   image: minio/minio:RELEASE.2024-01-28T20-20-01Z
+  #   command: server /data --console-address ":9001"
+  #   environment:
+  #     MINIO_ROOT_USER: minioadmin
+  #     MINIO_ROOT_PASSWORD: minioadmin
+  #   ports:
+  #     - "9000:9000"
+  #     - "9001:9001"
+  #   volumes:
+  #     - minio_data:/data
+
+volumes:
+  postgres_data:
+  redis_data:
+  minio_data:
+```
+
+### 2. 配置环境变量
+
+```bash
+cp .env.example .env
+```
+
+`.env.example`:
+```bash
+# 运行模式：建议将 API 与 Worker 分开运行
+IMAGEFORGE_ROLE=api # api | worker
+
+# 服务配置
+HOST=0.0.0.0
+PORT=8080
+PUBLIC_BASE_URL=http://localhost:8080
+RUST_LOG=info,imageforge=debug
+
+# 数据库
+DATABASE_URL=postgres://imageforge:devpassword@localhost:5432/imageforge
+
+# Redis
+REDIS_URL=redis://localhost:6379
+
+# JWT（网站/管理后台）
+JWT_SECRET=your-super-secret-key-change-in-production
+JWT_EXPIRY_HOURS=168
+
+# API Key
+API_KEY_PEPPER=please-change-this-in-production
+
+# 存储（生产建议 S3/MinIO + 预签名 URL）
+STORAGE_TYPE=local  # local | s3
+STORAGE_PATH=./uploads
+# 预签名下载链接过期（分钟）
+SIGNED_URL_TTL_MINUTES=60
+
+# S3 配置（如果使用 S3/MinIO）
+# S3_ENDPOINT=http://localhost:9000
+# S3_BUCKET=your-bucket
+# S3_REGION=us-east-1
+# S3_ACCESS_KEY=xxx
+# S3_SECRET_KEY=xxx
+
+# 计费（已确认：Stripe）
+BILLING_PROVIDER=stripe
+STRIPE_SECRET_KEY=sk_test_xxx
+STRIPE_WEBHOOK_SECRET=whsec_xxx
+
+# 限制（默认值；最终以套餐/用户覆盖为准）
+ALLOW_ANONYMOUS_UPLOAD=true
+ANON_MAX_FILE_SIZE_MB=5
+ANON_MAX_FILES_PER_BATCH=5
+ANON_DAILY_UNITS=10
+MAX_IMAGE_PIXELS=40000000
+IDEMPOTENCY_TTL_HOURS=24
+
+# 结果保留（匿名默认；登录用户按套餐 retention_days）
+ANON_RETENTION_HOURS=24
+
+# 管理员初始账户
+ADMIN_EMAIL=admin@example.com
+ADMIN_PASSWORD=changeme123
+```
+
+### 3. 初始化数据库
+
+```bash
+# 运行首期迁移（可重复执行）
+psql "$DATABASE_URL" -f migrations/001_init.sql
+```
+
+### 4. 启动开发服务器
+
+```bash
+# 后端 API (热重载)
+cargo install cargo-watch
+IMAGEFORGE_ROLE=api cargo watch -x run
+
+# 后端 Worker（另一个终端，处理异步/批量任务）
+IMAGEFORGE_ROLE=worker cargo watch -x run
+
+# 前端 (另一个终端)
+cd frontend
+npm install
+npm run dev
+```
+
+### 5. Stripe Webhook 本地调试（可选）
+
+本地调试 Stripe 订阅/支付状态，通常需要将 Stripe Webhook 转发到本机：
+
+```bash
+# 1) 安装并登录 Stripe CLI（按官方文档）
+# 2) 监听并转发到你的后端回调地址
+stripe listen --forward-to http://localhost:8080/api/v1/webhooks/stripe
+
+# CLI 会输出一个 whsec_...，写入 .env 的 STRIPE_WEBHOOK_SECRET
+```
+
+---
+
+## 生产部署
+
+> 注意：以下内容为生产部署模板示例；仓库当前首期仅提供开发用 `docker/docker-compose.dev.yml`，生产 compose/Dockerfile/nginx/k8s 等可在开工阶段按需落地并调整。
+
+### 方案一：Docker Compose（推荐小规模）
+
+`docker/docker-compose.prod.yml`:
+```yaml
+version: '3.8'
+
+services:
+  api:
+    build:
+      context: ..
+      dockerfile: docker/Dockerfile
+    environment:
+      - IMAGEFORGE_ROLE=api
+      - BILLING_PROVIDER=stripe
+      - PUBLIC_BASE_URL=https://your-domain.com
+      - STRIPE_SECRET_KEY=${STRIPE_SECRET_KEY}
+      - STRIPE_WEBHOOK_SECRET=${STRIPE_WEBHOOK_SECRET}
+      - DATABASE_URL=postgres://imageforge:${DB_PASSWORD}@postgres:5432/imageforge
+      - REDIS_URL=redis://redis:6379
+      - JWT_SECRET=${JWT_SECRET}
+      - STORAGE_TYPE=local
+      - STORAGE_PATH=/app/uploads
+    ports:
+      - "8080:8080"
+    volumes:
+      - uploads:/app/uploads
+    depends_on:
+      - postgres
+      - redis
+    restart: unless-stopped
+
+  worker:
+    build:
+      context: ..
+      dockerfile: docker/Dockerfile
+    environment:
+      - IMAGEFORGE_ROLE=worker
+      - DATABASE_URL=postgres://imageforge:${DB_PASSWORD}@postgres:5432/imageforge
+      - REDIS_URL=redis://redis:6379
+      - JWT_SECRET=${JWT_SECRET}
+      - STORAGE_TYPE=local
+      - STORAGE_PATH=/app/uploads
+    volumes:
+      - uploads:/app/uploads
+    depends_on:
+      - postgres
+      - redis
+    restart: unless-stopped
+
+  postgres:
+    image: postgres:16-alpine
+    environment:
+      POSTGRES_USER: imageforge
+      POSTGRES_PASSWORD: ${DB_PASSWORD}
+      POSTGRES_DB: imageforge
+    volumes:
+      - postgres_data:/var/lib/postgresql/data
+    restart: unless-stopped
+
+  redis:
+    image: redis:7-alpine
+    volumes:
+      - redis_data:/data
+    restart: unless-stopped
+
+  nginx:
+    image: nginx:alpine
+    ports:
+      - "80:80"
+      - "443:443"
+    volumes:
+      - ./nginx.conf:/etc/nginx/nginx.conf:ro
+      - /etc/letsencrypt:/etc/letsencrypt:ro
+    depends_on:
+      - api
+    restart: unless-stopped
+
+volumes:
+  uploads:
+  postgres_data:
+  redis_data:
+```
+
+`docker/Dockerfile`:
+```dockerfile
+FROM rust:1.92-bookworm AS builder
+
+WORKDIR /app
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    cmake \
+    nasm \
+    pkg-config \
+  && rm -rf /var/lib/apt/lists/*
+
+COPY Cargo.toml Cargo.lock ./
+COPY src ./src
+COPY migrations ./migrations
+COPY templates ./templates
+
+RUN cargo build --release
+
+# 前端构建阶段
+FROM node:20-alpine AS frontend-builder
+
+WORKDIR /app/frontend
+COPY frontend/package*.json ./
+RUN npm ci
+COPY frontend ./
+RUN npm run build
+
+# 运行阶段
+FROM debian:bookworm-slim
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    ca-certificates \
+  && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /app
+
+COPY --from=builder /app/target/release/imageforge ./imageforge
+COPY --from=frontend-builder /app/frontend/dist ./static
+COPY migrations ./migrations
+
+RUN mkdir -p uploads
+
+ENV HOST=0.0.0.0
+ENV PORT=8080
+
+EXPOSE 8080
+
+CMD ["./imageforge"]
+```
+
+`docker/nginx.conf`:
+```nginx
+events {
+    worker_connections 1024;
+}
+
+http {
+    include       mime.types;
+    default_type  application/octet-stream;
+
+    # 日志
+    access_log /var/log/nginx/access.log;
+    error_log /var/log/nginx/error.log;
+
+    # 文件上传大小限制
+    client_max_body_size 100M;
+
+    # Gzip
+    gzip on;
+    gzip_types text/plain text/css application/json application/javascript;
+
+    upstream backend {
+        server api:8080;
+    }
+
+    server {
+        listen 80;
+        server_name your-domain.com;
+        return 301 https://$server_name$request_uri;
+    }
+
+    server {
+        listen 443 ssl http2;
+        server_name your-domain.com;
+
+        ssl_certificate /etc/letsencrypt/live/your-domain.com/fullchain.pem;
+        ssl_certificate_key /etc/letsencrypt/live/your-domain.com/privkey.pem;
+
+        # SSL 配置
+        ssl_protocols TLSv1.2 TLSv1.3;
+        ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256;
+        ssl_prefer_server_ciphers off;
+
+        # 静态文件
+        location /static/ {
+            proxy_pass http://backend;
+            expires 30d;
+            add_header Cache-Control "public, immutable";
+        }
+
+        # WebSocket
+        location /ws/ {
+            proxy_pass http://backend;
+            proxy_http_version 1.1;
+            proxy_set_header Upgrade $http_upgrade;
+            proxy_set_header Connection "upgrade";
+            proxy_set_header Host $host;
+            proxy_read_timeout 86400;
+        }
+
+        # API 和其他请求
+        location / {
+            proxy_pass http://backend;
+            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 $scheme;
+        }
+    }
+}
+```
+
+### 部署步骤
+
+```bash
+# 1. 创建 .env 文件
+cat > .env << EOF
+DB_PASSWORD=your-secure-db-password
+JWT_SECRET=your-very-long-random-jwt-secret-at-least-32-chars
+STRIPE_SECRET_KEY=sk_live_xxx
+STRIPE_WEBHOOK_SECRET=whsec_xxx
+EOF
+
+# 2. 获取 SSL 证书
+sudo certbot certonly --standalone -d your-domain.com
+
+# 3. 构建并启动
+docker-compose -f docker/docker-compose.prod.yml up -d --build
+
+# 4. 查看日志
+docker-compose -f docker/docker-compose.prod.yml logs -f api
+```
+
+---
+
+### 方案二：Kubernetes（大规模）
+
+`k8s/deployment.yaml`:
+```yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: imageforge
+spec:
+  replicas: 3
+  selector:
+    matchLabels:
+      app: imageforge
+  template:
+    metadata:
+      labels:
+        app: imageforge
+    spec:
+      containers:
+      - name: imageforge
+        image: your-registry/imageforge:latest
+        ports:
+        - containerPort: 8080
+        env:
+        - name: IMAGEFORGE_ROLE
+          value: api
+        - name: DATABASE_URL
+          valueFrom:
+            secretKeyRef:
+              name: imageforge-secrets
+              key: database-url
+        - name: REDIS_URL
+          valueFrom:
+            secretKeyRef:
+              name: imageforge-secrets
+              key: redis-url
+        - name: JWT_SECRET
+          valueFrom:
+            secretKeyRef:
+              name: imageforge-secrets
+              key: jwt-secret
+        resources:
+          requests:
+            memory: "512Mi"
+            cpu: "500m"
+          limits:
+            memory: "2Gi"
+            cpu: "2000m"
+        livenessProbe:
+          httpGet:
+            path: /health
+            port: 8080
+          initialDelaySeconds: 10
+          periodSeconds: 30
+        readinessProbe:
+          httpGet:
+            path: /health
+            port: 8080
+          initialDelaySeconds: 5
+          periodSeconds: 10
+---
+apiVersion: v1
+kind: Service
+metadata:
+  name: imageforge
+spec:
+  selector:
+    app: imageforge
+  ports:
+  - port: 80
+    targetPort: 8080
+  type: ClusterIP
+---
+apiVersion: networking.k8s.io/v1
+kind: Ingress
+metadata:
+  name: imageforge
+  annotations:
+    kubernetes.io/ingress.class: nginx
+    cert-manager.io/cluster-issuer: letsencrypt-prod
+spec:
+  tls:
+  - hosts:
+    - your-domain.com
+    secretName: imageforge-tls
+  rules:
+  - host: your-domain.com
+    http:
+      paths:
+      - path: /
+        pathType: Prefix
+        backend:
+          service:
+            name: imageforge
+            port:
+              number: 80
+
+---
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: imageforge-worker
+spec:
+  replicas: 2
+  selector:
+    matchLabels:
+      app: imageforge-worker
+  template:
+    metadata:
+      labels:
+        app: imageforge-worker
+    spec:
+      containers:
+      - name: imageforge-worker
+        image: your-registry/imageforge:latest
+        env:
+        - name: IMAGEFORGE_ROLE
+          value: worker
+        - name: DATABASE_URL
+          valueFrom:
+            secretKeyRef:
+              name: imageforge-secrets
+              key: database-url
+        - name: REDIS_URL
+          valueFrom:
+            secretKeyRef:
+              name: imageforge-secrets
+              key: redis-url
+        - name: JWT_SECRET
+          valueFrom:
+            secretKeyRef:
+              name: imageforge-secrets
+              key: jwt-secret
+        resources:
+          requests:
+            memory: "512Mi"
+            cpu: "500m"
+          limits:
+            memory: "4Gi"
+            cpu: "4000m"
+```
+
+---
+
+## 监控与日志
+
+### Prometheus 指标
+
+应用暴露 `/metrics` 端点：
+
+```rust
+// 在代码中添加指标
+use prometheus::{Counter, Histogram};
+
+lazy_static! {
+    static ref COMPRESSION_REQUESTS: Counter = Counter::new(
+        "imageforge_compression_requests_total",
+        "Total number of compression requests"
+    ).unwrap();
+
+    static ref COMPRESSION_DURATION: Histogram = Histogram::with_opts(
+        HistogramOpts::new(
+            "imageforge_compression_duration_seconds",
+            "Time spent compressing images"
+        )
+    ).unwrap();
+}
+```
+
+### Grafana 仪表板
+
+监控项目：
+- 请求量 / QPS
+- 响应时间 P50/P95/P99
+- 错误率
+- 压缩任务队列长度
+- CPU / 内存使用率
+- 磁盘使用率
+
+### 日志聚合
+
+使用 ELK Stack 或 Loki：
+
+```yaml
+# docker-compose 添加 Loki
+loki:
+  image: grafana/loki:2.9.0
+  ports:
+    - "3100:3100"
+  command: -config.file=/etc/loki/local-config.yaml
+
+promtail:
+  image: grafana/promtail:2.9.0
+  volumes:
+    - /var/log:/var/log
+    - ./promtail-config.yml:/etc/promtail/config.yml
+  command: -config.file=/etc/promtail/config.yml
+```
+
+---
+
+## 备份策略
+
+### 数据库备份
+
+```bash
+#!/bin/bash
+# backup.sh
+
+DATE=$(date +%Y%m%d_%H%M%S)
+BACKUP_DIR=/backups
+
+# PostgreSQL 备份
+docker exec postgres pg_dump -U imageforge imageforge | gzip > $BACKUP_DIR/db_$DATE.sql.gz
+
+# 保留最近 7 天的备份
+find $BACKUP_DIR -name "db_*.sql.gz" -mtime +7 -delete
+
+# 可选：上传到 S3
+# aws s3 cp $BACKUP_DIR/db_$DATE.sql.gz s3://your-bucket/backups/
+```
+
+添加到 crontab：
+```bash
+0 3 * * * /path/to/backup.sh
+```
+
+### 上传文件备份
+
+如果使用本地存储，定期同步到 S3：
+```bash
+aws s3 sync /app/uploads s3://your-bucket/uploads --delete
+```
+
+---
+
+## 故障排查
+
+### 常见问题
+
+**1. 数据库连接失败**
+```bash
+# 检查 PostgreSQL 状态
+docker-compose logs postgres
+
+# 测试连接
+docker exec -it postgres psql -U imageforge -d imageforge -c "SELECT 1"
+```
+
+**2. 压缩失败**
+```bash
+# 检查应用日志
+docker-compose logs api | grep ERROR
+docker-compose logs worker | grep ERROR
+
+# 检查磁盘空间
+df -h
+```
+
+**3. 内存不足**
+```bash
+# 查看内存使用
+docker stats
+
+# 调整容器内存限制
+```
+
+**4. 上传超时**
+```bash
+# 检查 Nginx 配置
+# client_max_body_size 和 proxy_read_timeout
+```
+
+### 健康检查端点
+
+```
+GET /health
+{
+  "status": "healthy",
+  "database": "connected",
+  "redis": "connected",
+  "storage": "available",
+  "uptime": 3600
+}
+```