feat: add test environment deployment workflow

.github/workflows/build-push-acr.yml

@@ -0,0 +1,67 @@
+name: Build and Push Backend to Aliyun ACR
+
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:
+    inputs:
+      version:
+        description: "Image version tag, for example v0.1.0-test.1"
+        required: true
+        type: string
+
+env:
+  REGISTRY: ${{ secrets.ALIYUN_REGISTRY }}
+  NAMESPACE: ${{ secrets.ALIYUN_NAME_SPACE }}
+  ALIYUN_REGISTRY_USER: ${{ secrets.ALIYUN_REGISTRY_USER }}
+  ALIYUN_REGISTRY_PASSWORD: ${{ secrets.ALIYUN_REGISTRY_PASSWORD }}
+
+jobs:
+  build-backend:
+    name: Build and push Rust backend
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v5
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Login to Aliyun ACR
+        shell: bash
+        run: |
+          set -euo pipefail
+          echo "$ALIYUN_REGISTRY_PASSWORD" | docker login \
+            --username "$ALIYUN_REGISTRY_USER" \
+            --password-stdin "$REGISTRY"
+
+      - name: Prepare image tags
+        id: prep
+        shell: bash
+        run: |
+          set -euo pipefail
+          VERSION="${{ inputs.version || github.ref_name }}"
+          IMAGE="${REGISTRY}/${NAMESPACE}/email-unlimit-server"
+          SHORT_SHA="${GITHUB_SHA::7}"
+          echo "image=$IMAGE" >> "$GITHUB_OUTPUT"
+          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
+          echo "short_sha=$SHORT_SHA" >> "$GITHUB_OUTPUT"
+
+      - name: Build and push backend
+        shell: bash
+        run: |
+          set -euo pipefail
+          docker buildx build \
+            --platform linux/amd64 \
+            --provenance=false \
+            --cache-from=type=gha,scope=email-unlimit-server \
+            --cache-to=type=gha,mode=max,scope=email-unlimit-server \
+            -t "${{ steps.prep.outputs.image }}:${{ steps.prep.outputs.version }}" \
+            -t "${{ steps.prep.outputs.image }}:sha-${{ steps.prep.outputs.short_sha }}" \
+            -t "${{ steps.prep.outputs.image }}:latest" \
+            --push \
+            -f server/Dockerfile \
+            server

.gitignore

@@ -7,4 +7,5 @@ plan.md
 info.md
 # docker-compose.self.yml
 compose.self.env
+deploy/server/backend/.env
 node_modules

README.md

@@ -41,6 +41,8 @@ VITE_API_BASE_URL=http://localhost:3000
 
 ## Docker 部署
 
+测试服务器使用宿主机 Nginx 提供静态文件和 HTTPS、使用阿里云 ACR 拉取 Rust 后端镜像时，请使用 [deploy/README.md](deploy/README.md) 中的独立部署方案。该方案适用于 `test-mail.shenjianl.cn` 与 `admin-mail.shenjianl.cn`，并与本地构建、上传前端静态文件的流程对应。
+
 开发/内网部署：
 
 先修改 `compose.env` 中所有 `CHANGE_ME` 配置，然后运行：

deploy/README.md

@@ -0,0 +1,97 @@
+# 测试服务器部署
+
+该目录交付给运行宿主机 Nginx 和 Docker Compose 的测试服务器。后端由阿里云 ACR 拉取，用户端和管理端均在本机构建后上传为静态文件。
+
+## 一次性准备
+
+1. 在服务器创建目录：
+
+   ```bash
+   sudo mkdir -p /site/email-unlimit/{frontend/releases,admin/releases,backend,backups}
+   sudo chown -R "$USER":"$USER" /site/email-unlimit
+   ```
+
+2. 上传 `deploy/server/docker-compose.yml` 到 `/site/email-unlimit/docker-compose.yml`，复制 `deploy/server/backend/.env.example` 为 `/site/email-unlimit/backend/.env`，填写真实值并执行：
+
+   ```bash
+   chmod 600 /site/email-unlimit/backend/.env
+   ```
+
+3. 使用 ACR 只读凭据在服务器登录私有镜像仓库：
+
+   ```bash
+   docker login <ALIYUN_REGISTRY>
+   ```
+
+4. 将 `deploy/nginx/email-unlimit.conf` 安装到宿主机 Nginx 的 `http` 上下文包含目录。确认通配符证书路径与文件名后，执行：
+
+   ```bash
+   sudo nginx -t && sudo systemctl reload nginx
+   ```
+
+5. 在 `/site/email-unlimit` 启动数据服务和后端：
+
+   ```bash
+   docker compose --env-file backend/.env up -d
+   docker compose --env-file backend/.env ps
+   curl --fail http://127.0.0.1:3000/health
+   ```
+
+   `backend/.env` 同时是 Docker Compose 的变量来源和后端容器的环境文件，因此之后所有 Compose 命令都必须带上 `--env-file backend/.env`。
+
+## 本机构建与静态发布
+
+构建时用户端必须使用测试收件域名，且两个前端均保持空 API 基址以使用同域反向代理：
+
+```powershell
+$env:VITE_APP_DOMAIN = "test-mail.shenjianl.cn"
+$env:VITE_API_BASE_URL = ""
+Set-Location frontend
+pnpm build
+
+Set-Location ..\admin
+pnpm build
+```
+
+将两个 `dist` 分别上传到服务器的 `frontend/releases/<版本>` 和 `admin/releases/<版本>`。确认上传完整后，在服务器原子切换当前版本：
+
+```bash
+cd /site/email-unlimit
+ln -sfn releases/<版本> frontend/current
+ln -sfn releases/<版本> admin/current
+sudo nginx -t && sudo systemctl reload nginx
+```
+
+## 后端发布与回滚
+
+GitHub 镜像仓库创建 `v*` 标签后，工作流将构建并推送 `linux/amd64` 镜像到 ACR。把 `/site/email-unlimit/backend/.env` 中的 `IMAGE_TAG` 更新为相同版本，然后执行：
+
+```bash
+cd /site/email-unlimit
+docker compose --env-file backend/.env pull backend
+docker compose --env-file backend/.env up -d --no-deps backend
+docker compose --env-file backend/.env logs --tail=100 backend
+curl --fail http://127.0.0.1:3000/health
+```
+
+回滚时将 `IMAGE_TAG` 改回上一镜像版本后重复相同命令。
+
+## DNS 与网络
+
+- `A test-mail.shenjianl.cn` 指向服务器公网 IP。
+- `MX test-mail.shenjianl.cn` 指向 `test-mail.shenjianl.cn`，优先级为 10。
+- `A admin-mail.shenjianl.cn` 指向同一公网 IP。
+- 安全组与防火墙仅放行 TCP `80`、`443`、`25`；不公开 `3000`、`3306`、`6379`。
+- 确认云厂商允许入站 TCP 25。建议将公网 IP 的 PTR 设为 `test-mail.shenjianl.cn`。
+
+## 备份
+
+每日从 MySQL 容器导出一次一致性备份到 `/site/email-unlimit/backups`，保留 7 天：
+
+```bash
+docker compose --env-file /site/email-unlimit/backend/.env exec -T mysql sh -c 'exec mysqldump --single-transaction -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" "$MYSQL_DATABASE"' \
+  | gzip > "/site/email-unlimit/backups/email-unlimit-$(date +%F).sql.gz"
+find /site/email-unlimit/backups -type f -name 'email-unlimit-*.sql.gz' -mtime +7 -delete
+```
+
+将上面的命令放入宿主机 cron 或 systemd timer。MySQL 数据卷与 Redis AOF 卷由 Docker 持久化。

deploy/nginx/email-unlimit.conf

@@ -0,0 +1,108 @@
+map $http_upgrade $connection_upgrade {
+    default upgrade;
+    '' close;
+}
+
+server {
+    listen 80;
+    server_name test-mail.shenjianl.cn;
+    return 301 https://$host$request_uri;
+}
+
+server {
+    listen 80;
+    server_name admin-mail.shenjianl.cn;
+    return 301 https://$host$request_uri;
+}
+
+server {
+    listen 443 ssl http2;
+    server_name test-mail.shenjianl.cn;
+
+    ssl_certificate /etc/nginx/certs/shenjianl.cn.fullchain.pem;
+    ssl_certificate_key /etc/nginx/certs/shenjianl.cn.key;
+
+    root /site/email-unlimit/frontend/current;
+    index index.html;
+    client_max_body_size 1m;
+
+    location ~ ^/(auth|api)(/|$) {
+        proxy_pass http://127.0.0.1:3000;
+        proxy_http_version 1.1;
+        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;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection $connection_upgrade;
+        proxy_read_timeout 600s;
+        proxy_send_timeout 600s;
+    }
+
+    location = /health {
+        proxy_pass http://127.0.0.1:3000;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+    }
+
+    location = /index.html {
+        add_header Cache-Control "no-store" always;
+        try_files $uri =404;
+    }
+
+    location ~* \.(?:css|js|mjs|png|jpg|jpeg|gif|ico|svg|webp|woff2?)$ {
+        expires 1y;
+        add_header Cache-Control "public, immutable" always;
+        try_files $uri =404;
+    }
+
+    location / {
+        try_files $uri $uri/ /index.html;
+    }
+}
+
+server {
+    listen 443 ssl http2;
+    server_name admin-mail.shenjianl.cn;
+
+    ssl_certificate /etc/nginx/certs/shenjianl.cn.fullchain.pem;
+    ssl_certificate_key /etc/nginx/certs/shenjianl.cn.key;
+
+    root /site/email-unlimit/admin/current;
+    index index.html;
+    client_max_body_size 1m;
+
+    location ~ ^/(auth|api|admin)(/|$) {
+        proxy_pass http://127.0.0.1:3000;
+        proxy_http_version 1.1;
+        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;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection $connection_upgrade;
+        proxy_read_timeout 600s;
+        proxy_send_timeout 600s;
+    }
+
+    location ~ ^/(health|info)$ {
+        proxy_pass http://127.0.0.1:3000;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+    }
+
+    location = /index.html {
+        add_header Cache-Control "no-store" always;
+        try_files $uri =404;
+    }
+
+    location ~* \.(?:css|js|mjs|png|jpg|jpeg|gif|ico|svg|webp|woff2?)$ {
+        expires 1y;
+        add_header Cache-Control "public, immutable" always;
+        try_files $uri =404;
+    }
+
+    location / {
+        try_files $uri $uri/ /index.html;
+    }
+}

deploy/server/backend/.env.example

@@ -0,0 +1,44 @@
+# This file is copied to /site/email-unlimit/backend/.env and must never be committed.
+ENV=production
+CONFIG=config/production.toml
+TZ=Asia/Shanghai
+RUST_LOG=info
+
+REGISTRY=registry.example.com
+NAMESPACE=your-acr-namespace
+IMAGE_TAG=v0.1.0-test.1
+
+MYSQL_DATABASE=email_unlimit
+MYSQL_USER=email_unlimit
+MYSQL_PASSWORD=CHANGE_ME_DATABASE_USER_PASSWORD
+MYSQL_ROOT_PASSWORD=CHANGE_ME_DATABASE_ROOT_PASSWORD
+
+REDIS_PASSWORD=CHANGE_ME_REDIS_PASSWORD
+
+DATABASE__DATABASE_TYPE=mysql
+DATABASE__HOST=mysql
+DATABASE__PORT=3306
+DATABASE__USER=email_unlimit
+DATABASE__PASSWORD=CHANGE_ME_DATABASE_USER_PASSWORD
+DATABASE__DATABASE=email_unlimit
+
+REDIS__ENABLED=true
+REDIS__HOST=redis
+REDIS__PORT=6379
+REDIS__PASSWORD=CHANGE_ME_REDIS_PASSWORD
+REDIS__DB=0
+
+AUTH__JWT_SECRET=CHANGE_ME_WITH_AT_LEAST_32_RANDOM_CHARACTERS
+AUTH__INVITE_CODE=CHANGE_ME_WITH_AT_LEAST_16_CHARACTERS
+AUTH__BOOTSTRAP_ADMIN_EMAIL=admin@example.com
+AUTH__REGISTRATION_OPEN=true
+
+SERVER__CORS_ORIGINS=https://test-mail.shenjianl.cn,https://admin-mail.shenjianl.cn
+
+SMTP__HOSTNAME=test-mail.shenjianl.cn
+SMTP__LOCAL_DOMAINS=test-mail.shenjianl.cn
+SMTP__BODY_ENCRYPTION_KEY=CHANGE_ME_EXACTLY_32_ASCII_CHARACTERS
+ABUSE__HONEYPOT_ADDRESSES=admin@test-mail.shenjianl.cn,noreply@test-mail.shenjianl.cn,test@test-mail.shenjianl.cn
+
+EMAIL__ENABLED=false
+EMAIL__QUEUE_ENABLED=false

deploy/server/docker-compose.yml

@@ -0,0 +1,69 @@
+services:
+  backend:
+    image: ${REGISTRY}/${NAMESPACE}/email-unlimit-server:${IMAGE_TAG}
+    container_name: email-unlimit-backend
+    restart: unless-stopped
+    env_file:
+      - ./backend/.env
+    ports:
+      - "127.0.0.1:3000:3000"
+      - "25:25"
+    depends_on:
+      mysql:
+        condition: service_healthy
+      redis:
+        condition: service_healthy
+    healthcheck:
+      test: ["CMD", "curl", "-fsS", "http://localhost:3000/health"]
+      interval: 10s
+      timeout: 3s
+      retries: 10
+      start_period: 20s
+    networks:
+      - email-unlimit
+
+  mysql:
+    image: mysql:8.0
+    container_name: email-unlimit-mysql
+    restart: unless-stopped
+    environment:
+      MYSQL_DATABASE: ${MYSQL_DATABASE}
+      MYSQL_USER: ${MYSQL_USER}
+      MYSQL_PASSWORD: ${MYSQL_PASSWORD}
+      MYSQL_ROOT_PASSWORD: ${MYSQL_ROOT_PASSWORD}
+      TZ: Asia/Shanghai
+    volumes:
+      - mysql-data:/var/lib/mysql
+    healthcheck:
+      test: ["CMD-SHELL", "mysqladmin ping -h localhost -p$$MYSQL_ROOT_PASSWORD --silent"]
+      interval: 10s
+      timeout: 5s
+      retries: 10
+      start_period: 30s
+    networks:
+      - email-unlimit
+
+  redis:
+    image: redis:7.4-alpine
+    container_name: email-unlimit-redis
+    restart: unless-stopped
+    environment:
+      REDIS_PASSWORD: ${REDIS_PASSWORD}
+    command: ["sh", "-c", "redis-server --appendonly yes --requirepass $$REDIS_PASSWORD"]
+    volumes:
+      - redis-data:/data
+    healthcheck:
+      test: ["CMD-SHELL", "redis-cli -a \"$$REDIS_PASSWORD\" ping | grep -q PONG"]
+      interval: 10s
+      timeout: 3s
+      retries: 10
+    networks:
+      - email-unlimit
+
+networks:
+  email-unlimit:
+    driver: bridge
+
+volumes:
+  mysql-data: {}
+  redis-data: {}

server/src/infra/middleware/rate_limit.rs

@@ -6,7 +6,7 @@ use axum::{
 };
 use std::{
     collections::HashMap,
-    net::SocketAddr,
+    net::{IpAddr, SocketAddr},
     sync::Arc,
     time::{Duration, Instant},
 };
@@ -38,27 +38,79 @@ impl RateLimiter {
         }
     }
 }
+
+fn client_key(req: &Request) -> String {
+    let peer_ip = req
+        .extensions()
+        .get::<ConnectInfo<SocketAddr>>()
+        .map(|value| value.0.ip());
+
+    // Only the host Nginx can reach the production backend through loopback.
+    // It overwrites X-Real-IP with the actual remote address, so untrusted
+    // direct clients cannot choose their own rate-limit key.
+    if peer_ip.is_some_and(|ip| ip.is_loopback()) {
+        if let Some(forwarded_ip) = req
+            .headers()
+            .get("x-real-ip")
+            .and_then(|value| value.to_str().ok())
+            .and_then(|value| value.trim().parse::<IpAddr>().ok())
+        {
+            return forwarded_ip.to_string();
+        }
+    }
+
+    peer_ip
+        .map(|value| value.to_string())
+        .unwrap_or_else(|| "unknown".into())
+}
+
 pub async fn rate_limit_middleware(
     State(limiter): State<RateLimiter>,
     req: Request,
     next: Next,
 ) -> Response {
-    let key = req
+    let key = client_key(&req);
-        .extensions()
-        .get::<ConnectInfo<SocketAddr>>()
-        .map(|v| v.0.ip().to_string())
-        .or_else(|| {
-            req.headers()
-                .get("x-forwarded-for")
-                .and_then(|v| v.to_str().ok())
-                .and_then(|v| v.split(',').next())
-                .map(str::trim)
-                .map(str::to_string)
-        })
-        .unwrap_or_else(|| "unknown".into());
     if limiter.allow(key).await {
         next.run(req).await
     } else {
         (StatusCode::TOO_MANY_REQUESTS, "rate limit exceeded").into_response()
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use axum::body::Body;
+
+    fn request_with_peer(peer_ip: IpAddr, real_ip: Option<&str>) -> Request {
+        let mut request = Request::builder().uri("/").body(Body::empty()).unwrap();
+        request
+            .extensions_mut()
+            .insert(ConnectInfo(SocketAddr::new(peer_ip, 12345)));
+        if let Some(real_ip) = real_ip {
+            request.headers_mut().insert(
+                "x-real-ip",
+                real_ip.parse().expect("test IP header must be valid"),
+            );
+        }
+        request
+    }
+
+    #[test]
+    fn loopback_proxy_uses_valid_real_ip() {
+        let request = request_with_peer("127.0.0.1".parse().unwrap(), Some("203.0.113.8"));
+        assert_eq!(client_key(&request), "203.0.113.8");
+    }
+
+    #[test]
+    fn public_peer_cannot_spoof_real_ip() {
+        let request = request_with_peer("203.0.113.9".parse().unwrap(), Some("198.51.100.7"));
+        assert_eq!(client_key(&request), "203.0.113.9");
+    }
+
+    #[test]
+    fn loopback_proxy_with_invalid_real_ip_falls_back_to_peer() {
+        let request = request_with_peer("::1".parse().unwrap(), Some("not-an-ip"));
+        assert_eq!(client_key(&request), "::1");
+    }
+}