feat(admin): improve setup and runtime settings

Add first-run setup helpers, runtime status reporting, admin auth flow updates, docs quick-start options, and configurable background media controls.

Raise MP4 dynamic wallpaper uploads to 40MB while keeping image uploads capped at 20MB.

Author: james-6-23

README.md

@@ -166,7 +166,7 @@ Notes:
 - Before switching deployment modes, replace `.env` with the matching example file.
 - The SQLite lightweight mode runs a single `codex2api` container and stores data at `/data/codex2api.db`.
 - **SQLite compose files bind to `127.0.0.1` by default for security.** To expose the SQLite service on all interfaces, set `BIND_HOST=0.0.0.0` in `.env` or override the port binding in the compose file. The standard compose files bind to `0.0.0.0` by default.
-- The image studio library is stored under `/data/images`; Docker configurations persist `/data`.
+- The image studio library is stored under `/data/images`; uploaded admin backgrounds are stored under `/data/backgrounds`; Docker configurations persist `/data`.
 - `docker compose down` does not delete named volumes by default. Data is removed only by commands such as `docker compose down -v`, `docker volume rm`, or `docker volume prune`.
 
 ---
@@ -238,6 +238,7 @@ Vite proxies `/api` and `/health` to the backend. During development, open `http
 | Variable | Description |
 | --- | --- |
 | `CODEX_PORT` | HTTP port, default `8080` |
+| `CODEX_MAX_REQUEST_BODY_SIZE_MB` | HTTP request body limit in MB, default `48` |
 | `ADMIN_SECRET` | Admin dashboard secret. When set, `/admin` prompts for authentication |
 | `DATABASE_DRIVER` | Database driver: `postgres` or `sqlite` |
 | `DATABASE_PATH` | SQLite database file path, used when `DATABASE_DRIVER=sqlite` |

README.zh-CN.md

@@ -211,7 +211,7 @@ docker compose -f docker-compose.sqlite.local.yml logs -f codex2api
 - SQLite 本地构建版容器名：`codex2api-sqlite-local`
 - SQLite 轻量版只启动 `codex2api` 单容器，数据保存在 `/data/codex2api.db`
 - **SQLite compose 文件默认绑定 `127.0.0.1`，仅本机可访问。** 如需暴露给外部，请在 `.env` 中设置 `BIND_HOST=0.0.0.0` 或修改 compose 文件中的端口绑定。标准版 compose 文件默认绑定 `0.0.0.0`（所有网络接口）。
-- 生图工作台图库默认保存在 `/data/images`，标准版和 SQLite 版 Docker 配置都会持久化 `/data`
+- 生图工作台图库默认保存在 `/data/images`，上传的后台背景默认保存在 `/data/backgrounds`，标准版和 SQLite 版 Docker 配置都会持久化 `/data`
 - `docker compose down` 默认不会删除命名卷；只有 `docker compose down -v`、`docker volume rm` 或 `docker volume prune` 才会删除持久化数据
 - 不同部署模式的数据卷彼此隔离；切换 compose 文件后看到空数据，通常是切到了另一组卷，而不是原卷被自动删除
 
@@ -289,6 +289,7 @@ Vite 会自动代理 `/api` 和 `/health` 到后端，开发时访问 `http://lo
 | 变量 | 说明 |
 | --- | --- |
 | `CODEX_PORT` | HTTP 端口，默认 `8080` |
+| `CODEX_MAX_REQUEST_BODY_SIZE_MB` | HTTP 请求体上限，单位 MB，默认 `48` |
 | `ADMIN_SECRET` | 管理后台登录密钥；设置后首次访问 `/admin` 会弹出密码输入框 |
 | `DATABASE_DRIVER` | 数据库驱动，支持 `postgres` / `sqlite` |
 | `DATABASE_PATH` | SQLite 数据文件路径，`DATABASE_DRIVER=sqlite` 时生效 |

admin/bootstrap.go

@@ -12,6 +12,7 @@ import (
 	"unicode/utf8"
 
 	"github.com/codex2api/database"
+	"github.com/codex2api/internal/imagestore"
 	"github.com/codex2api/proxy"
 	"github.com/codex2api/security"
 	"github.com/gin-gonic/gin"
@@ -78,6 +79,119 @@ func bootstrapAllowClientIP(clientIP string) bool {
 	return false
 }
 
+func firstForwardedHeaderValue(value string) string {
+	value = strings.TrimSpace(value)
+	if value == "" {
+		return ""
+	}
+	if idx := strings.Index(value, ","); idx >= 0 {
+		value = value[:idx]
+	}
+	return strings.TrimSpace(value)
+}
+
+func bootstrapPublicBaseURL(r *http.Request) string {
+	if r == nil {
+		return ""
+	}
+	proto := firstForwardedHeaderValue(r.Header.Get("X-Forwarded-Proto"))
+	if proto == "" {
+		if r.TLS != nil {
+			proto = "https"
+		} else {
+			proto = "http"
+		}
+	}
+	host := firstForwardedHeaderValue(r.Header.Get("X-Forwarded-Host"))
+	if host == "" {
+		host = strings.TrimSpace(r.Host)
+	}
+	if host == "" {
+		return ""
+	}
+	return strings.TrimRight(proto+"://"+host, "/")
+}
+
+func bootstrapDatabaseLocation(driver string) string {
+	if strings.EqualFold(driver, "sqlite") {
+		return strings.TrimSpace(os.Getenv("DATABASE_PATH"))
+	}
+	host := strings.TrimSpace(os.Getenv("DATABASE_HOST"))
+	name := strings.TrimSpace(os.Getenv("DATABASE_NAME"))
+	port := strings.TrimSpace(os.Getenv("DATABASE_PORT"))
+	if host == "" || name == "" {
+		return ""
+	}
+	if port != "" {
+		host += ":" + port
+	}
+	return host + "/" + name
+}
+
+func (h *Handler) bootstrapSetupHints(r *http.Request) gin.H {
+	serviceURL := bootstrapPublicBaseURL(r)
+	adminURL := ""
+	apiBaseURL := ""
+	if serviceURL != "" {
+		adminURL = strings.TrimRight(serviceURL, "/") + "/admin/"
+		apiBaseURL = strings.TrimRight(serviceURL, "/") + "/v1"
+	}
+	databaseDriver := h.databaseDriver
+	databaseLabel := h.databaseLabel
+	if databaseDriver == "" && h.db != nil {
+		databaseDriver = h.db.Driver()
+	}
+	if databaseLabel == "" && h.db != nil {
+		databaseLabel = h.db.Label()
+	}
+	cacheDriver := h.cacheDriver
+	cacheLabel := h.cacheLabel
+	if cacheDriver == "" && h.cache != nil {
+		cacheDriver = h.cache.Driver()
+	}
+	if cacheLabel == "" && h.cache != nil {
+		cacheLabel = h.cache.Label()
+	}
+
+	usageLogMode := database.UsageLogModeFull
+	usageLogBatchSize := 200
+	usageLogFlushIntervalSeconds := 5
+	if h.db != nil {
+		usageLogMode = h.db.GetUsageLogMode()
+		usageLogBatchSize = h.db.GetUsageLogBatchSize()
+		usageLogFlushIntervalSeconds = h.db.GetUsageLogFlushIntervalSeconds()
+	}
+
+	imageBackend := imagestore.CurrentConfig().Backend
+	if imageBackend == "" {
+		imageBackend = imagestore.BackendLocal
+	}
+
+	return gin.H{
+		"service_url":  serviceURL,
+		"admin_url":    adminURL,
+		"api_base_url": apiBaseURL,
+		"database": gin.H{
+			"driver":   databaseDriver,
+			"label":    databaseLabel,
+			"location": bootstrapDatabaseLocation(databaseDriver),
+		},
+		"cache": gin.H{
+			"driver": cacheDriver,
+			"label":  cacheLabel,
+		},
+		"data": gin.H{
+			"image_local_dir":       imageAssetDir(),
+			"image_storage_backend": imageBackend,
+		},
+		"usage": gin.H{
+			"log_mode":               usageLogMode,
+			"batch_size":             usageLogBatchSize,
+			"flush_interval_seconds": usageLogFlushIntervalSeconds,
+		},
+	}
+}
+
 // GetBootstrapStatus 返回当前是否需要执行初始化（GET /api/admin/bootstrap-status）。
 //
 // 该端点不要求鉴权，前端 AuthGate 在拿到登录界面前会先轮询此端点：
@@ -116,9 +230,18 @@ func (h *Handler) GetBootstrapStatus(c *gin.Context) {
 	c.JSON(http.StatusOK, gin.H{
 		"needs_bootstrap": true,
 		"source":          "empty",
+		"setup":           h.bootstrapSetupHints(c.Request),
 	})
 }
 
+// GetSetupHints 返回登录后的部署检查信息。
+//
+// 与公开的 bootstrap-status 不同，该接口注册在 /api/admin 下，需要管理密钥，
+// 因此可以安全返回数据库位置、图片目录等部署诊断信息。
+func (h *Handler) GetSetupHints(c *gin.Context) {
+	c.JSON(http.StatusOK, h.bootstrapSetupHints(c.Request))
+}
+
 // PostBootstrap 接收用户在浏览器中输入的初始管理密钥并写入数据库。
 //
 // 安全约束：