perf(db): 数据库连接池配置 + 慢查询超时（DB_POOL_SIZE, DB_QUERY_TIMEOUT）

Author: bkmashiro

.env.example

@@ -15,6 +15,10 @@ DB_PORT=3306
 DB_DATABASE=leverage
 DB_USERNAME=leverage
 DB_PASSWORD=your_password_here
+# 连接池大小（生产环境建议 20-50，开发环境建议 5-10）
+DB_POOL_SIZE=20
+# 全局查询超时（ms），超过此时间 TypeORM 会记录警告日志
+DB_QUERY_TIMEOUT=10000
 
 # ---- Redis ----
 REDIS_HOST=localhost

docs/DEPLOYMENT.md

@@ -165,6 +165,55 @@ server {
 
 ---
 
+## Database Connection Pool Tuning
+
+The backend uses TypeORM with a MySQL2 connection pool. Two environment variables control pool behavior:
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `DB_POOL_SIZE` | `20` | Maximum number of simultaneous DB connections |
+| `DB_QUERY_TIMEOUT` | `10000` | Slow query warning threshold (ms). TypeORM logs a warning when exceeded but does **not** kill the query; use DB-level `wait_timeout` for hard kills. |
+
+### Recommended values by environment
+
+| Environment | `DB_POOL_SIZE` | `DB_QUERY_TIMEOUT` |
+|-------------|---------------|-------------------|
+| Development | 5–10 | 10000 |
+| Staging | 10–20 | 10000 |
+| Production (OJ) | 20–50 | 10000 |
+
+### How to choose `DB_POOL_SIZE`
+
+- A pool that is **too small** causes connection queuing under load, increasing API latency.
+- A pool that is **too large** exhausts MariaDB's `max_connections` (default 151). Leave headroom for admin connections.
+- Rule of thumb: `DB_POOL_SIZE` × number of app replicas < `max_connections − 10`.
+
+### Slow query logging
+
+In non-production environments (`NODE_ENV !== 'production'`), TypeORM also logs every query. Watch the logs for `[TypeORM] query: SELECT …` lines that take longer than `DB_QUERY_TIMEOUT` — these are candidates for index optimization.
+
+To suppress verbose query logs on a staging server while keeping slow-query warnings:
+
+```dotenv
+NODE_ENV=production
+DB_QUERY_TIMEOUT=5000
+```
+
+### Additional MariaDB server tuning
+
+For high-concurrency OJ workloads, also tune the DB server itself:
+
+```ini
+# /etc/mysql/mariadb.conf.d/99-oj.cnf
+[mysqld]
+max_connections       = 200
+wait_timeout          = 30
+interactive_timeout   = 30
+innodb_buffer_pool_size = 1G   # adjust to available RAM
+```
+
+---
+
 ## Production Recommendations
 
 ### Run as a single process

src/database/database.module.ts

@@ -77,8 +77,29 @@ const entities = [
           process.env.NODE_ENV === 'production' ? ['dist/migrations/*.js'] : [],
         migrationsRun: process.env.NODE_ENV === 'production',
         migrationsTableName: 'migrations',
-        logging: process.env.NODE_ENV === 'development',
+        logging:
+          process.env.NODE_ENV !== 'production'
+            ? ['error', 'warn', 'query']
+            : ['error'],
         charset: 'utf8mb4',
+        // 全局查询超时（慢查询记录警告，防止慢查询卡住连接池）
+        maxQueryExecutionTime: parseInt(
+          process.env.DB_QUERY_TIMEOUT || '10000',
+        ),
+        // 连接池配置
+        extra: {
+          // 最大连接数（生产 20-50，开发 5-10）
+          connectionLimit: parseInt(process.env.DB_POOL_SIZE || '20'),
+          // 获取连接超时（ms）
+          acquireTimeout: 30000,
+          // 连接超时（ms）
+          connectTimeout: 10000,
+          // 空闲连接超时（10分钟）
+          idleTimeoutMillis: 600000,
+          // 心跳查询保持连接
+          enableKeepAlive: true,
+          keepAliveInitialDelay: 10000,
+        },
       }),
     }),
   ],